@hominis/fireforge 0.18.0 → 0.18.2

package/dist/src/core/patch-registration-refs.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Extracts furnace-shaped registration references from a patch body.
+ *
+ * 2026-04-24 eval Finding 1: `export-all --exclude-furnace` can land a
+ * patch that registers a furnace component (via edits to
+ * `toolkit/content/customElements.js`, `toolkit/content/jar.mn`, or
+ * `toolkit/locales/jar.mn`) without including the component's source
+ * files in the patch. `fireforge verify` then reports "Verify clean" for
+ * the broken queue. This module provides a pattern-scoped scan so
+ * `verify` can cross-check registrations against available file bodies.
+ *
+ * The scan is deliberately narrow: it only matches component-shaped
+ * references (widget tag names, locale fluent names). Unrelated jar.mn
+ * or customElements.js edits pass through without spurious warnings.
+ */
+/** Canonical file paths that registration-shaped diffs touch. */
+const REGISTRATION_FILE_PATHS = new Set([
+    'toolkit/content/customElements.js',
+    'toolkit/content/jar.mn',
+    'toolkit/locales/jar.mn',
+]);
+/**
+ * Walks a unified-diff patch body and returns the set of
+ * component-shaped engine paths that the patch ADDS a registration for.
+ *
+ * Returns the empty array when no registration hunks are present OR
+ * when the registration hunks do not mention any component-shaped
+ * paths — that leaves the scan silent on the vast majority of patches
+ * (branding tweaks, behavioural fixes, module additions) so it only
+ * fires when a furnace-managed component is being newly registered.
+ *
+ * @param patchBody - Full unified-diff body of the patch file.
+ */
+export function collectPatchRegistrationReferences(patchBody) {
+    if (!patchBody)
+        return [];
+    const refs = [];
+    let currentFile;
+    // Walk line-by-line. The canonical unified-diff header line is
+    // `diff --git a/<path> b/<path>` — we key the file state off the `b/`
+    // path because that names the target side and is stable against
+    // renames. Additional diff metadata lines (index/---/+++/@@) are
+    // ignored for the purposes of tracking the current file.
+    const lines = patchBody.split(/\r?\n/);
+    for (const line of lines) {
+        const diffHeader = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+        if (diffHeader?.[2]) {
+            currentFile = diffHeader[2];
+            continue;
+        }
+        if (!currentFile)
+            continue;
+        if (!REGISTRATION_FILE_PATHS.has(currentFile))
+            continue;
+        if (!line.startsWith('+'))
+            continue;
+        // Skip the `+++ b/<path>` header line — only real hunk adds count.
+        if (line.startsWith('+++'))
+            continue;
+        const added = line.slice(1);
+        const extracted = extractTargetPathsFromRegistrationLine(currentFile, added);
+        for (const target of extracted) {
+            refs.push({ targetPath: target, source: currentFile, lineText: added });
+        }
+    }
+    return refs;
+}
+/**
+ * Per-source extractor. Each registration file has a distinct syntactic
+ * shape; we scope the match to that file so a jar.mn regex does not
+ * accidentally match a customElements.js line.
+ */
+function extractTargetPathsFromRegistrationLine(sourceFile, added) {
+    if (sourceFile === 'toolkit/content/jar.mn') {
+        // Example (added line, leading `+` already stripped):
+        //   `   content/global/elements/moz-qa-panel.mjs  (widgets/moz-qa-panel/moz-qa-panel.mjs)`
+        // The parenthesised second half is the repo-relative path Firefox's
+        // packaging system reads. Widget registrations always live under
+        // `widgets/<tag>/<file>` — the enclosing tree is
+        // `toolkit/content/widgets/`. Reconstruct the engine-relative
+        // target path so callers can check it against patch bodies.
+        const widgetMatch = /\(\s*(widgets\/[^\s)]+)\s*\)/.exec(added);
+        if (widgetMatch?.[1]) {
+            return [`toolkit/content/${widgetMatch[1]}`];
+        }
+        return [];
+    }
+    if (sourceFile === 'toolkit/locales/jar.mn') {
+        // Example:
+        //   `  locale/@AB_CD@/toolkit/global/moz-qa-panel.ftl (%toolkit/global/moz-qa-panel.ftl)`
+        // The `%`-prefixed repo-relative reference points at
+        // `toolkit/locales/en-US/<rel>`, which is the canonical FTL path.
+        const localeMatch = /\(%\s*([^\s)]+\.ftl)\s*\)/.exec(added);
+        if (localeMatch?.[1]) {
+            return [`toolkit/locales/en-US/${localeMatch[1]}`];
+        }
+        return [];
+    }
+    if (sourceFile === 'toolkit/content/customElements.js') {
+        // Example:
+        //   `          ["moz-qa-panel", "chrome://global/content/elements/moz-qa-panel.mjs"],`
+        // The chrome URL maps back to
+        // `toolkit/content/widgets/<tag>/<tag>.mjs` by convention: the
+        // packager rewrites `chrome://global/content/elements/<file>` to the
+        // widget tree root. The tag name is the identifier we key off.
+        const elementMatch = /\[\s*"([a-z][a-z0-9-]*)"\s*,\s*"chrome:\/\/global\/content\/elements\/([a-zA-Z0-9_-]+)\.mjs"\s*\]/.exec(added);
+        if (elementMatch?.[1] && elementMatch[2]) {
+            const tag = elementMatch[1];
+            const fileStem = elementMatch[2];
+            return [`toolkit/content/widgets/${tag}/${fileStem}.mjs`];
+        }
+        return [];
+    }
+    return [];
+}
+//# sourceMappingURL=patch-registration-refs.js.map

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/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchReorderOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchReorderOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
 export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';

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

@@ -93,6 +93,24 @@ export interface ExportOptions {
      * another patch, because the resulting queue fails `verify` immediately.
      */
     allowOverlap?: boolean;
+    /**
+     * Force a tier override on the new patch's `PatchMetadata.tier`. Only
+     * `"branding"` is currently recognised — Commander rejects other values
+     * before the handler runs. Use when a branding patch legitimately
+     * touches a non-allowlisted sibling that `isBrandingOnlyPatch` cannot
+     * reach (a fork-specific theme override under `browser/themes/<name>/`,
+     * a vendor-specific icon resource, etc.).
+     */
+    tier?: 'branding';
+    /**
+     * Lint check IDs to suppress on this patch. Writes to
+     * `PatchMetadata.lintIgnore`. Repeatable on the CLI; each occurrence
+     * appends to the list. Useful when a patch is advisory-noisy by nature
+     * (a cohesive branding bundle, an auto-generated manifest) and a
+     * specific check does not apply, but `--skip-lint` is too coarse a
+     * hammer.
+     */
+    lintIgnore?: string[];
 }
 /**
  * Options for the reset command.
@@ -172,6 +190,55 @@ export interface ReExportOptions {
      * `rebase`.
      */
     stamp?: boolean;
+    /**
+     * Force a tier override on the selected patch(es). Only `"branding"` is
+     * currently recognised. Mutually exclusive with `--all` — mass tier
+     * changes are virtually always footguns, since different patches in
+     * the queue have different shapes.
+     */
+    tier?: 'branding';
+    /**
+     * Lint check IDs to suppress, **appended** (union) to the patch's
+     * existing `lintIgnore` list. De-duplicated. Mutually exclusive with
+     * `--all`. To remove an entry or clear the list entirely, use the
+     * `fireforge patch lint-ignore` subcommand (which has explicit
+     * `--add` / `--remove` / `--clear` modes); re-export's append-only
+     * semantics match the operator's most common intent ("I want this
+     * patch to also suppress X").
+     */
+    lintIgnore?: string[];
+}
+/**
+ * Options for the `fireforge patch tier` subcommand. Sets or clears the
+ * `PatchMetadata.tier` field on a single patch without rewriting the
+ * `.patch` file body — the manifest is the only thing that changes.
+ */
+export interface PatchTierOptions {
+    /** Force the named tier on the patch. Only `"branding"` is recognised. */
+    tier?: 'branding';
+    /** Remove the `tier` override entirely, restoring auto-detection. */
+    clear?: boolean;
+    /** Print the planned change without writing. */
+    dryRun?: boolean;
+    /** Skip the confirmation prompt (required for non-TTY). */
+    yes?: boolean;
+}
+/**
+ * Options for the `fireforge patch lint-ignore` subcommand. Modes are
+ * mutually exclusive — exactly one of `add`, `remove`, or `clear` must
+ * be set per invocation.
+ */
+export interface PatchLintIgnoreOptions {
+    /** Lint check IDs to add to the patch's `lintIgnore` list (union, de-duped). */
+    add?: string[];
+    /** Lint check IDs to remove from the patch's `lintIgnore` list. */
+    remove?: string[];
+    /** Drop the `lintIgnore` field entirely. */
+    clear?: boolean;
+    /** Print the planned change without writing. */
+    dryRun?: boolean;
+    /** Skip the confirmation prompt (required for non-TTY). */
+    yes?: boolean;
 }
 /**
  * Options for the rebase command.

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

@@ -86,11 +86,12 @@ export interface PatchMetadata {
      * 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.
+     * (notice 8000 / warning 18000 / error 30000 lines, ≤60 files)
+     * 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.

package/package.json

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