@hominis/fireforge 0.15.9 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 0.16.0
+
+### Wire — transactional rollback
+
+- `fireforge wire` now snapshots every file the mutation sequence may touch (`browser/base/content/browser-main.js`, conditionally `browser/base/content/browser-init.js`, the chrome document the `#include` lands in, and `browser/base/jar.mn`) before any write, and restores them when any step fails. The evaluator hit the motivating case on `hominis/`: a `wire mock-wire --init … --destroy … --dom …` run threw `Could not find insertion point in chrome document` AFTER `browser-main.js`, `browser-init.js`, and `browser/base/jar.mn` had already been mutated — the operator had to hand-revert the partial mutation. The journal plumbing reuses `createRollbackJournal` / `snapshotFile` / `restoreRollbackJournal` from Furnace's rollback module; a rollback that itself fails surfaces both the original wire failure and the rollback diagnosis in a single `GeneralError` with `review "git status" under engine/` guidance so the operator knows the engine may need manual attention.
+- The snapshot set is conditional on which option set the run actually uses — no unused snapshot cost on a `wire` invocation that doesn't pass `--init`/`--destroy` or `--dom`. Real-fs integration tests in `browser-wire-rollback.integration.test.ts` pin both the failure-rollback contract and the successful-run pass-through so a future refactor can't regress either branch silently.
+
+### Branding/mozconfig preflight
+
+- New `assertBrandingMozconfigAgreement` fires at the end of `generateMozconfig` and refuses to hand off to `mach` when the just-written `engine/mozconfig` sets `--with-branding=browser/branding/<X>` while FireForge's branding tree lives at `browser/branding/<Y>`. The new `BrandingMozconfigMismatchError` enumerates three reasons — `mozconfig-missing-branding`, `name-mismatch`, `branding-dir-missing` — each with an actionable recovery line: edit `configs/common.mozconfig` to use `${binaryName}`, or align `fireforge.json`'s `binaryName` with the baked-in value. Motivating case: the evaluator's real `fresh/` tree produced a branding scaffold at `browser/branding/freshforge/` while the rendered mozconfig still pointed `mach` at `browser/branding/freshtest/moz.build`, and every first build failed deep inside moz.build resolution with a confusing "path does not exist" message. The preflight turns that into a single-line refusal before `mach` runs.
+- The extractor (`extractWithBrandingPath`) matches `/^\s*(?:ac_add_options\s+)?--with-branding\s*=\s*(\S+)/m` so both the bare form and the `ac_add_options`-prefixed on-disk convention are recognised, picks the last match (matches `mach`'s last-write-wins semantics for overlapping `ac_add_options` calls), and normalises backslash separators before comparing.
+- The preflight only fires on values that would actually fail under `mach`; it does not prescribe a single shape for `configs/*.mozconfig`. A follow-up (tracked for 0.17.0) will flip `setup-support.ts` to keep templates unsubstituted and substitute at `generateMozconfig` time, removing the drift vector entirely. The 0.16.0 fix is preflight-only because existing projects already have post-substitution configs; reshaping those requires a migration we intend to ship with 0.17.
+
+### Export-all — duplicate new-file-creation guard
+
+- `fireforge export-all` now refuses before writing when the aggregate diff would newly-create (`new file mode`) a path some other patch in the queue already creates. Motivating case on `fresh/lab/`: exporting patch 1 with `browser/modules/labforge/Hello.sys.mjs` as a new file, then running `export-all --name bye-module --category infra` without scoping the change set, produced a second patch that also claimed the same path — `verify` then failed on `files-affected-mismatch`, a cross-patch `filesAffected` conflict, AND a `duplicate-new-file-creation` error all at once, and the fix required either `patch delete` or hand-edited `re-export --files`. The new guard slots in right after the existing branding and furnace refusals at `src/commands/export-all.ts:checkDuplicateNewFileCreations`; it lists every conflicting path and every existing owner, and points the operator at `fireforge export <path>` with explicit file scoping as the clean recovery.
+- The guard reuses `detectNewFilesInDiff` + `collectNewFileCreatorsByPath` (already used by `verify` and `status --ownership`), so the pre-export check and the post-hoc detection report exactly the same conflict set. No change to `export` itself — single-path exports stay the surgical primitive for this case.
+
+### Path normalization parity (`lint` / `export`)
+
+- `fireforge lint <paths...>` and `fireforge export <paths...>` now accept both repo-root-relative forms (`engine/browser/base/content/foo.js`) and engine-relative forms (`browser/base/content/foo.js`), matching the normalization already implemented by `register` and `test`. Motivating cases on both `fresh/` and `fresh/lab/`: pasting `engine/browser/base/content/fresh-extra-a.js` into `fireforge export` produced `File "engine/..." has no changes to export.` and the same input to `fireforge lint` produced `No modified files found in the specified paths.` — both because the status lookup sees paths relative to `engine/` and the explicit prefix double-rooted the candidate. Re-running with the engine-relative form succeeded. The normalization is now shared: `stripEnginePrefix` in `src/utils/paths.ts` is the single source of truth, and `register`/`test` delegate to it so every command that takes an engine-relative path treats `Engine/`, `engine\\`, and leading whitespace identically.
+
+### Furnace override — stock auto-promotion
+
+- `fireforge furnace override <name>` no longer rejects the component when `name` is already present in `config.stock`. Motivating case on `hominis/`: every stock-discovered widget (populated by `furnace scan`) forced the operator to hand-edit `furnace.json` before the override could be created, with the error `"<name>" is already registered as a stock component. Remove it from config.stock before creating an override.` That's busywork — the whole point of `override` is to fork a stock component. The new contract splices the name out of `config.stock` in-memory and lets the existing mutation-phase `writeFurnaceConfig` persist the promotion atomically alongside the new override entry, under the same rollback journal. The collision check for `config.overrides[name]` and `config.custom[name]` stays — those are real conflicts. Promotion emits a one-line `Promoting "<name>" from stock to override.` so the operator sees that the stock entry is gone.
+- The batch variant `furnaceBatchOverrideCommand` applies the same promotion per-name; a batch that overrides both `moz-button` and `moz-card` demotes both from `stock` in the same `writeFurnaceConfig` write.
+
+### Furnace diff — FTL deployment path parity
+
+- `fireforge furnace diff <name>` now resolves `.ftl` entries through the configured `ftlDir` instead of the component's `targetPath`, matching the path `furnace apply`'s `applyCustomFtlFile` writes to. Before the fix, a custom component with a `.ftl` always reported "`<name>.ftl`: not yet deployed to engine (new file)" after a clean apply, because `diff` probed `engine/<customConfig.targetPath>/<name>.ftl` while the deployed file was at `engine/<ftlDir>/<name>.ftl`. The diff header also now names the locale path (`--- engine/<ftlDir>/<name>.ftl`) so the rendered diff anchors at the same target on both sides. Motivating case on `hominis/`: `furnace diff moz-lab-pill` after a successful apply/deploy reported the `.ftl` as new even though `engine/toolkit/locales/en-US/toolkit/global/moz-lab-pill.ftl` was present on disk and `furnace status moz-lab-pill` reported clean — `diff`, `status`, and `validate` now agree on deployed state.
+
+### Furnace rename — path-label fix
+
+- `fireforge furnace rename <old> <new>` for a custom component now reports `components/custom/<new>/` instead of `components/customs/<new>/` in the guidance that follows a successful rename (and in the "directory not found" / "target directory already exists" error messages). The actual filesystem operations always used `furnacePaths.customDir` / `furnacePaths.overridesDir` correctly — this was a cosmetic mis-pluralisation produced by appending `s` to the `custom` / `override` furnace-state key — but operators who copied the path from the message to a `cd` or `ls` invocation hit "no such file or directory". Override renames continue to name `components/overrides/<new>/` (which was already correct by coincidence with the plural on-disk dir). A `componentDirLabel` helper centralises the singular/plural pick so a future refactor cannot re-introduce the drift.
+
+### Furnace preview — build + toolchain preflight
+
+- `fireforge furnace preview` now refuses before staging components or running the multi-minute `mach storybook upgrade` npm install when either (a) no `obj-*/dist/` tree exists, or (b) `.cargo/config.toml` is absent under the engine directory. Motivating case on `fresh/`: on an otherwise-unbuilt engine, preview staged workspace components into `engine/`, npm-installed 1023 packages into the upstream Storybook workspace, and only then failed deep in `mach storybook` with errors about `.cargo/config.toml` and `chrome-map.json` — both artefacts `fireforge build` / `fireforge bootstrap` would have produced. The new preflight catches the dominant failure mode (no `dist/`) fast via the existing `hasBuildArtifacts` helper and points the operator at `fireforge build`; the secondary check fires on a bootstrap-incomplete tree and points at `fireforge bootstrap`. Extracted into `assertPreviewPrerequisites` so `furnacePreviewCommand` stays under the per-function LOC budget as the preflight list grows.
+
+### Register — `.inc.xhtml` fragments routed through `getUnregistrableAdvice`
+
+- The browser-content registration pattern in `src/core/manifest-rules.ts` now excludes `.inc.xhtml` fragments under `browser/base/content/`. Motivating case on `fresh/`: wiring a `browser/base/content/fresh-fragment.inc.xhtml` into `browser.xhtml` with `fireforge wire ... --dom …` then running `fireforge status` flagged the fragment as `Potentially unregistered`, and `fireforge register <fragment>.inc.xhtml --dry-run` proposed a bogus `browser/base/jar.mn` entry. `.inc.xhtml` files are deliberately consumed via `#include` from a registered chrome document; they don't need a separate chrome URI entry. The narrowed regex now routes these paths through `getUnregistrableAdvice`, which emits specific guidance: "`.inc.xhtml` fragments are consumed via `#include` from a registered chrome document — run `fireforge wire <name> --dom <path>`, or add the `#include` directive manually in the top-level chrome document." Plain `.xhtml` files under `browser/base/content/` still match the registrable pattern.
+
+### Stackless precondition errors
+
+- `getProjectRoot` now throws a typed `ConfigNotFoundError` (exit code `CONFIG_ERROR` / 2) instead of a plain `Error` when no `fireforge.json` exists in any ancestor of the current working directory. Motivating case on `fresh/` before setup: every precondition-checking command (`doctor`, `status`, `download`, `import`, `build`, `run`, `test`, `lint`, `verify`) printed `Unexpected error: Could not find fireforge.json...` followed by a full JS stack trace — a routine user mistake surfaced as what looked like an internal crash. `withErrorHandling` now routes the `FireForgeError` subclass through `logError(error.userMessage)` and exits with the CONFIG_ERROR code; the stack-dump fallback stays in place for genuinely unexpected errors. The user-facing message is the already-defined `ConfigNotFoundError` copy — `This directory does not appear to be a FireForge project. Navigate to your project root directory, or run "fireforge setup" to initialize a new project.`
+
+### Packager NoneType hint
+
+- `fireforge package` now captures `mach package`'s streamed output (via the new `machPackageCapture` helper that layers over `runMachCapture`) and feeds the stderr tail through `explainMachError` on non-zero exit. A new hint pattern matches the `AttributeError: 'NoneType' object has no attribute 'open'` / `packager.py` co-occurrence (either ordering) and surfaces an actionable guidance line: "This usually means the packager was handed an incomplete `obj-*/dist/` tree — e.g. running `fireforge package` before a full `fireforge build` (not --ui) completed. Re-run `fireforge build` to completion … before rerunning `fireforge package`." Motivating case on a real `hominis/` tree that reached `mach package` but had not completed a full build: the raw mach traceback was surfaced but wrapped only in "Packaging failed with exit code 1"; operators had to read the Python traceback to learn that the `obj-*/dist/` tree was incomplete. The hint now lands in the thrown `BuildError` directly after the generic exit-code line, so the operator reads the recovery instruction before scrolling up through the traceback.
+- The legacy `machPackage` helper stays exported for callers that only need the exit code; the new variant is additive. A negative-match test pins the pattern to the specific `packager.py` + `.open` pairing so unrelated `NoneType` errors elsewhere in mach output don't falsely trigger the hint.
+
+### Run + watch — bundle-readiness agreement
+
+- `fireforge run` now probes for the launchable binary (`obj-*/dist/<App>.app/Contents/MacOS/<binary>` on macOS, `obj-*/dist/bin/<binary>` on Linux, `obj-*/dist/bin/<binary>.exe` on Windows) via the new `hasRunnableBundle` helper in `src/core/mach-build-artifacts.ts`. Motivating case on a mid-build `hominis/` tree: `fireforge run` failed inside `mach run` because `dist/Hominis.app/Contents/MacOS/hominis` didn't exist yet, while `fireforge watch` happily announced "Using build artifacts from obj-…/" and entered watch mode — the two commands disagreed about whether the obj dir was usable. `run` now refuses up-front with a targeted error naming the missing path ("the expected binary at `obj-debug/dist/MyBrowser.app/Contents/MacOS/mybrowser` is missing — the build may have aborted or is still in progress"). `watch` stays permissive (it exists to drive rebuilds of partially-built trees) but now reports the bundle state in its startup banner: `Using build artifacts from obj-…/ (bundle: runnable)` or `Using build artifacts from obj-…/ (bundle: pending — watch will rebuild)`, so the operator can see at a glance why `run` would refuse right now.
+- `hasRunnableBundle` is exported from `mach.ts` alongside `hasBuildArtifacts`, degrades to `runnable: false` on readdir failure (no throw), and reports `expectedPath` even on the not-runnable branch so error copy can always name what to look for on disk. The three-platform probe is covered by explicit unit tests that mock `getPlatform`.
+
+### Token add — Furnace-initialized precondition
+
+- `fireforge token add` now refuses before any normalization when `furnace.json` is missing under the project root. Motivating case on `fresh/`: running `token add surface-test '#abcdef' --category 'Colors — Canvas' --mode static --dry-run` on a brand-new project surfaced a warning about the missing `furnace.json` and then hard-failed with `Token CSS file not found: browser/themes/shared/freshforge-tokens.css` — technically correct, but the missing tokens CSS is a downstream artefact of Furnace not being initialized. The new guard throws a targeted `FurnaceError`: `Token management requires Furnace. Run "fireforge furnace init" first, then rerun "fireforge token add …"`. Projects with an initialized Furnace hit the existing "tokens CSS file not found" path unchanged when they're missing the rendered tokens file specifically (e.g. after a manual deletion).
+
+### Re-export — stale-manifest advisory without `--scan`
+
+- `fireforge re-export <patch>` now warns at the start of a single-patch run when `--scan`/`--files` is not set AND one or more files in `patches.json`'s `filesAffected` no longer exist on disk. Motivating case on `fresh/lab/`: after discarding a file and re-exporting the patch without `--scan`, the refreshed patch body targeted fewer files than the manifest claimed, and `fireforge verify` then failed on manifest-consistency. The warning names the missing paths and spells out both recovery modes: re-run with `--scan` to reconcile `filesAffected` with the worktree, or `--files <paths>` to set the list explicitly. Behaviour is unchanged when `--scan` / `--files` is set (those modes already reconcile the manifest); this is advisory-only.
+
+### Download — indexing banner
+
+- `fireforge download` now emits a one-line `Indexing downloaded source into git (one-time; typically 1–3 minutes on a ~600 MB Firefox tree)...` before starting the git-init spinner. Motivating case on `fresh/`: after the 609 MB archive download completed, the `git add -A` pass ran silently for minutes, long enough that a CI log tail or non-TTY shell looked like the command had hung. The banner lands via `info` (not the interactive spinner) so non-TTY wrappers still see the heads-up in log scrollback.
+
+### Status — atomic-temp-file filter
+
+- `fireforge status` no longer surfaces FireForge's own in-flight atomic-write temp files in any output mode. Motivating case on `hominis/`: a `status --json` that coincided with a `brand.ftl` or `mozconfig` write briefly listed paths like `.brand.ftl.fireforge-tmp-12345-<uuid>` and `.mozconfig.fireforge-tmp-12345-<uuid>` alongside real changes. `src/utils/fs.ts` now exports `FIREFORGE_TMP_PATH_PATTERN`, a regex anchored on the exact shape `createAtomicTempPath` produces (`<dir>/.<filename>.fireforge-tmp-<pid>-<uuid>`), and `status.ts` filters every status entry through it after `expandDirectoryEntries` and before classification. All status modes — default, raw, unmanaged, ownership, json — apply the same filter, so a late `status` call during a large write produces the same output regardless of which view the operator chose. The pattern is tight enough to let an operator-named `.notes.fireforge-tmp-backup` (no PID+UUID continuation) pass through unfiltered.
+
 ## 0.15.0
 
 ### Re-export — opt-in `--stamp` and per-patch `lintIgnore`

package/README.md

@@ -115,6 +115,8 @@ fireforge import --force
 
 ### Exporting changes
 
+`export`, `export-all`, `lint`, `register`, and `test` all accept either engine-relative paths (`browser/base/content/foo.js`) or repo-root-relative paths with a leading `engine/` segment (`engine/browser/base/content/foo.js`). The prefix is case-insensitive and tolerates leading whitespace; operators commonly paste the repo-rooted form from `git status` output or shell tab-completion.
+
 ```bash
 # Single file
 fireforge export browser/base/content/browser.js

package/dist/src/cli.d.ts

@@ -11,7 +11,10 @@ export declare function resetBrokenPipeHandlerForTests(): void;
 /**
  * Gets the project root directory.
  * Walks up from the current working directory until a fireforge.json is found.
- * Throws when no fireforge.json is found within the walk depth limit.
+ * Throws a {@link ConfigNotFoundError} (code: CONFIG_ERROR) when no
+ * fireforge.json is found within the walk depth limit — the error is
+ * user-facing so `withErrorHandling` can print the guidance without
+ * the stack dump that a plain `Error` would trigger.
  */
 export declare function getProjectRoot(): string;
 /**

package/dist/src/cli.js

@@ -5,6 +5,7 @@ import { Command, Help } from 'commander';
 import { COMMAND_MANIFEST } from './commands/manifest.js';
 import { CancellationError, CommandError, FireForgeError } from './errors/base.js';
 import { ExitCode } from './errors/codes.js';
+import { ConfigNotFoundError } from './errors/config.js';
 import { toError } from './utils/errors.js';
 import { cancel, error as logError, setVerbose } from './utils/logger.js';
 import { getPackageVersion } from './utils/package-root.js';
@@ -64,7 +65,10 @@ const MAX_PROJECT_ROOT_WALK_DEPTH = 50;
 /**
  * Gets the project root directory.
  * Walks up from the current working directory until a fireforge.json is found.
- * Throws when no fireforge.json is found within the walk depth limit.
+ * Throws a {@link ConfigNotFoundError} (code: CONFIG_ERROR) when no
+ * fireforge.json is found within the walk depth limit — the error is
+ * user-facing so `withErrorHandling` can print the guidance without
+ * the stack dump that a plain `Error` would trigger.
  */
 export function getProjectRoot() {
     const start = resolve(process.cwd());
@@ -78,8 +82,7 @@ export function getProjectRoot() {
             break;
         current = parent;
     }
-    throw new Error('Could not find fireforge.json in any parent directory. ' +
-        'Are you inside a FireForge project?');
+    throw new ConfigNotFoundError('fireforge.json');
 }
 /**
  * Wraps a command handler with error handling.

package/dist/src/commands/download.js

@@ -191,6 +191,15 @@ export async function downloadCommand(projectRoot, options) {
         s.error('Download failed');
         throw error;
     }
+    // Finding #17: the git indexing phase of `download` can block for
+    // minutes on a ~600 MB Firefox tree — the spinner updates less often
+    // than operators expect during the monolithic `git add -A` pass, and
+    // non-TTY shells see long stretches of silence. Emit a one-line
+    // heads-up banner BEFORE the spinner starts so even a log-scraping
+    // CI job notes the expected duration. The progress callbacks below
+    // still fire as usual; this is an additional up-front signal, not a
+    // replacement.
+    info('Indexing downloaded source into git (one-time; typically 1–3 minutes on a ~600 MB Firefox tree)...');
     // Initialize git repository
     const gitSpinner = spinner('Initializing git repository (this may take a few minutes)...');
     let baseCommit;

package/dist/src/commands/export-all.js

@@ -8,6 +8,7 @@ import { getAllDiff } from '../core/git-diff.js';
 import { getWorkingTreeStatus } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { commitExportedPatch } from '../core/patch-export.js';
+import { buildPatchQueueContext, collectNewFileCreatorsByPath, detectNewFilesInDiff, } from '../core/patch-lint.js';
 import { GeneralError } from '../errors/base.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
@@ -37,6 +38,47 @@ async function checkFurnaceManagedFiles(paths, projectRoot) {
             'These files are deployed by "fireforge furnace apply" and should be managed through the Furnace workflow. Review them with "fireforge status" or "fireforge furnace status".');
     }
 }
+/**
+ * Refuses the export when the aggregate diff would create (new-file-mode) a
+ * path that some existing patch in the queue already creates. `verify`
+ * detects this post-hoc via `collectNewFileCreatorsByPath`, but by the time
+ * `verify` runs the operator has already landed a patch that irreversibly
+ * sits atop the queue — resolving the conflict from there requires a
+ * `patch delete` or hand-surgery on `re-export --files`. Catching it here,
+ * pre-write, keeps the queue clean and gives the operator a specific path
+ * to narrow with `export` + explicit file scoping (which lets them drop
+ * the already-claimed path without losing other edits).
+ *
+ * Slots in alongside the existing branding and furnace guards so the three
+ * "export-all refuses" branches remain the single, symmetric fence around
+ * unintended captures.
+ */
+async function checkDuplicateNewFileCreations(paths, diff) {
+    if (!(await pathExists(paths.patches)))
+        return;
+    const pendingNewFiles = detectNewFilesInDiff(diff);
+    if (pendingNewFiles.size === 0)
+        return;
+    const ctx = await buildPatchQueueContext(paths.patches);
+    if (ctx.entries.length === 0)
+        return;
+    const creators = collectNewFileCreatorsByPath(ctx);
+    const conflicts = [];
+    for (const path of pendingNewFiles) {
+        const owners = creators.get(path);
+        if (owners && owners.length > 0) {
+            conflicts.push({ path, owners });
+        }
+    }
+    if (conflicts.length === 0)
+        return;
+    const conflictList = conflicts
+        .map(({ path, owners }) => `  • ${path} — already created by ${owners.join(', ')}`)
+        .join('\n');
+    throw new GeneralError('Export-all refuses to capture new-file creations that are already claimed by existing patches.\n\n' +
+        `Conflicting creations:\n${conflictList}\n\n` +
+        'Only one patch may create a given path. Run "fireforge export <path> [...]" with an explicit file list that omits the already-claimed path(s), or resolve the conflict via "fireforge patch delete" / "fireforge re-export --files" before retrying export-all.');
+}
 /**
  * Runs the export-all command to export all changes as a patch.
  * @param projectRoot - Root directory of the project
@@ -69,6 +111,10 @@ export async function exportAllCommand(projectRoot, options = {}) {
         outro('Nothing to export');
         return;
     }
+    // Duplicate-creation preflight needs the diff in hand to see which paths
+    // the aggregate would newly create, so it runs here instead of alongside
+    // the branding / furnace guards that operate on the raw status list.
+    await checkDuplicateNewFileCreations(paths, diff);
     // Check for non-interactive mode
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
     // Auto-fix missing license headers on new files (interactive only)

package/dist/src/commands/export.js

@@ -16,6 +16,7 @@ import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag, PATCH_CATEGORIES } from '../utils/validation.js';
 import { commitPlacementExport, placementSummary, projectPlacementForLint, renderDryRunPreview, resolvePlacementPlan, } from './export-flow.js';
 import { autoFixLicenseHeaders, confirmSupersedePatches, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
@@ -23,7 +24,15 @@ async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
     let fileStatuses;
     let untrackedFiles;
-    for (const inputPath of files) {
+    // Accept both repo-root-relative (`engine/browser/...`) and engine-relative
+    // (`browser/...`) paths for every input, matching `register`/`test`/`lint`.
+    // Previously, an `engine/`-prefixed path fell through to
+    // `File "engine/..." has no changes to export.` because the status lookup
+    // sees paths relative to `paths.engine` and the explicit prefix double-
+    // rooted the candidate. `stripEnginePrefix` makes that user-facing form
+    // a no-op for the lookup pipeline.
+    for (const rawInputPath of files) {
+        const inputPath = stripEnginePrefix(rawInputPath);
         const fullInputPath = join(paths.engine, inputPath);
         let isDirectory = false;
         try {

package/dist/src/commands/furnace/diff.js

@@ -100,6 +100,14 @@ async function diffOverride(name, projectRoot, config) {
 /**
  * Diffs a custom component's workspace files against the engine-deployed copy.
  * Shows what would change (or has changed) on the next `furnace apply`.
+ *
+ * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via `applyCustomFtlFile`
+ * — NOT to `customConfig.targetPath` — so the deployment-target lookup has
+ * to branch on extension. Before this branch existed, a component's
+ * localization file always reported "not yet deployed to engine (new
+ * file)" after a successful apply/deploy because diff was looking for it
+ * under the component's `targetPath` while apply had written it into the
+ * locale tree.
  */
 async function diffCustom(name, projectRoot, config) {
     const customConfig = config.custom[name];
@@ -108,6 +116,7 @@ async function diffCustom(name, projectRoot, config) {
     }
     const paths = getProjectPaths(projectRoot);
     const furnacePaths = getFurnacePaths(projectRoot);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
     const customDir = join(furnacePaths.customDir, name);
     if (!(await pathExists(customDir))) {
         throw new FurnaceError(`Custom component directory not found: components/custom/${name}`, name);
@@ -121,8 +130,19 @@ async function diffCustom(name, projectRoot, config) {
         if (!isComponentSourceFile(entry.name))
             continue;
         const workspacePath = join(customDir, entry.name);
-        const deployedPath = join(engineDir, entry.name);
         const workspaceContent = await readText(workspacePath);
+        // `.ftl` files deploy to the locale tree, not the component's
+        // targetPath; mirror `applyCustomFtlFile`'s target computation so the
+        // diff header and the existence probe name the same path apply
+        // writes to. Any change here must stay in lock-step with
+        // `src/core/furnace-apply-ftl.ts`.
+        const isFtl = entry.name.endsWith('.ftl');
+        const deployedPath = isFtl
+            ? join(paths.engine, ftlDir, entry.name)
+            : join(engineDir, entry.name);
+        const deployedDisplayPath = isFtl
+            ? `engine/${ftlDir}/${entry.name}`
+            : `engine/${customConfig.targetPath}/${entry.name}`;
         if (!(await pathExists(deployedPath))) {
             info(`${entry.name}: not yet deployed to engine (new file)`);
             hasDifferences = true;
@@ -133,7 +153,7 @@ async function diffCustom(name, projectRoot, config) {
             continue;
         }
         hasDifferences = true;
-        info(`--- engine/${customConfig.targetPath}/${entry.name}`);
+        info(`--- ${deployedDisplayPath}`);
         info(`+++ components/custom/${name}/${entry.name}`);
         for (const line of formatUnifiedDiff(deployedContent, workspaceContent)) {
             info(line);

package/dist/src/commands/furnace/override.js

@@ -139,23 +139,37 @@ async function performOverrideMutations(args) {
     });
 }
 /**
- * Throws if `componentName` is already classified anywhere in the furnace
- * config. Without this guard, `writeFurnaceConfig` would happily produce a
- * file where the same tag appears under multiple categories (stock +
- * override, custom + override) and later commands would no longer be able
- * to reason about that component cleanly.
+ * Throws if `componentName` is already classified as something `override`
+ * cannot coexist with. A stock-bucket entry is NOT a hard conflict — the
+ * whole point of `override` is to fork a component out of the stock bucket
+ * into the overrides bucket, and requiring manual `furnace.json` surgery
+ * first was a pure footgun. `promoteStockToOverrideIfNeeded` handles the
+ * transition in-memory; this guard only rejects the other two cases where
+ * a rename actually contradicts existing state.
  */
 function assertNoComponentCollision(config, componentName) {
     if (componentName in config.overrides) {
         throw new FurnaceError(`An override for "${componentName}" already exists in furnace.json`, componentName);
     }
-    if (config.stock.includes(componentName)) {
-        throw new FurnaceError(`"${componentName}" is already registered as a stock component. Remove it from config.stock before creating an override.`, componentName);
-    }
     if (componentName in config.custom) {
         throw new FurnaceError(`"${componentName}" is already registered as a custom component. Custom components cannot also be overrides.`, componentName);
     }
 }
+/**
+ * When the operator overrides a component that `furnace scan` previously
+ * classified as stock, splice the name out of `config.stock` in-memory so
+ * the subsequent `writeFurnaceConfig` inside the mutation phase persists
+ * the stock → override promotion atomically alongside the new override
+ * entry. Returns true when a promotion happened so the caller can emit a
+ * one-line note; false when the component was not stock.
+ */
+function promoteStockToOverrideIfNeeded(config, componentName) {
+    const index = config.stock.indexOf(componentName);
+    if (index === -1)
+        return false;
+    config.stock.splice(index, 1);
+    return true;
+}
 /**
  * Runs the furnace override command to fork an existing engine component.
  * @param projectRoot - Root directory of the project
@@ -213,6 +227,10 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         componentName = selected;
     }
     assertNoComponentCollision(config, componentName);
+    const promotedFromStock = promoteStockToOverrideIfNeeded(config, componentName);
+    if (promotedFromStock) {
+        info(`Promoting "${componentName}" from stock to override.`);
+    }
     // Validate the component exists in engine
     const details = await getComponentDetails(paths.engine, componentName, ftlDir);
     if (!details) {
@@ -323,13 +341,18 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
     const forgeConfig = await loadConfig(projectRoot);
     const state = await loadState(projectRoot);
     // Check for duplicates and pre-existing classifications across every
-    // bucket in furnace.json. Missing these collisions silently double-
-    // classifies a tag (e.g. both stock and override) and leaves the
-    // workspace in a state that later `furnace status`/`apply` cannot
-    // reason about cleanly.
+    // bucket in furnace.json. A stock-bucket entry is promoted in-memory
+    // here (see `promoteStockToOverrideIfNeeded`) rather than rejected —
+    // the operator's intent is to fork that specific stock component. The
+    // collision guard still rejects name conflicts that would double-
+    // classify a tag in a way `writeFurnaceConfig` cannot safely produce
+    // (two overrides, or an override + custom).
     const uniqueNames = [...new Set(names)];
     for (const name of uniqueNames) {
         assertNoComponentCollision(config, name);
+        if (promoteStockToOverrideIfNeeded(config, name)) {
+            info(`Promoting "${name}" from stock to override.`);
+        }
     }
     const succeeded = [];
     const failed = [];

package/dist/src/commands/furnace/preview.js

@@ -6,7 +6,7 @@ import { furnaceConfigExists, loadFurnaceConfig, updateFurnaceState, } from '../
 import { runFurnaceMutation } from '../../core/furnace-operation.js';
 import { restoreRollbackJournal } from '../../core/furnace-rollback.js';
 import { cleanStories, syncStories } from '../../core/furnace-stories.js';
-import { runMach, runMachCapture } from '../../core/mach.js';
+import { hasBuildArtifacts, runMach, runMachCapture } from '../../core/mach.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -89,6 +89,35 @@ function buildStorybookFailureMessage(output, installRequested) {
     return ('Storybook failed to start. Check the output above for the specific Firefox-side error.\n\n' +
         installHint);
 }
+/**
+ * Preflights the Firefox build + toolchain prerequisites `mach storybook`
+ * quietly assumes. Pre-0.16.0 the preview staged components and launched
+ * a ~1000-package `mach storybook upgrade` npm install before the
+ * backend surfaced a "missing chrome-map.json" / Cargo-config failure;
+ * the preflight below refuses fast and leaves the workspace untouched.
+ *
+ * Extracted from `furnacePreviewCommand` so the main function stays
+ * under the per-function LOC budget as the preflight list grows.
+ *
+ * @param engineDir - Resolved engine directory
+ * @throws FurnaceError when the Firefox build hasn't produced dist/, or
+ *         when `.cargo/config.toml` is absent
+ */
+async function assertPreviewPrerequisites(engineDir) {
+    const buildCheck = await hasBuildArtifacts(engineDir);
+    if (!buildCheck.exists) {
+        throw new FurnaceError('Furnace preview requires a completed Firefox build. ' +
+            '`mach storybook` consumes `obj-*/dist/chrome-map.json` and the packaged chrome resources under `dist/`, neither of which is present before `fireforge build` completes.\n\n' +
+            'Run "fireforge build" and wait for it to finish, then rerun "fireforge furnace preview". ' +
+            'This preflight avoids a multi-minute `mach storybook upgrade` npm install on an engine that cannot start Storybook anyway.');
+    }
+    const cargoConfigPath = join(engineDir, '.cargo', 'config.toml');
+    if (!(await pathExists(cargoConfigPath))) {
+        throw new FurnaceError("Furnace preview requires the engine's Rust toolchain to be bootstrapped. " +
+            '`.cargo/config.toml` is missing under the engine directory — `mach storybook` fails deep inside the Storybook backend compile without it.\n\n' +
+            'Run "fireforge bootstrap" (or the underlying `mach bootstrap` in the engine) to populate the toolchain config, then rerun "fireforge furnace preview".');
+    }
+}
 /**
  * Runs the furnace preview command to start Storybook for component preview.
  * @param projectRoot - Root directory of the project
@@ -119,6 +148,9 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
     if (!(await pathExists(storybookRoot))) {
         throw new FurnaceError('This Firefox checkout does not contain browser/components/storybook. Furnace preview requires the upstream Storybook workspace to exist before stories can be synced.');
     }
+    // Build + toolchain preflight (Finding #9). Extracted into a helper so
+    // the function below stays under the per-function LOC budget.
+    await assertPreviewPrerequisites(paths.engine);
     let previewResult;
     // True once we are about to (or have) written to engine/.../stories/furnace.
     // Intentionally set BEFORE `syncStories` is awaited so a mid-sync failure

package/dist/src/commands/furnace/rename.js

@@ -304,14 +304,25 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
         throw new FurnaceError(`A component named "${newName}" already exists in furnace.json.`, newName);
     }
     const componentType = isCustom ? 'custom' : 'override';
+    // `componentType` is the furnace-state key (singular: `custom` /
+    // `override`); the on-disk directory label differs — custom components
+    // live under `components/custom/` (singular) while overrides live under
+    // `components/overrides/` (plural). Before 0.16.0, every rename
+    // user-facing message appended an `s` to `componentType`, which
+    // produced the wrong label `components/customs/` for custom components
+    // and was technically correct for overrides only by coincidence.
+    // `componentDirLabel` centralises the singular/plural pick so every
+    // operator-facing string names the directory that actually exists on
+    // disk.
+    const componentDirLabel = isCustom ? 'custom' : 'overrides';
     const baseDir = isCustom ? furnacePaths.customDir : furnacePaths.overridesDir;
     const oldDir = join(baseDir, oldName);
     const newDir = join(baseDir, newName);
     if (!(await pathExists(oldDir))) {
-        throw new FurnaceError(`Component directory not found: components/${componentType}s/${oldName}`, oldName);
+        throw new FurnaceError(`Component directory not found: components/${componentDirLabel}/${oldName}`, oldName);
     }
     if (await pathExists(newDir)) {
-        throw new FurnaceError(`Target directory already exists: components/${componentType}s/${newName}`, newName);
+        throw new FurnaceError(`Target directory already exists: components/${componentDirLabel}/${newName}`, newName);
     }
     await performRenameMutations({
         projectRoot,
@@ -326,7 +337,7 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
         engineDir: paths.engine,
     });
     note(`Component renamed: ${oldName} → ${newName}\n\n` +
-        `Directory: components/${componentType}s/${newName}/\n\n` +
+        `Directory: components/${componentDirLabel}/${newName}/\n\n` +
         'Next steps:\n' +
         '  1. Review the renamed files for any remaining references\n' +
         '  2. Run "fireforge furnace validate" to verify\n' +

package/dist/src/commands/lint.js

@@ -12,6 +12,7 @@ import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
+import { stripEnginePrefix } from '../utils/paths.js';
 /**
  * Resolves the diff the lint command should run against. Returns `null` when
  * there is nothing to lint (e.g. no matching files, clean tree, or empty
@@ -27,7 +28,15 @@ async function resolveLintDiff(engineDir, files) {
         const collectedFiles = new Set();
         let fileStatuses;
         let untrackedFiles;
-        for (const inputPath of files) {
+        // Strip a leading `engine/` segment up-front so the rest of the lookup
+        // pipeline (directory stat, modified-files-in-dir, status probe) all
+        // see the engine-relative form. Without this, passing
+        // `engine/browser/base/content/foo.js` fell through to "No modified
+        // files found in the specified paths." because git sees every path
+        // relative to engine/. The same normalization runs in `register`,
+        // `test`, and `export` via `stripEnginePrefix`.
+        const normalizedFiles = files.map((inputPath) => stripEnginePrefix(inputPath));
+        for (const inputPath of normalizedFiles) {
             const fullInputPath = join(engineDir, inputPath);
             let isDirectory = false;
             try {

package/dist/src/commands/package.js

@@ -1,7 +1,8 @@
 import { validateBrandOverride } from '../core/brand-validation.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, machPackage } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, machPackageCapture, } from '../core/mach.js';
+import { explainMachError } from '../core/mach-error-hints.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -49,9 +50,16 @@ export async function packageCommand(projectRoot, options) {
     info('Creating distribution package...');
     info('This may take a while.\n');
     const startTime = Date.now();
-    let exitCode;
+    let result;
     try {
-        exitCode = await machPackage(paths.engine);
+        // `machPackageCapture` streams output live AND captures the tail for
+        // post-run diagnostics. Previously `machPackage` inherited stdio
+        // only, so a targeted hint translator could not see the failure text.
+        // The captured stderr is fed through `explainMachError` below so
+        // recognised failure modes (notably the `packager.py` NoneType trip
+        // the evaluator hit on `hominis/`) get an actionable hint prepended
+        // to the raw mach output the operator already saw.
+        result = await machPackageCapture(paths.engine);
     }
     catch (error) {
         throw new BuildError('Package process failed to start', 'mach package', error instanceof Error ? error : undefined);
@@ -60,9 +68,12 @@ export async function packageCommand(projectRoot, options) {
     const minutes = Math.floor(duration / 60000);
     const seconds = Math.floor((duration % 60000) / 1000);
     const timeStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
-    if (exitCode !== 0) {
+    if (result.exitCode !== 0) {
         error(`Packaging failed after ${timeStr}`);
-        throw new BuildError(`Packaging failed with exit code ${exitCode}`, 'mach package');
+        const combinedOutput = `${result.stdout}\n${result.stderr}`;
+        const hints = explainMachError(combinedOutput);
+        const hintBlock = hints.length > 0 ? `\n\nHint:\n${hints.map((h) => `  ${h}`).join('\n')}` : '';
+        throw new BuildError(`Packaging failed with exit code ${result.exitCode}.${hintBlock}`, 'mach package');
     }
     info(`\nPackage created in obj-*/dist/`);
     outro(`Packaging completed in ${timeStr}!`);

package/dist/src/commands/re-export.js

@@ -59,6 +59,31 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     if (options.scan) {
         currentFilesAffected = await scanPatchFiles(currentFilesAffected, paths.engine, manifest, patch.filename, isDryRun);
     }
+    else if (options.files === undefined) {
+        // Finding #16: when neither `--scan` nor `--files` is set and some
+        // of the manifest's claimed files no longer exist on disk, the
+        // re-export silently writes a refreshed body whose filesAffected
+        // still names the vanished paths. That is the documented contract,
+        // but it is also a footgun — a later `verify` then fails on
+        // manifest-consistency with no obvious trigger. Emit one advisory
+        // warning up-front when we can detect the drift cheaply, so the
+        // operator has a chance to re-run with `--scan` or `--files`
+        // before the stale filesAffected lands in patches.json.
+        const missingFiles = [];
+        for (const file of currentFilesAffected) {
+            if (!(await pathExists(join(paths.engine, file)))) {
+                missingFiles.push(file);
+            }
+        }
+        if (missingFiles.length > 0) {
+            warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
+                `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +
+                `filesAffected unchanged and the missing entries will be preserved — ` +
+                `\`fireforge verify\` may flag manifest inconsistency after this run.\n` +
+                `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
+                `or pass --files <paths> to set the list explicitly.`);
+        }
+    }
     // --- Explicit file-subset path ---
     // When --files is given, the target filesAffected is authoritative — drop
     // anything not in the list, add anything new. This is the surgical repair

package/dist/src/commands/register.js

@@ -6,23 +6,7 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
-/**
- * Strips a leading `engine/` segment (either separator flavour) from a
- * user-supplied path so operators can pass either a repo-root-relative
- * path (`engine/browser/base/content/foo.xhtml`) or an engine-relative
- * path (`browser/base/content/foo.xhtml`). The engine-relative form is
- * what the manifest writers expect; without this normalisation, the
- * former failed with a misleading "File not found in engine" pointing
- * at a doubled path like `engine/engine/browser/...` that operators
- * had no way to spot from the error message alone.
- */
-function normalizeEngineRelativePath(filePath) {
-    if (filePath.startsWith('engine/'))
-        return filePath.slice('engine/'.length);
-    if (filePath.startsWith('engine\\'))
-        return filePath.slice('engine\\'.length);
-    return filePath;
-}
+import { stripEnginePrefix } from '../utils/paths.js';
 /**
  * Registers a file in the appropriate build manifest.
  *
@@ -50,7 +34,7 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
     // the former from the output of tab completion or `git status`, and
     // the mismatch used to produce a "File not found" error that named
     // the original path with no hint that dropping `engine/` would fix it.
-    const engineRelativePath = normalizeEngineRelativePath(filePath);
+    const engineRelativePath = stripEnginePrefix(filePath);
     // Verify the file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);