@hyperfrontend/builder 0.1.0

package/bin/script/index.cjs.js

@@ -0,0 +1,265 @@
+'use strict';
+
+const index_cjs_js$5 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js$2 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
+const index_cjs_js = require('../../_dependencies/@hyperfrontend/project-scope/core/index.cjs.js');
+const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/project-scope/core/path/index.cjs.js');
+const { normalizeFormats } = require('../../_shared/bin/format/index.cjs.js');
+const { defaultBootstrap } = require('../../_shared/bin/script/bootstrap-footer/index.cjs.js');
+const { buildWorkspaceRoutes } = require('../../_shared/bundle/dependencies/externalize-plugin/index.cjs.js');
+const { depsRootOf } = require('../../_shared/bundle/fs/deps-root/index.cjs.js');
+require('node:module');
+require('node:path');
+const index_cjs_js$6 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
+require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
+require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js');
+require('../../_dependencies/@hyperfrontend/project-scope/core/fs/index.cjs.js');
+const node_child_process = require('node:child_process');
+const node_fs = require('node:fs');
+const node_os = require('node:os');
+const index_cjs_js$4 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
+const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+
+const SHEBANG = '#!/usr/bin/env node';
+const BIN_FILE_MODE = 0o755;
+const resolveBinOutputFile = (binDir, name, format, formats) => {
+    if (format === 'esm')
+        return index_cjs_js$1.join(binDir, `${name}.mjs`);
+    return formats.length === 1 ? index_cjs_js$1.join(binDir, `${name}.js`) : index_cjs_js$1.join(binDir, `${name}.cjs.js`);
+};
+const resolveBinFooter = (bin, format) => bin.bootstrap ?? defaultBootstrap({ runner: bin.runner ?? 'default', format });
+/**
+ * Builds the worker descriptor for a single bin output (one (bin, format) pair).
+ *
+ * Bins are self-contained executable scripts: workspace deps are inlined and the
+ * worker writes to `<outputPath>/bin/<name>.<ext>` with the shebang banner, the
+ * resolved bootstrap footer, and `chmod 0o755` applied.
+ *
+ * Output naming convention:
+ * - ESM: `<name>.mjs`
+ * - CJS only: `<name>.js`
+ * - CJS alongside ESM: `<name>.cjs.js`
+ *
+ * @param bin - Bin declaration including name, runner, and per-bin bootstrap override.
+ * @param context - Resolved build context.
+ * @param format - Format being built (one of `bin.format`'s entries).
+ * @param formats - Full list of formats requested for this bin (drives the CJS filename).
+ * @param reportPath - Absolute path the worker will write its JSON report to.
+ * @returns Descriptor ready to be JSON-serialized for the worker.
+ *
+ * @example Producing the descriptor for an `hf-build` CJS bin alongside an ESM twin
+ * ```typescript
+ * const descriptor = toBinBuildDescriptor(bin, context, 'cjs', ['cjs', 'esm'], '/tmp/r.json')
+ * ```
+ */
+const toBinBuildDescriptor = (bin, context, format, formats, reportPath) => {
+    const inputFile = index_cjs_js$1.join(context.projectRoot, 'src', 'bin', `${bin.name}.ts`);
+    const binDir = index_cjs_js$1.join(context.outputPath, 'bin');
+    const outputFile = resolveBinOutputFile(binDir, bin.name, format, formats);
+    const bundledDepsRoot = depsRootOf(context);
+    const workspaceRoutes = buildWorkspaceRoutes(context.workspaceBundledDeps);
+    const useExternalizePlugin = context.bundledDeps.length > 0 || workspaceRoutes.length > 0;
+    return {
+        format,
+        inputFile,
+        outputDir: index_cjs_js$1.getDirname(outputFile),
+        external: [],
+        sourcemap: false,
+        bundledDepsPlugin: useExternalizePlugin ? { deps: context.bundledDeps, depsRoot: bundledDepsRoot } : null,
+        workspaceRoutes,
+        tsConfigPath: context.tsConfigPath,
+        projectRoot: context.projectRoot,
+        workspaceRoot: context.workspaceRoot,
+        bundleWorkspaceDeps: true,
+        bundle: null,
+        bin: {
+            outputFile,
+            banner: SHEBANG,
+            footer: resolveBinFooter(bin, format),
+            exports: 'named',
+            inlineDynamicImports: true,
+            chmod: BIN_FILE_MODE,
+        },
+        reportPath,
+    };
+};
+
+const log$1 = index_cjs_js$2.logger.channel('builder:bundle:rollup:dispatch');
+const REPORT_DIR_PREFIX = 'hf-builder-rollup-';
+const SWC_NODE_REGISTER = '@swc-node/register';
+const swcNodeAvailable = (workspaceRoot) => node_fs.existsSync(index_cjs_js.join(workspaceRoot, 'node_modules', '@swc-node', 'register', 'index.js'));
+/**
+ * Default worker-path resolution: prefers the built-and-published artifact, falls
+ * back to the workspace dist path, and finally to the in-source TypeScript file
+ * via `@swc-node/register` (bootstrap case where builder is building itself for
+ * the first time and the dist worker doesn't exist yet).
+ *
+ * Looks at, in order:
+ * 1. `<workspaceRoot>/dist/libs/builder/bundle/rollup/worker/index.cjs.js`
+ * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/rollup/worker/index.cjs.js`
+ * 3. `<workspaceRoot>/libs/builder/src/bundle/rollup/worker/index.ts` (with `--require \@swc-node/register`)
+ *
+ * @param workspaceRoot - Absolute workspace root.
+ * @returns Worker invocation descriptor, or `undefined` if no candidate exists.
+ *
+ * @example Locating the worker for an in-workspace consumer
+ * ```typescript
+ * const invocation = resolveDefaultRollupWorkerPath('/abs/repo')
+ * if (!invocation) throw new Error('builder rollup worker artifact not found')
+ * ```
+ */
+const resolveDefaultRollupWorkerPath = (workspaceRoot) => {
+    const distCandidates = [
+        index_cjs_js.join(workspaceRoot, 'dist', 'libs', 'builder', 'bundle', 'rollup', 'worker', 'index.cjs.js'),
+        index_cjs_js.join(workspaceRoot, 'node_modules', '@hyperfrontend', 'builder', 'bundle', 'rollup', 'worker', 'index.cjs.js'),
+    ];
+    for (const path of distCandidates) {
+        if (node_fs.existsSync(path))
+            return { path, execArgv: [] };
+    }
+    const sourcePath = index_cjs_js.join(workspaceRoot, 'libs', 'builder', 'src', 'bundle', 'rollup', 'worker', 'index.ts');
+    if (node_fs.existsSync(sourcePath) && swcNodeAvailable(workspaceRoot)) {
+        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER] };
+    }
+    return undefined;
+};
+const createReportDir = () => node_fs.mkdtempSync(index_cjs_js.join(node_os.tmpdir(), REPORT_DIR_PREFIX));
+const reportPathFor = (reportDir, descriptor) => {
+    const safeLabel = descriptor.inputFile.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return index_cjs_js.join(reportDir, `${descriptor.format}-${safeLabel}.json`);
+};
+const runOne = (descriptor, options, label) => index_cjs_js$3.createPromise((resolve, reject) => {
+    const execPath = options.execPath ?? process.execPath;
+    const argv = [...(options.execArgv ?? []), options.workerPath, index_cjs_js$4.stringify(descriptor)];
+    const child = node_child_process.spawn(execPath, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let capturedStderr = '';
+    child.stdout?.on('data', (chunk) => {
+        process.stdout.write(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+        const text = typeof chunk === 'string' ? chunk : chunk.toString();
+        capturedStderr += text;
+        process.stderr.write(text);
+    });
+    child.on('error', (error) => {
+        reject(index_cjs_js$5.createError(`rollup worker for ${label} failed to spawn: ${error.message}`));
+    });
+    child.on('exit', (code) => {
+        if (code !== 0) {
+            const tail = capturedStderr.trim().split('\n').slice(-10).join('\n');
+            reject(index_cjs_js$5.createError(`rollup worker for ${label} exited with code ${code}\n${tail}`));
+            return;
+        }
+        resolve();
+    });
+});
+const readReport = (reportPath, label) => {
+    if (!node_fs.existsSync(reportPath)) {
+        throw index_cjs_js$5.createError(`rollup worker for ${label} did not write a report at ${reportPath}`);
+    }
+    const data = index_cjs_js$4.parse(node_fs.readFileSync(reportPath, 'utf8'));
+    return data;
+};
+/**
+ * Forks a single rollup worker for the supplied descriptor and waits for it
+ * to exit. The caller-provided descriptor's `reportPath` is overwritten with
+ * a temp-dir path created by this function.
+ *
+ * Each worker writes a JSON report at the temp path; this function reads it
+ * after the child exits and returns the per-job statistics. If the worker
+ * exits non-zero or fails to produce a report, the function throws with a
+ * label-rich message.
+ *
+ * The temp report directory is cleaned up before returning, regardless of
+ * success or failure.
+ *
+ * @param descriptor - Build descriptor to dispatch.
+ * @param options - Worker path + optional memory monitor.
+ * @returns Worker report (output size + memory + duration) for the dispatched job.
+ *
+ * @example Dispatching a single ESM build
+ * ```typescript
+ * const report = await dispatchRollupWorker(descriptor, { workerPath: '/abs/dist/.../worker.cjs.js' })
+ * ```
+ */
+const dispatchRollupWorker = async (descriptor, options) => {
+    const reportDir = createReportDir();
+    const label = options.label ?? `${descriptor.format}:${descriptor.inputFile}`;
+    const reportPath = reportPathFor(reportDir, descriptor);
+    const job = { ...descriptor, reportPath };
+    try {
+        options.monitor?.check(`bundle:rollup:dispatch:${label}:start`);
+        log$1.info(`rollup dispatch: ${label}`);
+        await runOne(job, options, label);
+        const report = readReport(reportPath, label);
+        log$1.debug(`rollup dispatch done: ${label} size=${report.outputSize}B heap=${report.endHeapMB.toFixed(1)}MB rss=${report.endRssMB.toFixed(1)}MB t=${report.durationMs}ms`);
+        options.monitor?.check(`bundle:rollup:dispatch:${label}:end`);
+        return report;
+    }
+    finally {
+        node_fs.rmSync(reportDir, { recursive: true, force: true });
+    }
+};
+
+const log = index_cjs_js$2.logger.channel('builder:bin:script');
+const resolveWorkerOrThrow = (workspaceRoot) => {
+    const invocation = resolveDefaultRollupWorkerPath(workspaceRoot);
+    if (!invocation) {
+        throw index_cjs_js$5.createError('rollup worker could not be resolved for bin script bundling. Build @hyperfrontend/builder at least once before invoking the bin phase, or ensure @swc-node/register is installed for source-mode bootstrap.');
+    }
+    return invocation;
+};
+/**
+ * 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.
+ *
+ * @param bin - Bin declaration including name, format(s), optional runner override, and bootstrap override.
+ * @param ctx - Resolved build context.
+ * @returns One `BinOutput` per emitted JS artifact.
+ *
+ * @example Building a CJS-only bin
+ * ```typescript
+ * const outputs = await buildJsBin({ name: 'cz', format: 'cjs', runner: 'runCz' }, context)
+ * ```
+ *
+ * @example Building dual CJS + ESM outputs
+ * ```typescript
+ * const outputs = await buildJsBin({ name: 'hf-build', format: ['cjs', 'esm'] }, context)
+ * ```
+ */
+const buildJsBin = async (bin, ctx) => {
+    const formats = normalizeFormats(bin.format);
+    const binDir = index_cjs_js.join(ctx.outputPath, 'bin');
+    index_cjs_js.ensureDir(binDir);
+    const worker = resolveWorkerOrThrow(ctx.workspaceRoot);
+    const outputs = [];
+    for (const format of formats) {
+        const descriptor = toBinBuildDescriptor(bin, ctx, format, formats, '');
+        log.info(`building ${format} bin: ${bin.name}`);
+        await dispatchRollupWorker(descriptor, {
+            workerPath: worker.path,
+            execArgv: worker.execArgv,
+            label: `bin:${bin.name}:${format}`,
+        });
+        outputs.push({ name: bin.name, kind: format, outputPath: descriptor.bin?.outputFile });
+    }
+    return outputs;
+};
+
+exports.buildJsBin = buildJsBin;
+exports.defaultBootstrap = defaultBootstrap;

package/bin/script/index.d.ts

@@ -0,0 +1,79 @@
+import { BinScriptFormat, BinConfig, BuildContext, BinOutput } from '../../models';
+
+/**
+ * Inputs to {@link defaultBootstrap}.
+ */
+interface DefaultBootstrapOptions {
+    /** Runner export name to invoke. Use `'default'` to target the file's default export. */
+    runner: string;
+    /** Output format the bootstrap will be appended to. */
+    format: BinScriptFormat;
+}
+/**
+ * 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.
+ *
+ * @param options - Runner name + target format.
+ * @returns Bootstrap snippet suitable for `output.footer`.
+ *
+ * @example Default-export runner for an ESM bin
+ * ```typescript
+ * const footer = defaultBootstrap({ runner: 'default', format: 'esm' })
+ * ```
+ *
+ * @example Named runner shared between CJS and ESM outputs
+ * ```typescript
+ * const footer = defaultBootstrap({ runner: 'runCz', format: 'cjs' })
+ * ```
+ */
+declare const defaultBootstrap: (options: DefaultBootstrapOptions) => string;
+
+/**
+ * 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.
+ *
+ * @param bin - Bin declaration including name, format(s), optional runner override, and bootstrap override.
+ * @param ctx - Resolved build context.
+ * @returns One `BinOutput` per emitted JS artifact.
+ *
+ * @example Building a CJS-only bin
+ * ```typescript
+ * const outputs = await buildJsBin({ name: 'cz', format: 'cjs', runner: 'runCz' }, context)
+ * ```
+ *
+ * @example Building dual CJS + ESM outputs
+ * ```typescript
+ * const outputs = await buildJsBin({ name: 'hf-build', format: ['cjs', 'esm'] }, context)
+ * ```
+ */
+declare const buildJsBin: (bin: BinConfig, ctx: BuildContext) => Promise<BinOutput[]>;
+
+export { buildJsBin, defaultBootstrap };
+export type { DefaultBootstrapOptions };

package/bin/script/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bin/script/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/bin/script/index.esm.js

@@ -0,0 +1,262 @@
+import { createError } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { logger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { join, ensureDir } from '../../_dependencies/@hyperfrontend/project-scope/core/index.esm.js';
+import { join as join$1, getDirname } from '../../_dependencies/@hyperfrontend/project-scope/core/path/index.esm.js';
+import 'node:module';
+import 'node:path';
+import { isArray } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
+import '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
+import '../../_dependencies/@hyperfrontend/project-scope/core/fs/index.esm.js';
+import { spawn } from 'node:child_process';
+import { rmSync, existsSync, mkdtempSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { stringify, parse } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
+import { createPromise } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
+import { normalizeFormats } from '../../_shared/bin/format/index.esm.js';
+import { defaultBootstrap } from '../../_shared/bin/script/bootstrap-footer/index.esm.js';
+import { buildWorkspaceRoutes } from '../../_shared/bundle/dependencies/externalize-plugin/index.esm.js';
+import { depsRootOf } from '../../_shared/bundle/fs/deps-root/index.esm.js';
+
+const SHEBANG = '#!/usr/bin/env node';
+const BIN_FILE_MODE = 0o755;
+const resolveBinOutputFile = (binDir, name, format, formats) => {
+    if (format === 'esm')
+        return join$1(binDir, `${name}.mjs`);
+    return formats.length === 1 ? join$1(binDir, `${name}.js`) : join$1(binDir, `${name}.cjs.js`);
+};
+const resolveBinFooter = (bin, format) => bin.bootstrap ?? defaultBootstrap({ runner: bin.runner ?? 'default', format });
+/**
+ * Builds the worker descriptor for a single bin output (one (bin, format) pair).
+ *
+ * Bins are self-contained executable scripts: workspace deps are inlined and the
+ * worker writes to `<outputPath>/bin/<name>.<ext>` with the shebang banner, the
+ * resolved bootstrap footer, and `chmod 0o755` applied.
+ *
+ * Output naming convention:
+ * - ESM: `<name>.mjs`
+ * - CJS only: `<name>.js`
+ * - CJS alongside ESM: `<name>.cjs.js`
+ *
+ * @param bin - Bin declaration including name, runner, and per-bin bootstrap override.
+ * @param context - Resolved build context.
+ * @param format - Format being built (one of `bin.format`'s entries).
+ * @param formats - Full list of formats requested for this bin (drives the CJS filename).
+ * @param reportPath - Absolute path the worker will write its JSON report to.
+ * @returns Descriptor ready to be JSON-serialized for the worker.
+ *
+ * @example Producing the descriptor for an `hf-build` CJS bin alongside an ESM twin
+ * ```typescript
+ * const descriptor = toBinBuildDescriptor(bin, context, 'cjs', ['cjs', 'esm'], '/tmp/r.json')
+ * ```
+ */
+const toBinBuildDescriptor = (bin, context, format, formats, reportPath) => {
+    const inputFile = join$1(context.projectRoot, 'src', 'bin', `${bin.name}.ts`);
+    const binDir = join$1(context.outputPath, 'bin');
+    const outputFile = resolveBinOutputFile(binDir, bin.name, format, formats);
+    const bundledDepsRoot = depsRootOf(context);
+    const workspaceRoutes = buildWorkspaceRoutes(context.workspaceBundledDeps);
+    const useExternalizePlugin = context.bundledDeps.length > 0 || workspaceRoutes.length > 0;
+    return {
+        format,
+        inputFile,
+        outputDir: getDirname(outputFile),
+        external: [],
+        sourcemap: false,
+        bundledDepsPlugin: useExternalizePlugin ? { deps: context.bundledDeps, depsRoot: bundledDepsRoot } : null,
+        workspaceRoutes,
+        tsConfigPath: context.tsConfigPath,
+        projectRoot: context.projectRoot,
+        workspaceRoot: context.workspaceRoot,
+        bundleWorkspaceDeps: true,
+        bundle: null,
+        bin: {
+            outputFile,
+            banner: SHEBANG,
+            footer: resolveBinFooter(bin, format),
+            exports: 'named',
+            inlineDynamicImports: true,
+            chmod: BIN_FILE_MODE,
+        },
+        reportPath,
+    };
+};
+
+const log$1 = logger.channel('builder:bundle:rollup:dispatch');
+const REPORT_DIR_PREFIX = 'hf-builder-rollup-';
+const SWC_NODE_REGISTER = '@swc-node/register';
+const swcNodeAvailable = (workspaceRoot) => existsSync(join(workspaceRoot, 'node_modules', '@swc-node', 'register', 'index.js'));
+/**
+ * Default worker-path resolution: prefers the built-and-published artifact, falls
+ * back to the workspace dist path, and finally to the in-source TypeScript file
+ * via `@swc-node/register` (bootstrap case where builder is building itself for
+ * the first time and the dist worker doesn't exist yet).
+ *
+ * Looks at, in order:
+ * 1. `<workspaceRoot>/dist/libs/builder/bundle/rollup/worker/index.cjs.js`
+ * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bundle/rollup/worker/index.cjs.js`
+ * 3. `<workspaceRoot>/libs/builder/src/bundle/rollup/worker/index.ts` (with `--require \@swc-node/register`)
+ *
+ * @param workspaceRoot - Absolute workspace root.
+ * @returns Worker invocation descriptor, or `undefined` if no candidate exists.
+ *
+ * @example Locating the worker for an in-workspace consumer
+ * ```typescript
+ * const invocation = resolveDefaultRollupWorkerPath('/abs/repo')
+ * if (!invocation) throw new Error('builder rollup worker artifact not found')
+ * ```
+ */
+const resolveDefaultRollupWorkerPath = (workspaceRoot) => {
+    const distCandidates = [
+        join(workspaceRoot, 'dist', 'libs', 'builder', 'bundle', 'rollup', 'worker', 'index.cjs.js'),
+        join(workspaceRoot, 'node_modules', '@hyperfrontend', 'builder', 'bundle', 'rollup', 'worker', 'index.cjs.js'),
+    ];
+    for (const path of distCandidates) {
+        if (existsSync(path))
+            return { path, execArgv: [] };
+    }
+    const sourcePath = join(workspaceRoot, 'libs', 'builder', 'src', 'bundle', 'rollup', 'worker', 'index.ts');
+    if (existsSync(sourcePath) && swcNodeAvailable(workspaceRoot)) {
+        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER] };
+    }
+    return undefined;
+};
+const createReportDir = () => mkdtempSync(join(tmpdir(), REPORT_DIR_PREFIX));
+const reportPathFor = (reportDir, descriptor) => {
+    const safeLabel = descriptor.inputFile.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return join(reportDir, `${descriptor.format}-${safeLabel}.json`);
+};
+const runOne = (descriptor, options, label) => createPromise((resolve, reject) => {
+    const execPath = options.execPath ?? process.execPath;
+    const argv = [...(options.execArgv ?? []), options.workerPath, stringify(descriptor)];
+    const child = spawn(execPath, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let capturedStderr = '';
+    child.stdout?.on('data', (chunk) => {
+        process.stdout.write(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+        const text = typeof chunk === 'string' ? chunk : chunk.toString();
+        capturedStderr += text;
+        process.stderr.write(text);
+    });
+    child.on('error', (error) => {
+        reject(createError(`rollup worker for ${label} failed to spawn: ${error.message}`));
+    });
+    child.on('exit', (code) => {
+        if (code !== 0) {
+            const tail = capturedStderr.trim().split('\n').slice(-10).join('\n');
+            reject(createError(`rollup worker for ${label} exited with code ${code}\n${tail}`));
+            return;
+        }
+        resolve();
+    });
+});
+const readReport = (reportPath, label) => {
+    if (!existsSync(reportPath)) {
+        throw createError(`rollup worker for ${label} did not write a report at ${reportPath}`);
+    }
+    const data = parse(readFileSync(reportPath, 'utf8'));
+    return data;
+};
+/**
+ * Forks a single rollup worker for the supplied descriptor and waits for it
+ * to exit. The caller-provided descriptor's `reportPath` is overwritten with
+ * a temp-dir path created by this function.
+ *
+ * Each worker writes a JSON report at the temp path; this function reads it
+ * after the child exits and returns the per-job statistics. If the worker
+ * exits non-zero or fails to produce a report, the function throws with a
+ * label-rich message.
+ *
+ * The temp report directory is cleaned up before returning, regardless of
+ * success or failure.
+ *
+ * @param descriptor - Build descriptor to dispatch.
+ * @param options - Worker path + optional memory monitor.
+ * @returns Worker report (output size + memory + duration) for the dispatched job.
+ *
+ * @example Dispatching a single ESM build
+ * ```typescript
+ * const report = await dispatchRollupWorker(descriptor, { workerPath: '/abs/dist/.../worker.cjs.js' })
+ * ```
+ */
+const dispatchRollupWorker = async (descriptor, options) => {
+    const reportDir = createReportDir();
+    const label = options.label ?? `${descriptor.format}:${descriptor.inputFile}`;
+    const reportPath = reportPathFor(reportDir, descriptor);
+    const job = { ...descriptor, reportPath };
+    try {
+        options.monitor?.check(`bundle:rollup:dispatch:${label}:start`);
+        log$1.info(`rollup dispatch: ${label}`);
+        await runOne(job, options, label);
+        const report = readReport(reportPath, label);
+        log$1.debug(`rollup dispatch done: ${label} size=${report.outputSize}B heap=${report.endHeapMB.toFixed(1)}MB rss=${report.endRssMB.toFixed(1)}MB t=${report.durationMs}ms`);
+        options.monitor?.check(`bundle:rollup:dispatch:${label}:end`);
+        return report;
+    }
+    finally {
+        rmSync(reportDir, { recursive: true, force: true });
+    }
+};
+
+const log = logger.channel('builder:bin:script');
+const resolveWorkerOrThrow = (workspaceRoot) => {
+    const invocation = resolveDefaultRollupWorkerPath(workspaceRoot);
+    if (!invocation) {
+        throw createError('rollup worker could not be resolved for bin script bundling. Build @hyperfrontend/builder at least once before invoking the bin phase, or ensure @swc-node/register is installed for source-mode bootstrap.');
+    }
+    return invocation;
+};
+/**
+ * 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.
+ *
+ * @param bin - Bin declaration including name, format(s), optional runner override, and bootstrap override.
+ * @param ctx - Resolved build context.
+ * @returns One `BinOutput` per emitted JS artifact.
+ *
+ * @example Building a CJS-only bin
+ * ```typescript
+ * const outputs = await buildJsBin({ name: 'cz', format: 'cjs', runner: 'runCz' }, context)
+ * ```
+ *
+ * @example Building dual CJS + ESM outputs
+ * ```typescript
+ * const outputs = await buildJsBin({ name: 'hf-build', format: ['cjs', 'esm'] }, context)
+ * ```
+ */
+const buildJsBin = async (bin, ctx) => {
+    const formats = normalizeFormats(bin.format);
+    const binDir = join(ctx.outputPath, 'bin');
+    ensureDir(binDir);
+    const worker = resolveWorkerOrThrow(ctx.workspaceRoot);
+    const outputs = [];
+    for (const format of formats) {
+        const descriptor = toBinBuildDescriptor(bin, ctx, format, formats, '');
+        log.info(`building ${format} bin: ${bin.name}`);
+        await dispatchRollupWorker(descriptor, {
+            workerPath: worker.path,
+            execArgv: worker.execArgv,
+            label: `bin:${bin.name}:${format}`,
+        });
+        outputs.push({ name: bin.name, kind: format, outputPath: descriptor.bin?.outputFile });
+    }
+    return outputs;
+};
+
+export { buildJsBin, defaultBootstrap };

package/build.d.ts

@@ -0,0 +1,56 @@
+import type { BuildConfig, BuildContext, BuildResult } from './models';
+/**
+ * Resolves a {@link BuildContext} from a top-level {@link BuildConfig}.
+ *
+ * Defaults applied:
+ * - `outputPath` → `<workspaceRoot>/dist/<projectRelativePath>`
+ * - `tsConfigPath` → `<projectRoot>/tsconfig.lib.json`
+ * - `external` → `[]`
+ * - `assets` → `[]`
+ * - `isWorkspacePackage` → predicate that always returns `false`
+ *
+ * Entry-point discovery is performed against `<projectRoot>/src` exactly once
+ * during context creation.
+ *
+ * @param config - Top-level builder configuration.
+ * @returns Resolved context consumed by the bundle, package, and bin phases.
+ *
+ * @example Building a context manually for a custom orchestrator
+ * ```typescript
+ * const context = createBuildContext({ projectRoot, workspaceRoot })
+ * await runBundlePhase(context, config)
+ * ```
+ */
+export declare const createBuildContext: (config: BuildConfig) => BuildContext;
+/**
+ * The single facade that orchestrates a complete build: resolves the context,
+ * optionally enables the memory monitor, then runs the bundle, package, and bin
+ * phases in order before reflecting `package.json#files` from the materialized
+ * output tree. Returns a {@link BuildResult} summarizing what was emitted and
+ * how long it took.
+ *
+ * A failure in any phase still flushes the memory-monitor summary (when
+ * enabled) before re-throwing the original error.
+ *
+ * @param config - Top-level builder configuration.
+ * @returns A `BuildResult` with per-format counts, raw format outputs, bin
+ * outputs, and total duration in milliseconds.
+ * @throws {Error} Whatever any phase throws — the facade does not swallow errors.
+ *
+ * @example Building a library with workspace-aware externals
+ * ```typescript
+ * import { build } from '@hyperfrontend/builder'
+ * import { byPrefix } from '@hyperfrontend/builder/presets'
+ *
+ * const result = await build({
+ *   projectRoot: '/abs/libs/foo',
+ *   workspaceRoot: '/abs/repo',
+ *   isWorkspacePackage: byPrefix('@hyperfrontend/'),
+ *   esm: { bundleWorkspaceDeps: false },
+ *   cjs: { bundleWorkspaceDeps: false },
+ * })
+ * result.formatCounts.esm // => number of ESM entries emitted
+ * ```
+ */
+export declare const build: (config: BuildConfig) => Promise<BuildResult>;
+//# sourceMappingURL=build.d.ts.map

package/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../../../../libs/builder/src/build.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EAQZ,MAAM,UAAU,CAAA;AAkFjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,WAAW,KAAG,YAmBxD,CAAA;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,KAAK,GAAU,QAAQ,WAAW,KAAG,OAAO,CAAC,WAAW,CAiCpE,CAAA"}