@hominis/fireforge 0.17.0 → 0.18.1

package/dist/src/core/wire-init.d.ts

@@ -5,12 +5,18 @@
  * AST-based implementation: finds onLoad() method body, locates existing
  * fireforge init blocks (TryStatements containing typeof guards), and inserts
  * after the correct position.
+ *
+ * `marker` is prepended (uppercased) to the generated comment line so the
+ * emitted block carries the patch-lint `// <MARKER>:` signature that
+ * `lintModificationComments` looks for. Otherwise the first export after
+ * `wire` trips `missing-modification-comment` on wire-generated edits —
+ * exactly the eval 1 Finding #9 regression.
  */
-export declare function addInitAST(content: string, expression: string, after?: string): string;
+export declare function addInitAST(content: string, expression: string, after?: string, marker?: string): string;
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export declare function legacyAddInit(content: string, expression: string, after?: string): string;
+export declare function legacyAddInit(content: string, expression: string, after?: string, marker?: string): string;
 /**
  * Adds an init expression as the first statement(s) in gBrowserInit.onLoad()
  * in browser-init.js, after any previously-wired fireforge init blocks.
@@ -20,4 +26,4 @@ export declare function legacyAddInit(content: string, expression: string, after
  * @param after - Optional name to insert after (e.g., "MyComponent" to insert after its block)
  * @returns true if added, false if already present
  */
-export declare function addInitToBrowserInit(engineDir: string, expression: string, after?: string): Promise<boolean>;
+export declare function addInitToBrowserInit(engineDir: string, expression: string, after?: string, marker?: string): Promise<boolean>;

package/dist/src/core/wire-init.js

@@ -12,12 +12,24 @@ import { detectIndent, getNodeSource, parseScript } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
+/**
+ * Default patch-lint marker used when a caller does not supply a
+ * project-specific one. Kept as a constant so test fixtures and
+ * fallback code paths agree on the shape.
+ */
+const DEFAULT_MARKER = 'FIREFORGE:';
 /**
  * AST-based implementation: finds onLoad() method body, locates existing
  * fireforge init blocks (TryStatements containing typeof guards), and inserts
  * after the correct position.
+ *
+ * `marker` is prepended (uppercased) to the generated comment line so the
+ * emitted block carries the patch-lint `// <MARKER>:` signature that
+ * `lintModificationComments` looks for. Otherwise the first export after
+ * `wire` trips `missing-modification-comment` on wire-generated edits —
+ * exactly the eval 1 Finding #9 regression.
  */
-export function addInitAST(content, expression, after) {
+export function addInitAST(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
     // `validateWireName` accepts both `Foo.bar` and `Foo.bar()` shapes. The
     // template below interpolates the value verbatim, so a bare property
@@ -99,7 +111,7 @@ export function addInitAST(content, expression, after) {
         }
     }
     const block = [
-        `${indent}// ${name} init — must be first, before Firefox subsystem`,
+        `${indent}// ${marker} wire-init ${name} — must be first, before Firefox subsystem`,
         `${indent}// inits that reference native UI elements we hide.`,
         `${indent}try {`,
         `${indent}  if (typeof ${name} !== "undefined") {`,
@@ -115,7 +127,7 @@ export function addInitAST(content, expression, after) {
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export function legacyAddInit(content, expression, after) {
+export function legacyAddInit(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
     // See `addInitAST` for the rationale — the AST and fallback paths must
     // agree on whether the emitted block is a function call, otherwise
@@ -174,7 +186,7 @@ export function legacyAddInit(content, expression, after) {
     const inner = baseIndent + '  ';
     const inner2 = inner + '  ';
     const block = [
-        `${baseIndent}// ${name} init — must be first, before Firefox subsystem`,
+        `${baseIndent}// ${marker} wire-init ${name} — must be first, before Firefox subsystem`,
         `${baseIndent}// inits that reference native UI elements we hide.`,
         `${baseIndent}try {`,
         `${inner}if (typeof ${name} !== "undefined") {`,
@@ -196,7 +208,7 @@ export function legacyAddInit(content, expression, after) {
  * @param after - Optional name to insert after (e.g., "MyComponent" to insert after its block)
  * @returns true if added, false if already present
  */
-export async function addInitToBrowserInit(engineDir, expression, after) {
+export async function addInitToBrowserInit(engineDir, expression, after, marker = DEFAULT_MARKER) {
     validateWireName(expression, 'init expression');
     const filePath = join(engineDir, BROWSER_INIT_JS);
     if (!(await pathExists(filePath))) {
@@ -212,7 +224,7 @@ export async function addInitToBrowserInit(engineDir, expression, after) {
     if (initPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after), () => legacyAddInit(content, expression, after), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }

package/dist/src/core/wire-subscript.d.ts

@@ -4,12 +4,16 @@
 /**
  * AST-based implementation: finds the last try/catch containing
  * `loadSubScript` and inserts a new try/catch block after it.
+ *
+ * The inserted block carries a `// <MARKER>: wire-subscript ...` comment
+ * so the emitted edit satisfies `lintModificationComments` (eval 1
+ * Finding #9).
  */
-export declare function addSubscriptAST(content: string, name: string): string;
+export declare function addSubscriptAST(content: string, name: string, marker?: string): string;
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export declare function legacyAddSubscript(content: string, name: string): string;
+export declare function legacyAddSubscript(content: string, name: string, marker?: string): string;
 /**
  * Adds a loadSubScript entry to browser-main.js with try/catch error handling.
  *
@@ -17,4 +21,4 @@ export declare function legacyAddSubscript(content: string, name: string): strin
  * @param name - Subscript name (without .js extension)
  * @returns true if added, false if already present
  */
-export declare function addSubscriptToBrowserMain(engineDir: string, name: string): Promise<boolean>;
+export declare function addSubscriptToBrowserMain(engineDir: string, name: string, marker?: string): Promise<boolean>;

package/dist/src/core/wire-subscript.js

@@ -11,11 +11,16 @@ import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, findNearestTryLine, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_MAIN_JS = 'browser/base/content/browser-main.js';
+const DEFAULT_MARKER = 'FIREFORGE:';
 /**
  * AST-based implementation: finds the last try/catch containing
  * `loadSubScript` and inserts a new try/catch block after it.
+ *
+ * The inserted block carries a `// <MARKER>: wire-subscript ...` comment
+ * so the emitted edit satisfies `lintModificationComments` (eval 1
+ * Finding #9).
  */
-export function addSubscriptAST(content, name) {
+export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
     const ast = parseScript(content);
     const ms = new MagicString(content);
     // Collect all TryStatements containing loadSubScript
@@ -58,6 +63,7 @@ export function addSubscriptAST(content, name) {
         indent = detectIndent(content, lastBrace);
     }
     const block = [
+        `${indent}// ${marker} wire-subscript ${name}`,
         `${indent}try {`,
         `${indent}  Services.scriptloader.loadSubScript("chrome://browser/content/${name}.js", this);`,
         `${indent}} catch (e) {`,
@@ -70,7 +76,7 @@ export function addSubscriptAST(content, name) {
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export function legacyAddSubscript(content, name) {
+export function legacyAddSubscript(content, name, marker = DEFAULT_MARKER) {
     const lines = content.split('\n');
     let lastSubScriptLine = -1;
     for (let i = 0; i < lines.length; i++) {
@@ -103,6 +109,7 @@ export function legacyAddSubscript(content, name) {
     const ind = refLine?.match(/^(\s*)/)?.[1] ?? '  ';
     const inner = ind + '  ';
     const block = [
+        `${ind}// ${marker} wire-subscript ${name}`,
         `${ind}try {`,
         `${inner}Services.scriptloader.loadSubScript("chrome://browser/content/${name}.js", this);`,
         `${ind}} catch (e) {`,
@@ -119,7 +126,7 @@ export function legacyAddSubscript(content, name) {
  * @param name - Subscript name (without .js extension)
  * @returns true if added, false if already present
  */
-export async function addSubscriptToBrowserMain(engineDir, name) {
+export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAULT_MARKER) {
     validateWireName(name, 'subscript name');
     const filePath = join(engineDir, BROWSER_MAIN_JS);
     if (!(await pathExists(filePath))) {
@@ -130,7 +137,7 @@ export async function addSubscriptToBrowserMain(engineDir, name) {
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name), () => legacyAddSubscript(content, name), BROWSER_MAIN_JS);
+    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_MAIN_JS);
     }

package/dist/src/core/xpcshell-appdir.d.ts

@@ -96,11 +96,25 @@ export declare function readMozinfoAppname(objDirPath: string): Promise<string>;
  * (which fails with a different error than the original `firefox-appdir`
  * symptom and confuses triage).
  *
- * Probe order matches the on-disk layouts FireForge supports today:
- *  1. `<objDir>/dist/bin/<value>` — Linux primary, also macOS via the
- *     `dist/bin -> dist/<App>.app/Contents/MacOS/` symlink.
- *  2. `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` — macOS
- *     packaged layout, where `dist/bin/` may not exist as a directory.
+ * Probe order differs by host platform:
+ *
+ * - **macOS (`darwin`)**: prefer `<objDir>/dist/<App>.app/Contents/Resources/
+ *   <value>` FIRST, then fall back to `<objDir>/dist/bin/<value>`.
+ *   2026-04-24 eval Finding 8: on macOS `dist/bin` is symlinked to
+ *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
+ *   `dist/bin/browser` actually resolves to `<App>.app/Contents/MacOS/
+ *   browser/`. That is NOT where `resource:///modules/` is rooted — on
+ *   macOS, `-a` for xpcshell must point at the `.app/Contents/Resources/
+ *   <value>` subtree where modules / chrome.manifest live. Returning
+ *   `dist/bin/browser` caused the injected `--app-path` to look
+ *   successful (the info log showed it) but pointed at a directory
+ *   without the modules tree, so every `resource:///modules/…` import
+ *   still threw.
+ * - **non-macOS**: keep the historical order — `dist/bin/<value>` first,
+ *   `.app/Contents/Resources/<value>` as fallback.
+ *
+ * On both platforms the final `.app` fallback iterates every `*.app`
+ * entry because a rebranded fork may pick an arbitrary app name.
  */
 export declare function resolveAbsoluteAppPath(objDirAbs: string, relativeAppdir: string): Promise<string | null>;
 /**

package/dist/src/core/xpcshell-appdir.js

@@ -164,34 +164,60 @@ export async function readMozinfoAppname(objDirPath) {
  * (which fails with a different error than the original `firefox-appdir`
  * symptom and confuses triage).
  *
- * Probe order matches the on-disk layouts FireForge supports today:
- *  1. `<objDir>/dist/bin/<value>` — Linux primary, also macOS via the
- *     `dist/bin -> dist/<App>.app/Contents/MacOS/` symlink.
- *  2. `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` — macOS
- *     packaged layout, where `dist/bin/` may not exist as a directory.
+ * Probe order differs by host platform:
+ *
+ * - **macOS (`darwin`)**: prefer `<objDir>/dist/<App>.app/Contents/Resources/
+ *   <value>` FIRST, then fall back to `<objDir>/dist/bin/<value>`.
+ *   2026-04-24 eval Finding 8: on macOS `dist/bin` is symlinked to
+ *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
+ *   `dist/bin/browser` actually resolves to `<App>.app/Contents/MacOS/
+ *   browser/`. That is NOT where `resource:///modules/` is rooted — on
+ *   macOS, `-a` for xpcshell must point at the `.app/Contents/Resources/
+ *   <value>` subtree where modules / chrome.manifest live. Returning
+ *   `dist/bin/browser` caused the injected `--app-path` to look
+ *   successful (the info log showed it) but pointed at a directory
+ *   without the modules tree, so every `resource:///modules/…` import
+ *   still threw.
+ * - **non-macOS**: keep the historical order — `dist/bin/<value>` first,
+ *   `.app/Contents/Resources/<value>` as fallback.
+ *
+ * On both platforms the final `.app` fallback iterates every `*.app`
+ * entry because a rebranded fork may pick an arbitrary app name.
  */
 export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
     const distBinCandidate = join(objDirAbs, 'dist', 'bin', relativeAppdir);
-    if (await pathExists(distBinCandidate))
-        return distBinCandidate;
     const distDir = join(objDirAbs, 'dist');
-    if (!(await pathExists(distDir)))
+    const isMacos = process.platform === 'darwin';
+    async function probeMacAppBundle() {
+        if (!(await pathExists(distDir)))
+            return null;
+        let entries;
+        try {
+            entries = await readdir(distDir);
+        }
+        catch {
+            return null;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.app'))
+                continue;
+            const candidate = join(distDir, entry, 'Contents', 'Resources', relativeAppdir);
+            if (await pathExists(candidate))
+                return candidate;
+        }
         return null;
-    let entries;
-    try {
-        entries = await readdir(distDir);
     }
-    catch {
+    if (isMacos) {
+        const appBundle = await probeMacAppBundle();
+        if (appBundle)
+            return appBundle;
+        if (await pathExists(distBinCandidate))
+            return distBinCandidate;
         return null;
     }
-    for (const entry of entries) {
-        if (!entry.endsWith('.app'))
-            continue;
-        const candidate = join(distDir, entry, 'Contents', 'Resources', relativeAppdir);
-        if (await pathExists(candidate))
-            return candidate;
-    }
-    return null;
+    if (await pathExists(distBinCandidate))
+        return distBinCandidate;
+    return probeMacAppBundle();
 }
 /**
  * Top-level resolver. Walks every test path, reads the nearest

package/dist/src/errors/git.d.ts

@@ -39,3 +39,23 @@ export declare class GitIndexLockError extends GitError {
     constructor(lockPath: string, ageMs?: number | undefined);
     get userMessage(): string;
 }
+/**
+ * Error thrown when `git add` (monolithic or chunked) exceeds the
+ * configured timeout while indexing the Firefox source tree.
+ *
+ * 2026-04-24 eval Finding 10: a 140.10.0esr bump on a previously-working
+ * 140.9.0esr workspace aborted after ~854s with a generic
+ * `AbortError: The operation was aborted`. The root cause was the
+ * `git add` timeout firing, but the surfaced error was indistinguishable
+ * from any other AbortError and gave the operator no actionable
+ * direction. This typed error carries the elapsed budget and the
+ * environment-variable override so the recovery path is
+ * self-documenting.
+ */
+export declare class GitIndexingTimeoutError extends GitError {
+    readonly phase: 'monolithic' | 'chunked';
+    readonly timeoutMs: number;
+    readonly envVar: string;
+    constructor(phase: 'monolithic' | 'chunked', timeoutMs: number, envVar: string, cause?: Error);
+    get userMessage(): string;
+}

package/dist/src/errors/git.js

@@ -96,4 +96,43 @@ export class GitIndexLockError extends GitError {
             '  3. Re-run "fireforge download --force"');
     }
 }
+/**
+ * Error thrown when `git add` (monolithic or chunked) exceeds the
+ * configured timeout while indexing the Firefox source tree.
+ *
+ * 2026-04-24 eval Finding 10: a 140.10.0esr bump on a previously-working
+ * 140.9.0esr workspace aborted after ~854s with a generic
+ * `AbortError: The operation was aborted`. The root cause was the
+ * `git add` timeout firing, but the surfaced error was indistinguishable
+ * from any other AbortError and gave the operator no actionable
+ * direction. This typed error carries the elapsed budget and the
+ * environment-variable override so the recovery path is
+ * self-documenting.
+ */
+export class GitIndexingTimeoutError extends GitError {
+    phase;
+    timeoutMs;
+    envVar;
+    constructor(phase, timeoutMs, envVar, cause) {
+        super(`Git ${phase} indexing exceeded the ${Math.round(timeoutMs / 1000)}s timeout`, 'add -A', cause);
+        this.phase = phase;
+        this.timeoutMs = timeoutMs;
+        this.envVar = envVar;
+    }
+    get userMessage() {
+        const minutes = Math.max(1, Math.round(this.timeoutMs / 60_000));
+        const phaseDescription = this.phase === 'monolithic'
+            ? 'the monolithic `git add -A` pass'
+            : 'one of the chunked `git add -- <dir>` passes';
+        return (`Git Error: ${phaseDescription} exceeded the ${minutes}-minute timeout while indexing the Firefox source tree.\n\n` +
+            'Common triggers:\n' +
+            '  - Slow or loaded disk (an external volume, encrypted filesystem, or heavily-used SSD under load).\n' +
+            '  - A Firefox source tree that has grown beyond what the default timeout accommodates.\n' +
+            '  - A background process (antivirus, backup, indexing) holding the working directory.\n\n' +
+            'To recover:\n' +
+            `  1. Extend the timeout via the ${this.envVar} environment variable (milliseconds; e.g. "export ${this.envVar}=1800000" for 30 minutes).\n` +
+            '  2. Re-run "fireforge download --force" — the resume path resumes from the partial initialisation, so the repeat pass is not wasted work.\n' +
+            '  3. If the problem persists, check disk throughput and free space; Firefox source indexing on a cold SSD typically completes in 1–3 minutes.');
+    }
+}
 //# sourceMappingURL=git.js.map

package/dist/src/types/commands/patches.d.ts

@@ -73,6 +73,29 @@ export interface PatchMetadata {
      * renamed or removed.
      */
     lintIgnore?: string[];
+    /**
+     * Optional per-patch threshold-tier override for the `large-patch-lines`
+     * rule. Exists for branding patches that must touch a small number of
+     * cross-cutting registration files alongside `browser/branding/<name>/`
+     * (notably `browser/moz.configure` to register the new branding flavor
+     * with the top-level configure). The narrow auto-detect allowlist in
+     * `isBrandingOnlyPatch` covers the canonical shape, but a fork whose
+     * branding patch also touches an unlisted sibling (for example a
+     * `browser/themes/<name>/` override or a vendor-specific icon
+     * resource) falls through to the general tier and trips the hard
+     * limit on what is legitimately one branding diff.
+     *
+     * Declaring `tier: "branding"` here forces the branding thresholds
+     * (notice 3000 / warning 8000 / error 20000) regardless of
+     * `filesAffected`. The tier is the weaker claim than test — a patch
+     * of all-tests still lands in the test tier even if this field is
+     * set, because the test-tier thresholds are already more permissive
+     * and a test that is also branding-shaped is vanishingly rare.
+     *
+     * Only `"branding"` is currently recognised. Unknown values are
+     * rejected by the manifest validator, not silently stripped.
+     */
+    tier?: 'branding';
 }
 /**
  * Schema for patches/patches.json file.

package/dist/src/types/furnace.d.ts

@@ -102,6 +102,15 @@ export interface FurnaceConfig {
     tokenPrefix?: string;
     /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
     tokenAllowlist?: string[];
+    /**
+     * CSS custom-property prefixes that identify upstream / platform
+     * variables the fork does not own. `token coverage` counts matches
+     * as `allowlisted` rather than `unknown` so a copied upstream
+     * baseline doesn't drag fork-owned coverage percentages down.
+     * Defaults to `['--moz-']` when unset. Pass an explicit empty array
+     * to restore the pre-0.18.0 strict contract.
+     */
+    platformPrefixes?: string[];
     /**
      * Custom properties used as runtime state channels — written and read by the
      * component itself (e.g. per-frame camera/tile positions) rather than

package/dist/src/utils/parse.d.ts

@@ -76,6 +76,13 @@ export declare class ParsedRecord {
      * @throws Error if the field is missing or not an array of strings
      */
     stringArray(key: string): string[];
+    /**
+     * Extracts an optional array-of-strings field.
+     * @param key - Field name
+     * @returns The string array (fresh copy) or undefined when absent
+     * @throws Error if the field is present but not an array of strings
+     */
+    optionalStringArray(key: string): string[] | undefined;
     /**
      * Extracts a required nested object field.
      * @param key - Field name

package/dist/src/utils/parse.js

@@ -142,6 +142,21 @@ export class ParsedRecord {
         }
         return [...value];
     }
+    /**
+     * Extracts an optional array-of-strings field.
+     * @param key - Field name
+     * @returns The string array (fresh copy) or undefined when absent
+     * @throws Error if the field is present but not an array of strings
+     */
+    optionalStringArray(key) {
+        const value = this.#data[key];
+        if (value === undefined)
+            return undefined;
+        if (!isArray(value) || !value.every(isString)) {
+            throw new Error(`${this.#label}.${key} must be an array of strings`);
+        }
+        return [...value];
+    }
     /**
      * Extracts a required nested object field.
      * @param key - Field name

package/package.json

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