@hominis/fireforge 0.15.8 → 0.16.0

package/CHANGELOG.md

@@ -1,7 +1,92 @@
 # 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`
+
+- New `fireforge re-export --stamp` stamps `sourceEsrVersion` on every successfully re-exported patch to the current `firefox.version` from `fireforge.json`. Previously `re-export` only ever refreshed patch bodies and `filesAffected`; version stamping was exclusive to `rebase`'s `stampPatchVersions` call (plus `doctor --repair-patches-manifest`). An operator asked to "re-export targeting a new ESR" had no in-surface signal that the command could not deliver the version half of that request, and had to route through the full rebase flow (which requires a Firefox source re-download) purely to update a version string. `--stamp` closes that gap for the case where the re-export cleanly refreshes every selected patch — a partial run (any skipped or failed patch) refuses to stamp and the success line notes the refusal, so a torn "some bodies refreshed at old version, some at new" state is not representable. The command description and `--help` text now explicitly call out that `re-export` does NOT change `sourceEsrVersion` by default.
+- New optional `lintIgnore: string[]` field on each patch entry in `patches.json` lists lint check IDs to suppress for that patch specifically. Surgical alternative to `--skip-lint` (which downgrades _every_ error to a warning) for the class of patch that is advisory-noisy by nature — cohesive branding bundles, localised-resource packs, auto-generated manifests — where a rule like `large-patch-lines` is not actionable. Threaded through `lintExportedPatch` as an optional `ignoreChecks` filter, honoured by `re-export`, `re-export --files`, and `lint --per-patch`. The file-level `fireforge-ignore:` comment markers for `raw-color-value` and `forward-import` are unchanged; `lintIgnore` fills the gap at the patch level where no per-line marker can exist (the `.patch` body is regenerated on every export). Unknown check IDs are a no-op so the metadata documents the _intent_ to suppress even if the rule is renamed later.
+- Motivating case: re-exporting a 22-patch queue onto 140.9.0esr after `download --force` failed on `001-branding-branding-assets` with `ERROR [large-patch-lines] (patch): Patch is 15665 lines (hard limit: 3000)` — a 57-file branding bundle that genuinely cannot be split. The only escape was `--skip-lint` (downgrades 22 patches' worth of errors) or the full `rebase` flow (already-wasted Firefox download). With `lintIgnore: ["large-patch-lines", "large-patch-files"]` on that one patch, `re-export --all --scan --stamp` now completes in one call.
+
+### Lint — `--per-patch` scope and aggregate-mode hint
+
+- New `fireforge lint --per-patch` scopes the lint diff to each patch's own `filesAffected` in turn rather than the aggregate `git diff HEAD` across every applied patch. Motivating case: running `fireforge lint` (no args) after `fireforge import` / `fireforge rebase` has just applied a 22-patch queue produces an aggregate diff of every patch summed, which means the patch-size advisory rules (`large-patch-lines`, `large-patch-files`) fire against the sum — e.g. `Patch is 37529 lines`, `Patch affects 126 files` — with `Lint failed` and a non-zero exit code on a repo that is actually in a good state. The aggregate framing reads as a task-specific regression when it is really an artefact of aggregation. `--per-patch` restates the scope so each patch lints as its own isolated diff, honours the patch's own `lintIgnore` entries, and runs the cross-patch rules (`duplicate-new-file-creation`, `forward-import`) once over the whole queue so queue-level findings are not lost by the rescoping. Mutually exclusive with explicit file paths (the two scope contracts are different).
+- Aggregate-mode runs that would otherwise surface a `large-patch-lines` / `large-patch-files` error against a multi-patch queue now print a one-line `NOTE: aggregate diff across all applied patches. Use 'fireforge lint --per-patch' to lint each patch individually; patch-size rules fire against the sum in aggregate mode.` ahead of the failure message, so the operator reaches the per-patch escape hatch without having to read the help text first. The note fires only when the patches directory has at least two entries AND the rule that fired is a patch-size rule — a single-patch queue or a non-size rule behaves identically to before.
+- Per-patch output namespaces every issue with its owning patch filename (`ERROR [relative-import] 001-ui-test.patch :: browser/base/content/a.ts: …`) so triage can attribute findings without cross-referencing patches.json. The passing summary reports how many patches were actually linted (patches with no files on disk or an empty projected diff are silently skipped — they are not a finding).
+
 ### Test — xpcshell appdir auto-injection
 
 - `fireforge test` now auto-injects `--app-path=<absolute>` into mach test invocations whose nearest `xpcshell.toml` sets `firefox-appdir = "browser"` on a rebranded fork (appname != `firefox`). Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws because the upstream xpcshell harness reads the appdir override under the appname-keyed manifest field (`<appname>-appdir`) — the literal `firefox-appdir = "browser"` directive is silently ignored when `appname` is anything other than `firefox`, so `appPath` falls back to `xrePath` (one level above the real app root). The resolver lives in the new `src/core/xpcshell-appdir.ts`: it walks each test path to the nearest `xpcshell.toml`, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest (so an operator who already migrated is not overridden), and otherwise probes `<objDir>/dist/bin/<value>` and `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` for the absolute target. Operator overrides via `--mach-arg=--app-path=…` always win and the resolver is skipped silently when one is detected. Mismatches across multiple test paths (different manifests resolving to different app dirs) and unresolvable manifest values (no candidate under `dist/`) are surfaced as warnings rather than guessed at, so triage can reach the underlying cause instead of debugging a wrong path.

package/README.md

@@ -64,8 +64,7 @@ npx fireforge export browser/base/content/browser.js --name "custom-toolbar" --c
 ```
 
 3. Your patch is now in `patches/`.
-
-# 4. Reset and import to verify everything applies cleanly:
+4. Reset and import to verify everything applies cleanly:
 
 ```bash
 npx fireforge reset --yes
@@ -116,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
@@ -139,6 +140,13 @@ fireforge export browser/base/content/browser.js --before 005-ui-sidebar.patch -
 
 # Restrict a re-export to a specific file subset
 fireforge re-export --files browser/base/content/browser.js 002-ui-toolbar
+
+# Refresh every patch AND stamp sourceEsrVersion from fireforge.json onto each
+# one. Only stamps when every selected patch refreshes cleanly — partial
+# runs refuse to stamp. Use when you re-exported after a manual Firefox
+# bump that did not go through `rebase`. By default `re-export` refreshes
+# patch bodies and filesAffected but does NOT change sourceEsrVersion.
+fireforge re-export --all --scan --stamp
 ```
 
 ### Rebasing on top of a new Firefox version
@@ -176,12 +184,15 @@ This re-exports the fixed patch and continues applying the remaining stack.
       "description": "Replaces default Firefox branding with custom logo",
       "createdAt": "2025-01-15T10:30:00Z",
       "sourceEsrVersion": "140.9.0esr",
-      "filesAffected": ["browser/branding/official/logo.png"]
+      "filesAffected": ["browser/branding/official/logo.png"],
+      "lintIgnore": ["large-patch-lines", "large-patch-files"]
     }
   ]
 }
 ```
 
+The optional `lintIgnore` field lists lint check IDs to suppress for that patch specifically. Useful for the class of patch that is advisory-noisy by nature — a cohesive branding bundle, a localised-resource pack, an auto-generated manifest — where `--skip-lint` is too blunt and a per-line marker cannot exist (the `.patch` body is regenerated on every export). Threaded through `export`, `re-export`, `re-export --files`, and `lint --per-patch`. Unknown check IDs are a no-op.
+
 If the manifest drifts after an interrupted export or manual edits, `fireforge import` will stop rather then silently applying a stale stack. Use `fireforge doctor --repair-patches-manifest` to rebuild it from disk. Because the rebuild is deterministic, the result will always be consistent with what is actually on the filesystem.
 
 </details>
@@ -191,6 +202,8 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 `fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
 
+By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further; the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
+
 | Check                          | Scope                                                                     | Severity                 |
 | ------------------------------ | ------------------------------------------------------------------------- | ------------------------ |
 | `missing-license-header`       | New files (JS/CSS/FTL)                                                    | error                    |

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-shared.d.ts

@@ -11,8 +11,13 @@ import type { SpinnerHandle } from '../utils/logger.js';
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional per-patch set of `check` IDs to suppress
+ *   (threaded from `PatchMetadata.lintIgnore`). Surgical alternative to
+ *   `--skip-lint` when exactly one advisory rule does not apply to a
+ *   specific patch — e.g. `large-patch-lines` on a cohesive branding
+ *   bundle that genuinely cannot be split.
  */
-export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext): Promise<void>;
+export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>): Promise<void>;
 /**
  * Resolves patch metadata interactively or from flags, with shared validation.
  * @param options - Export command options

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

@@ -18,9 +18,14 @@ import { isValidPatchCategory, PATCH_CATEGORIES, validatePatchName } from '../ut
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional per-patch set of `check` IDs to suppress
+ *   (threaded from `PatchMetadata.lintIgnore`). Surgical alternative to
+ *   `--skip-lint` when exactly one advisory rule does not apply to a
+ *   specific patch — e.g. `large-patch-lines` on a cohesive branding
+ *   bundle that genuinely cannot be split.
  */
-export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx) {
-    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx);
+export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx, ignoreChecks) {
+    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx, ignoreChecks);
     if (issues.length === 0)
         return;
     const errors = issues.filter((i) => i.severity === 'error');

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' +