@hominis/fireforge 0.15.2 → 0.15.4

package/dist/src/commands/wire.js

@@ -2,7 +2,9 @@
 import { join, relative } from 'node:path';
 import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wire.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
+import { DEFAULT_DOM_TARGET } from '../core/wire-dom-fragment.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -10,7 +12,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { isContainedRelativePath, isPathInsideRoot, toRootRelativePath } from '../utils/paths.js';
 const BROWSER_BASE_DIR = 'browser/base';
-function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
+function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPath, options) {
     info('[dry-run] Would wire subscript:');
     info(`  source: ${subscriptDir}/${name}.js`);
     info(`  browser-main.js: loadSubScript("chrome://browser/content/${name}.js")`);
@@ -22,12 +24,45 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
     }
     if (domFilePath) {
         const includePath = relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)).replace(/\\/g, '/');
-        info(`  browser.xhtml: #include ${includePath}`);
+        info(`  ${domTargetPath}: #include ${includePath}`);
     }
     const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
     info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
     outro('Dry run complete');
 }
+/**
+ * Resolves the chrome document the `#include` directive is inserted into.
+ *
+ * Preference order:
+ *   1. `--target <path>` CLI flag (explicit caller intent)
+ *   2. First entry of `furnace.json.tokenHostDocuments` (fork-configured
+ *      chrome doc list; already consumed by the missing-token-link
+ *      validator and the doctor check)
+ *   3. `browser/base/content/browser.xhtml` (upstream default)
+ *
+ * Step 2 is silent — a missing / invalid furnace.json falls through to the
+ * upstream default rather than surfacing a warning, because forks that don't
+ * use furnace shouldn't have to configure anything.
+ */
+async function resolveDomTargetPath(projectRoot, explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    if (await checkFurnaceConfigExists(projectRoot)) {
+        try {
+            const furnaceConfig = await loadFurnaceConfig(projectRoot);
+            const first = furnaceConfig.tokenHostDocuments?.[0];
+            if (first !== undefined && first.length > 0) {
+                return first;
+            }
+        }
+        catch {
+            // Fall through to default — a broken furnace.json should not block
+            // the wire command. The doctor surfaces that issue separately.
+        }
+    }
+    return DEFAULT_DOM_TARGET;
+}
 /**
  * Validates a subscript name supplied on the command line. Subscripts are
  * resolved into filenames under the subscript directory and registered in
@@ -90,6 +125,21 @@ export async function wireCommand(projectRoot, name, options = {}) {
         }
         domFilePath = toRootRelativePath(paths.engine, options.dom);
     }
+    // Resolve the chrome document the `#include` directive will land in.
+    // Only consulted when `--dom` is supplied — we still resolve it here so
+    // the dry-run plan can print the target accurately.
+    if (options.target !== undefined && !isContainedRelativePath(options.target)) {
+        throw new InvalidArgumentError(`Target chrome document must stay within engine/: ${options.target}`, 'target');
+    }
+    const domTargetPath = await resolveDomTargetPath(projectRoot, options.target);
+    if (domFilePath) {
+        const paths = getProjectPaths(projectRoot);
+        if (!options.dryRun && !(await pathExists(join(paths.engine, domTargetPath)))) {
+            throw new InvalidArgumentError(`Chrome document not found in engine: ${domTargetPath}\n` +
+                'Set "tokenHostDocuments" in furnace.json (first entry is used by wire) ' +
+                'or pass --target <path>.', 'target');
+        }
+    }
     // Verify the subscript file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);
@@ -100,13 +150,14 @@ export async function wireCommand(projectRoot, name, options = {}) {
         }
     }
     if (options.dryRun) {
-        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, options);
+        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);
         return;
     }
     const result = await wireSubscript(projectRoot, name, {
         ...(options.init !== undefined ? { init: options.init } : {}),
         ...(options.destroy !== undefined ? { destroy: options.destroy } : {}),
         ...(domFilePath !== undefined ? { domFilePath } : {}),
+        ...(domFilePath !== undefined && domTargetPath !== DEFAULT_DOM_TARGET ? { domTargetPath } : {}),
         ...(options.after !== undefined ? { after: options.after } : {}),
         ...(subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR ? { subscriptDir } : {}),
         dryRun: false,
@@ -140,10 +191,10 @@ export async function wireCommand(projectRoot, name, options = {}) {
     }
     if (domFilePath) {
         if (result.domInserted) {
-            success(`Inserted #include directive into browser.xhtml`);
+            success(`Inserted #include directive into ${domTargetPath}`);
         }
         else {
-            info(`#include directive already present in browser.xhtml (skipped)`);
+            info(`#include directive already present in ${domTargetPath} (skipped)`);
         }
     }
     if (result.jarMnResult.skipped) {
@@ -161,10 +212,12 @@ export function registerWire(program, { getProjectRoot, withErrorHandling }) {
         .description('Wire a chrome subscript into the browser')
         .option('--init <expression>', 'Init expression for browser-init.js onLoad()')
         .option('--destroy <expression>', 'Destroy expression for browser-init.js onUnload()')
-        .option('--dom <file>', 'XHTML fragment file to insert into browser.xhtml')
+        .option('--dom <file>', 'XHTML fragment file to insert into the chrome document')
         .option('--dry-run', 'Show what would be changed without writing')
         .option('--after <name>', 'Insert init block after the block for this name')
         .option('--subscript-dir <dir>', 'Subscript directory relative to engine/ (default: browser/base/content)')
+        .option('--target <path>', 'Chrome document to insert --dom into, relative to engine/ ' +
+        '(default: first entry of furnace.json tokenHostDocuments, else browser/base/content/browser.xhtml)')
         .action(withErrorHandling(async (name, options) => {
         await wireCommand(getProjectRoot(), name, pickDefined(options));
     }));

package/dist/src/core/browser-wire.d.ts

@@ -22,6 +22,14 @@ export interface WireOptions {
     destroy?: string | undefined;
     /** Path to `.inc.xhtml` file relative to engine root */
     domFilePath?: string | undefined;
+    /**
+     * Top-level chrome document the DOM fragment's `#include` directive is
+     * inserted into, relative to engine/. Defaults to
+     * `browser/base/content/browser.xhtml`. Forks that replace browser.xhtml
+     * with a custom chrome document (e.g. `mybrowser.xhtml`) pass the
+     * replacement path here.
+     */
+    domTargetPath?: string | undefined;
     /** Dry run — don't write any files */
     dryRun?: boolean | undefined;
     /** Insert init block after the block containing this name */

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

@@ -48,10 +48,10 @@ export async function wireSubscript(root, name, options = {}) {
     if (options.destroy) {
         destroyAdded = await addDestroyToBrowserInit(engineDir, options.destroy);
     }
-    // 4. Add #include directive to browser.xhtml (if provided)
+    // 4. Add #include directive to the top-level chrome document (if provided)
     let domInserted = false;
     if (options.domFilePath) {
-        domInserted = await addDomFragment(engineDir, toRootRelativePath(engineDir, options.domFilePath));
+        domInserted = await addDomFragment(engineDir, toRootRelativePath(engineDir, options.domFilePath), options.domTargetPath);
     }
     // 5. Register in jar.mn
     const jarMnResult = await registerBrowserContent(engineDir, `${name}.js`, undefined, jarMnSourcePath);

package/dist/src/core/build-audit.d.ts

@@ -0,0 +1,46 @@
+import type { BuildBaseline } from './build-baseline.js';
+/** Result of a single artifact lookup. */
+export interface AuditEntry {
+    /** Engine-relative source file path (POSIX separators). */
+    source: string;
+    /**
+     * Resolved artifact path inside the dist tree, or undefined when no
+     * candidate bundle location was found. An entry with an undefined path
+     * and status "missing" means the source was packageable but nothing
+     * that looked like its artifact showed up in the bundle.
+     */
+    artifact: string | undefined;
+    /**
+     * updated: an artifact exists and is at least as new as the source.
+     * stale:   artifact exists but is older than the source (probable packaging drop).
+     * missing: no artifact with a matching basename was found anywhere under dist/.
+     * skipped: the file extension / path does not imply packaging; not counted.
+     */
+    status: 'updated' | 'stale' | 'missing' | 'skipped';
+}
+/** Summary counts for the "Packaged:" end-of-build line. */
+export interface AuditSummary {
+    updated: number;
+    stale: number;
+    missing: number;
+    skipped: number;
+    entries: AuditEntry[];
+}
+/**
+ * Decides whether a source path should be packaged. Returns true for paths
+ * whose extension or directory fragment matches a known-packaged pattern.
+ * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
+ * @returns True when the path implies packaging.
+ */
+export declare function isPackageablePath(sourcePath: string): boolean;
+/**
+ * Runs the post-build audit. Emits per-file warnings for missing or
+ * stale artifacts and a summary info line at the end. Always returns
+ * the summary; never throws on audit failure (the audit itself must
+ * never fail a successful build).
+ * @param projectRoot Root of the project (reserved for future fork-specific rules).
+ * @param engineDir Path to the engine directory.
+ * @param baseline Optional previous-build baseline marker.
+ * @returns Summary of artifact status counts.
+ */
+export declare function auditBuildArtifacts(projectRoot: string, engineDir: string, baseline: BuildBaseline | undefined): Promise<AuditSummary>;

package/dist/src/core/build-audit.js

@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Post-build dist-tree audit.
+ *
+ * Purpose: catch the class of bug where a file under engine/ was edited
+ * but never registered in moz.build, jar.mn, or package-manifest.in, so
+ * the mach build reports success but the packaged bundle carries stale
+ * or missing content. A fork-specific pref file that was never registered
+ * for packaging is the motivating case.
+ *
+ * The audit is best-effort and warn-only:
+ *   - It enumerates engine files changed since the previous build baseline
+ *     (git-tracked diff + workdir modifications).
+ *   - For each file whose path pattern implies packaging, it resolves
+ *     the expected dist artifact under obj-star/dist/binary-name-star.
+ *   - A warning fires when the expected artifact is missing OR when its
+ *     mtime is older than the engine source (the build was reported
+ *     successful but that file's path never flowed through packaging).
+ *   - False positives are acceptable at this stage: fork-specific packaging
+ *     tricks FireForge doesn't know about will surface as warnings an
+ *     operator can investigate. The audit never fails the build.
+ */
+import { stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { info, verbose, warn } from '../utils/logger.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/** Path extensions that are conventionally packaged into the Firefox bundle. */
+const PACKAGEABLE_EXTENSIONS = [
+    '.js',
+    '.mjs',
+    '.jsm',
+    '.css',
+    '.ftl',
+    '.xhtml',
+    '.xul',
+    '.html',
+    '.properties',
+];
+/** Path fragments whose contents are packaged regardless of extension. */
+const PACKAGEABLE_PATH_FRAGMENTS = ['/app/profile/', '/chrome/', '/locales/'];
+/** Directories that are build artifacts, not source — never audited. */
+const IGNORE_PATH_FRAGMENTS = ['obj-', 'node_modules/', '.git/', '.cargo/', '.mozbuild/'];
+/*
+ * Finds the first file with the given basename anywhere under the dist
+ * bundle. Scans the darwin Contents/Resources layout and the linux/win
+ * top-level layout with a depth-limited traversal so deeply-nested
+ * node_modules in the dist copy do not dominate the audit wall clock.
+ */
+async function findArtifactByBasename(distRoot, name, maxDepth = 10) {
+    const { readdir } = await import('node:fs/promises');
+    const stack = [{ dir: distRoot, depth: 0 }];
+    while (stack.length > 0) {
+        const entry = stack.pop();
+        if (!entry)
+            break;
+        if (entry.depth > maxDepth)
+            continue;
+        let children;
+        try {
+            children = await readdir(entry.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const child of children) {
+            const fullPath = join(entry.dir, child.name);
+            if (child.isDirectory()) {
+                // Skip the symlinked mozbuild cache tree which contains full copies
+                // and would dominate the scan on macOS.
+                if (child.name.startsWith('.'))
+                    continue;
+                stack.push({ dir: fullPath, depth: entry.depth + 1 });
+                continue;
+            }
+            if (child.name === name) {
+                return fullPath;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Decides whether a source path should be packaged. Returns true for paths
+ * whose extension or directory fragment matches a known-packaged pattern.
+ * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
+ * @returns True when the path implies packaging.
+ */
+export function isPackageablePath(sourcePath) {
+    for (const fragment of IGNORE_PATH_FRAGMENTS) {
+        if (sourcePath.includes(fragment))
+            return false;
+    }
+    for (const ext of PACKAGEABLE_EXTENSIONS) {
+        if (sourcePath.endsWith(ext))
+            return true;
+    }
+    for (const fragment of PACKAGEABLE_PATH_FRAGMENTS) {
+        if (sourcePath.includes(fragment))
+            return true;
+    }
+    return false;
+}
+/**
+ * Collects engine-relative paths changed since the baseline's HEAD SHA.
+ * Always includes modified + untracked workdir paths. When the baseline is
+ * missing or the engine has no HEAD yet, falls back to workdir-only diffs.
+ */
+async function collectChangedFiles(engineDir, baseline) {
+    const collected = new Set();
+    if (baseline?.engineHeadSha) {
+        try {
+            const output = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of output.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`Audit: could not diff against baseline SHA — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            const untracked = await getUntrackedFiles(engineDir);
+            for (const file of untracked) {
+                collected.add(file);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`Audit: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected].sort();
+}
+/*
+ * Finds the unique obj-star directory with a dist subtree, or undefined
+ * when zero or multiple match. The ambiguous case is already rejected
+ * by pre-flight in build.ts, so the auditor only has to handle
+ * one-or-none.
+ */
+async function resolveDistRoot(engineDir) {
+    const { readdir } = await import('node:fs/promises');
+    let entries;
+    try {
+        entries = await readdir(engineDir);
+    }
+    catch {
+        return undefined;
+    }
+    const objDirs = entries.filter((e) => e.startsWith('obj-'));
+    for (const objDir of objDirs) {
+        const distPath = join(engineDir, objDir, 'dist');
+        if (await pathExists(distPath)) {
+            return distPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Runs the post-build audit. Emits per-file warnings for missing or
+ * stale artifacts and a summary info line at the end. Always returns
+ * the summary; never throws on audit failure (the audit itself must
+ * never fail a successful build).
+ * @param projectRoot Root of the project (reserved for future fork-specific rules).
+ * @param engineDir Path to the engine directory.
+ * @param baseline Optional previous-build baseline marker.
+ * @returns Summary of artifact status counts.
+ */
+export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
+    void projectRoot;
+    const summary = {
+        updated: 0,
+        stale: 0,
+        missing: 0,
+        skipped: 0,
+        entries: [],
+    };
+    const distRoot = await resolveDistRoot(engineDir);
+    if (!distRoot) {
+        verbose('Audit skipped: no dist tree found under obj-*/dist/.');
+        return summary;
+    }
+    const changed = await collectChangedFiles(engineDir, baseline);
+    if (changed.length === 0) {
+        return summary;
+    }
+    for (const source of changed) {
+        if (!isPackageablePath(source)) {
+            summary.skipped += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
+            continue;
+        }
+        const sourcePath = join(engineDir, source);
+        let sourceMtime;
+        try {
+            const sourceStat = await stat(sourcePath);
+            sourceMtime = sourceStat.mtimeMs;
+        }
+        catch {
+            // File was deleted since the diff was computed. Skip — a deletion
+            // that didn't propagate to the dist tree is a distinct class of bug
+            // we don't audit yet.
+            summary.skipped += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
+            continue;
+        }
+        const artifact = await findArtifactByBasename(distRoot, basename(source));
+        if (!artifact) {
+            summary.missing += 1;
+            summary.entries.push({ source, artifact: undefined, status: 'missing' });
+            warn(`Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${distRoot}. Missing moz.build / jar.mn / package-manifest.in registration?`);
+            continue;
+        }
+        let artifactMtime;
+        try {
+            const artifactStat = await stat(artifact);
+            artifactMtime = artifactStat.mtimeMs;
+        }
+        catch {
+            // Disappeared after the directory scan; treat as missing.
+            summary.missing += 1;
+            summary.entries.push({ source, artifact, status: 'missing' });
+            warn(`Audit: engine/${source} has no readable packaged artifact at ${artifact} (disappeared during audit).`);
+            continue;
+        }
+        if (artifactMtime + 1 < sourceMtime) {
+            summary.stale += 1;
+            summary.entries.push({ source, artifact, status: 'stale' });
+            warn(`Audit: engine/${source} is newer than its packaged artifact ${artifact}. Build reported success but the file's path may not flow through packaging — check moz.build / jar.mn entries.`);
+            continue;
+        }
+        summary.updated += 1;
+        summary.entries.push({ source, artifact, status: 'updated' });
+    }
+    info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
+    return summary;
+}
+//# sourceMappingURL=build-audit.js.map

package/dist/src/core/build-baseline.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persists a marker describing the state of the engine tree at the time of
+ * the last successful `fireforge build`. Two downstream consumers share this
+ * marker:
+ *
+ *   - `build-audit`: after a build succeeds, compare engine files touched
+ *     since the baseline against the dist bundle to flag silent
+ *     packaging drops (e.g. a pref file never registered in moz.build).
+ *   - `build-prepare`: before a build starts, detect whether any
+ *     `moz.build` / `moz.configure` / `Makefile.in` changed since the
+ *     baseline and run `mach configure` before the build step so the
+ *     recursive-make backend isn't stale.
+ *
+ * The marker lives under `.fireforge/last-build.json`. It is written only
+ * on successful build completion; a failed build does not update it, so a
+ * subsequent run still audits against the last known-good tree.
+ */
+/** Shape of the on-disk baseline marker. */
+export interface BuildBaseline {
+    /** SHA of engine HEAD at the time the build succeeded. */
+    engineHeadSha: string;
+    /**
+     * ISO-8601 timestamp of when the baseline was recorded. Informational —
+     * downstream code keys off `engineHeadSha` for diffs, but the timestamp
+     * helps operators reason about stale markers.
+     */
+    builtAt: string;
+    /**
+     * The binaryName used at build time. Captured so the dist-tree audit
+     * can resolve the expected bundle root under obj-star/dist/ even when
+     * the project has since been renamed.
+     */
+    binaryName: string;
+}
+/** Name of the last-build marker file under `.fireforge/`. */
+export declare const BUILD_BASELINE_FILENAME = "last-build.json";
+/**
+ * Resolves the on-disk path of the build baseline marker.
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path of the marker file
+ */
+export declare function getBuildBaselinePath(projectRoot: string): string;
+/**
+ * Reads the last-build baseline if present. Returns undefined when no
+ * previous successful build has been recorded — callers must tolerate that
+ * path (first build, cleaned workspace).
+ * @param projectRoot - Root directory of the project
+ */
+export declare function readBuildBaseline(projectRoot: string): Promise<BuildBaseline | undefined>;
+/**
+ * Records a successful build by writing a fresh baseline marker. Captures
+ * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
+ * the current binaryName. Caller is responsible for only invoking this
+ * after the build exit code was zero.
+ * @param projectRoot - Root directory of the project
+ * @param engineDir - Path to the engine directory
+ * @param binaryName - Current `binaryName` from fireforge.json
+ */
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string): Promise<void>;

package/dist/src/core/build-baseline.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Persists a marker describing the state of the engine tree at the time of
+ * the last successful `fireforge build`. Two downstream consumers share this
+ * marker:
+ *
+ *   - `build-audit`: after a build succeeds, compare engine files touched
+ *     since the baseline against the dist bundle to flag silent
+ *     packaging drops (e.g. a pref file never registered in moz.build).
+ *   - `build-prepare`: before a build starts, detect whether any
+ *     `moz.build` / `moz.configure` / `Makefile.in` changed since the
+ *     baseline and run `mach configure` before the build step so the
+ *     recursive-make backend isn't stale.
+ *
+ * The marker lives under `.fireforge/last-build.json`. It is written only
+ * on successful build completion; a failed build does not update it, so a
+ * subsequent run still audits against the last known-good tree.
+ */
+import { join } from 'node:path';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+import { getHead, isMissingHeadError } from './git.js';
+/** Name of the last-build marker file under `.fireforge/`. */
+export const BUILD_BASELINE_FILENAME = 'last-build.json';
+/**
+ * Resolves the on-disk path of the build baseline marker.
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path of the marker file
+ */
+export function getBuildBaselinePath(projectRoot) {
+    return join(projectRoot, FIREFORGE_DIR, BUILD_BASELINE_FILENAME);
+}
+/**
+ * Reads the last-build baseline if present. Returns undefined when no
+ * previous successful build has been recorded — callers must tolerate that
+ * path (first build, cleaned workspace).
+ * @param projectRoot - Root directory of the project
+ */
+export async function readBuildBaseline(projectRoot) {
+    const path = getBuildBaselinePath(projectRoot);
+    if (!(await pathExists(path))) {
+        return undefined;
+    }
+    try {
+        return await readJson(path);
+    }
+    catch {
+        // A corrupt marker is equivalent to no marker — the audit/auto-configure
+        // will treat it as "first build" rather than block on the inconsistency.
+        return undefined;
+    }
+}
+/**
+ * Records a successful build by writing a fresh baseline marker. Captures
+ * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
+ * the current binaryName. Caller is responsible for only invoking this
+ * after the build exit code was zero.
+ * @param projectRoot - Root directory of the project
+ * @param engineDir - Path to the engine directory
+ * @param binaryName - Current `binaryName` from fireforge.json
+ */
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
+    let engineHeadSha = '';
+    try {
+        engineHeadSha = await getHead(engineDir);
+    }
+    catch (error) {
+        // Engine may be an unborn branch (freshly cloned + reset, or mid-import)
+        // — record an empty SHA and let downstream fall back to "no prior state"
+        // behavior. Any other git failure is bubbled up; we don't want to
+        // silently write a garbage marker.
+        if (!isMissingHeadError(error)) {
+            throw error;
+        }
+    }
+    const baseline = {
+        engineHeadSha,
+        builtAt: new Date().toISOString(),
+        binaryName,
+    };
+    await writeJson(getBuildBaselinePath(projectRoot), baseline);
+}
+//# sourceMappingURL=build-baseline.js.map

package/dist/src/core/build-prepare.d.ts

@@ -3,13 +3,32 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
+import type { BuildBaseline } from './build-baseline.js';
 /**
  * Result of the build preparation phase.
  */
 export interface BuildPreparation {
     /** Number of Furnace components applied (0 if none or no furnace.json) */
     furnaceApplied: number;
+    /** True when `mach configure` was auto-run to refresh a stale backend. */
+    reconfigured: boolean;
 }
+/** Options for {@link prepareBuildEnvironment}. */
+export interface PrepareBuildOptions {
+    /**
+     * Previous successful-build baseline, used to detect `moz.build` /
+     * `moz.configure` / `Makefile.in` changes that require a fresh
+     * `mach configure` before the build. When undefined, the auto-configure
+     * step is skipped — there's no reference point for what "changed since"
+     * means.
+     */
+    previousBaseline?: BuildBaseline | undefined;
+}
+/**
+ * Returns true when the file path matches a pattern that forces
+ * `mach configure` to regenerate the backend. Exported for testing.
+ */
+export declare function isBackendInvalidatingFile(path: string): boolean;
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Cleans Furnace stories from engine (prevents leaking into production)
@@ -22,4 +41,4 @@ export interface BuildPreparation {
  * @param config - Loaded FireForge configuration
  * @returns Preparation results
  */
-export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig): Promise<BuildPreparation>;
+export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, options?: PrepareBuildOptions): Promise<BuildPreparation>;