@hyperfrontend/builder/bin/script

script

JS bin synthesis primitives: rollup-driven bundling with shebang + bootstrap footer + chmod.

buildJsBin(bin, context) bundles src/bin/<name>.ts with Rollup once per declared format, prepends the #!/usr/bin/env node shebang, appends the resolved bootstrap footer (bin.bootstrap override or defaultBootstrap), writes the output to <outputPath>/bin/<name>.<ext>, and chmods it to 0o755. Output naming is <name>.mjs for ESM, <name>.js when CJS is the only declared format, and <name>.cjs.js when CJS is paired with ESM. defaultBootstrap({ runner, format }) produces the standard footer template — when runner === 'default' the runner reference resolves per-format (module.exports.default for CJS, (await import(import.meta.url)).default for ESM); otherwise the named runner is referenced directly.

API Reference

ƒ Functions

§function

buildJsBin(bin: BinConfig, ctx: BuildContext): Promise<BinOutput[]>

Builds the JS outputs for a single bin declaration.
For each declared format (CJS / ESM), forks a rollup worker that bundles src/bin/<name>.ts, prepends the #!/usr/bin/env node shebang, appends the resolved bootstrap footer (per-bin override or defaultBootstrap), writes the output to <outputPath>/bin/<name>.<ext>, and chmods it to 0o755 so the npm bin symlink is invokable. The worker isolates the heavy bin bundle (rollup + plugins + transitive deps loaded into the child) from the parent process.
Output naming follows the convention:

ESM: <name>.mjs
CJS only: <name>.js
CJS alongside ESM: <name>.cjs.js

Workspace dependencies are always inlined into bin bundles — bins are intended to ship as self-contained executable scripts.

Parameters

Name	Type	Description
§bin	`BinConfig`	Bin declaration including name, format(s), optional runner override, and bootstrap override.
§ctx	`BuildContext`	Resolved build context.

Returns

Promise<BinOutput[]>

One BinOutput per emitted JS artifact.

Examples

Building a CJS-only bin

const outputs = await buildJsBin({ name: 'cz', format: 'cjs', runner: 'runCz' }, context)

Building dual CJS + ESM outputs

const outputs = await buildJsBin({ name: 'hf-build', format: ['cjs', 'esm'] }, context)

§function

defaultBootstrap(options: DefaultBootstrapOptions): string

Builds the standard bootstrap footer appended to a JS bin's bundle output.
The footer wires the resolved runner export to process.argv / process.cwd() / process.stderr / process.stdout, maps the returned exit code to process.exit, and surfaces unexpected rejections by writing to stderr and exiting 1.
When runner === 'default', the runner reference is resolved differently per format:

CJS uses module.exports.default, available as a top-level reference inside the

compiled CommonJS bundle.

ESM uses (await import(import.meta.url)).default, which re-imports the bundle's

own module record to retrieve the default export. ESM top-level await is required.
Otherwise the supplied named runner is referenced directly, which works for both formats because Rollup preserves the local function name at the file scope.

Parameters

Name	Type	Description
§options	`DefaultBootstrapOptions`	Runner name + target format.

Returns

string

Bootstrap snippet suitable for output.footer.

Examples

Default-export runner for an ESM bin

const footer = defaultBootstrap({ runner: 'default', format: 'esm' })

Named runner shared between CJS and ESM outputs

const footer = defaultBootstrap({ runner: 'runCz', format: 'cjs' })

◈ Interfaces

§interface

DefaultBootstrapOptions

Inputs to defaultBootstrap.

Properties

§format:BinScriptFormat—

Output format the bootstrap will be appended to.

§runner:string—

Runner export name to invoke. Use 'default' to target the file's default export.