@hominis/fireforge 0.44.2 → 0.44.4

package/dist/src/core/engine-changes.d.ts

@@ -20,3 +20,21 @@ import type { BuildBaseline } from './build-baseline-types.js';
  * @returns Sorted engine-relative POSIX paths
  */
 export declare function collectChangedEnginePaths(engineDir: string, baseline: BuildBaseline | undefined, contextLabel: string): Promise<string[]>;
+/**
+ * Drops every path whose live content still matches the fingerprint the
+ * last successful build recorded for it, keeping the rest. Shared by the
+ * stale-build preflight (`packageableFingerprints`) and the auto-configure /
+ * full-build escalation in `build-prepare` (`buildInputFingerprints`).
+ *
+ * A path with no recorded entry, an unreadable file, or a differing hash
+ * is kept — "cannot prove unchanged" must never turn into "unchanged".
+ * With no fingerprint set at all (a baseline written before the field
+ * existed) every path is kept, which is the path-only comparison the
+ * fingerprints refine.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param paths - Candidate engine-relative POSIX paths
+ * @param fingerprints - Recorded hashes keyed by engine-relative path
+ * @returns The subset of `paths` that cannot be proven unchanged
+ */
+export declare function dropPathsMatchingFingerprints(engineDir: string, paths: readonly string[], fingerprints: Record<string, string> | undefined): Promise<string[]>;

package/dist/src/core/engine-changes.js

@@ -6,6 +6,7 @@
  */
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
+import { hashEngineFile } from './coverage-extend.js';
 import { hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
@@ -59,3 +60,36 @@ export async function collectChangedEnginePaths(engineDir, baseline, contextLabe
     }
     return [...collected].sort();
 }
+/**
+ * Drops every path whose live content still matches the fingerprint the
+ * last successful build recorded for it, keeping the rest. Shared by the
+ * stale-build preflight (`packageableFingerprints`) and the auto-configure /
+ * full-build escalation in `build-prepare` (`buildInputFingerprints`).
+ *
+ * A path with no recorded entry, an unreadable file, or a differing hash
+ * is kept — "cannot prove unchanged" must never turn into "unchanged".
+ * With no fingerprint set at all (a baseline written before the field
+ * existed) every path is kept, which is the path-only comparison the
+ * fingerprints refine.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param paths - Candidate engine-relative POSIX paths
+ * @param fingerprints - Recorded hashes keyed by engine-relative path
+ * @returns The subset of `paths` that cannot be proven unchanged
+ */
+export async function dropPathsMatchingFingerprints(engineDir, paths, fingerprints) {
+    if (!fingerprints)
+        return [...paths];
+    const kept = [];
+    for (const path of paths) {
+        const recorded = fingerprints[path];
+        if (recorded === undefined) {
+            kept.push(path);
+            continue;
+        }
+        const live = await hashEngineFile(engineDir, path);
+        if (live === undefined || live !== recorded)
+            kept.push(path);
+    }
+    return kept;
+}

package/dist/src/core/furnace-constants.d.ts

@@ -12,12 +12,33 @@ export declare const JAR_MN = "toolkit/content/jar.mn";
 export declare const WIDGETS_DIR = "toolkit/content/widgets";
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export declare const FTL_DIR = "toolkit/locales/en-US/toolkit/global";
+/**
+ * Engine-relative root every browser-chrome / xpcshell test scaffold lives
+ * under, trailing slash included. A `--test-dir` override must stay below
+ * it so the `browser/base/moz.build` manifest registration keeps working.
+ */
+export declare const BROWSER_TEST_SCAFFOLD_ROOT = "browser/base/content/test/";
 /**
  * Returns the engine-relative directory that holds xpcshell scaffolds for
  * a given binary. Matches the form `create-xpcshell.ts` writes and the
  * path `remove.ts` / `rename.ts` / `validate.ts` must clean up.
  */
 export declare function xpcshellTestParentDir(binaryName: string): string;
+/**
+ * Resolves the engine-relative directory a browser-chrome scaffold is
+ * written to: the `--test-dir` override when given, else
+ * `browser/base/content/test/<binaryName>`. The scaffolder AND the
+ * dry-run / success formatters resolve through this one function, so the
+ * printed plan cannot disagree with the files that land on disk.
+ */
+export declare function resolveBrowserChromeTestDir(binaryName: string, override?: string): string;
+/**
+ * Resolves the engine-relative directory an xpcshell scaffold is written
+ * to. A `--test-dir` override names the FINAL directory (no per-component
+ * segment is appended); the default is
+ * `browser/base/content/test/<binaryName>-xpcshell/<componentName>`.
+ */
+export declare function resolveXpcshellTestDir(binaryName: string, componentName: string, override?: string): string;
 /** Returns true when `fileName` has one of the standard component file extensions. */
 export declare function isComponentSourceFile(fileName: string): boolean;
 /**

package/dist/src/core/furnace-constants.js

@@ -13,6 +13,12 @@ export const JAR_MN = 'toolkit/content/jar.mn';
 export const WIDGETS_DIR = 'toolkit/content/widgets';
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
+/**
+ * Engine-relative root every browser-chrome / xpcshell test scaffold lives
+ * under, trailing slash included. A `--test-dir` override must stay below
+ * it so the `browser/base/moz.build` manifest registration keeps working.
+ */
+export const BROWSER_TEST_SCAFFOLD_ROOT = 'browser/base/content/test/';
 /**
  * Suffix for the per-binary xpcshell scaffold parent directory. Components
  * created with `furnace create --with-tests --xpcshell` land at
@@ -27,7 +33,26 @@ const XPCSHELL_TEST_DIR_SUFFIX = '-xpcshell';
  * path `remove.ts` / `rename.ts` / `validate.ts` must clean up.
  */
 export function xpcshellTestParentDir(binaryName) {
-    return `browser/base/content/test/${binaryName}${XPCSHELL_TEST_DIR_SUFFIX}`;
+    return `${BROWSER_TEST_SCAFFOLD_ROOT}${binaryName}${XPCSHELL_TEST_DIR_SUFFIX}`;
+}
+/**
+ * Resolves the engine-relative directory a browser-chrome scaffold is
+ * written to: the `--test-dir` override when given, else
+ * `browser/base/content/test/<binaryName>`. The scaffolder AND the
+ * dry-run / success formatters resolve through this one function, so the
+ * printed plan cannot disagree with the files that land on disk.
+ */
+export function resolveBrowserChromeTestDir(binaryName, override) {
+    return override ?? `${BROWSER_TEST_SCAFFOLD_ROOT}${binaryName}`;
+}
+/**
+ * Resolves the engine-relative directory an xpcshell scaffold is written
+ * to. A `--test-dir` override names the FINAL directory (no per-component
+ * segment is appended); the default is
+ * `browser/base/content/test/<binaryName>-xpcshell/<componentName>`.
+ */
+export function resolveXpcshellTestDir(binaryName, componentName, override) {
+    return override ?? `${xpcshellTestParentDir(binaryName)}/${componentName}`;
 }
 /** File extensions that constitute a Furnace component's source files. */
 const COMPONENT_FILE_EXTENSIONS = ['.mjs', '.css', '.ftl'];

package/dist/src/core/license-headers.d.ts

@@ -69,7 +69,9 @@ export declare function hasUpstreamMplBlockHeader(content: string): boolean;
 export declare function hasAnyLicenseHeaderAnyStyle(content: string): boolean;
 /**
  * Returns true if the first few lines of `content` contain a recognized
- * upstream license identifier string.
+ * upstream license identifier string — Mozilla's MPL boilerplate, an SPDX
+ * tag, the common permissive/copyleft license names, or the CC0
+ * public-domain dedication upstream test files carry.
  *
  * @param content  - File content to check
  * @param maxLines - Number of leading lines to inspect (default 10)
@@ -77,10 +79,12 @@ export declare function hasAnyLicenseHeaderAnyStyle(content: string): boolean;
 export declare function containsUpstreamLicenseText(content: string, maxLines?: number): boolean;
 /**
  * Returns true when the head of `content` carries a recognized THIRD-PARTY
- * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0), in any
- * comment style. Used by `export` to treat such files as vendored: offering
- * to prepend the project's own license header onto a byte-identity-pinned
- * upstream bundle would mislicense third-party code.
+ * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0) or the
+ * CC0 public-domain dedication, in any comment style. Used by `export` to
+ * treat such files as vendored: offering to prepend the project's own
+ * license header onto a byte-identity-pinned upstream bundle — or onto a
+ * test file Mozilla dedicated to the public domain — would mislicense code
+ * the project does not own.
  *
  * @param content  - File content to check
  * @param maxLines - Number of leading lines to inspect (default 30 — full

package/dist/src/core/license-headers.js

@@ -227,9 +227,31 @@ function normalizeLicenseHeadForScan(head) {
     s = s.replace(/\n[ \t]*\*[ \t]*/g, ' ');
     return s.replace(/\s+/g, ' ').trim();
 }
+/**
+ * Recognizes the CC0 public-domain dedication Mozilla puts on most of its
+ * test files, in every spelling the tree carries:
+ *
+ * - the prose (`Any copyright is dedicated to the Public Domain.`), which
+ *   the block, `//` and `#` comment forms all reduce to after
+ *   {@link normalizeLicenseHeadForScan};
+ * - the dedication URL (`creativecommons.org/publicdomain/zero/1.0/`, with
+ *   either scheme);
+ * - the SPDX identifier `CC0-1.0`.
+ *
+ * Deliberately narrow: a bare "public domain" mention, a different Creative
+ * Commons license (`licenses/by/4.0/`, `CC-BY-4.0`) or a made-up
+ * `publicdomain/zero/2.0/` is NOT a CC0 dedication and must not be
+ * accepted as one. `scanText` must already be normalized (and may be
+ * lowercased — the match is case-insensitive).
+ */
+function hasCc0Dedication(scanText) {
+    return /dedicated to the public domain|creativecommons\.org\/publicdomain\/zero\/1\.0|spdx-license-identifier:\s*cc0-1\.0\b/i.test(scanText);
+}
 /**
  * Returns true if the first few lines of `content` contain a recognized
- * upstream license identifier string.
+ * upstream license identifier string — Mozilla's MPL boilerplate, an SPDX
+ * tag, the common permissive/copyleft license names, or the CC0
+ * public-domain dedication upstream test files carry.
  *
  * @param content  - File content to check
  * @param maxLines - Number of leading lines to inspect (default 10)
@@ -244,14 +266,16 @@ export function containsUpstreamLicenseText(content, maxLines = 10) {
         'MIT License',
         'GNU General Public License',
     ];
-    return markers.some((marker) => scanText.includes(marker));
+    return markers.some((marker) => scanText.includes(marker)) || hasCc0Dedication(scanText);
 }
 /**
  * Returns true when the head of `content` carries a recognized THIRD-PARTY
- * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0), in any
- * comment style. Used by `export` to treat such files as vendored: offering
- * to prepend the project's own license header onto a byte-identity-pinned
- * upstream bundle would mislicense third-party code.
+ * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0) or the
+ * CC0 public-domain dedication, in any comment style. Used by `export` to
+ * treat such files as vendored: offering to prepend the project's own
+ * license header onto a byte-identity-pinned upstream bundle — or onto a
+ * test file Mozilla dedicated to the public domain — would mislicense code
+ * the project does not own.
  *
  * @param content  - File content to check
  * @param maxLines - Number of leading lines to inspect (default 30 — full
@@ -271,7 +295,9 @@ export function hasThirdPartyPermissiveBanner(content, maxLines = 30) {
     ];
     if (markers.some((marker) => scanText.includes(marker)))
         return true;
-    return /spdx-license-identifier:\s*(mit|isc|bsd-2-clause|bsd-3-clause|apache-2\.0)\b/.test(scanText);
+    if (hasCc0Dedication(scanText))
+        return true;
+    return /spdx-license-identifier:\s*(mit|isc|bsd-2-clause|bsd-3-clause|apache-2\.0|cc0-1\.0)\b/.test(scanText);
 }
 /**
  * Prepends the license header to a file on disk if it is not already present.

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

@@ -27,7 +27,7 @@ import { verbose, warn } from '../utils/logger.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
-import { collectChangedEnginePaths } from './engine-changes.js';
+import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
 export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
@@ -60,18 +60,7 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     // 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 = [];
-        for (const path of packageable) {
-            const recorded = fingerprints[path];
-            const live = await hashEngineFile(engineDir, path);
-            if (recorded === undefined || live === undefined || recorded !== live) {
-                staleAfterHashCheck.push(path);
-            }
-        }
-        packageable = staleAfterHashCheck;
-    }
+    packageable = await dropPathsMatchingFingerprints(engineDir, packageable, baseline.packageableFingerprints);
     if (packageable.length === 0) {
         return { stale: false, changedPaths: [], truncated: 0, baseline };
     }

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

@@ -23,10 +23,20 @@ export type VariantValidation = {
     reason: string;
 };
 /**
- * Validates a `--variant` attribute selector fragment and normalizes any
- * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Validates a `--variant` selector fragment and normalizes any `=value`
+ * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
+ * Structure is decided by {@link rootAttributeSelector} — the matcher's own
+ * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
+ * tail, and the validator did not move with it, so
+ * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
+ * could FIND but would not let you NAME. Running both halves off one parse
+ * is what stops them drifting apart again. Character-level safety stays a
+ * separate, per-group check, because the matcher finds bracket boundaries
+ * and validates no characters at all.
+ *
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export declare function validateVariantSelector(raw: unknown): VariantValidation;

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

@@ -12,36 +12,113 @@
  */
 import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
 /**
- * Accepts a single attribute selector fragment: `[data-private]` (boolean
- * attribute) or `[data-skin=precision]` / `[data-skin="precision"]`
- * (attribute with value). The value half is restricted to identifier-safe
+ * ONE attribute selector fragment: `[data-private]` (boolean attribute) or
+ * `[data-skin=precision]` / `[data-skin="precision"]` (attribute with
+ * value). The name and value halves are restricted to identifier-safe
  * characters so the fragment can be spliced into CSS verbatim without
  * escaping concerns.
+ *
+ * A multi-fragment variant is checked one group at a time (see
+ * {@link splitAttributeGroups}) rather than by wrapping this in a `+`: the
+ * repeated form is the shape CodeQL flags as `js/polynomial-redos`, and the
+ * split the matcher already performs is available for free.
+ */
+const ATTRIBUTE_FRAGMENT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
+/**
+ * A pseudo-class tail: `:not(…)`, `:hover`, and friends. The parenthesised
+ * argument is captured rather than validated here — it is a fragment run of
+ * its own and goes through the same per-group check.
  */
-const VARIANT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
+const QUALIFIER_PATTERN = /^:[a-zA-Z][a-zA-Z0-9-]*(?:\(([^()]*)\))?$/;
 /**
- * Validates a `--variant` attribute selector fragment and normalizes any
- * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Splits a run of consecutive attribute fragments into its groups, or
+ * returns `null` when the run is not exactly that — a group that does not
+ * open with `[`, an unclosed group, an empty run, or a group whose name or
+ * value is not identifier-safe.
+ *
+ * @param run - The `[…][…]` text with no `:root` prefix
+ * @returns The individual fragments, or null when the run is not valid
+ */
+function splitAttributeGroups(run) {
+    const groups = [];
+    let cursor = 0;
+    while (cursor < run.length) {
+        if (run[cursor] !== '[')
+            return null;
+        const close = run.indexOf(']', cursor);
+        if (close === -1)
+            return null;
+        const group = run.slice(cursor, close + 1);
+        if (!ATTRIBUTE_FRAGMENT_PATTERN.test(group))
+            return null;
+        groups.push(group);
+        cursor = close + 1;
+    }
+    return groups.length > 0 ? groups : null;
+}
+/** Rewrites `=value` / `='value'` to the double-quoted Mozilla convention. */
+function normalizeAttributeFragment(group) {
+    return group
+        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
+        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
+}
+/**
+ * Validates a `--variant` selector fragment and normalizes any `=value`
+ * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
+ * Structure is decided by {@link rootAttributeSelector} — the matcher's own
+ * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
+ * tail, and the validator did not move with it, so
+ * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
+ * could FIND but would not let you NAME. Running both halves off one parse
+ * is what stops them drifting apart again. Character-level safety stays a
+ * separate, per-group check, because the matcher finds bracket boundaries
+ * and validates no characters at all.
+ *
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export function validateVariantSelector(raw) {
     if (typeof raw !== 'string') {
         return { ok: false, reason: 'must be a string when set' };
     }
+    const reject = {
+        ok: false,
+        reason: 'must be one or more attribute selectors like [data-private], [data-skin=precision] ' +
+            'or [data-skin=precision][data-theme=dark], optionally followed by a pseudo-class ' +
+            'such as :not([data-private]) (identifier-safe attribute names and values only)',
+    };
     const value = raw.trim();
-    if (!VARIANT_PATTERN.test(value)) {
-        return {
-            ok: false,
-            reason: 'must be a single attribute selector like [data-private] or [data-skin=precision] ' +
-                '(identifier-safe attribute name and value only)',
-        };
+    if (value === '')
+        return reject;
+    const parts = rootAttributeSelector(`:root${value} {`);
+    // The parse must have consumed the WHOLE fragment: anything it declined to
+    // read (a stray space, a trailing combinator) is text the matcher would
+    // not see either, so accepting it would author a block nothing can find.
+    if (parts === null || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
+        return reject;
+    const groups = splitAttributeGroups(parts.attributes.slice(':root'.length));
+    if (groups === null)
+        return reject;
+    let qualifier = '';
+    if (parts.qualifier !== '') {
+        const match = QUALIFIER_PATTERN.exec(parts.qualifier);
+        if (match === null)
+            return reject;
+        const inner = match[1];
+        if (inner === undefined) {
+            qualifier = parts.qualifier;
+        }
+        else {
+            const innerGroups = splitAttributeGroups(inner);
+            if (innerGroups === null)
+                return reject;
+            const name = parts.qualifier.slice(0, parts.qualifier.indexOf('('));
+            qualifier = `${name}(${innerGroups.map(normalizeAttributeFragment).join('')})`;
+        }
     }
-    const normalized = value
-        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
-        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
-    return { ok: true, value: normalized };
+    return { ok: true, value: `${groups.map(normalizeAttributeFragment).join('')}${qualifier}` };
 }
 /**
  * Reduces a `:root<attr>` selector to a quote- and whitespace-insensitive
@@ -105,12 +182,24 @@ function rootAttributeSelector(line) {
  */
 function findVariantBlock(lines, variant) {
     const stripped = stripBlockCommentsInLines(lines);
-    const want = canonicalSelector(`:root${variant}`);
+    // The request goes through the same parse as the candidate lines, so a
+    // variant carrying its own `:not(…)` tail is compared tail-to-tail rather
+    // than being folded into the attribute run — where it would match nothing
+    // and every add would splice a fresh duplicate block.
+    const requested = rootAttributeSelector(`:root${variant} {`);
+    const want = canonicalSelector(requested?.attributes ?? `:root${variant}`);
+    const wantQualifier = canonicalSelector(requested?.qualifier ?? '');
     for (let i = 0; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
         const selector = rootAttributeSelector(line);
         if (selector === null || canonicalSelector(selector.attributes) !== want)
             continue;
+        // An UNqualified request still matches a qualified block: that is the
+        // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
+        // silently skipping the block is the worse failure. A request that names
+        // a qualifier, though, means it — so it must match.
+        if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)
+            continue;
         let openLine = /\{/.test(line) ? i : -1;
         if (openLine === -1) {
             for (let j = i + 1; j < stripped.length; j++) {

package/docs/README.md

@@ -0,0 +1,35 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# FireForge documentation
+
+[`../README.md`](../README.md) is the getting-started page. These files are
+the reference material behind it. `fireforge --help` (and
+`fireforge <command> --help`) stays the authority on flags; the docs cover
+what a flag list cannot state.
+
+## Using FireForge
+
+| File                                           | Covers                                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [patch-workflow.md](patch-workflow.md)         | Export, re-export, deletions, queue maintenance, per-patch lint, CI gating, rebasing |
+| [testing.md](testing.md)                       | `fireforge test`: scope, modes, build freshness, the verdict line, verbosity         |
+| [furnace.md](furnace.md)                       | Components: overrides, shared CSS fragments, typed cross-module imports              |
+| [verification-trees.md](verification-trees.md) | CoW snapshots for concurrent read-mostly verification                                |
+| [configuration.md](configuration.md)           | `fireforge.json` settings, design tokens, lock waits, environment variables          |
+
+## Contracts for scripts and CI
+
+| File                                   | Covers                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| [exit-codes.md](exit-codes.md)         | Every exit code, which error class produces it, and how CI should branch    |
+| [machine-output.md](machine-output.md) | The `--json` / `--raw` / verdict-line output contract and its versioning    |
+| [run-logs.md](run-logs.md)             | `.fireforge/logs/`: what `test` and `build` write, and what survives a pipe |
+
+## Internals
+
+| File                                               | Covers                                                                       |
+| -------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [lifecycle-invariants.md](lifecycle-invariants.md) | Locking, rollback, signal handling, and the decision table for new mutations |
+
+Release history and the reasoning behind individual changes live in
+[`../CHANGELOG.md`](../CHANGELOG.md).

package/docs/configuration.md

@@ -0,0 +1,116 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Configuration
+
+`fireforge.json` at the project root is the project's configuration;
+`furnace.json` holds component configuration. This file covers the settings
+whose behaviour needs more than a schema line, plus the environment variables
+FireForge reads.
+
+## External toolchains
+
+Projects with generated asset prerequisites can declare opt-in
+`externalToolchains`. `fireforge doctor` reports missing **required** tools as
+errors and missing **optional** tools as warnings.
+
+Seasonal branding on macOS, for example, can declare Apple's Icon Composer
+tool at
+`/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool`,
+plus `actool` via `xcrun`, `sips`, and `iconutil`.
+
+## `patchLint`
+
+Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals
+shim that tracks upstream WebIDL additions per release.
+
+- `patchLint.checkJsExtraShim` adds members to the structured shim globals via
+  TypeScript interface merging, e.g.
+  `interface ChromeUtilsShim { newApi(): any }`.
+- `patchLint.checkJsTestFiles: true` extends the pass to patch-owned test
+  `.js` files (`browser_*` / `test_*` / `xpcshell_*` and `/test/` paths). Each
+  is checked as its own small script-scope program against a loose built-in
+  harness shim.
+- `patchLint.checkJsTestShim` points at a project `.d.ts` whose typed
+  declarations (e.g. a real `TestUtils` interface) override the loose
+  baseline, so calls to nonexistent harness members fail at export time.
+
+## `patchPolicy`
+
+`patchPolicy.ranges` makes `patch compact` range-aware, so closing ordinal
+gaps does not move a patch out of the band its category owns.
+
+## `test`
+
+`test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
+`fireforge test --canary`. See [`testing.md`](testing.md).
+
+## Design tokens
+
+Tokens are managed with `fireforge token add`.
+
+- `--create-category` declares a new category banner and inserts the token in
+  one step. It is incompatible with `--variant`; author the category with the
+  base token first, then add each variant.
+- `--category` is required for a base declaration and optional under
+  `--variant`, where the declaration is routed into a `:root<selector>` block
+  and never into a category section. It is still validated when supplied.
+- `--variant` takes the same selector grammar the block matcher understands:
+  one attribute fragment (`[data-private]`, `[data-skin=precision]`), a run of
+  them (`[data-skin=precision][data-theme=dark]`), and an optional pseudo-class
+  tail (`[data-skin=precision]:not([data-private])`). Names and values must be
+  identifier-safe, and `=value` is normalized to `="value"`. A variant naming a
+  qualifier matches only a block carrying that qualifier; one without a
+  qualifier still matches a qualified block, and the write says so.
+- `--mode override` mirrors into both `:root[data-theme="dark"]` and
+  `:root[data-theme="light"]`. A qualified block such as
+  `:root[data-theme="light"]:not([data-private])` is matched and written
+  through, with a warning naming the selector — the qualifier is
+  semantically load-bearing, but silently skipping half the mirror is the
+  worse failure.
+- A token already present in the target block is reported with its location
+  (`already exists in :root[…] (line N), unchanged`) rather than a bare
+  no-op.
+
+## Smoke runs
+
+For unattended smoke checks, `fireforge run --smoke-exit <s> --headless`
+launches the browser headless. A headed smoke window on a shared desktop
+absorbs live input, which contaminates the console capture — headed non-CI
+launches print a warning saying so. Exit codes 12 and 13 separate a console
+regression from a launch failure; see [`exit-codes.md`](exit-codes.md).
+
+## Lock waits
+
+Every FireForge command that mutates the engine takes the engine-session lock,
+and some take a second subsystem lock as well. Contention fails fast after
+about a second by default.
+
+`--wait-lock [seconds]` (bare flag = 60, valid 1–3600) replaces that with a
+bounded wait, and the budget covers **every** lock the command takes — for
+`furnace apply`/`deploy`/`sync` that means the furnace lock as well as the
+engine-session lock. While waiting, a progress line roughly every 5 seconds
+identifies the holder by PID, command and start time.
+
+Commands that take no lock accept `--wait-lock` and ignore it, so a scripted
+sequence can blanket-append the flag without a usage error killing the run.
+
+`FIREFORGE_WAIT_LOCK=<seconds>` applies the same budget to every command in a
+session, using the same bounds as the flag. It is the only way to give a
+budget to the furnace mutators that declare no flag (`create`, `remove`,
+`rename`, `refresh`, `scan`, `override`, `chrome-doc`, …). An explicit
+`--wait-lock` always wins.
+
+`fireforge status --lock` reports the current holder and queue depth.
+
+## Environment variables
+
+| Variable                             | Effect                                                                                                                                  |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1–3600). See above.                                                                           |
+| `FIREFORGE_MAX_UNTRACKED_FILES`      | Per-directory cap when expanding collapsed untracked directories in `status` (default 5000). A non-positive value warns and is ignored. |
+| `FIREFORGE_GIT_ADD_TIMEOUT_MS`       | Timeout for the monolithic `git add -A` baseline pass (default 10 min). For slow or loaded filesystems.                                 |
+| `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` | Timeout for the chunked `git add -- <dir>` fallback (default 30 min). Paired with the above.                                            |
+
+`CLAUDECODE` is read by mozbuild, not by FireForge, and `fireforge test
+--full-output` unsets it for test dispatches only — see
+[`testing.md`](testing.md#output-verbosity).