@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/core/test-stale-check.js

@@ -4,24 +4,23 @@
  *
  * Without this preflight, an operator who edits engine chrome / packaged
  * resources (`jar.mn` entries, `.xhtml`/`.mjs`/`.css` under chrome trees,
- * pref files) and then runs `fireforge test <path>` only discovers the
- * build is stale AFTER xpcshell / mach test starts and errors out with
- * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI
- * — which reads as a test bug, not a rebuild prompt. The motivating case
- * was scaffolding a new top-level chrome document + BrowserGlue-style
- * xpcshell test: the test file existed, the manifests were registered,
- * but `dist/` still held the pre-edit bundle and chrome URIs resolved
- * to nothing.
+ * pref files) and then runs `fireforge test <path>` only discovers the build
+ * is stale AFTER xpcshell / mach test starts and errors out with
+ * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI —
+ * which reads as a test bug, not a rebuild prompt. Scaffolding a new
+ * top-level chrome document plus an xpcshell test is the canonical case: the
+ * test file exists, the manifests are registered, but `dist/` still holds
+ * the pre-edit bundle and chrome URIs resolve to nothing.
  *
  * This preflight diffs engine HEAD (or workdir) against the last-build
  * baseline (`.fireforge/last-build.json`), filters to paths that imply
  * packaging, and returns a compact summary. `fireforge test` prints a
- * warning up-front so the operator sees "you edited X, Y, Z since the
- * last build — rerun with `--build` to refresh" BEFORE mach test
- * launches. Detection stays advisory (warn-only) because a fork that
- * rebuilds out-of-band (a separate `./mach build` invocation, an IDE
- * plugin, etc.) can legitimately have a fresh `dist/` with no
- * FireForge-recorded baseline update.
+ * warning up-front so the operator sees "you edited X, Y, Z since the last
+ * build — rerun with `--build` to refresh" BEFORE mach test launches.
+ * Detection stays advisory (warn-only) because a fork that rebuilds
+ * out-of-band (a separate `./mach build` invocation, an IDE plugin) can
+ * legitimately have a fresh `dist/` with no FireForge-recorded baseline
+ * update.
  */
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
@@ -51,17 +50,16 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     let packageable = changed.filter((path) => isPackageablePath(path)).sort();
     // Content-hash comparison: when the baseline carries a fingerprint set,
     // fold each candidate path through a live re-hash and drop paths whose
-    // current content matches the baseline. Pre-0.16.0 baselines have no
-    // `packageableFingerprints` field; those fall through and the
-    // path-only comparison behaves as before (every workdir-dirty
-    // packageable path is reported as stale). The concrete motivating
-    // case: a project with imported patches + Furnace-applied components
-    // always has a persistent workdir diff against HEAD. Before the
-    // fingerprint layer, `git diff --name-only HEAD` returned that diff
-    // on every build, so the stale check fired immediately after a
-    // successful build even though nothing had actually changed. The
-    // fingerprints capture "these files had this content when the build
-    // ran"; a path stays stale only when its live hash diverges.
+    // current content matches the baseline. Baselines without
+    // `packageableFingerprints` fall through to the path-only comparison,
+    // where every workdir-dirty packageable path reports as stale.
+    //
+    // This matters because a project with imported patches plus
+    // Furnace-applied components always has a persistent workdir diff against
+    // HEAD, so `git diff --name-only HEAD` returns that diff on every build
+    // and the stale check fires immediately after a successful one. The
+    // fingerprints capture "these files had this content when the build ran";
+    // a path stays stale only when its live hash diverges.
     const fingerprints = baseline.packageableFingerprints;
     if (fingerprints) {
         const staleAfterHashCheck = [];
@@ -105,16 +103,16 @@ export const FULL_SUITE_REQUEST = '(entire suite)';
  * packaging does NOT cover — the runs that would dispatch against missing
  * `_tests/` support fixtures and hang rather than fail.
  *
- * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
- * everything. A scoped list covers a request path when the request equals a
- * covered entry, sits beneath a covered directory entry, or shares a
- * manifest granule with a covered entry ({@link toManifestGranule} — a
- * scoped `test --build` packages the whole manifest directory, so a
- * same-manifest sibling of a covered file is packaged too). Both sides are
- * normalized to forward slashes so Windows-style CLI input cannot defeat
- * the prefix rule (baseline paths are POSIX by convention). A request with
- * no paths is a full-suite run and is never covered by a scoped list — the
- * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ * Coverage semantics: an absent claim and `'full'` cover everything. A
+ * scoped list covers a request path when the request equals a covered entry,
+ * sits beneath a covered directory entry, or shares a manifest granule with
+ * a covered entry ({@link toManifestGranule} — a scoped `test --build`
+ * packages the whole manifest directory, so a same-manifest sibling of a
+ * covered file is packaged too). Both sides are normalized to forward
+ * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
+ * paths are POSIX by convention). A request with no paths is a full-suite
+ * run and is never covered by a scoped list — the {@link FULL_SUITE_REQUEST}
+ * sentinel is returned so the refusal can name it.
  */
 export function findUncoveredRequestPaths(coverage, requestedPaths) {
     if (coverage === undefined || coverage === 'full') {
@@ -167,8 +165,17 @@ export function formatTestCoverageRefusal(uncovered, coverage) {
         return head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
+    // Name --extend-coverage here or it is undiscoverable: a scoped build
+    // REPLACES the claim, so under several concurrent sessions a peer's build
+    // for an unrelated path erases coverage you legitimately still hold, and
+    // the union that fixes it is a flag the operator has no reason to know
+    // exists at the moment they need it. The anchor conditions are stated
+    // because they are what decides whether it will work.
+    const extendHint = rebuildTargets.length > 0
+        ? ` Add --extend-coverage to that rebuild to UNION the new paths onto the recorded claim instead of replacing it — it holds while engine HEAD and engine/mozconfig are unchanged since the recorded build.`
+        : '';
     const rebuildHint = rebuildTargets.length > 0
-        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.`
+        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
     return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
         `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
@@ -180,17 +187,17 @@ export function formatTestCoverageRefusal(uncovered, coverage) {
  * Probes whether any `components.conf` changed since the last FULL
  * `fireforge build` — i.e. since the compiled StaticComponents table was
  * last regenerated. `components.conf` entries bake into compiled code; a
- * scoped `test --build` packages the file but the child process resolves
- * the OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a
- * test bug.
+ * scoped `test --build` packages the file but the child process resolves the
+ * OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
+ * bug.
  *
  * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`
+ * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`,
  * which a scoped `test --build` advances. Dirty candidates are hash-checked
  * against the anchor's fingerprints so only genuine content divergence
- * counts. No baseline / no anchor (pre-0.38.0 marker) → fresh. Never
- * throws — the probes it composes degrade to verbose lines and empty
- * results on git failure, matching {@link checkStaleBuildForTest}.
+ * counts. No baseline or no anchor means fresh. Never throws — the probes it
+ * composes degrade to verbose lines and empty results on git failure,
+ * matching {@link checkStaleBuildForTest}.
  */
 export async function checkStaticComponentsStale(engineDir, baseline) {
     const anchor = baseline?.staticComponentsBaseline;

package/dist/src/core/test-stall-triage.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Operator-facing triage for the `timed out … with no output` / `Ran 0
+ * checks` stall — the shape where the harness dies before ANY test output.
+ *
+ * Split out of `test-harness-crash.ts`, which CLASSIFIES runs; this module
+ * only renders advice about one already-classified shape. Keeping the two
+ * apart matters because the census below carries claims of unequal
+ * evidential strength, and the rules for editing it are not the rules for
+ * editing a classifier: a pattern in the classifier is either matched by
+ * the output or not, while a cause in the census is an assertion about the
+ * world that an operator will act on.
+ *
+ * Everything here is pure — the platform and the probed display state are
+ * injected, so unit tests need no mocking.
+ */
+import type { DisplaySleepState } from './display-state.js';
+import type { HarnessCrashSignature } from './test-harness-signature.js';
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout.
+ *
+ * When `displayState` names a MEASURED display state, the hint states it as
+ * fact rather than as one of three possibilities — that is the point of
+ * probing: an operator staring at a bare test failure should not have to
+ * rediscover that their machine dimmed. `caffeinate` is described accurately
+ * (it prevents sleep; it cannot wake an already-sleeping display), so
+ * operators are not sent to a command that could not have helped them.
+ *
+ * Pure — the platform and the probed state are injected so unit tests need
+ * no mocking.
+ *
+ * @param signature - The recognized crash shape
+ * @param context - Run mode, platform, and the probed display state
+ * @returns The hint text, or undefined when the shape does not apply
+ */
+export declare function headedNoOutputTimeoutHint(signature: HarnessCrashSignature, context: {
+    headless: boolean;
+    platform: string;
+    displayState?: DisplaySleepState;
+}): string | undefined;
+/**
+ * Verdict-line note for a headed no-output stall whose display was
+ * measured asleep. Returned as the parenthetical the verdict line carries,
+ * so the one greppable line an automated consumer reads already names the
+ * environmental cause instead of a bare `FAIL reason=crash`.
+ */
+export declare function headedDisplayAsleepVerdictNote(signature: HarnessCrashSignature, context: {
+    headless: boolean;
+    platform: string;
+    displayState: DisplaySleepState;
+}): string | undefined;

package/dist/src/core/test-stall-triage.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Operator-facing triage for the `timed out … with no output` / `Ran 0
+ * checks` stall — the shape where the harness dies before ANY test output.
+ *
+ * Split out of `test-harness-crash.ts`, which CLASSIFIES runs; this module
+ * only renders advice about one already-classified shape. Keeping the two
+ * apart matters because the census below carries claims of unequal
+ * evidential strength, and the rules for editing it are not the rules for
+ * editing a classifier: a pattern in the classifier is either matched by
+ * the output or not, while a cause in the census is an assertion about the
+ * world that an operator will act on.
+ *
+ * Everything here is pure — the platform and the probed display state are
+ * injected, so unit tests need no mocking.
+ */
+/**
+ * First step for the `timed out … with no output` / `Ran 0 checks`
+ * signature, printed ABOVE the cause list. Running a known-good control
+ * separates "this test" from "this build" and is the correct opening move
+ * for EVERY cause below — it is not specific to any one of them, so
+ * attaching it to a single entry made reaching that entry informationally
+ * empty.
+ */
+const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If the control stalls too, the cause is not the test ' +
+    'under investigation, and the list below applies to the build or the host.';
+/**
+ * Recorded causes of the `timed out … with no output` / `Ran 0 checks`
+ * signature, each paired with the probe that DISCRIMINATES it from the
+ * others. Printed verbatim under the hint.
+ *
+ * Evidence per entry is deliberately unequal, and the text says so:
+ *
+ *  - (1) is MEASURED — `probeDisplaySleepState` reads the display's power
+ *    state, so the hint states it as fact rather than as a possibility.
+ *  - (2) is discriminated by `--headless`.
+ *  - (4) is MECHANICAL and was root-caused downstream: the harness serves
+ *    its manifest from `server.js` on 8888, and a survivor of an
+ *    interrupted run keeps the port. Its probe is exact, and the preflight
+ *    in `mochitest-server-port.ts` now refuses it before a run starts.
+ *  - (3) is a single downstream report (one consumer, 3/3 reproduce and 3/3
+ *    restore on one variable) whose MECHANISM was never root-caused. It is
+ *    stated as the correlation it is. An earlier revision asserted "stalls
+ *    first paint" as fact; that was a causal story written on top of the
+ *    correlation, and a doubtful one — a failed image load in Gecko fires
+ *    `error` and does not gate the document load event, and the harness's
+ *    browser-ready handshake does not wait on image decode. Do not restore
+ *    a mechanism claim here without a root cause to cite.
+ *
+ * Detection (a named signature, as with the module-resolution SIGSEGV) is
+ * not specified for (3) because no log line is known to key on. The bar for
+ * adding one is the bar `mach-error-hints.ts` states: an established
+ * diagnosis, never a plausible guess.
+ */
+const NO_OUTPUT_STALL_TRIAGE = [
+    '  1. A sleeping or locked display on an unattended HEADED run (macOS). The browser never ' +
+        'paints and never reaches its first test.',
+    '  2. A headless SWGL compositor failure — re-run with --headless to separate this from (1): ' +
+        'if --headless passes, the stall was display/compositor-side, not product-side.',
+    '  3. Product-side startup: the browser never reaches the state the harness waits for. One ' +
+        'downstream report correlates this stall with a broken `chrome://` image URI on the ' +
+        'startup page (reproduced and un-reproduced on that one variable); the mechanism was ' +
+        'never root-caused, so treat it as a lead, not an explanation. Discriminate with ' +
+        '"fireforge run --smoke-exit 60 --headless --capture-console <file>", which launches the ' +
+        'same browser OUTSIDE the test harness: a clean window with no unallowed console errors ' +
+        'means product-side startup is healthy and the stall is harness- or test-side; a hang, a ' +
+        'non-zero exit, or console errors in <file> put it in the startup document.',
+    '  4. A stale mochitest httpd holding the harness server port (127.0.0.1:8888). A fresh ' +
+        "browser connects to THAT server, which cannot serve this run's manifest, so the run " +
+        'stalls before TEST_START. Probe with "lsof -nP -iTCP:8888": any listener that is not ' +
+        "this run's own is the cause. FireForge now refuses this at preflight, so it should " +
+        'reach a stall only on a host where the port could not be probed.',
+];
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout.
+ *
+ * When `displayState` names a MEASURED display state, the hint states it as
+ * fact rather than as one of three possibilities — that is the point of
+ * probing: an operator staring at a bare test failure should not have to
+ * rediscover that their machine dimmed. `caffeinate` is described accurately
+ * (it prevents sleep; it cannot wake an already-sleeping display), so
+ * operators are not sent to a command that could not have helped them.
+ *
+ * Pure — the platform and the probed state are injected so unit tests need
+ * no mocking.
+ *
+ * @param signature - The recognized crash shape
+ * @param context - Run mode, platform, and the probed display state
+ * @returns The hint text, or undefined when the shape does not apply
+ */
+export function headedNoOutputTimeoutHint(signature, context) {
+    if (context.platform !== 'darwin' || context.headless)
+        return undefined;
+    if (!signature.reason.includes('no-output timeout'))
+        return undefined;
+    const lead = context.displayState === 'asleep'
+        ? 'Hint: this was a HEADED run on macOS and the display was MEASURED ASLEEP ' +
+            '(IODisplayWrangler below its awake power state). A headed browser on a sleeping ' +
+            'display never paints and never starts a test, so this stall is environmental — not a ' +
+            'product or test failure.'
+        : context.displayState === 'awake'
+            ? 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
+                'was measured AWAKE, so the sleeping-display cause below is ruled out for this run.'
+            : 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
+                'state could not be measured, so all three causes below remain open.';
+    const remedy = 'Note that `caffeinate -disu` PREVENTS sleep; it cannot WAKE a display that is already ' +
+        'asleep. Wake the display (or run on an attended machine), or pass --headless.';
+    return (`${lead}\n\n${NO_OUTPUT_STALL_CONTROL_STEP}\n\n` +
+        `Known causes of this exact signature:\n${NO_OUTPUT_STALL_TRIAGE.join('\n')}\n\n${remedy}`);
+}
+/**
+ * Verdict-line note for a headed no-output stall whose display was
+ * measured asleep. Returned as the parenthetical the verdict line carries,
+ * so the one greppable line an automated consumer reads already names the
+ * environmental cause instead of a bare `FAIL reason=crash`.
+ */
+export function headedDisplayAsleepVerdictNote(signature, context) {
+    if (context.platform !== 'darwin' || context.headless)
+        return undefined;
+    if (context.displayState !== 'asleep')
+        return undefined;
+    if (!signature.reason.includes('no-output timeout'))
+        return undefined;
+    return 'headed run stalled with the display asleep';
+}

package/dist/src/core/token-category.js

@@ -1,15 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Category banner and token-declaration helpers for the tokens CSS file
- *. Split out of `token-manager.ts` to stay inside the per-file
- * line budget.
+ * Category banner and token-declaration helpers for the tokens CSS file.
+ * Split out of `token-manager.ts` to stay inside the per-file line budget.
  *
  * Banner matching is EXACT: the text between the `=` runs (single-line
  * shape) or on the block line (multi-line shape) must equal the category
- * after trimming. The pre-0.40.0 substring match let a TOC comment or a
- * longer banner (`Colors — Canvas` for `Colors`) satisfy the lookup, so
- * `token add` wrote into the wrong section — or no-oped for 19
- * consecutive calls — with exit 0.
+ * after trimming. A substring match lets a TOC comment or a longer banner
+ * (`Colors — Canvas` for `Colors`) satisfy the lookup, so `token add` writes
+ * into the wrong section — or no-ops — with exit 0.
  */
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';

package/dist/src/core/token-coverage.js

@@ -7,17 +7,17 @@ import { countRawCssColors } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 /**
  * Default platform prefixes treated as allowlisted upstream vars. Any
- * `var(--moz-*)` usage in a fork's CSS is a Firefox platform variable
- * that the fork does not own and should not be counted as an unknown.
- * 2026-04-21 eval (Finding #5): a `furnace override moz-button -t
- * css-only` + one fork token produced 1% coverage because the 84
- * upstream `--moz-*` vars in the copied baseline counted as unknown.
+ * `var(--moz-*)` usage in a fork's CSS is a Firefox platform variable the
+ * fork does not own and must not count as an unknown — otherwise a
+ * `furnace override moz-button -t css-only` plus one fork token reports 1%
+ * coverage, because the ~84 upstream `--moz-*` vars in the copied baseline
+ * all count against it.
  *
  * Forks that want to opt out can override this via
- * `furnace.json.platformPrefixes = []`; forks that want more can
- * extend it (e.g. `['--moz-', '--in-content-']`). The config is
- * additive — nothing is removed from the defaults unless the operator
- * explicitly writes a shorter list.
+ * `furnace.json.platformPrefixes = []`; forks that want more can extend it
+ * (e.g. `['--moz-', '--in-content-']`). The config is additive — nothing is
+ * removed from the defaults unless the operator explicitly writes a shorter
+ * list.
  */
 const DEFAULT_PLATFORM_PREFIXES = ['--moz-'];
 /**

package/dist/src/core/token-dark-mode.d.ts

@@ -1,17 +1,15 @@
 /**
  * Dark-mode insertion helpers for the tokens CSS scaffold.
  *
- * The 2026-04-21 eval reproduced a bug where `fireforge token add
- * --mode override --dark-value ...` landed the dark declaration
- * AFTER the nested `:root { }` inside the
- * `@media (prefers-color-scheme: dark)` block had already closed,
- * producing a declaration outside any rule block. The helpers here
- * scan the comment-stripped source lines to find the *inner* `:root`
- * block's closing `}` and return a line index the caller can splice
- * into. When the inner `:root` is missing (a scaffold that drifted
- * from the default), the fallback helper returns the outer `@media`
- * block's close so the caller can materialise a fresh `:root` wrapper
- * rather than dropping the dark value.
+ * `fireforge token add --mode override --dark-value ...` must land the dark
+ * declaration INSIDE the nested `:root { }` of the
+ * `@media (prefers-color-scheme: dark)` block; landing after that block has
+ * closed produces a declaration outside any rule. The helpers here scan the
+ * comment-stripped source lines to find the *inner* `:root` block's closing
+ * `}` and return a line index the caller can splice into. When the inner
+ * `:root` is missing (a scaffold that drifted from the default), the
+ * fallback helper returns the outer `@media` block's close so the caller can
+ * materialise a fresh `:root` wrapper rather than dropping the dark value.
  */
 /**
  * Strips the content of `/* ... *\/` block comments from an array of

package/dist/src/core/token-dark-mode.js

@@ -2,17 +2,15 @@
 /**
  * Dark-mode insertion helpers for the tokens CSS scaffold.
  *
- * The 2026-04-21 eval reproduced a bug where `fireforge token add
- * --mode override --dark-value ...` landed the dark declaration
- * AFTER the nested `:root { }` inside the
- * `@media (prefers-color-scheme: dark)` block had already closed,
- * producing a declaration outside any rule block. The helpers here
- * scan the comment-stripped source lines to find the *inner* `:root`
- * block's closing `}` and return a line index the caller can splice
- * into. When the inner `:root` is missing (a scaffold that drifted
- * from the default), the fallback helper returns the outer `@media`
- * block's close so the caller can materialise a fresh `:root` wrapper
- * rather than dropping the dark value.
+ * `fireforge token add --mode override --dark-value ...` must land the dark
+ * declaration INSIDE the nested `:root { }` of the
+ * `@media (prefers-color-scheme: dark)` block; landing after that block has
+ * closed produces a declaration outside any rule. The helpers here scan the
+ * comment-stripped source lines to find the *inner* `:root` block's closing
+ * `}` and return a line index the caller can splice into. When the inner
+ * `:root` is missing (a scaffold that drifted from the default), the
+ * fallback helper returns the outer `@media` block's close so the caller can
+ * materialise a fresh `:root` wrapper rather than dropping the dark value.
  */
 /**
  * Strips the content of `/* ... *\/` block comments from an array of

package/dist/src/core/token-docs.d.ts

@@ -21,6 +21,8 @@ export interface TokenDocInput {
  * against a freshly parsed view of the document so that splice indices
  * stay valid as rewrites are layered.
  *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Token name, category and description to document
  * @param annotation - The mode annotation string the caller already computed
  *   (kept here as a parameter so this module needs no dependency on
  *   token-manager's `getModeAnnotation`).

package/dist/src/core/token-docs.js

@@ -26,6 +26,8 @@ function stripInlineCode(cell) {
  * against a freshly parsed view of the document so that splice indices
  * stay valid as rewrites are layered.
  *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Token name, category and description to document
  * @param annotation - The mode annotation string the caller already computed
  *   (kept here as a parameter so this module needs no dependency on
  *   token-manager's `getModeAnnotation`).

package/dist/src/core/token-manager.d.ts

@@ -1,8 +1,16 @@
 import { type TokenDeclarationLocation } from './token-category.js';
 /**
- * Dark mode behavior for a token.
+ * Dark mode behaviour for a token.
+ *
+ * Derived from {@link TOKEN_MODES} so the runtime allowlist and the type
+ * cannot drift: adding a member here without updating the list (or the
+ * reverse) is no longer possible, because there is only one list.
  */
-export type TokenMode = 'auto' | 'static' | 'override';
+export declare const TOKEN_MODES: readonly ["auto", "static", "override"];
+/** Dark mode behaviour for a token. */
+export type TokenMode = (typeof TOKEN_MODES)[number];
+/** Narrows an arbitrary string to a {@link TokenMode}. */
+export declare const isTokenMode: (value: string) => value is "override" | "auto" | "static";
 /**
  * Options for adding a token.
  */

package/dist/src/core/token-manager.js

@@ -5,13 +5,23 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
-import { validateTokenName } from '../utils/validation.js';
+import { describeTokenNameProblem, makeEnumGuard } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 import { assertTokenCategoryExists, categoryHeaderExists, declareCategoryBanner, findCategorySection, findTokenDeclarationInRoot, } from './token-category.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 import { addTokenToDocs } from './token-docs.js';
 import { insertVariantDeclaration, validateVariantSelector, variantBlockExists, variantBlockHasToken, } from './token-variant.js';
+/**
+ * Dark mode behaviour for a token.
+ *
+ * Derived from {@link TOKEN_MODES} so the runtime allowlist and the type
+ * cannot drift: adding a member here without updating the list (or the
+ * reverse) is no longer possible, because there is only one list.
+ */
+export const TOKEN_MODES = ['auto', 'static', 'override'];
+/** Narrows an arbitrary string to a {@link TokenMode}. */
+export const isTokenMode = makeEnumGuard(TOKEN_MODES);
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export function getTokensCssPath(binaryName) {
     return `browser/themes/shared/${binaryName}-tokens.css`;
@@ -59,7 +69,7 @@ async function validateTokenPrefix(root, options) {
     }
 }
 function validateTokenNameSyntax(tokenName) {
-    const error = validateTokenName(tokenName);
+    const error = describeTokenNameProblem(tokenName);
     if (error) {
         throw new InvalidArgumentError(error, 'tokenName');
     }
@@ -117,11 +127,10 @@ async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant)
     return { added: true };
 }
 /**
- * Evaluates base-`:root` idempotency for one add: a token
- * already declared in the TARGET category skips; a token declared
- * anywhere else in the base block refuses loud — the pre-0.40.0
- * whole-file substring check silently skipped (and discarded
- * `--create-category`) in that case, exit 0.
+ * Evaluates base-`:root` idempotency for one add: a token already declared
+ * in the TARGET category skips; a token declared anywhere else in the base
+ * block refuses loud. A whole-file substring check instead skips silently —
+ * discarding `--create-category` — and exits 0.
  */
 function evaluateBaseTokenIdempotency(lines, options, tokensCssPath) {
     const existing = findTokenDeclarationInRoot(lines, options.tokenName);
@@ -241,7 +250,7 @@ export async function addToken(root, options) {
  * pair the media query with `:root[data-theme="dark"]` /
  * `:root[data-theme="light"]` blocks (viewer-toggle theming) require every
  * themed list to declare identical token sets, so an override add that only
- * wrote the media block was a guaranteed half-finished edit.
+ * wrote the media block would be a guaranteed half-finished edit.
  */
 const THEME_ATTRIBUTE_VARIANTS = [
     { variant: '[data-theme="dark"]', pick: 'dark' },

package/dist/src/core/token-scaffold.d.ts

@@ -1,14 +1,14 @@
 /**
  * Scaffolds the default tokens CSS file consumed by `fireforge token add`.
  *
- * Before 0.16.0 `fireforge furnace init` wrote `furnace.json` but not the
- * tokens CSS — every project's first `fireforge token add` hit
+ * Without it, `fireforge furnace init` writes `furnace.json` but not the
+ * tokens CSS, and every project's first `fireforge token add` hits
  * `Token CSS file not found: browser/themes/shared/<binaryName>-tokens.css`.
- * The 0.16.0 init now calls into this module to write a canonical
- * `:root { … }` shell with a seed set of category headers that
- * `assertTokenCategoryExists` recognises, and registers the tokens CSS
- * path in `patchLint.rawColorAllowlist` so the first token that's an
- * actual color value does not instantly fail `fireforge lint`.
+ * Init calls into this module to write a canonical `:root { … }` shell with
+ * a seed set of category headers that `assertTokenCategoryExists`
+ * recognises, and registers the tokens CSS path in
+ * `patchLint.rawColorAllowlist` so the first token that is an actual color
+ * value does not instantly fail `fireforge lint`.
  */
 import type { ProjectLicense } from '../types/config.js';
 /**

package/dist/src/core/token-scaffold.js

@@ -2,14 +2,14 @@
 /**
  * Scaffolds the default tokens CSS file consumed by `fireforge token add`.
  *
- * Before 0.16.0 `fireforge furnace init` wrote `furnace.json` but not the
- * tokens CSS — every project's first `fireforge token add` hit
+ * Without it, `fireforge furnace init` writes `furnace.json` but not the
+ * tokens CSS, and every project's first `fireforge token add` hits
  * `Token CSS file not found: browser/themes/shared/<binaryName>-tokens.css`.
- * The 0.16.0 init now calls into this module to write a canonical
- * `:root { … }` shell with a seed set of category headers that
- * `assertTokenCategoryExists` recognises, and registers the tokens CSS
- * path in `patchLint.rawColorAllowlist` so the first token that's an
- * actual color value does not instantly fail `fireforge lint`.
+ * Init calls into this module to write a canonical `:root { … }` shell with
+ * a seed set of category headers that `assertTokenCategoryExists`
+ * recognises, and registers the tokens CSS path in
+ * `patchLint.rawColorAllowlist` so the first token that is an actual color
+ * value does not instantly fail `fireforge lint`.
  */
 import { getLicenseHeader } from './license-headers.js';
 /**

package/dist/src/core/token-variant.d.ts

@@ -2,10 +2,10 @@
  * Attribute-variant block helpers for the tokens CSS scaffold.
  *
  * `fireforge token add --mode` can author the base `:root { }` block and the
- * dark `@media (prefers-color-scheme: dark)` block, but there was no way to
- * target an attribute-keyed selector such as `:root[data-skin="precision"]`
- * or `:root[data-private]` — forcing those override blocks to be hand-edited.
- * These helpers locate (or compute the insertion point for) a top-level
+ * dark `@media (prefers-color-scheme: dark)` block, but not an
+ * attribute-keyed selector such as `:root[data-skin="precision"]` or
+ * `:root[data-private]`, which would otherwise have to be hand-edited. These
+ * helpers locate (or compute the insertion point for) a top-level
  * `:root<variant>` block so `token-manager.ts` can splice a declaration into
  * it, keeping all token authoring in the CLI.
  */

package/dist/src/core/token-variant.js

@@ -3,10 +3,10 @@
  * Attribute-variant block helpers for the tokens CSS scaffold.
  *
  * `fireforge token add --mode` can author the base `:root { }` block and the
- * dark `@media (prefers-color-scheme: dark)` block, but there was no way to
- * target an attribute-keyed selector such as `:root[data-skin="precision"]`
- * or `:root[data-private]` — forcing those override blocks to be hand-edited.
- * These helpers locate (or compute the insertion point for) a top-level
+ * dark `@media (prefers-color-scheme: dark)` block, but not an
+ * attribute-keyed selector such as `:root[data-skin="precision"]` or
+ * `:root[data-private]`, which would otherwise have to be hand-edited. These
+ * helpers locate (or compute the insertion point for) a top-level
  * `:root<variant>` block so `token-manager.ts` can splice a declaration into
  * it, keeping all token authoring in the CLI.
  */