@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -13,6 +13,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { getNodeErrorCode, toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
 import { cancel, info, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
+import { normalizePathSlashes } from '../../utils/paths.js';
 /**
  * File extensions that are definitely FTL resources (not locale
  * directories). A value ending in one of these is almost certainly the
@@ -38,16 +39,16 @@ function hasFtlFileExtension(value) {
 /**
  * Validates an FTL base path before writing it to furnace.json.
  * Rejects:
- *  - empty values and null bytes;
- *  - absolute paths (POSIX or Windows-drive) that escape the engine;
- *  - `..` segments that escape the engine;
+ *  - empty values and null bytes
+ *  - absolute paths (POSIX or Windows-drive) that escape the engine
+ *  - `..` segments that escape the engine
  *  - file-shaped values ending in `.ftl` / `.properties` / `.dtd`
- *    (these are locale resources, not directories — the operator
- *    almost certainly meant to name the parent directory).
+ *    (these are locale resources, not directories, so the operator
+ *    almost certainly meant to name the parent directory)
  *
  * When {@link engineDir} is provided and exists on disk, the resolved
- * `engine/${value}` path is probed: if it exists but is not a
- * directory, the same file-shape error fires; if it does not exist yet,
+ * `engine/${value}` path is probed. If it exists but is not a
+ * directory, the same file-shape error fires. If it does not exist yet,
  * a non-blocking warning is logged (a fresh project that has not
  * `fireforge download`-ed yet is the legitimate pre-existence case).
  */
@@ -64,7 +65,7 @@ async function validateFtlBasePath(value, engineDir) {
     // Normalize with the POSIX rules regardless of host: `normalize` on Windows
     // emits backslashes, so a `../`-prefix test against the platform `normalize`
     // silently passes every traversal attempt there.
-    const normalized = posix.normalize(value.replace(/\\/g, '/'));
+    const normalized = posix.normalize(normalizePathSlashes(value));
     if (normalized === '..' || normalized.startsWith('../')) {
         throw new FurnaceError(`ftlBasePath "${value}" must not escape the engine checkout via parent-directory segments.`);
     }
@@ -86,16 +87,16 @@ async function validateFtlBasePath(value, engineDir) {
         }
         catch (error) {
             // FurnaceError (from the `isDirectory()` branch above) is a real
-            // shape failure — re-throw so the operator sees it.
+            // shape failure, so re-throw and let the operator see it.
             if (error instanceof FurnaceError)
                 throw error;
             // ENOENT is expected on a fresh project before `fireforge
-            // download` has populated engine/; only warn.
+            // download` has populated engine/. Only warn.
             const code = getNodeErrorCode(error);
             if (code === 'ENOENT') {
                 warn(`ftlBasePath "${value}" does not yet exist at ${resolved}. This is fine if you have not run "fireforge download" yet; rerun "fireforge furnace init --force" after the engine is extracted to re-validate.`);
             }
-            // Any other stat error is also best-effort ignored here — a
+            // Any other stat error is also ignored here as best-effort: a
             // permission issue or malformed engine checkout will surface on
             // the next command that actually reads the FTL tree.
         }
@@ -115,7 +116,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
     const paths = getProjectPaths(projectRoot);
     // Seed the default furnace config with a tokenPrefix derived from
     // fireforge.json's binaryName so `token coverage` sees real tokens on the
-    // very first run — without the prefix default, a fresh init → token add →
+    // very first run. Without the prefix default, a fresh init → token add →
     // coverage sequence reports `0 tokens / N unknown` because the scan has
     // nothing to key off. Loading fireforge.json here is best-effort: a
     // project without one (mid-setup) falls through to the prefix-less
@@ -196,8 +197,8 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
  * Scaffolds the default tokens CSS file under the engine and registers
  * its path in `fireforge.json`'s `patchLint.rawColorAllowlist`. Both
  * operations are skipped silently when the engine directory does not
- * yet exist (a fresh project that hasn't `fireforge download`ed yet);
- * the scaffold is re-driven on the next `furnace init --force`.
+ * yet exist (a fresh project that hasn't `fireforge download`ed yet).
+ * The scaffold is re-driven on the next `furnace init --force`.
  *
  * Returns the scaffolded path when the file was actually created, so
  * the init command can surface it in the summary note.
@@ -257,12 +258,12 @@ async function scaffoldTokensCss(projectRoot) {
     // is owned end-to-end by tooling. Scaffolding and allowlisting it without
     // registering leaves the very next `fireforge status` correctly flagging
     // it as unmanaged + unregistered while `furnace deploy --dry-run` reports
-    // nothing to deploy — a documented init command turning a clean project
+    // nothing to deploy, a documented init command turning a clean project
     // unclean. The CSS lives at the canonical
     // `browser/themes/shared/<binaryName>-tokens.css` path the shared-CSS rule
     // already targets, so it gets the same
     // `skin/classic/browser/<name>.css (../shared/<name>.css)` entry as any
-    // other shared CSS. Idempotent — `furnace init --force` against a
+    // other shared CSS. It is idempotent: `furnace init --force` against a
     // registered tree is a no-op.
     try {
         const fileBase = `${forgeConfig.binaryName}-tokens.css`;

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

@@ -22,8 +22,8 @@ async function getHealthIndicator(componentDir, type, name, appliedChecksums) {
     }
     catch {
         // A race with `furnace remove`, filesystem permission change, or a
-        // transient IO failure must not crash the entire `list -v` output —
-        // render a degraded state so the rest of the table still shows.
+        // transient IO failure must not crash the entire `list -v` output, so
+        // render a degraded state and the rest of the table still shows.
         return formatErrorText('unavailable');
     }
 }

package/dist/src/commands/furnace/override.d.ts

@@ -8,7 +8,7 @@ import type { FurnaceOverrideOptions } from '../../types/commands/index.js';
 export declare function furnaceOverrideCommand(projectRoot: string, name?: string, options?: FurnaceOverrideOptions): Promise<void>;
 /**
  * Creates multiple overrides in a single invocation. Each component is validated
- * and created sequentially; failures on one component do not block the rest.
+ * and created sequentially. Failures on one component do not block the rest.
  * @param projectRoot - Root directory of the project
  * @param names - Component tag names to override
  * @param options - CLI options applied to all overrides

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

@@ -4,7 +4,7 @@ import { dirname, join } from 'node:path';
 import { select, text } from '@clack/prompts';
 import { getProjectPaths, loadConfig, loadState } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
-import { createDefaultFurnaceConfig, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
+import { getFurnacePaths, writeFurnaceConfig } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
 import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
@@ -16,25 +16,14 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { copyFile, ensureDir, pathExists, writeJson } from '../../utils/fs.js';
 import { cancel, info, intro, isCancel, note, outro, warn } from '../../utils/logger.js';
-async function loadAuthoringFurnaceConfig(projectRoot) {
-    if (await furnaceConfigExists(projectRoot)) {
-        return loadFurnaceConfig(projectRoot);
-    }
-    return createDefaultFurnaceConfig();
-}
+import { loadAuthoringFurnaceConfig } from './authoring-config.js';
 /**
  * Copies the source files needed for a new override into the workspace.
- * @param engineDir - Absolute path to the engine checkout
- * @param srcDir - Original component directory in the engine checkout
- * @param destDir - Destination override directory in the workspace
- * @param componentName - Custom element tag name being overridden
- * @param hasFTL - Whether the component ships a localized `.ftl` file
- * @param overrideType - Requested override mode
- * @param ftlDir - Engine-relative directory the shared `.ftl` deploys into
- * @param journal - Rollback journal every write is recorded in
+ * @param options - See {@link CopyOverrideFilesOptions}
  * @returns Filenames copied into the override directory
  */
-async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasFTL, overrideType, ftlDir, journal) {
+async function copyOverrideFiles(options) {
+    const { engineDir, srcDir, destDir, componentName, hasFTL, overrideType, ftlDir, journal } = options;
     await ensureDir(destDir);
     const entries = await readdir(srcDir, { withFileTypes: true });
     const copiedFiles = [];
@@ -90,10 +79,11 @@ async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasF
  * override entry. Re-reads the current on-disk furnace.json inside the
  * operation lock and splices the new entry onto the fresh state, so two
  * concurrent `furnace override` commands cannot race their read-modify-write
- * cycles into a single surviving entry — otherwise both report success and
+ * cycles into a single surviving entry. Otherwise both report success and
  * furnace.json keeps only the second writer's.
  */
-async function saveOverrideConfig(projectRoot, destDir, componentName, overrideType, description, details, firefoxVersion, journal, baseCommit) {
+async function saveOverrideConfig(options) {
+    const { projectRoot, destDir, componentName, overrideType, description, details, firefoxVersion, journal, baseCommit, } = options;
     const overrideJson = {
         type: overrideType,
         description,
@@ -106,8 +96,8 @@ async function saveOverrideConfig(projectRoot, destDir, componentName, overrideT
     await writeJson(overrideJsonPath, overrideJson);
     // Re-read the current furnace.json inside the lock. The outer caller
     // loaded a snapshot before entering `runFurnaceMutation`, but another
-    // furnace mutation (override / init / sync) may have landed in between
-    // — writing back the stale snapshot would drop that concurrent write.
+    // furnace mutation (override / init / sync) may have landed in between,
+    // and writing back the stale snapshot would drop that concurrent write.
     const freshConfig = await loadAuthoringFurnaceConfig(projectRoot);
     freshConfig.overrides[componentName] = {
         type: overrideType,
@@ -138,9 +128,28 @@ async function performOverrideMutations(args) {
         ctx.registerJournal(journal);
         recordCreatedDir(journal, args.destDir);
         try {
-            const filesCopied = await copyOverrideFiles(args.engineDir, args.srcDir, args.destDir, args.componentName, args.details.hasFTL, args.overrideType, args.ftlDir, journal);
+            const filesCopied = await copyOverrideFiles({
+                engineDir: args.engineDir,
+                srcDir: args.srcDir,
+                destDir: args.destDir,
+                componentName: args.componentName,
+                hasFTL: args.details.hasFTL,
+                overrideType: args.overrideType,
+                ftlDir: args.ftlDir,
+                journal,
+            });
             await snapshotFile(journal, args.furnacePaths.furnaceConfig);
-            await saveOverrideConfig(args.projectRoot, args.destDir, args.componentName, args.overrideType, args.description, args.details, args.firefoxVersion, journal, args.baseCommit);
+            await saveOverrideConfig({
+                projectRoot: args.projectRoot,
+                destDir: args.destDir,
+                componentName: args.componentName,
+                overrideType: args.overrideType,
+                description: args.description,
+                details: args.details,
+                firefoxVersion: args.firefoxVersion,
+                journal,
+                baseCommit: args.baseCommit,
+            });
             return filesCopied;
         }
         catch (error) {
@@ -155,11 +164,11 @@ async function performOverrideMutations(args) {
 }
 /**
  * Throws if `componentName` is already classified as something `override`
- * cannot coexist with. A stock-bucket entry is NOT a hard conflict — the
- * whole point of `override` is to fork a component out of the stock bucket
- * into the overrides bucket, and requiring manual `furnace.json` surgery
- * first was a pure footgun. `promoteStockToOverrideIfNeeded` handles the
- * transition in-memory; this guard only rejects the other two cases where
+ * cannot coexist with. A stock-bucket entry is not a hard conflict:
+ * `override` exists to fork a component out of the stock bucket into the
+ * overrides bucket, and requiring manual `furnace.json` surgery first was
+ * a footgun. `promoteStockToOverrideIfNeeded` handles the
+ * transition in-memory. This guard only rejects the other two cases where
  * a rename actually contradicts existing state.
  */
 function assertNoComponentCollision(config, componentName) {
@@ -176,7 +185,7 @@ function assertNoComponentCollision(config, componentName) {
  * the subsequent `writeFurnaceConfig` inside the mutation phase persists
  * the stock → override promotion atomically alongside the new override
  * entry. Returns true when a promotion happened so the caller can emit a
- * one-line note; false when the component was not stock.
+ * one-line note. Returns false when the component was not stock.
  */
 function promoteStockToOverrideIfNeeded(config, componentName) {
     const index = config.stock.indexOf(componentName);
@@ -194,9 +203,9 @@ function promoteStockToOverrideIfNeeded(config, componentName) {
 export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
     const isInteractive = stdioIsInteractive();
     intro('Furnace Override');
-    // --- Validate config-independent inputs BEFORE auto-creating furnace.json
+    // --- Validate config-independent inputs before auto-creating furnace.json
     // so a failed authoring command never strands a fresh config in the
-    // project root. CLI-supplied name is checked here; the engine directory
+    // project root. CLI-supplied name is checked here. The engine directory
     // and component-resolution checks below also have no config dependency.
     const paths = getProjectPaths(projectRoot);
     if (name !== undefined && !CUSTOM_ELEMENT_TAG_PATTERN.test(name)) {
@@ -217,7 +226,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
     // --- Resolve component name ---
     let componentName = name;
     if (!componentName) {
-        // Interactive prompt path; non-interactive missing-name was rejected above.
+        // Interactive prompt path. Non-interactive missing-name was rejected above.
         const allComponents = await scanWidgetsDirectory(paths.engine, ftlDir);
         const available = allComponents.filter((c) => !(c.tagName in config.overrides));
         if (available.length === 0) {
@@ -327,7 +336,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
 }
 /**
  * Creates multiple overrides in a single invocation. Each component is validated
- * and created sequentially; failures on one component do not block the rest.
+ * and created sequentially. Failures on one component do not block the rest.
  * @param projectRoot - Root directory of the project
  * @param names - Component tag names to override
  * @param options - CLI options applied to all overrides
@@ -353,8 +362,8 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
     const state = await loadState(projectRoot);
     // Check for duplicates and pre-existing classifications across every
     // bucket in furnace.json. A stock-bucket entry is promoted in-memory
-    // here (see `promoteStockToOverrideIfNeeded`) rather than rejected —
-    // the operator's intent is to fork that specific stock component. The
+    // here (see `promoteStockToOverrideIfNeeded`) rather than rejected,
+    // since the operator's intent is to fork that specific stock component. The
     // collision guard still rejects name conflicts that would double-
     // classify a tag in a way `writeFurnaceConfig` cannot safely produce
     // (two overrides, or an override + custom).

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

@@ -13,8 +13,8 @@ import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
 /**
- * Runs the two teardown steps — `cleanStories` and the rollback-journal
- * restore — independently, collecting whatever errors either step throws.
+ * Runs the two teardown steps (`cleanStories` and the rollback-journal
+ * restore) independently, collecting whatever errors either step throws.
  * Both steps must run regardless of the other's outcome, because each
  * operates on a different part of engine state and skipping one leaves
  * the engine in a worse position than a single-step failure.
@@ -72,10 +72,10 @@ function reportPreviewStagingFailures(stageResult) {
 }
 /**
  * Filenames emitted by the Firefox build backend (not by Storybook's npm
- * package set) — their absence means `mach build` has not produced its
+ * package set). Their absence means `mach build` has not produced its
  * post-configure artifacts, which is a different failure mode from a missing
  * Storybook workspace dependency tree. A
- * `FileNotFoundError: [...] chrome-map.json` AFTER a successful Storybook
+ * `FileNotFoundError: [...] chrome-map.json` after a successful Storybook
  * `npm install` is the case a dep-focused heuristic misdiagnoses, sending
  * the operator back to `--install`. The pattern list is narrow on purpose so
  * the backend-rebuild hint only fires when it is confident.
@@ -101,7 +101,7 @@ export function buildStorybookFailureMessage(output, installRequested) {
         ? 'Try running "python3 ./mach storybook upgrade" manually in the engine directory.'
         : 'Run "fireforge furnace preview --install" to bootstrap Storybook dependencies, or run "python3 ./mach storybook upgrade" manually in engine/.';
     const hasFileNotFoundSignal = /(ENOENT|No such file or directory|FileNotFoundError)/i.test(output);
-    // Check backend-artifact signal first — a missing chrome-map.json looks
+    // Check the backend-artifact signal first: a missing chrome-map.json looks
     // like any other "No such file" error to a naïve regex, but the fix is
     // to rerun `fireforge build`, not to reinstall Storybook dependencies.
     if (hasFileNotFoundSignal && BACKEND_ARTIFACT_PATTERNS.some((p) => p.test(output))) {
@@ -122,7 +122,7 @@ export function buildStorybookFailureMessage(output, installRequested) {
  * Preflights the Firefox build + toolchain prerequisites `mach storybook`
  * quietly assumes. Without it, preview stages components and launches a
  * ~1000-package `mach storybook upgrade` npm install before the backend
- * surfaces a "missing chrome-map.json" / Cargo-config failure; this refuses
+ * surfaces a "missing chrome-map.json" / Cargo-config failure. This refuses
  * fast and leaves the workspace untouched.
  *
  * @param engineDir - Resolved engine directory
@@ -143,7 +143,7 @@ async function assertPreviewPrerequisites(engineDir) {
     // follow the remediation instruction ("run bootstrap then rerun preview")
     // hit the same refusal on the retry, because `fireforge bootstrap` alone
     // produces only `.in`. Either name is sufficient to prove the Rust
-    // toolchain is registered; the stronger `hasBuildArtifacts` check above
+    // toolchain is registered. The stronger `hasBuildArtifacts` check above
     // already guards against a completely un-configured tree.
     const cargoConfigPath = join(engineDir, '.cargo', 'config.toml');
     const cargoConfigInPath = join(engineDir, '.cargo', 'config.toml.in');
@@ -158,10 +158,10 @@ async function assertPreviewPrerequisites(engineDir) {
 /**
  * Emits a framing banner when the Storybook workspace has not yet had its npm
  * dependencies installed. `mach storybook` drives the install internally and
- * prints ELSPROBLEMS / UNMET DEPENDENCY lines verbatim; without this banner
+ * prints ELSPROBLEMS / UNMET DEPENDENCY lines verbatim. Without this banner
  * operators reliably read the npm output as a failure.
  *
- * Skipped when `--install` was explicitly requested — that path already runs
+ * Skipped when `--install` was explicitly requested, since that path runs
  * `mach storybook upgrade` before the preview launches, so the npm output
  * for the subsequent `mach storybook` invocation is a no-op.
  */
@@ -177,9 +177,9 @@ async function announceStorybookFirstRunIfNeeded(engineDir, installRequested) {
 /**
  * Surfaces an explicit success banner after a clean mach-storybook
  * exit so the operator's scrollback visually terminates the npm noise
- * from the first-run install. Only fires on expected exit codes — non-
- * zero cases fall through to the existing
- * `buildStorybookFailureMessage` classification.
+ * from the first-run install. Only fires on expected exit codes. Non-zero
+ * cases fall through to the existing `buildStorybookFailureMessage`
+ * classification.
  */
 function announceStorybookCleanExitIfApplicable(exitCode) {
     if (exitCode === 0 || exitCode === 130 || exitCode === 143) {
@@ -212,9 +212,9 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
     await assertPreviewPrerequisites(paths.engine);
     let previewResult;
     // True once we are about to (or have) written to engine/.../stories/furnace.
-    // Intentionally set BEFORE `syncStories` is awaited so a mid-sync failure
-    // still triggers `cleanStories` during teardown. `cleanStories` is a
-    // full-directory wipe, so it is correct to run against partial state —
+    // Set before `syncStories` is awaited so a mid-sync failure still
+    // triggers `cleanStories` during teardown. `cleanStories` is a
+    // full-directory wipe, so it is correct to run against partial state,
     // including state with zero files, where it is a cheap no-op.
     let storiesCleanupRequired = false;
     let previewJournal;
@@ -264,7 +264,7 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
                 stageSpinner.stop(`Staged ${stageResult.applied.length} component${stageResult.applied.length === 1 ? '' : 's'} for preview`);
             }
             // Sync story files. Set the cleanup flag before the await so a partial
-            // write failure still triggers the teardown wipe — `syncStories` writes
+            // write failure still triggers the teardown wipe. `syncStories` writes
             // files incrementally with no internal cleanup of its own.
             const syncSpinner = spinner('Syncing component stories...');
             storiesCleanupRequired = true;
@@ -299,7 +299,7 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
         // cleanStories must not prevent the journal restore, and vice versa.
         // Running teardown in a `finally` that calls
         // `restoreRollbackJournalOrThrow` throws synchronously, bypassing the
-        // primary error and skipping downstream handling — the engine is left
+        // primary error and skipping downstream handling, so the engine is left
         // with staged files and the user gets a teardown message with no
         // guidance. Both failures are collected instead and, if anything went
         // wrong, a `pendingRepair` marker is persisted for `fireforge doctor` to

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

@@ -90,8 +90,8 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
         }
         return { results: [], currentVersion };
     }
-    // Prefer the per-override baseCommit (survives download --force); fall back
-    // to the project-wide value for overrides created before this field existed.
+    // Prefer the per-override baseCommit (survives download --force). Fall
+    // back to the project-wide value for overrides created before this field existed.
     const baseCommit = overrideConfig.baseCommit ?? state.baseCommit;
     if (!baseCommit) {
         throw new FurnaceError('Cannot refresh: baseCommit not found. Re-run "fireforge download" to establish a baseline, ' +
@@ -126,7 +126,15 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
             for (const entry of overrideFiles) {
                 const overridePath = join(overrideDir, entry.name);
                 const engineRelPath = getOverrideEngineTargetPath(paths.engine, overrideConfig, entry.name, ftlDir).slice(paths.engine.length + 1);
-                const result = await refreshOverrideFile(paths.engine, overridePath, engineRelPath, baseCommit, entry.name, dryRun, strategy);
+                const result = await refreshOverrideFile({
+                    engineDir: paths.engine,
+                    overridePath,
+                    engineRelPath,
+                    baseCommit,
+                    fileName: entry.name,
+                    dryRun,
+                    strategy,
+                });
                 fileResults.push(result);
             }
             // Update baseVersion and baseCommit on clean merge (not dry-run, no conflicts)
@@ -145,7 +153,7 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
             return fileResults;
         }
         catch (error) {
-            // A dry run wrote nothing, so there is no journal to restore — it
+            // A dry run wrote nothing, so there is no journal to restore. It
             // rethrows without touching the lifecycle wrapper.
             if (!dryRun) {
                 return await completeJournalRollback(ctx, journal, error, {
@@ -163,7 +171,7 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
 /**
  * Refreshes every override sequentially, tallying merged/conflict/
  * unchanged file counts. Per-override errors are expected (warned and
- * recorded as failures) and do not abort the batch; only an error that
+ * recorded as failures) and do not abort the batch. Only an error that
  * escapes this function entirely warrants the caller's journal rollback.
  */
 async function runBatchRefresh(projectRoot, overrideNames, options) {
@@ -224,7 +232,7 @@ export async function furnaceRefreshCommand(projectRoot, name, options = {}) {
     if (name && refreshAll) {
         throw new FurnaceError('Cannot specify both a component name and --all. Use one or the other.');
     }
-    // Verify engine exists — refresh reads engine files for three-way merge
+    // Verify engine exists: refresh reads engine files for three-way merge
     // and --reset-base reads engine HEAD. Without this check, the user gets
     // an obscure git error instead of a clear precondition message.
     await assertFurnaceEngineReady(projectRoot);
@@ -257,7 +265,7 @@ export async function furnaceRefreshCommand(projectRoot, name, options = {}) {
     }
     // Snapshot furnace.json before the batch loop so an unexpected failure
     // (process crash, unhandled error) can be recovered from. Per-component
-    // errors caught below are expected and do not trigger a restore — only
+    // errors caught below are expected and do not trigger a restore. Only
     // an error that escapes the loop entirely warrants rolling back.
     const batchJournal = dryRun ? undefined : createRollbackJournal();
     if (batchJournal) {

package/dist/src/commands/furnace/remove-mutations.d.ts

@@ -1,9 +1,8 @@
-import type { loadFurnaceConfig } from '../../core/furnace-config.js';
-import { getFurnacePaths } from '../../core/furnace-config.js';
+import type { FurnacePaths } from '../../core/furnace-config.js';
 import type { RollbackJournal } from '../../core/furnace-rollback.js';
-import type { FurnaceState } from '../../types/furnace.js';
+import type { FurnaceConfig, FurnaceState } from '../../types/furnace.js';
 /**
- * Engine-side and workspace-side removal for an OVERRIDE component.
+ * Engine-side and workspace-side removal for an override component.
  *
  * Runs inside the caller's rollback journal rather than opening its own, so
  * a failure anywhere in the remove still restores the whole operation as a
@@ -14,15 +13,15 @@ export declare function performOverrideRemovalMutations(args: {
     paths: {
         engine: string;
     };
-    furnacePaths: ReturnType<typeof getFurnacePaths>;
-    freshConfig: Awaited<ReturnType<typeof loadFurnaceConfig>>;
+    furnacePaths: FurnacePaths;
+    freshConfig: FurnaceConfig;
     freshState: FurnaceState;
     ftlDir: string;
     journal: RollbackJournal;
 }): Promise<void>;
 /**
- * Engine-side and workspace-side removal for a CUSTOM component.
- * Sibling of {@link performOverrideRemovalMutations}; see its note.
+ * Engine-side and workspace-side removal for a custom component.
+ * Sibling of {@link performOverrideRemovalMutations}. See its note.
  */
 export declare function performCustomRemovalMutations(args: {
     projectRoot: string;
@@ -30,8 +29,8 @@ export declare function performCustomRemovalMutations(args: {
     paths: {
         engine: string;
     };
-    furnacePaths: ReturnType<typeof getFurnacePaths>;
-    freshConfig: Awaited<ReturnType<typeof loadFurnaceConfig>>;
+    furnacePaths: FurnacePaths;
+    freshConfig: FurnaceConfig;
     ftlDir: string;
     journal: RollbackJournal;
 }): Promise<void>;

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

@@ -7,7 +7,7 @@
  * `furnaceRemoveCommand` at the per-function cap. Extracting them inside the
  * same file would trade a function-length problem for a file-length one.
  *
- * Both run inside the CALLER's rollback journal rather than opening their
+ * Both run inside the caller's rollback journal rather than opening their
  * own, so a failure anywhere in the remove still restores the whole
  * operation as a single unit.
  */
@@ -16,7 +16,6 @@ import { join } from 'node:path';
 import { removeCustomFtlJarMnEntry } from '../../core/furnace-apply-ftl.js';
 import { getOverrideEngineTargetPath, isOverrideCopyCandidate, restoreOverrideFileToBaseline, } from '../../core/furnace-apply-helpers.js';
 import { extractComponentChecksums } from '../../core/furnace-checksum-utils.js';
-import { getFurnacePaths } from '../../core/furnace-config.js';
 import { removeCustomElementRegistration, removeJarMnEntries, } from '../../core/furnace-registration.js';
 import { snapshotDir, snapshotFile } from '../../core/furnace-rollback.js';
 import { isGitRepository } from '../../core/git.js';
@@ -28,12 +27,12 @@ import { removeDeployedCustomFiles } from './remove-state.js';
 /**
  * Restores every override-deployed file in `engine/` to its pristine HEAD
  * state, inverting what `applyOverrideComponent` would have written. Files that
- * existed in HEAD are restored via `git restore`; files the override
+ * existed in HEAD are restored via `git restore`. Files the override
  * introduced (not in HEAD) are deleted outright.
  *
- * The restore set is the **union** of (a) files currently in the override
- * workspace directory and (b) filenames recorded in `previousChecksumKeys`
- * — i.e. files we know we deployed last time, even if the developer has
+ * The restore set is the union of (a) files currently in the override
+ * workspace directory and (b) filenames recorded in `previousChecksumKeys`,
+ * i.e. files we know we deployed last time, even if the developer has
  * since deleted them from the workspace. Without (b), a workspace deletion
  * leaves an orphaned engine copy that `furnace remove` would never see.
  *
@@ -44,14 +43,15 @@ import { removeDeployedCustomFiles } from './remove-state.js';
 async function restoreOverrideEngineFiles(engineDir, overrideDir, overrideConfig, previousChecksumKeys, ftlDir, journal) {
     // Engine-as-git is a hard precondition for restoration: git HEAD is the only
     // honest oracle for "what was there before the override". If the engine is
-    // not a git repo we refuse rather than silently leaving files behind — the
-    // previous warn-and-continue behaviour is exactly what this fix removes.
+    // not a git repo we refuse rather than silently leaving files behind. The
+    // previous behaviour was to warn and continue, which is what this fix
+    // removes.
     if (!(await isGitRepository(engineDir))) {
         throw new FurnaceError('Cannot restore override files: engine is not a git repository. Run "fireforge download" to initialise it.');
     }
     // Build the union of "files we still see on disk" and "files state.json
     // claims we deployed". The state set is the only authority for files that
-    // were deployed and later deleted from the workspace; the workspace set is
+    // were deployed and later deleted from the workspace. The workspace set is
     // the only authority for files added since last apply that have not yet
     // been recorded in state. We need both.
     const fileSet = new Set();
@@ -81,7 +81,7 @@ async function restoreOverrideEngineFiles(engineDir, overrideDir, overrideConfig
     return { restored, removed };
 }
 /**
- * Engine-side and workspace-side removal for an OVERRIDE component.
+ * Engine-side and workspace-side removal for an override component.
  *
  * Runs inside the caller's rollback journal rather than opening its own, so
  * a failure anywhere in the remove still restores the whole operation as a
@@ -91,10 +91,10 @@ export async function performOverrideRemovalMutations(args) {
     const { name, paths, furnacePaths, freshConfig, freshState, ftlDir, journal } = args;
     const overrideConfig = freshConfig.overrides[name];
     const dir = join(furnacePaths.overridesDir, name);
-    // Restore deployed engine files BEFORE removing the workspace
+    // Restore deployed engine files before removing the workspace
     // directory. The restore set is the union of (a) files currently in
-    // the workspace and (b) files state.json says we deployed last time
-    // — without (b), source-side deletions would orphan engine copies
+    // the workspace and (b) files state.json says we deployed last time.
+    // Without (b), source-side deletions would orphan engine copies
     // that this command can never see again.
     if (overrideConfig?.basePath) {
         const previousKeys = Object.keys(extractComponentChecksums(freshState.appliedChecksums, 'override', name));
@@ -113,8 +113,8 @@ export async function performOverrideRemovalMutations(args) {
     }
 }
 /**
- * Engine-side and workspace-side removal for a CUSTOM component.
- * Sibling of {@link performOverrideRemovalMutations}; see its note.
+ * Engine-side and workspace-side removal for a custom component.
+ * Sibling of {@link performOverrideRemovalMutations}. See its note.
  */
 export async function performCustomRemovalMutations(args) {
     const { projectRoot, name, paths, furnacePaths, freshConfig, ftlDir, journal } = args;
@@ -141,12 +141,12 @@ export async function performCustomRemovalMutations(args) {
         await removeDir(dir);
         info(`Deleted components/custom/${name}/`);
     }
-    // Clean up deployed files in engine (per-file — see helper doc).
+    // Clean up deployed files in engine (per-file, see helper doc).
     if (customConfig?.targetPath) {
         await removeDeployedCustomFiles(projectRoot, paths.engine, name, customConfig.targetPath, journal);
     }
     // Localized components deploy a .ftl outside targetPath into the
-    // shared Fluent tree; apply writes it, so remove must delete it too
+    // shared Fluent tree. Apply writes it, so remove must delete it too
     // or the locale payload is orphaned.
     if (customConfig?.localized) {
         const ftlRel = join(ftlDir, `${name}.ftl`);
@@ -155,12 +155,12 @@ export async function performCustomRemovalMutations(args) {
             await snapshotFile(journal, ftlPath);
             await removeFile(ftlPath);
             // `ftlRel` is a native join, so on Windows an interpolated
-            // `engine/${ftlRel}` renders as `engine/toolkit\locales\...` — one
+            // `engine/${ftlRel}` renders as `engine/toolkit\locales\...`, one
             // message with both separators. Print the engine-relative form.
             info(`Deleted localized file engine/${normalizePathSlashes(ftlRel)}`);
         }
         // Drop the locale jar.mn chrome registration that `applyCustomFtlFile`
-        // wrote during deploy — otherwise the engine is left with a
+        // wrote during deploy. Otherwise the engine is left with a
         // `locale/.../${name}.ftl` entry pointing at a file just deleted, which
         // breaks the next package-manifest validation.
         await removeCustomFtlJarMnEntry(paths.engine, `${name}.ftl`, ftlDir, customConfig, journal);

package/dist/src/commands/furnace/remove-state.d.ts

@@ -10,7 +10,7 @@ export declare function dropChecksumsByPrefix(state: FurnaceState, prefix: strin
  * Per-file, never a recursive `removeDir` of the whole directory: nothing
  * stops two components from sharing a targetPath (or a hand-edited config
  * from pointing at an upstream-shared directory), and the recursive delete
- * permanently destroyed the co-located files on success — the rollback
+ * permanently destroyed the co-located files on success. The rollback
  * journal only protects the failure path. Deployed files come from the
  * component's state checksums, falling back to the conventional
  * `<name>.{mjs,css,ftl}` set when state carries no record (cleared by a

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

@@ -24,7 +24,7 @@ export function dropChecksumsByPrefix(state, prefix) {
  * Per-file, never a recursive `removeDir` of the whole directory: nothing
  * stops two components from sharing a targetPath (or a hand-edited config
  * from pointing at an upstream-shared directory), and the recursive delete
- * permanently destroyed the co-located files on success — the rollback
+ * permanently destroyed the co-located files on success. The rollback
  * journal only protects the failure path. Deployed files come from the
  * component's state checksums, falling back to the conventional
  * `<name>.{mjs,css,ftl}` set when state carries no record (cleared by a