@hominis/fireforge 0.34.1 → 0.35.0

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

@@ -0,0 +1,195 @@
+// 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. Deliberately FAIL-SOFT: it reports
+ *     a mismatch only when a minimum was positively parsed AND the host
+ *     binary was found AND its version is definitively lower. Any
+ *     uncertainty (file moved upstream, unparseable output, binary not
+ *     on PATH) skips silently — the mach-error-hints translator still
+ *     catches the real configure failure downstream.
+ */
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+/** 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. */
+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+)*)/ },
+    rustc: { envVar: 'RUSTC', versionPattern: /rustc\s+(\d+(?:\.\d+)*)/ },
+};
+/**
+ * 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 probeHostToolVersion(tool) {
+    const probe = HOST_PROBES[tool];
+    const binary = process.env[probe.envVar] ?? tool;
+    const output = await new Promise((resolvePromise) => {
+        execFile(binary, ['--version'], { timeout: 10_000 }, (err, stdout) => {
+            resolvePromise(err ? undefined : stdout);
+        });
+    });
+    if (output === undefined) {
+        verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping ${tool}.`);
+        return undefined;
+    }
+    const match = probe.versionPattern.exec(output);
+    if (!match?.[1]) {
+        verbose(`Toolchain preflight: could not parse ${tool} version from "${output.trim()}".`);
+        return undefined;
+    }
+    return match[1];
+}
+/**
+ * Compares the tree-declared toolchain minimums against the host binaries
+ * `mach configure` will resolve. Returns only DEFINITIVE mismatches; every
+ * uncertain probe passes silently (see module header for the 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 hostVersion = await probeHostToolVersion(tool);
+        if (hostVersion === undefined)
+            continue;
+        const host = parseVersionComponents(hostVersion);
+        if (!host)
+            continue;
+        if (isVersionLower(host, minimum)) {
+            mismatches.push({
+                tool,
+                hostVersion,
+                minimumVersion,
+                declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
+            });
+        }
+        else {
+            verbose(`Toolchain preflight: ${tool} ${hostVersion} satisfies minimum ${minimumVersion}.`);
+        }
+    }
+    return mismatches;
+}
+/**
+ * Formats the fail-fast message for definitive preflight mismatches,
+ * 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) => `  - ${m.tool} ${m.hostVersion} is older than the minimum ${m.minimumVersion} declared by this Firefox source (engine/${m.declaredIn})`);
+    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.');
+}
+//# sourceMappingURL=toolchain-preflight.js.map

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,7 +54,9 @@ 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;
@@ -46,7 +65,12 @@ declare var ChromeUtils: {
   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;
@@ -63,23 +87,27 @@ declare var gNavigatorBundle: any;
 declare var AppConstants: 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 +182,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.
  *

package/dist/src/errors/download.js

@@ -65,8 +65,10 @@ export class ExtractionError extends DownloadError {
         this.archivePath = archivePath;
     }
     get userMessage() {
+        const reason = this.cause instanceof Error ? `Reason: ${this.cause.message}\n\n` : '';
         return (`Extraction Error: Failed to extract Firefox source archive.\n\n` +
             `Archive: ${this.archivePath}\n\n` +
+            reason +
             'To fix this:\n' +
             '  1. Delete the corrupted archive and try again\n' +
             '  2. Ensure you have enough disk space\n' +

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

@@ -389,6 +389,13 @@ export interface RunOptions {
      * inspect the raw stream after smoke-exit returns.
      */
     captureConsole?: string;
+    /**
+     * Launch the browser with `--headless` (forwarded to the binary via
+     * `mach run`). Primarily for smoke mode on shared desktops: a headed
+     * smoke window absorbs live keyboard/mouse input, and the resulting
+     * console errors contaminate the capture and can fail the run.
+     */
+    headless?: boolean;
 }
 /**
  * Options for the test command.

package/package.json

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