@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -11,21 +11,21 @@ export interface ExecResult {
     exitCode: number;
     /**
      * True when `stdout` was cut off at the 50 MB collector cap. Optional so
-     * existing mocks stay valid; absent means "not truncated". Callers that
+     * existing mocks stay valid. Absent means "not truncated". Callers that
      * feed the output into safety decisions (e.g. archive-listing scans) must
-     * treat `true` as a hard failure — a truncated listing looks exactly like
-     * a complete one otherwise.
+     * treat `true` as a hard failure, since a truncated listing otherwise
+     * looks exactly like a complete one.
      */
     stdoutTruncated?: boolean;
     /** True when `stderr` was cut off at the 50 MB collector cap. See {@link ExecResult.stdoutTruncated}. */
     stderrTruncated?: boolean;
 }
 /**
- * Options for plain `exec()` — the pipe-capturing, non-grouped, non-mirrored
+ * Options for plain `exec()`, the pipe-capturing, non-grouped, non-mirrored
  * path. The other wrappers extend this with the fields they actually read:
  * `processGroup` lives in {@link ProcessGroupOptions}, `mirror` in
  * {@link MirrorOptions}. Neither belongs here because `exec()` reads
- * neither — a field the type accepts but the function ignores is a trap
+ * neither, and a field the type accepts but the function ignores is a trap
  * (the caller believes it got a process group, and never did).
  */
 export interface ExecOptions {
@@ -34,13 +34,13 @@ export interface ExecOptions {
     /** Environment variables */
     env?: Record<string, string>;
     /**
-     * Environment variables to REMOVE from the child's inherited environment,
+     * Environment variables to remove from the child's inherited environment,
      * applied after {@link ExecOptions.env} is merged over `process.env`.
      *
      * Needed because `env` can only add or overwrite, and some variables are
-     * read for their PRESENCE — mozbuild's `is_running_under_coding_agent()`
+     * read only for their presence: mozbuild's `is_running_under_coding_agent()`
      * keys on `CLAUDECODE`, so setting it empty would not unset it. An
-     * explicit delete says what it means; relying on Node dropping
+     * explicit delete says what it means. Relying on Node dropping
      * `undefined`-valued env entries would be a semantics gamble at a layer
      * that must not have any.
      */
@@ -59,7 +59,7 @@ export interface MirrorOptions {
      * path, or an operator-supplied `--capture-console` file on the smoke
      * path. Lets a caller tee the live output somewhere else (a run log)
      * without a second per-chunk hook. Writes happen inline with capture and
-     * the stream is NOT closed here — the caller owns its lifecycle.
+     * the stream is not closed here. The caller owns its lifecycle.
      */
     mirror?: {
         stdout?: NodeJS.WritableStream;
@@ -73,15 +73,15 @@ export interface MirrorOptions {
 export interface ProcessGroupOptions {
     /**
      * 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
+     * (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, which reparent
      * to launchd and busy-spin at 100% CPU indefinitely. Win32: tree-kill via
      * `taskkill /T /F` on abort/signals only, no post-run sweep
-     * (best-effort). Default false — non-mach consumers are unaffected.
+     * (best-effort). Default false, so 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
+     * 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;
@@ -121,7 +121,7 @@ export declare function execStream(command: string, args: string[], options?: St
  * Exported for the one legitimate spawn outside this module:
  * `core/marionette-preflight.ts` keeps its own `spawn` because it needs the
  * live `ChildProcess` mid-run, returns while the child is still running, and
- * aborts on a TCP byte rather than a deadline — none of which any wrapper
+ * aborts on a TCP byte rather than a deadline, none of which any wrapper
  * here can express. It still needs the shutdown contract, and a second
  * hand-rolled copy is what lets a Ctrl+C orphan the whole mach → Firefox
  * tree.
@@ -130,7 +130,7 @@ export declare function execStream(command: string, args: string[], options?: St
  * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
  * wait for, and returns the handle that deregisters it.
  *
- * @returns `settle()` — call from both the child's `close` and `error`
+ * @returns `settle()`. Call from both the child's `close` and `error`
  *   handlers so a dead child never holds the shutdown wait open
  */
 export declare function trackChildClosure(): {
@@ -157,7 +157,7 @@ export interface InheritCaptureOptions extends InheritOptions, MirrorOptions {
  * Graceful shutdown: when the FireForge process receives SIGINT/SIGTERM, the
  * signal is forwarded to the child as SIGTERM and a short grace timer (default
  * 1500ms) runs before escalating to SIGKILL. A second matching signal during
- * the grace period triggers an immediate SIGKILL — matching the usual
+ * the grace period triggers an immediate SIGKILL, matching the usual
  * "hit Ctrl-C again to force-quit" UX. Without this, Firefox's AsyncShutdown
  * / profileBeforeChange blockers (which flush in-memory state to disk) can be
  * racing the OS child-exit path, losing the last few seconds of edits.
@@ -170,9 +170,9 @@ export interface InheritCaptureOptions extends InheritOptions, MirrorOptions {
 export declare function execInherit(command: string, args: string[], options?: InheritOptions): Promise<number>;
 /**
  * Wires parent-process SIGINT/SIGTERM to a child: first signal → child.kill
- * (SIGTERM) + grace timer; second matching signal → immediate SIGKILL; grace
- * timer expiry → SIGKILL. Returns a `dispose()` that clears the listeners and
- * any outstanding timer. Callers must invoke `dispose()` from both the child's
+ * (SIGTERM) + grace timer. A second matching signal → immediate SIGKILL.
+ * Grace timer expiry → SIGKILL. Returns a `dispose()` that clears the
+ * listeners and any outstanding timer. Callers must invoke `dispose()` from both the child's
  * `close` and `error` handlers so the process does not accumulate signal
  * listeners across repeated spawns.
  */
@@ -193,28 +193,28 @@ export type SmokeLineCallback = (line: string) => void;
 /**
  * Options for {@link execSmokeRun}.
  *
- * Deliberately omits `ExecOptions.timeout`: the smoke run's only deadline is
+ * Omits `ExecOptions.timeout`: the smoke run's only deadline is
  * {@link SmokeRunOptions.smokeTimeoutMs}, which signals the whole process
- * group. Inheriting `timeout` is a leaky trap — accepted by the type but
- * silently ignored, so a caller setting it gets no deadline at all.
+ * group. Inheriting `timeout` would be a leaky trap, accepted by the type
+ * but silently ignored, so a caller setting it gets no deadline at all.
  *
  * {@link ProcessGroupOptions} is not mixed in for the same reason: a smoke
- * run is ALWAYS detached on POSIX (`usesProcessGroup` is derived from
+ * run is always detached on POSIX (`usesProcessGroup` is derived from
  * `process.platform` alone), so the field would be accepted and never read.
  */
 interface SmokeRunOptions extends Omit<ExecOptions, 'timeout'>, MirrorOptions {
     /**
      * Hard deadline in milliseconds. When it elapses the child process
      * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned
-     * {@link SmokeRunResult.timedOut} is `true` when the deadline fires —
-     * callers treat that as a clean smoke window (no child-driven error),
-     * not a failure.
+     * {@link SmokeRunResult.timedOut} is `true` when the deadline fires.
+     * Callers treat that as a clean smoke window (no child-driven error)
+     * rather than a failure.
      */
     smokeTimeoutMs: number;
     /**
      * Grace period between SIGTERM and SIGKILL when the deadline fires.
      * Defaults to 10000 ms because Firefox's AsyncShutdown and
-     * profileBeforeChange blockers can take ~5–10 s to flush in-memory
+     * profileBeforeChange blockers can take roughly 5 to 10 s to flush in-memory
      * state. A shorter grace risks corrupting the dev profile mid-quit.
      */
     killGraceMs?: number;
@@ -228,9 +228,9 @@ export interface SmokeRunResult extends ExecResult {
     /**
      * `true` when the smoke deadline fired and we SIGTERMed the child
      * ourselves. Callers that want to distinguish "smoke window elapsed
-     * cleanly" from "child exited on its own" check this flag — the
+     * cleanly" from "child exited on its own" check this flag: the
      * `exitCode` in the timedOut path is almost always 143 (SIGTERM) and
-     * should NOT be treated as a child-driven failure.
+     * should not be treated as a child-driven failure.
      */
     timedOut: boolean;
 }
@@ -249,9 +249,10 @@ export interface SmokeRunResult extends ExecResult {
  *
  * Windows fallback: `detached: true` does not create an equivalent group
  * there, so we kill the descendant tree with `taskkill /pid <pid> /T /F`
- * instead. taskkill has no graceful-signal equivalent — both the deadline
- * and the grace re-invocation are forced kills, so Windows children get
- * no shutdown window (best-effort; Windows is untested, see README).
+ * instead. taskkill has no graceful-signal equivalent, so both the deadline
+ * and the grace re-invocation are forced kills and Windows children get
+ * no shutdown window. This is best-effort and Windows is untested, see
+ * README.
  * `child.kill()` is still sent as a direct-child fallback in case
  * taskkill itself is unavailable.
  */

package/dist/src/utils/process.js

@@ -6,7 +6,7 @@ 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)
+// 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
 // scanning a full `tar -tvf` listing) must check `wasTruncated` and fail hard.
@@ -67,7 +67,7 @@ function toExecRejection(error, command, args, timeout, output) {
 /**
  * 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
+ * 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) {
@@ -131,9 +131,9 @@ export async function exec(command, args, options = {}) {
  * 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.
+ * SIGKILL escalation could not finish before the parent exited. That was 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.
@@ -155,7 +155,7 @@ async function spawnTracked(spec) {
         });
         const groupPid = usesProcessGroup ? child.pid : undefined;
         spec.attach?.(child);
-        // Group-aware kills route to the whole tree; a non-group child is killed
+        // 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) => {
@@ -207,7 +207,7 @@ export async function execStream(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.
+        // is set. A plain streamed child does not get one.
         forwardWithoutProcessGroup: false,
         spawnChild: (base) => spawn(command, args, { ...base, stdio: ['ignore', 'pipe', 'pipe'] }),
         attach: (child) => {
@@ -243,7 +243,7 @@ const activeChildClosures = new Set();
  * Exported for the one legitimate spawn outside this module:
  * `core/marionette-preflight.ts` keeps its own `spawn` because it needs the
  * live `ChildProcess` mid-run, returns while the child is still running, and
- * aborts on a TCP byte rather than a deadline — none of which any wrapper
+ * aborts on a TCP byte rather than a deadline, none of which any wrapper
  * here can express. It still needs the shutdown contract, and a second
  * hand-rolled copy is what lets a Ctrl+C orphan the whole mach → Firefox
  * tree.
@@ -252,7 +252,7 @@ const activeChildClosures = new Set();
  * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
  * wait for, and returns the handle that deregisters it.
  *
- * @returns `settle()` — call from both the child's `close` and `error`
+ * @returns `settle()`. Call from both the child's `close` and `error`
  *   handlers so a dead child never holds the shutdown wait open
  */
 export function trackChildClosure() {
@@ -291,7 +291,7 @@ export async function waitForActiveChildShutdown(timeoutMs) {
  * Graceful shutdown: when the FireForge process receives SIGINT/SIGTERM, the
  * signal is forwarded to the child as SIGTERM and a short grace timer (default
  * 1500ms) runs before escalating to SIGKILL. A second matching signal during
- * the grace period triggers an immediate SIGKILL — matching the usual
+ * the grace period triggers an immediate SIGKILL, matching the usual
  * "hit Ctrl-C again to force-quit" UX. Without this, Firefox's AsyncShutdown
  * / profileBeforeChange blockers (which flush in-memory state to disk) can be
  * racing the OS child-exit path, losing the last few seconds of edits.
@@ -314,9 +314,9 @@ export async function execInherit(command, args, options = {}) {
 }
 /**
  * Wires parent-process SIGINT/SIGTERM to a child: first signal → child.kill
- * (SIGTERM) + grace timer; second matching signal → immediate SIGKILL; grace
- * timer expiry → SIGKILL. Returns a `dispose()` that clears the listeners and
- * any outstanding timer. Callers must invoke `dispose()` from both the child's
+ * (SIGTERM) + grace timer. A second matching signal → immediate SIGKILL.
+ * Grace timer expiry → SIGKILL. Returns a `dispose()` that clears the
+ * listeners and any outstanding timer. Callers must invoke `dispose()` from both the child's
  * `close` and `error` handlers so the process does not accumulate signal
  * listeners across repeated spawns.
  */
@@ -337,7 +337,7 @@ export function installGracefulShutdownForwarder(child, graceMs, killTarget) {
             sendKill('SIGKILL');
         }
         catch {
-            // Child is already gone — nothing to do.
+            // Child is already gone, nothing to do.
         }
     };
     const handleSignal = (signal) => {
@@ -422,9 +422,10 @@ export async function execInheritCapture(command, args, options = {}) {
  *
  * Windows fallback: `detached: true` does not create an equivalent group
  * there, so we kill the descendant tree with `taskkill /pid <pid> /T /F`
- * instead. taskkill has no graceful-signal equivalent — both the deadline
- * and the grace re-invocation are forced kills, so Windows children get
- * no shutdown window (best-effort; Windows is untested, see README).
+ * instead. taskkill has no graceful-signal equivalent, so both the deadline
+ * and the grace re-invocation are forced kills and Windows children get
+ * no shutdown window. This is best-effort and Windows is untested, see
+ * README.
  * `child.kill()` is still sent as a direct-child fallback in case
  * taskkill itself is unavailable.
  */
@@ -473,8 +474,8 @@ export async function execSmokeRun(command, args, options) {
         }, options.smokeTimeoutMs);
         deadlineTimer.unref();
         // Forward parent SIGINT/SIGTERM to the whole child process group. The
-        // smoke child is a group leader (detached), so it does NOT receive the
-        // terminal's Ctrl+C SIGINT — without this forwarder, the parent exits
+        // smoke child is a group leader (detached), so it does not receive the
+        // terminal's Ctrl+C SIGINT. Without this forwarder, the parent exits
         // and the entire mach → firefox tree is orphaned. Second signal (or
         // grace expiry) escalates to a group SIGKILL.
         const forwardedSignals = new Set();

package/dist/src/utils/ps-duration.d.ts

@@ -3,9 +3,9 @@
  *
  * Two different columns share one grammar, which is why this lives apart
  * from either consumer: `time=` (accumulated CPU) and `etime=` (elapsed
- * wall clock). Reading them with one parser is deliberate — a second
- * hand-rolled copy is how the two would drift, and the darwin dialect is
- * the half that is easy to get wrong.
+ * wall clock). One parser handles both: a second hand-rolled copy is how
+ * the two would drift, and the darwin dialect is the half that is easy to
+ * get wrong.
  *
  * Dialects:
  *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
@@ -13,7 +13,7 @@
  *     wrapping (e.g. `38412:07.55`)
  *
  * Returns `NaN` for anything else, so callers must treat an unrecognized
- * shape as "unknown" rather than as zero — a browser reported as 0 seconds
+ * shape as "unknown" rather than as zero. A browser reported as 0 seconds
  * old would be exactly the wrong attribution.
  */
 /**

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

@@ -4,9 +4,9 @@
  *
  * Two different columns share one grammar, which is why this lives apart
  * from either consumer: `time=` (accumulated CPU) and `etime=` (elapsed
- * wall clock). Reading them with one parser is deliberate — a second
- * hand-rolled copy is how the two would drift, and the darwin dialect is
- * the half that is easy to get wrong.
+ * wall clock). One parser handles both: a second hand-rolled copy is how
+ * the two would drift, and the darwin dialect is the half that is easy to
+ * get wrong.
  *
  * Dialects:
  *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
@@ -14,7 +14,7 @@
  *     wrapping (e.g. `38412:07.55`)
  *
  * Returns `NaN` for anything else, so callers must treat an unrecognized
- * shape as "unknown" rather than as zero — a browser reported as 0 seconds
+ * shape as "unknown" rather than as zero. A browser reported as 0 seconds
  * old would be exactly the wrong attribution.
  */
 /**
@@ -34,14 +34,14 @@ export function parsePsDuration(value) {
     }
     const parts = rest.split(':');
     if (parts.length === 3) {
-        // hh:mm:ss (linux; seconds may not carry fractions but tolerate them)
+        // hh:mm:ss on linux. Seconds may not carry fractions but tolerate them.
         const [h, m, s] = parts.map(Number);
         if ([h, m, s].some((n) => Number.isNaN(n)))
             return NaN;
         return days * 86400 + (h ?? 0) * 3600 + (m ?? 0) * 60 + (s ?? 0);
     }
     if (parts.length === 2) {
-        // mm:ss.cc (darwin — the minutes field accumulates without wrapping)
+        // mm:ss.cc on darwin. The minutes field accumulates without wrapping.
         const [m, s] = parts.map(Number);
         if ([m, s].some((n) => Number.isNaN(n)))
             return NaN;

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

@@ -9,16 +9,16 @@ export declare function hasRawCssColors(content: string): boolean;
 /**
  * Strips JS single-line and multi-line comments from source code, replacing
  * comment bytes with spaces (newlines inside block comments are kept) so
- * both character offsets AND line numbers are preserved. String literals are
+ * both character offsets and line numbers are preserved. String literals are
  * preserved intact.
  *
- * Uses acorn's tokenizer, which understands regex literals — a pure-regex
+ * Uses acorn's tokenizer, which understands regex literals. A pure-regex
  * implementation does not model them, so two adjacent slashes inside a regex
  * (the tail of `/https?:\/\//`) read as a `//` line comment and the rest of
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. Firefox chrome sources contain preprocessor directives (`#ifdef`)
- * and other constructs acorn cannot tokenize; those fall back to the legacy
- * regex strip, which handles strings but NOT regex literals.
+ * and other constructs acorn cannot tokenize. Those fall back to the legacy
+ * regex strip, which handles strings but not regex literals.
  */
 export declare function stripJsComments(source: string): string;
 /**

package/dist/src/utils/regex.js

@@ -25,16 +25,16 @@ export function hasRawCssColors(content) {
 /**
  * Strips JS single-line and multi-line comments from source code, replacing
  * comment bytes with spaces (newlines inside block comments are kept) so
- * both character offsets AND line numbers are preserved. String literals are
+ * both character offsets and line numbers are preserved. String literals are
  * preserved intact.
  *
- * Uses acorn's tokenizer, which understands regex literals — a pure-regex
+ * Uses acorn's tokenizer, which understands regex literals. A pure-regex
  * implementation does not model them, so two adjacent slashes inside a regex
  * (the tail of `/https?:\/\//`) read as a `//` line comment and the rest of
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. Firefox chrome sources contain preprocessor directives (`#ifdef`)
- * and other constructs acorn cannot tokenize; those fall back to the legacy
- * regex strip, which handles strings but NOT regex literals.
+ * and other constructs acorn cannot tokenize. Those fall back to the legacy
+ * regex strip, which handles strings but not regex literals.
  */
 export function stripJsComments(source) {
     const comments = [];
@@ -47,7 +47,7 @@ export function stripJsComments(source) {
                 comments.push({ start, end });
             },
         });
-        // Drive the tokenizer to EOF; we only care about onComment callbacks.
+        // Drive the tokenizer to EOF. We only care about onComment callbacks.
         for (;;) {
             const token = t.getToken();
             if (token.type === acornTokTypes.eof)
@@ -71,8 +71,8 @@ export function stripJsComments(source) {
 }
 /**
  * Legacy pure-regex comment strip, used only when acorn cannot tokenize
- * the source (preprocessor directives, syntax errors). Strings survive;
- * regex literals are NOT modeled, so `//` inside a regex blanks the rest
+ * the source (preprocessor directives, syntax errors). Strings survive.
+ * Regex literals are not modeled, so `//` inside a regex blanks the rest
  * of the line.
  */
 function stripJsCommentsLegacy(source) {

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

@@ -4,18 +4,18 @@
  * 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 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.
+ * 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).

package/dist/src/utils/sleep.js

@@ -5,18 +5,18 @@
  * 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 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.
+ * 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).

package/dist/src/utils/stdio-drain.d.ts

@@ -1,16 +1,16 @@
 /**
  * Bounded stdio drain for delayed process exits.
  *
- * `process.exit()` discards whatever is still queued in an async writable —
- * and stdout IS async when it is a pipe, with a 64 KiB kernel buffer on
+ * `process.exit()` discards whatever is still queued in an async writable,
+ * and stdout is async when it is a pipe, with a 64 KiB kernel buffer on
  * macOS/Linux. The observed failure: `status --json --fail-on` writes a
  * 176 KB payload, the refusal makes `bin/fireforge.ts` exit non-zero, and a
  * piped consumer receives exactly 65 536 bytes. The bin entry point awaits
- * this helper before every delayed exit; the helper itself never calls
+ * this helper before every delayed exit. The helper itself never calls
  * `process.exit` (the process-boundary test keeps that a bin-only right).
  */
 /**
- * The structural slice of `Writable` the drain wait needs — accepted instead
+ * The structural slice of `Writable` the drain wait needs. Accepted instead
  * of `NodeJS.WriteStream` so unit tests can drive synthetic streams.
  */
 export interface DrainableStream {
@@ -21,8 +21,8 @@ export interface DrainableStream {
     off(event: 'drain' | 'error' | 'close', listener: () => void): unknown;
 }
 /**
- * Waits (bounded by `timeoutMs`) for every given stream — stdout and stderr
- * by default — to drain. Resolution is unconditional; the caller exits
- * either way, the bound only decides how much queued output survives.
+ * Waits (bounded by `timeoutMs`) for every given stream (stdout and stderr
+ * by default) to drain. Resolution is unconditional. The caller exits
+ * either way, and the bound only decides how much queued output survives.
  */
 export declare function waitForStdioDrain(timeoutMs: number, streams?: readonly DrainableStream[]): Promise<void>;

package/dist/src/utils/stdio-drain.js

@@ -2,12 +2,12 @@
 /**
  * Bounded stdio drain for delayed process exits.
  *
- * `process.exit()` discards whatever is still queued in an async writable —
- * and stdout IS async when it is a pipe, with a 64 KiB kernel buffer on
+ * `process.exit()` discards whatever is still queued in an async writable,
+ * and stdout is async when it is a pipe, with a 64 KiB kernel buffer on
  * macOS/Linux. The observed failure: `status --json --fail-on` writes a
  * 176 KB payload, the refusal makes `bin/fireforge.ts` exit non-zero, and a
  * piped consumer receives exactly 65 536 bytes. The bin entry point awaits
- * this helper before every delayed exit; the helper itself never calls
+ * this helper before every delayed exit. The helper itself never calls
  * `process.exit` (the process-boundary test keeps that a bin-only right).
  */
 /** True when nothing the process is about to lose remains queued. */
@@ -16,8 +16,8 @@ function isFlushed(stream) {
 }
 /**
  * Resolves once `stream` has drained its queued writes, and always within
- * `timeoutMs`. Never rejects: `'error'` and `'close'` (an EPIPE'd pipe —
- * `installBrokenPipeHandler` already swallows the error itself) resolve
+ * `timeoutMs`. Never rejects: `'error'` and `'close'` (an EPIPE'd pipe,
+ * whose error `installBrokenPipeHandler` already swallows) resolve
  * immediately, because a destroyed pipe can never drain and must not stall
  * the exit behind it.
  */
@@ -45,9 +45,9 @@ function waitForStreamDrain(stream, timeoutMs) {
     });
 }
 /**
- * Waits (bounded by `timeoutMs`) for every given stream — stdout and stderr
- * by default — to drain. Resolution is unconditional; the caller exits
- * either way, the bound only decides how much queued output survives.
+ * Waits (bounded by `timeoutMs`) for every given stream (stdout and stderr
+ * by default) to drain. Resolution is unconditional. The caller exits
+ * either way, and the bound only decides how much queued output survives.
  */
 export async function waitForStdioDrain(timeoutMs, streams = [process.stdout, process.stderr]) {
     await Promise.all(streams.map((stream) => waitForStreamDrain(stream, timeoutMs)));

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

@@ -27,9 +27,9 @@ export declare function isPositiveInteger(value: unknown): value is number;
  * orders instead of failing fast.
  *
  * Rejects leading-zero forms ("01"), decimals ("1.5"), whitespace, and
- * non-numeric garbage via a strict regex — only the canonical
- * representation is accepted, so there is no ambiguity between what the user
- * typed and what the value becomes on disk.
+ * non-numeric garbage via a strict regex. Only the canonical representation
+ * is accepted, so there is no ambiguity between what the user typed and what
+ * the value becomes on disk.
  *
  * @param flagName - Flag name to include in the error (e.g. `--order`)
  * @param rawValue - Raw string value from Commander
@@ -57,8 +57,8 @@ export declare function isArray(value: unknown): value is unknown[];
  * Narrows a JSON value to a JSON object node (excludes arrays and `null`).
  *
  * Unlike {@link isObject} this accepts only values already known to be JSON
- * data, so the narrowed `JsonObject` keeps its concrete value contract —
- * use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
+ * data, so the narrowed `JsonObject` keeps its concrete value contract.
+ * Use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
  * @param value - JSON value to check
  * @returns True if value is a JSON object node
  */
@@ -78,22 +78,21 @@ export declare const FIREFOX_PRODUCTS: readonly ["firefox", "firefox-esr", "fire
  * Validates a Firefox product string.
  *
  * 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.
+ * Returning plain `boolean` would force `as FirefoxProduct` casts at the
+ * call sites even though the `.includes` check is the runtime proof.
  */
 export declare const isValidFirefoxProduct: (value: string) => value is "firefox" | "firefox-esr" | "firefox-beta" | "firefox-devedition";
 /**
  * Builds a type predicate from a `readonly` tuple of allowed values.
  *
- * Deriving the type from the list — rather than declaring a union and
- * hand-maintaining a matching array — removes a whole class of drift: a
+ * Deriving the type from the list, rather than declaring a union and
+ * hand-maintaining a matching array, removes a whole class of drift: a
  * union can otherwise accept a stale allowlist with no compile error, and a
  * copy of the member list on the `fireforge.json` read path can silently
  * reject a newly added value.
  *
  * Returning a predicate rather than a boolean is what removes the `as`
- * casts: `.includes` IS the runtime proof, so the caller should not have to
+ * casts: `.includes` is the runtime proof, so the caller should not have to
  * re-assert it. `ParsedRecord.stringEnum` (src/utils/parse.ts) consumes
  * exactly this shape.
  *
@@ -158,7 +157,7 @@ export declare function normalizeTokenName(name: string): string;
  * Normalizes a patch display name against its category:
  * strips a trailing `.patch` and any redundant `NNN-<category>-` /
  * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
- * the filename slug pipeline's require-the-category-token rule — a bare
+ * the filename slug pipeline's require-the-category-token rule. A bare
  * leading number is never stripped, so names like `2-step-verification`
  * survive intact. Falls back to the `.patch`-stripped stem when the
  * strip would empty the name.