@hominis/fireforge 0.34.2 → 0.36.0

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

@@ -95,4 +95,3 @@ export async function measureTokenCoverage(repoDir, cssFiles, projectRoot) {
         files: entries,
     };
 }
-//# sourceMappingURL=token-coverage.js.map

package/dist/src/core/token-dark-mode.js

@@ -167,4 +167,3 @@ export function findDarkMediaCloseIndex(lines) {
         return -1;
     return findBlockCloseIndex(stripped, darkMediaLine);
 }
-//# sourceMappingURL=token-dark-mode.js.map

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

@@ -98,4 +98,3 @@ export async function addTokenToDocs(engineDir, options, annotation) {
     await writeText(filePath, lines.join('\n'));
     return { docsAdded, unmappedAdded, countUpdated };
 }
-//# sourceMappingURL=token-docs.js.map

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

@@ -455,4 +455,3 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     await writeText(filePath, content);
     return { added: true, categoryCreated };
 }
-//# sourceMappingURL=token-manager.js.map

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

@@ -71,4 +71,3 @@ ${categoryBlocks}
 }
 `;
 }
-//# sourceMappingURL=token-scaffold.js.map

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

@@ -138,4 +138,3 @@ export function insertVariantDeclaration(lines, variant, declLine) {
     }
     lines.splice(findVariantBlockInsertionPoint(lines), 0, '', `:root${variant} {`, declLine, '}');
 }
-//# sourceMappingURL=token-variant.js.map

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

@@ -0,0 +1,85 @@
+/**
+ * Toolchain-minimum awareness for Firefox source hops.
+ *
+ * When `fireforge download --force` moves the engine to a new Firefox
+ * MAJOR version, the tree's declared toolchain minimums (cbindgen, Rust)
+ * frequently move with it — and the first `fireforge build` then dies a
+ * few seconds into `mach configure` with a message whose remediation
+ * text names `./mach bootstrap`, the wrong tool for a FireForge-managed
+ * repo (152.0b7 → 153.0b8 source-refresh drill: `ERROR: cbindgen version
+ * 0.29.1 is too old. At least version 0.29.4 is required.`).
+ *
+ * Two layers:
+ *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when
+ *     the downloaded major differs from the previously downloaded one.
+ *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
+ *     the minimums the tree itself declares against the host binaries
+ *     `mach configure` will resolve, probing configure's own candidate
+ *     order: env override first, then the `~/.mozbuild` state-directory
+ *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
+ *     only, blocking builds whose current tool lived in the state dir
+ *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
+ *     mismatch only when a minimum was positively parsed AND at least
+ *     one candidate resolved AND every resolved candidate is
+ *     definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure
+ *     failure downstream.
+ */
+/** Tools the preflight knows how to probe. */
+export type ToolchainTool = 'cbindgen' | 'rustc';
+/** One probed candidate binary for a tool. */
+export interface ToolchainCandidate {
+    /** Binary path (or bare name for the PATH candidate). */
+    binary: string;
+    /** Parsed version of the candidate. */
+    version: string;
+}
+/** One definitive host-vs-tree mismatch found by the preflight. */
+export interface ToolchainMismatch {
+    tool: ToolchainTool;
+    minimumVersion: string;
+    /** Engine-relative file the minimum was parsed from. */
+    declaredIn: string;
+    /**
+     * Every candidate that resolved — all of them below the minimum
+     * (mach-resolution order: env override, mozbuild state dir, PATH).
+     */
+    candidates: ToolchainCandidate[];
+}
+/**
+ * Returns the one-line notice to print after a download that hopped the
+ * Firefox MAJOR version, or undefined when no notice is warranted (first
+ * download, same major, or unparseable versions — an unparseable version
+ * must not spam every download with a false hint).
+ *
+ * @param previousVersion - `downloadedVersion` recorded in state before this download
+ * @param newVersion - Version that was just downloaded
+ */
+export declare function formatMajorVersionHopNotice(previousVersion: string | undefined, newVersion: string): string | undefined;
+/**
+ * Reads the toolchain minimums the engine tree itself declares. Any file
+ * that is missing or no longer matches the expected declaration shape
+ * yields undefined for that tool — never an error.
+ */
+export declare function readDeclaredToolchainMinimums(engineDir: string): Promise<Partial<Record<ToolchainTool, string>>>;
+/**
+ * Compares the tree-declared toolchain minimums against the host binaries
+ * `mach configure` will resolve, in configure's own candidate order (env
+ * override, mozbuild state dir, PATH). A tool fails ONLY when at least
+ * one candidate resolved and none of them meets the minimum; any single
+ * passing candidate passes the tool (configure will find it), and a tool
+ * with no resolvable candidate skips silently (see module header for the
+ * fail-soft rationale).
+ *
+ * @param engineDir - Path to the engine directory
+ */
+export declare function runToolchainPreflight(engineDir: string): Promise<ToolchainMismatch[]>;
+/**
+ * Formats the fail-fast message for definitive preflight mismatches,
+ * listing every candidate probed (in mach's resolution order) and naming
+ * `fireforge bootstrap` as the remedy (mach's own configure error
+ * suggests `./mach bootstrap`, which is the wrong entry point for a
+ * FireForge-managed repo).
+ */
+export declare function formatToolchainMismatchMessage(mismatches: ToolchainMismatch[]): string;

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

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Toolchain-minimum awareness for Firefox source hops.
+ *
+ * When `fireforge download --force` moves the engine to a new Firefox
+ * MAJOR version, the tree's declared toolchain minimums (cbindgen, Rust)
+ * frequently move with it — and the first `fireforge build` then dies a
+ * few seconds into `mach configure` with a message whose remediation
+ * text names `./mach bootstrap`, the wrong tool for a FireForge-managed
+ * repo (152.0b7 → 153.0b8 source-refresh drill: `ERROR: cbindgen version
+ * 0.29.1 is too old. At least version 0.29.4 is required.`).
+ *
+ * Two layers:
+ *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when
+ *     the downloaded major differs from the previously downloaded one.
+ *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
+ *     the minimums the tree itself declares against the host binaries
+ *     `mach configure` will resolve, probing configure's own candidate
+ *     order: env override first, then the `~/.mozbuild` state-directory
+ *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
+ *     only, blocking builds whose current tool lived in the state dir
+ *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
+ *     mismatch only when a minimum was positively parsed AND at least
+ *     one candidate resolved AND every resolved candidate is
+ *     definitively lower. Any uncertainty (file moved upstream,
+ *     unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure
+ *     failure downstream.
+ */
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+/**
+ * Resolves the mach state directory the same way mach itself does:
+ * `$MOZBUILD_STATE_PATH`, else `~/.mozbuild` (same resolution as
+ * `mach-resource-shim.ts`).
+ */
+function mozbuildStateDir() {
+    return process.env['MOZBUILD_STATE_PATH'] ?? join(homedir(), '.mozbuild');
+}
+/** Where each tool's minimum is declared inside the Firefox tree. */
+const MINIMUM_DECLARATIONS = {
+    // build/moz.configure/bindgen.configure:
+    //   cbindgen_min_version = Version("0.27.0")
+    cbindgen: {
+        relPath: 'build/moz.configure/bindgen.configure',
+        pattern: /cbindgen_min_version\s*=\s*Version\(\s*["']([\d.]+)["']\s*\)/,
+    },
+    // python/mozboot/mozboot/util.py:
+    //   MINIMUM_RUST_VERSION = "1.82.0"
+    // (build/moz.configure/rust.configure imports this constant, so the
+    // mozboot file is the single authority in the tree.)
+    rustc: {
+        relPath: 'python/mozboot/mozboot/util.py',
+        pattern: /MINIMUM_RUST_VERSION\s*=\s*["']([\d.]+)["']/,
+    },
+};
+/**
+ * How each tool's host binary is resolved and its version parsed.
+ *
+ * `stateDirRelPaths` are the mach-state-directory locations `fireforge
+ * bootstrap` (via mozboot) installs the tool to. mach's configure tries
+ * the state directory BEFORE the PATH candidates (bindgen.configure's
+ * toolchain search path lists `~/.mozbuild/cbindgen/cbindgen` first — a
+ * configure log shows `trying cbindgen: ~/.mozbuild/cbindgen/cbindgen`
+ * ahead of PATH), so the probe must too. 0.35.0 probed only env-or-PATH,
+ * which failed a build configure would have accepted whenever an old
+ * `~/.cargo/bin/cbindgen` shadowed a current bootstrap-installed copy
+ * (field report: PATH 0.29.1 vs mozbuild 0.29.4, minimum 0.29.4). Rust
+ * has no state-dir install — rustup owns it — so its list is empty.
+ */
+const HOST_PROBES = {
+    // `mach configure` honours the CBINDGEN env option (bindgen.configure's
+    // `option(env="CBINDGEN", ...)`), so the probe must too — otherwise the
+    // preflight could veto a build configure would have accepted.
+    cbindgen: {
+        envVar: 'CBINDGEN',
+        versionPattern: /cbindgen\s+(\d+(?:\.\d+)*)/,
+        stateDirRelPaths: ['cbindgen/cbindgen'],
+    },
+    rustc: { envVar: 'RUSTC', versionPattern: /rustc\s+(\d+(?:\.\d+)*)/, stateDirRelPaths: [] },
+};
+/**
+ * Parses a dotted version string into numeric components. Trailing
+ * non-numeric suffixes are ignored; returns undefined when the string
+ * does not start with a number. (Same posture as the furnace version
+ * drift classifier, kept local so the two modules stay decoupled.)
+ */
+function parseVersionComponents(version) {
+    const match = /^(\d+(?:\.\d+)*)/.exec(version.trim());
+    if (!match?.[1])
+        return undefined;
+    return match[1].split('.').map(Number);
+}
+/** Component-wise comparison; missing components count as 0. */
+function isVersionLower(candidate, minimum) {
+    const length = Math.max(candidate.length, minimum.length);
+    for (let i = 0; i < length; i += 1) {
+        const a = candidate[i] ?? 0;
+        const b = minimum[i] ?? 0;
+        if (a !== b)
+            return a < b;
+    }
+    return false;
+}
+/**
+ * Returns the one-line notice to print after a download that hopped the
+ * Firefox MAJOR version, or undefined when no notice is warranted (first
+ * download, same major, or unparseable versions — an unparseable version
+ * must not spam every download with a false hint).
+ *
+ * @param previousVersion - `downloadedVersion` recorded in state before this download
+ * @param newVersion - Version that was just downloaded
+ */
+export function formatMajorVersionHopNotice(previousVersion, newVersion) {
+    if (!previousVersion)
+        return undefined;
+    const previousMajor = parseVersionComponents(previousVersion)?.[0];
+    const newMajor = parseVersionComponents(newVersion)?.[0];
+    if (previousMajor === undefined || newMajor === undefined)
+        return undefined;
+    if (previousMajor === newMajor)
+        return undefined;
+    return (`Firefox major version changed (${String(previousMajor)} → ${String(newMajor)}): ` +
+        'upstream toolchain minimums (cbindgen, Rust, …) may have moved with it. ' +
+        'Consider running "fireforge bootstrap" before the next build.');
+}
+/**
+ * Reads the toolchain minimums the engine tree itself declares. Any file
+ * that is missing or no longer matches the expected declaration shape
+ * yields undefined for that tool — never an error.
+ */
+export async function readDeclaredToolchainMinimums(engineDir) {
+    const minimums = {};
+    for (const [tool, declaration] of Object.entries(MINIMUM_DECLARATIONS)) {
+        const filePath = join(engineDir, declaration.relPath);
+        if (!(await pathExists(filePath))) {
+            verbose(`Toolchain preflight: ${declaration.relPath} not found; skipping ${tool}.`);
+            continue;
+        }
+        try {
+            const content = await readText(filePath);
+            const match = declaration.pattern.exec(content);
+            if (match?.[1]) {
+                minimums[tool] = match[1];
+            }
+            else {
+                verbose(`Toolchain preflight: no ${tool} minimum declaration recognized in ${declaration.relPath}; skipping.`);
+            }
+        }
+        catch (error) {
+            verbose(`Toolchain preflight: could not read ${declaration.relPath} (${error instanceof Error ? error.message : String(error)}); skipping ${tool}.`);
+        }
+    }
+    return minimums;
+}
+/** Runs `<binary> --version` and parses the leading version number. */
+async function probeBinaryVersion(binary, versionPattern) {
+    const output = await new Promise((resolvePromise) => {
+        execFile(binary, ['--version'], { timeout: 10_000 }, (err, stdout) => {
+            resolvePromise(err ? undefined : stdout);
+        });
+    });
+    if (output === undefined)
+        return undefined;
+    const match = versionPattern.exec(output);
+    if (!match?.[1]) {
+        verbose(`Toolchain preflight: could not parse a version from "${output.trim()}" (${binary}).`);
+        return undefined;
+    }
+    return match[1];
+}
+/**
+ * Probes every candidate binary for a tool in mach's resolution order:
+ * the env override (which, when set, is the ONLY candidate — configure
+ * uses it even when a better binary exists elsewhere), then the mozbuild
+ * state-directory copy bootstrap installs, then PATH. Candidates that
+ * fail to run or to parse are dropped silently.
+ */
+async function probeHostToolCandidates(tool) {
+    const probe = HOST_PROBES[tool];
+    const envOverride = process.env[probe.envVar];
+    const binaries = envOverride
+        ? [envOverride]
+        : [...probe.stateDirRelPaths.map((rel) => join(mozbuildStateDir(), rel)), tool];
+    const candidates = [];
+    for (const binary of binaries) {
+        const version = await probeBinaryVersion(binary, probe.versionPattern);
+        if (version !== undefined) {
+            candidates.push({ binary, version });
+        }
+        else {
+            verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping.`);
+        }
+    }
+    return candidates;
+}
+/**
+ * Compares the tree-declared toolchain minimums against the host binaries
+ * `mach configure` will resolve, in configure's own candidate order (env
+ * override, mozbuild state dir, PATH). A tool fails ONLY when at least
+ * one candidate resolved and none of them meets the minimum; any single
+ * passing candidate passes the tool (configure will find it), and a tool
+ * with no resolvable candidate skips silently (see module header for the
+ * fail-soft rationale).
+ *
+ * @param engineDir - Path to the engine directory
+ */
+export async function runToolchainPreflight(engineDir) {
+    const minimums = await readDeclaredToolchainMinimums(engineDir);
+    const mismatches = [];
+    for (const [tool, minimumVersion] of Object.entries(minimums)) {
+        const minimum = parseVersionComponents(minimumVersion);
+        if (!minimum)
+            continue;
+        const candidates = await probeHostToolCandidates(tool);
+        const parsed = candidates.filter((c) => parseVersionComponents(c.version) !== undefined);
+        if (parsed.length === 0)
+            continue;
+        const satisfying = parsed.find((c) => {
+            const components = parseVersionComponents(c.version);
+            return components !== undefined && !isVersionLower(components, minimum);
+        });
+        if (satisfying) {
+            verbose(`Toolchain preflight: ${tool} ${satisfying.version} (${satisfying.binary}) satisfies minimum ${minimumVersion}.`);
+            continue;
+        }
+        mismatches.push({
+            tool,
+            minimumVersion,
+            declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
+            candidates: parsed,
+        });
+    }
+    return mismatches;
+}
+/**
+ * Formats the fail-fast message for definitive preflight mismatches,
+ * listing every candidate probed (in mach's resolution order) and naming
+ * `fireforge bootstrap` as the remedy (mach's own configure error
+ * suggests `./mach bootstrap`, which is the wrong entry point for a
+ * FireForge-managed repo).
+ */
+export function formatToolchainMismatchMessage(mismatches) {
+    const lines = mismatches.map((m) => {
+        const probed = m.candidates.map((c) => `${c.version} (${c.binary})`).join(', ');
+        return (`  - ${m.tool}: no resolvable candidate meets the minimum ${m.minimumVersion} declared by ` +
+            `this Firefox source (engine/${m.declaredIn}); probed in mach's resolution order: ${probed}`);
+    });
+    return ('Toolchain preflight found host tools older than what this Firefox source requires:\n' +
+        `${lines.join('\n')}\n\n` +
+        'This typically happens after "fireforge download --force" moved the engine to a new ' +
+        'Firefox major version. Run "fireforge bootstrap" to update the toolchain, then retry the build.');
+}

package/dist/src/core/typecheck-shim.d.ts

@@ -40,7 +40,10 @@ export interface ComposedShim {
  * direction is intentional (declarations later in concat order
  * augment earlier ones), so a project that wants to refine `Services`
  * with a more specific type can do so by declaring it in the extra
- * shim. Any triple-slash `/// <reference path="…">` directives inside the
+ * shim, and members can be ADDED to the structured globals by merging
+ * their interfaces (`interface ChromeUtilsShim { newMember(): any }` —
+ * see the module doc comment). Any triple-slash
+ * `/// <reference path="…">` directives inside the
  * extra shim are inlined (resolved against the extra shim's own directory)
  * so they are not silently dropped at the synthetic shim path.
  *

package/dist/src/core/typecheck-shim.js

@@ -22,6 +22,23 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  * for the most common Mozilla APIs. Types are intentionally loose
  * (`any`) because full Firefox type coverage is out of scope.
  *
+ * Structured globals (`ChromeUtils`, `Localization`) are declared via
+ * named global interfaces (`ChromeUtilsShim`, `LocalizationShim`, …)
+ * rather than closed object-literal types, so a project's extra shim
+ * (`patchLint.checkJsExtraShim` / `typecheck.extraShim`) can ADD members
+ * through TypeScript interface merging:
+ *
+ *   // my-extra-shim.d.ts
+ *   interface ChromeUtilsShim {
+ *     someNewApi(arg: string): unknown;
+ *   }
+ *
+ * (A second `declare var ChromeUtils` in the extra shim remains a
+ * duplicate-identifier error by design — merge the interface instead.)
+ * The member lists track upstream WebIDL additions per Firefox release
+ * (`dom/chrome-webidl/ChromeUtils.webidl` for ChromeUtils); when a new
+ * release adds a commonly-patched member, add a loose signature here.
+ *
  * Notable patterns that require shimming:
  * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
  *   populates `lazy` at runtime; we declare it as `Record<string, any>`.
@@ -37,16 +54,24 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  */
 const FIREFOX_GLOBALS_SHIM = `
 declare var Services: any;
-declare var ChromeUtils: {
+// Extensible via interface merging from a project extra shim — see the
+// module doc comment in typecheck-shim.ts.
+interface ChromeUtilsShim {
   defineESModuleGetters(target: any, modules: Record<string, string>): void;
   importESModule(specifier: string): any;
   import(specifier: string): any;
+  registerWindowActor(name: string, options: Record<string, any>): void;
   defineModuleGetter(target: any, name: string, specifier: string): void;
   defineLazyGetter(target: any, name: string, getter: () => any): void;
   generateQI(interfaces: any[]): Function;
   getClassName(obj: any, unwrap?: boolean): string;
   isClassInfo(obj: any): boolean;
-};
+  // Firefox 153, dom/chrome-webidl/ChromeUtils.webidl: two overloads
+  // (URI string / nsIURI) with a PredictRemoteTypeOptions dictionary —
+  // collapsed into one loose signature per the shim's pragmatic posture.
+  predictRemoteTypeForURI(uri: string | object | null, options?: object): string | null;
+}
+declare var ChromeUtils: ChromeUtilsShim;
 declare var Cu: any;
 declare var Ci: any;
 declare var Cc: any;
@@ -61,25 +86,41 @@ declare var gBrowser: any;
 declare var gURLBar: any;
 declare var gNavigatorBundle: any;
 declare var AppConstants: any;
+declare class JSWindowActorChild {
+  readonly browsingContext: any;
+  readonly contentWindow: any;
+  readonly document: any;
+  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
+  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
+}
+declare class JSWindowActorParent {
+  readonly browsingContext: any;
+  sendAsyncMessage(name: string, data?: any, transfers?: any[]): void;
+  sendQuery(name: string, data?: any, transfers?: any[]): Promise<any>;
+}
 // Fluent localization — a stable chrome global. Members stay loose (any),
 // but the constructor shape is declared so "new Localization([...])" and
-// "new Localization([...], true)" typecheck without a local cast.
-declare var Localization: {
+// "new Localization([...], true)" typecheck without a local cast. Both
+// interfaces are extensible via interface merging from a project extra
+// shim, same as ChromeUtilsShim.
+interface LocalizationInstanceShim {
+  formatValue(id: string, args?: Record<string, unknown>): any;
+  formatValues(keys: any[]): any;
+  formatMessages(keys: any[]): any;
+  formatValueSync(id: string, args?: Record<string, unknown>): any;
+  formatValuesSync(keys: any[]): any;
+  formatMessagesSync(keys: any[]): any;
+  addResourceIds(ids: Array<string | { path: string; optional?: boolean }>): void;
+  removeResourceIds(ids: string[]): number;
+  setAsync(): void;
+}
+interface LocalizationShim {
   new (
     resourceIds: Array<string | { path: string; optional?: boolean }>,
     sync?: boolean
-  ): {
-    formatValue(id: string, args?: Record<string, unknown>): any;
-    formatValues(keys: any[]): any;
-    formatMessages(keys: any[]): any;
-    formatValueSync(id: string, args?: Record<string, unknown>): any;
-    formatValuesSync(keys: any[]): any;
-    formatMessagesSync(keys: any[]): any;
-    addResourceIds(ids: Array<string | { path: string; optional?: boolean }>): void;
-    removeResourceIds(ids: string[]): number;
-    setAsync(): void;
-  };
-};
+  ): LocalizationInstanceShim;
+}
+declare var Localization: LocalizationShim;
 
 // Shorthand ambient modules — exports from matching URL imports are loosely typed,
 // avoiding noResolve empty-graph namespaces. (Named member access broke when we tried
@@ -154,7 +195,10 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
  * direction is intentional (declarations later in concat order
  * augment earlier ones), so a project that wants to refine `Services`
  * with a more specific type can do so by declaring it in the extra
- * shim. Any triple-slash `/// <reference path="…">` directives inside the
+ * shim, and members can be ADDED to the structured globals by merging
+ * their interfaces (`interface ChromeUtilsShim { newMember(): any }` —
+ * see the module doc comment). Any triple-slash
+ * `/// <reference path="…">` directives inside the
  * extra shim are inlined (resolved against the extra shim's own directory)
  * so they are not silently dropped at the synthetic shim path.
  *
@@ -182,4 +226,3 @@ export async function composeShimSource(projectRoot, extraShimPath) {
         extraShimAppended: true,
     };
 }
-//# sourceMappingURL=typecheck-shim.js.map

package/dist/src/core/typecheck.js

@@ -327,4 +327,3 @@ export function relativeForDisplay(projectRoot, absoluteFile) {
         return absoluteFile;
     return rel;
 }
-//# sourceMappingURL=typecheck.js.map

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

@@ -121,4 +121,3 @@ export async function addDestroyToBrowserInit(engineDir, expression, marker = DE
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-destroy.js.map

package/dist/src/core/wire-dom-fragment.js

@@ -181,4 +181,3 @@ export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAUL
     await writeText(targetAbsPath, value);
     return true;
 }
-//# sourceMappingURL=wire-dom-fragment.js.map

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

@@ -231,4 +231,3 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-init.js.map

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

@@ -144,4 +144,3 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
     await writeText(filePath, value);
     return true;
 }
-//# sourceMappingURL=wire-subscript.js.map

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

@@ -6,4 +6,3 @@ export { addDestroyToBrowserInit } from './wire-destroy.js';
 export { addDomFragment } from './wire-dom-fragment.js';
 export { addInitToBrowserInit } from './wire-init.js';
 export { addSubscriptToBrowserMain } from './wire-subscript.js';
-//# sourceMappingURL=wire-targets.js.map

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

@@ -349,4 +349,3 @@ export function findMethodBody(ast, methodName) {
     });
     return found;
 }
-//# sourceMappingURL=wire-utils.js.map

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

@@ -41,6 +41,7 @@
 import { readdir, stat } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 import { pathExists, readJson, readText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
 import { isObject, isString } from '../utils/validation.js';
 /**
  * `[DEFAULT]` section parser shaped to the narrow case we need: pull a
@@ -88,9 +89,6 @@ export function parseAppdirFromToml(tomlText, key) {
     }
     return undefined;
 }
-function escapeRegex(input) {
-    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 function stripQuotes(raw) {
     if (raw.length === 0)
         return undefined;
@@ -305,4 +303,3 @@ export function operatorAlreadySetAppPath(extraArgs) {
     }
     return false;
 }
-//# sourceMappingURL=xpcshell-appdir.js.map

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

@@ -54,6 +54,35 @@ export declare class InvalidArgumentError extends FireForgeError {
     constructor(message: string, argument?: string | undefined, cause?: Error);
     get userMessage(): string;
 }
+/**
+ * Error thrown when a spawned command exceeds its `timeout` option.
+ *
+ * Every `exec*` helper in `src/utils/process.ts` rejects with this type
+ * (instead of Node's bare `AbortError: The operation was aborted`) when the
+ * caller-supplied timeout fires. The bare AbortError bit an operator during
+ * the 2026-04-24 eval (see {@link GitIndexingTimeoutError} in errors/git.ts):
+ * an 854 s git indexing pass died with no command name, no elapsed time, and
+ * no hint that a timeout — not git — was responsible. The git path gained a
+ * site-local typed error then; this class extends the same courtesy to every
+ * other `timeout` caller.
+ */
+export declare class ExecTimeoutError extends FireForgeError {
+    /** Executable that was spawned (argv[0]). */
+    readonly command: string;
+    /** Arguments the executable was spawned with. */
+    readonly args: readonly string[];
+    /** Timeout that elapsed, in milliseconds. */
+    readonly timeoutMs: number;
+    readonly code: 1;
+    constructor(
+    /** Executable that was spawned (argv[0]). */
+    command: string, 
+    /** Arguments the executable was spawned with. */
+    args: readonly string[], 
+    /** Timeout that elapsed, in milliseconds. */
+    timeoutMs: number, cause?: unknown);
+    get userMessage(): string;
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */

package/dist/src/errors/base.js

@@ -78,6 +78,41 @@ export class InvalidArgumentError extends FireForgeError {
         return msg;
     }
 }
+/**
+ * Error thrown when a spawned command exceeds its `timeout` option.
+ *
+ * Every `exec*` helper in `src/utils/process.ts` rejects with this type
+ * (instead of Node's bare `AbortError: The operation was aborted`) when the
+ * caller-supplied timeout fires. The bare AbortError bit an operator during
+ * the 2026-04-24 eval (see {@link GitIndexingTimeoutError} in errors/git.ts):
+ * an 854 s git indexing pass died with no command name, no elapsed time, and
+ * no hint that a timeout — not git — was responsible. The git path gained a
+ * site-local typed error then; this class extends the same courtesy to every
+ * other `timeout` caller.
+ */
+export class ExecTimeoutError extends FireForgeError {
+    command;
+    args;
+    timeoutMs;
+    code = ExitCode.GENERAL_ERROR;
+    constructor(
+    /** Executable that was spawned (argv[0]). */
+    command, 
+    /** Arguments the executable was spawned with. */
+    args, 
+    /** Timeout that elapsed, in milliseconds. */
+    timeoutMs, cause) {
+        super(`Command timed out after ${Math.round(timeoutMs / 1000)}s: ${[command, ...args].join(' ')}`, cause);
+        this.command = command;
+        this.args = args;
+        this.timeoutMs = timeoutMs;
+    }
+    get userMessage() {
+        return (`${this.message}\n\n` +
+            'The command was killed because it exceeded its time budget, not because it failed on its own. ' +
+            'If the host is just slow or loaded, re-running may succeed.');
+    }
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */
@@ -108,4 +143,3 @@ export class CommandError extends Error {
         this.name = 'CommandError';
     }
 }
-//# sourceMappingURL=base.js.map