@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/mach-build-artifacts.js

@@ -1,436 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readdir } from 'node:fs/promises';
-import { join, relative, resolve, sep } from 'node:path';
-import { GeneralError } from '../errors/base.js';
-import { AmbiguousBuildArtifactsError } from '../errors/build.js';
-import { toError } from '../utils/errors.js';
-import { pathExists, readJson, readText, writeJson } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { getPlatform } from '../utils/platform.js';
-import { isObject, isString } from '../utils/validation.js';
-import { extractMozObjdirName } from './mach-mozconfig.js';
-import { findStaleObjdirLink, relocateObjdirProducts } from './objdir-maintenance.js';
-function validateBuildMozinfo(data) {
-    if (!isObject(data)) {
-        throw new Error('mozinfo metadata must be an object');
-    }
-    const mozinfo = {};
-    if (data['topsrcdir'] !== undefined) {
-        if (!isString(data['topsrcdir'])) {
-            throw new Error('mozinfo.topsrcdir must be a string');
-        }
-        mozinfo.topsrcdir = data['topsrcdir'];
-    }
-    if (data['topobjdir'] !== undefined) {
-        if (!isString(data['topobjdir'])) {
-            throw new Error('mozinfo.topobjdir must be a string');
-        }
-        mozinfo.topobjdir = data['topobjdir'];
-    }
-    if (data['mozconfig'] !== undefined) {
-        if (!isString(data['mozconfig'])) {
-            throw new Error('mozinfo.mozconfig must be a string');
-        }
-        mozinfo.mozconfig = data['mozconfig'];
-    }
-    return mozinfo;
-}
-/**
- * Reads the objdir name the engine's mozconfig declares, or undefined when
- * there is no mozconfig, it cannot be read, or it declares nothing.
- *
- * Fail-open: this only ever narrows an ambiguity that would
- * otherwise refuse, so an unreadable mozconfig costs nothing beyond the
- * refusal the caller was already going to raise.
- */
-async function readDeclaredObjDirName(engineDir) {
-    try {
-        const mozconfigPath = join(engineDir, 'mozconfig');
-        if (!(await pathExists(mozconfigPath)))
-            return undefined;
-        return extractMozObjdirName(await readText(mozconfigPath));
-    }
-    catch (error) {
-        verbose(`Could not read mozconfig for MOZ_OBJDIR: ${toError(error).message}`);
-        return undefined;
-    }
-}
-/**
- * Checks if build artifacts exist in the engine directory.
- * Looks for obj-* directories with a dist subdirectory. Detection is
- * symlink-agnostic on purpose: building/running against a symlinked
- * objdir in place is the user's own arrangement. The clone path, where a
- * symlink would route writes into the original build, refuses separately
- * (`assertCloneSafeObjdir` in tree-store.ts).
- * @param engineDir - Path to the engine directory
- * @returns Build artifact check result
- */
-export async function hasBuildArtifacts(engineDir) {
-    try {
-        const entries = await readdir(engineDir);
-        const objDirs = entries.filter((e) => e.startsWith('obj-')).sort();
-        if (objDirs.length === 0) {
-            return { exists: false };
-        }
-        const validObjDirs = [];
-        for (const objDir of objDirs) {
-            const distPath = join(engineDir, objDir, 'dist');
-            if (await pathExists(distPath)) {
-                validObjDirs.push(objDir);
-            }
-        }
-        if (validObjDirs.length === 0) {
-            const firstObjDir = objDirs[0];
-            return firstObjDir ? { exists: false, objDir: firstObjDir } : { exists: false };
-        }
-        let resolvedObjDirs = validObjDirs;
-        let declaredObjDir;
-        if (validObjDirs.length > 1) {
-            // An ambiguous glob is a question the mozconfig may already answer.
-            // Refusing when the active configuration names the objdir sends the
-            // operator to rename a directory to satisfy a scan, when the thing
-            // that decides the build has said which one it is. The refusal is
-            // kept for the genuinely ambiguous case: a declaration that does not
-            // resolve to exactly one candidate selects nothing.
-            declaredObjDir = await readDeclaredObjDirName(engineDir);
-            const declaredMatches = declaredObjDir === undefined
-                ? []
-                : validObjDirs.filter((candidate) => candidate === declaredObjDir);
-            if (declaredMatches.length === 1) {
-                verbose(`Objdir ambiguity resolved by mozconfig MOZ_OBJDIR: ${declaredMatches[0] ?? ''}.`);
-                resolvedObjDirs = declaredMatches;
-            }
-            else {
-                return {
-                    exists: true,
-                    ambiguous: true,
-                    objDirs: validObjDirs,
-                    ...(declaredObjDir !== undefined ? { declaredObjDir } : {}),
-                };
-            }
-        }
-        const selectedObjDir = resolvedObjDirs[0];
-        if (!selectedObjDir) {
-            return { exists: false };
-        }
-        const mozinfoPath = join(engineDir, selectedObjDir, 'mozinfo.json');
-        if (await pathExists(mozinfoPath)) {
-            try {
-                const mozinfo = validateBuildMozinfo(await readJson(mozinfoPath));
-                const expectedSrcDir = resolve(engineDir);
-                const expectedObjDir = resolve(engineDir, selectedObjDir);
-                const actualSrcDir = mozinfo.topsrcdir ? resolve(mozinfo.topsrcdir) : undefined;
-                const actualObjDir = mozinfo.topobjdir ? resolve(mozinfo.topobjdir) : undefined;
-                if ((actualSrcDir !== undefined && actualSrcDir !== expectedSrcDir) ||
-                    (actualObjDir !== undefined && actualObjDir !== expectedObjDir)) {
-                    return {
-                        exists: true,
-                        objDir: selectedObjDir,
-                        metadataMismatch: {
-                            objDir: selectedObjDir,
-                            ...(mozinfo.topsrcdir ? { topsrcdir: mozinfo.topsrcdir } : {}),
-                            ...(mozinfo.topobjdir ? { topobjdir: mozinfo.topobjdir } : {}),
-                            ...(mozinfo.mozconfig ? { mozconfig: mozinfo.mozconfig } : {}),
-                        },
-                    };
-                }
-            }
-            catch (error) {
-                verbose(`Ignoring invalid mozinfo metadata in ${selectedObjDir}: ${toError(error).message}`);
-            }
-        }
-        return { exists: true, objDir: selectedObjDir };
-    }
-    catch {
-        return { exists: false };
-    }
-}
-/**
- * Checks whether the built browser's launchable binary exists under
- * `<engineDir>/<objDir>/dist/...`. `hasBuildArtifacts` only confirms that
- * an obj tree with a `dist/` subdir exists. A partial or in-progress build
- * can satisfy that check without ever writing the executable, which is the
- * failure mode that makes `fireforge run` throw `mach run` after having
- * reported the build as usable. Separating the probes lets `run` fail fast
- * with a precise message and `watch` stay permissive (it exists to drive
- * rebuilds of incomplete trees) while still reporting the bundle state in
- * its startup banner.
- *
- * Platform layout:
- * - macOS: `<objDir>/dist/*.app/Contents/MacOS/<binaryName>` (the `.app`
- *   display casing can differ from `binaryName`, e.g. `MyBrowser.app` for
- *   binary `mybrowser`, so we enumerate the `*.app` bundles rather than
- *   compute the name.
- * - Linux: `<objDir>/dist/bin/<binaryName>`.
- * - Windows: `<objDir>/dist/bin/<binaryName>.exe`.
- *
- * Returns `runnable: false` with no `expectedPath` when the `objDir`
- * itself cannot be scanned. Same degraded contract as `hasBuildArtifacts`.
- *
- * @param engineDir Path to the engine directory
- * @param binaryName Lowercase binary name from `fireforge.json`
- * @param objDir The single matching `obj-*` directory name (caller
- *   resolves it, typically from `hasBuildArtifacts().objDir`)
- * @returns Structured check result
- */
-export async function hasRunnableBundle(engineDir, binaryName, objDir) {
-    const platform = getPlatform();
-    const distDir = join(engineDir, objDir, 'dist');
-    if (!(await pathExists(distDir))) {
-        return { runnable: false };
-    }
-    if (platform === 'darwin') {
-        let entries;
-        try {
-            entries = await readdir(distDir, { withFileTypes: true });
-        }
-        catch {
-            // No readable dist directory means no runnable bundle, which is exactly
-            // what the caller needs to know.
-            return { runnable: false };
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            if (!entry.name.endsWith('.app'))
-                continue;
-            const candidate = join(distDir, entry.name, 'Contents', 'MacOS', binaryName);
-            if (await pathExists(candidate)) {
-                return { runnable: true, expectedPath: relative(engineDir, candidate) };
-            }
-        }
-        // Report an expected-but-missing path rooted at the first .app bundle we
-        // can see, or a synthetic path when no bundle exists yet, so the error
-        // message names something the operator can look for on disk.
-        const firstApp = entries.find((e) => e.isDirectory() && e.name.endsWith('.app'));
-        const expected = firstApp
-            ? relative(engineDir, join(distDir, firstApp.name, 'Contents', 'MacOS', binaryName))
-            : relative(engineDir, join(distDir, `<AppName>.app/Contents/MacOS/${binaryName}`));
-        return { runnable: false, expectedPath: expected };
-    }
-    const binaryFile = platform === 'win32' ? `${binaryName}.exe` : binaryName;
-    const candidate = join(distDir, 'bin', binaryFile);
-    const expectedPath = relative(engineDir, candidate);
-    if (await pathExists(candidate)) {
-        return { runnable: true, expectedPath };
-    }
-    return { runnable: false, expectedPath };
-}
-/** Builds a user-facing explanation when detected build artifacts belong to another workspace. */
-export function buildArtifactMismatchMessage(engineDir, buildCheck, commandName) {
-    if (!buildCheck.metadataMismatch || !buildCheck.objDir) {
-        return undefined;
-    }
-    const expectedObjDir = join(engineDir, buildCheck.objDir);
-    const details = [`Current engine: ${engineDir}`, `Detected objdir: ${expectedObjDir}`];
-    if (buildCheck.metadataMismatch.topsrcdir) {
-        details.push(`mozinfo topsrcdir: ${buildCheck.metadataMismatch.topsrcdir}`);
-    }
-    if (buildCheck.metadataMismatch.topobjdir) {
-        details.push(`mozinfo topobjdir: ${buildCheck.metadataMismatch.topobjdir}`);
-    }
-    if (buildCheck.metadataMismatch.mozconfig) {
-        details.push(`mozinfo mozconfig: ${buildCheck.metadataMismatch.mozconfig}`);
-    }
-    return (`${commandName} cannot use copied or relocated build artifacts whose metadata still points at a different Firefox workspace.\n\n` +
-        `${details.join('\n')}\n\n` +
-        'Delete the stale obj-* directory in this workspace and run "fireforge build" again so mach regenerates build metadata for the current checkout.\n' +
-        'If the workspace was simply moved (same tree, different prefix), "fireforge build --rewrite-mozinfo" will patch mozinfo.json paths in place and run mach configure instead of scrubbing the whole tree.');
-}
-/**
- * Safe-relocation rewriter for mozinfo.json under the active obj-* tree.
- *
- * Copied objdirs retain source symlinks, dependency metadata and tracking
- * inventories as well as mozinfo.json. Repair them before configure so
- * config.track cannot write nulls into the primary checkout. Configure then
- * regenerates the root config files; callers verify old-source links too.
- *
- * Safety rules. The rewrite is refused when any of them are violated:
- *   - `topsrcdir` and `topobjdir` must both be present and non-empty.
- *   - `topobjdir` must resolve to `<topsrcdir>/<objDir>`. A non-in-tree
- *     objdir means the previous workspace was configured differently,
- *     so a blind prefix-rewrite could point mach at the wrong tree.
- *   - The computed new `topobjdir` must be `<engineDir>/<objDir>`. If it
- *     is not, the objDir name itself changed and we cannot prove safety.
- *
- * When any rule trips, the caller should fall back to the clean-rebuild
- * instruction, which is always a correct (if expensive) recovery path.
- *
- * @param engineDir Absolute path to the current engine checkout.
- * @param objDir Name of the obj-* directory to rewrite against.
- * @returns Result object. Callers inspect `rewritten` and surface `reason`.
- */
-export async function attemptMozinfoRewrite(engineDir, objDir) {
-    const mozinfoPath = join(engineDir, objDir, 'mozinfo.json');
-    if (!(await pathExists(mozinfoPath))) {
-        return { rewritten: false, reason: 'mozinfo.json not found in obj directory' };
-    }
-    let raw;
-    try {
-        raw = await readJson(mozinfoPath);
-    }
-    catch (error) {
-        return { rewritten: false, reason: `mozinfo.json is unreadable: ${toError(error).message}` };
-    }
-    if (!isObject(raw)) {
-        return { rewritten: false, reason: 'mozinfo.json is not a JSON object' };
-    }
-    let mozinfo;
-    try {
-        mozinfo = validateBuildMozinfo(raw);
-    }
-    catch (error) {
-        return { rewritten: false, reason: toError(error).message };
-    }
-    const oldSrc = mozinfo.topsrcdir;
-    const oldObj = mozinfo.topobjdir;
-    if (!oldSrc || !oldObj) {
-        return {
-            rewritten: false,
-            reason: 'mozinfo.json is missing topsrcdir or topobjdir; cannot rewrite safely',
-        };
-    }
-    const oldSrcResolved = resolve(oldSrc);
-    const oldObjResolved = resolve(oldObj);
-    const insideTree = oldObjResolved === oldSrcResolved ||
-        oldObjResolved.startsWith(oldSrcResolved + sep) ||
-        oldObjResolved.startsWith(oldSrcResolved + '/');
-    if (!insideTree) {
-        return {
-            rewritten: false,
-            reason: `topobjdir (${oldObjResolved}) is not inside topsrcdir (${oldSrcResolved}) — rewrite would change workspace layout`,
-        };
-    }
-    const relativeObj = relative(oldSrcResolved, oldObjResolved).split(sep).join('/');
-    if (relativeObj !== objDir) {
-        return {
-            rewritten: false,
-            reason: `mozinfo objdir "${relativeObj}" does not match detected objdir "${objDir}" — rewrite would change the obj directory name`,
-        };
-    }
-    const newSrc = resolve(engineDir);
-    const newObj = resolve(engineDir, objDir);
-    const patched = { ...raw, topsrcdir: newSrc, topobjdir: newObj };
-    let newMozconfig;
-    if (mozinfo.mozconfig) {
-        const oldMozconfigResolved = resolve(mozinfo.mozconfig);
-        if (oldMozconfigResolved === oldSrcResolved ||
-            oldMozconfigResolved.startsWith(oldSrcResolved + sep) ||
-            oldMozconfigResolved.startsWith(oldSrcResolved + '/')) {
-            const rel = relative(oldSrcResolved, oldMozconfigResolved);
-            newMozconfig = resolve(newSrc, rel);
-            patched['mozconfig'] = newMozconfig;
-        }
-        // A mozconfig living outside the old topsrcdir is left as-is. It
-        // probably points at a shared configuration file the user kept in
-        // place across the relocation. A relocated checkout that also moved
-        // its mozconfig will still fail configure. The operator can re-point
-        // with `MOZCONFIG=…` or run a full clean rebuild.
-    }
-    try {
-        await relocateObjdirProducts(engineDir, objDir, oldSrcResolved);
-    }
-    catch (error) {
-        return { rewritten: false, reason: `objdir relocation refused: ${toError(error).message}` };
-    }
-    await writeJson(mozinfoPath, patched);
-    return {
-        rewritten: true,
-        newTopsrcdir: newSrc,
-        oldTopsrcdir: oldSrcResolved,
-        newTopobjdir: newObj,
-        ...(newMozconfig ? { newMozconfig } : {}),
-    };
-}
-/**
- * Shared build-artifact preflight: rejects ambiguous multi-objdir checkouts,
- * artifacts whose metadata points at another tree, and (when
- * `requireExisting`) missing or incomplete builds, each with the actionable
- * message for that case.
- *
- * Takes an already-probed {@link BuildArtifactCheck} rather than probing
- * itself, so it stays a pure validator: callers keep their own
- * `hasBuildArtifacts` call (which their suites already stub) and this
- * function needs no test double of its own.
- */
-export function assertBuildArtifacts(engineDir, buildCheck, options) {
-    if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
-        throw new AmbiguousBuildArtifactsError(buildCheck.objDirs, buildCheck.declaredObjDir);
-    }
-    const mismatchMessage = buildArtifactMismatchMessage(engineDir, buildCheck, options.label);
-    if (mismatchMessage) {
-        throw new GeneralError(mismatchMessage);
-    }
-    if (options.requireExisting && !buildCheck.exists) {
-        const detail = buildCheck.objDir
-            ? `Build artifacts incomplete in ${buildCheck.objDir}/`
-            : 'No build artifacts found (obj-*/ directory missing)';
-        throw new GeneralError(`${options.requirement} ${detail}\n\n${options.remediation}`);
-    }
-}
-/**
- * Post-`mach configure` relocation check for a cloned objdir: confirms
- * configure actually regenerated `<engineDir>/<objDir>` and that none of
- * the four configure-generated root files (`config.status`, `backend.mk`,
- * `Makefile`, `config/autoconf.mk`) still names `forbiddenDir` (the
- * primary engine a relocated clone must never consult). Exit code 0 alone
- * proves neither: a stray MOZCONFIG/MOZ_OBJDIR can steer configure at a
- * different objdir entirely. Nested Makefiles are products of the verified
- * `config.status` and are not scanned. `.deps` files are build products a
- * configure cannot regenerate and are explicitly out of scope, and any
- * primary-path strings they retain are read-only staleness corrected by
- * the first in-tree rebuild. Pure checker: returns a human-readable
- * violation, or `undefined` when clean. Callers own the error type and
- * remediation copy. Unreadable metadata is itself a violation (fail
- * closed).
- */
-export async function findObjdirRelocationViolation(args) {
-    const { engineDir, objDir, forbiddenDir } = args;
-    const objDirPath = join(engineDir, objDir);
-    if (!(await pathExists(join(objDirPath, 'config.status')))) {
-        return (`${objDir}/config.status was not written — mach configure may have targeted a ` +
-            'different objdir (check MOZCONFIG / MOZ_OBJDIR)');
-    }
-    let mozinfo;
-    try {
-        mozinfo = validateBuildMozinfo(await readJson(join(objDirPath, 'mozinfo.json')));
-    }
-    catch (error) {
-        return `${objDir}/mozinfo.json could not be read after configure: ${toError(error).message}`;
-    }
-    const expectedSrcDir = resolve(engineDir);
-    const expectedObjDir = resolve(objDirPath);
-    const actualSrcDir = mozinfo.topsrcdir ? resolve(mozinfo.topsrcdir) : undefined;
-    const actualObjDir = mozinfo.topobjdir ? resolve(mozinfo.topobjdir) : undefined;
-    if (actualSrcDir !== expectedSrcDir) {
-        return `${objDir}/mozinfo.json topsrcdir resolves to ${actualSrcDir ?? '(absent)'}, expected ${expectedSrcDir}`;
-    }
-    if (actualObjDir !== expectedObjDir) {
-        return `${objDir}/mozinfo.json topobjdir resolves to ${actualObjDir ?? '(absent)'}, expected ${expectedObjDir}`;
-    }
-    // The canonical no-primary-paths assertion (mirrored by the opt-in
-    // real-mach proof in scripts/run-full-firefox-integration.mjs): substring
-    // search on the resolved primary engine dir is collision-safe against the
-    // tree's own paths: `<primary>/.fireforge/trees/<name>/engine` never
-    // contains the substring `<primary>/engine`. Scans exactly the
-    // configure-generated root files. `config.status` is mandatory (checked
-    // above), the rest are optional-if-absent because not every configure
-    // backend writes them.
-    const forbidden = resolve(forbiddenDir);
-    for (const name of ['config.status', 'backend.mk', 'Makefile', 'config/autoconf.mk']) {
-        const filePath = join(objDirPath, ...name.split('/'));
-        if (name !== 'config.status' && !(await pathExists(filePath)))
-            continue;
-        let content;
-        try {
-            content = await readText(filePath);
-        }
-        catch (error) {
-            return `${objDir}/${name} could not be read after configure: ${toError(error).message}`;
-        }
-        if (content.includes(forbidden)) {
-            return `${objDir}/${name} still contains the primary engine path ${forbidden}`;
-        }
-    }
-    return await findStaleObjdirLink(engineDir, objDir, forbidden);
-}

package/dist/src/core/mach-error-hints.d.ts

@@ -1,24 +0,0 @@
-/**
- * Pattern-based translator for cryptic mozbuild / mach errors.
- *
- * Each entry maps a stderr regex to an actionable hint. The goal is narrow:
- * convert the handful of errors whose message is non-obvious into a one-line
- * "here's what to change", rather than parse every mach failure. New
- * entries should only be added when a concrete diagnosis of the cryptic
- * output has been established. Low-confidence hints would train operators
- * to ignore the translator.
- */
-/** A single translator entry. */
-export interface MachErrorHint {
-    /** Pattern to search within the captured mach stderr. */
-    pattern: RegExp;
-    /** Actionable, one-line hint to surface alongside the raw mach output. */
-    hint: string;
-}
-/**
- * Scans captured stderr for known mach errors and returns matching hints.
- * Pure function. Safe to call on any string and never throws.
- * @param stderr Captured mach stderr.
- * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
- */
-export declare function explainMachError(stderr: string): string[];

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

@@ -1,135 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Pattern-based translator for cryptic mozbuild / mach errors.
- *
- * Each entry maps a stderr regex to an actionable hint. The goal is narrow:
- * convert the handful of errors whose message is non-obvious into a one-line
- * "here's what to change", rather than parse every mach failure. New
- * entries should only be added when a concrete diagnosis of the cryptic
- * output has been established. Low-confidence hints would train operators
- * to ignore the translator.
- */
-/**
- * Registered hint patterns. Order-sensitive: the first match wins per
- * pattern, but multiple distinct patterns may fire for the same stderr.
- */
-const MACH_ERROR_HINTS = [
-    {
-        pattern: /mozbuild\.preprocessor\.Preprocessor\.Error[\s\S]*?no preprocessor directives found/,
-        hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +
-            'Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.',
-    },
-    {
-        // mozbuild raises `UnsortedError` while reading a moz.build whose
-        // StrictOrderingOnAppendList entries are out of order, so `mach
-        // configure` dies before anything compiles. The ordering rule is the
-        // part operators get wrong: mozbuild sorts by `.lower()`
-        // (`StrictOrderingOnAppendList.ensure_sorted`), so an uppercase letter
-        // does not sort ahead of a lowercase one, and an entry that looks
-        // correctly placed by byte order can be rejected. mozbuild's own
-        // message names both entries ("We expected X but got Y") and survives
-        // to the operator through `extractMachConfigureError`, so the hint
-        // supplies only the rule and the remedy.
-        pattern: /mozbuild\.util\.UnsortedError|\bUnsortedError\b/,
-        hint: 'A moz.build list is out of order — mozbuild rejects the file while reading it, so ' +
-            'configure dies before any compile. The entries are compared CASE-INSENSITIVELY ' +
-            '(mozbuild lowercases before comparing), so uppercase does not sort before lowercase: ' +
-            '"HominisEditorFilePaths.sys.mjs" belongs BEFORE "HominisEditorFiles.sys.mjs" ' +
-            '("filep" < "files"). The mozbuild error above names the file and both entries — move ' +
-            'the entry to the position it names. "fireforge lint --per-patch" checks this ' +
-            '(mozbuild-unsorted-list) before a build, which is the cheaper place to catch it.',
-    },
-    {
-        // `mach package` inside `packager.py` dereferences a `None` sink when
-        // the packaging input set cannot resolve an entry it expected, most
-        // commonly running `fireforge package` before a full `fireforge build`
-        // has finished, so `obj-*/dist/` is missing pieces the packager assumes
-        // exist. The broader "build failed" path has already surfaced the raw
-        // traceback above this hint.
-        pattern: /packager\.py[\s\S]*?AttributeError: 'NoneType' object has no attribute 'open'|AttributeError: 'NoneType' object has no attribute 'open'[\s\S]*?packager\.py/,
-        hint: '`mach package` tripped a `NoneType.open` inside `packager.py`. This is almost always a ' +
-            'symptom of the packager being handed an incomplete `obj-*/dist/` tree — e.g. running ' +
-            '"fireforge package" before a full "fireforge build" (not --ui) completed, or packaging ' +
-            'after a build that failed late. Re-run "fireforge build" to completion, confirm the app ' +
-            'bundle exists under `obj-*/dist/`, and rerun "fireforge package".',
-    },
-    {
-        // Upstream bindgen on some macOS libc++ SDK versions emits
-        // `pub type basic_string___self_view = root::std::__1::basic_string_view<_CharT>;`
-        // inside gecko-profiler's generated `bindings.rs`, but `_CharT` is not
-        // in scope where the alias lands, so the Rust compile fails with
-        // "cannot find type `_CharT`". The fix is external: a consumer's patch
-        // queue may ship a workaround patch that strips the offending alias line
-        // post-generation. This hint surfaces that pointer alongside the raw
-        // bindgen output.
-        pattern: /cannot find type `_CharT` in this scope[\s\S]*?gecko-profiler-|gecko-profiler-[\s\S]*?cannot find type `_CharT` in this scope/,
-        hint: 'The Rust compile failed on a bindgen-generated `basic_string___self_view` alias in ' +
-            'gecko-profiler/bindings.rs. This is an upstream bindgen output bug against some ' +
-            'macOS libc++ SDK versions and needs a post-generation patch to strip the alias. ' +
-            'The known-working workaround is the `990-infra-bindgen-basic-string-workaround.patch` ' +
-            "shipped by some downstream patch queues — import the equivalent into your fork's patches/, " +
-            'then re-run "fireforge import" + "fireforge build". If your fork does not carry such a patch, ' +
-            'apply the following post-process to the generated file before the Rust compile: ' +
-            '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, and mozboot's
-        // MINIMUM_RUST_VERSION for rustc/cargo), and a source hop can move them.
-        // The failure lands ~8s into `mach configure` (e.g. "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
-        // complete! / Be sure to run |mach build|..." summary on the way out.
-        // Those three lines are plain upstream mach output, printed after the
-        // non-zero exit code is established, and they read deceptively like a
-        // success banner. Nudge the operator that they are cosmetic
-        // post-failure output, not a mixed success/failure signal.
-        pattern: /Config object not found by mach\.[\s\S]*?Configure complete!/,
-        hint: 'Ignore the trailing "Config object not found by mach. / Configure complete!" block — ' +
-            "that is mach's post-failure configure summary printed after the build already failed, " +
-            'not a sign the build succeeded. The real failure is the error above this block.',
-    },
-];
-/**
- * Scans captured stderr for known mach errors and returns matching hints.
- * Pure function. Safe to call on any string and never throws.
- * @param stderr Captured mach stderr.
- * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
- */
-export function explainMachError(stderr) {
-    if (!stderr) {
-        return [];
-    }
-    const hits = [];
-    const seen = new Set();
-    for (const { pattern, hint } of MACH_ERROR_HINTS) {
-        if (pattern.test(stderr) && !seen.has(hint)) {
-            seen.add(hint);
-            hits.push(hint);
-        }
-    }
-    return hits;
-}