@hominis/fireforge 0.43.1 → 0.44.1

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.
  */
@@ -52,6 +52,28 @@ export function validateVariantSelector(raw) {
 function canonicalSelector(selector) {
     return selector.replace(/\s+/g, '').replace(/["']/g, '');
 }
+/**
+ * The `:root[…]` selector fragment on `line`, spanning to the LAST `]` that
+ * precedes the block's opening brace, or `null` when the line carries none.
+ *
+ * Index arithmetic rather than `/:root\[[^{]*\]/`: `[^{]` also matches `]`,
+ * so that pattern backtracks quadratically on a line repeating `:root[`
+ * (CodeQL `js/polynomial-redos`). Taking the last `]` — not the first —
+ * preserves the greedy regex's reach, so a multi-attribute selector still
+ * compares as the whole fragment and does not collide with a single-attribute
+ * variant that happens to be its prefix.
+ */
+function rootAttributeSelector(line) {
+    const start = line.indexOf(':root[');
+    if (start === -1)
+        return null;
+    const brace = line.indexOf('{', start);
+    const limit = brace === -1 ? line.length : brace;
+    const close = line.lastIndexOf(']', limit - 1);
+    if (close <= start + ':root['.length - 1)
+        return null;
+    return line.slice(start, close + 1);
+}
 /**
  * Finds the top-level `:root<variant>` block whose attribute selector
  * matches `variant` (compared canonically). Returns the opening-brace and
@@ -66,8 +88,8 @@ function findVariantBlock(lines, variant) {
     const want = canonicalSelector(`:root${variant}`);
     for (let i = 0; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
-        const match = /:root\[[^{]*\]/.exec(line);
-        if (!match || canonicalSelector(match[0]) !== want)
+        const selector = rootAttributeSelector(line);
+        if (selector === null || canonicalSelector(selector) !== want)
             continue;
         let openLine = /\{/.test(line) ? i : -1;
         if (openLine === -1) {

package/dist/src/core/toolchain-preflight.d.ts

@@ -1,30 +1,29 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox
- * MAJOR version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it — and the first `fireforge build` then dies a
- * few seconds into `mach configure` with a message whose remediation
- * text names `./mach bootstrap`, the wrong tool for a FireForge-managed
- * repo (152.0b7 → 153.0b8 source-refresh drill: `ERROR: cbindgen version
- * 0.29.1 is too old. At least version 0.29.4 is required.`).
+ * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * version, the tree's declared toolchain minimums (cbindgen, Rust)
+ * frequently move with it — and the first `fireforge build` then dies a few
+ * seconds into `mach configure` with a message whose remediation text names
+ * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
+ * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
+ * required.`).
  *
  * Two layers:
- *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when
- *     the downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
- *     the minimums the tree itself declares against the host binaries
+ *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when the
+ *     downloaded major differs from the previously downloaded one.
+ *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing the
+ *     minimums the tree itself declares against the host binaries
  *     `mach configure` will resolve, probing configure's own candidate
- *     order: env override first, then the `~/.mozbuild` state-directory
- *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
- *     only, blocking builds whose current tool lived in the state dir
- *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
- *     mismatch only when a minimum was positively parsed AND at least
- *     one candidate resolved AND every resolved candidate is
- *     definitively lower. Any uncertainty (file moved upstream,
- *     unparseable output, no candidate found) skips silently — the
- *     mach-error-hints translator still catches the real configure
- *     failure downstream.
+ *     order: env override first, then the `~/.mozbuild` state-directory copy
+ *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
+ *     whose current tool lives in the state dir behind a stale PATH copy.
+ *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
+ *     positively parsed AND at least one candidate resolved AND every
+ *     resolved candidate is definitively lower. Any uncertainty (file moved
+ *     upstream, unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure failure
+ *     downstream.
  */
 /** Tools the preflight knows how to probe. */
 export type ToolchainTool = 'cbindgen' | 'rustc';

package/dist/src/core/toolchain-preflight.js

@@ -2,30 +2,29 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox
- * MAJOR version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it — and the first `fireforge build` then dies a
- * few seconds into `mach configure` with a message whose remediation
- * text names `./mach bootstrap`, the wrong tool for a FireForge-managed
- * repo (152.0b7 → 153.0b8 source-refresh drill: `ERROR: cbindgen version
- * 0.29.1 is too old. At least version 0.29.4 is required.`).
+ * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * version, the tree's declared toolchain minimums (cbindgen, Rust)
+ * frequently move with it — and the first `fireforge build` then dies a few
+ * seconds into `mach configure` with a message whose remediation text names
+ * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
+ * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
+ * required.`).
  *
  * Two layers:
- *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when
- *     the downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
- *     the minimums the tree itself declares against the host binaries
+ *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when the
+ *     downloaded major differs from the previously downloaded one.
+ *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing the
+ *     minimums the tree itself declares against the host binaries
  *     `mach configure` will resolve, probing configure's own candidate
- *     order: env override first, then the `~/.mozbuild` state-directory
- *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
- *     only, blocking builds whose current tool lived in the state dir
- *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
- *     mismatch only when a minimum was positively parsed AND at least
- *     one candidate resolved AND every resolved candidate is
- *     definitively lower. Any uncertainty (file moved upstream,
- *     unparseable output, no candidate found) skips silently — the
- *     mach-error-hints translator still catches the real configure
- *     failure downstream.
+ *     order: env override first, then the `~/.mozbuild` state-directory copy
+ *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
+ *     whose current tool lives in the state dir behind a stale PATH copy.
+ *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
+ *     positively parsed AND at least one candidate resolved AND every
+ *     resolved candidate is definitively lower. Any uncertainty (file moved
+ *     upstream, unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure failure
+ *     downstream.
  */
 import { execFile } from 'node:child_process';
 import { homedir } from 'node:os';
@@ -61,16 +60,14 @@ const MINIMUM_DECLARATIONS = {
 /**
  * How each tool's host binary is resolved and its version parsed.
  *
- * `stateDirRelPaths` are the mach-state-directory locations `fireforge
- * bootstrap` (via mozboot) installs the tool to. mach's configure tries
- * the state directory BEFORE the PATH candidates (bindgen.configure's
- * toolchain search path lists `~/.mozbuild/cbindgen/cbindgen` first — a
- * configure log shows `trying cbindgen: ~/.mozbuild/cbindgen/cbindgen`
- * ahead of PATH), so the probe must too. 0.35.0 probed only env-or-PATH,
- * which failed a build configure would have accepted whenever an old
- * `~/.cargo/bin/cbindgen` shadowed a current bootstrap-installed copy
- * (field report: PATH 0.29.1 vs mozbuild 0.29.4, minimum 0.29.4). Rust
- * has no state-dir install — rustup owns it — so its list is empty.
+ * `stateDirRelPaths` are the mach-state-directory locations
+ * `fireforge bootstrap` (via mozboot) installs the tool to. mach's configure
+ * tries the state directory BEFORE the PATH candidates —
+ * bindgen.configure's toolchain search path lists `~/.mozbuild/cbindgen/
+ * cbindgen` first — so the probe must too. Probing only env-or-PATH fails a
+ * build configure would have accepted whenever an old `~/.cargo/bin/
+ * cbindgen` shadows a current bootstrap-installed copy. Rust has no
+ * state-dir install — rustup owns it — so its list is empty.
  */
 const HOST_PROBES = {
     // `mach configure` honours the CBINDGEN env option (bindgen.configure's

package/dist/src/core/tree-guard.js

@@ -15,7 +15,7 @@
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { GeneralError } from '../errors/base.js';
-import { getTreeMarkerPath, readTreeMarkerState, } from './tree-store.js';
+import { getTreeMarkerPath, readTreeMarker, } from './tree-store.js';
 /**
  * Per-command verdicts. `allowed` runs unconditionally; `refused` never
  * runs in a tree; `conditional` consults `TREE_CONDITIONAL_CHECKS` with
@@ -135,7 +135,7 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
         let current = resolve(process.cwd());
         for (let depth = 0; depth < 50; depth++) {
             if (existsSync(join(current, 'fireforge.json'))) {
-                return { root: current, state: await readTreeMarkerState(current) };
+                return { root: current, state: await readTreeMarker(current) };
             }
             const parent = dirname(current);
             if (parent === current)
@@ -153,6 +153,16 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
     // evidence that we cannot tell. Treating it as "not a tree" would grant the
     // full mutating command set to a snapshot on the strength of a file that
     // failed to parse, which is exactly backwards for a default-deny guard.
+    // A marker from a NEWER FireForge is not damaged, so the corrupt branch's
+    // remedies — recreate the tree, delete the stray marker — are actively
+    // wrong for it. Refuse with the upgrade instruction instead, and do NOT
+    // offer --ignore-corrupt-tree-marker: proceeding would mean acting on a
+    // marker whose fields this build does not understand.
+    if (state.kind === 'unsupported') {
+        if (TREE_COMMAND_VERDICTS[commandName] === 'allowed')
+            return;
+        throw new GeneralError(`Refusing "${[commandName, ...subcommands].join(' ')}": ${state.reason}`);
+    }
     if (state.kind === 'corrupt') {
         if (options['ignoreCorruptTreeMarker'] === true)
             return;

package/dist/src/core/tree-store.d.ts

@@ -33,13 +33,13 @@ export declare function withTreeLifecycleLock<T>(primaryRoot: string, operation:
  * Outcome of reading a tree marker.
  *
  * The three states must stay distinct because they carry opposite safety
- * meanings. `absent` means "this directory is not a tree", which is what lets
- * every mutating command run. `corrupt` means "this directory claims to be a
- * tree but we cannot read the claim" — collapsing it into `absent` (as a bare
- * `undefined` return does) hands a snapshot the full mutating command set on
- * the strength of a file we failed to parse, inverting `tree-guard.ts`'s
- * default-deny design. Deleting one field from a marker was enough to run
- * `reset` inside a clone.
+ * meanings. `absent` means "this directory is not a tree", which is what
+ * lets every mutating command run. `corrupt` means "this directory claims to
+ * be a tree but we cannot read the claim" — collapsing it into `absent` (as
+ * a bare `undefined` return does) hands a snapshot the full mutating command
+ * set on the strength of a file we failed to parse, inverting
+ * `tree-guard.ts`'s default-deny design. Deleting one field from a marker is
+ * enough to make `reset` runnable inside a clone.
  */
 export type TreeMarkerRead = {
     kind: 'absent';
@@ -49,31 +49,45 @@ export type TreeMarkerRead = {
 } | {
     kind: 'corrupt';
     reason: string;
+}
+/**
+ * Written by a NEWER FireForge. Distinct from `corrupt` because the remedy
+ * is the opposite: upgrade, do not delete.
+ */
+ | {
+    kind: 'unsupported';
+    reason: string;
 };
 /** Absolute path of a root's tree marker. */
 export declare function getTreeMarkerPath(root: string): string;
 /**
  * Reads the tree marker for a project root, distinguishing "not a tree" from
- * "a tree whose marker we could not read". Callers that make a safety decision
- * (the guard hook, the no-nesting refusal) must use this rather than
- * {@link readTreeMarker}.
+ * "a tree whose marker we could not read". Callers that make a safety
+ * decision (the guard hook, the no-nesting refusal) must use this rather
+ * than {@link tryReadTreeMarker}.
  *
  * Only ENOENT/ENOTDIR mean `absent`: any other probe failure (EACCES on the
  * `.fireforge` directory, EIO, …) reports `corrupt`, because "we cannot read
  * the marker" is not evidence that there is no marker — a `pathExists`
- * pre-check here classified a tree with an unreadable `.fireforge` as
- * `absent` and handed it the full mutating command set.
+ * pre-check classifies a tree with an unreadable `.fireforge` as `absent`
+ * and hands it the full mutating command set.
  */
-export declare function readTreeMarkerState(root: string): Promise<TreeMarkerRead>;
+/**
+ * Naming convention for state-file readers:
+ *   - `readX(): Promise<XRead>` — the TRI-STATE read: absent, corrupt, or
+ *     valid.
+ *   - `tryReadX(): Promise<X | undefined>` — collapses absent and corrupt.
+ */
+export declare function readTreeMarker(root: string): Promise<TreeMarkerRead>;
 /**
  * Reads the tree marker for a project root, or undefined when it is absent
  * OR unreadable.
  *
  * For display and best-effort paths only (`tree list` renders an unreadable
  * marker as staleness 'unknown'). Anything that decides whether a mutation may
- * proceed must call {@link readTreeMarkerState} and handle `corrupt`.
+ * proceed must call {@link readTreeMarker} and handle `corrupt`.
  */
-export declare function readTreeMarker(root: string): Promise<TreeMarker | undefined>;
+export declare function tryReadTreeMarker(root: string): Promise<TreeMarker | undefined>;
 /**
  * Refuses a build-less in-tree `test` when the objdir preflight found is not
  * the one this tree's marker vouched for as rewritten-and-reconfigured. A
@@ -92,18 +106,18 @@ export declare function computePrimaryFingerprint(primaryRoot: string): Promise<
 /** Validates a tree name: one path segment, no traversal. */
 export declare function assertValidTreeName(name: string): void;
 /**
- * Materialises the tree at `treeRoot` from `primaryRoot` using
- * `capability` ('none' = plain copy, already gated on --force-copy by
- * the caller). The engine is cloned one TOP-LEVEL entry at a time so unwanted
- * `obj-*` directories are never traversed or materialised. That distinction
- * is substantial on Firefox trees: even CoW-cloning and deleting an objdir
- * touches metadata for millions of build outputs. With `withObjdir` exactly
- * that objdir is included — after {@link assertCloneSafeObjdir}
- * refuses symlinked or engine-escaping objdirs before any copying —
- * rewritten to the tree (see below), and
- * reconfigured in-tree via the caller-supplied `reconfigure` hook. A
- * fresh `.fireforge/` is created with only `state.json` (when present),
- * the last-build baseline (withObjdir only), and the tree marker.
+ * Materialises the tree at `treeRoot` from `primaryRoot` using `capability`
+ * ('none' = plain copy, already gated on --force-copy by the caller).
+ *
+ * The engine is cloned one TOP-LEVEL entry at a time so unwanted `obj-*`
+ * directories are never traversed or materialised — on a Firefox tree, even
+ * CoW-cloning and then deleting an objdir touches metadata for millions of
+ * build outputs. With `withObjdir` exactly that objdir is included (after
+ * {@link assertCloneSafeObjdir} refuses symlinked or engine-escaping objdirs
+ * before any copying), rewritten to the tree, and reconfigured in-tree via
+ * the caller-supplied `reconfigure` hook. A fresh `.fireforge/` is created
+ * with only `state.json` (when present), the last-build baseline (withObjdir
+ * only), and the tree marker.
  */
 export declare function cloneTree(args: {
     primaryRoot: string;