@hominis/fireforge 0.45.0 → 0.46.0

package/dist/src/utils/process.js

@@ -4,6 +4,7 @@ import { constants as osConstants } from 'node:os';
 import { StringDecoder } from 'node:string_decoder';
 import { ExecTimeoutError } from '../errors/base.js';
 import { buildChildEnv } from './child-env.js';
+import { dispatchCompleteLines } from './line-dispatch.js';
 import { killProcessTree, sweepProcessGroup } from './process-group.js';
 // 50 MB cap per stream to prevent OOM — large toolchain builds (e.g. Firefox, Chromium)
 // can easily blow past this, so we truncate rather than let the buffer grow unbounded.
@@ -57,12 +58,25 @@ function buildSignalFromTimeout(timeout) {
  * {@link ExecTimeoutError} naming the command and budget instead of Node's
  * opaque `AbortError: The operation was aborted`.
  */
-function toExecRejection(error, command, args, timeout) {
+function toExecRejection(error, command, args, timeout, output) {
     if (timeout !== undefined && error.name === 'AbortError') {
-        return new ExecTimeoutError(command, args, timeout, error);
+        return new ExecTimeoutError(command, args, timeout, error, output);
     }
     return error;
 }
+/**
+ * Snapshot of what two collectors hold, for carrying onto a timeout
+ * rejection. Without it a `git add -A` killed at its budget rejected with
+ * nothing but the budget — the partial stdout/stderr that said what git was
+ * doing when it died was already collected and simply dropped.
+ */
+function collectedOutput(out, err) {
+    return {
+        stdout: out.getText(),
+        stderr: err.getText(),
+        truncated: out.wasTruncated() || err.wasTruncated(),
+    };
+}
 function exitCodeFromClose(code, signal) {
     if (code !== null) {
         return code;
@@ -95,7 +109,7 @@ export async function exec(command, args, options = {}) {
         child.stdout.on('data', out.onData);
         child.stderr.on('data', err.onData);
         child.on('error', (error) => {
-            reject(toExecRejection(error, command, args, options.timeout));
+            reject(toExecRejection(error, command, args, options.timeout, collectedOutput(out, err)));
         });
         child.on('close', (code, signal) => {
             resolve({
@@ -109,48 +123,48 @@ export async function exec(command, args, options = {}) {
     });
 }
 /**
- * Executes a command and streams its output.
- * @param command - Command to execute
- * @param args - Command arguments
- * @param options - Execution options
- * @returns Exit code of the process
+ * The shared body of every spawn wrapper that outlives its call: detach
+ * decision, shutdown forwarding, closure tracking, process-group sweep and
+ * typed timeout rejection.
+ *
+ * `execStream`, `execInherit` and `execInheritCapture` each hand-rolled this
+ * sequence, and the copies drifted: `execStream` was the one that omitted
+ * {@link trackChildClosure}, so the bin signal handler did not wait for
+ * `runMachStream`'s children on Ctrl+C and the forwarder's SIGTERM → grace →
+ * SIGKILL escalation could not finish before the parent exited — the exact
+ * failure the tracking set was introduced to fix, left unwired in one copy.
+ * Keeping the sequence in one place is what stops that recurring.
+ *
+ * `exec` deliberately stays outside: it neither forwards signals nor tracks
+ * closure, because it is for short-lived helpers that no one Ctrl+Cs through.
+ * `execSmokeRun` also stays outside: its deadline owns the SIGTERM → grace →
+ * SIGKILL escalation directly, so it shares no forwarder with the others.
+ *
+ * @param spec - The variant's stdio, stream wiring, grace budget and result shape
+ * @returns Whatever `spec.result` builds from the child's `close` event
  */
-export async function execStream(command, args, options = {}) {
+async function spawnTracked(spec) {
+    const { command, args, options } = spec;
     return new Promise((resolve, reject) => {
         const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
-        const child = spawn(command, args, {
+        const child = spec.spawnChild({
             cwd: options.cwd,
             env: buildChildEnv(options),
-            stdio: ['ignore', 'pipe', 'pipe'],
             signal: buildSignalFromTimeout(options.timeout),
             detached: usesProcessGroup,
         });
         const groupPid = usesProcessGroup ? child.pid : undefined;
-        const stdoutDecoder = new StringDecoder('utf8');
-        const stderrDecoder = new StringDecoder('utf8');
-        child.stdout.on('data', (data) => {
-            const chunk = stdoutDecoder.write(data);
-            if (chunk.length > 0)
-                options.onStdout?.(chunk);
-        });
-        child.stderr.on('data', (data) => {
-            const chunk = stderrDecoder.write(data);
-            if (chunk.length > 0)
-                options.onStderr?.(chunk);
-        });
-        // A detached group leader no longer receives the terminal's Ctrl+C, so
-        // the forwarder is mandatory (not just graceful-UX) when processGroup
-        // is set. Group-aware: kills route to the whole tree.
-        const forwarder = options.processGroup === true
-            ? installGracefulShutdownForwarder(child, 1500, (signal) => {
+        spec.attach?.(child);
+        // Group-aware kills route to the whole tree; a non-group child is killed
+        // directly by the forwarder's own `child.kill`.
+        const killTarget = options.processGroup === true
+            ? (signal) => {
                 killProcessTree(child, signal, usesProcessGroup);
-            })
+            }
+            : undefined;
+        const forwarder = spec.forwardWithoutProcessGroup || options.processGroup === true
+            ? installGracefulShutdownForwarder(child, spec.graceMs, killTarget)
             : undefined;
-        // Closure tracking: this was the one wrapper that omitted it, so the bin
-        // signal handler did not wait for `runMachStream`'s children on Ctrl+C
-        // and the forwarder's SIGTERM → grace → SIGKILL escalation above could
-        // not finish before the parent exited — the exact failure the tracking
-        // set was introduced to fix, left unwired here.
         const closure = trackChildClosure();
         child.on('error', (error) => {
             // Abort/startup failure: make sure a partially-started tree does not
@@ -161,13 +175,13 @@ export async function execStream(command, args, options = {}) {
             }
             forwarder?.dispose();
             closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout));
+            reject(toExecRejection(error, command, args, options.timeout, spec.rejectionOutput?.()));
         });
         child.on('close', (code, signal) => {
             forwarder?.dispose();
             const finish = () => {
                 closure.settle();
-                resolve(exitCodeFromClose(code, signal));
+                resolve(spec.result(code, signal));
             };
             if (groupPid !== undefined) {
                 sweepProcessGroup(groupPid).then(finish, finish);
@@ -178,6 +192,41 @@ export async function execStream(command, args, options = {}) {
         });
     });
 }
+/**
+ * Executes a command and streams its output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Exit code of the process
+ */
+export async function execStream(command, args, options = {}) {
+    return spawnTracked({
+        command,
+        args,
+        options,
+        graceMs: 1500,
+        // A detached group leader no longer receives the terminal's Ctrl+C, so
+        // the forwarder is mandatory (not just graceful-UX) when processGroup
+        // is set — but a plain streamed child does not get one.
+        forwardWithoutProcessGroup: false,
+        spawnChild: (base) => spawn(command, args, { ...base, stdio: ['ignore', 'pipe', 'pipe'] }),
+        attach: (child) => {
+            const stdoutDecoder = new StringDecoder('utf8');
+            const stderrDecoder = new StringDecoder('utf8');
+            child.stdout.on('data', (data) => {
+                const chunk = stdoutDecoder.write(data);
+                if (chunk.length > 0)
+                    options.onStdout?.(chunk);
+            });
+            child.stderr.on('data', (data) => {
+                const chunk = stderrDecoder.write(data);
+                if (chunk.length > 0)
+                    options.onStderr?.(chunk);
+            });
+        },
+        result: exitCodeFromClose,
+    });
+}
 /**
  * Close-promises of children whose shutdown the CLI must wait for when a
  * termination signal arrives. A bin signal handler that calls `process.exit`
@@ -253,44 +302,14 @@ export async function waitForActiveChildShutdown(timeoutMs) {
  * @returns Exit code of the process
  */
 export async function execInherit(command, args, options = {}) {
-    return new Promise((resolve, reject) => {
-        const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
-        const child = spawn(command, args, {
-            cwd: options.cwd,
-            env: buildChildEnv(options),
-            stdio: 'inherit',
-            signal: buildSignalFromTimeout(options.timeout),
-            detached: usesProcessGroup,
-        });
-        const groupPid = usesProcessGroup ? child.pid : undefined;
-        const graceMs = options.shutdownGraceMs ?? 1500;
-        const { dispose } = installGracefulShutdownForwarder(child, graceMs, options.processGroup === true
-            ? (signal) => {
-                killProcessTree(child, signal, usesProcessGroup);
-            }
-            : undefined);
-        const closure = trackChildClosure();
-        child.on('error', (error) => {
-            if (options.processGroup === true) {
-                killProcessTree(child, 'SIGKILL', usesProcessGroup);
-            }
-            dispose();
-            closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout));
-        });
-        child.on('close', (code, signal) => {
-            dispose();
-            const finish = () => {
-                closure.settle();
-                resolve(exitCodeFromClose(code, signal));
-            };
-            if (groupPid !== undefined) {
-                sweepProcessGroup(groupPid).then(finish, finish);
-            }
-            else {
-                finish();
-            }
-        });
+    return spawnTracked({
+        command,
+        args,
+        options,
+        graceMs: options.shutdownGraceMs ?? 1500,
+        forwardWithoutProcessGroup: true,
+        spawnChild: (base) => spawn(command, args, { ...base, stdio: 'inherit' }),
+        result: exitCodeFromClose,
     });
 }
 /**
@@ -365,54 +384,27 @@ export function installGracefulShutdownForwarder(child, graceMs, killTarget) {
  * @returns Execution result with stdout, stderr, and exit code
  */
 export async function execInheritCapture(command, args, options = {}) {
-    return new Promise((resolve, reject) => {
-        const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
-        const child = spawn(command, args, {
-            cwd: options.cwd,
-            env: buildChildEnv(options),
-            stdio: ['inherit', 'pipe', 'pipe'],
-            signal: buildSignalFromTimeout(options.timeout),
-            detached: usesProcessGroup,
-        });
-        const groupPid = usesProcessGroup ? child.pid : undefined;
-        const out = createStreamCollector(options.mirror?.stdout ?? process.stdout);
-        const err = createStreamCollector(options.mirror?.stderr ?? process.stderr);
-        child.stdout.on('data', out.onData);
-        child.stderr.on('data', err.onData);
-        const graceMs = options.shutdownGraceMs ?? 1500;
-        const { dispose } = installGracefulShutdownForwarder(child, graceMs, options.processGroup === true
-            ? (signal) => {
-                killProcessTree(child, signal, usesProcessGroup);
-            }
-            : undefined);
-        const closure = trackChildClosure();
-        child.on('error', (error) => {
-            if (options.processGroup === true) {
-                killProcessTree(child, 'SIGKILL', usesProcessGroup);
-            }
-            dispose();
-            closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout));
-        });
-        child.on('close', (code, signal) => {
-            dispose();
-            const finish = () => {
-                closure.settle();
-                resolve({
-                    stdout: out.getText(),
-                    stderr: err.getText(),
-                    exitCode: exitCodeFromClose(code, signal),
-                    stdoutTruncated: out.wasTruncated(),
-                    stderrTruncated: err.wasTruncated(),
-                });
-            };
-            if (groupPid !== undefined) {
-                sweepProcessGroup(groupPid).then(finish, finish);
-            }
-            else {
-                finish();
-            }
-        });
+    const out = createStreamCollector(options.mirror?.stdout ?? process.stdout);
+    const err = createStreamCollector(options.mirror?.stderr ?? process.stderr);
+    return spawnTracked({
+        command,
+        args,
+        options,
+        graceMs: options.shutdownGraceMs ?? 1500,
+        forwardWithoutProcessGroup: true,
+        spawnChild: (base) => spawn(command, args, { ...base, stdio: ['inherit', 'pipe', 'pipe'] }),
+        attach: (child) => {
+            child.stdout.on('data', out.onData);
+            child.stderr.on('data', err.onData);
+        },
+        result: (code, signal) => ({
+            stdout: out.getText(),
+            stderr: err.getText(),
+            exitCode: exitCodeFromClose(code, signal),
+            stdoutTruncated: out.wasTruncated(),
+            stderrTruncated: err.wasTruncated(),
+        }),
+        rejectionOutput: () => collectedOutput(out, err),
     });
 }
 /**
@@ -542,48 +534,6 @@ export async function execSmokeRun(command, args, options) {
         });
     });
 }
-/**
- * Cap on the partial-line tail kept between chunks. A child emitting one
- * enormous line with no terminator (minified JS dumped to stderr, a raw
- * binary blob) would otherwise grow the buffer without bound — the 50 MB cap
- * guards the collector, not these line buffers. When the tail exceeds the
- * cap it is dispatched as a synthetic (oversized) line so the matchers still
- * see its content, then the buffer resets.
- */
-const MAX_PARTIAL_LINE_SIZE = 1024 * 1024;
-/**
- * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
- * `\n`, `\r\n`, and lone `\r` as line terminators — the lone-`\r` case
- * matters for progress-bar style output (mach, cargo) that repaints a line
- * with carriage returns and never sends a newline, which otherwise
- * accumulates indefinitely. A single trailing `\r` is held back since it may
- * be the first half of a `\r\n` pair split across chunks. Returns the
- * remaining partial line — callers keep accumulating into it.
- */
-function dispatchCompleteLines(buffer, cb) {
-    let searchFrom = 0;
-    for (;;) {
-        const nl = buffer.indexOf('\n', searchFrom);
-        const cr = buffer.indexOf('\r', searchFrom);
-        const idx = nl === -1 ? cr : cr === -1 ? nl : Math.min(nl, cr);
-        if (idx === -1)
-            break;
-        if (buffer[idx] === '\r' && idx === buffer.length - 1) {
-            // Possible first half of a chunk-split \r\n — wait for the next chunk.
-            break;
-        }
-        const line = buffer.slice(0, idx);
-        const terminatorLength = buffer[idx] === '\r' && buffer[idx + 1] === '\n' ? 2 : 1;
-        buffer = buffer.slice(idx + terminatorLength);
-        searchFrom = 0;
-        cb?.(line);
-    }
-    if (buffer.length > MAX_PARTIAL_LINE_SIZE) {
-        cb?.(buffer);
-        return '';
-    }
-    return buffer;
-}
 /**
  * Finds an executable in the system PATH.
  * @param name - Name of the executable
@@ -602,8 +552,7 @@ export async function findExecutable(name) {
         }
         return undefined;
     }
-    catch (error) {
-        void error;
+    catch {
         return undefined;
     }
 }

package/dist/src/utils/ps-duration.js

@@ -58,13 +58,13 @@ export function formatPsDuration(seconds) {
     if (Number.isNaN(seconds) || seconds < 0)
         return undefined;
     if (seconds < 60)
-        return `${String(Math.floor(seconds))}s`;
+        return `${Math.floor(seconds)}s`;
     if (seconds < 3600) {
         const m = Math.floor(seconds / 60);
         const s = Math.floor(seconds % 60);
-        return `${String(m)}m${String(s).padStart(2, '0')}s`;
+        return `${m}m${String(s).padStart(2, '0')}s`;
     }
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
-    return `${String(h)}h${String(m).padStart(2, '0')}m`;
+    return `${h}h${String(m).padStart(2, '0')}m`;
 }

package/dist/src/utils/sleep.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The single awaitable delay used across FireForge.
+ *
+ * Five modules had grown a private copy of this (`sleep`, `delay`,
+ * `sweepDelay`) and four more sites inlined
+ * `new Promise((resolve) => setTimeout(resolve, ms))`. The copies disagreed on
+ * the one property that actually matters — whether the pending timer holds the
+ * event loop open — and the disagreement was invisible at each call site. Both
+ * behaviours now live here, and callers state which one they need.
+ *
+ * The default is a ref'd timer, because the dangerous mistake is the other
+ * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node
+ * exit mid-grace and skip the escalation entirely.
+ *
+ * Deliberately built on the global `setTimeout` rather than
+ * `node:timers/promises`: the suites that drive retry and grace-period logic
+ * use vitest fake timers, which patch the global but not the promisified
+ * module, so the tidier import would make every timing path untestable.
+ * @param ms - Milliseconds to wait.
+ * @param options - Pass `unref: true` when a pending delay must not keep the
+ *   process alive (background probes, best-effort retries during shutdown).
+ * @returns A promise that resolves once the delay has elapsed.
+ */
+export declare function sleep(ms: number, options?: {
+    unref?: boolean;
+}): Promise<void>;

package/dist/src/utils/sleep.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The single awaitable delay used across FireForge.
+ *
+ * Five modules had grown a private copy of this (`sleep`, `delay`,
+ * `sweepDelay`) and four more sites inlined
+ * `new Promise((resolve) => setTimeout(resolve, ms))`. The copies disagreed on
+ * the one property that actually matters — whether the pending timer holds the
+ * event loop open — and the disagreement was invisible at each call site. Both
+ * behaviours now live here, and callers state which one they need.
+ *
+ * The default is a ref'd timer, because the dangerous mistake is the other
+ * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node
+ * exit mid-grace and skip the escalation entirely.
+ *
+ * Deliberately built on the global `setTimeout` rather than
+ * `node:timers/promises`: the suites that drive retry and grace-period logic
+ * use vitest fake timers, which patch the global but not the promisified
+ * module, so the tidier import would make every timing path untestable.
+ * @param ms - Milliseconds to wait.
+ * @param options - Pass `unref: true` when a pending delay must not keep the
+ *   process alive (background probes, best-effort retries during shutdown).
+ * @returns A promise that resolves once the delay has elapsed.
+ */
+export function sleep(ms, options) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        if (options?.unref === true)
+            timer.unref();
+    });
+}

package/dist/src/utils/validation.d.ts

@@ -73,40 +73,12 @@ export declare function isValidFirefoxVersion(version: string): boolean;
  * Accepts formats like "build1", "build2", "build12" (no leading zero).
  */
 export declare function isValidFirefoxCandidate(candidate: string): boolean;
-/**
- * Naming contract for this module's checks.
- *
- * `validate*` is easy to spread across incompatible return contracts — some
- * throwing and returning void, some returning an issue list, some a parsed
- * value, some a boolean, some an error MESSAGE — and a caller cannot tell
- * which from the name. Passing a THROWING `validate*` to a clack `validate`
- * callback, which expects a returned message, kills the prompt instead of
- * re-prompting.
- *
- * The two dominant contracts keep the prefix:
- *   - `validate*` — throws on failure, or returns an issue list.
- *   - `is*` / `has*` — a type predicate or boolean.
- * The message-returning minority is `describe*Problem`, which reads as what
- * it is: a description of what is wrong, or `undefined`.
- *
- * `assert*` is uniform throughout: throw-or-continue.
- */
-/**
- * Valid Firefox product identifiers.
- *
- * `satisfies readonly FirefoxProduct[]` links the runtime list to the union
- * in ONE direction: it rejects an entry here that the union does not
- * declare. It cannot see a union member missing from this list — widening a
- * `readonly T[]` check never fails for being short. The reverse direction is
- * covered by the exhaustive switch in `utils/__tests__/validation.test.ts`,
- * which fails to compile when the union grows.
- */
 export declare const FIREFOX_PRODUCTS: readonly ["firefox", "firefox-esr", "firefox-beta", "firefox-devedition"];
 /**
  * Validates a Firefox product string.
  *
- * A type predicate, matching its siblings {@link isValidPatchCategory} and
- * {@link isValidProjectLicense}. Returning plain `boolean` would force
+ * A type predicate, matching its sibling {@link isValidProjectLicense}.
+ * Returning plain `boolean` would force
  * `as FirefoxProduct` casts at the call sites even though the `.includes`
  * check IS the runtime proof.
  */
@@ -141,10 +113,6 @@ export declare const isValidProjectLicense: (value: string) => value is "EUPL-1.
  * Valid patch categories.
  */
 export declare const PATCH_CATEGORIES: readonly ["branding", "ui", "privacy", "security", "infra"];
-/**
- * Validates a patch category string.
- */
-export declare const isValidPatchCategory: (value: string) => value is "branding" | "ui" | "privacy" | "security" | "infra";
 /**
  * Infers the Firefox product type from a version string.
  * Returns undefined if no clear inference can be made.
@@ -166,10 +134,6 @@ export declare function describeProductVersionIncompatibility(version: string, p
  * Accepts reverse-domain format like "org.example.browser"
  */
 export declare function isValidAppId(appId: string): boolean;
-/**
- * Checks if a value is defined (not undefined or null).
- */
-export declare function isDefined<T>(value: T | undefined | null): value is T;
 /**
  * Validates that a string is a legal CSS custom property identifier (the part after `--`).
  *

package/dist/src/utils/validation.js

@@ -89,7 +89,7 @@ export function isArray(value) {
  * @returns True if value is a JSON object node
  */
 export function isJsonObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return isObject(value);
 }
 /**
  * Validates a Firefox version string.
@@ -132,20 +132,21 @@ export function isValidFirefoxCandidate(candidate) {
  * in ONE direction: it rejects an entry here that the union does not
  * declare. It cannot see a union member missing from this list — widening a
  * `readonly T[]` check never fails for being short. The reverse direction is
- * covered by the exhaustive switch in `utils/__tests__/validation.test.ts`,
- * which fails to compile when the union grows.
+ * covered by the `ExhaustiveFirefoxProductList` operand below, which stops
+ * compiling when the union grows past this list.
  */
-export const FIREFOX_PRODUCTS = [
+const FIREFOX_PRODUCT_VALUES = [
     'firefox',
     'firefox-esr',
     'firefox-beta',
     'firefox-devedition',
 ];
+export const FIREFOX_PRODUCTS = FIREFOX_PRODUCT_VALUES;
 /**
  * Validates a Firefox product string.
  *
- * A type predicate, matching its siblings {@link isValidPatchCategory} and
- * {@link isValidProjectLicense}. Returning plain `boolean` would force
+ * A type predicate, matching its sibling {@link isValidProjectLicense}.
+ * Returning plain `boolean` would force
  * `as FirefoxProduct` casts at the call sites even though the `.includes`
  * check IS the runtime proof.
  */
@@ -182,10 +183,6 @@ export const isValidProjectLicense = makeEnumGuard(PROJECT_LICENSES);
  * Valid patch categories.
  */
 export const PATCH_CATEGORIES = ['branding', 'ui', 'privacy', 'security', 'infra'];
-/**
- * Validates a patch category string.
- */
-export const isValidPatchCategory = makeEnumGuard(PATCH_CATEGORIES);
 /**
  * Checks whether a Firefox version string has an ESR suffix.
  */
@@ -257,12 +254,6 @@ export function describeProductVersionIncompatibility(version, product) {
 export function isValidAppId(appId) {
     return /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/.test(appId);
 }
-/**
- * Checks if a value is defined (not undefined or null).
- */
-export function isDefined(value) {
-    return value !== undefined && value !== null;
-}
 /**
  * Validates that a string is a legal CSS custom property identifier (the part after `--`).
  *