@hyperfrontend/builder 0.1.0

package/bin/native/dispatch.d.ts

@@ -0,0 +1,75 @@
+import type { MemoryMonitor } from '../../memory/monitor';
+import type { InjectWorkerJob, InjectWorkerReport } from './worker/types';
+/**
+ * Caller-supplied options threaded through {@link dispatchInjectWorker}.
+ */
+export 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).
+ */
+export 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')
+ * ```
+ */
+export 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' }
+ * )
+ * ```
+ */
+export declare const dispatchInjectWorker: (job: InjectWorkerJob, options: DispatchInjectWorkerOptions) => Promise<InjectWorkerReport>;
+//# sourceMappingURL=dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bin/native/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAYzE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,uGAAuG;IACvG,UAAU,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,8BAA8B,GAAI,eAAe,MAAM,KAAG,sBAAsB,GAAG,SAa/F,CAAA;AA4CD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,GAAU,KAAK,eAAe,EAAE,SAAS,2BAA2B,KAAG,OAAO,CAAC,kBAAkB,CAkBjI,CAAA"}

package/bin/native/host-binary.d.ts

@@ -0,0 +1,36 @@
+import type { SeaPlatform } from '../../models';
+/**
+ * Inputs to {@link resolveHostBinary}.
+ */
+export 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
+ * ```
+ */
+export declare const resolveHostBinary: (inputs: ResolveHostBinaryInputs) => string;
+//# sourceMappingURL=host-binary.d.ts.map

package/bin/native/host-binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-binary.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/builder/src/bin/native/host-binary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,QAAQ,EAAE,WAAW,CAAA;IACrB,4FAA4F;IAC5F,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qGAAqG;IACrG,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,uBAAuB,KAAG,MAQnE,CAAA"}

package/bin/native/index.cjs.js

@@ -0,0 +1,264 @@
+'use strict';
+
+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$5 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
+const index_cjs_js$2 = require('../../_dependencies/@hyperfrontend/project-scope/core/index.cjs.js');
+const index_cjs_js = 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$4 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
+const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/promise/index.cjs.js');
+const index_cjs_js$6 = require('../../_dependencies/postject/index.cjs.js');
+const { normalizeFormats } = require('../../_shared/bin/format/index.cjs.js');
+const { removeCodesign, applyCodesign } = 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, injectBlob } = 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 log$1 = index_cjs_js$1.logger.channel('builder:bin:native:dispatch');
+const REPORT_DIR_PREFIX = 'hf-builder-inject-';
+const SWC_NODE_REGISTER = '@swc-node/register';
+const swcNodeAvailable = (workspaceRoot) => node_fs.existsSync(index_cjs_js$2.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$2.join(workspaceRoot, 'dist', 'libs', 'builder', 'bin', 'native', 'worker', 'index.cjs.js'),
+        index_cjs_js$2.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$2.join(workspaceRoot, 'libs', 'builder', 'src', 'bin', 'native', '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$2.join(node_os.tmpdir(), REPORT_DIR_PREFIX));
+const reportPathFor = (reportDir, job) => {
+    const safeLabel = job.outputBinary.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return index_cjs_js$2.join(reportDir, `inject-${safeLabel}.json`);
+};
+const runOne = (job, options, label) => index_cjs_js$3.createPromise((resolve, reject) => {
+    const execPath = options.execPath ?? process.execPath;
+    const argv = [...(options.execArgv ?? []), options.workerPath, index_cjs_js$4.stringify(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$5.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$5.createError(`inject worker for ${label} exited with code ${code}\n${tail}`));
+            return;
+        }
+        resolve();
+    });
+});
+const readReport = (reportPath, label) => {
+    if (!node_fs.existsSync(reportPath)) {
+        throw index_cjs_js$5.createError(`inject worker for ${label} did not write a report at ${reportPath}`);
+    }
+    const data = index_cjs_js$4.parse(node_fs.readFileSync(reportPath, 'utf8'));
+    return data;
+};
+/**
+ * Forks a single 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 {
+        node_fs.rmSync(reportDir, { recursive: true, force: true });
+    }
+};
+
+const log = index_cjs_js$1.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(node_os.freemem())}MB`);
+};
+const requireSeaConfig = (bin) => {
+    if (!bin.sea)
+        throw index_cjs_js$5.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$5.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$2.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$2.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.info(`skipping native build for ${bin.name}: current platform ${target} not in declared targets [${platforms.join(', ')}]`);
+        return [];
+    }
+    const binDir = index_cjs_js$2.join(ctx.outputPath, 'bin');
+    index_cjs_js$2.ensureDir(binDir);
+    const seaConfigPath = index_cjs_js$2.join(binDir, `${bin.name}.sea-config.json`);
+    const blobPath = index_cjs_js$2.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 });
+    index_cjs_js$2.writeJsonFile(seaConfigPath, seaConfig);
+    memorySnapshot(`${bin.name}: pre-sea-blob`);
+    const blobStart = index_cjs_js$7.dateNow();
+    generateSeaBlob({ seaConfigPath, outputBlobPath: blobPath });
+    log.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$5.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 }];
+};
+
+exports.NODE_SEA_FUSE = NODE_SEA_FUSE;
+exports.NODE_SEA_MACHO_SEGMENT = NODE_SEA_MACHO_SEGMENT;
+exports.NODE_SEA_RESOURCE_NAME = NODE_SEA_RESOURCE_NAME;
+exports.applyCodesign = applyCodesign;
+exports.buildNativeBin = buildNativeBin;
+exports.currentPlatformMatches = currentPlatformMatches;
+exports.currentPlatformTarget = currentPlatformTarget;
+exports.dispatchInjectWorker = dispatchInjectWorker;
+exports.generateSeaBlob = generateSeaBlob;
+exports.generateSeaConfig = generateSeaConfig;
+exports.injectBlob = injectBlob;
+exports.removeCodesign = removeCodesign;
+exports.resolveDefaultInjectWorkerPath = resolveDefaultInjectWorkerPath;
+exports.resolveHostBinary = resolveHostBinary;