@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/utils/options.js

@@ -1,14 +1,16 @@
-// SPDX-License-Identifier: EUPL-1.2
+import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { toError } from './errors.js';
 /**
  * Filters an object to only include keys whose values are not undefined.
- * Designed for use with exactOptionalPropertyTypes — the result can be
+ * Designed for use with exactOptionalPropertyTypes: the result can be
  * spread into typed option objects without assigning undefined to optional
  * properties.
  *
  * Constrained to `object`, not `Record<string, unknown>`: a named interface
  * has no index signature, so the narrower constraint rejects exactly the
  * annotations this helper is most useful with. Nothing in the body needs the
- * index signature — the key walk goes through `Object.keys`.
+ * index signature, since the key walk goes through `Object.keys`.
  *
  * @param obj - Object to filter
  * @returns The same object with every `undefined`-valued key removed
@@ -22,15 +24,12 @@ export function pickDefined(obj) {
     }
     return result;
 }
-import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { toError } from './errors.js';
 /**
  * Wraps an option-argument parser so its failures surface through
  * commander's own invalid-argument channel.
  *
  * Commander only treats errors whose `code` is `'commander.invalidArgument'`
- * as argument-validation failures; anything else re-throws out of
+ * as argument-validation failures. Anything else re-throws out of
  * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
  * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
  * That covers a plain Error, a `GeneralError`, and even a FireForge
@@ -88,12 +87,12 @@ function parseWaitLockSeconds(raw) {
  * The standing wait budget from {@link WAIT_LOCK_ENV_VAR}, or undefined when
  * it is unset or empty.
  *
- * Exists because a wait budget is a property of the SESSION, not of the
+ * Exists because a wait budget is a property of the session, not of the
  * invocation: a checkout worked by several concurrent agent sessions has a
  * held lock as its normal state, and an unattended loop would otherwise have
- * to thread `--wait-lock` through every command it issues — the one place
- * it is easiest to forget, and the failure only shows up once the loop has
- * already produced a tail of refusals.
+ * to thread `--wait-lock` through every command it issues. That is the one
+ * place it is easiest to forget, and the failure only shows up once the loop
+ * has already produced a tail of refusals.
  *
  * An unusable value is a usage error rather than a silent fall-back to
  * fail-fast: the operator set it precisely because they did not want to
@@ -106,7 +105,7 @@ function waitLockSecondsFromEnv() {
     }
     const parsed = parseWaitLockSeconds(raw);
     if (parsed === undefined) {
-        throw new InvalidArgumentError(`${WAIT_LOCK_ENV_VAR} must be an integer in ${String(MIN_WAIT_LOCK_SECONDS)}..${String(MAX_WAIT_LOCK_SECONDS)} (got "${raw}")`, WAIT_LOCK_ENV_VAR);
+        throw new InvalidArgumentError(`${WAIT_LOCK_ENV_VAR} must be an integer in ${MIN_WAIT_LOCK_SECONDS}..${MAX_WAIT_LOCK_SECONDS} (got "${raw}")`, WAIT_LOCK_ENV_VAR);
     }
     return parsed;
 }
@@ -125,8 +124,8 @@ function waitLockSecondsFromEnv() {
  * Accepts the raw string too, so it doubles as the option's arg parser (wrap
  * with {@link commanderArgParser} so failures surface through commander's
  * invalid-argument channel). In that role the value is never `undefined`, so
- * the environment fallback cannot leak into flag PARSING — only into flag
- * ABSENCE, which is where it belongs.
+ * the environment fallback cannot leak into flag parsing, only into flag
+ * absence, which is where it belongs.
  */
 export function resolveWaitLockSeconds(value) {
     if (value === undefined || value === false) {
@@ -140,25 +139,25 @@ export function resolveWaitLockSeconds(value) {
     }
     const parsed = parseWaitLockSeconds(value);
     if (parsed === undefined) {
-        throw new GeneralError(`--wait-lock must be an integer in ${String(MIN_WAIT_LOCK_SECONDS)}..${String(MAX_WAIT_LOCK_SECONDS)} (got "${value}")`);
+        throw new GeneralError(`--wait-lock must be an integer in ${MIN_WAIT_LOCK_SECONDS}..${MAX_WAIT_LOCK_SECONDS} (got "${value}")`);
     }
     return parsed;
 }
 /**
- * The session-wide wait budget in MILLISECONDS, or undefined when none is
+ * The session-wide wait budget in milliseconds, or undefined when none is
  * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
  *
- * Exists for the SECONDARY locks a command takes after the one its
+ * Exists for the secondary locks a command takes after the one its
  * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
- * session lock and then `.fireforge/furnace.lock`; only the first had a
+ * session lock and then `.fireforge/furnace.lock`. Only the first had a
  * budget, so a contended deploy died on the file lock's fixed 30 s while
  * its operator believed a much larger budget was in force. Threading the
- * flag reaches the three furnace commands that declare it — this reaches
+ * flag reaches the three furnace commands that declare it. This reaches
  * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
  * `override`, `chrome-doc`, …), which have no flag to thread but are just
  * as contended.
  *
- * Deliberately env-only: a flag belongs to one invocation and is passed
+ * Env-only: a flag belongs to one invocation and is passed
  * explicitly where it applies, while the environment is exactly the place a
  * session-wide default is expressed. An explicit budget at a call site
  * always wins over this.
@@ -170,12 +169,12 @@ export function sessionWaitLockMs() {
     return seconds === undefined ? undefined : seconds * 1000;
 }
 /**
- * Registers `--wait-lock [seconds]` on a command that takes NO lock, so a
+ * Registers `--wait-lock [seconds]` on a command that takes no lock, so a
  * scripted sequence can blanket-append the flag without hitting a usage
- * error — a command that rejects it with "unknown option" kills the whole
+ * error. A command that rejects it with "unknown option" kills the whole
  * sequence with a usage error instead of a lock message.
  *
- * The flag is accepted and ignored here — never silently repurposed — and
+ * The flag is accepted and ignored here, never silently repurposed, and
  * the help text says so, so nobody reads its presence as evidence that this
  * command waits for anything.
  *
@@ -191,7 +190,7 @@ function addAcceptedWaitLockOption(command) {
  * CLI wiring to add the accept-and-ignore variant only where the honoring
  * one is absent.
  */
-export function hasWaitLockOption(command) {
+function hasWaitLockOption(command) {
     return command.options.some((option) => option.long === '--wait-lock');
 }
 /**
@@ -210,12 +209,12 @@ export function ensureWaitLockOptionEverywhere(command) {
  * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
  * command (the engine session lock for engine-mutating commands, the patch
  * directory lock for queue-mutating ones). The parsed option value is `true`
- * for the bare flag or a validated integer; feed it through
+ * for the bare flag or a validated integer. Feed it through
  * {@link resolveWaitLockSeconds} at the call site to obtain the
  * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
  *
- * A command can take MORE than one lock — a furnace mutation takes the
- * engine session lock and then `.fireforge/furnace.lock` — and the budget
+ * A command can take more than one lock (a furnace mutation takes the
+ * engine session lock and then `.fireforge/furnace.lock`) and the budget
  * has to reach all of them or the flag is a half-truth. The secondary locks
  * read the session budget through {@link sessionWaitLockMs} rather than
  * having it threaded to every call site.

package/dist/src/utils/package-root.js

@@ -3,21 +3,12 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getNodeErrorCode, toError } from './errors.js';
+import { parseObject } from './parse.js';
 import { isObject } from './validation.js';
-function validatePackageMetadata(data, filePath) {
-    if (typeof data !== 'object' || data === null) {
-        throw new Error(`Invalid package metadata in ${filePath}: expected an object`);
-    }
-    const name = 'name' in data ? data.name : undefined;
-    const version = 'version' in data ? data.version : undefined;
-    if (typeof name !== 'string' || typeof version !== 'string') {
-        throw new Error(`Invalid package metadata in ${filePath}: expected string "name" and "version" fields`);
-    }
-    return { name, version, bin: 'bin' in data ? data.bin : undefined };
-}
 function readPackageMetadata(filePath) {
     const raw = readFileSync(filePath, 'utf-8');
-    return validatePackageMetadata(JSON.parse(raw), filePath);
+    const parsed = parseObject(JSON.parse(raw), 'package.json');
+    return { name: parsed.string('name'), version: parsed.string('version'), bin: parsed.raw('bin') };
 }
 let cachedPackageRoot;
 /**
@@ -45,8 +36,8 @@ export function getPackageRoot() {
             }
         }
         catch (error) {
-            // Absent package.json: keep walking. A package.json that EXISTS but
-            // fails to parse is a different animal — walking past it could bind
+            // Absent package.json: keep walking. A package.json that exists but
+            // fails to parse is a different case: walking past it could bind
             // to a wrong ancestor package (any parent exposing bin.fireforge) or
             // end in the unhelpful generic "could not locate" error, hiding the
             // actual syntax problem.

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

@@ -7,13 +7,13 @@ export declare function normalizePathSlashes(path: string): string;
  * (`browser/base/content/foo.js`).
  *
  * The match is case-insensitive because default macOS and Windows
- * filesystems treat `Engine/` and `engine/` as the same directory; a literal
- * lowercase-only check leaves `mach` and the manifest writers resolving
- * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * filesystems treat `Engine/` and `engine/` as the same directory. A
+ * literal lowercase-only check leaves `mach` and the manifest writers
+ * resolving against a wrongly-cased prefix. Leading whitespace is ignored so
  * tab-completed inputs do not slip past the strip.
  *
  * The return value is trimmed of that leading whitespace when the prefix
- * matched, and otherwise passed through verbatim — callers that care about
+ * matched, and otherwise passed through verbatim. Callers that care about
  * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user

package/dist/src/utils/paths.js

@@ -21,13 +21,13 @@ export function normalizePathSlashes(path) {
  * (`browser/base/content/foo.js`).
  *
  * The match is case-insensitive because default macOS and Windows
- * filesystems treat `Engine/` and `engine/` as the same directory; a literal
- * lowercase-only check leaves `mach` and the manifest writers resolving
- * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * filesystems treat `Engine/` and `engine/` as the same directory. A
+ * literal lowercase-only check leaves `mach` and the manifest writers
+ * resolving against a wrongly-cased prefix. Leading whitespace is ignored so
  * tab-completed inputs do not slip past the strip.
  *
  * The return value is trimmed of that leading whitespace when the prefix
- * matched, and otherwise passed through verbatim — callers that care about
+ * matched, and otherwise passed through verbatim. Callers that care about
  * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user

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

@@ -2,10 +2,6 @@
  * Supported operating system platforms.
  */
 export type Platform = 'darwin' | 'linux' | 'win32';
-/**
- * Supported CPU architectures.
- */
-export type Arch = 'x64' | 'arm64';
 /**
  * Gets the current operating system platform.
  * @throws Error if running on an unsupported platform

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

@@ -1,15 +1,15 @@
 /**
  * Process-group kill and post-run sweep helpers for the exec layer. 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.
+ * out of `process.ts` to keep that file within the per-file line budget.
+ * Spawn-based rather than `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
+ * Sends `signal` to the child's whole tree: the process group on POSIX
+ * (negative-PID kill, which 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).
  *
  * A failed group kill falls through to a direct `child.kill` on POSIX too:
@@ -19,7 +19,7 @@ import { type ChildProcess } from 'node:child_process';
  */
 export declare function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, usesProcessGroup: boolean): void;
 /** One process still alive in a swept group. */
-export interface ProcessGroupSurvivor {
+interface ProcessGroupSurvivor {
     /** PID, or -1 when pgrep was unavailable and only a liveness probe ran. */
     pid: number;
     /** Command line (pgrep -lf output), best-effort. */
@@ -30,9 +30,10 @@ export interface ProcessGroupSurvivor {
  * 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.
+ * 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[];
 }>;
+export {};

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

@@ -1,18 +1,19 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Process-group kill and post-run sweep helpers for the exec layer. 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.
+ * out of `process.ts` to keep that file within the per-file line budget.
+ * Spawn-based rather than `exec`-based so the two modules do not import
+ * each other cyclically.
  */
 import { spawn } from 'node:child_process';
 import { getNodeErrorCode } from './errors.js';
 import { verbose, warn } from './logger.js';
+import { sleep } from './sleep.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
+ * Sends `signal` to the child's whole tree: the process group on POSIX
+ * (negative-PID kill, which 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).
  *
  * A failed group kill falls through to a direct `child.kill` on POSIX too:
@@ -37,19 +38,19 @@ export function killProcessTree(child, signal, usesProcessGroup) {
             catch {
                 // ESRCH/EPERM: the group is gone, or was never created because the
                 // platform ignored `detached`. Signal the direct child rather than
-                // doing nothing — it may well still be alive. Without this
+                // doing nothing, since it may well still be alive. Without this
                 // fall-through a failed group kill left the child running.
                 child.kill(signal);
             }
         }
         else {
-            // No process group on Windows — taskkill /T walks the descendant
+            // No process group on Windows, so 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
+                // taskkill unavailable, so nothing more we can do beyond the
                 // direct-child kill below.
             });
             child.kill(signal);
@@ -61,18 +62,6 @@ export function killProcessTree(child, signal, usesProcessGroup) {
 }
 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").
@@ -115,10 +104,10 @@ async function listGroupSurvivors(pgid) {
         return [{ pid: -1, command: 'unknown (pgrep unavailable; group still has live members)' }];
     }
     catch (error) {
-        // Same errno semantics as `isProcessAlive` (which cannot be called here —
-        // it probes a single positive pid): only ESRCH proves the group is gone.
-        // EPERM means it exists under another uid, and an unrecognized failure is
-        // not evidence of absence — report survivors in both cases.
+        // Same errno semantics as `isProcessAlive` (which cannot be called here,
+        // since it probes a single positive pid): only ESRCH proves the group is
+        // gone. EPERM means it exists under another uid, and an unrecognized
+        // failure is not evidence of absence, so report survivors in both cases.
         if (getNodeErrorCode(error) === 'ESRCH')
             return [];
         return [{ pid: -1, command: 'unknown (pgrep unavailable; group liveness probe denied)' }];
@@ -130,7 +119,7 @@ function describeSurvivors(list) {
         const tag = MULTIPROCESSING_WORKER_PATTERN.test(s.command)
             ? ' [multiprocessing worker — the known busy-spin orphan shape]'
             : '';
-        return `PID ${String(s.pid)}: ${s.command}${tag}`;
+        return `PID ${s.pid}: ${s.command}${tag}`;
     })
         .join('; ');
 }
@@ -139,7 +128,7 @@ function describeSurvivors(list) {
  * 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.
+ * 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) {
@@ -148,17 +137,23 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
     const survivors = await listGroupSurvivors(pgid);
     if (survivors.length === 0)
         return { survivors };
-    warn(`Harness process group ${String(pgid)} left ${String(survivors.length)} surviving ` +
+    warn(`Harness process group ${pgid} left ${survivors.length} surviving ` +
         `process(es) after exit — reaping the group. ${describeSurvivors(survivors)}`);
     try {
         process.kill(-pgid, 'SIGTERM');
     }
     catch {
-        // The group vanished between the listing and the signal — nothing left to
-        // escalate against, so report the survivors collected so far.
+        // The group vanished between the listing and the signal, so there is
+        // nothing left to escalate against. Report the survivors collected so far.
         return { survivors };
     }
-    await sweepDelay(graceMs);
+    // Ref'd (sleep's default): this wait sits between the group
+    // SIGTERM and the post-grace re-list/SIGKILL escalation, awaited from a
+    // child 'close' handler after the signal forwarder is disposed. With an
+    // unref'd timer nothing keeps the event loop alive, so Node could exit
+    // mid-grace and skip the escalation entirely. Healthy runs never reach
+    // here (sweepProcessGroup early-returns on zero survivors).
+    await sleep(graceMs);
     let remaining = await listGroupSurvivors(pgid);
     if (remaining.length > 0) {
         try {
@@ -169,18 +164,24 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
             // nothing to signal.
             return { survivors };
         }
-        await sweepDelay(Math.min(200, graceMs));
+        // Ref'd (sleep's default): this wait sits between the group
+        // SIGTERM and the post-grace re-list/SIGKILL escalation, awaited from a
+        // child 'close' handler after the signal forwarder is disposed. With an
+        // unref'd timer nothing keeps the event loop alive, so Node could exit
+        // mid-grace and skip the escalation entirely. Healthy runs never reach
+        // here (sweepProcessGroup early-returns on zero survivors).
+        await sleep(Math.min(200, graceMs));
         remaining = await listGroupSurvivors(pgid);
         if (remaining.length > 0) {
-            warn(`Process group ${String(pgid)} still has survivors after SIGKILL: ${describeSurvivors(remaining)}. ` +
+            warn(`Process group ${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.`);
+            verbose(`Process group ${pgid} reaped after SIGKILL escalation.`);
         }
     }
     else {
-        verbose(`Process group ${String(pgid)} reaped cleanly with SIGTERM.`);
+        verbose(`Process group ${pgid} reaped cleanly with SIGTERM.`);
     }
     return { survivors };
 }