@hominis/fireforge 0.15.9 → 0.16.0

package/dist/src/commands/run.js

@@ -2,9 +2,9 @@
 import { createWriteStream } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectPaths } from '../core/config.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, run, runMachSmoke, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke, } from '../core/mach.js';
 import { compileAllowlistFromFile, compileAllowlistFromStrings, matchesAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
@@ -94,6 +94,27 @@ export async function runCommand(projectRoot, options = {}) {
         throw new GeneralError(`Run requires a completed build. ${detail}\n\n` +
             "Run 'fireforge build' first, then rerun 'fireforge run'.");
     }
+    // `hasBuildArtifacts` only checks for an `obj-*/dist/` directory; a
+    // build that configured but hasn't yet produced the launchable binary
+    // (common in a long real Firefox compile that the operator stopped
+    // and restarted) passes that check, and `mach run` then fails on the
+    // missing binary path. `hasRunnableBundle` narrows the probe to the
+    // actual executable so `fireforge run` refuses with a targeted
+    // message before handing control to mach. `fireforge watch` stays
+    // permissive and instead surfaces the same information as a banner
+    // suffix; watch is supposed to drive rebuilds of partially-built
+    // trees, so blocking there would defeat the feature.
+    if (buildCheck.objDir) {
+        const config = await loadConfig(projectRoot);
+        const bundleCheck = await hasRunnableBundle(paths.engine, config.binaryName, buildCheck.objDir);
+        if (!bundleCheck.runnable) {
+            const expected = bundleCheck.expectedPath ?? `dist/bin/${config.binaryName}`;
+            throw new GeneralError(`Run requires a completed build that produced the launchable bundle. ` +
+                `Build artifacts exist in ${buildCheck.objDir}/ but the expected binary at ${expected} is missing — ` +
+                `the build may have aborted or is still in progress.\n\n` +
+                "Run 'fireforge build' and wait for it to finish before retrying 'fireforge run'.");
+        }
+    }
     // Warn if Furnace components changed since the last apply
     await warnIfFurnaceStale(projectRoot);
     // Clean stale profile state to prevent silent startup failures

package/dist/src/commands/status.js

@@ -12,7 +12,7 @@ import { buildPatchQueueContext, collectNewFileCreatorsByPath } from '../core/pa
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readText } from '../utils/fs.js';
+import { FIREFORGE_TMP_PATH_PATTERN, pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, verbose, warn } from '../utils/logger.js';
 /**
  * Status code descriptions for git status.
@@ -164,6 +164,21 @@ async function expandDirectoryEntries(files, engineDir) {
     }
     return { entries: expanded, truncations };
 }
+/**
+ * Strips entries whose path matches the atomic-temp-file shape
+ * FireForge's own `writeText` produces (see
+ * {@link import('../utils/fs.js').FIREFORGE_TMP_PATH_PATTERN}). Those
+ * files only exist for the duration of a write + rename and should
+ * never appear in `status` output; filtering them here keeps every
+ * status mode (default, raw, unmanaged, ownership, json) symmetric so
+ * the operator never sees a `.mozconfig.fireforge-tmp-<pid>-<uuid>`
+ * entry mid-write. Files named for unrelated reasons (e.g. a user's
+ * `.bashrc.fireforge-tmp-backup` without the PID+UUID tail) do not
+ * match the pattern and pass through unfiltered.
+ */
+function filterFireForgeTempFiles(files) {
+    return files.filter((entry) => !FIREFORGE_TMP_PATH_PATTERN.test(entry.file));
+}
 /**
  * Classifies files into patch-backed, unmanaged, or branding buckets.
  */
@@ -277,7 +292,11 @@ export async function statusCommand(projectRoot, options = {}) {
         const ownershipExpansion = (await isGitRepository(paths.engine))
             ? await expandDirectoryEntries(await getStatusWithCodes(paths.engine), paths.engine)
             : { entries: [], truncations: [] };
-        const rawFilesOwnership = ownershipExpansion.entries;
+        // Filter atomic-write temp files (Finding #18) so a mid-flight
+        // `.fireforge-tmp-<pid>-<uuid>` artefact never shows up in any
+        // status mode. The pattern is tight enough to let legitimately
+        // similar names through.
+        const rawFilesOwnership = filterFireForgeTempFiles(ownershipExpansion.entries);
         renderTruncationBanner(ownershipExpansion.truncations);
         // Only walk the patch bodies when the directory actually exists.
         // Fresh projects with no patch queue yet pass through with an empty
@@ -313,7 +332,10 @@ export async function statusCommand(projectRoot, options = {}) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     const rawFiles = await getStatusWithCodes(paths.engine);
-    const { entries: files, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
+    const { entries: expanded, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
+    // Strip atomic-write temp files (Finding #18) before every mode
+    // branch so raw / unmanaged / default / json all agree.
+    const files = filterFireForgeTempFiles(expanded);
     renderTruncationBanner(truncations);
     if (files.length === 0) {
         info('No modified files');

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