@hominis/fireforge 0.34.2 → 0.35.0

package/dist/src/core/license-headers.d.ts

@@ -38,6 +38,22 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  * @param style   - Comment syntax of the file
  */
 export declare function hasAnyLicenseHeader(content: string, style: CommentStyle): boolean;
+/**
+ * Returns true if `content` starts with the verbatim upstream Mozilla
+ * MPL-2.0 block header (`/* This Source Code Form … *\/`), optionally
+ * preceded by editor-directive comments — the exact shape a JS file
+ * copied from the Firefox source tree carries.
+ *
+ * Deliberately independent of the project license: a new JS file that
+ * legitimately keeps its upstream MPL block header (copied-from-upstream
+ * provenance) is valid in an EUPL/GPL/0BSD project too. Before 0.35.0
+ * this acceptance only existed behind a `license === 'MPL-2.0'` gate in
+ * patch-lint, making it dead code for every other project license and
+ * forcing repo-side audit workarounds.
+ *
+ * @param content - File content to check
+ */
+export declare function hasUpstreamMplBlockHeader(content: string): boolean;
 /**
  * Returns true if `content` starts with any known license header in any
  * comment style (js, css, hash).

package/dist/src/core/license-headers.js

@@ -119,6 +119,25 @@ export function hasAnyLicenseHeader(content, style) {
     }
     return false;
 }
+/**
+ * Returns true if `content` starts with the verbatim upstream Mozilla
+ * MPL-2.0 block header (`/* This Source Code Form … *\/`), optionally
+ * preceded by editor-directive comments — the exact shape a JS file
+ * copied from the Firefox source tree carries.
+ *
+ * Deliberately independent of the project license: a new JS file that
+ * legitimately keeps its upstream MPL block header (copied-from-upstream
+ * provenance) is valid in an EUPL/GPL/0BSD project too. Before 0.35.0
+ * this acceptance only existed behind a `license === 'MPL-2.0'` gate in
+ * patch-lint, making it dead code for every other project license and
+ * forcing repo-side audit workarounds.
+ *
+ * @param content - File content to check
+ */
+export function hasUpstreamMplBlockHeader(content) {
+    const blockHeader = getLicenseHeader('MPL-2.0', 'css');
+    return (content.startsWith(blockHeader) || stripLeadingEditorDirectives(content).startsWith(blockHeader));
+}
 /**
  * Returns true if `content` starts with any known license header in any
  * comment style (js, css, hash).

package/dist/src/core/mach-error-hints.js

@@ -56,6 +56,33 @@ export const MACH_ERROR_HINTS = [
             'remove any `pub type basic_string___self_view = …<_CharT>;` line from ' +
             '`<objdir>/release/build/gecko-profiler-*/out/gecko/bindings.rs`.',
     },
+    {
+        // Firefox declares per-release toolchain minimums in-tree
+        // (`build/moz.configure/bindgen.configure` for cbindgen; mozboot's
+        // MINIMUM_RUST_VERSION for rustc/cargo), and a source hop can move
+        // them. The 152.0b7 → 153.0b8 source-refresh drill hit exactly this:
+        // the first post-hop build died ~8s into `mach configure` with
+        // "ERROR: cbindgen version 0.29.1 is too old. At least version
+        // 0.29.4 is required." — and mach's own remediation text names
+        // "./mach bootstrap", the wrong entry point for a FireForge-managed
+        // repo. Pattern matches configure's cbindgen die() shape.
+        pattern: /\bversion [\d.]+ is too old\.?\s+At least version [\d.]+ is required/i,
+        hint: 'A toolchain component is older than the minimum this Firefox source declares — typical ' +
+            'after "fireforge download --force" moved the engine to a new Firefox major version. ' +
+            'Run "fireforge bootstrap" (not mach\'s suggested "./mach bootstrap") to update the ' +
+            'toolchain, then retry the build.',
+    },
+    {
+        // Same family, rust.configure's die() shapes: "Rust compiler {v} is
+        // too old." / "Cargo package manager {v} is too old." — the minimum
+        // is only named further down that message, so the pattern keys on
+        // the first line.
+        pattern: /\b(?:Rust compiler|Cargo package manager) [\d.]+(?:[\w.-]*)? is too old/i,
+        hint: "The Rust toolchain is older than the minimum this Firefox source declares (mozboot's " +
+            'MINIMUM_RUST_VERSION) — typical after "fireforge download --force" moved the engine to a ' +
+            'new Firefox major version. Run "fireforge bootstrap" to update the toolchain, then retry ' +
+            'the build.',
+    },
     {
         // When `mach build` fails mid-compile, mach's own shutdown pipeline still
         // runs its trailing "Config object not found by mach. / Configure

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

@@ -3,8 +3,8 @@
  * Patch orchestration — coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
-import { lstat } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { lstat, readlink, realpath } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
@@ -159,33 +159,63 @@ export async function validatePatches(patchesDir, engineDir) {
     return { valid: errors.length === 0, errors };
 }
 async function validatePatchTargets(patch, affectedFiles, engineDir) {
+    // realpath the engine root once so containment is checked against the
+    // physical tree (the root itself may sit behind a symlink, e.g. /tmp on
+    // macOS). An unresolvable engine dir skips the symlink checks — a missing
+    // engine surfaces through `git apply --check` with a better message.
+    const engineRoot = engineDir ? await realpath(engineDir).catch(() => null) : null;
     for (const file of affectedFiles) {
         if (!isContainedRelativePath(file)) {
             throw new PatchError(`Patch targets a path outside engine/: ${file}`, patch.filename);
         }
-        // When the engine directory is known, verify that existing target paths
-        // are not symlinks pointing outside the engine tree. A crafted patch
-        // could otherwise write through a symlink to an arbitrary location.
-        if (engineDir) {
-            const targetPath = join(engineDir, file);
-            try {
-                const stats = await lstat(targetPath);
-                if (stats.isSymbolicLink()) {
-                    const realPath = resolve(engineDir, file);
-                    const resolvedEngine = resolve(engineDir);
-                    if (!realPath.startsWith(resolvedEngine + '/') && realPath !== resolvedEngine) {
-                        throw new PatchError(`Patch targets a symlink that resolves outside engine/: ${file}`, patch.filename);
-                    }
-                }
-            }
-            catch (error) {
-                // File doesn't exist yet (new file) or stat fails — skip check
-                if (error instanceof PatchError)
-                    throw error;
+        // Verify that a write to the target would physically land inside the
+        // engine tree. A crafted patch could otherwise write through a symlink
+        // (the target itself, a dangling link, or a symlinked parent directory)
+        // to an arbitrary location.
+        if (engineDir && engineRoot) {
+            const destination = await resolvePatchWriteDestination(join(engineDir, file));
+            if (destination !== engineRoot && !destination.startsWith(engineRoot + sep)) {
+                throw new PatchError(`Patch targets a path that resolves outside engine/ (symlink escape): ${file}`, patch.filename);
             }
         }
     }
 }
+/**
+ * Resolves where a write to `targetPath` would physically land, following
+ * symlinks on every path component that already exists.
+ *
+ * - Existing target: `realpath` resolves it fully.
+ * - Dangling symlink: `realpath` rejects it, but a write through the link
+ *   would still be created at the link target, so the target is resolved
+ *   against the link's (real) parent directory. The link target is taken
+ *   textually — a loop or nested dangling link fails at apply time anyway.
+ * - Not-yet-existing file: resolved against the nearest existing ancestor's
+ *   real path. Components below that ancestor do not exist, so they cannot
+ *   be symlinks and are appended verbatim.
+ */
+async function resolvePatchWriteDestination(targetPath) {
+    try {
+        return await realpath(targetPath);
+    }
+    catch {
+        // Fall through: the path (or its symlink target) does not exist.
+    }
+    try {
+        const stats = await lstat(targetPath);
+        if (stats.isSymbolicLink()) {
+            const linkTarget = await readlink(targetPath);
+            return resolve(await resolvePatchWriteDestination(dirname(targetPath)), linkTarget);
+        }
+    }
+    catch {
+        // The path component itself does not exist.
+    }
+    const parent = dirname(targetPath);
+    if (parent === targetPath) {
+        return targetPath;
+    }
+    return join(await resolvePatchWriteDestination(parent), basename(targetPath));
+}
 /**
  * Decides whether a patch filename matches an `--until` identifier.
  *

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

@@ -2,7 +2,7 @@
 import { dirname, join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { stripJsComments } from '../utils/regex.js';
-import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, } from './license-headers.js';
+import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, hasUpstreamMplBlockHeader, } from './license-headers.js';
 import { invokePatchLintCheckJs } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
 import { lintPatchedCss } from './patch-lint-css.js';
@@ -251,6 +251,17 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
         // browser/base/content) do not need `--skip-lint` to land it.
         if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
             continue;
+        // Accept the verbatim upstream MPL block header on new JS files
+        // REGARDLESS of the project license: a file copied from the Firefox
+        // tree legitimately keeps Mozilla's header for provenance in an
+        // EUPL/GPL/0BSD project too. The carve-out above is gated on the
+        // project being MPL-2.0 itself, which made this documented case dead
+        // code for every other license — consumers carried repo-side audit
+        // workarounds (recorded 2026-07-04 in the Hominis FORGE.md). Only
+        // the block-comment form is accepted; the `// `-style MPL header is
+        // FireForge-generated, not upstream provenance.
+        if (style === 'js' && hasUpstreamMplBlockHeader(content))
+            continue;
         issues.push({
             file,
             check: 'missing-license-header',

package/dist/src/core/patch-manifest-io.js

@@ -13,7 +13,7 @@ import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readJson, removeFile, writeJson } from '../utils/fs.js';
+import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { isArray, isObject } from '../utils/validation.js';
 import { validatePatchesManifest } from './patch-manifest-validate.js';
@@ -25,7 +25,7 @@ export const PATCHES_MANIFEST = 'patches.json';
  */
 export async function loadPatchesManifestState(patchesDir) {
     const manifestPath = join(patchesDir, PATCHES_MANIFEST);
-    if (!(await pathExists(manifestPath))) {
+    if (!(await pathExistsStrict(manifestPath))) {
         return { exists: false, manifest: null, parseError: undefined };
     }
     try {
@@ -70,7 +70,7 @@ export async function savePatchesManifest(patchesDir, manifest) {
  */
 export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator) {
     const manifestPath = join(patchesDir, PATCHES_MANIFEST);
-    if (!(await pathExists(manifestPath)))
+    if (!(await pathExistsStrict(manifestPath)))
         return null;
     const rawManifest = await readJson(manifestPath);
     const beforeManifest = validatePatchesManifest(rawManifest);
@@ -252,7 +252,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     try {
         for (const [oldFilename, entry] of renameMap) {
             const oldPath = join(patchesDir, oldFilename);
-            if (!(await pathExists(oldPath))) {
+            if (!(await pathExistsStrict(oldPath))) {
                 throw new Error(`Cannot renumber: patch file is missing on disk: ${oldFilename}`);
             }
             const stagedName = `.fireforge-renumber-${stagingId}-${oldFilename}`;
@@ -280,7 +280,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         for (const stagedEntry of stagedRenames) {
             const { staged, toEntry } = stagedEntry;
             const targetPath = join(patchesDir, toEntry.newFilename);
-            if (await pathExists(targetPath)) {
+            if (await pathExistsStrict(targetPath)) {
                 throw new Error(`Cannot renumber: target patch filename already exists on disk: ${toEntry.newFilename}`);
             }
             await rename(join(patchesDir, staged), targetPath);
@@ -291,7 +291,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
             // described: manifest rewrote to new filenames while the old
             // files stayed on disk. If the assert ever fires, the Phase 2
             // rollback will undo prior moves before re-throwing.
-            if (!(await pathExists(targetPath))) {
+            if (!(await pathExistsStrict(targetPath))) {
                 throw new Error(`Rename postcondition failed: expected ${toEntry.newFilename} to exist after rename, but it was not found on disk.`);
             }
             completedFinalRenames.push(stagedEntry);
@@ -428,7 +428,7 @@ export async function removePatchFileAndManifest(patchesDir, filename) {
     const originalManifest = await loadPatchesManifest(patchesDir);
     const removedFromManifest = await removePatchFromManifest(patchesDir, filename);
     try {
-        if (await pathExists(patchPath)) {
+        if (await pathExistsStrict(patchPath)) {
             await removeFile(patchPath);
         }
     }

package/dist/src/core/patch-manifest-query.d.ts

@@ -42,6 +42,12 @@ export declare function validatePatchIntegrity(patchesDir: string, engineDir: st
 /**
  * Stamps multiple patches with a new source version in a single
  * manifest read-modify-write cycle.
+ *
+ * Acquires the shared patch-directory lock for the read-modify-write, so a
+ * concurrent export/reorder/metadata update cannot interleave with the stamp.
+ * The lock is not reentrant — callers must NOT invoke this while already
+ * holding {@link withPatchDirectoryLock} on the same patches directory.
+ *
  * @param patchesDir - Path to the patches directory
  * @param filenames - Patch filenames to update
  * @param newVersion - Version string to set (e.g. "140.9.0esr")

package/dist/src/core/patch-manifest-query.js

@@ -5,6 +5,7 @@
 import { readText } from '../utils/fs.js';
 import { fileExistsInHead } from './git-file-ops.js';
 import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
+import { withPatchDirectoryLock } from './patch-lock.js';
 import { loadPatchesManifest, mutatePatchRowsInManifest } from './patch-manifest-io.js';
 import { isNewFileInPatch } from './patch-parse.js';
 /**
@@ -101,12 +102,18 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
 /**
  * Stamps multiple patches with a new source version in a single
  * manifest read-modify-write cycle.
+ *
+ * Acquires the shared patch-directory lock for the read-modify-write, so a
+ * concurrent export/reorder/metadata update cannot interleave with the stamp.
+ * The lock is not reentrant — callers must NOT invoke this while already
+ * holding {@link withPatchDirectoryLock} on the same patches directory.
+ *
  * @param patchesDir - Path to the patches directory
  * @param filenames - Patch filenames to update
  * @param newVersion - Version string to set (e.g. "140.9.0esr")
  */
 export async function stampPatchVersions(patchesDir, filenames, newVersion, newProduct) {
-    await mutatePatchRowsInManifest(patchesDir, filenames, (patch, rawPatch) => {
+    await withPatchDirectoryLock(patchesDir, () => mutatePatchRowsInManifest(patchesDir, filenames, (patch, rawPatch) => {
         if (patch.sourceEsrVersion !== newVersion ||
             rawPatch['sourceVersion'] !== newVersion ||
             (newProduct !== undefined && rawPatch['sourceProduct'] !== newProduct)) {
@@ -119,6 +126,6 @@ export async function stampPatchVersions(patchesDir, filenames, newVersion, newP
             };
         }
         return null;
-    });
+    }));
 }
 //# sourceMappingURL=patch-manifest-query.js.map

package/dist/src/core/test-path-scope.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Directory-argument scope analysis for `fireforge test`.
+ *
+ * mozbuild's test resolver matches command-line paths by STRING PREFIX,
+ * so `fireforge test browser/base/content/test/hominis` silently also
+ * ran the sibling directory `browser/base/content/test/hominis-tiles`
+ * (152.0b7 → 153.0b8 source-refresh drill: 1224 tests instead of ~200,
+ * with no indication the scope widened). A trailing separator makes the
+ * prefix match exact — `hominis/` cannot prefix `hominis-tiles/…`.
+ *
+ * FireForge therefore treats a directory argument as meaning EXACTLY
+ * that directory: {@link analyzeTestPathScopes} returns a trailing-`/`
+ * dispatch form for every existing directory, plus the sibling
+ * directories the raw prefix would have swept in so the command layer
+ * can tell the operator what was excluded. Note FireForge already
+ * rejects non-existent paths up front, so raw prefix-widening was never
+ * something an operator could invoke deliberately — it only ever
+ * happened by accident.
+ */
+/** A sibling directory the raw mach prefix match would have included. */
+export interface SiblingPrefixMatch {
+    /** Engine-relative path of the sibling directory. */
+    path: string;
+    /** Recursive count of `browser_*` / `test_*` JS files under it. */
+    testFileCount: number;
+}
+/** Scope analysis for one `fireforge test` path argument. */
+export interface TestPathScope {
+    /** The path as the operator passed it (engine-relative, normalized). */
+    requestedPath: string;
+    /**
+     * The form to hand to mach: directories gain a trailing `/` so
+     * mozbuild's prefix match is exact; files pass through unchanged.
+     */
+    dispatchPath: string;
+    /** True when the path resolved to a directory under engine/. */
+    isDirectory: boolean;
+    /** Recursive test-file count inside the requested directory (0 for files). */
+    testFileCount: number;
+    /** Sibling directories a raw prefix match would also have selected. */
+    siblingPrefixMatches: SiblingPrefixMatch[];
+}
+/**
+ * Analyzes every test path argument of a run.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param requestedPaths - Engine-relative test path arguments
+ */
+export declare function analyzeTestPathScopes(engineDir: string, requestedPaths: readonly string[]): Promise<TestPathScope[]>;
+/**
+ * Formats the sibling-exclusion notice for one scope, or undefined when
+ * nothing needs saying (file arg, or no prefix-matching siblings).
+ */
+export declare function formatScopeNotice(scope: TestPathScope): string | undefined;

package/dist/src/core/test-path-scope.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Directory-argument scope analysis for `fireforge test`.
+ *
+ * mozbuild's test resolver matches command-line paths by STRING PREFIX,
+ * so `fireforge test browser/base/content/test/hominis` silently also
+ * ran the sibling directory `browser/base/content/test/hominis-tiles`
+ * (152.0b7 → 153.0b8 source-refresh drill: 1224 tests instead of ~200,
+ * with no indication the scope widened). A trailing separator makes the
+ * prefix match exact — `hominis/` cannot prefix `hominis-tiles/…`.
+ *
+ * FireForge therefore treats a directory argument as meaning EXACTLY
+ * that directory: {@link analyzeTestPathScopes} returns a trailing-`/`
+ * dispatch form for every existing directory, plus the sibling
+ * directories the raw prefix would have swept in so the command layer
+ * can tell the operator what was excluded. Note FireForge already
+ * rejects non-existent paths up front, so raw prefix-widening was never
+ * something an operator could invoke deliberately — it only ever
+ * happened by accident.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+/** Test implementation files as mozbuild manifests name them. */
+const TEST_FILE_PATTERN = /^(?:browser|test)_.*\.m?js$/;
+/**
+ * Recursively counts test-implementation files under a directory.
+ * Returns 0 when the directory cannot be read — the count feeds an
+ * informational notice, never a decision.
+ */
+async function countTestFiles(dir) {
+    let count = 0;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            count += await countTestFiles(join(dir, entry.name));
+        }
+        else if (entry.isFile() && TEST_FILE_PATTERN.test(entry.name)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+/** Probes whether `path` is a directory, without throwing. */
+async function isDirectorySafe(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Analyzes one engine-relative test path argument. See the module doc
+ * comment for the semantics.
+ */
+async function analyzeTestPathScope(engineDir, requestedPath) {
+    const stripped = requestedPath.replace(/\/+$/, '');
+    const absolute = join(engineDir, stripped);
+    if (!(await isDirectorySafe(absolute))) {
+        return {
+            requestedPath,
+            dispatchPath: requestedPath,
+            isDirectory: false,
+            testFileCount: 0,
+            siblingPrefixMatches: [],
+        };
+    }
+    const siblingPrefixMatches = [];
+    const base = basename(stripped);
+    const parentRel = dirname(stripped);
+    try {
+        const siblings = await readdir(dirname(absolute), { withFileTypes: true });
+        for (const entry of siblings) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === base || !entry.name.startsWith(base))
+                continue;
+            const siblingRel = parentRel === '.' ? entry.name : `${parentRel}/${entry.name}`;
+            const testFileCount = await countTestFiles(join(dirname(absolute), entry.name));
+            // A prefix-matching sibling with no test files never surfaces in a
+            // mach run, so listing it would only add noise.
+            if (testFileCount > 0) {
+                siblingPrefixMatches.push({ path: siblingRel, testFileCount });
+            }
+        }
+    }
+    catch {
+        // Unreadable parent: skip the sibling probe; exactness via the
+        // trailing separator is preserved regardless.
+    }
+    return {
+        requestedPath,
+        dispatchPath: `${stripped}/`,
+        isDirectory: true,
+        testFileCount: await countTestFiles(absolute),
+        siblingPrefixMatches,
+    };
+}
+/**
+ * Analyzes every test path argument of a run.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param requestedPaths - Engine-relative test path arguments
+ */
+export async function analyzeTestPathScopes(engineDir, requestedPaths) {
+    const scopes = [];
+    for (const requestedPath of requestedPaths) {
+        scopes.push(await analyzeTestPathScope(engineDir, requestedPath));
+    }
+    return scopes;
+}
+/**
+ * Formats the sibling-exclusion notice for one scope, or undefined when
+ * nothing needs saying (file arg, or no prefix-matching siblings).
+ */
+export function formatScopeNotice(scope) {
+    if (!scope.isDirectory || scope.siblingPrefixMatches.length === 0)
+        return undefined;
+    const siblings = scope.siblingPrefixMatches
+        .map((s) => `${s.path}/ (${s.testFileCount} test file${s.testFileCount === 1 ? '' : 's'})`)
+        .join(', ');
+    return (`Selected exactly ${scope.dispatchPath} (${scope.testFileCount} test file${scope.testFileCount === 1 ? '' : 's'}). ` +
+        `Excluded ${scope.siblingPrefixMatches.length} sibling director${scope.siblingPrefixMatches.length === 1 ? 'y' : 'ies'} ` +
+        `that a raw prefix match would also have run: ${siblings}. ` +
+        'Pass them as separate paths to include them.');
+}
+//# sourceMappingURL=test-path-scope.js.map

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

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+/** Tools the preflight knows how to probe. */
+export type ToolchainTool = 'cbindgen' | 'rustc';
+/** One definitive host-vs-tree mismatch found by the preflight. */
+export interface ToolchainMismatch {
+    tool: ToolchainTool;
+    hostVersion: string;
+    minimumVersion: string;
+    /** Engine-relative file the minimum was parsed from. */
+    declaredIn: string;
+}
+/**
+ * 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. Returns only DEFINITIVE mismatches; every
+ * uncertain probe passes silently (see module header for the 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,
+ * 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;