@hominis/fireforge 0.36.0 → 0.38.0

package/dist/src/utils/process-group.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Process-group kill and post-run sweep helpers for the exec layer
+ * (0.37.0 item 9a). Split out of `process.ts` to keep that file within the
+ * per-file line budget; deliberately spawn-based (not `exec`-based) so the
+ * two modules do not import each other cyclically.
+ */
+import { type ChildProcess } from 'node:child_process';
+/**
+ * Sends `signal` to the child's whole tree: the process GROUP on POSIX
+ * (negative-PID kill — reaches mach → python → firefox → content-process
+ * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
+ * fallback on Windows. No-ops once the direct child has exited (group
+ * survivors after exit are the post-run sweep's job, not this function's).
+ */
+export declare function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, usesProcessGroup: boolean): void;
+/** One process still alive in a swept group. */
+export interface ProcessGroupSurvivor {
+    /** PID, or -1 when pgrep was unavailable and only a liveness probe ran. */
+    pid: number;
+    /** Command line (pgrep -lf output), best-effort. */
+    command: string;
+}
+/**
+ * Post-run reaper for a process group FireForge itself spawned (`pgid` is
+ * the PID of a child started with `detached: true`): lists survivors,
+ * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
+ * about anything that still refuses to die. POSIX only (no-op on win32).
+ * The only kill target is `-pgid` — never anything outside the group.
+ * A healthy run costs exactly one `pgrep`.
+ */
+export declare function sweepProcessGroup(pgid: number, graceMs?: number): Promise<{
+    survivors: ProcessGroupSurvivor[];
+}>;

package/dist/src/utils/process-group.js

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Process-group kill and post-run sweep helpers for the exec layer
+ * (0.37.0 item 9a). Split out of `process.ts` to keep that file within the
+ * per-file line budget; deliberately spawn-based (not `exec`-based) so the
+ * two modules do not import each other cyclically.
+ */
+import { spawn } from 'node:child_process';
+import { verbose, warn } from './logger.js';
+/**
+ * Sends `signal` to the child's whole tree: the process GROUP on POSIX
+ * (negative-PID kill — reaches mach → python → firefox → content-process
+ * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
+ * fallback on Windows. No-ops once the direct child has exited (group
+ * survivors after exit are the post-run sweep's job, not this function's).
+ */
+export function killProcessTree(child, signal, usesProcessGroup) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const targetPid = child.pid;
+    if (targetPid === undefined)
+        return;
+    try {
+        if (usesProcessGroup) {
+            // Negative PID routes to the process group, killing the Python
+            // wrapper, the firefox it forked, and every content process
+            // that inherited the group.
+            process.kill(-targetPid, signal);
+        }
+        else {
+            // No process group on Windows — taskkill /T walks the descendant
+            // tree instead. Always forced (/F): there is no SIGTERM analogue,
+            // so the grace window only exists on POSIX.
+            spawn('taskkill', ['/pid', String(targetPid), '/T', '/F'], {
+                stdio: 'ignore',
+            }).on('error', () => {
+                // taskkill unavailable — nothing more we can do beyond the
+                // direct-child kill below.
+            });
+            child.kill(signal);
+        }
+    }
+    catch {
+        // Already gone. Nothing to do.
+    }
+}
+const SWEEP_GRACE_MS = 2000;
+const MULTIPROCESSING_WORKER_PATTERN = /multiprocessing\.(?:spawn|forkserver)|resource_tracker/;
+function sweepDelay(ms) {
+    // Deliberately ref'd (no unref()): this promise is AWAITED between the
+    // group SIGTERM and the post-grace re-list/SIGKILL escalation, from a
+    // child 'close' handler after the signal forwarder is disposed — with an
+    // unref'd timer nothing kept the event loop alive, so Node could exit
+    // mid-grace and skip the escalation entirely. Healthy runs never reach
+    // this function (sweepProcessGroup early-returns on zero survivors), so
+    // the ref never holds a clean exit open.
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Minimal spawn-based pgrep runner. exitCode -1 means pgrep itself was
+ * unavailable or errored (distinct from exit 1 = "no matches").
+ */
+async function runPgrep(args) {
+    return new Promise((resolve) => {
+        const child = spawn('pgrep', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString('utf8');
+        });
+        child.on('error', () => {
+            resolve({ exitCode: -1, stdout: '' });
+        });
+        child.on('close', (code) => {
+            resolve({ exitCode: code ?? -1, stdout });
+        });
+    });
+}
+/** Lists processes still in `pgid` via `pgrep -g -lf`, with a kill(0) fallback. */
+async function listGroupSurvivors(pgid) {
+    const result = await runPgrep(['-g', String(pgid), '-lf']);
+    if (result.exitCode === 0) {
+        return result.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            const match = /^(\d+)\s+(.*)$/.exec(line);
+            return match
+                ? { pid: Number(match[1]), command: match[2] ?? '' }
+                : { pid: -1, command: line };
+        });
+    }
+    if (result.exitCode === 1)
+        return []; // no matches
+    // pgrep unavailable/broken: fall back to a group liveness probe.
+    try {
+        process.kill(-pgid, 0);
+        return [{ pid: -1, command: 'unknown (pgrep unavailable; group still has live members)' }];
+    }
+    catch {
+        return [];
+    }
+}
+function describeSurvivors(list) {
+    return list
+        .map((s) => {
+        const tag = MULTIPROCESSING_WORKER_PATTERN.test(s.command)
+            ? ' [multiprocessing worker — the known busy-spin orphan shape]'
+            : '';
+        return `PID ${String(s.pid)}: ${s.command}${tag}`;
+    })
+        .join('; ');
+}
+/**
+ * Post-run reaper for a process group FireForge itself spawned (`pgid` is
+ * the PID of a child started with `detached: true`): lists survivors,
+ * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
+ * about anything that still refuses to die. POSIX only (no-op on win32).
+ * The only kill target is `-pgid` — never anything outside the group.
+ * A healthy run costs exactly one `pgrep`.
+ */
+export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
+    if (process.platform === 'win32')
+        return { survivors: [] };
+    const survivors = await listGroupSurvivors(pgid);
+    if (survivors.length === 0)
+        return { survivors };
+    warn(`Harness process group ${String(pgid)} left ${String(survivors.length)} surviving ` +
+        `process(es) after exit — reaping the group. ${describeSurvivors(survivors)}`);
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        return { survivors };
+    }
+    await sweepDelay(graceMs);
+    let remaining = await listGroupSurvivors(pgid);
+    if (remaining.length > 0) {
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch {
+            return { survivors };
+        }
+        await sweepDelay(Math.min(200, graceMs));
+        remaining = await listGroupSurvivors(pgid);
+        if (remaining.length > 0) {
+            warn(`Process group ${String(pgid)} still has survivors after SIGKILL: ${describeSurvivors(remaining)}. ` +
+                'Inspect manually (ps -axo pid,ppid,time,command) and kill by PID.');
+        }
+        else {
+            verbose(`Process group ${String(pgid)} reaped after SIGKILL escalation.`);
+        }
+    }
+    else {
+        verbose(`Process group ${String(pgid)} reaped cleanly with SIGTERM.`);
+    }
+    return { survivors };
+}

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

@@ -29,6 +29,21 @@ export interface ExecOptions {
     env?: Record<string, string>;
     /** Timeout in milliseconds */
     timeout?: number;
+    /**
+     * POSIX: spawn the child as a process-group leader and route every kill
+     * (parent-signal forwarding, abort, escalation) to the whole GROUP, then
+     * sweep the group for survivors after close — so a harness that dies at
+     * startup cannot strand spinning `multiprocessing` workers (field
+     * incident: an orphaned Python spawn worker reparented to launchd and
+     * busy-spun at 100% CPU for ~26 days). Win32: tree-kill via
+     * `taskkill /T /F` on abort/signals only, no post-run sweep
+     * (best-effort). Default false — non-mach consumers are unaffected.
+     *
+     * NOTE for callers: a detached group leader does NOT receive terminal
+     * Ctrl+C; the exec layer installs its own group-aware signal forwarder
+     * whenever this option is set.
+     */
+    processGroup?: boolean;
 }
 /**
  * Executes a command and returns its output.

package/dist/src/utils/process.js

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process';
 import { constants as osConstants } from 'node:os';
 import { StringDecoder } from 'node:string_decoder';
 import { ExecTimeoutError } from '../errors/base.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.
 // Callers for whom truncation is unacceptable (e.g. the archive-safety preflight
@@ -115,12 +116,15 @@ export async function exec(command, args, options = {}) {
  */
 export async function execStream(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: { ...process.env, ...options.env },
             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) => {
@@ -133,11 +137,35 @@ export async function execStream(command, args, options = {}) {
             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) => {
+                killProcessTree(child, signal, usesProcessGroup);
+            })
+            : undefined;
         child.on('error', (error) => {
+            // Abort/startup failure: make sure a partially-started tree does not
+            // outlive the dispatch (a mach dying at startup used to strand
+            // multiprocessing workers).
+            if (options.processGroup === true) {
+                killProcessTree(child, 'SIGKILL', usesProcessGroup);
+            }
+            forwarder?.dispose();
             reject(toExecRejection(error, command, args, options.timeout));
         });
         child.on('close', (code, signal) => {
-            resolve(exitCodeFromClose(code, signal));
+            forwarder?.dispose();
+            const finish = () => {
+                resolve(exitCodeFromClose(code, signal));
+            };
+            if (groupPid !== undefined) {
+                sweepProcessGroup(groupPid).then(finish, finish);
+            }
+            else {
+                finish();
+            }
         });
     });
 }
@@ -199,24 +227,42 @@ export async function waitForActiveChildShutdown(timeoutMs) {
  */
 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: { ...process.env, ...options.env },
             stdio: 'inherit',
             signal: buildSignalFromTimeout(options.timeout),
+            detached: usesProcessGroup,
         });
+        const groupPid = usesProcessGroup ? child.pid : undefined;
         const graceMs = options.shutdownGraceMs ?? 1500;
-        const { dispose } = installGracefulShutdownForwarder(child, graceMs);
+        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();
-            closure.settle();
-            resolve(exitCodeFromClose(code, signal));
+            const finish = () => {
+                closure.settle();
+                resolve(exitCodeFromClose(code, signal));
+            };
+            if (groupPid !== undefined) {
+                sweepProcessGroup(groupPid).then(finish, finish);
+            }
+            else {
+                finish();
+            }
         });
     });
 }
@@ -228,14 +274,21 @@ export async function execInherit(command, args, options = {}) {
  * `close` and `error` handlers so the process does not accumulate signal
  * listeners across repeated spawns.
  */
-function installGracefulShutdownForwarder(child, graceMs) {
+function installGracefulShutdownForwarder(child, graceMs, killTarget) {
     let graceTimer;
     const forwarded = new Set();
+    const sendKill = (signal) => {
+        if (killTarget) {
+            killTarget(signal);
+            return;
+        }
+        child.kill(signal);
+    };
     const escalate = () => {
         if (child.exitCode !== null || child.signalCode !== null)
             return;
         try {
-            child.kill('SIGKILL');
+            sendKill('SIGKILL');
         }
         catch {
             // Child is already gone — nothing to do.
@@ -249,7 +302,7 @@ function installGracefulShutdownForwarder(child, graceMs) {
         }
         forwarded.add(signal);
         try {
-            child.kill('SIGTERM');
+            sendKill('SIGTERM');
         }
         catch {
             // If the child can't accept SIGTERM (already dead), nothing to do.
@@ -286,34 +339,52 @@ function installGracefulShutdownForwarder(child, graceMs) {
  */
 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: { ...process.env, ...options.env },
             stdio: ['inherit', 'pipe', 'pipe'],
             signal: buildSignalFromTimeout(options.timeout),
+            detached: usesProcessGroup,
         });
+        const groupPid = usesProcessGroup ? child.pid : undefined;
         const out = createStreamCollector(process.stdout);
         const err = createStreamCollector(process.stderr);
         child.stdout.on('data', out.onData);
         child.stderr.on('data', err.onData);
         const graceMs = options.shutdownGraceMs ?? 1500;
-        const { dispose } = installGracefulShutdownForwarder(child, graceMs);
+        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();
-            closure.settle();
-            resolve({
-                stdout: out.getText(),
-                stderr: err.getText(),
-                exitCode: exitCodeFromClose(code, signal),
-                stdoutTruncated: out.wasTruncated(),
-                stderrTruncated: err.wasTruncated(),
-            });
+            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();
+            }
         });
     });
 }
@@ -371,34 +442,7 @@ export async function execSmokeRun(command, args, options) {
         let graceTimer;
         let signalGraceTimer;
         const signalChildGroup = (signal) => {
-            if (child.exitCode !== null || child.signalCode !== null)
-                return;
-            const targetPid = child.pid;
-            if (targetPid === undefined)
-                return;
-            try {
-                if (usesProcessGroup) {
-                    // Negative PID routes to the process group, killing the Python
-                    // wrapper, the firefox it forked, and every content process
-                    // that inherited the group.
-                    process.kill(-targetPid, signal);
-                }
-                else {
-                    // No process group on Windows — taskkill /T walks the descendant
-                    // tree instead. Always forced (/F): there is no SIGTERM analogue,
-                    // so the grace window only exists on POSIX.
-                    spawn('taskkill', ['/pid', String(targetPid), '/T', '/F'], {
-                        stdio: 'ignore',
-                    }).on('error', () => {
-                        // taskkill unavailable — nothing more we can do beyond the
-                        // direct-child kill below.
-                    });
-                    child.kill(signal);
-                }
-            }
-            catch {
-                // Already gone. Nothing to do.
-            }
+            killProcessTree(child, signal, usesProcessGroup);
         };
         const deadlineTimer = setTimeout(() => {
             timedOut = true;

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

@@ -57,6 +57,11 @@ export declare function isArray(value: unknown): value is unknown[];
  * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
  */
 export declare function isValidFirefoxVersion(version: string): boolean;
+/**
+ * Validates a release-candidate build directory name.
+ * Accepts formats like "build1", "build2", "build12" (no leading zero).
+ */
+export declare function isValidFirefoxCandidate(candidate: string): boolean;
 /**
  * Validates a Firefox product string.
  * Accepts: firefox, firefox-esr, firefox-beta, firefox-devedition

package/dist/src/utils/validation.js

@@ -87,6 +87,13 @@ export function isValidFirefoxVersion(version) {
     // Beta: 147.0b1, 147.0b2
     return /^[1-9]\d{0,2}\.\d+(?:b[1-9]\d*|\.\d+(?:esr)?|esr)?$/.test(version);
 }
+/**
+ * Validates a release-candidate build directory name.
+ * Accepts formats like "build1", "build2", "build12" (no leading zero).
+ */
+export function isValidFirefoxCandidate(candidate) {
+    return /^build[1-9]\d{0,3}$/.test(candidate);
+}
 /**
  * Validates a Firefox product string.
  * Accepts: firefox, firefox-esr, firefox-beta, firefox-devedition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -73,9 +73,9 @@
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.23.0",
+    "knip": "6.26.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.4",
+    "prettier": "3.9.5",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",