@hominis/fireforge 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 0.11.0
+
+### New commands
+
+- **`fireforge verify`** — read-only integrity check for the patch queue. Reports duplicate file creations across patches, forward imports, orphaned patch files, and manifest inconsistencies. Exits non-zero on any error, making it usable as a CI pre-flight gate.
+- **`fireforge patch delete <name>`** — removes a patch file and its manifest entry atomically. Refuses when a later patch imports from a file the deleted patch owns (bypassable with `--force-unsafe`).
+- **`fireforge patch reorder <name> --to <N> | --before <anchor> | --after <anchor>`** — moves a patch to a new position, renumbers surrounding patches, and runs cross-patch lint against the projected order before writing.
+
+### New flags and options
+
+- `fireforge export --dry-run` previews the full export plan (filename, metadata, affected files) without writing. With `--supersede`, shows which existing patches would be absorbed and why.
+- `fireforge export --order <N> | --before <anchor> | --after <anchor>` places a new patch at a specific position and shifts subsequent patches up.
+- `fireforge re-export --files <paths> <patch>` restricts a re-export to an explicit file subset, useful for splitting or shrinking a patch's scope.
+- `fireforge import --until <patch>` (alias `--stop-at`) applies patches only up to the named patch, useful for bisection.
+- `fireforge status --ownership` prints a flat table mapping every managed path to its owning patch and flags ownership conflicts.
+- `fireforge furnace apply --force` and `furnace deploy --force` proceed despite `baseVersion` drift between `furnace.json` and the Firefox version.
+- `fireforge furnace deploy --skip-validate` skips the validation suite during deploy.
+- `fireforge furnace override` now accepts multiple tag names in a single invocation for batch creation.
+- `fireforge import --dry-run` previews which patches would be applied, in order, without modifying the engine.
+- `fireforge status --json` outputs classified file status as machine-readable JSON for CI scripting.
+
+### Furnace improvements
+
+- **`furnace refresh <name>`** merges upstream Firefox changes into an override workspace via three-way merge. Clean merges update `baseVersion` automatically; conflicts leave standard markers for manual resolution. Supports `--dry-run` and `--reset-base` (skip merge, just update the baseline).
+- **Full overrides now include shared Fluent files.** Localized widgets (those with a `.ftl` file) are now copied, applied, removed, and diffed end-to-end instead of silently dropping the locale payload.
+- **`furnace diff` rewritten with proper multi-hunk output.** Scattered edits across a file now render as separate hunks with context lines instead of one giant block.
+- **`furnace apply` detects and undeploys deleted workspace files.** If you remove a file from a component's workspace directory and re-run apply, the corresponding engine copy is cleaned up and registrations are adjusted.
+- **`furnace status` now distinguishes workspace edits from engine drift.** These have different remediation paths and are reported separately instead of collapsed into one message.
+- **`furnace scan` offers to override just-added stock components** in the same interactive session.
+- **Preview stages workspace files into the engine** before launching Storybook so fresh edits actually appear, then rolls them back on teardown.
+- **FTL base path is now configurable** via `ftlBasePath` in `furnace.json` for projects with non-standard locale paths.
+- **`scanPaths` in `furnace.json`** lets `furnace scan` discover components outside the default `toolkit/content/widgets`.
+- File copies during apply are now parallelized within each component.
+
+### New lint rules
+
+- **`duplicate-new-file-creation`** (error) — flags any path that appears as a new-file creation in more than one patch.
+- **`forward-import`** (error) — flags imports that reference a file owned by a later-ordered patch. Supports an inline suppression marker (`// fireforge-ignore: forward-import`) for false positives from basename collisions.
+
+### Doctor and diagnostics
+
+- `fireforge doctor` now runs the full Furnace component validation suite (structure, accessibility, compatibility, registration) and reports issues without needing a separate `furnace validate` run.
+- New `--repair-furnace` flag reconciles the engine when a furnace operation was interrupted or left inconsistent state.
+- `fireforge doctor` checks that Firefox-internal paths Furnace depends on still exist and reports targeted warnings when they are missing.
+- `furnace validate` now enforces `.ftl` presence for `localized: true` custom components and no longer false-warns about missing CSS jar entries when the component has no CSS file.
+
+### Reliability
+
+- All furnace mutations now serialize on a project-wide lock, preventing concurrent operations from racing on engine state.
+- Ctrl+C and SIGTERM trigger clean rollback across all furnace commands. A `pendingRepair` marker is only written when rollback was actually incomplete, so normal interrupts do not leave false-positive repair flags.
+- Override `baseVersion` drift now blocks `apply` and `deploy` by default instead of warning and continuing. Pass `--force` to override, or use `furnace refresh` to update the baseline.
+- Post-apply consistency check verifies that `customElements.js` and `jar.mn` entries match what was deployed.
+- Engine-side content hashes are cached in the furnace state file, making drift detection faster for the common no-change case.
+- `build` and `test --build` now share the same preparation pipeline including Furnace apply, so incremental test builds no longer run against stale component state.
+- `furnace remove` on an override now restores every overridden engine file to its Firefox baseline instead of leaving deployed files behind.
+- Scanner results are cached by content hash within a process, avoiding redundant parsing during scan-status-apply sequences.
+- `download` and `build` now check available disk space before starting and warn when free space is low (Firefox source ~5 GB, full build ~20 GB).
+- `getProjectRoot()` now throws instead of silent fallback.
+- `getPackageRoot()` caches its result after the first call, avoiding repeated filesystem walks.
+- Process spawn timeout is now enforced via `AbortSignal.timeout()` instead of the unreliable `timeout` option on `child_process.spawn()`.
+
+### Bug fixes
+
+- `furnace refresh` now correctly advances the per-override `baseCommit` to the engine HEAD after a successful merge, preventing phantom conflicts on subsequent refreshes.
+- `furnace rename` uses the correct file-removal function for FTL files.
+- `furnace remove` now parses browser.toml sections properly, cleaning up metadata keys below the section header instead of leaving stale fragments.
+- Registration duplicate detection now uses exact path matching so `moz-card` no longer collides with `moz-card-group`.
+- The `customElements.js` parser now accepts `const` and `var` loop declarations alongside `let`.
+- `re-export --files` refuses to write when a requested path would produce no hunks, preventing manifest/patch-body desynchronisation.
+- `patch delete` now respects the `fireforge-ignore: forward-import` suppression marker, matching the behavior of `verify` and `lint`.
+- Furnace apply no longer reports "up to date" after `reset --yes` or `download --force` wiped the engine. Both commands now clear the furnace state, and the skip logic checks engine-side drift before trusting cached checksums.
+- `status` now classifies Furnace-managed engine paths as `furnace` instead of `unmanaged`, and `export-all` refuses to capture them.
+- AST parser fallback in the scanner now emits a warning instead of failing silently.
+- `stock` entries in `furnace.json` are validated against a safe character set, rejecting path-traversal strings.
+
+### Internal
+
+- CLI command registration is now driven by a declarative manifest instead of hand-listed calls.
+- Doctor checks are a declarative registry with per-check `run`, `skipIf`, and `fix` fields.
+- New shared destructive-op framework handles confirmation, `--dry-run`, `--yes`/`--force-unsafe`, and audit logging for the patch mutation commands.
+- Export internals factored into `planExport` / `executeExportPlan` so dry-run and real writes share one code path.
+- Ownership table builder extracted from `status.ts` into `src/core/ownership-table.ts`.
+- Cross-patch lint regression calculator extracted from `re-export.ts` into `src/core/lint-projection.ts`.
+- The `re-export --files` path extracted into `src/commands/re-export-files.ts` to keep `re-export.ts` under the line limit.
+- `max-lines` and `max-lines-per-function` ESLint rules promoted from `warn` to `error`.
+- Doctor check ordering dependencies documented in the registry comment.
+- Default Firefox version bumped to ESR 146.
+
+### Packaging
+
+- Package metadata and lockfile updated to 0.11.0.
+
 ## 0.10.0
 
 ### Patch workflow validation
@@ -22,7 +114,7 @@
 
 ### Packaging
 
-- Package metadata and smoke tests now use version `0.10.0`.
+- Package metadata and smoke tests now use version 0.10.0.
 - npm install instructions use the scoped `@hominis/fireforge` package name.
 - Packaging and full Firefox integration helpers now handle platform-specific npm and mozconfig names more consistently.
 

package/README.md

@@ -6,16 +6,39 @@
 [![types](https://img.shields.io/npm/types/@hominis/fireforge)](https://www.npmjs.com/package/@hominis/fireforge)
 [![npm downloads](https://img.shields.io/npm/dm/@hominis/fireforge)](https://www.npmjs.com/package/@hominis/fireforge)
 
-**Build and maintain your own Firefox-based browser with a patch-first workflow.**
+**Build and maintain your own Firefox-based browser with a patch-first workflow**
 
-FireForge gives you a toolkit for forking Firefox: download a specific ESR release, manage your customisations as an ordered stack of contextual patches, survive version upgrades with semi-automated rebase, wire custom code into Mozilla's startup paths, and build the result. It also ships **Furnace**, a component system for creating and overriding Firefox custom elements.
+FireForge gives you a toolkit for forking Firefox: download a specific ESR release, manage your customisations as a series of patches, survive version upgrades with semi-automated rebase, wire custom code into Mozilla's startup paths, and build the result. It also ships **Furnace**, a component system for creating and overriding Firefox custom elements under `toolkit/content/widgets`.
 
-Inspired by [fern.js](https://github.com/nicktrosper/user-agent-desktop?tab=readme-ov-file#user-agent-desktop) and [Melon](https://github.com/nicktrosper/nicktrosper-melon).
+Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon](https://github.com/dothq/melon).
 
----
+## Features
+
+- **Patch-based fork management** Your customisations live as portable, ordered `.patch` files. Export single files, multiple paths, or everything at once. Contextual diffs mean upstream security fixes are not silently dropped when you rebase.
+
+- **Semi-automated ESR rebase** `fireforge rebase` replays your patch stack onto new Firefox source with escalating fuzz matching. When a patch fails, you fix it manually and `--continue`. The full stack gets re-exported with updated version stamps.
+
+- **Wiring and registration** `fireforge wire` and `fireforge register` inject your code into Mozilla's startup paths, build manifests, and JAR files with a single command. The injection is AST-based (via Acorn), so it survives formatting changes applied between versions.
+
+- **Furnace component system** Override existing Firefox custom elements or create new ones under `toolkit/content/widgets` (CSS-only restyles, full behavioural forks, or entirely new widgets).
+
+- **Design token management** Track CSS custom property coverage across your modified files.
+
+- **Quality checks** `fireforge lint` catches fork-specific issues (raw colours, missing licence headers, relative imports, large patches, cross-patch ordering problems) before you export. `fireforge verify` runs a read-only integrity check over the whole patch queue. `fireforge doctor` diagnoses project health including Furnace component validation.
+
+- **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced, and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Full end-to-end runs are currently only run locally, as they require about 30 GB of disk and significant compute for the full build.
 
 ## Quick Start
 
+### Requirements
+
+- **Node.js 20+**
+- **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.
+
+### Setup
+
 ```bash
 mkdir mybrowser && cd mybrowser
 npm init -y
@@ -31,11 +54,7 @@ npx fireforge run                 # launch it
 
 Your project now has `fireforge.json`, an `engine/` directory with Firefox source, and a `patches/` directory ready for your first customisation.
 
-A few things worth noting here: `bootstrap` may prompt for elevated permissions depending on your platform and what build dependencies are already present. This is not something we can avoid, since Mozilla's own `mach bootstrap` requires it, and wrapping that in our own sudo logic would be worse in every way that matters.
-
----
-
-## Core Workflow
+### Workflow Overview
 
 ```bash
 # 1. Make changes inside engine/
@@ -49,45 +68,14 @@ npx fireforge export browser/base/content/browser.js \
 #    with metadata tracked in patches/patches.json
 
 # 4. Later, reset and replay to verify everything applies cleanly
-npx fireforge reset --force
-npx fireforge import
+npx fireforge reset --yes
+npx fireforge import              # --dry-run to preview without applying
 
 # 5. When Firefox releases a new ESR, update fireforge.json, re-download, and rebase
 npx fireforge download --force
 npx fireforge rebase
 ```
 
-The reason your customisations live as patches rather than as a permanent fork branch is, in fairness, a trade-off. Branches are more familiar, but they make upstream merges progressively harder as your changes grow, and they obscure which modifications are intentional versus which are artefacts of merge resolution. Patches are explicit. Each one is a discrete, portable unit of intent. The cost is that you need tooling to manage the stack, which is what FireForge exists to provide.
-
----
-
-## What You Get
-
-- **Patch-based fork management.** Your customisations live as portable, ordered `.patch` files. Export single files, multiple paths, or everything at once. Contextual diffs mean upstream security fixes are not silently dropped when you rebase. This matters more then it might seem at first, because silent patch drift in a browser fork is the sort of bug that only surfaces when someone audits your security posture six months later.
-
-- **Semi-automated ESR rebase.** `fireforge rebase` replays your patch stack onto new Firefox source with escalating fuzz matching. When a patch fails, you fix it manually and `--continue`. The full stack gets re-exported with updated version stamps. It would be cleaner to make this fully automatic, of course, but patches that touch the same code as upstream changes genuinely require human judgement about which intent should win. Pretending otherwise would be worse.
-
-- **Wiring and registration.** `fireforge wire` and `fireforge register` inject your code into Mozilla's startup paths, build manifests, and JAR files with a single command. The injection is AST-based (via Acorn), not regex-based, which means it survives the formatting changes that Mozilla applies between versions. This is less about elegance then about not breaking on every minor release.
-
-- **Furnace component system.** Override existing Firefox custom elements (CSS-only or full fork) or create new ones. Storybook preview included. The component types are `stock` (tracked for preview, no local files), `override` (CSS-only restyle or full behavioural fork), and `custom` (entirely new elements).
-
-- **Design token management.** Track CSS custom property coverage across your modified files. This exists because raw colour values in a browser fork become a maintenance problem faster then you would expect, and catching them at export time is considerably cheaper then catching them during a visual regression review.
-
-- **Quality checks.** `fireforge lint` catches fork-specific issues (raw colours, missing licence headers, relative imports, large patches) before you export. `fireforge doctor` diagnoses project health. These are not redundant with Mozilla's own `./mach lint`, which does not know about your fork-specific conventions.
-
-- **Tested against real Firefox source.** We run end-to-end test passes against actual Firefox ESR 140 source code as part of development. The in-repo test suite is derived from those real-world runs, reflecting actual developer scenarios (multi-file patches, conflict resolution, manifest recovery, binary assets) without requiring 30 GB of Firefox source to execute. 1400+ tests run in under 15 seconds.
-
----
-
-## Requirements
-
-- **Node.js 20+.** Version 18 will appear to work initially, but the native fetch usage in the request layer will fail silently in certain edge cases, which is the sort of thing you would rather discover now.
-- **Python 3** (required by Firefox's `mach` build system).
-- **Git.**
-- Platform build tools: Xcode on macOS, `build-essential` on Linux, Visual Studio on Windows. If you are on an M-series Mac and encounter native module compilation errors, this is almost certainly the `sharp` dependency in your broader toolchain, not FireForge itself.
-
----
-
 ## Patch Workflow
 
 Patches live in `patches/`, applied by numeric filename prefix, and tracked in `patches/patches.json`:
@@ -102,7 +90,26 @@ patches/
 
 **Categories:** `branding` | `ui` | `privacy` | `security` | `infra`
 
-The category system is intentionally coarse. Finer-grained categorisation sounds appealing in theory, but in practice it creates more classification arguments then it resolves, and the numeric ordering already handles sequencing.
+The category system is intentionally broad. The numeric ordering provides sequencing.
+
+### Importing patches
+
+```bash
+# Apply all patches from patches/ to the engine
+fireforge import
+
+# Preview what would be applied without modifying the engine
+fireforge import --dry-run
+
+# Apply patches up to (and including) a specific one
+fireforge import --until 003-ui-sidebar-tweaks.patch
+
+# Keep going if a patch fails instead of stopping
+fireforge import --continue
+
+# Force-apply even when the engine has drifted or has unmanaged changes
+fireforge import --force
+```
 
 ### Exporting changes
 
@@ -119,9 +126,19 @@ fireforge export-all --name "all-changes" --category ui
 
 # Regenerate patches after further edits
 fireforge re-export --all --scan
+
+# Preview what an export would do without writing
+fireforge export browser/base/content/browser.js --dry-run
+
+# Insert a new patch at a specific position
+fireforge export browser/base/content/browser.js --order 3 --name "inserted" --category ui
+fireforge export browser/base/content/browser.js --before 005-ui-sidebar.patch --name "prelim"
+
+# Restrict a re-export to a specific file subset
+fireforge re-export --files browser/base/content/browser.js 002-ui-toolbar
 ```
 
-### Rebasing onto a new Firefox version
+### Rebasing on top of a new Firefox version
 
 1. Update `firefox.version` in `fireforge.json`
 2. `fireforge download --force`
@@ -129,8 +146,6 @@ fireforge re-export --all --scan
 4. Fix any rejects, then `fireforge rebase --continue`
 5. If stuck, `fireforge rebase --abort` to restore the pre-rebase state
 
-Mind you, the rebase process is deliberately conservative: it will stop at the first patch that cannot be applied cleanly rather then guessing at a resolution and potentially corrupting your intent. This is slower but considerably safer, especially for security-sensitive patches where a misapplied hunk could silently undo a fix.
-
 ### Resolving conflicts
 
 When `fireforge import` fails on a patch, fix the `.rej` files in `engine/`, then:
@@ -157,40 +172,64 @@ This re-exports the fixed patch and continues applying the remaining stack.
       "name": "custom-logo",
       "description": "Replaces default Firefox branding with custom logo",
       "createdAt": "2025-01-15T10:30:00Z",
-      "sourceEsrVersion": "140.0esr",
+      "sourceEsrVersion": "146.0esr",
       "filesAffected": ["browser/branding/official/logo.png"]
     }
   ]
 }
 ```
 
-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. The rebuild is deterministic: it reads patch headers, not cached state, so the result is always consistent with what is actually on the filesystem.
+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>
 
 <details>
 <summary>Patch lint checks</summary>
 
-`fireforge lint` runs automatically during export, export-all, and re-export. Use `--skip-lint` to downgrade errors to warnings, though I would recommend against making that a habit.
+`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.
+
+| Check                          | Scope                                 | Severity |
+| ------------------------------ | ------------------------------------- | -------- |
+| `missing-license-header`       | New files (JS/CSS/FTL)                | error    |
+| `relative-import`              | JS/MJS files                          | error    |
+| `token-prefix-violation`       | CSS files (with furnace)              | error    |
+| `raw-color-value`              | Introduced CSS color values           | error    |
+| `duplicate-new-file-creation`  | Same path created by multiple patches | error    |
+| `forward-import`               | Patch imports from a later-patch file | error    |
+| `missing-modification-comment` | Modified upstream JS/MJS              | warning  |
+| `file-too-large`               | New files >650 lines                  | warning  |
+| `missing-jsdoc`                | Exports in new `.sys.mjs`             | warning  |
+| `observer-topic-naming`        | Observer topics with binaryName       | warning  |
+| `large-patch-files`            | Patches affecting >5 files            | warning  |
+| `large-patch-lines`            | Patches >300 lines                    | warning  |
+
+The two cross-patch rules (`duplicate-new-file-creation` and `forward-import`) run over the whole patch queue rather than a single diff, catching ordering issues that only surface during `import`. Forward-import detection compares leaf filenames, so a false positive is theoretically possible when two patches create files with the same basename in different directories. Suppress with an inline `// fireforge-ignore: forward-import` comment on or above the import line. This is currently the only lint rule that supports inline suppression.
 
-| Check                          | Scope                           | Severity |
-| ------------------------------ | ------------------------------- | -------- |
-| `missing-license-header`       | New files (JS/CSS/FTL)          | error    |
-| `relative-import`              | JS/MJS files                    | error    |
-| `token-prefix-violation`       | CSS files (with furnace)        | error    |
-| `raw-color-value`              | Introduced CSS color values     | error    |
-| `missing-modification-comment` | Modified upstream JS/MJS        | warning  |
-| `file-too-large`               | New files >650 lines            | warning  |
-| `missing-jsdoc`                | Exports in new `.sys.mjs`       | warning  |
-| `observer-topic-naming`        | Observer topics with binaryName | warning  |
-| `large-patch-files`            | Patches affecting >5 files      | warning  |
-| `large-patch-lines`            | Patches >300 lines              | warning  |
+</details>
 
-These catch fork-specific issues that Mozilla's `./mach lint` does not cover. The severity levels are not arbitrary: errors block export because they indicate structural problems that will cause failures downstream, while warnings flag things that are suboptimal but not immediately dangerous.
+### Repairing a broken patch queue
 
-</details>
+When a patch queue drifts — overlapping new-file creations, forward imports, manifest desync — start with diagnosis:
+
+```bash
+fireforge verify                    # fsck: manifest + cross-patch lint
+fireforge lint                      # includes the same cross-patch rules
+fireforge status --ownership        # flat path → owning patch table
+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>`                            |
+| 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`                       |
+
+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` — it is owned by FireForge.
 
 ## Wiring Custom Code
 
@@ -229,81 +268,28 @@ fireforge register browser/modules/mybrowser/MyStore.sys.mjs
 
 </details>
 
----
-
-## Furnace (Component System)
-
-```bash
-fireforge furnace scan                              # discover available components
-fireforge furnace override moz-button -t css-only   # fork an existing one
-fireforge furnace create moz-my-widget              # create a new one
-fireforge furnace deploy --dry-run                   # preview
-fireforge furnace deploy                             # apply + validate
-```
-
-Furnace manages Firefox custom elements (`MozLitElement`). Override stock components with CSS-only restyles or full forks, or scaffold entirely new ones. Changes are applied to `engine/` and then captured by the patch system, which means Furnace is not a separate persistence layer; it feeds into the same patch workflow as everything else.
-
-<details>
-<summary>Component types</summary>
-
-| Type         | Description                                                       | Local files                    |
-| ------------ | ----------------------------------------------------------------- | ------------------------------ |
-| **Stock**    | Engine components tracked for Storybook preview                   | None                           |
-| **Override** | Forked copies: `css-only` (restyle) or `full` (behaviour + style) | `components/overrides/<name>/` |
-| **Custom**   | New elements that do not exist in Firefox                         | `components/custom/<name>/`    |
+## Furnace (UI Component System)
 
-</details>
+Furnace manages Firefox custom elements (`MozLitElement`) under `toolkit/content/widgets`. You can override existing components or create new ones. Changes feed into the same patch workflow as everything else — Furnace is not a separate persistence layer.
 
-<details>
-<summary>Validation checks</summary>
-
-Furnace validates components on deploy. Errors block apply; warnings are advisory. The distinction is not about severity in the abstract but about whether a violation will cause a runtime failure versus a maintenance headache.
-
-| Check                    | Severity | Description                                 |
-| ------------------------ | -------- | ------------------------------------------- |
-| `missing-mjs`            | error    | Custom component missing `.mjs` file        |
-| `missing-css`            | warning  | No `.css` file                              |
-| `filename-mismatch`      | error    | File name does not match tag name           |
-| `missing-override-json`  | error    | Override missing `override.json`            |
-| `no-aria-role`           | warning  | Generic interactive markup lacks semantics  |
-| `no-keyboard-handler`    | warning  | Has `@click` but no keyboard handler        |
-| `relative-import`        | error    | Imports must use `chrome://` URIs           |
-| `raw-color-value`        | error    | Raw hex/rgb/hsl (use CSS custom properties) |
-| `token-prefix-violation` | error    | CSS variable does not match `tokenPrefix`   |
+There are three component types:
 
-</details>
+| Type         | What it is                                             | Local files                    |
+| ------------ | ------------------------------------------------------ | ------------------------------ |
+| **Stock**    | Engine components tracked for Storybook preview        | None                           |
+| **Override** | Forked copy: `css-only` (restyle) or `full` (JS + CSS) | `components/overrides/<name>/` |
+| **Custom**   | New element that does not exist in Firefox             | `components/custom/<name>/`    |
 
-<details>
-<summary>furnace.json schema</summary>
-
-```jsonc
-{
-  "version": 1,
-  "componentPrefix": "moz-",
-  "stock": ["moz-button", "moz-toggle"],
-  "overrides": {
-    "moz-button": {
-      "type": "css-only",
-      "description": "Custom button styles",
-      "basePath": "toolkit/content/widgets/moz-button",
-      "baseVersion": "134.0",
-    },
-  },
-  "custom": {
-    "moz-my-widget": {
-      "description": "A new widget",
-      "targetPath": "toolkit/content/widgets/moz-my-widget",
-      "register": true,
-      "localized": false,
-      "composes": ["moz-button"],
-    },
-  },
-}
+```bash
+fireforge furnace scan                             # discover components in the engine
+fireforge furnace override moz-button -t css-only  # fork with CSS-only restyle
+fireforge furnace create moz-my-widget             # scaffold a new component
+fireforge furnace deploy                           # apply to engine/ + validate
+fireforge furnace status                           # workspace vs engine drift
+fireforge furnace diff moz-button                  # unified diff against baseline
 ```
 
-</details>
-
----
+`furnace deploy` validates components before applying — errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
 
 ## Configuration
 
@@ -317,7 +303,7 @@ Furnace validates components on deploy. Errors block apply; warnings are advisor
   "binaryName": "mybrowser",
   "license": "EUPL-1.2",
   "firefox": {
-    "version": "140.0esr",
+    "version": "146.0esr",
     "product": "firefox-esr"
   },
   "build": { "jobs": 8 },
@@ -325,114 +311,15 @@ Furnace validates components on deploy. Errors block apply; warnings are advisor
 }
 ```
 
-Use `fireforge config <key> [value]` to read or update values. Run `fireforge --help` and `fireforge <command> --help` for the full option reference. The `jobs` value defaults to your CPU core count, which is usually reasonable but not always optimal; Firefox's build system has enough sequential bottlenecks that doubling your core count does not halve your build time, for what it is worth.
-
----
-
-## Testing Methodology
-
-FireForge's test suite is designed around a constraint that, at least in my experience, does not get enough attention: realistic tests do not have to be slow.
-
-### Real Firefox validation
-
-We run full end-to-end test passes against real Firefox ESR 140 source code in a production fork setup. These validate the entire workflow: setup, download, bootstrap, build, export, import, discard, and recovery.
-
-### Derived in-repo tests
-
-The 1400+ in-repo tests are not idealised mocks. They are derived from those real Firefox runs. Every fixture, edge case, and scenario was first observed against actual Firefox source, then distilled into a deterministic test that runs in seconds. Examples:
-
-- CSS design tokens with `light-dark(#hex)` from a real 348-line tokens file
-- BrowserGlue lazy import with `// BRAND:` markers from a real 2-hunk modification
-- Multi-file theme patches spanning CSS + manifest + build system from real patches
-- Observer topic regex edge cases from a real `notifyObservers` call
-
-This means the fast test suite covers the same behavioural surface as the full-tree runs, without requiring 30 GB of Firefox source. It would be fair to call the fixtures "synthetic" in the sense that they are not the original files, but the scenarios they encode are not invented; they are reproductions of real behaviour we observed during development.
-
-<details>
-<summary>Running the full-tree suite</summary>
-
-The opt-in full-tree suite exercises a connected workflow against a prepared Firefox project:
-
-```bash
-FIREFORGE_FULL_PROJECT_ROOT=/path/to/project npm run test:firefox-full
-```
-
-Optional environment variables:
-
-- `FIREFORGE_FULL_BUILD_MODE=ui|full` (defaults to `ui`)
-- `FIREFORGE_FULL_TARGET_FILE=browser/base/content/browser.js` (override the target file for export/import)
-- `FIREFORGE_FULL_KEEP_PATCH=1` (keep the temporary patch instead of cleaning up)
-- `FIREFORGE_FULL_SKIP_SETUP=1` (skip `setup --force` for an already-prepared project)
-
-Each run writes artefacts under `.fireforge/full-integration-artifacts/<timestamp>/` in the target project.
-
-</details>
-
----
-
-<details>
-<summary>Programmatic API</summary>
-
-> **Pre-1.0 stability notice.** FireForge is at v0.9.x. The programmatic API
-> exported from the main package entry point is functional and tested, but
-> may change between minor versions until 1.0. Pin your dependency to an
-> exact version if you rely on it. I would rather be honest about this then
-> pretend the API surface is frozen when it is not.
-
-FireForge can be used as a library in addition to the CLI:
-
-```typescript
-import { loadConfig, validateConfig, applyAllComponents, loadFurnaceConfig } from 'fireforge';
-```
-
-### Exported functions
-
-| Function                | Module           | Purpose                                    |
-| ----------------------- | ---------------- | ------------------------------------------ |
-| `loadConfig`            | config           | Load and parse `fireforge.json`            |
-| `validateConfig`        | config           | Validate a config object                   |
-| `applyAllComponents`    | furnace-apply    | Apply all Furnace components to the engine |
-| `ensureFurnaceConfig`   | furnace-config   | Create `furnace.json` if missing           |
-| `loadFurnaceConfig`     | furnace-config   | Load and parse `furnace.json`              |
-| `loadFurnaceState`      | furnace-config   | Load Furnace runtime state                 |
-| `saveFurnaceState`      | furnace-config   | Persist Furnace runtime state              |
-| `validateFurnaceConfig` | furnace-config   | Validate a Furnace config                  |
-| `validateAllComponents` | furnace-validate | Validate all registered components         |
-| `validateComponent`     | furnace-validate | Validate a single component                |
-| `addToken`              | token-manager    | Add a design token                         |
-| `getTokensCssPath`      | token-manager    | Get the path to the tokens CSS file        |
-| `validateTokenAdd`      | token-manager    | Validate a token before adding             |
-
-### Exported types
-
-All configuration and result types are exported (`FireForgeConfig`, `FurnaceConfig`, `BuildConfig`, `ApplyResult`, `PatchInfo`, etc.). See `src/types/index.ts` for the full list.
-
-### Error classes
-
-All error classes extend `FireForgeError`:
-
-- `CancellationError` (user-initiated cancellation)
-- `CommandError` (CLI command failure)
-- `GeneralError` (catch-all for unexpected failures)
-- `InvalidArgumentError` (bad input)
-- `ResolutionError` (dependency resolution failure)
-
-Use `ExitCode` for programmatic exit code handling.
-
-</details>
-
----
-
 ## Roadmap
 
-These are planned but not yet implemented. I mention them here for transparency rather then as a promise, since priorities shift and some of these may prove harder then they look.
-
-- **Docker builds.** Reproducible builds using Docker containers. The main challenge is keeping the image size reasonable given Firefox's build dependency tree.
-- **CI mode.** Automated setup for continuous integration pipelines.
-- **Update manifests.** Generate update server manifests for auto-updates.
-- **Nightly support.** This requires `hg clone` from mozilla-central rather then the archive download path, which is a meaningfully different code path.
+Planned but not yet implemented:
 
----
+- **Docker builds** Reproducible builds using Docker containers.
+- **CI mode** Automated setup for continuous integration pipelines.
+- **Update manifests** Generate update server manifests for auto-updates.
+- **Nightly support** Requires implementing `hg clone` support via mozilla-central. Currently fireforge only downloads from the archive.
+- **E2E Github Actions** Requires either a higher tier of Github offering, an external VPS or similar, or another provider entirely. In either case, full end-to-end testing is currently run solely locally.
 
 ## Licence
 

package/dist/bin/fireforge.js

@@ -9,6 +9,7 @@
  *
  */
 import { installBrokenPipeHandler, main } from '../src/cli.js';
+import { isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
 import { CommandError } from '../src/errors/base.js';
 installBrokenPipeHandler();
 process.on('unhandledRejection', (reason) => {
@@ -18,6 +19,31 @@ process.on('unhandledRejection', (reason) => {
     }
     process.exit(1);
 });
+// SIGINT / SIGTERM handlers run any in-flight furnace rollback before
+// terminating. The library cannot call process.exit itself (the
+// process-boundary test enforces that invariant), so the bin entry point owns
+// both the rollback dispatch and the exit. The handler is a no-op when no
+// furnace mutation is currently registered with the lifecycle wrapper, so
+// patch-only commands behave exactly as before.
+function installFurnaceSignalHandler(signal, exitCode) {
+    process.on(signal, () => {
+        if (isSignalRollbackInFlight()) {
+            // A second Ctrl+C while we're already rolling back is a noisy "I want
+            // out now" — let the second signal terminate the process forcefully
+            // rather than queueing another rollback that will race the first.
+            process.exit(exitCode);
+        }
+        rollbackActiveOperationsForSignal(signal)
+            .catch((error) => {
+            console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
+        })
+            .finally(() => {
+            process.exit(exitCode);
+        });
+    });
+}
+installFurnaceSignalHandler('SIGINT', 130);
+installFurnaceSignalHandler('SIGTERM', 143);
 main().catch((error) => {
     if (error instanceof CommandError) {
         process.exit(error.exitCode);

package/dist/src/cli.d.ts

@@ -11,7 +11,7 @@ export declare function resetBrokenPipeHandlerForTests(): void;
 /**
  * Gets the project root directory.
  * Walks up from the current working directory until a fireforge.json is found.
- * Falls back to the current working directory when no project root is found.
+ * Throws when no fireforge.json is found within the walk depth limit.
  */
 export declare function getProjectRoot(): string;
 /**