@hyperfrontend/builder 0.1.0

package/bin/native/index.d.ts

@@ -0,0 +1,407 @@
+import { BinConfig, BuildContext, BinOutput, SeaPlatform } from '../../models';
+import { MemoryMonitor } from '../../memory';
+import { InjectWorkerJob, InjectWorkerReport } from './worker';
+export { InjectWorkerJob, InjectWorkerReport } from './worker';
+
+/**
+ * Inputs to {@link buildNativeBin}.
+ */
+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',
+ * })
+ * ```
+ */
+declare const buildNativeBin: (inputs: BuildNativeBinInputs) => Promise<BinOutput[]>;
+
+/**
+ * Inputs to {@link removeCodesign}.
+ */
+interface RemoveCodesignInputs {
+    /** Absolute path to the binary whose existing macOS signature should be removed. */
+    binary: string;
+}
+/**
+ * Inputs to {@link applyCodesign}.
+ */
+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.
+ */
+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' })
+ * ```
+ */
+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' })
+ * ```
+ */
+declare const applyCodesign: (inputs: ApplyCodesignInputs) => CodesignResult;
+
+/**
+ * Caller-supplied options threaded through {@link dispatchInjectWorker}.
+ */
+interface DispatchInjectWorkerOptions {
+    /** Absolute path to the worker entry script. Required — see {@link resolveDefaultInjectWorkerPath}. */
+    workerPath: string;
+    /** Optional memory monitor invoked before and after the spawned worker. */
+    monitor?: MemoryMonitor;
+    /** Override `process.execPath` for the spawned worker (used by tests). */
+    execPath?: string;
+    /** Extra arguments prepended to the worker invocation (e.g. `['--require', '@swc-node/register']`). */
+    execArgv?: string[];
+    /** Human-readable label for log lines and monitor checkpoints (e.g. `hf-build`). */
+    label?: string;
+}
+/**
+ * Resolved worker invocation: absolute path + any extra Node args (e.g. `--require \@swc-node/register`
+ * when the worker is loaded from TypeScript source during a bootstrap build).
+ */
+interface InjectWorkerInvocation {
+    /** Absolute path to the worker entry script. */
+    path: string;
+    /** Extra args prepended to the spawned child's argv. */
+    execArgv: string[];
+}
+/**
+ * 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')
+ * ```
+ */
+declare const resolveDefaultInjectWorkerPath: (workspaceRoot: string) => InjectWorkerInvocation | undefined;
+/**
+ * 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' }
+ * )
+ * ```
+ */
+declare const dispatchInjectWorker: (job: InjectWorkerJob, options: DispatchInjectWorkerOptions) => Promise<InjectWorkerReport>;
+
+/**
+ * Inputs to {@link resolveHostBinary}.
+ */
+interface ResolveHostBinaryInputs {
+    /** Target platform identifier (`<platform>-<arch>`). */
+    platform: SeaPlatform;
+    /** Override for the path of the current Node executable; defaults to `process.execPath`. */
+    currentExecPath?: string;
+    /** Override for the current platform identifier; defaults to `<process.platform>-<process.arch>`. */
+    currentPlatform?: string;
+}
+/**
+ * Resolves the path of the Node host binary that will be cloned and have the
+ * SEA blob injected into it.
+ *
+ * The resolver is current-platform-only: the host binary is always
+ * `process.execPath`. Cross-platform builds are orchestrated by an external
+ * CI matrix where each runner produces the binary for its own platform.
+ *
+ * Calling this function with a target platform that doesn't match the current
+ * host throws — the caller is expected to gate via {@link currentPlatformMatches}
+ * before invoking the SEA pipeline. The throw exists as a defense-in-depth
+ * check should that gate be bypassed.
+ *
+ * @param inputs - Target platform and optional current-host overrides for testability.
+ * @returns Absolute path to a Node host binary suitable as a postject template.
+ * @throws {Error} When the requested platform doesn't match the current process platform.
+ *
+ * @example Resolving the host for the current runner
+ * ```typescript
+ * const host = resolveHostBinary({ platform: 'linux-x64' }) // process.execPath
+ * ```
+ */
+declare const resolveHostBinary: (inputs: ResolveHostBinaryInputs) => string;
+
+/**
+ * Inputs to {@link injectBlob}.
+ */
+interface InjectBlobInputs {
+    /** Absolute path to the Node host binary to clone as the injection target. */
+    hostBinary: string;
+    /** Absolute path where the cloned + injected binary should land. */
+    outputBinary: string;
+    /** Absolute path to the SEA preparation blob produced by `node --experimental-sea-config`. */
+    blobPath: string;
+    /** Resource name for the injected SEA section. Defaults to Node's expected `NODE_SEA_BLOB`. */
+    resourceName?: string;
+    /** Mach-O segment name for macOS injection. Defaults to Node's expected `NODE_SEA`. */
+    machoSegmentName?: string;
+    /** SEA fuse string searched for in the binary. Defaults to Node's standard SEA fuse. */
+    sentinelFuse?: string;
+}
+/**
+ * Node's expected SEA resource name. Hardcoded by the runtime when looking up
+ * the embedded blob, so this value is required for the resulting binary to
+ * function as a single-executable application.
+ */
+declare const NODE_SEA_RESOURCE_NAME = "NODE_SEA_BLOB";
+/**
+ * Node's expected Mach-O segment name for SEA blobs on macOS.
+ */
+declare const NODE_SEA_MACHO_SEGMENT = "NODE_SEA";
+/**
+ * Sentinel fuse string Node's runtime flips from `0` → `1` to mark a SEA-injected binary.
+ *
+ * Built at runtime from two parts so the contiguous sentinel literal never appears
+ * in the bundled JS of a bin that imports this module: that JS is embedded in the
+ * SEA blob, and a contiguous copy there collides with the host binary's own sentinel,
+ * making postject reject the inject with "Multiple occurences of sentinel". Keep it
+ * split — do not inline into a single string literal.
+ */
+declare const NODE_SEA_FUSE: string;
+/**
+ * Clones the Node host binary to `outputBinary` and injects the SEA preparation
+ * blob via [postject](https://www.npmjs.com/package/postject)'s programmatic API.
+ *
+ * The host binary itself is never modified — postject mutates the cloned copy
+ * at `outputBinary`. The injection uses Node's expected SEA resource name and
+ * fuse so the produced executable is recognized by Node's SEA runtime.
+ *
+ * Callers are responsible for adjusting code-signing afterwards (see
+ * {@link removeCodesign} for macOS).
+ *
+ * @param inputs - Host binary, target output path, and blob path.
+ *
+ * @example Producing a SEA binary on a Linux runner
+ * ```typescript
+ * await injectBlob({
+ *   hostBinary: process.execPath,
+ *   outputBinary: '/abs/dist/libs/builder/bin/hf-build.linux-x64',
+ *   blobPath: '/abs/dist/libs/builder/bin/hf-build.sea-prep.blob',
+ * })
+ * ```
+ */
+declare const injectBlob: (inputs: InjectBlobInputs) => Promise<void>;
+
+/**
+ * Inputs to {@link generateSeaBlob}.
+ */
+interface GenerateSeaBlobInputs {
+    /** Absolute path to a SEA configuration JSON written to disk. */
+    seaConfigPath: string;
+    /** Absolute path the SEA configuration's `output` field points at; returned for caller convenience. */
+    outputBlobPath: string;
+    /** Override for the Node executable used to run the SEA-config command. Defaults to `process.execPath`. */
+    nodeExecutable?: string;
+}
+/**
+ * Outcome of a SEA blob generation attempt.
+ */
+interface GenerateSeaBlobResult {
+    /** Absolute path of the emitted blob (echoes `inputs.outputBlobPath`). */
+    blobPath: string;
+    /** Exit status returned by the `node --experimental-sea-config` invocation. */
+    status: number;
+}
+/**
+ * Spawns `node --experimental-sea-config <seaConfigPath>` to produce the SEA
+ * preparation blob declared by the config's `output` field.
+ *
+ * Spawn errors and non-zero exit codes are surfaced as thrown `Error`s with the
+ * captured stderr included; this function does not retry.
+ *
+ * @param inputs - Resolved SEA config path + the blob path declared in that config.
+ * @returns The blob path (for chaining) and the spawn status.
+ *
+ * @example Generating the SEA prep blob
+ * ```typescript
+ * const result = generateSeaBlob({
+ *   seaConfigPath: '/abs/dist/libs/builder/bin/hf-build.sea-config.json',
+ *   outputBlobPath: '/abs/dist/libs/builder/bin/hf-build.sea-prep.blob',
+ * })
+ * ```
+ */
+declare const generateSeaBlob: (inputs: GenerateSeaBlobInputs) => GenerateSeaBlobResult;
+
+/**
+ * Inputs to {@link generateSeaConfig}.
+ */
+interface SeaConfigInputs {
+    /** Absolute path to the bundled CJS entry the SEA blob will execute. */
+    mainPath: string;
+    /** Absolute path where the SEA blob should be emitted by `node --experimental-sea-config`. */
+    outputPath: string;
+}
+/**
+ * Shape of the JSON document consumed by `node --experimental-sea-config`.
+ *
+ * Mirrors the [Node SEA configuration schema]
+ * (https://nodejs.org/api/single-executable-applications.html). Builder always
+ * sets `disableExperimentalSEAWarning` so the produced binary doesn't print
+ * the warning banner on every invocation.
+ */
+interface SeaConfigDocument {
+    /** Absolute path to the script the SEA bundle will execute. */
+    main: string;
+    /** Absolute path to the blob that `node --experimental-sea-config` will write. */
+    output: string;
+    /** Suppresses the runtime "this is an experimental feature" warning. Always `true`. */
+    disableExperimentalSEAWarning: true;
+}
+/**
+ * Builds the JSON document consumed by `node --experimental-sea-config <path>`.
+ *
+ * Builder always emits `disableExperimentalSEAWarning: true` to silence the
+ * runtime warning banner on every native binary invocation — published bins
+ * are expected to behave like first-class executables.
+ *
+ * @param inputs - Resolved absolute paths for the SEA `main` script and `output` blob.
+ * @returns SEA config document ready to be JSON-serialized to disk.
+ *
+ * @example Generating a SEA config for a bin
+ * ```typescript
+ * const config = generateSeaConfig({
+ *   mainPath: '/abs/dist/libs/builder/bin/hf-build.cjs.js',
+ *   outputPath: '/abs/dist/libs/builder/bin/hf-build.sea-prep.blob',
+ * })
+ * ```
+ */
+declare const generateSeaConfig: (inputs: SeaConfigInputs) => SeaConfigDocument;
+
+/**
+ * Returns the target identifier for the current Node process in the form
+ * `<process.platform>-<process.arch>` (e.g., `linux-x64`).
+ *
+ * The string is shaped to match {@link SeaPlatform} but is returned as a plain
+ * string because callers commonly compare against arbitrary user-declared
+ * platform lists, which may legally include values not in the supported union.
+ *
+ * @returns `<platform>-<arch>` for the current process.
+ *
+ * @example Identifying the current target
+ * ```typescript
+ * const target = currentPlatformTarget() // 'linux-x64'
+ * ```
+ */
+declare const currentPlatformTarget: () => string;
+/**
+ * Returns `true` when the current Node process matches one of the declared
+ * SEA target platforms — i.e., when `<process.platform>-<process.arch>` is
+ * present in `declaredPlatforms`.
+ *
+ * Builder uses this gate to skip native emission silently on runners that
+ * weren't asked to produce a binary for the current host. CI orchestrates the
+ * matrix so each declared platform is built on the matching runner.
+ *
+ * @param declaredPlatforms - Platforms declared on the bin's `sea` config.
+ * @returns Whether the current host matches any declared platform.
+ *
+ * @example Gating native emission to declared targets
+ * ```typescript
+ * if (!currentPlatformMatches(bin.sea?.platforms ?? [])) {
+ *   log.info(`skipping native build for ${bin.name} on ${currentPlatformTarget()}`)
+ *   return []
+ * }
+ * ```
+ */
+declare const currentPlatformMatches: (declaredPlatforms: readonly SeaPlatform[]) => boolean;
+
+export { NODE_SEA_FUSE, NODE_SEA_MACHO_SEGMENT, NODE_SEA_RESOURCE_NAME, applyCodesign, buildNativeBin, currentPlatformMatches, currentPlatformTarget, dispatchInjectWorker, generateSeaBlob, generateSeaConfig, injectBlob, removeCodesign, resolveDefaultInjectWorkerPath, resolveHostBinary };
+export type { ApplyCodesignInputs, BuildNativeBinInputs, CodesignResult, DispatchInjectWorkerOptions, GenerateSeaBlobInputs, GenerateSeaBlobResult, InjectBlobInputs, InjectWorkerInvocation, RemoveCodesignInputs, ResolveHostBinaryInputs, SeaConfigDocument, SeaConfigInputs };

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bin/native/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAC1D,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC3F,YAAY,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AACrF,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAChD,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAC9E,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACtE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAA;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACpG,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA"}

package/bin/native/index.esm.js

@@ -0,0 +1,249 @@
+import { rmSync, existsSync, mkdtempSync, readFileSync, copyFileSync, 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 { 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, 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 { createPromise } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.esm.js';
+import { inject } from '../../_dependencies/postject/index.esm.js';
+import { normalizeFormats } from '../../_shared/bin/format/index.esm.js';
+import { removeCodesign, applyCodesign } 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, injectBlob } 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';
+
+const log$1 = logger.channel('builder:bin:native:dispatch');
+const REPORT_DIR_PREFIX = 'hf-builder-inject-';
+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/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(workspaceRoot)) {
+        return { path: sourcePath, execArgv: ['--require', SWC_NODE_REGISTER] };
+    }
+    return undefined;
+};
+const createReportDir = () => mkdtempSync(join(tmpdir(), REPORT_DIR_PREFIX));
+const reportPathFor = (reportDir, job) => {
+    const safeLabel = job.outputBinary.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return join(reportDir, `inject-${safeLabel}.json`);
+};
+const runOne = (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 = (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();
+    const label = options.label ?? job.outputBinary;
+    const reportPath = reportPathFor(reportDir, job);
+    const dispatched = { ...job, reportPath };
+    try {
+        options.monitor?.check(`bin:native:dispatch:${label}:start`);
+        log$1.info(`inject dispatch: ${label}`);
+        await runOne(dispatched, options, label);
+        const report = readReport(reportPath, label);
+        log$1.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 = 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.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.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.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.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.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.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 }];
+};
+
+export { NODE_SEA_FUSE, NODE_SEA_MACHO_SEGMENT, NODE_SEA_RESOURCE_NAME, applyCodesign, buildNativeBin, currentPlatformMatches, currentPlatformTarget, dispatchInjectWorker, generateSeaBlob, generateSeaConfig, injectBlob, removeCodesign, resolveDefaultInjectWorkerPath, resolveHostBinary };