@hominis/fireforge 0.18.0 → 0.18.1

package/CHANGELOG.md

@@ -20,8 +20,8 @@
 - **`fireforge test --doctor` — triple-path PASS footer survives non-TTY clack rendering.** The eval's `test --doctor` captures on both fresh and hominis projects showed `● Running marionette preflight...` and then exited 0 with nothing else — the 0.17.0 `outro(\`Marionette preflight: PASS (...)\`)`was dropped by clack somewhere in the non-TTY render pipeline (exact root cause could not be isolated from captures alone). Rather than chase the rendering bug, the fix triple-writes the result:`success(\`Marionette preflight: PASS (...)\`)`, then `outro('Test completed')`closes the intro frame, then`process.stdout.write(\`${summary}\n\`)`guarantees the line reaches stdout regardless of clack's buffering. A test in`test.test.ts` asserts all three emissions.
 - **`fireforge test` — fork-owned module import failures beat the branding stale-build diagnosis.** The eval's hominis xpcshell test failed loading `resource:///modules/hominis/HominisStore.sys.mjs`; FireForge reported "stale build artifacts, run fireforge build --ui" because the harness teardown also printed a branding warning that matched the narrower stale-build pattern. Re-running the build did nothing — the real failure was that the new module wasn't registered in `browser/modules/hominis/moz.build`. `handleNonZeroTestExit` now checks for `Failed to load resource:///modules/<binaryName>/` BEFORE the branding stale-build branch and surfaces a fork-module-specific diagnostic pointing at `browser/modules/<binary>/moz.build` + `fireforge register`, so the operator sees the correct recovery path on the first try. Existing branding-stale diagnosis is untouched.
 - **`fireforge token coverage` — `--moz-*` platform variables allowlisted by default; untracked CSS directories now scanned.** Two independent token-coverage fixes:
-  - **Platform allowlist** — `src/core/token-coverage.ts` seeds a default `platformPrefixes: ['--moz-']` and treats matches as `allowlisted` rather than `unknown`. A CSS-only Furnace override of `moz-button` with one fork token previously reported 1% coverage because the copied upstream baseline referenced 84 `--moz-*` platform vars; coverage now reports 100% on the same diff, and the one unknown was correctly declared by the fork. Forks can override through a new optional `platformPrefixes?: string[]` field on `furnace.json` — extending the list (e.g. `['--moz-', '--in-content-']`) for forks with additional platform prefixes, or setting an explicit empty array to restore the pre-0.18 strict contract. The field is added to the public `FurnaceConfig` type.
-  - **Untracked-directory expansion** — `src/commands/token-coverage.ts` now reads `getWorkingTreeStatus` + `expandUntrackedDirectoryEntries` instead of `getStatusWithCodes` so CSS files inside a `?? dir/` untracked directory (the common shape for a freshly-imported patch stack adding a new theme tree) show up in the scan. The eval's hominis run saw `?? browser/branding/hominis/content/aboutDialog.css` and `?? browser/themes/shared/hominis-tokens.css` collapse to directory entries that didn't end in `.css`; coverage reported "No modified CSS files". Both CSS files are now scanned.
+- **Platform allowlist** — `src/core/token-coverage.ts` seeds a default `platformPrefixes: ['--moz-']` and treats matches as `allowlisted` rather than `unknown`. A CSS-only Furnace override of `moz-button` with one fork token previously reported 1% coverage because the copied upstream baseline referenced 84 `--moz-*` platform vars; coverage now reports 100% on the same diff, and the one unknown was correctly declared by the fork. Forks can override through a new optional `platformPrefixes?: string[]` field on `furnace.json` — extending the list (e.g. `['--moz-', '--in-content-']`) for forks with additional platform prefixes, or setting an explicit empty array to restore the pre-0.18 strict contract. The field is added to the public `FurnaceConfig` type.
+- **Untracked-directory expansion** — `src/commands/token-coverage.ts` now reads `getWorkingTreeStatus` + `expandUntrackedDirectoryEntries` instead of `getStatusWithCodes` so CSS files inside a `?? dir/` untracked directory (the common shape for a freshly-imported patch stack adding a new theme tree) show up in the scan. The eval's hominis run saw `?? browser/branding/hominis/content/aboutDialog.css` and `?? browser/themes/shared/hominis-tokens.css` collapse to directory entries that didn't end in `.css`; coverage reported "No modified CSS files". Both CSS files are now scanned.
 - **`fireforge patch reorder` + `fireforge patch delete` — accept manifest `name` handle in addition to filename and ordinal.** `resolvePatchIdentifier` in `src/core/patch-manifest-resolve.ts` previously rejected the `name` field even though CLI help says `<name>` and the manifest stores a `name` on every entry. Operators had to copy the full filename from `patches.json` before every queue mutation. The resolver now matches, in order: ordinal number → exact filename → filename-with-`.patch`-appended → `name` field. Filename lookup still wins when a manifest happens to have a `name` identical to a different filename — legacy scripts passing filenames keep working. Error messages on both commands now list filenames AND their `name` counterparts so operators see both forms as valid identifiers.
 - **`fireforge patch reorder` — postcondition assert on each Phase 2 rename.** The eval reported that a two-patch swap updated `patches.json` but left the files at their pre-rename names, and `fireforge verify` then failed ENOENT opening the manifest-renamed file. The code path in `renumberPatchesInManifest` (two-phase staging: stage → final + manifest write) appears correct against both the integration test in `patch-mutations.integration.test.ts` and the shipped 0.17.0 dist — but the eval's operation log shows the manifest was updated while the rename was missing, so a filesystem-specific failure mode exists that the existing integration test does not exercise. Defense-in-depth lands a postcondition `pathExists(newFilename)` assert after every `rename()` in Phase 2, so any silent rename failure aborts the reorder before the manifest write and triggers the Phase 2 rollback (which itself reverses completed final-name moves and unwinds the staging). A second integration test reproduces the exact eval scenario (`001-infra` + `002-ui` swap via `--to 1 --yes`) and asserts both filenames exist on disk after completion.
 - **`fireforge register --dry-run` — honours the rule-level idempotency decision.** `registerFile` in `src/core/manifest-rules.ts` returned `{ skipped: true }` when the rule's `isRegistered(...)` check found the file already present in its manifest, but `registerCommand` in `src/commands/register.ts` ignored the flag on the dry-run branch and always printed `[dry-run] Would register <path>`. The next real invocation correctly reported `Already registered: <path>`. Automation that consumed the dry-run as a plan mis-predicted unnecessary work. Dry-run now prints `[dry-run] Already registered: <path> in <manifest>` when `result.skipped` is true — mirroring the real-run copy — and otherwise prints the registration plan as before.
@@ -30,9 +30,25 @@
 - **`fireforge register` — empty single-line `EXTRA_JS_MODULES += []` lists expand before insertion.** `tokenizeMozBuildList` in `src/core/manifest-tokenizers.ts` tracked opening `[` and closing `]` on separate lines. A freshly-scaffolded `browser/modules/<fork>/moz.build` that wrote `EXTRA_JS_MODULES += []` on one line returned `null` from the tokenizer because the scanner never saw a line STARTING with `]`, and `registerFireForgeModule` failed with `Could not find EXTRA_JS_MODULES in moz.build` — blocking the documented `browser/modules/<fork>/*.sys.mjs` workflow at the first module. The tokenizer now detects the single-line empty-list form `...+= []` at open time, rewrites `lines[i]` to `...+= [` and splices in a `]` at `i + 1`, and emits matched `list-open` / `list-close` tokens for the canonical multi-line shape. Downstream `findAlphabeticalMozBuildPosition` and the register helpers then place the new entry inside the brackets as normal.
 - **`fireforge wire --dry-run` — notice when the subscript file is absent.** The dry-run branch in `src/commands/wire.ts` deliberately skips the subscript-file existence check to support the "wire first, create the file after" scaffolding workflow. Pre-0.18 that deliberate skip produced a plausible plan even when the subscript was genuinely missing, and the real `wire` invocation then refused with `Subscript file not found`. The skip stays (the workflow is legitimate) but dry-run now emits `Note: <subscriptDir>/<name>.js does not exist yet — the real wire command will require it before writing.` so the operator sees the absence in the preview and can create the file before re-running without `--dry-run`.
 - **`fireforge status --unmanaged` + `fireforge register` — browser-chrome test files route to browser.toml, not jar.mn.** The browser-content pattern in `src/core/manifest-rules.ts` matched every `browser/base/content/**/*.{js,mjs,xhtml,css}` path, including test implementation files at `browser/base/content/test/<dir>/browser_*.js`. `status --unmanaged` therefore proposed `fireforge register browser/base/content/test/forgeqa/browser_forgeqa_qa_browser.js` which, if run, would cluttered jar.mn with a test-file chrome URI (the right place for those files is the sibling `browser.toml`). The pattern now excludes the `test/` subtree via a negative lookahead, so these paths fall through to `getUnregistrableAdvice`, which already returns the correct browser.toml-centric guidance for individual test files. `status`, `register`, and `register --dry-run` all now agree that test JS belongs in the test manifest.
+- **`fireforge export-all --exclude-furnace` — refuses patches that would register a furnace component without carrying its source files; `fireforge verify` now flags dangling registrations that slipped through earlier versions.** Finding 1 (High). The evaluator's fresh-project smoke sequence (`furnace init` → `token add` → `furnace override moz-button -t css-only` → `furnace create moz-qa-panel --localized --with-tests --test-style mochikit` → `furnace deploy` → `export-all --exclude-furnace`) produced a patch whose `toolkit/content/customElements.js`, `toolkit/content/jar.mn`, and `toolkit/locales/jar.mn` hunks registered `moz-qa-panel` even though the widget sources were filtered out. `fireforge verify` reported "Verify clean" for the broken queue. The fix lands in two layers: a new `collectPatchRegistrationReferences` scanner in `src/core/patch-registration-refs.ts` extracts component-shaped registration references from any patch body, and `verifyCommand` in `src/commands/verify.ts` now cross-checks each extracted reference against both the aggregate `filesAffected` coverage and the engine working tree — any miss fires a `dangling-registration` error naming the specific patch + target path. `export-all --exclude-furnace` in `src/commands/export-all.ts` calls the same scanner before writing and refuses with a clear message when the hunks would register a furnace-managed component not included in the patch. Tests in `patch-registration-refs.test.ts` + `verify.integration.test.ts` pin both halves.
+- **`fireforge status --unmanaged` — tolerates a missing parent moz.build instead of exiting non-zero.** Finding 2 (Medium). `printUnregisteredWarnings` in `src/commands/status.ts` awaited `Promise.all` on `isFileRegistered` checks, and the manifest-rules layer threw `GeneralError("Manifest not found: ...")` synchronously when the parent `moz.build` was absent — exactly the state an operator hits after scaffolding a new engine module and before running `register`. Status is a read-only reporter; the non-zero exit broke `status --unmanaged` as a discovery tool. The fix wraps each `isFileRegistered` call in a narrowly scoped try/catch, buckets missing-manifest cases into a distinct "registration manifest does not exist yet" warning list, and lets the command exit cleanly. Other error shapes still propagate. A regression test in `status.test.ts` pins the new contract.
+- **`fireforge lint --since HEAD --only-introduced` — aggregate patch-size findings tag as `[introduced]` when the diff set is non-empty.** Finding 4 (Low). The `large-patch-files` and `large-patch-lines` rules emit findings with the synthetic `file: '(patch)'` placeholder, which never matched any entry in the `diffFiles` set. `tagLintIssues` in `src/core/patch-lint-diff-tag.ts` therefore tagged them `[cumulative]` even when the aggregate was entirely the operator's own diff — reading as "pre-existing drift" to an operator asking "what did this task introduce?" The tagger now recognises the synthetic placeholder (exported as `AGGREGATE_PATCH_FILE`) and promotes it to `introduced` whenever the diff set is non-empty. Cumulative semantics are preserved for the empty-diff case. Tests in `patch-lint-diff-tag.test.ts` pin both branches.
+- **`fireforge furnace remove` / `rename` / `validate` — xpcshell scaffolds are cleaned up, renamed, and flagged as orphans.** Finding 5 (Medium). `furnace create --with-tests --xpcshell` scaffolds at `browser/base/content/test/<binary>-xpcshell/<name>/`, but the pre-0.18.1 `furnace remove` only touched the sibling browser-mochitest tree and `furnace rename` never reached the scaffold at all. Operators who ran create → rename → remove were left with an orphan scaffold whose filenames still referenced the original pre-rename component. The path template is now centralised in `xpcshellTestParentDir` in `src/core/furnace-constants.ts`; `create-xpcshell.ts` consumes it, a new `cleanupCustomXpcshellTestFiles` helper in `src/commands/furnace/remove.ts` removes the scaffold under the journal contract, a new `renameXpcshellTestFiles` helper in `src/commands/furnace/rename-xpcshell.ts` (extracted to keep `rename.ts` under the per-file LOC budget) updates the directory, test filename, TOML section header, and word-boundary tag references in the test body, and `findOrphanXpcshellScaffolds` in `src/core/furnace-validate.ts` walks the parent directory reporting any entry whose name is not in furnace.json as an `orphan-xpcshell-scaffold` error. The validator degrades silently on projects that never used xpcshell scaffolding. Test coverage lands in `furnace-validate-xpcshell-orphan.test.ts`.
+- **`fireforge doctor --repair-patches-manifest` — recovery guidance no longer contradicts the docs by telling operators to hand-edit patches.json.** Finding 6 (Low). The per-filename warning emitted on recovered manifest entries ended with "Edit patches.json to restore the original description if you have it backed up." — which directly contradicts the README and Hominis docs that treat the manifest as FireForge-owned. The reworded warning now points at `fireforge re-export <filename> --description "<your description>"` (or the equivalent `fireforge export` invocation) to overwrite the reconstructed metadata through the tool, and explicitly warns against hand-editing. Test coverage in `doctor.test.ts` pins both the presence of the new guidance and the absence of the old "Edit patches.json" string.
+- **`fireforge test --doctor` — PASS/FAIL line written directly to stdout, bypassing any clack flush races.** Finding 7 (Medium). The 0.18.0 "belt-and-suspenders" approach still reproducibly dropped the PASS footer under non-TTY capture — the eval log showed only the intro and `Running marionette preflight...` banner before exit. A new `formatMarionettePreflightLine` helper in `src/core/marionette-preflight.ts` returns the raw banner as a plain string, and `testCommand` in `src/commands/test.ts` writes both the "Running marionette preflight..." intro and the final PASS/FAIL summary via `process.stdout.write` as the authoritative emissions so non-TTY captures always see the summary. The clack `success()` + `outro()` calls are retained for TTY framing. Test coverage in `test.test.ts` now spies on `process.stdout.write` and asserts both the intro and PASS lines are emitted.
+- **`fireforge test` — xpcshell appdir probe prefers the macOS `.app/Contents/Resources/<value>` layout on Darwin.** Finding 8 (High). `resolveAbsoluteAppPath` in `src/core/xpcshell-appdir.ts` probed `dist/bin/<value>` first on every platform. On macOS `dist/bin` is a symlink to `<App>.app/Contents/MacOS/`, so `dist/bin/browser` resolved to the _binaries_ directory rather than the Resources tree where `resource:///modules/` is rooted — the auto-injection logged success, but the injected path did not match where modules actually live. The probe now branches on `process.platform`: on Darwin it prefers `<App>.app/Contents/Resources/<value>` first and falls back to `dist/bin/<value>`; other platforms keep the historical order. The operator-facing `buildXpcshellAppdirMessage` in `src/commands/test.ts` also gains a macOS-specific note recommending the `<appname>-appdir = "browser"` xpcshell.toml migration, which is the most reliable fix on rebranded macOS builds. Test coverage in `xpcshell-appdir.test.ts` now exercises both probe orders via `process.platform` branches.
+- **`fireforge download` — git-indexing timeouts raise a typed `GitIndexingTimeoutError` with env-var recovery guidance, and the monolithic → chunked transition is visible in non-TTY logs.** Finding 10 (High). On a loaded filesystem the fresh Firefox source indexing legitimately exceeded the 10-minute monolithic `git add -A` budget; the chunked fallback then hit its own `AbortSignal.timeout` and surfaced a generic `AbortError: The operation was aborted` with no recovery direction. `src/core/git-base.ts` now exposes `FIREFORGE_GIT_ADD_TIMEOUT_MS` and `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` environment variables that override the monolithic (default 10 min) and chunked (default grew to 30 min) timeouts respectively; the chunked pass's timeout is wrapped into a typed `GitIndexingTimeoutError` in `src/errors/git.ts` that names the elapsed budget, points at the environment variable override, and explains the `fireforge download --force` resume path. The fallback-transition progress banner now names the specific timeout so operators watching a non-TTY log see exactly when the monolithic attempt lost. Test coverage in `git-performance.test.ts` pins both the new error type and the refreshed transition banner.
+- **`fireforge rebase --dry-run` — refuses when the engine has no baseline commit.** Finding 11 (Medium). A partially-initialised engine (e.g. the aftermath of an aborted `download --force`) has `.git/` in place but no valid HEAD; the real `rebase --yes` immediately failed with `fatal: ambiguous argument 'HEAD'` even though dry-run had previously reported "Dry run complete" suggesting the rebase was ready to run. `handleFreshStart` in `src/commands/rebase/index.ts` now calls `getHead(paths.engine)` and, on `isMissingHeadError`, throws a clear `GeneralError` pointing at `fireforge download --force`. The check runs ahead of the dry-run early-exit so dry-run and real-run preconditions stay in sync. Test coverage in `rebase.test.ts` pins both the dry-run and real-run refusal paths.
+- **`fireforge watch` — resolved watchman directory is prepended to the mach subprocess PATH.** Finding 12 (Medium). `fireforge watch` located watchman via the parent shell PATH but the `mach watch` subprocess inherited the Node parent's PATH, which on macOS frequently omits `/opt/homebrew/bin`. `mach watch` then failed at the `watch-project` subscription step with a confusing `FasterBuildException: timed out`. `watch.ts` now resolves watchman's absolute path via `findExecutable`, prepends the containing directory to the subprocess PATH, and threads the composed env through a new optional `options.env` parameter on `watchWithOutput` in `src/core/mach.ts`. The watch-failure diagnostic also gains a line naming the resolved watchman path so operators can distinguish "FireForge didn't find watchman" from "FireForge found watchman but mach still failed to reach it." Test coverage in `watch.test.ts` pins the env plumbing and the de-duplication branch.
+- **`fireforge furnace preview` — first-run banner frames the unavoidable npm noise from `mach storybook`.** Finding 13 (Low). `mach storybook` internally drives a ~1000-package `npm install` when the Storybook workspace's `node_modules/` is absent and emits `npm error code ELSPROBLEMS` + `UNMET DEPENDENCY` lines verbatim. Operators on a fresh Firefox checkout read the npm block as a fatal error even though the command recovers and Storybook starts. `furnacePreviewCommand` in `src/commands/furnace/preview.ts` now checks for the absent `node_modules` before spawning mach and emits a clear pre-banner explaining the npm output is an expected one-time first-run cost; an explicit "Storybook stopped cleanly." line fires on clean exits so the npm noise is visually terminated. The `--install` path skips the banner because `mach storybook upgrade` already runs its install before `mach storybook` launches. Test coverage in `furnace-preview.test.ts` pins both the presence of the banner when node_modules is absent and its absence when node_modules is already populated.
 
 ### Internal
 
+- **Module extractions preserve the per-file LOC budget.** `doctor-working-tree.ts` hosts `inspectEngineWorkingTree` (the ownership-aware working-tree check), `doctor-furnace-manifest-sync.ts` hosts the orphan override / custom detection + repair, `patch-registration-refs.ts` hosts the dangling-registration scanner shared between `verify` and `export-all`, and `rename-xpcshell.ts` hosts the xpcshell scaffold rename path. All spliced into their respective orchestrators from the hosting file, keeping `doctor.ts`, `doctor-furnace.ts`, `rename.ts`, and `preview.ts` under the 500-line `max-lines` rule. The drift test in `manifest.test.ts` classifies each new file as a helper so the top-level command drift check stays clean.
+- **Expanded test coverage.** Every eval3 fix ships with at least one regression test exercising the failing path: `patch-registration-refs.test.ts` + `verify.integration.test.ts` (Finding 1), `status.test.ts` (Finding 2), `patch-lint-diff-tag.test.ts` (Finding 4), `furnace-validate-xpcshell-orphan.test.ts` (Finding 5), `doctor.test.ts` (Finding 6), `test.test.ts` (Finding 7), `xpcshell-appdir.test.ts` (Finding 8), `git-performance.test.ts` (Finding 10), `rebase.test.ts` (Finding 11), `watch.test.ts` (Finding 12), `furnace-preview.test.ts` (Finding 13).
+
+### Internal (0.18.0 original)
+
 - **Two small module extractions preserve the per-file LOC budget.** `doctor-working-tree.ts` hosts `inspectEngineWorkingTree` (the ownership-aware working-tree check), and `doctor-furnace-manifest-sync.ts` hosts the orphan override / custom detection + repair. Both are spliced into their respective registries from the hosting file, keeping `doctor.ts` and `doctor-furnace.ts` under the 500-line `max-lines` rule. The drift test in `manifest.test.ts` is extended to classify both new files as helpers so the top-level command drift check stays clean.
 - **Expanded test coverage — 34 new assertions.** Every fix above ships with at least one new test exercising the regression path: `src/core/__tests__/git-diff.test.ts` gains a `?? dir/` expansion case; `src/commands/__tests__/doctor.test.ts` gains patch-backed / conflict / orphan-override / manifest-sync-repair cases; `furnace-remove.test.ts` + `furnace-rename.test.ts` pin the locale jar.mn re-wire / removal; `furnace-override.test.ts` pins the concurrent-writer read-modify-write; `build.test.ts` pins the stale-configure annotation; `test.test.ts` pins the fork-module diagnostic + triple-path PASS footer; `token-coverage.test.ts` pins the `--moz-*` allowlist + untracked-dir expansion; `patch-manifest-helpers.test.ts` pins name-field resolution; `patch-mutations.integration.test.ts` pins the two-patch swap postcondition; `register.test.ts` pins dry-run idempotency; `wire-init.test.ts` pins the marker; `manifest-tokenizers.test.ts` + `register-module.test.ts` pin the empty-list expansion; `wire.test.ts` pins the dry-run missing-subscript notice; `manifest-register.test.ts` pins the test-file pattern exclusion.
 

package/README.md

@@ -36,7 +36,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 - **Python 3** (required by Firefox's `mach` build system).
 - **Git**
 - Platform build tools: Xcode on macOS, `build-essential` on Linux, Visual Studio Build Tools on Windows.
-- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH` so the dependency is visible during the usual onboarding sweep rather than at the watch-mode failure site.
+- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH` so the dependency is visible during the usual onboarding sweep rather than at the watch-mode failure site. `fireforge watch` resolves watchman's absolute path via `which` / `where` and prepends its directory to the subprocess `PATH` it hands mach, so a homebrew-installed watchman at `/opt/homebrew/bin/watchman` (absent from the Node subprocess's default `PATH` on macOS) is still visible to `mach watch` without the operator having to re-export `PATH` manually.
 
 ### Setup
 
@@ -83,6 +83,10 @@ npx fireforge download --force
 npx fireforge rebase
 ```
 
+`fireforge download` indexes the extracted Firefox source into a fresh git repository — a one-time 1–3 minute pass on a cold SSD, longer on slow or loaded disks. The monolithic `git add -A` is capped at 10 minutes by default and falls back to a per-directory chunked pass (30 minutes per chunk) when the cap hits. If indexing still times out, the command now raises `GitIndexingTimeoutError` with recovery guidance: extend the cap via `FIREFORGE_GIT_ADD_TIMEOUT_MS` (monolithic) and/or `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` (chunked) in milliseconds, e.g. `FIREFORGE_GIT_ADD_TIMEOUT_MS=1800000 fireforge download --force` for a 30-minute monolithic budget, then re-run `fireforge download --force` — the resume path picks up from the partial git state so the repeat is not wasted work.
+
+`fireforge rebase --dry-run` refuses when the engine has no baseline commit yet (e.g. the aftermath of an aborted `download --force`), so dry-run and real-run preconditions stay in sync.
+
 ## Patch Workflow
 
 Patches live in `patches/`, applied by numeric filename prefix and tracked in `patches/patches.json`:
@@ -259,17 +263,18 @@ fireforge status --json             # machine-readable classified output
 
 Then fix with the appropriate primitive:
 
-| Problem                                        | Fix                                                                   |
-| ---------------------------------------------- | --------------------------------------------------------------------- |
-| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files` |
-| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                 |
-| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                            |
-| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                             |
-| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                        |
-| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                          |
-| Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                       |
+| Problem                                        | Fix                                                                                                          |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files`                                        |
+| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                                                        |
+| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                                                                   |
+| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                                                                    |
+| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                                                               |
+| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                                                                 |
+| Dangling widget / locale registration in patch | Re-run `fireforge export` without `--exclude-furnace` to capture the source files, or revert furnace changes |
+| Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                                                              |
 
-Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge.
+Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge — `doctor --repair-patches-manifest` reconstructs missing metadata, and `fireforge re-export <filename> --description "<text>"` overwrites recovered entries with operator-supplied metadata through the tool. `fireforge verify` cross-checks every registration hunk in each patch body against the files the queue and engine supply, so a patch that registers a widget / locale without carrying its source surfaces as a `dangling-registration` error rather than slipping through as "Verify clean"; `fireforge export-all --exclude-furnace` refuses up-front when it would produce that shape.
 
 ## Wiring Custom Code
 
@@ -472,6 +477,8 @@ fireforge lint --since main --only-introduced
 
 The failure message reports how many cumulative errors were suppressed by the flag so a branch that passed only because of the flag still tells the operator what was hidden. Without `--since`, `--only-introduced` is rejected up-front — there is no introduced-vs-cumulative distinction to scope to.
 
+Aggregate patch-size findings (`large-patch-files`, `large-patch-lines`) describe the whole diff rather than a single file. Under `--since` + a non-empty diff they tag `[introduced]` (the aggregate IS the introduced work); with an empty diff they tag `[cumulative]` (the finding describes drift accumulated across earlier commits).
+
 ### Post-build audit and auto-configure
 
 `fireforge build` is a transactional step: after a successful mach build it audits the dist bundle against engine-relative paths touched since the last successful build, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact or whose dist mtime is older than the source. Ends every build with a `Packaged: N updated, M stale, K missing, S skipped` summary. The audit is warn-only — it never fails a build that mach reported green.
@@ -589,9 +596,9 @@ The two flags can be combined — `--with-tests --xpcshell` writes both harnesse
 
 ### xpcshell appdir auto-injection on rebranded forks
 
-`fireforge test` auto-resolves and injects `--app-path=<absolute>` into the underlying `mach test` invocation when the nearest `xpcshell.toml` sets `firefox-appdir = "browser"` and the active build's `appname` is anything other than `firefox`. Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws `Failed to load resource:///modules/…` 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 on rebranded forks, `appPath` falls back to `xrePath`, and `resource:///` resolves one level above the real app root. The resolver walks each test path to its nearest manifest, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest, 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 skip the resolver silently. Mismatches across multiple test paths and unresolvable manifest values surface as warnings rather than guesses, so triage reaches the underlying cause.
+`fireforge test` auto-resolves and injects `--app-path=<absolute>` into the underlying `mach test` invocation when the nearest `xpcshell.toml` sets `firefox-appdir = "browser"` and the active build's `appname` is anything other than `firefox`. Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws `Failed to load resource:///modules/…` 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 on rebranded forks, `appPath` falls back to `xrePath`, and `resource:///` resolves one level above the real app root. The resolver walks each test path to its nearest manifest, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest, and otherwise probes the platform-appropriate layout for the absolute target: on macOS, `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` is preferred over `<objDir>/dist/bin/<value>` (the `dist/bin` symlink on Darwin points at the binaries directory, not the Resources tree where modules live); on other platforms `dist/bin/<value>` is preferred and the macOS bundle layout is the fallback. Operator overrides via `--mach-arg=--app-path=…` always win and skip the resolver silently. Mismatches across multiple test paths and unresolvable manifest values surface as warnings rather than guesses, so triage reaches the underlying cause.
 
-The durable fix is to add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the manifest — the harness then reads the appname-keyed value directly without auto-injection. The xpcshell appdir hint that fires when the symptom persists despite injection lists this option first.
+The durable fix is to add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the manifest — the harness then reads the appname-keyed value directly without auto-injection. This is the most reliable fix on rebranded macOS builds where mach's xpcshell runner binds `-a` to the `.app/Contents/Resources` default and may not honour `--app-path` overrides. The xpcshell appdir hint that fires when the symptom persists despite injection lists this option first.
 
 ### Smoke-run mode (`fireforge run --smoke-exit`)
 

package/dist/src/commands/doctor.js

@@ -322,7 +322,19 @@ const DOCTOR_CHECKS = [
                 // (only `filesAffected` / ordering drifted) are not flagged.
                 if (repaired.recoveredFilenames.length > 0) {
                     for (const filename of repaired.recoveredFilenames) {
-                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. Edit patches.json to restore the original description if you have it backed up.`);
+                        // 2026-04-24 eval Finding 6: the repair path used to tell the
+                        // operator to hand-edit patches.json, which contradicts the
+                        // README + Hominis docs that treat the manifest as
+                        // FireForge-owned. Point at the existing `re-export` /
+                        // `export` workflow instead so the fix stays inside the tool:
+                        // re-exporting the same files with an explicit `--description`
+                        // overwrites the recovered entry with operator-supplied
+                        // metadata and supersedes the mtime-based createdAt stamp.
+                        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. ` +
+                            'Re-export the affected files with `fireforge re-export <filename> --description "<your description>"` ' +
+                            '(or `fireforge export <paths...> --name <name> --category <category> --description "<your description>"`) ' +
+                            'to overwrite the reconstructed metadata, or accept the generic description if the original text is not recoverable. ' +
+                            'Avoid hand-editing patches.json — FireForge owns that file and will regenerate it on the next manifest consistency pass.');
                     }
                 }
                 return warning('Patch manifest consistency', `Rebuilt patches.json from ${repaired.manifest.patches.length} patch${repaired.manifest.patches.length === 1 ? '' : 'es'}${repaired.recoveredFilenames.length > 0 ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)` : ''}. Review recovered metadata before release.`);

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

@@ -2,13 +2,14 @@
 import { Option } from 'commander';
 import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
+import { collectFurnaceManagedPrefixes, furnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { hasChanges, isGitRepository } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { commitExportedPatch, findAllPatchesForFiles } from '../core/patch-export.js';
 import { buildPatchQueueContext, collectNewFileCreatorsByPath, detectNewFilesInDiff, } from '../core/patch-lint.js';
+import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
 import { GeneralError } from '../errors/base.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
@@ -62,6 +63,62 @@ async function resolveFurnaceExclusionPolicy(paths, projectRoot, excludeFurnace)
         'Review them with "fireforge status" or "fireforge furnace status", ' +
         'or pass --exclude-furnace to export the non-Furnace subset of the diff.');
 }
+/**
+ * Refuses the export when the resulting patch would register furnace
+ * component source files it does not itself carry. 2026-04-24 eval
+ * Finding 1: operators running `export-all --exclude-furnace` after
+ * `furnace create --localized --with-tests` ended up with patches that
+ * added `toolkit/content/widgets/moz-qa-panel/*` via jar.mn /
+ * customElements.js / locale jar.mn but excluded the component source
+ * files themselves. The resulting patch queue was structurally broken
+ * and `fireforge verify` stayed silent. We now detect the condition
+ * pre-write and ask the operator to either include the component
+ * sources (skip `--exclude-furnace`) or revert the furnace changes
+ * before exporting.
+ *
+ * The check runs against the synthesised patch body before
+ * `commitExportedPatch` writes anything, so no broken patch is left on
+ * disk when the refusal fires.
+ */
+async function checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExcluded) {
+    if (furnaceExcluded.size === 0)
+        return;
+    if (!(await furnaceConfigExists(projectRoot)))
+        return;
+    const refs = collectPatchRegistrationReferences(diff);
+    if (refs.length === 0)
+        return;
+    const config = await loadFurnaceConfig(projectRoot);
+    // Build the set of furnace-managed component names so we can tell
+    // "registers moz-qa-panel (furnace-managed)" apart from "registers
+    // moz-button (an upstream widget this patch legitimately touches)".
+    const furnaceComponentNames = new Set([
+        ...Object.keys(config.custom),
+        ...Object.keys(config.overrides),
+        ...config.stock,
+    ]);
+    const dangling = [];
+    for (const ref of refs) {
+        if (!furnaceExcluded.has(ref.targetPath))
+            continue;
+        const tagMatch = /toolkit\/content\/widgets\/([a-z][a-z0-9-]*)\//.exec(ref.targetPath);
+        const ftlMatch = /toolkit\/locales\/en-US\/toolkit\/global\/([a-z][a-z0-9-]*)\.ftl$/.exec(ref.targetPath);
+        const component = tagMatch?.[1] ?? ftlMatch?.[1];
+        if (!component || !furnaceComponentNames.has(component))
+            continue;
+        dangling.push({ component, targetPath: ref.targetPath, source: ref.source });
+    }
+    if (dangling.length === 0)
+        return;
+    const summary = dangling
+        .map((d) => `  • ${d.component} — registered via ${d.source} → ${d.targetPath}`)
+        .join('\n');
+    throw new GeneralError('Export-all --exclude-furnace would produce a patch that registers furnace-managed components without including their source files.\n\n' +
+        `Dangling registrations:\n${summary}\n\n` +
+        'To proceed, either:\n' +
+        '  1. Drop the --exclude-furnace flag so the source files are captured alongside the registration edits.\n' +
+        '  2. Revert the registration hunks (or the whole furnace workflow) before re-running export-all — registrations belong with their components, and splitting them across separate patches is what "verify" catches post-hoc as a dangling-registration error.');
+}
 /**
  * Refuses the export when the aggregate diff would create (new-file-mode) a
  * path that some existing patch in the queue already creates. `verify`
@@ -163,6 +220,11 @@ export async function exportAllCommand(projectRoot, options = {}) {
     // 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);
+    // Dangling-furnace-registration preflight (Finding 1). Runs after the
+    // diff is assembled so we can inspect the exact hunks the operator is
+    // about to land; runs BEFORE any write so a refusal leaves the
+    // patches directory untouched.
+    await checkDanglingFurnaceRegistrations(projectRoot, diff, furnaceExcluded);
     // 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/furnace/create-xpcshell.js

@@ -5,6 +5,7 @@
  * per-file LOC budget and the scaffolder is unit-testable in isolation.
  */
 import { join } from 'node:path';
+import { xpcshellTestParentDir } from '../../core/furnace-constants.js';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getLicenseHeader } from '../../core/license-headers.js';
 import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
@@ -26,8 +27,9 @@ import { generateXpcshellManifestContent, generateXpcshellTestContent, xpcshellT
  * auto-insertion that guessed wrong would be worse than a note.
  */
 export async function scaffoldXpcshellTestFiles(componentName, license, forgeConfig, paths, journal) {
-    const parentDirName = `${forgeConfig.binaryName}-xpcshell`;
-    const testDir = join(paths.engine, 'browser/base/content/test', parentDirName, componentName);
+    const parentRelDir = xpcshellTestParentDir(forgeConfig.binaryName);
+    const parentDirName = parentRelDir.split('/').slice(-1)[0] ?? `${forgeConfig.binaryName}-xpcshell`;
+    const testDir = join(paths.engine, parentRelDir, componentName);
     if (journal && !(await pathExists(testDir))) {
         recordCreatedDir(journal, testDir);
     }

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

@@ -163,6 +163,38 @@ async function assertPreviewPrerequisites(engineDir) {
             'Run "fireforge bootstrap" (or the underlying `mach bootstrap` in the engine) to populate the toolchain config, then rerun "fireforge furnace preview".');
     }
 }
+/**
+ * Emits a framing banner when the Storybook workspace has not yet had
+ * its npm dependencies installed. `mach storybook` will drive the
+ * install internally and print ELSPROBLEMS / UNMET DEPENDENCY lines
+ * verbatim; without this banner operators reliably read the npm output
+ * as a failure (2026-04-24 eval Finding 13).
+ *
+ * Skipped when `--install` was explicitly requested — that path already
+ * runs `mach storybook upgrade` before the preview launches, so the npm
+ * output for the subsequent `mach storybook` invocation is a no-op.
+ */
+async function announceStorybookFirstRunIfNeeded(engineDir, installRequested) {
+    if (installRequested)
+        return;
+    const storybookNodeModules = join(engineDir, 'browser', 'components', 'storybook', 'node_modules');
+    const storybookDepsMissing = !(await pathExists(storybookNodeModules));
+    if (!storybookDepsMissing)
+        return;
+    info('Storybook workspace dependencies are not yet installed. The next step will install ~1000 npm packages via `mach storybook`; expect npm error-style output below. This is a one-time first-run cost — Storybook will start once the install finishes.');
+}
+/**
+ * Surfaces an explicit success banner after a clean mach-storybook
+ * exit so the operator's scrollback visually terminates the npm noise
+ * from the first-run install. Only fires on expected exit codes — non-
+ * zero cases fall through to the existing
+ * `buildStorybookFailureMessage` classification.
+ */
+function announceStorybookCleanExitIfApplicable(exitCode) {
+    if (exitCode === 0 || exitCode === 130 || exitCode === 143) {
+        info('Storybook stopped cleanly.');
+    }
+}
 /**
  * Runs the furnace preview command to start Storybook for component preview.
  * @param projectRoot - Root directory of the project
@@ -269,10 +301,16 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
                 }
                 installSpinner.stop('Storybook dependencies reinstalled');
             }
+            // 2026-04-24 eval Finding 13: frame the npm noise that `mach
+            // storybook` emits on first-run as expected progress rather than a
+            // failure. The banner-before / banner-after helpers are extracted
+            // so the command body stays under the per-function LOC budget.
+            await announceStorybookFirstRunIfNeeded(paths.engine, options.install ?? false);
             // Start Storybook
             info('Starting Storybook...');
             info('Press Ctrl+C to stop\n');
             previewResult = await runMachCapture(['storybook'], paths.engine);
+            announceStorybookCleanExitIfApplicable(previewResult.exitCode);
         }
         catch (error) {
             primaryError = error;

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

@@ -6,7 +6,7 @@ import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { removeCustomFtlJarMnEntry } from '../../core/furnace-apply-ftl.js';
 import { extractComponentChecksums, getOverrideEngineTargetPath, isOverrideCopyCandidate, restoreOverrideFileToBaseline, } from '../../core/furnace-apply-helpers.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { resolveFtlDir } from '../../core/furnace-constants.js';
+import { resolveFtlDir, xpcshellTestParentDir } from '../../core/furnace-constants.js';
 import { recordFurnaceRollbackFailure, runFurnaceMutation } from '../../core/furnace-operation.js';
 import { removeCustomElementRegistration, removeJarMnEntries, } from '../../core/furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -212,6 +212,64 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
     }
     return { partialFailures };
 }
+/**
+ * Removes generated xpcshell test scaffolds associated with a custom
+ * component. 2026-04-24 eval Finding 5: `furnace remove` handled
+ * browser mochitests via `cleanupCustomTestFiles` but never touched the
+ * xpcshell scaffold tree, so an operator who ran
+ * `furnace create --with-tests --xpcshell` followed by `furnace remove`
+ * was left with orphan `xpcshell.toml` + `test_<name>_packaged.js`
+ * files still referencing the removed component. This cleanup pass
+ * mirrors the mochitest one — snapshot before removal, warn-and-
+ * continue semantics, explicit summary when partial failures occur.
+ */
+async function cleanupCustomXpcshellTestFiles(name, projectRoot, journal) {
+    const partialFailures = [];
+    let forgeConfig;
+    try {
+        forgeConfig = await loadConfig(projectRoot);
+    }
+    catch (error) {
+        const msg = `Could not load config for xpcshell test cleanup — ${toError(error).message}. Remove xpcshell test files manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+        return { partialFailures };
+    }
+    const paths = getProjectPaths(projectRoot);
+    const xpcshellRoot = join(paths.engine, xpcshellTestParentDir(forgeConfig.binaryName));
+    const componentXpcshellDir = join(xpcshellRoot, name);
+    if (!(await pathExists(componentXpcshellDir)))
+        return { partialFailures };
+    try {
+        await snapshotDir(journal, componentXpcshellDir);
+        await removeDir(componentXpcshellDir);
+        info(`Deleted xpcshell test scaffold directory: ${componentXpcshellDir.replace(paths.engine + '/', 'engine/')}`);
+    }
+    catch (error) {
+        const msg = `Could not delete xpcshell test scaffold — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    // If the xpcshell parent directory is now empty (no other components
+    // had scaffolds), drop it too so `furnace validate` stays quiet about
+    // the empty per-binary tree. Warn-and-continue on any failure.
+    try {
+        if (await pathExists(xpcshellRoot)) {
+            const remaining = await readdir(xpcshellRoot);
+            if (remaining.length === 0) {
+                await snapshotDir(journal, xpcshellRoot);
+                await removeDir(xpcshellRoot);
+                info(`Deleted empty xpcshell parent directory: ${xpcshellRoot.replace(paths.engine + '/', 'engine/')}`);
+            }
+        }
+    }
+    catch (error) {
+        const msg = `Could not clean up xpcshell parent directory — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    return { partialFailures };
+}
 function dropChecksumsByPrefix(state, prefix) {
     const result = { ...state };
     if (state.appliedChecksums) {
@@ -367,6 +425,14 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
             if (type === 'custom') {
                 const result = await cleanupCustomTestFiles(name, projectRoot, journal);
                 testCleanupFailures = result.partialFailures;
+                // 2026-04-24 eval Finding 5: also clean up xpcshell scaffolds
+                // generated by `furnace create --with-tests --xpcshell`. The
+                // mochitest cleanup above covers `browser/base/content/test/
+                // <binary>/`, but xpcshell scaffolds live in the sibling
+                // `<binary>-xpcshell/` directory and were orphaned by prior
+                // versions.
+                const xpcshellResult = await cleanupCustomXpcshellTestFiles(name, projectRoot, journal);
+                testCleanupFailures.push(...xpcshellResult.partialFailures);
             }
             // Remove entry from furnace.json
             if (type === 'stock') {

package/dist/src/commands/furnace/rename-xpcshell.d.ts

@@ -0,0 +1,35 @@
+/**
+ * xpcshell scaffold rename helper extracted from `rename.ts`.
+ *
+ * 2026-04-24 eval Finding 5: `furnace create --with-tests --xpcshell`
+ * writes a scaffold at `browser/base/content/test/<binary>-xpcshell/
+ * <name>/` and `furnace rename` did not update it. The helper below
+ * renames the directory, updates the test filename, rewrites the
+ * `xpcshell.toml` section header, and re-writes the test body so word-
+ * boundary occurrences of the old tag / underscored name map to the new
+ * ones.
+ *
+ * Extracted to keep `rename.ts` under the per-file LOC budget —
+ * `rename.ts` already carries mochikit + browser-mochitest + FTL
+ * handling, and tacking xpcshell onto that tree pushed the file past
+ * the limit.
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+/**
+ * Renames an xpcshell test scaffold in place. Moves the directory,
+ * rewrites the test filename, updates the `[test_name]` section header
+ * in `xpcshell.toml`, and word-boundary-rewrites occurrences of the
+ * old tag / old underscored name inside the test body.
+ *
+ * Best-effort: any failure logs a warning through the shared logger
+ * but never throws — the component rename itself has already succeeded
+ * at this point, and blocking on a test rewrite would leave the
+ * operator with a half-renamed component.
+ *
+ * @param engineDir - Absolute path to the engine directory under the project.
+ * @param projectRoot - Absolute path to the project root, used to load the binary name.
+ * @param oldName - Pre-rename component tag name.
+ * @param newName - Post-rename component tag name.
+ * @param journal - Rollback journal that the rename mutation writes to before touching files.
+ */
+export declare function renameXpcshellTestFiles(engineDir: string, projectRoot: string, oldName: string, newName: string, journal: RollbackJournal): Promise<void>;

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

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * xpcshell scaffold rename helper extracted from `rename.ts`.
+ *
+ * 2026-04-24 eval Finding 5: `furnace create --with-tests --xpcshell`
+ * writes a scaffold at `browser/base/content/test/<binary>-xpcshell/
+ * <name>/` and `furnace rename` did not update it. The helper below
+ * renames the directory, updates the test filename, rewrites the
+ * `xpcshell.toml` section header, and re-writes the test body so word-
+ * boundary occurrences of the old tag / underscored name map to the new
+ * ones.
+ *
+ * Extracted to keep `rename.ts` under the per-file LOC budget —
+ * `rename.ts` already carries mochikit + browser-mochitest + FTL
+ * handling, and tacking xpcshell onto that tree pushed the file past
+ * the limit.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadConfig } from '../../core/config.js';
+import { xpcshellTestParentDir } from '../../core/furnace-constants.js';
+import { snapshotFile } from '../../core/furnace-rollback.js';
+import { toError } from '../../utils/errors.js';
+import { ensureDir, pathExists, readText, removeDir, removeFile, writeText, } from '../../utils/fs.js';
+import { info, warn } from '../../utils/logger.js';
+/** Escapes regex metacharacters so a user-supplied name stays literal. */
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Renames an xpcshell test scaffold in place. Moves the directory,
+ * rewrites the test filename, updates the `[test_name]` section header
+ * in `xpcshell.toml`, and word-boundary-rewrites occurrences of the
+ * old tag / old underscored name inside the test body.
+ *
+ * Best-effort: any failure logs a warning through the shared logger
+ * but never throws — the component rename itself has already succeeded
+ * at this point, and blocking on a test rewrite would leave the
+ * operator with a half-renamed component.
+ *
+ * @param engineDir - Absolute path to the engine directory under the project.
+ * @param projectRoot - Absolute path to the project root, used to load the binary name.
+ * @param oldName - Pre-rename component tag name.
+ * @param newName - Post-rename component tag name.
+ * @param journal - Rollback journal that the rename mutation writes to before touching files.
+ */
+export async function renameXpcshellTestFiles(engineDir, projectRoot, oldName, newName, journal) {
+    let forgeConfig;
+    try {
+        forgeConfig = await loadConfig(projectRoot);
+    }
+    catch {
+        return; // Cannot determine scaffold path without config.
+    }
+    const parentDir = join(engineDir, xpcshellTestParentDir(forgeConfig.binaryName));
+    if (!(await pathExists(parentDir)))
+        return;
+    const oldScaffoldDir = join(parentDir, oldName);
+    const newScaffoldDir = join(parentDir, newName);
+    if (!(await pathExists(oldScaffoldDir)))
+        return;
+    const oldUnderscored = oldName.replace(/-/g, '_');
+    const newUnderscored = newName.replace(/-/g, '_');
+    const oldTestFileName = `test_${oldUnderscored}_packaged.js`;
+    const newTestFileName = `test_${newUnderscored}_packaged.js`;
+    try {
+        await ensureDir(newScaffoldDir);
+        const entries = await readdir(oldScaffoldDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const oldFilePath = join(oldScaffoldDir, entry.name);
+            const renamedFileName = entry.name === oldTestFileName ? newTestFileName : entry.name;
+            const newFilePath = join(newScaffoldDir, renamedFileName);
+            await snapshotFile(journal, oldFilePath);
+            const body = await readText(oldFilePath);
+            let updated = body;
+            if (entry.name === 'xpcshell.toml') {
+                updated = updated.replace(new RegExp(`\\[${escapeRegex(`"${oldTestFileName}"`)}\\]`, 'g'), `["${newTestFileName}"]`);
+            }
+            else if (entry.name === oldTestFileName) {
+                const oldTagPattern = new RegExp(`(?<![\\w-])${escapeRegex(oldName)}(?![\\w-])`, 'g');
+                updated = updated.replace(oldTagPattern, newName);
+                const oldUnderscoredPattern = new RegExp(`(?<![\\w])${escapeRegex(oldUnderscored)}(?![\\w])`, 'g');
+                updated = updated.replace(oldUnderscoredPattern, newUnderscored);
+            }
+            await writeText(newFilePath, updated);
+            await removeFile(oldFilePath);
+        }
+        await removeDir(oldScaffoldDir);
+        info(`Renamed xpcshell scaffold directory: ${xpcshellTestParentDir(forgeConfig.binaryName)}/${oldName} → ${xpcshellTestParentDir(forgeConfig.binaryName)}/${newName}`);
+    }
+    catch (error) {
+        warn(`Could not rename xpcshell scaffold — ${toError(error).message}. Rename the scaffold files manually if needed.`);
+    }
+}
+//# sourceMappingURL=rename-xpcshell.js.map

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

@@ -14,6 +14,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeDir, removeFile, writeText, } from '../../utils/fs.js';
 import { info, intro, note, outro, warn } from '../../utils/logger.js';
+import { renameXpcshellTestFiles } from './rename-xpcshell.js';
 /** Escapes regex metacharacters so a user-supplied name is literal inside a RegExp. */
 function escapeRegex(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -299,6 +300,14 @@ async function performRenameMutations(args) {
                 // either failed the test run outright or (worse) passed for the
                 // wrong component.
                 await renameMochikitTestFiles(args.engineDir, oldName, newName, journal);
+                // 2026-04-24 eval Finding 5: xpcshell scaffolds live in yet
+                // another tree (`browser/base/content/test/<binary>-xpcshell/
+                // <name>/`). Before this call, renaming a component scaffolded
+                // with `--with-tests --xpcshell` left a directory whose name
+                // still referenced the pre-rename component, plus a test file
+                // whose underscored name referenced the old tag — both of
+                // which then failed to match the new component.
+                await renameXpcshellTestFiles(args.engineDir, projectRoot, oldName, newName, journal);
                 // Clear the stale deployed component directory so the next
                 // `furnace apply` is the single writer of the new name's
                 // deployment. Without this, eval runs showed the old widget