@hominis/fireforge 0.15.9 → 0.16.1

package/dist/src/core/firefox.d.ts

@@ -23,12 +23,26 @@ export declare function getDownloadUrl(version: string, product?: FirefoxProduct
  * @returns Tarball filename
  */
 export declare function getTarballFilename(version: string, product?: FirefoxProduct): string;
+/**
+ * Lifecycle phase reported by {@link downloadFirefoxSource}. The download
+ * CLI command uses this to swap spinners between the bytes-on-the-wire
+ * phase and the silent tar-xz decompression phase that follows — before
+ * this, a single spinner stuck at "Downloading Firefox … 100%" covered
+ * both phases, making the first-run setup look hung precisely when the
+ * archive was already on disk and `tar` was the long pole.
+ */
+export type FirefoxSourcePhase = 'download' | 'extract';
+/** Callback fired at phase transitions during {@link downloadFirefoxSource}. */
+export type FirefoxSourcePhaseCallback = (phase: FirefoxSourcePhase) => void;
 /**
  * Downloads and extracts Firefox source.
  * @param version - Firefox version to download
  * @param product - Firefox product type
  * @param destDir - Destination directory for extracted source
  * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback
+ * @param onProgress - Optional progress callback for the download byte stream
+ * @param onPhase - Optional callback fired when the function transitions
+ *   between phases (`'download'` → `'extract'`). Fires exactly once per
+ *   phase even if the cached archive path skips the wire entirely.
  */
-export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback): Promise<void>;
+export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback): Promise<void>;

package/dist/src/core/firefox.js

@@ -39,16 +39,21 @@ export function getTarballFilename(version, product = 'firefox') {
  * @param product - Firefox product type
  * @param destDir - Destination directory for extracted source
  * @param cacheDir - Directory to store downloaded tarball
- * @param onProgress - Optional progress callback
+ * @param onProgress - Optional progress callback for the download byte stream
+ * @param onPhase - Optional callback fired when the function transitions
+ *   between phases (`'download'` → `'extract'`). Fires exactly once per
+ *   phase even if the cached archive path skips the wire entirely.
  */
-export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress) {
+export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase) {
     const archive = resolveArchive(version, product);
     const tarballPath = join(cacheDir, archive.filename);
     // Ensure cache directory exists
     await ensureDir(cacheDir);
+    onPhase?.('download');
     await ensureCachedArchive(archive, cacheDir, onProgress);
     // Extract to a unique temporary directory so concurrent downloads for
     // the same destination do not clobber each other.
+    onPhase?.('extract');
     const tempDir = `${destDir}.tmp-${randomUUID()}`;
     try {
         await extractTarXz(tarballPath, tempDir);

package/dist/src/core/furnace-config.d.ts

@@ -86,6 +86,29 @@ export declare function loadFurnaceConfig(root: string): Promise<FurnaceConfig>;
  * @param config - Configuration to write
  */
 export declare function writeFurnaceConfig(root: string, config: FurnaceConfig): Promise<void>;
+/**
+ * Stamps every override's `baseVersion` to the supplied version. Used by
+ * `fireforge rebase` after a successful patch re-export so a successful
+ * ESR bump does not leave Furnace overrides in a doctor-failing drift
+ * state. Returns the number of overrides stamped (zero if furnace.json
+ * has no overrides, or if the file is missing).
+ *
+ * Motivating case: a 140.9.0esr → 140.9.1esr rebase stamps patch
+ * `sourceEsrVersion` via `stampPatchVersions`, but before 0.16.0 no
+ * equivalent stamping ran for Furnace override `baseVersion`. `doctor`
+ * then immediately failed Furnace component validation on every
+ * override. The stamp is deliberately unconditional — `fireforge
+ * furnace validate` is the right tool for "does this override still
+ * apply", and rebase already attested that the patch layer re-validated
+ * against the new ESR; the per-override health check belongs in a
+ * separate pass, not inline with the stamp.
+ *
+ * @param root - Root directory of the project
+ * @param version - Firefox version string to stamp onto every override
+ * @returns Number of overrides whose `baseVersion` was updated (either
+ *   because it was missing or because it differed from `version`).
+ */
+export declare function stampFurnaceOverrideBaseVersions(root: string, version: string): Promise<number>;
 /**
  * Creates a default furnace configuration.
  * @returns A valid empty FurnaceConfig

package/dist/src/core/furnace-config.js

@@ -420,6 +420,44 @@ export async function writeFurnaceConfig(root, config) {
     const paths = getFurnacePaths(root);
     await writeJson(paths.furnaceConfig, config);
 }
+/**
+ * Stamps every override's `baseVersion` to the supplied version. Used by
+ * `fireforge rebase` after a successful patch re-export so a successful
+ * ESR bump does not leave Furnace overrides in a doctor-failing drift
+ * state. Returns the number of overrides stamped (zero if furnace.json
+ * has no overrides, or if the file is missing).
+ *
+ * Motivating case: a 140.9.0esr → 140.9.1esr rebase stamps patch
+ * `sourceEsrVersion` via `stampPatchVersions`, but before 0.16.0 no
+ * equivalent stamping ran for Furnace override `baseVersion`. `doctor`
+ * then immediately failed Furnace component validation on every
+ * override. The stamp is deliberately unconditional — `fireforge
+ * furnace validate` is the right tool for "does this override still
+ * apply", and rebase already attested that the patch layer re-validated
+ * against the new ESR; the per-override health check belongs in a
+ * separate pass, not inline with the stamp.
+ *
+ * @param root - Root directory of the project
+ * @param version - Firefox version string to stamp onto every override
+ * @returns Number of overrides whose `baseVersion` was updated (either
+ *   because it was missing or because it differed from `version`).
+ */
+export async function stampFurnaceOverrideBaseVersions(root, version) {
+    if (!(await furnaceConfigExists(root)))
+        return 0;
+    const config = await loadFurnaceConfig(root);
+    let changed = 0;
+    for (const override of Object.values(config.overrides)) {
+        if (override.baseVersion !== version) {
+            override.baseVersion = version;
+            changed++;
+        }
+    }
+    if (changed > 0) {
+        await writeFurnaceConfig(root, config);
+    }
+    return changed;
+}
 /**
  * Creates a default furnace configuration.
  * @returns A valid empty FurnaceConfig

package/dist/src/core/mach-build-artifacts.d.ts

@@ -25,6 +25,47 @@ export interface BuildArtifactCheck {
  * @returns Build artifact check result
  */
 export declare function hasBuildArtifacts(engineDir: string): Promise<BuildArtifactCheck>;
+/**
+ * Outcome of the `hasRunnableBundle` probe. Distinguishes "no objdir at
+ * all" from "objdir exists but the launchable binary is not yet written"
+ * so callers (notably `fireforge run`) can give the operator a specific
+ * message instead of the generic build-artifacts-missing line.
+ */
+export interface RunnableBundleCheck {
+    /** True when an objdir is present AND the expected binary was found under it. */
+    runnable: boolean;
+    /** Repo-relative (engine-rooted) path we probed; populated even on failure for error copy. */
+    expectedPath?: string;
+}
+/**
+ * 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. `Hominis.app` for
+ *   binary `hominis`, 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 declare function hasRunnableBundle(engineDir: string, binaryName: string, objDir: string): Promise<RunnableBundleCheck>;
 /** Builds a user-facing explanation when detected build artifacts belong to another workspace. */
 export declare function buildArtifactMismatchMessage(engineDir: string, buildCheck: BuildArtifactCheck, commandName: string): string | undefined;
 /**

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

@@ -4,6 +4,7 @@ import { join, relative, resolve, sep } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { getPlatform } from '../utils/platform.js';
 import { isObject, isString } from '../utils/validation.js';
 function validateBuildMozinfo(data) {
     if (!isObject(data)) {
@@ -94,6 +95,75 @@ export async function hasBuildArtifacts(engineDir) {
         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. `Hominis.app` for
+ *   binary `hominis`, 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 {
+            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) {

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

@@ -19,6 +19,44 @@ export const MACH_ERROR_HINTS = [
         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.',
     },
+    {
+        // `mach package` inside `packager.py` dereferences a `None` sink when
+        // the packaging input set cannot resolve an entry it expected — the
+        // most common real-world cause is running `fireforge package` before
+        // a full `fireforge build` has finished, so `obj-*/dist/` is missing
+        // pieces the packager assumes exist. The hint points at that root
+        // cause specifically; 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 symptom is obscure and the
+        // fix is external: Hominis ships
+        // `990-infra-bindgen-basic-string-workaround.patch` in its patch
+        // queue, which strips the offending alias line post-generation.
+        // This hint surfaces the workaround pointer alongside the raw
+        // bindgen output so operators don't have to reverse-engineer the
+        // failure.
+        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` ' +
+            "Hominis ships in its patch queue — import the equivalent into your fork's patches/, " +
+            'then re-run "fireforge import" + "fireforge build". If you do not use Hominis\' queue, ' +
+            '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`.',
+    },
 ];
 /**
  * Scans captured stderr for known mach errors and returns matching hints.

package/dist/src/core/mach-mozconfig.d.ts

@@ -8,6 +8,31 @@ export interface MozconfigVariables {
     appId: string;
     binaryName: string;
 }
+/**
+ * Extracts the `--with-branding=<path>` value from a rendered mozconfig
+ * body. Returns `undefined` when no directive is present — callers treat
+ * that as "mozconfig is missing branding", which is itself an actionable
+ * configuration error.
+ *
+ * Exported for testing.
+ */
+export declare function extractWithBrandingPath(mozconfigContent: string): string | undefined;
+/**
+ * Preflights the just-written mozconfig against the branding tree FireForge
+ * set up. A drift between the two is silent-corruption territory — the
+ * build runs, `mach configure` reads the stale directory name out of
+ * mozconfig, and then the recursive make backend errors out with a "path
+ * does not exist" message that names the branding dir the mozconfig
+ * referenced. By parsing the mozconfig here and comparing to
+ * `config.binaryName`, we turn that into a single-line actionable error
+ * before `mach` runs.
+ *
+ * @param engineDir Path to the engine directory (the branding tree lives here)
+ * @param mozconfigPath Path to the mozconfig just written
+ * @param config FireForge configuration (reads `binaryName`)
+ * @throws BrandingMozconfigMismatchError on drift or missing directive
+ */
+export declare function assertBrandingMozconfigAgreement(engineDir: string, mozconfigPath: string, config: FireForgeConfig): Promise<void>;
 /**
  * Generates a mozconfig file from templates.
  * @param configsDir - Path to the configs directory

package/dist/src/core/mach-mozconfig.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { MozconfigError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { getPlatform } from '../utils/platform.js';
+import { BrandingMozconfigMismatchError } from './branding.js';
 /**
  * Replaces template variables in a string.
  * @param content - Content with ${variable} placeholders
@@ -16,6 +17,66 @@ function replaceVariables(content, variables) {
         .replace(/\$\{appId\}/g, variables.appId)
         .replace(/\$\{binaryName\}/g, variables.binaryName);
 }
+/**
+ * Matches an `--with-branding=<path>` directive anywhere in a rendered
+ * mozconfig. The directive form is the one mach reads; an optional
+ * `ac_add_options` prefix is the on-disk convention. `m` flag anchors the
+ * search per-line so a multi-line mozconfig with older directives earlier
+ * in the file doesn't confuse the extractor. We pick the LAST match
+ * because mach itself takes the last-write-wins semantics of shell
+ * configuration for overlapping `ac_add_options` calls.
+ */
+const WITH_BRANDING_PATTERN = /^\s*(?:ac_add_options\s+)?--with-branding\s*=\s*(\S+)/gm;
+/**
+ * Extracts the `--with-branding=<path>` value from a rendered mozconfig
+ * body. Returns `undefined` when no directive is present — callers treat
+ * that as "mozconfig is missing branding", which is itself an actionable
+ * configuration error.
+ *
+ * Exported for testing.
+ */
+export function extractWithBrandingPath(mozconfigContent) {
+    const matches = [...mozconfigContent.matchAll(WITH_BRANDING_PATTERN)];
+    const last = matches.at(-1);
+    return last?.[1];
+}
+/**
+ * Preflights the just-written mozconfig against the branding tree FireForge
+ * set up. A drift between the two is silent-corruption territory — the
+ * build runs, `mach configure` reads the stale directory name out of
+ * mozconfig, and then the recursive make backend errors out with a "path
+ * does not exist" message that names the branding dir the mozconfig
+ * referenced. By parsing the mozconfig here and comparing to
+ * `config.binaryName`, we turn that into a single-line actionable error
+ * before `mach` runs.
+ *
+ * @param engineDir Path to the engine directory (the branding tree lives here)
+ * @param mozconfigPath Path to the mozconfig just written
+ * @param config FireForge configuration (reads `binaryName`)
+ * @throws BrandingMozconfigMismatchError on drift or missing directive
+ */
+export async function assertBrandingMozconfigAgreement(engineDir, mozconfigPath, config) {
+    const mozconfigContent = await readText(mozconfigPath);
+    const found = extractWithBrandingPath(mozconfigContent);
+    const expected = `browser/branding/${config.binaryName}`;
+    if (!found) {
+        throw new BrandingMozconfigMismatchError(expected, '(no --with-branding directive)', 'mozconfig-missing-branding');
+    }
+    // Normalise both sides to forward slashes before compare — Windows-edited
+    // configs can carry backslash path separators that the build would treat
+    // as literal characters in a repo-relative path.
+    const normalizedFound = found.replace(/\\/g, '/');
+    if (normalizedFound !== expected) {
+        throw new BrandingMozconfigMismatchError(expected, found, 'name-mismatch');
+    }
+    // Last line of defence: even with matching names, a missing branding tree
+    // means the scaffold step hasn't run. Preflight here so the operator
+    // doesn't pay for a configure-through-build cycle to discover it.
+    const brandingMozBuild = join(engineDir, expected, 'moz.build');
+    if (!(await pathExists(brandingMozBuild))) {
+        throw new BrandingMozconfigMismatchError(expected, found, 'branding-dir-missing');
+    }
+}
 /**
  * Generates a mozconfig file from templates.
  * @param configsDir - Path to the configs directory
@@ -46,5 +107,10 @@ export async function generateMozconfig(configsDir, engineDir, config) {
     const platformContent = await readText(platformPath);
     content += `# Platform configuration (${platform})\n${replaceVariables(platformContent, variables)}`;
     await writeText(outputPath, content);
+    // Preflight: the mozconfig we just wrote must reference the branding
+    // directory FireForge actually set up. Catching the drift here (after the
+    // write, before anything consumes mozconfig) keeps `generateMozconfig`
+    // the single source of truth for both the render and the sanity-check.
+    await assertBrandingMozconfigAgreement(engineDir, outputPath, config);
 }
 //# sourceMappingURL=mach-mozconfig.js.map

package/dist/src/core/mach.d.ts

@@ -1,5 +1,5 @@
 import { type SmokeLineCallback, type SmokeRunResult } from '../utils/process.js';
-export { attemptMozinfoRewrite, type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, type MozinfoRewriteResult, } from './mach-build-artifacts.js';
+export { attemptMozinfoRewrite, type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, type MozinfoRewriteResult, type RunnableBundleCheck, } from './mach-build-artifacts.js';
 export { generateMozconfig, type MozconfigVariables } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**
@@ -111,6 +111,17 @@ export declare function runMachSmoke(args: string[], engineDir: string, options:
  * @returns Exit code
  */
 export declare function machPackage(engineDir: string): Promise<number>;
+/**
+ * Creates a distribution package while streaming output to the terminal
+ * and capturing the stderr tail for post-run diagnostics. Callers that
+ * want to consult {@link explainMachError} on failure should use this
+ * variant; the inherit-only `machPackage` above remains for callers that
+ * just need an exit code.
+ *
+ * @param engineDir - Path to the engine directory
+ * @returns Captured mach result (stdout tail, stderr tail, exit code)
+ */
+export declare function machPackageCapture(engineDir: string): Promise<MachCommandResult>;
 /**
  * Runs mach watch for auto-rebuilding.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -7,7 +7,7 @@ import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
-export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
+export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**
@@ -197,6 +197,19 @@ export async function runMachSmoke(args, engineDir, options) {
 export async function machPackage(engineDir) {
     return runMach(['package'], engineDir, { inherit: true });
 }
+/**
+ * Creates a distribution package while streaming output to the terminal
+ * and capturing the stderr tail for post-run diagnostics. Callers that
+ * want to consult {@link explainMachError} on failure should use this
+ * variant; the inherit-only `machPackage` above remains for callers that
+ * just need an exit code.
+ *
+ * @param engineDir - Path to the engine directory
+ * @returns Captured mach result (stdout tail, stderr tail, exit code)
+ */
+export async function machPackageCapture(engineDir) {
+    return runMachCapture(['package'], engineDir);
+}
 /**
  * Runs mach watch for auto-rebuilding.
  * @param engineDir - Path to the engine directory

package/dist/src/core/manifest-rules.js

@@ -16,7 +16,15 @@ export function getRules(binaryName) {
             extractArgs: (m) => [m[1] ?? ''],
         },
         {
-            pattern: /^browser\/base\/content\/(.+\.(?:js|mjs|xhtml|css))$/,
+            // `.inc.xhtml` fragments under browser/base/content/ are deliberately
+            // excluded: they are consumed via `#include` from a registered chrome
+            // document (typically browser.xhtml) and do not get their own
+            // packaged chrome URI. Before this carve-out, `status` flagged every
+            // wired fragment as "potentially unregistered" and `register --dry-run`
+            // proposed a bogus jar.mn entry. The lookahead blocks the match so
+            // `getUnregistrableAdvice` gets a chance to emit the correct
+            // guidance for the `.inc.xhtml` case.
+            pattern: /^browser\/base\/content\/(?!.+\.inc\.xhtml$)(.+\.(?:js|mjs|xhtml|css))$/,
             isRegistered: (engineDir, fileName) => isBrowserContentRegistered(engineDir, fileName),
             register: (engineDir, after, dryRun, fileName) => registerBrowserContent(engineDir, fileName, after, undefined, dryRun),
             extractArgs: (m) => [m[1] ?? ''],
@@ -98,6 +106,19 @@ function getUnregistrableAdvice(filePath) {
     if (filePath.endsWith('.ftl')) {
         return "FTL locale files are auto-discovered via jar.mn glob patterns and don't need manual registration.";
     }
+    // `.inc.xhtml` fragments live under browser/base/content/ but are
+    // consumed via `#include` from a registered chrome document (browser.xhtml
+    // by default; a fork's custom top-level doc when `wire --dom-target` is
+    // set). The preprocessor resolves the include at packaging time, so the
+    // fragment never needs its own chrome URI entry in jar.mn. Give the
+    // operator the actionable `wire` path instead of letting the generic
+    // "unknown file pattern" message above fire.
+    if (/^browser\/base\/content\/.+\.inc\.xhtml$/.test(filePath)) {
+        return ('`.inc.xhtml` fragments are consumed via `#include` from a registered chrome document ' +
+            '(e.g. browser.xhtml). They do not need an independent jar.mn entry — run ' +
+            '"fireforge wire <name> --dom <path>" to insert the #include, or add the directive manually ' +
+            'in the top-level chrome document.');
+    }
     const testMatch = filePath.match(/^browser\/base\/content\/test\/([^/]+)\/(?!browser\.toml$).+$/);
     if (testMatch) {
         const dir = testMatch[1];

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

@@ -159,6 +159,17 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
         // Check for non-tokenized custom properties. A variable that is both
         // declared and consumed inside the same file is auto-exempted as a
         // runtime state channel (see furnace.json → runtimeVariables).
+        //
+        // When diff context is available, scope the `var(...)` scan to
+        // added/modified lines only. `cssContent` (full-file) is still the
+        // source of `localDeclarations` so vars declared anywhere in the file
+        // are recognised as same-file refs regardless of where the consuming
+        // `var(...)` appears. Before this scoping change, a small edit to a
+        // Furnace override of a stock component (e.g. moz-card) produced a
+        // `token-prefix-violation` for every stock `var(--moz-card-*)` the
+        // upstream file already carried, because the scanner saw the full
+        // applied file and flagged each inherited reference as if the fork
+        // had introduced it.
         if (tokenPrefix) {
             const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
             const localDeclarations = new Set();
@@ -168,26 +179,38 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
                 if (name)
                     localDeclarations.add(name);
             }
-            const varPattern = /var\(\s*(--[\w-]+)/g;
-            let match;
-            while ((match = varPattern.exec(cssContent)) !== null) {
-                const prop = match[1];
-                if (!prop)
-                    continue;
-                if (prop.startsWith(tokenPrefix))
-                    continue;
-                if (tokenAllowlist?.has(prop))
-                    continue;
-                if (runtimeVariables?.has(prop))
-                    continue;
-                if (localDeclarations.has(prop))
-                    continue;
-                issues.push({
-                    file,
-                    check: 'token-prefix-violation',
-                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
-                    severity: 'error',
-                });
+            const prefixScanSource = addedLinesByFile
+                ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
+                : cssContent;
+            if (prefixScanSource.length > 0) {
+                const varPattern = /var\(\s*(--[\w-]+)/g;
+                const flaggedProps = new Set();
+                let match;
+                while ((match = varPattern.exec(prefixScanSource)) !== null) {
+                    const prop = match[1];
+                    if (!prop)
+                        continue;
+                    if (prop.startsWith(tokenPrefix))
+                        continue;
+                    if (tokenAllowlist?.has(prop))
+                        continue;
+                    if (runtimeVariables?.has(prop))
+                        continue;
+                    if (localDeclarations.has(prop))
+                        continue;
+                    // De-duplicate per (file, prop) pair so the same introduced var
+                    // used five times in the added hunk doesn't produce five
+                    // identical issue entries.
+                    if (flaggedProps.has(prop))
+                        continue;
+                    flaggedProps.add(prop);
+                    issues.push({
+                        file,
+                        check: 'token-prefix-violation',
+                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
+                        severity: 'error',
+                    });
+                }
             }
         }
     }