@hyperfrontend/builder 0.1.0

package/bin/index.esm.js

@@ -0,0 +1,546 @@
+import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { createPromise } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
+import { setTimeout } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/timers/index.esm.js';
+import { existsSync, rmSync, mkdtempSync, readFileSync, unlinkSync } from 'node:fs';
+import { tmpdir, freemem } from 'node:os';
+import { dateNow } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.esm.js';
+import { logger } from '../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { join, ensureDir, writeJsonFile, exists } from '../_dependencies/@hyperfrontend/project-scope/core/index.esm.js';
+import { isArray } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
+import { spawnSync, spawn } from 'node:child_process';
+import { stringify, parse } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
+import '../_dependencies/postject/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 '../_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 { recover } from '../_shared/memory/recover/index.esm.js';
+import { normalizeFormats } from '../_shared/bin/format/index.esm.js';
+import { removeCodesign } from '../_shared/bin/native/codesign/index.esm.js';
+import { resolveHostBinary } from '../_shared/bin/native/host-binary/index.esm.js';
+import { NODE_SEA_RESOURCE_NAME, NODE_SEA_MACHO_SEGMENT, NODE_SEA_FUSE } from '../_shared/bin/native/inject/index.esm.js';
+import { currentPlatformTarget, currentPlatformMatches } from '../_shared/bin/native/platform-check/index.esm.js';
+import { generateSeaBlob } from '../_shared/bin/native/sea-blob/index.esm.js';
+import { generateSeaConfig } from '../_shared/bin/native/sea-config/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 log$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) => 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/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 = [
+        join(workspaceRoot, 'dist', 'libs', 'builder', 'bin', 'native', 'worker', 'index.cjs.js'),
+        join(workspaceRoot, 'node_modules', '@hyperfrontend', 'builder', 'bin', 'native', 'worker', 'index.cjs.js'),
+    ];
+    for (const path of distCandidates) {
+        if (existsSync(path))
+            return { path, execArgv: [] };
+    }
+    const sourcePath = join(workspaceRoot, 'libs', 'builder', 'src', 'bin', 'native', 'worker', 'index.ts');
+    if (existsSync(sourcePath) && swcNodeAvailable$1(workspaceRoot)) {
+        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER$1] };
+    }
+    return undefined;
+};
+const createReportDir$1 = () => mkdtempSync(join(tmpdir(), REPORT_DIR_PREFIX$1));
+const reportPathFor$1 = (reportDir, job) => {
+    const safeLabel = job.outputBinary.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return join(reportDir, `inject-${safeLabel}.json`);
+};
+const runOne$1 = (job, options, label) => createPromise((resolve, reject) => {
+    const execPath = options.execPath ?? process.execPath;
+    const argv = [...(options.execArgv ?? []), options.workerPath, stringify(job)];
+    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(`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(createError(`inject worker for ${label} exited with code ${code}\n${tail}`));
+            return;
+        }
+        resolve();
+    });
+});
+const readReport$1 = (reportPath, label) => {
+    if (!existsSync(reportPath)) {
+        throw createError(`inject worker for ${label} did not write a report at ${reportPath}`);
+    }
+    const data = parse(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 {
+        rmSync(reportDir, { recursive: true, force: true });
+    }
+};
+
+const log$2 = 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(freemem())}MB`);
+};
+const requireSeaConfig = (bin) => {
+    if (!bin.sea)
+        throw 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 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 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 (exists(file))
+            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 = join(ctx.outputPath, 'bin');
+    ensureDir(binDir);
+    const seaConfigPath = join(binDir, `${bin.name}.sea-config.json`);
+    const blobPath = 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 });
+    writeJsonFile(seaConfigPath, seaConfig);
+    memorySnapshot(`${bin.name}: pre-sea-blob`);
+    const blobStart = dateNow();
+    generateSeaBlob({ seaConfigPath, outputBlobPath: blobPath });
+    log$2.debug(`${bin.name}: sea blob generated in ${dateNow() - blobStart}ms`);
+    const hostBinary = resolveHostBinary({ platform: target });
+    memorySnapshot(`${bin.name}: pre-inject (host=${hostBinary})`);
+    const invocation = resolveDefaultInjectWorkerPath(ctx.workspaceRoot);
+    if (!invocation) {
+        throw 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 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;
+};
+
+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 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;
+};
+
+export { runBinPhase };

package/bin/native/build-native.d.ts

@@ -0,0 +1,44 @@
+import type { BinConfig, BinOutput, BuildContext } from '../../models';
+/**
+ * Inputs to {@link buildNativeBin}.
+ */
+export interface BuildNativeBinInputs {
+    /** Bin declaration. Must include a `sea` block; otherwise the function throws. */
+    bin: BinConfig;
+    /** Resolved build context. */
+    ctx: BuildContext;
+    /** Absolute path to the CJS bundle the SEA blob will execute. Must already be written to disk. */
+    cjsOutputPath: string;
+}
+/**
+ * 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',
+ * })
+ * ```
+ */
+export declare const buildNativeBin: (inputs: BuildNativeBinInputs) => Promise<BinOutput[]>;
+//# sourceMappingURL=build-native.d.ts.map

package/bin/native/build-native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-native.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bin/native/build-native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAe,MAAM,cAAc,CAAA;AA0BnF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,GAAG,EAAE,SAAS,CAAA;IACd,8BAA8B;IAC9B,GAAG,EAAE,YAAY,CAAA;IACjB,kGAAkG;IAClG,aAAa,EAAE,MAAM,CAAA;CACtB;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,cAAc,GAAU,QAAQ,oBAAoB,KAAG,OAAO,CAAC,SAAS,EAAE,CAgEtF,CAAA"}

package/bin/native/codesign.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Inputs to {@link removeCodesign}.
+ */
+export interface RemoveCodesignInputs {
+    /** Absolute path to the binary whose existing macOS signature should be removed. */
+    binary: string;
+}
+/**
+ * Inputs to {@link applyCodesign}.
+ */
+export interface ApplyCodesignInputs {
+    /** Absolute path to the binary to sign. */
+    binary: string;
+    /** Signing identity passed to `codesign --sign`. Use `'-'` for an ad-hoc signature. */
+    identity?: string;
+}
+/**
+ * Result of a codesign invocation.
+ */
+export interface CodesignResult {
+    /** Whether the codesign command was attempted (skipped silently on non-macOS hosts). */
+    ran: boolean;
+    /** Exit status of the codesign command, or `null` if it was skipped or did not start. */
+    status: number | null;
+    /** Captured stderr, useful for surfacing diagnostics. */
+    stderr: string;
+}
+/**
+ * Strips the macOS code signature from `inputs.binary` (via
+ * `codesign --remove-signature`) after postject's blob injection has
+ * invalidated it, leaving an unsigned binary that runs locally. No-op on
+ * non-macOS hosts.
+ *
+ * Re-signing the produced binary (with a real Apple Developer ID) is left to
+ * release tooling; this step only produces an unsigned executable that runs
+ * locally.
+ *
+ * @param inputs - Path to the binary to clean up.
+ * @returns Whether the command ran, its exit status, and captured stderr.
+ *
+ * @example Removing the signature on macOS before postject inject
+ * ```typescript
+ * removeCodesign({ binary: '/abs/dist/libs/builder/bin/hf-build.darwin-arm64' })
+ * ```
+ */
+export declare const removeCodesign: (inputs: RemoveCodesignInputs) => CodesignResult;
+/**
+ * Applies an ad-hoc (or identity-based) macOS code signature to the produced
+ * SEA binary. No-op on non-macOS hosts.
+ *
+ * Defaults to `--sign -` (ad-hoc signing), which is sufficient for local
+ * execution and satisfies macOS Catalina+ launch requirements without an
+ * Apple Developer identity. Release tooling can pass a real identity via
+ * `inputs.identity`.
+ *
+ * @param inputs - Binary path and optional signing identity.
+ * @returns Whether the command ran, its exit status, and captured stderr.
+ *
+ * @example Ad-hoc signing the produced SEA binary on macOS
+ * ```typescript
+ * applyCodesign({ binary: '/abs/dist/libs/builder/bin/hf-build.darwin-arm64' })
+ * ```
+ */
+export declare const applyCodesign: (inputs: ApplyCodesignInputs) => CodesignResult;
+//# sourceMappingURL=codesign.d.ts.map

package/bin/native/codesign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codesign.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bin/native/codesign.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,GAAG,EAAE,OAAO,CAAA;IACZ,yFAAyF;IACzF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAA;CACf;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,oBAAoB,KAAG,cAQ7D,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,mBAAmB,KAAG,cAS3D,CAAA"}