@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -3,6 +3,7 @@ import { stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, normalize } from 'node:path';
 import { text } from '@clack/prompts';
 import { getProjectPaths, loadConfig, mutateConfig, writeConfig } from '../../core/config.js';
+import { stdioIsInteractive } from '../../core/destructive.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { DEFAULT_LICENSE } from '../../core/license-headers.js';
 import { registerSharedCSS } from '../../core/register-shared-css.js';
@@ -15,17 +16,15 @@ import { cancel, info, intro, isCancel, note, outro, success, warn } from '../..
 /**
  * File extensions that are definitely FTL resources (not locale
  * directories). A value ending in one of these is almost certainly the
- * result of the operator pointing at a single FTL file instead of the
- * locale directory that contains it.
+ * result of the operator pointing at a single FTL file instead of the locale
+ * directory that contains it.
  *
- * 2026-04-21 eval: `furnace init --ftl-base-path browser/forgefresh.ftl`
- * produced a misleading success path — the subsequent
- * `furnace create --localized` scaffolded an `.mjs` referencing
- * `insertFTLIfNeeded("<name>.ftl")` while furnace.json had no component
- * entry, leaving the scaffold orphaned. Switching to a locale directory
- * (`toolkit/locales/en-US/toolkit/global`) fixed the downstream path.
- * Rejecting file-shaped values up-front keeps the operator on the
- * correct path before any partial state is written.
+ * `furnace init --ftl-base-path browser/<name>.ftl` otherwise produces a
+ * misleading success path: the subsequent `furnace create --localized`
+ * scaffolds an `.mjs` referencing `insertFTLIfNeeded("<name>.ftl")` while
+ * furnace.json has no component entry, leaving the scaffold orphaned.
+ * Rejecting file-shaped values up-front keeps the operator on the correct
+ * path before any partial state is written.
  */
 const FTL_FILE_EXTENSIONS = new Set(['.ftl', '.properties', '.dtd']);
 function hasFtlFileExtension(value) {
@@ -112,13 +111,13 @@ 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. The 2026-04-21 eval initialised Furnace, added
-    // tokens, ran coverage, and got `0 tokens / N unknown` — the prefix
-    // default was absent and the scan had nothing to key off. Loading
-    // fireforge.json here is best-effort: a project without one (e.g.
-    // mid-setup) falls through to the prefix-less default, and
-    // `token coverage` emits the existing "no tokenPrefix" warning.
+    // fireforge.json's binaryName so `token coverage` sees real tokens on the
+    // 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
+    // default, and `token coverage` emits its existing "no tokenPrefix"
+    // warning.
     let derivedBinaryName;
     try {
         const fireForgeConfig = await loadConfig(projectRoot);
@@ -129,7 +128,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
         // rare but not forbidden. Skip the prefix default in that case.
     }
     const config = createDefaultFurnaceConfig(derivedBinaryName ? { binaryName: derivedBinaryName } : {});
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     const engineForValidation = (await pathExists(paths.engine)) ? paths.engine : undefined;
     // Resolve componentPrefix
     if (options.prefix !== undefined) {
@@ -231,12 +230,11 @@ async function scaffoldTokensCss(projectRoot) {
         info(`Tokens CSS already present at engine/${tokensCssPath}; leaving it untouched.`);
     }
     // Registering the tokens file in `patchLint.rawColorAllowlist` is the
-    // complement to the scaffold itself: the file exists specifically to
-    // carry raw color literals, and without the allowlist entry the very
-    // first `fireforge lint` run against a post-`token add` workspace
-    // fails on raw-color-value issues for tokens the operator just
-    // created. The add is idempotent, so re-running `furnace init --force`
-    // does not duplicate the entry.
+    // complement to the scaffold itself: the file exists specifically to carry
+    // raw color literals, and without the allowlist entry the first
+    // `fireforge lint` after a `token add` fails on raw-color-value issues for
+    // tokens the operator just created. The add is idempotent, so re-running
+    // `furnace init --force` does not duplicate the entry.
     try {
         const existingAllowlist = forgeConfig.patchLint?.rawColorAllowlist ?? [];
         if (!existingAllowlist.includes(tokensCssPath)) {
@@ -252,18 +250,17 @@ async function scaffoldTokensCss(projectRoot) {
         warn(`Could not register tokens CSS in patchLint.rawColorAllowlist: ${toError(error).message}. ` +
             `Add "${tokensCssPath}" manually under patchLint.rawColorAllowlist in fireforge.json if lint flags its contents.`);
     }
-    // 2026-04-26 eval Finding 2: register the tokens CSS in
-    // browser/themes/shared/jar.inc.mn so the file is owned end-to-end by
-    // tooling. Pre-fix, `furnace init` only scaffolded + allowlisted the
-    // file, so the very next `fireforge status` correctly flagged it as
-    // unmanaged + unregistered and `furnace deploy --dry-run` reported
-    // nothing to deploy — a documented init command turned a clean
-    // project into an unclean one. The CSS lives at the canonical
-    // `browser/themes/shared/<binaryName>-tokens.css` path that the
-    // shared-CSS rule already targets, so the tokens file gets the same
-    // `skin/classic/browser/<name>.css (../shared/<name>.css)` jar.inc.mn
-    // entry as any other shared CSS. Idempotent — running
-    // `furnace init --force` against a registered tree is a no-op.
+    // Register the tokens CSS in browser/themes/shared/jar.inc.mn so the file
+    // 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
+    // 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
+    // registered tree is a no-op.
     try {
         const fileBase = `${forgeConfig.binaryName}-tokens.css`;
         const result = await registerSharedCSS(paths.engine, fileBase, undefined, false);

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

@@ -3,11 +3,13 @@ import { readdir } from 'node:fs/promises';
 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 { resolveFtlDir } from '../../core/furnace-constants.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
-import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
+import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getComponentDetails, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
@@ -22,9 +24,14 @@ async function loadAuthoringFurnaceConfig(projectRoot) {
 }
 /**
  * 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
  * @returns Filenames copied into the override directory
  */
 async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasFTL, overrideType, ftlDir, journal) {
@@ -81,10 +88,10 @@ async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasF
 /**
  * Writes override metadata to disk and updates furnace.json with the new
  * 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 (eval 2: parallel overrides
- * both reported success but furnace.json kept only the second writer).
+ * 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
+ * furnace.json keeps only the second writer's.
  */
 async function saveOverrideConfig(projectRoot, destDir, componentName, overrideType, description, details, firefoxVersion, journal, baseCommit) {
     const overrideJson = {
@@ -137,17 +144,12 @@ async function performOverrideMutations(args) {
             return filesCopied;
         }
         catch (error) {
-            // This body owns its rollback end to end, so tell the lifecycle
-            // wrapper not to restore the same journal again on the way out.
-            ctx.markRolledBack();
-            try {
-                await restoreRollbackJournalOrThrow(journal, `Failed to override component "${args.componentName}"`);
-            }
-            catch (rollbackError) {
-                await recordFurnaceRollbackFailure(args.projectRoot, 'override-rollback', `component "${args.componentName}": ${toError(rollbackError).message}`);
-                throw rollbackError;
-            }
-            throw error;
+            return await completeJournalRollback(ctx, journal, error, {
+                projectRoot: args.projectRoot,
+                operation: 'override-rollback',
+                failureMessage: `Failed to override component "${args.componentName}"`,
+                subject: `component "${args.componentName}"`,
+            });
         }
     });
 }
@@ -190,7 +192,7 @@ function promoteStockToOverrideIfNeeded(config, componentName) {
  * @param options - CLI options for non-interactive mode
  */
 export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     intro('Furnace Override');
     // --- Validate config-independent inputs BEFORE auto-creating furnace.json
     // so a failed authoring command never strands a fresh config in the
@@ -205,9 +207,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
             'Usage: fireforge furnace override <name> -t <type> -d "description"', 'name');
     }
     // Verify engine/ exists (config-independent precondition)
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
+    await assertFurnaceEngineReady(projectRoot);
     // Load the current config without auto-creating a new furnace.json. A user
     // cancelling out of the interactive prompts should not leave a fresh config
     // behind in an otherwise untouched project.
@@ -334,14 +334,12 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
  */
 export async function furnaceBatchOverrideCommand(projectRoot, names, options = {}) {
     intro(`Furnace Override (batch: ${names.length} components)`);
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     if (!options.type && !isInteractive) {
         throw new InvalidArgumentError('Override type is required for batch override in non-interactive mode. Use -t css-only or -t full.', 'type');
     }
     const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
+    await assertFurnaceEngineReady(projectRoot);
     // Validate all names upfront before any mutations
     for (const name of names) {
         if (!CUSTOM_ELEMENT_TAG_PATTERN.test(name)) {

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

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
-import { getProjectPaths } from '../../core/config.js';
 import { applyAllComponents } from '../../core/furnace-apply.js';
-import { furnaceConfigExists, loadFurnaceConfig, updateFurnaceState, } from '../../core/furnace-config.js';
+import { updateFurnaceState } from '../../core/furnace-config.js';
 import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { restoreRollbackJournal } from '../../core/furnace-rollback.js';
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { cleanStories, syncStories } from '../../core/furnace-stories.js';
@@ -49,14 +49,11 @@ async function runPreviewTeardown(engineDir, storiesCleanupRequired, journal) {
     return errors;
 }
 /**
- * Reports staging failures (component-level errors and per-step errors) to the
- * user and throws a single FurnaceError summarising the failure count.
- * Extracted from `furnacePreviewCommand` to keep that function under the
- * `max-lines-per-function` threshold and to colocate the failure-reporting
- * contract in one place.
+ * Reports staging failures (component-level errors and per-step errors) to
+ * the user and throws a single FurnaceError summarising the failure count.
  *
- * @returns The total failure count if there were any (always non-zero when
- *          this returns; the function throws after logging).
+ * Never returns: it always throws after logging, which is what the `never`
+ * return type states.
  */
 function reportPreviewStagingFailures(stageResult) {
     for (const err of stageResult.errors) {
@@ -76,13 +73,12 @@ 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
- * post-configure artifacts, which is a different failure mode from a
- * missing Storybook workspace dependency tree. The eval log for finding
- * #11 reported `FileNotFoundError: [...] chrome-map.json` *after* a
- * successful Storybook `npm install`, and the pre-0.16 heuristic
- * misdiagnosed it as a dep failure and sent the operator back to
- * `--install`. Pattern list is narrow on purpose so we only surface the
- * backend-rebuild hint when we are confident.
+ * 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
+ * `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.
  */
 const BACKEND_ARTIFACT_PATTERNS = [
     /chrome-map\.json/i,
@@ -124,17 +120,14 @@ export function buildStorybookFailureMessage(output, installRequested) {
 }
 /**
  * Preflights the Firefox build + toolchain prerequisites `mach storybook`
- * quietly assumes. Pre-0.16.0 the preview staged components and launched
- * a ~1000-package `mach storybook upgrade` npm install before the
- * backend surfaced a "missing chrome-map.json" / Cargo-config failure;
- * the preflight below refuses fast and leaves the workspace untouched.
- *
- * Extracted from `furnacePreviewCommand` so the main function stays
- * under the per-function LOC budget as the preflight list grows.
+ * 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
+ * fast and leaves the workspace untouched.
  *
  * @param engineDir - Resolved engine directory
- * @throws FurnaceError when the Firefox build hasn't produced dist/, or
- *         when `.cargo/config.toml` is absent
+ * @throws FurnaceError when the Firefox build has not produced dist/, or
+ *   when `.cargo/config.toml` is absent
  */
 async function assertPreviewPrerequisites(engineDir) {
     const buildCheck = await hasBuildArtifacts(engineDir);
@@ -146,14 +139,12 @@ async function assertPreviewPrerequisites(engineDir) {
     }
     // Accept either `.cargo/config.toml` (post-configure) or
     // `.cargo/config.toml.in` (post-bootstrap template, consumed at
-    // `mach configure` time). Pre-0.16.0 the preflight insisted on the
-    // plain file, but `fireforge bootstrap` alone produces only `.in` —
-    // operators who followed the remediation instruction ("run bootstrap
-    // then rerun preview") hit the same refusal on the retry. Either name
-    // is sufficient to prove the Rust toolchain is registered; the stronger
-    // `hasBuildArtifacts` check above already guards against a completely
-    // un-configured tree, so relaxing this to an OR-check does not weaken
-    // the signal we care about.
+    // `mach configure` time). Insisting on the plain file makes operators who
+    // 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
+    // already guards against a completely un-configured tree.
     const cargoConfigPath = join(engineDir, '.cargo', 'config.toml');
     const cargoConfigInPath = join(engineDir, '.cargo', 'config.toml.in');
     const cargoConfigPresent = (await pathExists(cargoConfigPath)) || (await pathExists(cargoConfigInPath));
@@ -165,15 +156,14 @@ async function assertPreviewPrerequisites(engineDir) {
     }
 }
 /**
- * Emits a framing banner when the Storybook workspace has not yet had
- * its npm dependencies installed. `mach storybook` will drive the
- * install internally and print ELSPROBLEMS / UNMET DEPENDENCY lines
- * verbatim; without this banner operators reliably read the npm output
- * as a failure (2026-04-24 eval Finding 13).
+ * 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
+ * operators reliably read the npm output as a failure.
  *
- * Skipped when `--install` was explicitly requested — that path already
- * runs `mach storybook upgrade` before the preview launches, so the npm
- * output for the subsequent `mach storybook` invocation is a no-op.
+ * Skipped when `--install` was explicitly requested — that path already runs
+ * `mach storybook upgrade` before the preview launches, so the npm output
+ * for the subsequent `mach storybook` invocation is a no-op.
  */
 async function announceStorybookFirstRunIfNeeded(engineDir, installRequested) {
     if (installRequested)
@@ -203,16 +193,7 @@ function announceStorybookCleanExitIfApplicable(exitCode) {
  */
 export async function furnacePreviewCommand(projectRoot, options = {}) {
     intro('Furnace Preview (Storybook)');
-    // Verify engine exists
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
-    // Load furnace config
-    if (!(await furnaceConfigExists(projectRoot))) {
-        throw new FurnaceError('No furnace.json found. Run "fireforge furnace create" or "fireforge furnace override" to get started.');
-    }
-    const config = await loadFurnaceConfig(projectRoot);
+    const { paths, config } = await assertFurnaceReady(projectRoot);
     const stockCount = config.stock.length;
     const overrideCount = Object.keys(config.overrides).length;
     const customCount = Object.keys(config.custom).length;
@@ -226,8 +207,8 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
     if (!(await pathExists(storybookRoot))) {
         throw new FurnaceError('This Firefox checkout does not contain browser/components/storybook. Furnace preview requires the upstream Storybook workspace to exist before stories can be synced.');
     }
-    // Build + toolchain preflight (Finding #9). Extracted into a helper so
-    // the function below stays under the per-function LOC budget.
+    // Build + toolchain preflight, extracted into a helper so the function
+    // below stays under the per-function LOC budget.
     await assertPreviewPrerequisites(paths.engine);
     let previewResult;
     // True once we are about to (or have) written to engine/.../stories/furnace.
@@ -302,10 +283,8 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
                 }
                 installSpinner.stop('Storybook dependencies reinstalled');
             }
-            // 2026-04-24 eval Finding 13: frame the npm noise that `mach
-            // storybook` emits on first-run as expected progress rather than a
-            // failure. The banner-before / banner-after helpers are extracted
-            // so the command body stays under the per-function LOC budget.
+            // Frame the npm noise `mach storybook` emits on first run as expected
+            // progress rather than a failure.
             await announceStorybookFirstRunIfNeeded(paths.engine, options.install ?? false);
             // Start Storybook
             info('Starting Storybook...');
@@ -317,16 +296,17 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
             primaryError = error;
         }
         // Teardown runs unconditionally and never short-circuits: a failure in
-        // cleanStories must not prevent the journal restore, and vice versa. The
-        // previous implementation ran teardown in a `finally` block that called
-        // `restoreRollbackJournalOrThrow`, which threw synchronously — that throw
-        // bypassed the primary error and, worse, skipped downstream handling so
-        // the engine was left with staged files and the user got a teardown
-        // message with no guidance. We now collect both failures and, if anything
-        // went wrong, persist a `pendingRepair` marker that `fireforge doctor`
-        // consumes to finish the reconciliation.
-        // Teardown restores the journal itself, so the lifecycle wrapper must not
-        // restore it again when the throw below propagates out of this body.
+        // 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
+        // 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
+        // finish the reconciliation.
+        //
+        // Teardown restores the journal itself, so the lifecycle wrapper must
+        // not restore it again when the throw below propagates out of this body.
         ctx.markRolledBack();
         const teardownErrors = await runPreviewTeardown(paths.engine, storiesCleanupRequired, previewJournal);
         if (teardownErrors.length > 0) {

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

@@ -6,9 +6,10 @@ import { getOverrideEngineTargetPath } from '../../core/furnace-apply-helpers.js
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
 import { isComponentSourceFile } from '../../core/furnace-constants.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { refreshOverrideFile } from '../../core/furnace-refresh.js';
-import { createRollbackJournal, restoreRollbackJournal, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { createRollbackJournal, restoreRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getHead } from '../../core/git.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
@@ -144,17 +145,15 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
             return fileResults;
         }
         catch (error) {
+            // A dry run wrote nothing, so there is no journal to restore — it
+            // rethrows without touching the lifecycle wrapper.
             if (!dryRun) {
-                // This body owns its rollback end to end, so tell the lifecycle
-                // wrapper not to restore the same journal again on the way out.
-                ctx.markRolledBack();
-                try {
-                    await restoreRollbackJournalOrThrow(journal, `Failed to refresh override "${name}"`);
-                }
-                catch (rollbackError) {
-                    await recordFurnaceRollbackFailure(projectRoot, 'refresh-rollback', `override "${name}": ${toError(rollbackError).message}`);
-                    throw rollbackError;
-                }
+                return await completeJournalRollback(ctx, journal, error, {
+                    projectRoot,
+                    operation: 'refresh-rollback',
+                    failureMessage: `Failed to refresh override "${name}"`,
+                    subject: `override "${name}"`,
+                });
             }
             throw error;
         }
@@ -228,10 +227,7 @@ export async function furnaceRefreshCommand(projectRoot, name, options = {}) {
     // 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.
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
+    await assertFurnaceEngineReady(projectRoot);
     const dryRun = options.dryRun ?? false;
     if (name) {
         intro('Furnace Refresh');

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

@@ -5,12 +5,9 @@ import type { FurnaceState } from '../../types/furnace.js';
 /**
  * Engine-side and workspace-side removal for an OVERRIDE component.
  *
- * Extracted in 0.41.0: this and its custom-component sibling were the only
- * large inline blocks in the furnace subsystem never wrapped in a
- * `perform*Mutations` helper, and together they held `remove.ts` at 496/500
- * file lines with `furnaceRemoveCommand` at 149/150 — one line from a build
- * failure. Both run inside the caller's rollback journal rather than opening
- * their own, so a failure anywhere still restores the whole operation.
+ * 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
+ * single unit.
  */
 export declare function performOverrideRemovalMutations(args: {
     name: string;

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

@@ -2,12 +2,10 @@
 /**
  * Engine-side and workspace-side mutation bodies for `furnace remove`.
  *
- * Split out of `remove.ts` in 0.41.0. The two `perform*RemovalMutations`
- * functions were the only large inline blocks in the furnace subsystem never
- * wrapped in a helper, and together they held `remove.ts` at 496/500 file
- * lines with `furnaceRemoveCommand` at 149/150 — one line from a build
- * failure. Extracting them inside the same file traded a function-length
- * problem for a file-length one, so they live here instead.
+ * Split out of `remove.ts`, where the two `perform*RemovalMutations`
+ * functions held the file at the per-file line cap with
+ * `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
  * own, so a failure anywhere in the remove still restores the whole
@@ -84,12 +82,9 @@ async function restoreOverrideEngineFiles(engineDir, overrideDir, overrideConfig
 /**
  * Engine-side and workspace-side removal for an OVERRIDE component.
  *
- * Extracted in 0.41.0: this and its custom-component sibling were the only
- * large inline blocks in the furnace subsystem never wrapped in a
- * `perform*Mutations` helper, and together they held `remove.ts` at 496/500
- * file lines with `furnaceRemoveCommand` at 149/150 — one line from a build
- * failure. Both run inside the caller's rollback journal rather than opening
- * their own, so a failure anywhere still restores the whole operation.
+ * 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
+ * single unit.
  */
 export async function performOverrideRemovalMutations(args) {
     const { name, paths, furnacePaths, freshConfig, freshState, ftlDir, journal } = args;
@@ -162,10 +157,8 @@ export async function performCustomRemovalMutations(args) {
         }
         // Drop the locale jar.mn chrome registration that `applyCustomFtlFile`
         // wrote during deploy — otherwise the engine is left with a
-        // `locale/.../${name}.ftl` entry pointing at a file we just
-        // deleted. 2026-04-21 eval (Finding #1): `furnace remove` left
-        // `browser/locales/jar.mn` referencing the missing FTL, which
-        // would break the next package-manifest validation.
+        // `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.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { loadFurnaceState } from '../../core/furnace-config.js';
 import { snapshotFile } from '../../core/furnace-rollback.js';
@@ -52,7 +53,6 @@ export async function removeDeployedCustomFiles(projectRoot, engineDir, name, ta
     if (deletedCount > 0) {
         info(`Deleted ${deletedCount} deployed file(s) from engine/${targetPath}/`);
     }
-    const { readdir } = await import('node:fs/promises');
     if ((await readdir(engineTargetDir)).length === 0) {
         await removeDir(engineTargetDir);
         info(`Removed now-empty engine/${targetPath}/`);