@hominis/fireforge 0.43.0 → 0.44.0

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

@@ -11,28 +11,3 @@ export type Arch = 'x64' | 'arm64';
  * @throws Error if running on an unsupported platform
  */
 export declare function getPlatform(): Platform;
-/**
- * Gets the current CPU architecture.
- * @throws Error if running on an unsupported architecture
- */
-export declare function getArch(): Arch;
-/**
- * Gets the mozconfig filename for the current platform.
- */
-export declare function getMozconfigName(): string;
-/**
- * Checks if the current platform is macOS.
- */
-export declare function isDarwin(): boolean;
-/**
- * Checks if the current platform is Linux.
- */
-export declare function isLinux(): boolean;
-/**
- * Checks if the current platform is Windows.
- */
-export declare function isWindows(): boolean;
-/**
- * Gets the appropriate file extension for executables on the current platform.
- */
-export declare function getExecutableExtension(): string;

package/dist/src/utils/platform.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { arch, platform } from 'node:os';
+import { platform } from 'node:os';
 import { GeneralError } from '../errors/base.js';
 /**
  * Gets the current operating system platform.
@@ -12,44 +12,3 @@ export function getPlatform() {
     }
     throw new GeneralError(`Unsupported platform: ${p}. FireForge supports darwin, linux, and win32.`);
 }
-/**
- * Gets the current CPU architecture.
- * @throws Error if running on an unsupported architecture
- */
-export function getArch() {
-    const a = arch();
-    if (a === 'x64' || a === 'arm64') {
-        return a;
-    }
-    throw new GeneralError(`Unsupported architecture: ${a}. FireForge supports x64 and arm64.`);
-}
-/**
- * Gets the mozconfig filename for the current platform.
- */
-export function getMozconfigName() {
-    return `${getPlatform()}.mozconfig`;
-}
-/**
- * Checks if the current platform is macOS.
- */
-export function isDarwin() {
-    return platform() === 'darwin';
-}
-/**
- * Checks if the current platform is Linux.
- */
-export function isLinux() {
-    return platform() === 'linux';
-}
-/**
- * Checks if the current platform is Windows.
- */
-export function isWindows() {
-    return platform() === 'win32';
-}
-/**
- * Gets the appropriate file extension for executables on the current platform.
- */
-export function getExecutableExtension() {
-    return isWindows() ? '.exe' : '';
-}

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

@@ -1,8 +1,8 @@
 /**
- * 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.
+ * 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.
  */
 import { type ChildProcess } from 'node:child_process';
 /**
@@ -11,6 +11,11 @@ import { type ChildProcess } from 'node:child_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:
+ * ESRCH/EPERM on the negative PID means the group is gone or was never
+ * created, and signalling the direct child is strictly better than
+ * returning silently.
  */
 export declare function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, usesProcessGroup: boolean): void;
 /** One process still alive in a swept group. */

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

@@ -1,9 +1,9 @@
 // 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.
+ * 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.
  */
 import { spawn } from 'node:child_process';
 import { getNodeErrorCode } from './errors.js';
@@ -14,6 +14,11 @@ import { verbose, warn } from './logger.js';
  * 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:
+ * ESRCH/EPERM on the negative PID means the group is gone or was never
+ * created, and signalling the direct child is strictly better than
+ * returning silently.
  */
 export function killProcessTree(child, signal, usesProcessGroup) {
     if (child.exitCode !== null || child.signalCode !== null)
@@ -26,7 +31,16 @@ export function killProcessTree(child, signal, 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);
+            try {
+                process.kill(-targetPid, signal);
+            }
+            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
+                // fall-through a failed group kill left the child running.
+                child.kill(signal);
+            }
         }
         else {
             // No process group on Windows — taskkill /T walks the descendant

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

@@ -1,3 +1,4 @@
+import { spawn } from 'node:child_process';
 /**
  * Result of executing a command.
  */
@@ -33,9 +34,8 @@ export interface ExecOptions {
      * 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
+     * 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.
      *
@@ -74,6 +74,27 @@ export interface StreamOptions extends ExecOptions {
  * @returns Exit code of the process
  */
 export declare function execStream(command: string, args: string[], options?: StreamOptions): Promise<number>;
+/**
+ * Registers a child with {@link waitForActiveChildShutdown}.
+ *
+ * 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
+ * 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.
+ */
+/**
+ * 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`
+ *   handlers so a dead child never holds the shutdown wait open
+ */
+export declare function trackChildClosure(): {
+    settle: () => void;
+};
 /**
  * Waits (bounded) for every tracked child process to close. Called by the
  * bin signal handler after forwarding SIGINT/SIGTERM, so the parent stays
@@ -100,6 +121,17 @@ export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<v
 export declare function execInherit(command: string, args: string[], options?: ExecOptions & {
     shutdownGraceMs?: number;
 }): 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
+ * `close` and `error` handlers so the process does not accumulate signal
+ * listeners across repeated spawns.
+ */
+export declare function installGracefulShutdownForwarder(child: ReturnType<typeof spawn>, graceMs: number, killTarget?: (signal: NodeJS.Signals) => void): {
+    dispose: () => void;
+};
 /**
  * Executes a command while inheriting stdin, streaming stdout/stderr live,
  * and capturing the emitted output for diagnostics.
@@ -118,11 +150,14 @@ export type SmokeLineCallback = (line: string) => void;
  *
  * Deliberately omits `ExecOptions.timeout`: the smoke run's only deadline is
  * {@link SmokeRunOptions.smokeTimeoutMs}, which signals the whole process
- * group. Inheriting `timeout` used to be a leaky trap — it was accepted by
- * the type but silently ignored, so a caller setting it got no deadline at
- * all.
+ * group. Inheriting `timeout` is a leaky trap — accepted by the type but
+ * silently ignored, so a caller setting it gets no deadline at all.
+ *
+ * `processGroup` is omitted for the same reason: a smoke run is ALWAYS
+ * detached on POSIX (`usesProcessGroup` is derived from `process.platform`
+ * alone), so the field would be accepted and never read.
  */
-export interface SmokeRunOptions extends Omit<ExecOptions, 'timeout'> {
+export interface SmokeRunOptions extends Omit<ExecOptions, 'processGroup' | 'timeout'> {
     /**
      * Hard deadline in milliseconds. When it elapses the child process
      * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned

package/dist/src/utils/process.js

@@ -145,6 +145,12 @@ export async function execStream(command, args, options = {}) {
                 killProcessTree(child, signal, usesProcessGroup);
             })
             : 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
             // outlive the dispatch (a mach dying at startup used to strand
@@ -153,11 +159,13 @@ export async function execStream(command, args, options = {}) {
                 killProcessTree(child, 'SIGKILL', usesProcessGroup);
             }
             forwarder?.dispose();
+            closure.settle();
             reject(toExecRejection(error, command, args, options.timeout));
         });
         child.on('close', (code, signal) => {
             forwarder?.dispose();
             const finish = () => {
+                closure.settle();
                 resolve(exitCodeFromClose(code, signal));
             };
             if (groupPid !== undefined) {
@@ -171,15 +179,33 @@ export async function execStream(command, args, options = {}) {
 }
 /**
  * Close-promises of children whose shutdown the CLI must wait for when a
- * termination signal arrives. The bin signal handler used to `process.exit`
- * within a microtask of the first Ctrl+C, which made `execInherit`'s
- * documented SIGTERM → grace → SIGKILL escalation unreachable: the parent
- * was gone before the 1500 ms grace timer could fire, so a hung Firefox
- * was orphaned forever instead of being SIGKILLed and a healthy one lost
- * its AsyncShutdown flush window.
+ * termination signal arrives. A bin signal handler that calls `process.exit`
+ * within a microtask of the first Ctrl+C makes `execInherit`'s documented
+ * SIGTERM → grace → SIGKILL escalation unreachable: the parent is gone
+ * before the 1500 ms grace timer can fire, so a hung Firefox is orphaned
+ * forever instead of being SIGKILLed and a healthy one loses its
+ * AsyncShutdown flush window.
  */
 const activeChildClosures = new Set();
-function trackChildClosure() {
+/**
+ * Registers a child with {@link waitForActiveChildShutdown}.
+ *
+ * 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
+ * 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.
+ */
+/**
+ * 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`
+ *   handlers so a dead child never holds the shutdown wait open
+ */
+export function trackChildClosure() {
     let resolveClosed;
     const closed = new Promise((resolve) => {
         resolveClosed = resolve;
@@ -274,7 +300,7 @@ 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, killTarget) {
+export function installGracefulShutdownForwarder(child, graceMs, killTarget) {
     let graceTimer;
     const forwarded = new Set();
     const sendKill = (signal) => {
@@ -508,6 +534,8 @@ export async function execSmokeRun(command, args, options) {
                 stdout: out.getText(),
                 stderr: err.getText(),
                 exitCode: exitCodeFromClose(code, signal),
+                stdoutTruncated: out.wasTruncated(),
+                stderrTruncated: err.wasTruncated(),
                 timedOut,
             });
         });
@@ -516,21 +544,20 @@ 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) previously grew the buffer without bound — the 50 MB cap
- * only guarded the collector, not these line buffers. When the tail
- * exceeds the cap it is dispatched as a synthetic (oversized) line so the
- * matchers still get to see its content, then the buffer resets.
+ * 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; before `\r` counted as a
- * terminator those updates accumulated 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.
+ * 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;

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

@@ -0,0 +1,31 @@
+/**
+ * Parser for the duration fields `ps` prints.
+ *
+ * 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.
+ *
+ * Dialects:
+ *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
+ *   - darwin/BSD `mm:ss.cc`, whose minutes field accumulates without
+ *     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
+ * old would be exactly the wrong attribution.
+ */
+/**
+ * Parses a `ps` duration field into whole seconds.
+ *
+ * @param value - Raw field text, e.g. `03:14:12` or `38412:07.55`
+ * @returns Seconds, or `NaN` when the shape is not recognized
+ */
+export declare function parsePsDuration(value: string): number;
+/**
+ * Renders a duration for an operator-facing line: `4s`, `3m12s`, `2h05m`.
+ * Returns `undefined` for `NaN`, so a caller can omit the clause entirely
+ * rather than print "unknown" noise.
+ */
+export declare function formatPsDuration(seconds: number): string | undefined;

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

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Parser for the duration fields `ps` prints.
+ *
+ * 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.
+ *
+ * Dialects:
+ *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
+ *   - darwin/BSD `mm:ss.cc`, whose minutes field accumulates without
+ *     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
+ * old would be exactly the wrong attribution.
+ */
+/**
+ * Parses a `ps` duration field into whole seconds.
+ *
+ * @param value - Raw field text, e.g. `03:14:12` or `38412:07.55`
+ * @returns Seconds, or `NaN` when the shape is not recognized
+ */
+export function parsePsDuration(value) {
+    const trimmed = value.trim();
+    let days = 0;
+    let rest = trimmed;
+    const dayMatch = /^(\d+)-(.*)$/.exec(trimmed);
+    if (dayMatch) {
+        days = Number(dayMatch[1]);
+        rest = dayMatch[2] ?? '';
+    }
+    const parts = rest.split(':');
+    if (parts.length === 3) {
+        // hh:mm:ss (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)
+        const [m, s] = parts.map(Number);
+        if ([m, s].some((n) => Number.isNaN(n)))
+            return NaN;
+        return days * 86400 + (m ?? 0) * 60 + (s ?? 0);
+    }
+    return NaN;
+}
+/**
+ * Renders a duration for an operator-facing line: `4s`, `3m12s`, `2h05m`.
+ * Returns `undefined` for `NaN`, so a caller can omit the clause entirely
+ * rather than print "unknown" noise.
+ */
+export function formatPsDuration(seconds) {
+    if (Number.isNaN(seconds) || seconds < 0)
+        return undefined;
+    if (seconds < 60)
+        return `${String(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`;
+    }
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    return `${String(h)}h${String(m).padStart(2, '0')}m`;
+}

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

@@ -9,17 +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 preserved intact.
+ * both character offsets AND line numbers are preserved. String literals are
+ * preserved intact.
  *
- * Uses acorn's tokenizer, which understands regex literals — the previous
- * pure-regex implementation did not model them, so two adjacent slashes
- * inside a regex (e.g. the tail of `/https?:\/\//`) were treated as a `//`
- * line comment and the rest of the line was blanked, corrupting whatever
- * lint pass consumed 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 (documented limitation of the fallback).
+ * 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.
  */
 export declare function stripJsComments(source: string): string;
 /**

package/dist/src/utils/regex.js

@@ -25,17 +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 preserved intact.
+ * both character offsets AND line numbers are preserved. String literals are
+ * preserved intact.
  *
- * Uses acorn's tokenizer, which understands regex literals — the previous
- * pure-regex implementation did not model them, so two adjacent slashes
- * inside a regex (e.g. the tail of `/https?:\/\//`) were treated as a `//`
- * line comment and the rest of the line was blanked, corrupting whatever
- * lint pass consumed 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 (documented limitation of the fallback).
+ * 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.
  */
 export function stripJsComments(source) {
     const comments = [];

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

@@ -1,4 +1,3 @@
-import type { FirefoxProduct } from '../types/config.js';
 import type { JsonObject, JsonValue } from '../types/json.js';
 /**
  * Checks whether a value is a string.
@@ -22,15 +21,15 @@ export declare function isPositiveInteger(value: unknown): value is number;
  * Parses a CLI flag value as a positive integer. Throws
  * {@link InvalidArgumentError} on NaN, non-integer, or non-positive input.
  *
- * Intended for use inside Commander `argParser` bodies where the raw
- * input arrives as a string. Without this wrapper the default pattern
- * (`parseInt(v, 10)`) silently hands NaN to downstream planners, which
- * then embed it into filenames / orders instead of failing fast.
+ * Intended for use inside Commander `argParser` bodies where the raw input
+ * arrives as a string. The default pattern (`parseInt(v, 10)`) silently
+ * hands NaN to downstream planners, which then embed it into filenames and
+ * orders instead of failing fast.
  *
  * Rejects leading-zero forms ("01"), decimals ("1.5"), whitespace, and
- * non-numeric garbage via a strict regex — we only accept the canonical
- * representation 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
@@ -75,30 +74,61 @@ export declare function isValidFirefoxVersion(version: string): boolean;
  */
 export declare function isValidFirefoxCandidate(candidate: string): boolean;
 /**
- * Valid Firefox product identifiers.
+ * 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`.
  *
- * `satisfies readonly FirefoxProduct[]` links the runtime list to the union at
- * `types/config.ts:5` 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.
+ * `assert*` is uniform throughout: throw-or-continue.
+ */
+/**
+ * Valid Firefox product identifiers.
  *
- * Two further copies of this list existed before 0.41.0 — an inline literal
- * inside the validator below and `SOURCE_PRODUCTS` in `commands/source.ts` —
- * neither linked to the union.
+ * `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}. It returned plain `boolean` until 0.41.0,
- * which forced `as FirefoxProduct` casts at both call sites even though the
- * `.includes` check IS the runtime proof.
+ * {@link isValidProjectLicense}. 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
+ * 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
+ * re-assert it. `ParsedRecord.stringEnum` (src/utils/parse.ts) consumes
+ * exactly this shape.
+ *
+ * @param values - The allowed values, as a `readonly` tuple
+ * @returns A type predicate narrowing a string to one of `values`
  */
-export declare function isValidFirefoxProduct(product: string): product is FirefoxProduct;
+export declare function makeEnumGuard<const T extends readonly string[]>(values: T): (value: string) => value is T[number];
 /**
  * Valid project license SPDX identifiers.
  */
@@ -106,7 +136,7 @@ export declare const PROJECT_LICENSES: readonly ["EUPL-1.2", "MPL-2.0", "0BSD",
 /**
  * Validates a project license string.
  */
-export declare function isValidProjectLicense(license: string): license is (typeof PROJECT_LICENSES)[number];
+export declare const isValidProjectLicense: (value: string) => value is "EUPL-1.2" | "MPL-2.0" | "0BSD" | "GPL-2.0-or-later";
 /**
  * Valid patch categories.
  */
@@ -114,7 +144,7 @@ export declare const PATCH_CATEGORIES: readonly ["branding", "ui", "privacy", "s
 /**
  * Validates a patch category string.
  */
-export declare function isValidPatchCategory(category: string): category is (typeof PATCH_CATEGORIES)[number];
+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.
@@ -130,7 +160,7 @@ export declare function inferProductFromVersion(version: string): 'firefox' | 'f
  *
  * @returns An error message if incompatible, or undefined if valid.
  */
-export declare function validateFirefoxProductVersionCompatibility(version: string, product: string): string | undefined;
+export declare function describeProductVersionIncompatibility(version: string, product: string): string | undefined;
 /**
  * Validates an application ID string.
  * Accepts reverse-domain format like "org.example.browser"
@@ -151,7 +181,7 @@ export declare function isDefined<T>(value: T | undefined | null): value is T;
  *
  * @returns An error message if invalid, or undefined if valid.
  */
-export declare function validateTokenName(name: string): string | undefined;
+export declare function describeTokenNameProblem(name: string): string | undefined;
 /**
  * Normalizes a CSS custom property token name.
  * Strips leading `--` if present, then always prepends `--`.
@@ -175,4 +205,4 @@ export declare function normalizePatchDisplayName(name: string, category: string
  * @param name - The patch name to validate
  * @returns Error message if invalid, undefined if valid
  */
-export declare function validatePatchName(name: string): string | undefined;
+export declare function describePatchNameProblem(name: string): string | undefined;