@hominis/fireforge 0.43.1 → 0.44.1

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;

package/dist/src/utils/validation.js

@@ -36,15 +36,15 @@ export function isPositiveInteger(value) {
  * 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
@@ -108,19 +108,32 @@ export function isValidFirefoxCandidate(candidate) {
     return /^build[1-9]\d{0,3}$/.test(candidate);
 }
 /**
- * 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.
  *
- * `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.
+ * 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`.
  *
- * 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.
+ * `assert*` is uniform throughout: throw-or-continue.
+ */
+/**
+ * Valid Firefox product identifiers.
+ *
+ * `satisfies readonly FirefoxProduct[]` links the runtime list to the union
+ * in ONE direction: it rejects an entry here that the union does not
+ * declare. It cannot see a union member missing from this list — widening a
+ * `readonly T[]` check never fails for being short. The reverse direction is
+ * covered by the exhaustive switch in `utils/__tests__/validation.test.ts`,
+ * which fails to compile when the union grows.
  */
 export const FIREFOX_PRODUCTS = [
     'firefox',
@@ -132,12 +145,30 @@ export const FIREFOX_PRODUCTS = [
  * 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 function isValidFirefoxProduct(product) {
-    return FIREFOX_PRODUCTS.includes(product);
+export const isValidFirefoxProduct = makeEnumGuard(FIREFOX_PRODUCTS);
+/**
+ * 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 function makeEnumGuard(values) {
+    return (value) => values.includes(value);
 }
 /**
  * Valid project license SPDX identifiers.
@@ -146,9 +177,7 @@ export const PROJECT_LICENSES = ['EUPL-1.2', 'MPL-2.0', '0BSD', 'GPL-2.0-or-late
 /**
  * Validates a project license string.
  */
-export function isValidProjectLicense(license) {
-    return PROJECT_LICENSES.includes(license);
-}
+export const isValidProjectLicense = makeEnumGuard(PROJECT_LICENSES);
 /**
  * Valid patch categories.
  */
@@ -156,9 +185,7 @@ export const PATCH_CATEGORIES = ['branding', 'ui', 'privacy', 'security', 'infra
 /**
  * Validates a patch category string.
  */
-export function isValidPatchCategory(category) {
-    return PATCH_CATEGORIES.includes(category);
-}
+export const isValidPatchCategory = makeEnumGuard(PATCH_CATEGORIES);
 /**
  * Checks whether a Firefox version string has an ESR suffix.
  */
@@ -194,7 +221,7 @@ export function inferProductFromVersion(version) {
  *
  * @returns An error message if incompatible, or undefined if valid.
  */
-export function validateFirefoxProductVersionCompatibility(version, product) {
+export function describeProductVersionIncompatibility(version, product) {
     const versionIsEsr = isEsrVersion(version);
     const versionIsBeta = isBetaVersion(version);
     switch (product) {
@@ -247,7 +274,7 @@ export function isDefined(value) {
  *
  * @returns An error message if invalid, or undefined if valid.
  */
-export function validateTokenName(name) {
+export function describeTokenNameProblem(name) {
     // Strip leading -- for validation (callers may pass with or without)
     const ident = name.replace(/^--/, '');
     if (!ident) {
@@ -282,7 +309,7 @@ export function validateTokenName(name) {
  * @throws InvalidArgumentError if the resulting name is not a valid CSS custom property.
  */
 export function normalizeTokenName(name) {
-    const error = validateTokenName(name);
+    const error = describeTokenNameProblem(name);
     if (error) {
         throw new InvalidArgumentError(error, 'tokenName');
     }
@@ -323,7 +350,7 @@ export function normalizePatchDisplayName(name, category) {
  * @param name - The patch name to validate
  * @returns Error message if invalid, undefined if valid
  */
-export function validatePatchName(name) {
+export function describePatchNameProblem(name) {
     if (!name.trim())
         return 'Name is required';
     if (name.length > 50)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.43.1",
+  "version": "0.44.1",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -38,7 +38,7 @@
     "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\"",
     "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
     "prepack": "npm run build && node ./scripts/generate-build-info.mjs --loud",
-    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run cycles:check && npm run test:coverage && npm run pack:verify && npm run pack:dry-run",
+    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run cycles:check && npm run test:coverage && npm run pack:verify",
     "prepublishOnly": "npm run release:check"
   },
   "files": [
@@ -83,7 +83,7 @@
     "vitest": "^4.0.18"
   },
   "engines": {
-    "node": ">=22.22.1"
+    "node": ">=22.22.2"
   },
   "packageManager": "npm@11.12.1",
   "license": "EUPL-1.2",

package/dist/src/commands/doctor/post-rebase-audit.d.ts

@@ -1,2 +0,0 @@
-import type { DoctorCheckDefinition } from '../doctor-check-core.js';
-export declare const POST_REBASE_AUDIT_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-furnace-manifest-sync.d.ts

@@ -1,18 +0,0 @@
-/**
- * "Furnace manifest sync" doctor check.
- *
- * Surfaces orphaned component directories on disk whose names are missing
- * from `furnace.json`. The motivating eval case is the concurrent-override
- * race (eval 2) where two parallel `furnace override` commands both left
- * their directory on disk but only the second reached
- * `writeFurnaceConfig`. Under `--repair-furnace`, override orphans are
- * re-registered from the `override.json` sidecar the command wrote during
- * the copy phase; custom orphans are listed for the operator to either
- * re-run `furnace create` against or delete manually, because custom
- * components have no similar persisted metadata.
- *
- * Lives in a sibling module to keep `doctor-furnace.ts` under the
- * per-file LOC budget.
- */
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-export declare const furnaceManifestSyncCheck: DoctorCheckDefinition;