@hominis/fireforge 0.16.2 → 0.16.3

package/dist/src/core/file-lock.js

@@ -43,23 +43,39 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
         const ageMs = Date.now() - lockStat.mtimeMs;
-        if (ageMs <= staleMs) {
-            return false;
-        }
-        // If the lock directory contains a PID file, check whether the owning
-        // process is still running before removing. This prevents premature
-        // removal when a slow operation (e.g. mach build) legitimately holds
-        // the lock past the stale threshold.
-        try {
-            const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-            const pid = parseInt(pidContent.trim(), 10);
-            if (Number.isFinite(pid) && isProcessAlive(pid)) {
-                verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${pid} is still running — not removing`);
-                return false;
+        // Check PID FIRST, independent of age. Before this ordering change the
+        // function age-gated everything: a lock younger than `staleMs` (default
+        // 5 minutes) was never removed even when its PID file pointed at a
+        // process that had already exited. That's the exact situation an
+        // operator lands in after SIGINT'ing `furnace preview` — the signal
+        // handler calls `process.exit`, `withFileLock`'s `finally { rm }`
+        // never runs, and the next command has to either wait 5 minutes for
+        // the staleness gate or manually remove the lock directory. With the
+        // PID-first check, an explicitly-dead owner unblocks immediately.
+        const pidCheck = await readLockOwnerPid(lockPath);
+        if (pidCheck.present) {
+            if (!isProcessAlive(pidCheck.pid)) {
+                const staleMessage = onStaleLockMessage?.(ageMs);
+                if (staleMessage) {
+                    warn(staleMessage);
+                }
+                else {
+                    verbose(`Lock at ${lockPath} owner PID ${pidCheck.pid} is no longer running — removing (age: ${Math.round(ageMs / 1000)}s)`);
+                }
+                await rm(lockPath, { recursive: true, force: true });
+                return true;
             }
+            // PID is alive — respect it regardless of age. A slow `mach build`
+            // legitimately holds the lock past the stale threshold and we don't
+            // want to race-remove it.
+            verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${pidCheck.pid} is still running — not removing`);
+            return false;
         }
-        catch {
-            // No PID file or unreadable — fall through to stale removal
+        // No readable PID file. Fall back to the age-only heuristic so locks
+        // written by earlier FireForge releases (which may not have written a
+        // PID file) still clear after the staleness window elapses.
+        if (ageMs <= staleMs) {
+            return false;
         }
         const staleMessage = onStaleLockMessage?.(ageMs);
         if (staleMessage) {
@@ -78,6 +94,24 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
         throw toError(error);
     }
 }
+/**
+ * Reads the owner PID from a lock directory's PID file. Returns `{ present:
+ * false }` when the PID file is missing or the content does not parse as a
+ * finite integer (caller falls back to the age-only staleness heuristic).
+ */
+async function readLockOwnerPid(lockPath) {
+    try {
+        const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
+        const pid = parseInt(pidContent.trim(), 10);
+        if (Number.isFinite(pid)) {
+            return { present: true, pid };
+        }
+    }
+    catch {
+        // PID file missing or unreadable — treat as absent.
+    }
+    return { present: false };
+}
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
 export async function withFileLock(lockPath, operation, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;

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

@@ -74,6 +74,23 @@ export declare function rollbackActiveOperationsForSignal(signal: FurnaceShutdow
  * touch this directly.
  */
 export declare function getFurnaceLockPath(root: string): string;
+/**
+ * Forcibly removes the furnace lock directory for every active operation.
+ *
+ * The bin-layer signal handler calls `process.exit` after rollback, which
+ * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
+ * }` never runs, so the lock directory survives the process. The next
+ * FireForge command then has to either wait out the staleness window or
+ * have the operator remove the lock manually. This sweeper runs inside
+ * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * by the time the next command starts.
+ *
+ * Errors are logged and swallowed: we do not want a slow I/O failure at
+ * shutdown to prevent the process from exiting. The doctor-side stale
+ * lock check (`src/commands/doctor-furnace.ts`) is the backup path for
+ * any lock that escapes this sweep.
+ */
+export declare function forceReleaseFurnaceLocksForActiveOperations(): Promise<void>;
 /**
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents

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

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
-import { warn } from '../utils/logger.js';
+import { verbose, warn } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { withFileLock } from './file-lock.js';
 import { loadFurnaceState, updateFurnaceState } from './furnace-config.js';
@@ -136,6 +137,34 @@ async function persistPendingRepair(root, operation, reason) {
 export function getFurnaceLockPath(root) {
     return join(root, FIREFORGE_DIR, FURNACE_LOCK_FILENAME);
 }
+/**
+ * Forcibly removes the furnace lock directory for every active operation.
+ *
+ * The bin-layer signal handler calls `process.exit` after rollback, which
+ * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
+ * }` never runs, so the lock directory survives the process. The next
+ * FireForge command then has to either wait out the staleness window or
+ * have the operator remove the lock manually. This sweeper runs inside
+ * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * by the time the next command starts.
+ *
+ * Errors are logged and swallowed: we do not want a slow I/O failure at
+ * shutdown to prevent the process from exiting. The doctor-side stale
+ * lock check (`src/commands/doctor-furnace.ts`) is the backup path for
+ * any lock that escapes this sweep.
+ */
+export async function forceReleaseFurnaceLocksForActiveOperations() {
+    const paths = new Set([...activeOperations.values()].map((op) => getFurnaceLockPath(op.root)));
+    for (const lockPath of paths) {
+        try {
+            await rm(lockPath, { recursive: true, force: true });
+            verbose(`Removed furnace lock at ${lockPath} during signal teardown`);
+        }
+        catch (error) {
+            verbose(`Could not remove furnace lock at ${lockPath} during signal teardown: ${toError(error).message}`);
+        }
+    }
+}
 /**
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents

package/dist/src/core/furnace-validate-helpers.d.ts

@@ -61,7 +61,39 @@ export declare function stripCssBlockComments(content: string): string;
 export declare function hasRelativeModuleImport(mjsContent: string): boolean;
 /** Detects whether a module defines a custom element at runtime. */
 export declare function hasCustomElementDefineCall(mjsContent: string): boolean;
-/** Checks whether a declared component class extends MozLitElement. */
+/**
+ * Detects whether the module's `customElements.define(...)` call includes a
+ * literal `extends:` option (third argument). That shape is the marker for
+ * a customized built-in element — the class extends a specific
+ * `HTMLxxxElement` rather than the autonomous `MozLitElement` path.
+ *
+ * Firefox's own widgets use this pattern for toolkit anchors (e.g.
+ * `moz-support-link` extends `HTMLAnchorElement` with
+ * `customElements.define("moz-support-link", ..., { extends: "a" })`), and
+ * the validator's `not-moz-lit-element` check must allow them through or
+ * `furnace override` of a valid upstream component fails its own
+ * `furnace validate` pass with nothing the operator can fix.
+ */
+export declare function hasCustomElementExtendsOption(mjsContent: string): boolean;
+/**
+ * Checks whether a declared component class extends a valid element base.
+ *
+ * Two shapes are accepted:
+ *
+ * 1. Autonomous custom element: `class X extends MozLitElement` — the
+ *    default FireForge pattern for fork-authored components and most
+ *    toolkit widgets.
+ * 2. Customized built-in: `class X extends HTML<Something>Element` paired
+ *    with a `customElements.define(..., ..., { extends: "<tagname>" })`
+ *    call. Firefox's `moz-support-link`, `moz-button-group` tabbing
+ *    widgets, and a handful of other toolkit components use this form;
+ *    `furnace override` of those components writes the original source
+ *    verbatim and the validator must not reject them.
+ *
+ * A class that extends a plain `HTMLElement` WITHOUT a `extends:` option
+ * is still rejected — that's the legitimate `not-moz-lit-element` case
+ * the rule was originally designed to catch.
+ */
 export declare function classExtendsMozLitElement(mjsContent: string): boolean;
 /** Collects CSS custom property references used via var(--token-name). */
 export declare function collectCssVariableReferences(cssContent: string): string[];

package/dist/src/core/furnace-validate-helpers.js

@@ -269,7 +269,46 @@ export function hasRelativeModuleImport(mjsContent) {
 export function hasCustomElementDefineCall(mjsContent) {
     return /customElements\.define\s*\(/.test(mjsContent);
 }
-/** Checks whether a declared component class extends MozLitElement. */
+/**
+ * Detects whether the module's `customElements.define(...)` call includes a
+ * literal `extends:` option (third argument). That shape is the marker for
+ * a customized built-in element — the class extends a specific
+ * `HTMLxxxElement` rather than the autonomous `MozLitElement` path.
+ *
+ * Firefox's own widgets use this pattern for toolkit anchors (e.g.
+ * `moz-support-link` extends `HTMLAnchorElement` with
+ * `customElements.define("moz-support-link", ..., { extends: "a" })`), and
+ * the validator's `not-moz-lit-element` check must allow them through or
+ * `furnace override` of a valid upstream component fails its own
+ * `furnace validate` pass with nothing the operator can fix.
+ */
+export function hasCustomElementExtendsOption(mjsContent) {
+    // Match `customElements.define(..., { ..., extends: "..." })`. Tolerant of
+    // whitespace, line breaks, and other object properties. The `[^)]*` stops
+    // the inner greedy match at the closing define call paren so a later
+    // `define` call on a different custom element in the same module does
+    // not bleed its options in.
+    return /customElements\.define\s*\([^)]*\bextends\s*:\s*["'`]/.test(mjsContent);
+}
+/**
+ * Checks whether a declared component class extends a valid element base.
+ *
+ * Two shapes are accepted:
+ *
+ * 1. Autonomous custom element: `class X extends MozLitElement` — the
+ *    default FireForge pattern for fork-authored components and most
+ *    toolkit widgets.
+ * 2. Customized built-in: `class X extends HTML<Something>Element` paired
+ *    with a `customElements.define(..., ..., { extends: "<tagname>" })`
+ *    call. Firefox's `moz-support-link`, `moz-button-group` tabbing
+ *    widgets, and a handful of other toolkit components use this form;
+ *    `furnace override` of those components writes the original source
+ *    verbatim and the validator must not reject them.
+ *
+ * A class that extends a plain `HTMLElement` WITHOUT a `extends:` option
+ * is still rejected — that's the legitimate `not-moz-lit-element` case
+ * the rule was originally designed to catch.
+ */
 export function classExtendsMozLitElement(mjsContent) {
     const hasClassDeclaration = /class\s+\w+\s+extends\s+/.test(mjsContent);
     if (!hasClassDeclaration) {
@@ -278,7 +317,19 @@ export function classExtendsMozLitElement(mjsContent) {
         // structural issues.
         return true;
     }
-    return /class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent);
+    if (/class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent)) {
+        return true;
+    }
+    // Customized built-in: extend a specific HTMLxxxElement AND the define
+    // call carries an `extends:` option. Both halves are required — a class
+    // that extends `HTMLAnchorElement` without the matching define option is
+    // almost certainly an author mistake, and a define call with `extends:`
+    // without a matching class is unreachable.
+    const extendsCustomizedBuiltin = /class\s+\w+\s+extends\s+HTML[A-Z]\w*Element\b/.test(mjsContent);
+    if (extendsCustomizedBuiltin && hasCustomElementExtendsOption(mjsContent)) {
+        return true;
+    }
+    return false;
 }
 /** Collects CSS custom property references used via var(--token-name). */
 export function collectCssVariableReferences(cssContent) {

package/dist/src/core/git.js

@@ -83,6 +83,15 @@ async function stageAllFilesChunked(dir, options = {}) {
         });
     }
 }
+/**
+ * Interval between heartbeat progress messages during the monolithic
+ * `git add -A`. On a fresh ~600 MB Firefox tree the monolithic add runs
+ * 60–120 seconds, during which git emits nothing to stdout/stderr. Without
+ * a heartbeat the CLI spinner stays pinned on "Indexing Firefox source …"
+ * for the full window, looks hung, and in the eval scenario operators
+ * SIGINT'd mid-way assuming the process had stalled.
+ */
+const GIT_ADD_HEARTBEAT_MS = 15_000;
 /**
  * Stages all files in the repository.
  * Tries a monolithic `git add -A` first; if that times out, falls back to
@@ -90,19 +99,39 @@ async function stageAllFilesChunked(dir, options = {}) {
  */
 export async function stageAllFiles(dir, options = {}) {
     const timeout = options.timeout ?? GIT_ADD_TIMEOUT_MS;
+    const reportProgress = options.onProgress;
+    const heartbeatStartedAt = Date.now();
+    // Periodic heartbeat so non-TTY log scrapers (CI, tail -f) AND operators
+    // watching a spinner both see that the add is still making progress
+    // rather than a dead process. Each tick reports elapsed seconds so the
+    // expected 1–3 minute window (see `download.ts`' info banner) is
+    // observable as it unfolds.
+    const heartbeatTimer = reportProgress
+        ? setInterval(() => {
+            const elapsedS = Math.round((Date.now() - heartbeatStartedAt) / 1000);
+            reportProgress(`Indexing Firefox source (still staging, ${elapsedS}s elapsed)`);
+        }, GIT_ADD_HEARTBEAT_MS)
+        : null;
+    heartbeatTimer?.unref();
     try {
-        await git(['add', '-A'], dir, { timeout, env: GIT_ADD_ENV });
-        return;
-    }
-    catch (error) {
-        if (!isTimeoutError(error)) {
-            throw await maybeWrapIndexLockError(dir, error);
+        try {
+            await git(['add', '-A'], dir, { timeout, env: GIT_ADD_ENV });
+            return;
+        }
+        catch (error) {
+            if (!isTimeoutError(error)) {
+                throw await maybeWrapIndexLockError(dir, error);
+            }
+            options.onProgress?.('Monolithic git add timed out; falling back to chunked staging...');
         }
-        options.onProgress?.('Monolithic git add timed out; falling back to chunked staging...');
+        // The killed process may have left an index lock
+        await cleanupIndexLock(dir);
+        await stageAllFilesChunked(dir, options);
+    }
+    finally {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
     }
-    // The killed process may have left an index lock
-    await cleanupIndexLock(dir);
-    await stageAllFilesChunked(dir, options);
 }
 /**
  * Initializes a new git repository with an orphan branch.

package/dist/src/core/manifest-rules.js

@@ -119,6 +119,22 @@ function getUnregistrableAdvice(filePath) {
             '"fireforge wire <name> --dom <path>" to insert the #include, or add the directive manually ' +
             'in the top-level chrome document.');
     }
+    // xpcshell.toml manifests scaffolded by `furnace create --test-style
+    // xpcshell` or `furnace chrome-doc create --with-tests` live under
+    // `browser/base/content/test/<binary-name>-xpcshell/<component>/`. The
+    // scaffold intentionally does NOT auto-register — wiring
+    // `XPCSHELL_TESTS_MANIFESTS` requires a deliberate choice about which
+    // moz.build should own the entry. `register` surfaces that same guidance
+    // instead of falling through to browser.toml-centric advice, which was
+    // the eval finding (operator saw "register browser.toml" hint for a
+    // path that was xpcshell-shaped and contained no browser.toml).
+    if (filePath.endsWith('/xpcshell.toml')) {
+        return (`xpcshell.toml manifests are not auto-registered by "fireforge register". ` +
+            `Add "XPCSHELL_TESTS_MANIFESTS += ['${basename(filePath)}']" to the ` +
+            `moz.build that covers ${filePath.replace(/\/xpcshell\.toml$/, '/')}, ` +
+            'or let `furnace create --test-style xpcshell` print the warning that names the canonical wiring location. ' +
+            'Browser-chrome tests (browser.toml) are auto-registered via "fireforge register <path>/browser.toml".');
+    }
     const testMatch = filePath.match(/^browser\/base\/content\/test\/([^/]+)\/(?!browser\.toml$).+$/);
     if (testMatch) {
         const dir = testMatch[1];

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

@@ -110,6 +110,16 @@ export async function runMarionettePreflight(engineDir, options = {}) {
                 cwd: engineDir,
                 env: { ...process.env, MOZ_HEADLESS: '1' },
                 stdio: ['ignore', 'ignore', 'pipe'],
+                // `detached: true` puts the child in a new process group so we can
+                // signal it and every descendant (Firefox, its helpers) via
+                // `process.kill(-pid, …)` in the finally block. Without this, the
+                // child is Python running mach; a SIGTERM kills Python but the
+                // Firefox grandchild inherits the stderr pipe FD and keeps Node's
+                // event loop alive even after the preflight PASS log. The symptom
+                // is `fireforge test --doctor` printing `Marionette preflight:
+                // PASS` and then hanging indefinitely in `uv__io_poll` — see the
+                // eval finding.
+                detached: true,
             });
         }
         catch (error) {
@@ -154,24 +164,21 @@ export async function runMarionettePreflight(engineDir, options = {}) {
     }
     finally {
         if (child && !hasChildExited(child)) {
-            try {
-                child.kill('SIGTERM');
-            }
-            catch {
-                // Already exited — nothing to do.
-            }
+            killProcessGroup(child, 'SIGTERM');
             // Small escalation: if the child doesn't honour SIGTERM quickly, SIGKILL
             // so we don't leave a ghost mach process around after a failed probe.
             await delay(500);
             if (!hasChildExited(child)) {
-                try {
-                    child.kill('SIGKILL');
-                }
-                catch {
-                    // Already gone.
-                }
+                killProcessGroup(child, 'SIGKILL');
             }
         }
+        // Destroy the stderr pipe explicitly. Firefox (a grandchild of the Python
+        // mach wrapper we spawned) can inherit and hold the stderr FD even after
+        // its direct parent exits — until the pipe closes, Node's readable
+        // stream stays attached and `uv__io_poll` keeps the event loop alive.
+        // `destroy()` closes the local end regardless, so `fireforge test
+        // --doctor` exits cleanly after a passing preflight.
+        child?.stderr?.destroy();
         try {
             await rm(profileDir, { recursive: true, force: true });
         }
@@ -180,6 +187,30 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         }
     }
 }
+/**
+ * Sends `signal` to the child's whole process group when possible, falling
+ * back to a direct `child.kill` for environments that don't support
+ * `detached: true` (Windows in particular: Node still returns a pid, but
+ * `kill(-pid, …)` is not a supported kernel primitive).
+ */
+function killProcessGroup(child, signal) {
+    if (child.pid !== undefined && process.platform !== 'win32') {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // ESRCH / EPERM — fall through to the narrow kill below so we at
+            // least signal the direct child.
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // Already exited — nothing to do.
+    }
+}
 function fail(layer, message, durationMs) {
     return {
         ok: false,

package/dist/src/core/patch-files.d.ts

@@ -7,5 +7,16 @@ export declare function countPatches(patchesDir: string): Promise<number>;
 export declare function isNewFilePatch(patchPath: string): Promise<boolean>;
 /** Returns the first target file path referenced by a patch, if any. */
 export declare function getTargetFileFromPatch(patchPath: string): Promise<string | null>;
-/** Returns all target file paths referenced by a multi-file patch. */
+/**
+ * Returns all target file paths referenced by a multi-file patch.
+ *
+ * Delegates to {@link extractAffectedFiles} so `GIT binary patch` sections
+ * (which have no `+++ b/…` line, only a `diff --git a/… b/…` header) are
+ * included alongside text hunks. Before this delegation the custom regex
+ * only matched `+++ b/…` lines, dropping every binary file from
+ * `filesAffected` — verify reported `files-affected-mismatch` against
+ * branding patches and `doctor --repair-patches-manifest` "repaired" the
+ * manifest by rewriting it to the text-only subset, hiding the true scope
+ * of the patch.
+ */
 export declare function getAllTargetFilesFromPatch(patchPath: string): Promise<string[]>;

package/dist/src/core/patch-files.js

@@ -2,7 +2,7 @@
 import { readdir } from 'node:fs/promises';
 import { extname, join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { extractOrder } from './patch-parse.js';
+import { extractAffectedFiles, extractOrder } from './patch-parse.js';
 /** Discovers patch files in a directory and returns them in apply order. */
 export async function discoverPatches(patchesDir) {
     if (!(await pathExists(patchesDir))) {
@@ -35,17 +35,20 @@ export async function getTargetFileFromPatch(patchPath) {
     const match = /^\+\+\+ b\/(.+)$/m.exec(content);
     return match?.[1] ?? null;
 }
-/** Returns all target file paths referenced by a multi-file patch. */
+/**
+ * Returns all target file paths referenced by a multi-file patch.
+ *
+ * Delegates to {@link extractAffectedFiles} so `GIT binary patch` sections
+ * (which have no `+++ b/…` line, only a `diff --git a/… b/…` header) are
+ * included alongside text hunks. Before this delegation the custom regex
+ * only matched `+++ b/…` lines, dropping every binary file from
+ * `filesAffected` — verify reported `files-affected-mismatch` against
+ * branding patches and `doctor --repair-patches-manifest` "repaired" the
+ * manifest by rewriting it to the text-only subset, hiding the true scope
+ * of the patch.
+ */
 export async function getAllTargetFilesFromPatch(patchPath) {
     const content = await readText(patchPath);
-    const files = [];
-    const regex = /^\+\+\+ b\/(.+)$/gm;
-    let match;
-    while ((match = regex.exec(content)) !== null) {
-        if (match[1]) {
-            files.push(match[1]);
-        }
-    }
-    return files;
+    return extractAffectedFiles(content);
 }
 //# sourceMappingURL=patch-files.js.map

package/dist/src/core/patch-lint.js

@@ -60,7 +60,28 @@ export function countNonBinaryDiffLines(diffContent) {
 const PATCH_LINE_THRESHOLDS = {
     general: { notice: 800, warning: 1500, error: 3000 },
     test: { notice: 1500, warning: 3000, error: 6000 },
+    /**
+     * Branding patches have a legitimate reason to be large: they include
+     * every locale's `brand.ftl`, copied upstream CSS/PNG assets, and the
+     * fork-specific `configure.sh` / `brand.properties` under a single
+     * `browser/branding/<name>/` subtree. The general hard limit of 3000
+     * lines fires on even a first-export branding patch (the eval saw 15904
+     * lines for a freshly-setup fork), which is loud but not actionable —
+     * the patch already is the minimum branding diff. A dedicated tier keeps
+     * the size guidance while moving the hard limit to a threshold that
+     * corresponds to "something other than branding is bundled in here too".
+     */
+    branding: { notice: 3000, warning: 8000, error: 20000 },
 };
+/**
+ * Returns true when every file in a patch lives under `browser/branding/`.
+ * Used by `lintPatchSize` to pick the branding threshold tier.
+ */
+function isBrandingOnlyPatch(files) {
+    if (files.length === 0)
+        return false;
+    return files.every((file) => file.startsWith('browser/branding/'));
+}
 /**
  * Returns true if the filename looks like a JS/MJS/JSM file.
  * Handles `.sys.mjs` as well.
@@ -133,10 +154,18 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
         // Strip block comments before scanning
         const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
         // Check only introduced raw color values when diff context is available.
-        // Skip files on the raw-color allowlist (exact path or basename match).
+        // Skip files on the raw-color allowlist (exact path or basename match) and
+        // auto-exempt files under `browser/branding/` — those are the fork's
+        // visual identity assets (app-about dialogs, installer pages, branded
+        // CSS copied from Firefox's `unofficial` template) and belong to the
+        // design-decision layer the design-token system does not govern.
+        // Without this auto-exemption, every first-time setup's copied CSS
+        // failed `raw-color-value` with no actionable fix other than manually
+        // listing each path in `rawColorAllowlist`.
         const allowlist = config?.patchLint?.rawColorAllowlist;
         const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
-        if (!isAllowlisted) {
+        const isBranding = file.startsWith('browser/branding/');
+        if (!isAllowlisted && !isBranding) {
             // Strip lines with inline fireforge-ignore: raw-color-value suppression.
             // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
             const sourceForSuppression = addedLinesByFile
@@ -239,14 +268,25 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
             continue;
         const content = await readText(filePath);
         const expectedHeader = getLicenseHeader(license, style);
-        if (!content.startsWith(expectedHeader)) {
-            issues.push({
-                file,
-                check: 'missing-license-header',
-                message: `New file is missing the required ${license} license header.`,
-                severity: 'error',
-            });
-        }
+        // Auto-exempt `browser/branding/` when the file carries ANY recognised
+        // license header in the matching comment style. The setup-generated
+        // branding directory is copied from Firefox's `unofficial` template,
+        // which arrives with Mozilla MPL-2.0 headers — those are legitimate
+        // for copyright purposes (the assets are Mozilla's) even when the
+        // fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later. The narrower
+        // license-match rule would force operators to either rewrite the
+        // copied headers (misrepresenting authorship) or suppress the lint
+        // with `--skip-lint` (hiding real issues elsewhere).
+        if (content.startsWith(expectedHeader))
+            continue;
+        if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
+            continue;
+        issues.push({
+            file,
+            check: 'missing-license-header',
+            message: `New file is missing the required ${license} license header.`,
+            severity: 'error',
+        });
     }
     return issues;
 }
@@ -402,8 +442,19 @@ export function lintPatchSize(filesAffected, lineCount) {
             severity: 'warning',
         });
     }
+    // Tier selection: test > branding > general. Tests keep their elevated
+    // thresholds because a big regression test is legitimate (table-driven
+    // harnesses run into the thousands of lines). Branding patches get their
+    // own tier so a first-export of setup-generated branding doesn't fire
+    // the general hard limit — see `PATCH_LINE_THRESHOLDS.branding` above
+    // for the eval data motivating this tier.
     const allTests = filesAffected.length > 0 && filesAffected.every(isTestFile);
-    const thresholds = allTests ? PATCH_LINE_THRESHOLDS.test : PATCH_LINE_THRESHOLDS.general;
+    const branding = !allTests && isBrandingOnlyPatch(filesAffected);
+    const thresholds = allTests
+        ? PATCH_LINE_THRESHOLDS.test
+        : branding
+            ? PATCH_LINE_THRESHOLDS.branding
+            : PATCH_LINE_THRESHOLDS.general;
     if (lineCount >= thresholds.error) {
         issues.push({
             file: '(patch)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",