@hominis/fireforge 0.19.6 → 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

package/README.md

@@ -87,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
@@ -435,6 +437,8 @@ Three styles are available via `--test-style`:
 
 `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.
@@ -448,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
 ```
@@ -456,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

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);

package/dist/src/commands/furnace/create-validation.d.ts

@@ -0,0 +1,6 @@
+import type { FurnaceCreateOptions } from '../../types/commands/index.js';
+import type { FurnaceConfig } from '../../types/furnace.js';
+/**
+ * Validates a proposed custom component against the current furnace config.
+ */
+export declare function validateCreateAgainstConfig(config: FurnaceConfig, componentName: string, allowPrefixMismatch: FurnaceCreateOptions['allowPrefixMismatch'], composes: string[] | undefined): void;

package/dist/src/commands/furnace/create-validation.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { detectComposesCycles } from '../../core/furnace-config.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { FurnaceError } from '../../errors/furnace.js';
+function checkNameConflict(config, name) {
+    if (name in config.custom) {
+        return `A custom component named "${name}" already exists in furnace.json`;
+    }
+    if (name in config.overrides) {
+        return `An override component named "${name}" already exists in furnace.json`;
+    }
+    return undefined;
+}
+function validateComposesTargets(config, componentName, composes) {
+    if (!composes || composes.length === 0)
+        return;
+    const known = new Set([
+        ...config.stock,
+        ...Object.keys(config.overrides),
+        ...Object.keys(config.custom),
+    ]);
+    for (const tag of composes) {
+        if (tag === componentName) {
+            throw new FurnaceError(`Component "${componentName}" cannot compose itself.`);
+        }
+        if (!known.has(tag)) {
+            throw new FurnaceError(`Cannot compose unknown component "${tag}". ` +
+                'The referenced component must be registered as stock, override, or custom.');
+        }
+    }
+    detectComposesCycles({
+        ...config.custom,
+        [componentName]: {
+            description: '',
+            targetPath: `toolkit/content/widgets/${componentName}`,
+            register: true,
+            localized: false,
+            composes,
+        },
+    });
+}
+/**
+ * Validates a proposed custom component against the current furnace config.
+ */
+export function validateCreateAgainstConfig(config, componentName, allowPrefixMismatch, composes) {
+    const conflict = checkNameConflict(config, componentName);
+    if (conflict) {
+        throw new FurnaceError(conflict, componentName);
+    }
+    if (config.componentPrefix &&
+        !componentName.startsWith(config.componentPrefix) &&
+        !allowPrefixMismatch) {
+        throw new InvalidArgumentError(`Name "${componentName}" does not start with the configured prefix "${config.componentPrefix}". ` +
+            `Use a prefixed name (e.g. "${config.componentPrefix}${componentName}"), update ` +
+            '`componentPrefix` in furnace.json, or pass --allow-prefix-mismatch to create the component anyway.', 'name');
+    }
+    validateComposesTargets(config, componentName, composes);
+}
+//# sourceMappingURL=create-validation.js.map