@hominis/fireforge 0.15.8 → 0.16.0

package/dist/src/commands/test.js

@@ -11,28 +11,7 @@ import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
-/**
- * Strips a leading "engine/" or "engine\\" prefix from a path if present.
- * Users may specify paths like "engine/browser/modules/..." from the project
- * root, but mach test expects paths relative to the engine directory.
- *
- * The match is case-insensitive because case-insensitive filesystems
- * (default macOS, Windows) treat "Engine/" and "engine/" as the same
- * directory, and a literal lowercase-only check left mach with a
- * non-stripped prefix that resolved to a different path under the engine
- * tree. Tab and other whitespace before the prefix is also ignored.
- *
- * @param testPath - Path as provided by the user
- * @returns Path relative to the engine directory
- */
-function normalizeTestPath(testPath) {
-    const trimmed = testPath.trim();
-    const match = /^engine[/\\]/i.exec(trimmed);
-    if (match) {
-        return trimmed.slice(match[0].length);
-    }
-    return trimmed;
-}
+import { stripEnginePrefix } from '../utils/paths.js';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
     for (const testPath of testPaths) {
@@ -198,8 +177,11 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             throw new GeneralError('Marionette preflight reported FAIL — see output above. Aborting before mach test runs.');
         }
     }
-    // Normalize test paths (strip engine/ prefix if present)
-    const normalizedPaths = testPaths.map(normalizeTestPath);
+    // Normalize test paths (strip engine/ prefix if present). Uses the
+    // shared `stripEnginePrefix` helper so `test`, `register`, `lint`, and
+    // `export` all accept the same prefix forms. Also trim to match the
+    // previous case-insensitive + leading-whitespace-tolerant contract.
+    const normalizedPaths = testPaths.map((p) => stripEnginePrefix(p).trim());
     await assertTestPathsExist(paths.engine, normalizedPaths);
     // Build extra args
     const extraArgs = [];

package/dist/src/commands/token.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Option } from 'commander';
 import { loadConfig } from '../core/config.js';
-import { loadFurnaceConfig } from '../core/furnace-config.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
 import { addToken, getTokensCssPath, validateTokenAdd, } from '../core/token-manager.js';
 import { InvalidArgumentError } from '../errors/base.js';
+import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
@@ -36,6 +37,18 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
  */
 export async function tokenAddCommand(projectRoot, tokenName, value, options) {
     intro('Token Add');
+    // Finding #15: a fresh project without furnace.json failed deep inside
+    // the token-manager's `assertTokenCategoryExists` with "Token CSS file
+    // not found: browser/themes/shared/<binary>-tokens.css" — technically
+    // correct, but the operator's actual next step is to initialize
+    // Furnace (which scaffolds the tokens CSS file among other things).
+    // Catching the uninitialized case here gives the right guidance up-
+    // front before the generic "file not found" error fires.
+    if (!(await furnaceConfigExists(projectRoot))) {
+        throw new FurnaceError('Token management requires Furnace to be initialized. ' +
+            'Tokens live in the Furnace-managed tokens CSS file, which `fireforge furnace init` scaffolds alongside the rest of the Furnace workspace.\n\n' +
+            'Run "fireforge furnace init" first, then rerun "fireforge token add ...".');
+    }
     // Normalize token name using the configured Furnace token prefix when the
     // user supplied a bare token name like "canvas-gap".
     tokenName = await normalizeTokenNameForProject(projectRoot, tokenName);

package/dist/src/commands/watch.js

@@ -1,6 +1,6 @@
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, watchWithOutput, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -114,7 +114,19 @@ export async function watchCommand(projectRoot) {
         throw new GeneralError(`Watch mode requires a completed build. ${detail}\n\n` +
             "Run 'fireforge build' first to create the initial build, then run 'fireforge watch'.");
     }
-    info(`Using build artifacts from ${buildCheck.objDir}/`);
+    // Report bundle state alongside the "Using build artifacts..." banner
+    // so an operator watching a mid-build tree can see why `fireforge run`
+    // would refuse right now while watch is still going. Watch remains
+    // permissive (it exists to drive rebuilds) — this is informational.
+    // The `hasBuildArtifacts` check already passed at this point, so
+    // `objDir` is always defined.
+    const bundleCheck = buildCheck.objDir
+        ? await hasRunnableBundle(paths.engine, config.binaryName, buildCheck.objDir)
+        : { runnable: false };
+    const bundleSuffix = bundleCheck.runnable
+        ? ' (bundle: runnable)'
+        : ' (bundle: pending — watch will rebuild)';
+    info(`Using build artifacts from ${buildCheck.objDir}/${bundleSuffix}`);
     // Advisory: warn when Furnace components have drifted since the last
     // apply so the user doesn't launch watch-mode builds with stale
     // components baked in. Mirrors the check in `fireforge run` — without

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

@@ -6,6 +6,29 @@ export declare class BrandingError extends FireForgeError {
     readonly code: 6;
     get userMessage(): string;
 }
+/**
+ * Error thrown when the generated `mozconfig` references a `--with-branding`
+ * directory that does not match the branding tree FireForge set up. The
+ * mismatch is a silent-corruption hazard — `mach configure` picks the value
+ * from mozconfig but the scaffolded branding lives elsewhere, so the build
+ * fails deep inside moz.build resolution with a confusing "path does not
+ * exist" message. Surface it as an actionable preflight instead.
+ *
+ * The root cause is that setup renders templates under `configs/` with
+ * `${binaryName}` baked in at setup time; a subsequent edit to
+ * `fireforge.json`'s `binaryName` (or a re-setup without re-templating)
+ * leaves those baked-in names stale while `setupBranding` continues to use
+ * the current `config.binaryName`. Both directions (mozconfig ahead of
+ * config, config ahead of mozconfig) produce the same class of build break.
+ */
+export declare class BrandingMozconfigMismatchError extends FireForgeError {
+    readonly expectedBrandingDir: string;
+    readonly mozconfigBrandingDir: string;
+    readonly reason: 'mozconfig-missing-branding' | 'name-mismatch' | 'branding-dir-missing';
+    readonly code: 6;
+    constructor(expectedBrandingDir: string, mozconfigBrandingDir: string, reason: 'mozconfig-missing-branding' | 'name-mismatch' | 'branding-dir-missing');
+    get userMessage(): string;
+}
 /**
  * Full branding configuration.
  */

package/dist/src/core/branding.js

@@ -13,6 +13,45 @@ export class BrandingError extends FireForgeError {
         return `Branding Error: ${this.message}\n\nBranding is required to set MOZ_APP_VENDOR, MOZ_MACBUNDLE_ID, and other Firefox identity values.`;
     }
 }
+/**
+ * Error thrown when the generated `mozconfig` references a `--with-branding`
+ * directory that does not match the branding tree FireForge set up. The
+ * mismatch is a silent-corruption hazard — `mach configure` picks the value
+ * from mozconfig but the scaffolded branding lives elsewhere, so the build
+ * fails deep inside moz.build resolution with a confusing "path does not
+ * exist" message. Surface it as an actionable preflight instead.
+ *
+ * The root cause is that setup renders templates under `configs/` with
+ * `${binaryName}` baked in at setup time; a subsequent edit to
+ * `fireforge.json`'s `binaryName` (or a re-setup without re-templating)
+ * leaves those baked-in names stale while `setupBranding` continues to use
+ * the current `config.binaryName`. Both directions (mozconfig ahead of
+ * config, config ahead of mozconfig) produce the same class of build break.
+ */
+export class BrandingMozconfigMismatchError extends FireForgeError {
+    expectedBrandingDir;
+    mozconfigBrandingDir;
+    reason;
+    code = ExitCode.PATCH_ERROR;
+    constructor(expectedBrandingDir, mozconfigBrandingDir, reason) {
+        super(`Generated mozconfig references "${mozconfigBrandingDir}" but the active branding directory is "${expectedBrandingDir}".`);
+        this.expectedBrandingDir = expectedBrandingDir;
+        this.mozconfigBrandingDir = mozconfigBrandingDir;
+        this.reason = reason;
+    }
+    get userMessage() {
+        const diagnosis = this.reason === 'mozconfig-missing-branding'
+            ? `The generated mozconfig does not contain a --with-branding directive (found "${this.mozconfigBrandingDir}"). FireForge expected to write one for binaryName "${this.expectedBrandingDir}".`
+            : this.reason === 'name-mismatch'
+                ? `The generated mozconfig sets --with-branding="${this.mozconfigBrandingDir}" but FireForge set up branding under "${this.expectedBrandingDir}".`
+                : `The generated mozconfig sets --with-branding="${this.mozconfigBrandingDir}" but no moz.build exists under engine/${this.mozconfigBrandingDir}/.`;
+        return (`Branding Error: ${diagnosis}\n\n` +
+            'This usually means the rendered configs/ templates drifted from fireforge.json. Fix one of:\n' +
+            '  1. Edit configs/common.mozconfig so --with-branding uses ${binaryName} (or the current binaryName), then re-run "fireforge build".\n' +
+            '  2. Update fireforge.json so binaryName matches the --with-branding value baked into configs/.\n\n' +
+            'The mismatch is caught before mach builds because resolving the build against the wrong branding tree fails deep in moz.build with a confusing "path does not exist" message.');
+    }
+}
 /**
  * Sets up the custom branding directory for the browser.
  *

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

@@ -1,8 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, relative } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
 import { toRootRelativePath } from '../utils/paths.js';
 import { getProjectPaths } from './config.js';
+import { createRollbackJournal, restoreRollbackJournal, snapshotFile } from './furnace-rollback.js';
 import { registerBrowserContent } from './manifest-register.js';
+import { DEFAULT_DOM_TARGET } from './wire-dom-fragment.js';
 import { addDestroyToBrowserInit, addDomFragment, addInitToBrowserInit, addSubscriptToBrowserMain, } from './wire-targets.js';
 export const DEFAULT_BROWSER_SUBSCRIPT_DIR = 'browser/base/content';
 const BROWSER_BASE_DIR = 'browser/base';
@@ -36,31 +40,72 @@ export async function wireSubscript(root, name, options = {}) {
             },
         };
     }
-    // 1. Add subscript to browser-main.js
-    const subscriptAdded = await addSubscriptToBrowserMain(engineDir, name);
-    // 2. Add init expression to browser-init.js (if provided)
-    let initAdded = false;
-    if (options.init) {
-        initAdded = await addInitToBrowserInit(engineDir, options.init, options.after);
+    // Snapshot every file the five mutation steps might touch so a mid-sequence
+    // failure (most commonly the chrome-document insertion not finding an
+    // anchor) does not leave a half-wired browser behind. Before the rollback
+    // journal landed here, a failed `wire` would still have written new
+    // `loadSubScript` calls into browser-main.js, new init/destroy expressions
+    // into browser-init.js, and a new entry into browser/base/jar.mn — the
+    // operator then had to grep the engine tree for the partial mutation and
+    // hand-revert, or re-download. The snapshots cover the targets on every
+    // code path (init/destroy/DOM are conditional, so we snapshot only when
+    // the corresponding option would fire a write) plus the two files every
+    // wire touches.
+    const journal = createRollbackJournal();
+    const effectiveDomTargetPath = options.domFilePath
+        ? toRootRelativePath(engineDir, options.domTargetPath ?? DEFAULT_DOM_TARGET)
+        : undefined;
+    await snapshotFile(journal, join(engineDir, 'browser/base/content/browser-main.js'));
+    if (options.init !== undefined || options.destroy !== undefined) {
+        await snapshotFile(journal, join(engineDir, 'browser/base/content/browser-init.js'));
     }
-    // 3. Add destroy expression to browser-init.js onUnload() (if provided)
-    let destroyAdded = false;
-    if (options.destroy) {
-        destroyAdded = await addDestroyToBrowserInit(engineDir, options.destroy);
+    if (effectiveDomTargetPath) {
+        await snapshotFile(journal, join(engineDir, effectiveDomTargetPath));
     }
-    // 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), options.domTargetPath);
+    await snapshotFile(journal, join(engineDir, 'browser/base/jar.mn'));
+    try {
+        // 1. Add subscript to browser-main.js
+        const subscriptAdded = await addSubscriptToBrowserMain(engineDir, name);
+        // 2. Add init expression to browser-init.js (if provided)
+        let initAdded = false;
+        if (options.init) {
+            initAdded = await addInitToBrowserInit(engineDir, options.init, options.after);
+        }
+        // 3. Add destroy expression to browser-init.js onUnload() (if provided)
+        let destroyAdded = false;
+        if (options.destroy) {
+            destroyAdded = await addDestroyToBrowserInit(engineDir, options.destroy);
+        }
+        // 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), options.domTargetPath);
+        }
+        // 5. Register in jar.mn
+        const jarMnResult = await registerBrowserContent(engineDir, `${name}.js`, undefined, jarMnSourcePath);
+        return {
+            subscriptAdded,
+            initAdded,
+            destroyAdded,
+            domInserted,
+            jarMnResult,
+        };
+    }
+    catch (error) {
+        // Best-effort rollback: if the restore itself fails, surface both the
+        // original wire failure and the rollback failure so the operator knows
+        // the engine may be in a partially-wired state that needs manual
+        // attention. The original error's message is preserved so the user sees
+        // *why* the wire failed (e.g. "Could not find insertion point in chrome
+        // document") alongside any rollback diagnosis.
+        const originalMessage = toError(error).message;
+        try {
+            await restoreRollbackJournal(journal);
+        }
+        catch (rollbackError) {
+            throw new GeneralError(`Wire failed: ${originalMessage}. Automatic rollback also failed: ${toError(rollbackError).message}. The engine may contain partially-applied wire mutations; review "git status" under engine/ and revert manually.`);
+        }
+        throw error;
     }
-    // 5. Register in jar.mn
-    const jarMnResult = await registerBrowserContent(engineDir, `${name}.js`, undefined, jarMnSourcePath);
-    return {
-        subscriptAdded,
-        initAdded,
-        destroyAdded,
-        domInserted,
-        jarMnResult,
-    };
 }
 //# sourceMappingURL=browser-wire.js.map

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,21 @@ 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".',
+    },
 ];
 /**
  * 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