@hominis/fireforge 0.19.5 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.20.0
+
+### Features
+
+- **Pinned Firefox archive verification.** `FirefoxConfig` now accepts optional `firefox.sha256`, and `fireforge config firefox.sha256 <digest>` is a supported config path. The digest must be a 64-character SHA-256 hex string; FireForge verifies both cached and freshly downloaded source archives against it before extraction, so reproducible workflows can fail fast on a mismatched upstream archive instead of discovering the problem after engine mutation has begun.
+- **`fireforge patch compact`.** Patch queues with ordinal gaps after deletes, splits, or manual repair can now be compacted back to contiguous numbering under the existing patch manifest lock. The command supports dry-run previews, confirmation/`--yes`, lock-time recomputation, history entries, and the same two-phase rename/rollback safety as other patch renumbering paths.
+- **Furnace xpcshell scaffolding and rename helpers.** Furnace test scaffolding now covers xpcshell packaging probes for storage/module-loading code paths, and rename logic is split into focused helpers for component filenames and config rewrites so custom and override renames share the same behaviour.
+
+### Hardening
+
+- **`fireforge download` is locked end-to-end.** The command now takes a project-level `.fireforge/` sidecar lock around the full engine mutation sequence: engine existence checks, forced removal, source download/extraction, git init or resume, patch cleanup, and state updates. Parallel invocations queue with explicit timeout/stale-lock messaging instead of racing over `engine/`.
+- **Firefox archive cache mutation is locked per archive.** Cache validation, invalidation, download promotion, and metadata writes now run under a per-archive cache lock. A failed downloader removes only its own unique `.part-*` file unless it already promoted the tarball, so a failing peer can no longer delete another process's valid final cache entry.
+- **Download stream timers clean up on all terminal paths.** The stall detector now clears its timer from `destroy(error, callback)` as well as normal `flush`, avoiding late timer errors and unnecessary event-loop retention after pipeline failures.
+- **Relative import linting is AST-backed.** `fireforge lint` now uses Acorn/ESTree traversal to detect relative ES imports, side-effect imports, dynamic `import()`, relative re-exports, and `ChromeUtils` / `Cu.import` calls, with a narrow stripped-text fallback only when parsing fails. This closes the false negatives left by the old regex pass while keeping malformed-file diagnostics useful.
+- **Cross-platform process and lock probes are stricter.** `findExecutable` now parses Windows `where` output with CRLF-safe per-line trimming and returns the first non-empty candidate. File-lock stale recovery treats only `ESRCH` from `process.kill(pid, 0)` as dead; `EPERM` and unknown errors are treated as live/unknown so FireForge does not reclaim a lock owned by another live process.
+- **Filesystem writes get low-risk durability checks.** `writeFileAtomic` preserves the existing mode-preservation behaviour and now best-effort fsyncs the parent directory after rename where the platform supports directory handles. `pathExistsStrict` is available for user-facing probes that should surface `EACCES` / `EPERM` instead of collapsing them into "missing".
+- **Furnace mutations use fresh locked state.** `furnace create`, `furnace remove`, and `furnace rename` re-read `furnace.json` inside the mutation lock before validation and writeback, preserving sibling entries created by concurrent commands instead of writing back stale outer snapshots. `furnace remove` also shares cleanup state for custom browser-chrome, xpcshell, and MochiKit scaffolds.
+- **Furnace refresh distinguishes conflicts from fatal merge failures.** `git merge-file` result handling now treats normal conflict exits separately from fatal/error output or high exit codes. `furnace refresh --all` continues through later overrides after a per-component failure, reports the failed count, and exits non-zero with the failed override names once the rest of the selection has been attempted.
+- **Shared naming and coverage drift guards.** Export placement now reuses `sanitizeName` from patch export instead of maintaining a duplicate slug helper, and the dedicated coverage-threshold script now enrols newly critical modules including Furnace refresh, patch compact, and Furnace xpcshell rename handling.
+
+### Documentation
+
+- **README — download locks and pinned archive checksums.** The quick-start and configuration sections now describe the project download lock, per-archive cache lock, and `firefox.sha256` workflow.
+- **README — concurrent Furnace mutations.** The Furnace section now documents locked fresh-state writeback for create/remove/rename and the `refresh --all` failure summary behaviour.
+
 ## 0.19.0
 
 ### Features
@@ -12,9 +37,14 @@
 - **`modified-file-missing-header` — standard Mozilla MPL-2.0 block headers with wrapped line breaks.** The upstream fallback scan required a contiguous `Mozilla Public License` substring in the first few lines, so files that follow Mozilla’s usual `/* … Mozilla Public` / ` * License, v. 2.0 … */` wrap (including after Emacs/vim directive blocks) were warned despite a valid notice. `containsUpstreamLicenseText` in `src/core/license-headers.ts` now normalizes common block-comment continuation prefixes before matching, so forks need not add SPDX solely to satisfy patch lint.
 - **`fireforge test` — `--marionette-port` auto-forward matches toolkit mochitests and mixed suites.** Auto-forward of `--setpref=marionette.port=<n>` previously keyed off a path heuristic that missed `toolkit/content/tests/**` widget HTML tests (no `/mochitest/` segment), so the preflight could use the operator’s port while mach still defaulted to **2828**. Forwarding now runs whenever `--marionette-port` is set unless `--mach-arg` explicitly includes `--flavor=xpcshell` / `xpcshell-tests` (the pref is unused there). `isMarionetteFlavor` also treats `toolkit/content/tests/` paths as Marionette-relevant unless they sit under `/tests/xpcshell/`, for consistency with other callers of that helper.
 
+### Compatibility
+
+- **`furnace create --with-tests` defaults to `browser-chrome` again** (not `mochikit`, which was the default after the `--test-style` split). Forks whose top-level chrome document has no `tabbrowser` should pass **`--test-style=mochikit`** explicitly. On macOS, toolkit MochiKit / mochitest-chrome-style widget tests can idle until ~370s with no subtests; README documents the tradeoff.
+
 ### Documentation
 
 - **README — mochitest timeouts vs Marionette.** The Test harness section documents long idle timeouts (~370s, `TEST_END: TIMEOUT`) on fork custom chrome, `--marionette-port` behaviour with xpcshell flavor, and pointers to fork-side prefs and investigation (for example Hominis `AGENT_RULES.md`).
+- **README — default test harness and macOS mochitest-chrome.** The README sections “Picking a test harness for `furnace create`”, “Test harness options”, and “Known upstream build issues” describe the browser-chrome default, macOS single-process idle timeout, explicit `--test-style=mochikit`, and `--with-tests` + `--xpcshell` resolution.
 
 ## 0.18.0
 

package/README.md

@@ -59,6 +59,8 @@ Your project now has `fireforge.json`, an `engine/` directory with Firefox sourc
 
 - **macOS 15 (Darwin 25+) — `gecko-profiler` bindgen error `cannot find type _CharT in this scope`.** An Apple toolchain update changed `std::__CharT_pointer` to `_CharT_pointer` in the libc++ headers Firefox's bindgen walks, so `toolkit/library/rust/target-objects` fails during `mach build` even on a clean `fireforge bootstrap`. This is an upstream Firefox issue, not a FireForge bug. Two workarounds: pin Xcode's command line tools to a pre-September-2025 release via `xcode-select --install` / [Apple developer downloads](https://developer.apple.com/download/all/), or apply a one-line bindgen-basic-string-workaround patch (a downstream consumer may ship one in its patch queue). If you interrupt the resulting `fireforge build` and re-run `fireforge doctor`, the download/engine state is unaffected — the failure is isolated to the Rust compile phase.
 
+- **macOS (including Apple Silicon) — toolkit / MochiKit widget tests idle until ~370s (`TEST_END: TIMEOUT`, no subtests).** The **mochitest-chrome** flavor used for `toolkit/content/tests/widgets/test_*.html` runs **single-process** (`e10s: false`), which interacts badly with headed or headless compositing (for example SWGL) in some setups. Prefer **`furnace create --with-tests`** (defaults to **`browser-chrome`**, multi-process) for interactive chrome coverage, or place tests alongside your fork's browser modules (for example `engine/browser/modules/<fork>/test/`). If you must use **`--test-style=mochikit`**, expect possible hangs on macOS. Details: [Picking a test harness for `furnace create`](#picking-a-test-harness-for-furnace-create), [Test harness options](#test-harness-options).
+
 ### Workflow Overview
 
 1. Make changes inside the `engine/` directory.
@@ -85,6 +87,8 @@ 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 download` is serialised by a project lock under `.fireforge/`, covering the engine-exists check, forced replacement, extraction, git initialisation/resume, patch cleanup and state update. Archive cache entries are also guarded by per-archive locks, so parallel downloads queue instead of racing over the same `engine/` directory or deleting each other's cache results. For reproducible workflows, set `firefox.sha256` to the expected 64-character archive SHA-256; FireForge verifies both cached and freshly downloaded archives before extraction and refuses a mismatch before touching the engine.
+
 `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
@@ -417,20 +421,24 @@ The packaging-verification test that `--with-tests` scaffolds is what FireForge
 
 ### Picking a test harness for `furnace create`
 
-`furnace create --with-tests` defaults to a MochiKit test at `engine/toolkit/content/tests/widgets/test_<tag>.html`. MochiKit tests load the component module via `chrome://global/` and don't need a `tabbrowser`, so they run against any fork — including bespoke chrome documents (`mybrowser.xhtml`-class) that deliberately omit the upstream browser chrome.
+`furnace create --with-tests` defaults to a **browser-chrome** mochitest: `browser_<binary>_<tag>.js` under `engine/browser/base/content/test/<binary-name>/`, registered via `browser.toml` (and `browser/base/moz.build` when the scaffolder appends there). Use this when the component participates in real browser chrome (tabs, `gBrowser`, and similar).
+
+**MochiKit** (`--test-style=mochikit`) is opt-in: it emits `test_<tag>.html` under `engine/toolkit/content/tests/widgets/`, loads the module via `chrome://global/`, and does not need a `tabbrowser` — so it is the right choice for bespoke chrome documents that omit the upstream tab strip. On **macOS**, that harness can hit a long idle timeout (see [Known upstream build issues](#known-upstream-build-issues)); prefer browser-chrome tests when your fork has a normal tabbed window.
 
 Three styles are available via `--test-style`:
 
-| Style            | When to use                                                                                                                                                                                                         |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mochikit`       | Default. Pure-UI custom elements. Runs today against non-tabbrowser chrome. Emits `test_<tag>.html` under `toolkit/content/tests/widgets/`.                                                                         |
-| `browser-chrome` | Element talks to the browser window (open URLs, manipulate tabs). Requires a working `tabbrowser` in the chrome document. Emits the `browser_<bin>_<tag>.js` scaffold and registers it in `browser/base/moz.build`. |
-| `xpcshell`       | Storage-layer, observer-driven, or ESM-loading code. Headless, no tabbrowser. Emits `test_<name>_module_loads.js` + `xpcshell.toml` (registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator).           |
+| Style            | When to use                                                                                                                                                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browser-chrome` | **Default** with `--with-tests`. Interactive chrome, tab strip, `gBrowser`. Requires a working `tabbrowser`. Emits `browser_<bin>_<tag>.js` and registers via `browser.toml` / `browser/base/moz.build`.  |
+| `mochikit`       | Pure-UI custom elements on forks **without** a `tabbrowser`. Emits `test_<tag>.html` under `toolkit/content/tests/widgets/`. May be unreliable on macOS (mochitest-chrome / single-process).              |
+| `xpcshell`       | Storage-layer, observer-driven, or ESM-loading code. Headless, no tabbrowser. Emits `test_<name>_module_loads.js` + `xpcshell.toml` (registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator). |
 
 `--xpcshell` is preserved as an alias for `--test-style=xpcshell`; conflicting flag combinations (`--xpcshell --test-style=mochikit`) are rejected.
 
 `furnace create --dry-run` previews the planned file set, test scaffold, and `furnace.json` mutation without writing anything. Every validation the real command runs (tag-name shape, name conflicts, engine pre-existence of the component, `--compose` target existence + cycle detection) fires BEFORE the plan is emitted, so a failed preview matches a failed real run.
 
+`furnace create`, `furnace remove`, and `furnace rename` re-read `furnace.json` inside the mutation lock before writing, so concurrent component edits preserve sibling entries instead of writing back a stale outer snapshot. `furnace refresh --all` continues past per-component refresh failures, reports the failed count, and exits non-zero with the failed override names after finishing the rest of the selection.
+
 ## Additional Commands
 
 The commands below cover project configuration, patch queue management, build packaging and development utilities. Run `fireforge <command> --help` for full option details.
@@ -444,6 +452,9 @@ fireforge config firefox.version
 # Set a config value
 fireforge config firefox.version 145.0.0esr
 
+# Pin the resolved Firefox source archive checksum
+fireforge config firefox.sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+
 # Set a value at a non-standard path (requires --force)
 fireforge config customKey "value" --force
 ```
@@ -452,6 +463,8 @@ Writes are serialised behind a sidecar lock — two concurrent `fireforge config
 
 Re-setting a key to its current value is a no-op: `fireforge.json` is not rewritten, key ordering is preserved, and the success log surfaces `<key> = <value> (unchanged)` instead of a fresh `Set …` line. This means automation that idempotently runs `fireforge config <key> <value>` no longer produces spurious diffs in `fireforge.json`.
 
+`firefox.sha256` is optional. When set, it must be a 64-character hex SHA-256 for the Firefox source archive resolved from `firefox.product` + `firefox.version`; cached archives and fresh downloads are verified against it before extraction. Omit it to keep the default cache-integrity-only behaviour.
+
 ### Patch queue management
 
 ```bash
@@ -628,7 +641,7 @@ Set this in `furnace.json` to extend the list (forks with additional platform pr
 
 ### Test harness options
 
-`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest**. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.).
+`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest** by default. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.). On **macOS**, avoid relying on **`--test-style=mochikit`** (toolkit `test_*.html` under `toolkit/content/tests/widgets/`) for primary chrome/widget coverage: the **mochitest-chrome** flavor runs **single-process** (`e10s: false`) and has been observed to **idle ~370s** with no subtests (headless or headed compositing / SWGL). Prefer browser-chrome tests (multi-process); for forks that organize interactive tests under `engine/browser/modules/<fork>/test/`, extend that tree rather than adding new `test_<tag>.html` scaffolds when browser-chrome is sufficient.
 
 `fireforge furnace create --xpcshell` scaffolds an **xpcshell test harness** instead. Use this when the component's code path is storage-only, observer-driven, or module-loading logic that does not touch a `tabbrowser`. xpcshell runs headless without browser chrome, so forks without an upstream tab strip can still cover these paths. The scaffolder writes `test_<name>_packaged.js` + `xpcshell.toml` into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/` and prints a note: registration in `XPCSHELL_TESTS_MANIFESTS` is the operator's call (the moz.build that should own the entry depends on where the component actually lives). `fireforge register <path>/xpcshell.toml` surfaces the same guidance when run directly rather than silently routing to a browser.toml-shaped advice.
 
@@ -636,7 +649,7 @@ The scaffolded xpcshell test is a **packaging probe**, not a module-load test. L
 
 xpcshell has a chrome-URI boundary that is worth knowing before writing assertions: `chrome://global/*` (toolkit chrome) IS registered and resolvable from the harness, but `chrome://browser/*` (browser chrome) is NOT — even when `firefox-appdir = "browser"` is set in the xpcshell.toml, the manifest set xpcshell loads lags what the real browser loads, so `NetUtil.asyncFetch("chrome://browser/content/…")` can still fail with `NS_ERROR_FILE_NOT_FOUND` against an artifact that IS present in `obj-*/dist/`. Assertions that need browser chrome URIs belong in a browser-chrome mochitest (`furnace create --test-style=browser-chrome`).
 
-The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
+If you pass **`--with-tests` and `--xpcshell` together**, FireForge resolves the harness to **xpcshell only** (`--xpcshell` takes precedence). To get the default browser-chrome mochitest as well, run a second `furnace create` with `--with-tests` only or add the browser test files manually.
 
 ### Mochitest stalls and `--marionette-port`
 

package/dist/src/commands/config.js

@@ -31,6 +31,7 @@ const STRING_TYPED_KEYS = new Set([
     'binaryName',
     'firefox.version',
     'firefox.product',
+    'firefox.sha256',
     'license',
     'wire.subscriptDir',
 ]);

package/dist/src/commands/download.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { getProjectPaths, loadConfig, updateState } from '../core/config.js';
+import { withFileLock } from '../core/file-lock.js';
 import { downloadFirefoxSource, formatBytes } from '../core/firefox.js';
 import { getFurnacePaths, updateFurnaceState } from '../core/furnace-config.js';
 import { getHead, initRepository, isGitRepository, isMissingHeadError, resumeRepository, } from '../core/git.js';
@@ -9,7 +10,7 @@ import { getDirtyFiles } from '../core/git-status.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { EngineExistsError, PartialEngineExistsError } from '../errors/download.js';
 import { toError } from '../utils/errors.js';
-import { checkDiskSpace, ensureDir, pathExists, removeDir } from '../utils/fs.js';
+import { checkDiskSpace, ensureDir, pathExists, pathExistsStrict, removeDir } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
@@ -124,203 +125,205 @@ export async function downloadCommand(projectRoot, options) {
     info(`Firefox version: ${version}`);
     // Disk space pre-flight: Firefox source is ~5 GB
     await checkDiskSpace(projectRoot, 5 * 1024 * 1024 * 1024, warn);
-    // Check if engine already exists
-    if (await pathExists(paths.engine)) {
-        if (!options.force) {
-            if (await isGitRepository(paths.engine)) {
-                try {
-                    await getHead(paths.engine);
-                }
-                catch (error) {
-                    if (isMissingHeadError(error)) {
-                        // Partial init detected — attempt to resume instead of requiring --force
-                        info('Detected partially initialized engine. Attempting to resume...');
-                        // Snapshot patch-touched files that are already dirty so we
-                        // can preserve them after the resume commit.
-                        const patchFiles = await getPatchTouchedFiles(paths.patches);
-                        const preExistingDirty = patchFiles.size > 0
-                            ? new Set(await getDirtyFiles(paths.engine, [...patchFiles]))
-                            : new Set();
-                        const resumeSpinner = spinner('Resuming git repository initialization...');
-                        try {
-                            await resumeRepository(paths.engine, {
-                                // The non-TTY spinner fallback in `src/utils/logger.ts`
-                                // already calls `p.log.step(msg)` from `message()`, so
-                                // forwarding the progress message is the single authority
-                                // in both TTY and non-TTY modes. Before 0.16.0 this
-                                // callback also invoked `step(message)` explicitly when
-                                // stdio was not a TTY, which printed the same step line
-                                // twice in CI logs (once from the fallback, once from
-                                // the explicit call).
-                                onProgress: (message) => {
-                                    resumeSpinner.message(message);
-                                },
-                            });
-                            const baseCommit = await getHead(paths.engine);
-                            resumeSpinner.stop('Git repository resumed successfully');
-                            // Restore patch-touched files BEFORE stamping state. If this
-                            // step fails (disk full, permission denied, git object issue),
-                            // state.json keeps the previous downloadedVersion so the
-                            // invariant "state.downloadedVersion matches a clean engine"
-                            // holds. A retry of `fireforge download` then re-enters the
-                            // resume path instead of declaring success against a dirty
-                            // engine.
-                            await cleanPatchTouchedFiles(paths.engine, paths.patches, preExistingDirty);
-                            await updateState(projectRoot, {
-                                downloadedVersion: version,
-                                baseCommit,
-                            });
-                            await noteUnappliedPatches(paths.patches);
-                            outro(`Firefox ${version} is ready! (resumed from partial init)`);
-                            return;
-                        }
-                        catch (error) {
-                            resumeSpinner.error('Resume failed');
-                            // Preserve the underlying cause so the user sees *why* the
-                            // resume failed (timeout, permission denied, corrupted object,
-                            // disk full, …) instead of only the generic "partial engine
-                            // exists" story. Verbose mode prints the stack for deeper
-                            // triage.
-                            const cause = toError(error);
-                            verbose(`Resume failure detail: ${cause.message}`);
-                            if (cause.stack) {
-                                verbose(cause.stack);
+    await withFileLock(join(paths.fireforgeDir, 'download.fireforge.lock'), async () => {
+        // Check if engine already exists
+        if (await pathExistsStrict(paths.engine)) {
+            if (!options.force) {
+                if (await isGitRepository(paths.engine)) {
+                    try {
+                        await getHead(paths.engine);
+                    }
+                    catch (error) {
+                        if (isMissingHeadError(error)) {
+                            // Partial init detected — attempt to resume instead of requiring --force
+                            info('Detected partially initialized engine. Attempting to resume...');
+                            // Snapshot patch-touched files that are already dirty so we
+                            // can preserve them after the resume commit.
+                            const patchFiles = await getPatchTouchedFiles(paths.patches);
+                            const preExistingDirty = patchFiles.size > 0
+                                ? new Set(await getDirtyFiles(paths.engine, [...patchFiles]))
+                                : new Set();
+                            const resumeSpinner = spinner('Resuming git repository initialization...');
+                            try {
+                                await resumeRepository(paths.engine, {
+                                    // The non-TTY spinner fallback in `src/utils/logger.ts`
+                                    // already calls `p.log.step(msg)` from `message()`, so
+                                    // forwarding the progress message is the single authority
+                                    // in both TTY and non-TTY modes. Before 0.16.0 this
+                                    // callback also invoked `step(message)` explicitly when
+                                    // stdio was not a TTY, which printed the same step line
+                                    // twice in CI logs (once from the fallback, once from
+                                    // the explicit call).
+                                    onProgress: (message) => {
+                                        resumeSpinner.message(message);
+                                    },
+                                });
+                                const baseCommit = await getHead(paths.engine);
+                                resumeSpinner.stop('Git repository resumed successfully');
+                                // Restore patch-touched files BEFORE stamping state. If this
+                                // step fails (disk full, permission denied, git object issue),
+                                // state.json keeps the previous downloadedVersion so the
+                                // invariant "state.downloadedVersion matches a clean engine"
+                                // holds. A retry of `fireforge download` then re-enters the
+                                // resume path instead of declaring success against a dirty
+                                // engine.
+                                await cleanPatchTouchedFiles(paths.engine, paths.patches, preExistingDirty);
+                                await updateState(projectRoot, {
+                                    downloadedVersion: version,
+                                    baseCommit,
+                                });
+                                await noteUnappliedPatches(paths.patches);
+                                outro(`Firefox ${version} is ready! (resumed from partial init)`);
+                                return;
+                            }
+                            catch (error) {
+                                resumeSpinner.error('Resume failed');
+                                // Preserve the underlying cause so the user sees *why* the
+                                // resume failed (timeout, permission denied, corrupted object,
+                                // disk full, …) instead of only the generic "partial engine
+                                // exists" story. Verbose mode prints the stack for deeper
+                                // triage.
+                                const cause = toError(error);
+                                verbose(`Resume failure detail: ${cause.message}`);
+                                if (cause.stack) {
+                                    verbose(cause.stack);
+                                }
+                                throw new PartialEngineExistsError(paths.engine, cause);
                             }
-                            throw new PartialEngineExistsError(paths.engine, cause);
                         }
+                        // Re-throw unexpected git errors (corrupted objects, permission
+                        // denied, …) wrapped in PartialEngineExistsError so the user sees
+                        // both narratives: "we detected a partial engine and attempted
+                        // resume" AND the underlying git failure. Without the wrap the
+                        // raw git error loses the context that resume was in flight.
+                        const cause = toError(error);
+                        verbose(`Partial-engine probe failed with unexpected error: ${cause.message}`);
+                        if (cause.stack) {
+                            verbose(cause.stack);
+                        }
+                        throw new PartialEngineExistsError(paths.engine, cause);
                     }
-                    // Re-throw unexpected git errors (corrupted objects, permission
-                    // denied, …) wrapped in PartialEngineExistsError so the user sees
-                    // both narratives: "we detected a partial engine and attempted
-                    // resume" AND the underlying git failure. Without the wrap the
-                    // raw git error loses the context that resume was in flight.
-                    const cause = toError(error);
-                    verbose(`Partial-engine probe failed with unexpected error: ${cause.message}`);
-                    if (cause.stack) {
-                        verbose(cause.stack);
-                    }
-                    throw new PartialEngineExistsError(paths.engine, cause);
                 }
+                throw new EngineExistsError(paths.engine);
+            }
+            warn('Removing existing engine directory...');
+            await removeDir(paths.engine);
+            // --force installs a new baseCommit, which invalidates every applied
+            // checksum in furnace-state.json. Clearing the state now prevents a
+            // subsequent `furnace apply` from reporting "up to date" against an
+            // engine that no longer contains any of the deployed files. Preserve
+            // pendingRepair: authoring-side rollback markers describe unresolved
+            // component workspace state and should survive an engine refresh.
+            const furnacePaths = getFurnacePaths(projectRoot);
+            if (await pathExists(furnacePaths.furnaceState)) {
+                await updateFurnaceState(projectRoot, (current) => ({
+                    ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
+                }));
             }
-            throw new EngineExistsError(paths.engine);
-        }
-        warn('Removing existing engine directory...');
-        await removeDir(paths.engine);
-        // --force installs a new baseCommit, which invalidates every applied
-        // checksum in furnace-state.json. Clearing the state now prevents a
-        // subsequent `furnace apply` from reporting "up to date" against an
-        // engine that no longer contains any of the deployed files. Preserve
-        // pendingRepair: authoring-side rollback markers describe unresolved
-        // component workspace state and should survive an engine refresh.
-        const furnacePaths = getFurnacePaths(projectRoot);
-        if (await pathExists(furnacePaths.furnaceState)) {
-            await updateFurnaceState(projectRoot, (current) => ({
-                ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
-            }));
         }
-    }
-    // Ensure cache directory exists
-    const cacheDir = join(paths.fireforgeDir, 'cache');
-    await ensureDir(cacheDir);
-    // Phase-switched spinners: the download phase runs with the byte-count
-    // progress callbacks below; the extract phase is blocking tar-xz and
-    // has no incremental progress, but it can take 30–90s on a ~600 MB
-    // Firefox tree, so it gets its own spinner message. Before the phase
-    // split, a single "Downloading Firefox … 100%" spinner covered both
-    // — the first-run setup looked hung precisely when the archive had
-    // already reached disk and `tar` was the long pole.
-    let s = spinner(`Downloading Firefox ${version}...`);
-    let lastPercent = 0;
-    const phaseState = { value: 'download' };
-    try {
-        await downloadFirefoxSource(version, config.firefox.product, paths.engine, cacheDir, (downloaded, total) => {
-            if (total <= 0)
-                return;
-            const percent = Math.floor((downloaded / total) * 100);
-            if (percent !== lastPercent && percent % 5 === 0) {
-                s.message(`Downloading Firefox ${version}... ${percent}% (${formatBytes(downloaded)} / ${formatBytes(total)})`);
-                lastPercent = percent;
+        // Ensure cache directory exists
+        const cacheDir = join(paths.fireforgeDir, 'cache');
+        await ensureDir(cacheDir);
+        // Phase-switched spinners: the download phase runs with the byte-count
+        // progress callbacks below; the extract phase is blocking tar-xz and
+        // has no incremental progress, but it can take 30–90s on a ~600 MB
+        // Firefox tree, so it gets its own spinner message. Before the phase
+        // split, a single "Downloading Firefox … 100%" spinner covered both
+        // — the first-run setup looked hung precisely when the archive had
+        // already reached disk and `tar` was the long pole.
+        let s = spinner(`Downloading Firefox ${version}...`);
+        let lastPercent = 0;
+        const phaseState = { value: 'download' };
+        try {
+            await downloadFirefoxSource(version, config.firefox.product, paths.engine, cacheDir, (downloaded, total) => {
+                if (total <= 0)
+                    return;
+                const percent = Math.floor((downloaded / total) * 100);
+                if (percent !== lastPercent && percent % 5 === 0) {
+                    s.message(`Downloading Firefox ${version}... ${percent}% (${formatBytes(downloaded)} / ${formatBytes(total)})`);
+                    lastPercent = percent;
+                }
+            }, (phase) => {
+                if (phase === 'extract' && phaseState.value === 'download') {
+                    s.stop(`Firefox ${version} downloaded`);
+                    phaseState.value = 'extract';
+                    s = spinner(`Extracting Firefox ${version}... (decompressing ~600 MB of source; typically 30–90s)`);
+                }
+            }, config.firefox.sha256);
+            if (phaseState.value === 'extract') {
+                s.stop(`Firefox ${version} extracted`);
             }
-        }, (phase) => {
-            if (phase === 'extract' && phaseState.value === 'download') {
+            else {
                 s.stop(`Firefox ${version} downloaded`);
-                phaseState.value = 'extract';
-                s = spinner(`Extracting Firefox ${version}... (decompressing ~600 MB of source; typically 30–90s)`);
             }
-        });
-        if (phaseState.value === 'extract') {
-            s.stop(`Firefox ${version} extracted`);
         }
-        else {
-            s.stop(`Firefox ${version} downloaded`);
+        catch (error) {
+            s.error(phaseState.value === 'extract' ? 'Extraction failed' : 'Download failed');
+            throw error;
         }
-    }
-    catch (error) {
-        s.error(phaseState.value === 'extract' ? 'Extraction failed' : 'Download failed');
-        throw error;
-    }
-    // Finding #17: the git indexing phase of `download` can block for
-    // minutes on a ~600 MB Firefox tree — the spinner updates less often
-    // than operators expect during the monolithic `git add -A` pass, and
-    // non-TTY shells see long stretches of silence. Emit a one-line
-    // heads-up banner BEFORE the spinner starts so even a log-scraping
-    // CI job notes the expected duration. The progress callbacks below
-    // still fire as usual; this is an additional up-front signal, not a
-    // replacement.
-    info('Indexing downloaded source into git (one-time; typically 1–3 minutes on a ~600 MB Firefox tree)...');
-    // Initialize git repository
-    const gitSpinner = spinner('Initializing git repository (this may take a few minutes)...');
-    let baseCommit;
-    try {
-        await initRepository(paths.engine, 'firefox', {
-            // Same one-authority rule as the resume path above: the non-TTY
-            // spinner fallback already emits `step(msg)` internally, so
-            // calling `step()` in addition to `.message()` duplicated every
-            // git-init progress line in CI logs.
-            onProgress: (message) => {
-                gitSpinner.message(message);
-            },
+        // Finding #17: the git indexing phase of `download` can block for
+        // minutes on a ~600 MB Firefox tree — the spinner updates less often
+        // than operators expect during the monolithic `git add -A` pass, and
+        // non-TTY shells see long stretches of silence. Emit a one-line
+        // heads-up banner BEFORE the spinner starts so even a log-scraping
+        // CI job notes the expected duration. The progress callbacks below
+        // still fire as usual; this is an additional up-front signal, not a
+        // replacement.
+        info('Indexing downloaded source into git (one-time; typically 1–3 minutes on a ~600 MB Firefox tree)...');
+        // Initialize git repository
+        const gitSpinner = spinner('Initializing git repository (this may take a few minutes)...');
+        let baseCommit;
+        try {
+            await initRepository(paths.engine, 'firefox', {
+                // Same one-authority rule as the resume path above: the non-TTY
+                // spinner fallback already emits `step(msg)` internally, so
+                // calling `step()` in addition to `.message()` duplicated every
+                // git-init progress line in CI logs.
+                onProgress: (message) => {
+                    gitSpinner.message(message);
+                },
+            });
+            baseCommit = await getHead(paths.engine);
+            gitSpinner.stop('Git repository initialized');
+        }
+        catch (error) {
+            gitSpinner.error('Failed to initialize git repository');
+            warn('engine/ may now contain a partially initialized git repository. Re-run "fireforge download --force" to recreate the baseline cleanly.');
+            throw error;
+        }
+        // Restore any patch-touched files that ended up dirty after the initial
+        // commit (e.g. line-ending normalisation or extraction artefacts) so that
+        // a subsequent `fireforge import` works without --force.
+        //
+        // Wrapped in a dedicated spinner because the restore can itself take
+        // tens of seconds on a ~600 MB Firefox tree: it walks every file in the
+        // patch manifest, calls `git status` / `git checkout` for each, and the
+        // eval's "download looks hung" report landed at least partly on this
+        // post-commit window. An operator watching the CLI needs to see that
+        // this phase is distinct from the preceding git-add work.
+        //
+        // This runs BEFORE updateState so a restore failure keeps the previous
+        // downloadedVersion in state.json. The invariant we preserve is
+        // "state.downloadedVersion matches a clean engine": stamping the new
+        // version only after the restore succeeds means a failed clean-up will
+        // re-enter the resume path on the next `fireforge download` rather than
+        // reporting success against a dirty engine.
+        const restoreSpinner = spinner('Restoring patch-touched files to baseline...');
+        try {
+            const restoreResult = await cleanPatchTouchedFiles(paths.engine, paths.patches);
+            closeRestoreSpinner(restoreSpinner, restoreResult);
+        }
+        catch (error) {
+            restoreSpinner.error('Failed to restore patch-touched files');
+            throw error;
+        }
+        await updateState(projectRoot, {
+            downloadedVersion: version,
+            baseCommit,
         });
-        baseCommit = await getHead(paths.engine);
-        gitSpinner.stop('Git repository initialized');
-    }
-    catch (error) {
-        gitSpinner.error('Failed to initialize git repository');
-        warn('engine/ may now contain a partially initialized git repository. Re-run "fireforge download --force" to recreate the baseline cleanly.');
-        throw error;
-    }
-    // Restore any patch-touched files that ended up dirty after the initial
-    // commit (e.g. line-ending normalisation or extraction artefacts) so that
-    // a subsequent `fireforge import` works without --force.
-    //
-    // Wrapped in a dedicated spinner because the restore can itself take
-    // tens of seconds on a ~600 MB Firefox tree: it walks every file in the
-    // patch manifest, calls `git status` / `git checkout` for each, and the
-    // eval's "download looks hung" report landed at least partly on this
-    // post-commit window. An operator watching the CLI needs to see that
-    // this phase is distinct from the preceding git-add work.
-    //
-    // This runs BEFORE updateState so a restore failure keeps the previous
-    // downloadedVersion in state.json. The invariant we preserve is
-    // "state.downloadedVersion matches a clean engine": stamping the new
-    // version only after the restore succeeds means a failed clean-up will
-    // re-enter the resume path on the next `fireforge download` rather than
-    // reporting success against a dirty engine.
-    const restoreSpinner = spinner('Restoring patch-touched files to baseline...');
-    try {
-        const restoreResult = await cleanPatchTouchedFiles(paths.engine, paths.patches);
-        closeRestoreSpinner(restoreSpinner, restoreResult);
-    }
-    catch (error) {
-        restoreSpinner.error('Failed to restore patch-touched files');
-        throw error;
-    }
-    await updateState(projectRoot, {
-        downloadedVersion: version,
-        baseCommit,
+        await noteUnappliedPatches(paths.patches);
+        outro(`Firefox ${version} is ready!`);
     });
-    await noteUnappliedPatches(paths.patches);
-    outro(`Firefox ${version} is ready!`);
 }
 /** Registers the download command on the CLI program. */
 export function registerDownload(program, { getProjectRoot, withErrorHandling }) {

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

@@ -8,7 +8,7 @@
  * testable without dragging the whole command harness along for the ride.
  */
 import { join } from 'node:path';
-import { findAllPatchesForFilesWithDetails, planExport } from '../core/patch-export.js';
+import { findAllPatchesForFilesWithDetails, planExport, sanitizeName, } from '../core/patch-export.js';
 import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../core/patch-lock.js';
 import { addPatchToManifest, loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, } from '../core/patch-manifest.js';
@@ -17,20 +17,9 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
-/**
- * Sanitizes a patch name for use in a filename. Mirrors the private helper
- * in patch-export.ts.
- */
-function sanitizeExportName(name) {
-    return name
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .slice(0, 50);
-}
 function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
-    return `${padded}-${category}-${sanitizeExportName(name)}.patch`;
+    return `${padded}-${category}-${sanitizeName(name)}.patch`;
 }
 function getSortedRenameEntries(renameMap) {
     return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);