@hyperfrontend/builder 0.1.0

package/bin/index.cjs.js

@@ -0,0 +1,548 @@
+'use strict';
+
+const index_cjs_js$6 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+const index_cjs_js$1 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.cjs.js');
+const node_fs = require('node:fs');
+const node_os = require('node:os');
+const index_cjs_js$7 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.cjs.js');
+const index_cjs_js$3 = require('../_dependencies/@hyperfrontend/logging/index.cjs.js');
+const index_cjs_js$4 = require('../_dependencies/@hyperfrontend/project-scope/core/index.cjs.js');
+const index_cjs_js$2 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
+const node_child_process = require('node:child_process');
+const index_cjs_js$5 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
+const { recover } = require('../_shared/memory/recover/index.cjs.js');
+const { normalizeFormats } = require('../_shared/bin/format/index.cjs.js');
+const { removeCodesign } = require('../_shared/bin/native/codesign/index.cjs.js');
+const { resolveHostBinary } = require('../_shared/bin/native/host-binary/index.cjs.js');
+const { NODE_SEA_RESOURCE_NAME, NODE_SEA_MACHO_SEGMENT, NODE_SEA_FUSE } = require('../_shared/bin/native/inject/index.cjs.js');
+const { currentPlatformTarget, currentPlatformMatches } = require('../_shared/bin/native/platform-check/index.cjs.js');
+const { generateSeaBlob } = require('../_shared/bin/native/sea-blob/index.cjs.js');
+const { generateSeaConfig } = require('../_shared/bin/native/sea-config/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('../_dependencies/postject/index.cjs.js');
+const index_cjs_js$8 = require('../_dependencies/@hyperfrontend/project-scope/core/path/index.cjs.js');
+require('node:module');
+require('node:path');
+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 log$3 = index_cjs_js$3.logger.channel('builder:bin:native:dispatch');
+const REPORT_DIR_PREFIX$1 = 'hf-builder-inject-';
+const SWC_NODE_REGISTER$1 = '@swc-node/register';
+const swcNodeAvailable$1 = (workspaceRoot) => node_fs.existsSync(index_cjs_js$4.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/bin/native/worker/index.cjs.js`
+ * 2. `<workspaceRoot>/node_modules/@hyperfrontend/builder/bin/native/worker/index.cjs.js`
+ * 3. `<workspaceRoot>/libs/builder/src/bin/native/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 = resolveDefaultInjectWorkerPath('/abs/repo')
+ * if (!invocation) throw new Error('builder inject worker artifact not found')
+ * ```
+ */
+const resolveDefaultInjectWorkerPath = (workspaceRoot) => {
+    const distCandidates = [
+        index_cjs_js$4.join(workspaceRoot, 'dist', 'libs', 'builder', 'bin', 'native', 'worker', 'index.cjs.js'),
+        index_cjs_js$4.join(workspaceRoot, 'node_modules', '@hyperfrontend', 'builder', 'bin', 'native', 'worker', 'index.cjs.js'),
+    ];
+    for (const path of distCandidates) {
+        if (node_fs.existsSync(path))
+            return { path, execArgv: [] };
+    }
+    const sourcePath = index_cjs_js$4.join(workspaceRoot, 'libs', 'builder', 'src', 'bin', 'native', 'worker', 'index.ts');
+    if (node_fs.existsSync(sourcePath) && swcNodeAvailable$1(workspaceRoot)) {
+        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER$1] };
+    }
+    return undefined;
+};
+const createReportDir$1 = () => node_fs.mkdtempSync(index_cjs_js$4.join(node_os.tmpdir(), REPORT_DIR_PREFIX$1));
+const reportPathFor$1 = (reportDir, job) => {
+    const safeLabel = job.outputBinary.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return index_cjs_js$4.join(reportDir, `inject-${safeLabel}.json`);
+};
+const runOne$1 = (job, options, label) => index_cjs_js.createPromise((resolve, reject) => {
+    const execPath = options.execPath ?? process.execPath;
+    const argv = [...(options.execArgv ?? []), options.workerPath, index_cjs_js$5.stringify(job)];
+    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$6.createError(`inject 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$6.createError(`inject worker for ${label} exited with code ${code}\n${tail}`));
+            return;
+        }
+        resolve();
+    });
+});
+const readReport$1 = (reportPath, label) => {
+    if (!node_fs.existsSync(reportPath)) {
+        throw index_cjs_js$6.createError(`inject worker for ${label} did not write a report at ${reportPath}`);
+    }
+    const data = index_cjs_js$5.parse(node_fs.readFileSync(reportPath, 'utf8'));
+    return data;
+};
+/**
+ * Forks a single inject worker for the supplied job and waits for it to exit.
+ * The caller-provided job's `reportPath` is overwritten with a temp-dir path
+ * created by this function.
+ *
+ * The 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 job - Inject job to dispatch.
+ * @param options - Worker path + optional memory monitor.
+ * @returns Worker report (output size + memory + duration) for the dispatched job.
+ *
+ * @example Dispatching a SEA inject for hf-build
+ * ```typescript
+ * const report = await dispatchInjectWorker(
+ *   { hostBinary, outputBinary, blobPath, resourceName, machoSegmentName, sentinelFuse, reportPath: '' },
+ *   { workerPath: '/abs/dist/.../worker.cjs.js', label: 'hf-build' }
+ * )
+ * ```
+ */
+const dispatchInjectWorker = async (job, options) => {
+    const reportDir = createReportDir$1();
+    const label = options.label ?? job.outputBinary;
+    const reportPath = reportPathFor$1(reportDir, job);
+    const dispatched = { ...job, reportPath };
+    try {
+        options.monitor?.check(`bin:native:dispatch:${label}:start`);
+        log$3.info(`inject dispatch: ${label}`);
+        await runOne$1(dispatched, options, label);
+        const report = readReport$1(reportPath, label);
+        log$3.debug(`inject 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(`bin:native:dispatch:${label}:end`);
+        return report;
+    }
+    finally {
+        node_fs.rmSync(reportDir, { recursive: true, force: true });
+    }
+};
+
+const log$2 = index_cjs_js$3.logger.channel('builder:bin:native');
+const BYTES_PER_MB = 1024 * 1024;
+const formatMB = (bytes) => (bytes / BYTES_PER_MB).toFixed(1);
+const memorySnapshot = (label) => {
+    const usage = process.memoryUsage();
+    log$2.debug(`${label}: heap=${formatMB(usage.heapUsed)}MB rss=${formatMB(usage.rss)}MB free=${formatMB(node_os.freemem())}MB`);
+};
+const requireSeaConfig = (bin) => {
+    if (!bin.sea)
+        throw index_cjs_js$6.createError(`buildNativeBin called for bin '${bin.name}' without a sea config`);
+    return bin.sea.platforms;
+};
+const requireCjsFormat = (bin) => {
+    if (!normalizeFormats(bin.format).includes('cjs')) {
+        throw index_cjs_js$6.createError(`SEA requires a CJS bin output; declare format: ['cjs'] or format: 'cjs' on bin ${bin.name}`);
+    }
+};
+const resolveOutputBinaryPath = (binDir, name, target) => {
+    const isWindows = target.startsWith('win32-');
+    return index_cjs_js$4.join(binDir, isWindows ? `${name}.${target}.exe` : `${name}.${target}`);
+};
+// why: the SEA config JSON and prep blob are build scaffolding consumed by the inject step; once the binary exists they are useless to consumers and must not remain in the publishable output.
+const cleanupSeaIntermediates = (seaConfigPath, blobPath) => {
+    for (const file of [seaConfigPath, blobPath]) {
+        if (index_cjs_js$4.exists(file))
+            node_fs.unlinkSync(file);
+    }
+};
+/**
+ * Builds the Node SEA native binary for a single bin declaration.
+ *
+ * Pipeline (current-platform-only — cross-platform matrices are orchestrated externally):
+ * 1. Validate the bin declares CJS — SEA requires a CJS bundle as the embedded script.
+ * 2. Skip silently with an info log if the current host doesn't match any declared platform.
+ * 3. Generate the SEA config JSON and write it to disk.
+ * 4. Spawn `node --experimental-sea-config <path>` to emit the SEA preparation blob.
+ * 5. Resolve the Node host binary for the current platform (defaults to `process.execPath`).
+ * 6. Dispatch a forked inject worker that clones the host, embeds the blob via
+ *    postject, and writes the output binary.
+ * 7. On macOS, strip the signature the injection invalidated so the unsigned binary still runs.
+ * 8. Delete the SEA build intermediates (config JSON + prep blob) so only the
+ *    runtime binary remains in the publishable output.
+ *
+ * Native binaries are not auto-wired into `package.json#bin` — they are shipped
+ * as separate release artifacts.
+ *
+ * @param inputs - Bin declaration, resolved context, and the path to the already-built CJS bundle.
+ * @returns A single {@link BinOutput} of kind `native` for the current platform, or `[]` if skipped.
+ *
+ * @example Producing the SEA binary for the current runner
+ * ```typescript
+ * const outputs = await buildNativeBin({
+ *   bin: { name: 'hf-build', format: 'cjs', sea: { platforms: ['linux-x64'] } },
+ *   ctx: context,
+ *   cjsOutputPath: '/abs/dist/libs/builder/bin/hf-build.js',
+ * })
+ * ```
+ */
+const buildNativeBin = async (inputs) => {
+    const { bin, ctx, cjsOutputPath } = inputs;
+    requireCjsFormat(bin);
+    const platforms = requireSeaConfig(bin);
+    const target = currentPlatformTarget();
+    if (!currentPlatformMatches(platforms)) {
+        log$2.info(`skipping native build for ${bin.name}: current platform ${target} not in declared targets [${platforms.join(', ')}]`);
+        return [];
+    }
+    const binDir = index_cjs_js$4.join(ctx.outputPath, 'bin');
+    index_cjs_js$4.ensureDir(binDir);
+    const seaConfigPath = index_cjs_js$4.join(binDir, `${bin.name}.sea-config.json`);
+    const blobPath = index_cjs_js$4.join(binDir, `${bin.name}.sea-prep.blob`);
+    const outputBinary = resolveOutputBinaryPath(binDir, bin.name, target);
+    log$2.info(`building native bin: ${bin.name} (${target})`);
+    memorySnapshot(`${bin.name}: pre-sea-config`);
+    const seaConfig = generateSeaConfig({ mainPath: cjsOutputPath, outputPath: blobPath });
+    index_cjs_js$4.writeJsonFile(seaConfigPath, seaConfig);
+    memorySnapshot(`${bin.name}: pre-sea-blob`);
+    const blobStart = index_cjs_js$7.dateNow();
+    generateSeaBlob({ seaConfigPath, outputBlobPath: blobPath });
+    log$2.debug(`${bin.name}: sea blob generated in ${index_cjs_js$7.dateNow() - blobStart}ms`);
+    const hostBinary = resolveHostBinary({ platform: target });
+    memorySnapshot(`${bin.name}: pre-inject (host=${hostBinary})`);
+    const invocation = resolveDefaultInjectWorkerPath(ctx.workspaceRoot);
+    if (!invocation) {
+        throw index_cjs_js$6.createError('inject worker could not be resolved for native bin build. Build @hyperfrontend/builder at least once before invoking the bin phase, or ensure @swc-node/register is installed for source-mode bootstrap.');
+    }
+    try {
+        const report = await dispatchInjectWorker({
+            hostBinary,
+            outputBinary,
+            blobPath,
+            resourceName: NODE_SEA_RESOURCE_NAME,
+            machoSegmentName: NODE_SEA_MACHO_SEGMENT,
+            sentinelFuse: NODE_SEA_FUSE,
+            reportPath: '',
+        }, { workerPath: invocation.path, execArgv: invocation.execArgv, label: bin.name });
+        log$2.debug(`${bin.name}: inject completed in ${report.durationMs}ms (worker end heap=${report.endHeapMB.toFixed(1)}MB rss=${report.endRssMB.toFixed(1)}MB)`);
+    }
+    catch (error) {
+        log$2.error(`${bin.name}: postject inject failed: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
+    memorySnapshot(`${bin.name}: post-inject`);
+    removeCodesign({ binary: outputBinary });
+    cleanupSeaIntermediates(seaConfigPath, blobPath);
+    memorySnapshot(`${bin.name}: native build complete`);
+    return [{ name: bin.name, kind: 'native', outputPath: outputBinary, platform: target }];
+};
+
+const SHEBANG = '#!/usr/bin/env node';
+const BIN_FILE_MODE = 0o755;
+const resolveBinOutputFile = (binDir, name, format, formats) => {
+    if (format === 'esm')
+        return index_cjs_js$8.join(binDir, `${name}.mjs`);
+    return formats.length === 1 ? index_cjs_js$8.join(binDir, `${name}.js`) : index_cjs_js$8.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$8.join(context.projectRoot, 'src', 'bin', `${bin.name}.ts`);
+    const binDir = index_cjs_js$8.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$8.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$3.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$4.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$4.join(workspaceRoot, 'dist', 'libs', 'builder', 'bundle', 'rollup', 'worker', 'index.cjs.js'),
+        index_cjs_js$4.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$4.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$4.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$4.join(reportDir, `${descriptor.format}-${safeLabel}.json`);
+};
+const runOne = (descriptor, options, label) => index_cjs_js.createPromise((resolve, reject) => {
+    const execPath = options.execPath ?? process.execPath;
+    const argv = [...(options.execArgv ?? []), options.workerPath, index_cjs_js$5.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$6.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$6.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$6.createError(`rollup worker for ${label} did not write a report at ${reportPath}`);
+    }
+    const data = index_cjs_js$5.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$3.logger.channel('builder:bin:script');
+const resolveWorkerOrThrow = (workspaceRoot) => {
+    const invocation = resolveDefaultRollupWorkerPath(workspaceRoot);
+    if (!invocation) {
+        throw index_cjs_js$6.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$4.join(ctx.outputPath, 'bin');
+    index_cjs_js$4.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;
+};
+
+const findCjsOutputPath = (jsOutputs) => {
+    for (const output of jsOutputs)
+        if (output.kind === 'cjs')
+            return output.outputPath;
+    return undefined;
+};
+/**
+ * Runs the bin phase: builds every declared JS bin, then emits a Node SEA native
+ * binary for any bin that opts in via `bin.sea`. Returns the flattened list of
+ * every output produced.
+ *
+ * A bin that declares a `sea` block must also produce a CJS output (`format: 'cjs'`
+ * or include `'cjs'` in the list); the CJS artifact becomes the SEA `main` script,
+ * and a bin without one throws. Native emission is skipped silently with an info
+ * log when the current host doesn't match any declared platform — CI orchestrates
+ * the matrix so each declared platform is built on the matching runner.
+ *
+ * @param ctx - Resolved build context.
+ * @param bins - Bin declarations to synthesize. Pass an empty array (or omit
+ * `config.bin` from the facade) to skip the phase entirely.
+ * @returns Flattened list of all bin outputs produced during the phase.
+ *
+ * @example Running the bin phase from a custom orchestrator
+ * ```typescript
+ * const binOutputs = await runBinPhase(context, config.bin ?? [])
+ * ```
+ */
+const runBinPhase = async (ctx, bins) => {
+    const outputs = [];
+    for (const bin of bins) {
+        const jsOutputs = await buildJsBin(bin, ctx);
+        outputs.push(...jsOutputs);
+        if (!bin.sea)
+            continue;
+        const cjsOutputPath = findCjsOutputPath(jsOutputs);
+        if (!cjsOutputPath) {
+            throw index_cjs_js$6.createError(`SEA requires a CJS bin output; declare format: ['cjs'] or format: 'cjs' on bin ${bin.name}`);
+        }
+        await recover();
+        const nativeOutputs = await buildNativeBin({ bin, ctx, cjsOutputPath });
+        outputs.push(...nativeOutputs);
+    }
+    return outputs;
+};
+
+exports.runBinPhase = runBinPhase;

package/bin/index.d.ts

@@ -0,0 +1,26 @@
+import { BuildContext, BinConfig, BinOutput } from '../models';
+
+/**
+ * Runs the bin phase: builds every declared JS bin, then emits a Node SEA native
+ * binary for any bin that opts in via `bin.sea`. Returns the flattened list of
+ * every output produced.
+ *
+ * A bin that declares a `sea` block must also produce a CJS output (`format: 'cjs'`
+ * or include `'cjs'` in the list); the CJS artifact becomes the SEA `main` script,
+ * and a bin without one throws. Native emission is skipped silently with an info
+ * log when the current host doesn't match any declared platform — CI orchestrates
+ * the matrix so each declared platform is built on the matching runner.
+ *
+ * @param ctx - Resolved build context.
+ * @param bins - Bin declarations to synthesize. Pass an empty array (or omit
+ * `config.bin` from the facade) to skip the phase entirely.
+ * @returns Flattened list of all bin outputs produced during the phase.
+ *
+ * @example Running the bin phase from a custom orchestrator
+ * ```typescript
+ * const binOutputs = await runBinPhase(context, config.bin ?? [])
+ * ```
+ */
+declare const runBinPhase: (ctx: BuildContext, bins: BinConfig[]) => Promise<BinOutput[]>;
+
+export { runBinPhase };

package/bin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/builder/src/bin/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA"}