@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -3,12 +3,13 @@ import { readdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { stdioIsInteractive } from '../../core/destructive.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { resolveFtlDir, xpcshellTestParentDir } from '../../core/furnace-constants.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation } from '../../core/furnace-operation.js';
-import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { createRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { isGitRepository } from '../../core/git.js';
-import { deregisterTestManifest } from '../../core/manifest-register.js';
+import { deregisterTestManifest } from '../../core/moz-manifest-register.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists, readText, removeDir, writeText } from '../../utils/fs.js';
@@ -157,23 +158,23 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
     return { partialFailures };
 }
 /**
- * Removes the MochiKit test scaffold a `furnace create --with-tests
- * --test-style mochikit` produced for the component (matches the rename
- * counterpart in `rename.ts`). The test file is `test_<name>.html` under
- * `engine/toolkit/content/tests/widgets/` and the registration is the
- * `["test_<name>.html"]` entry in the same directory's `chrome.toml`.
+ * Removes the MochiKit test scaffold a
+ * `furnace create --with-tests --test-style mochikit` produced for the
+ * component (matches the rename counterpart in `rename.ts`). The test file is
+ * `test_<name>.html` under `engine/toolkit/content/tests/widgets/` and the
+ * registration is the `["test_<name>.html"]` entry in the same directory's
+ * `chrome.toml`.
  *
- * 2026-04-25 eval Finding 13: the prior cleanup only handled the
- * browser-chrome mochitest layout under `browser/base/content/test/
- * <binary>/`, which left mochikit-style scaffolds and their toml entries
- * orphaned after `furnace remove`. The post-rename name passed in here
- * is the canonical one written to disk by deploy/rename, so the file
- * basenames match without needing to re-derive from the old name.
+ * Cleanup that only handles the browser-chrome mochitest layout under
+ * `browser/base/content/test/<binary>/` leaves mochikit-style scaffolds and
+ * their toml entries orphaned after `furnace remove`. The post-rename name
+ * passed in here is the canonical one written to disk by deploy/rename, so
+ * the file basenames match without re-deriving from the old name.
  *
- * Best-effort: each step warns on failure rather than throwing so the
- * rest of the remove transaction proceeds. The journal still snapshots
- * touched files so the outer rollback can restore them on a later
- * failure in the same operation.
+ * Best-effort: each step warns on failure rather than throwing so the rest
+ * of the remove transaction proceeds. The journal still snapshots touched
+ * files so the outer rollback can restore them on a later failure in the
+ * same operation.
  */
 async function cleanupCustomMochikitTestFiles(name, projectRoot, journal) {
     const partialFailures = [];
@@ -216,14 +217,13 @@ async function cleanupCustomMochikitTestFiles(name, projectRoot, journal) {
 }
 /**
  * Removes generated xpcshell test scaffolds associated with a custom
- * component. 2026-04-24 eval Finding 5: `furnace remove` handled
- * browser mochitests via `cleanupCustomTestFiles` but never touched the
- * xpcshell scaffold tree, so an operator who ran
- * `furnace create --with-tests --xpcshell` followed by `furnace remove`
- * was left with orphan `xpcshell.toml` + `test_<name>_packaged.js`
- * files still referencing the removed component. This cleanup pass
- * mirrors the mochitest one — snapshot before removal, warn-and-
- * continue semantics, explicit summary when partial failures occur.
+ * component. Cleanup that handles browser mochitests via
+ * `cleanupCustomTestFiles` but never touches the xpcshell scaffold tree
+ * leaves an operator who ran `furnace create --with-tests --xpcshell`
+ * followed by `furnace remove` with orphan `xpcshell.toml` +
+ * `test_<name>_packaged.js` files still referencing the removed component.
+ * This pass mirrors the mochitest one — snapshot before removal,
+ * warn-and-continue semantics, explicit summary on partial failures.
  */
 async function cleanupCustomXpcshellTestFiles(name, projectRoot, journal) {
     const partialFailures = [];
@@ -328,7 +328,7 @@ async function requireGitEngineForRemove(type, name, engineDir) {
  * @param options - CLI options
  */
 export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     intro('Furnace Remove');
     const config = await loadFurnaceConfig(projectRoot);
     const furnacePaths = getFurnacePaths(projectRoot);
@@ -405,17 +405,12 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
             }
         }
         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 remove component "${name}"`);
-            }
-            catch (rollbackError) {
-                await recordFurnaceRollbackFailure(projectRoot, 'remove-rollback', `component "${name}": ${toError(rollbackError).message}`);
-                throw rollbackError;
-            }
-            throw error;
+            return await completeJournalRollback(ctx, journal, error, {
+                projectRoot: projectRoot,
+                operation: 'remove-rollback',
+                failureMessage: `Failed to remove component "${name}"`,
+                subject: `component "${name}"`,
+            });
         }
     });
     info(`Removed "${name}" from furnace.json`);

package/dist/src/commands/furnace/rename-xpcshell.d.ts

@@ -1,18 +1,15 @@
 /**
  * xpcshell scaffold rename helper extracted from `rename.ts`.
  *
- * 2026-04-24 eval Finding 5: `furnace create --with-tests --xpcshell`
- * writes a scaffold at `browser/base/content/test/<binary>-xpcshell/
- * <name>/` and `furnace rename` did not update it. The helper below
- * renames the directory, updates the test filename, rewrites the
- * `xpcshell.toml` section header, and re-writes the test body so word-
- * boundary occurrences of the old tag / underscored name map to the new
- * ones.
+ * `furnace create --with-tests --xpcshell` writes a scaffold at
+ * `browser/base/content/test/<binary>-xpcshell/<name>/`, which a rename must
+ * follow. This helper renames the directory, updates the test filename,
+ * rewrites the `xpcshell.toml` section header, and re-writes the test body
+ * so word-boundary occurrences of the old tag / underscored name map to the
+ * new ones.
  *
- * Extracted to keep `rename.ts` under the per-file LOC budget —
- * `rename.ts` already carries mochikit + browser-mochitest + FTL
- * handling, and tacking xpcshell onto that tree pushed the file past
- * the limit.
+ * Extracted to keep `rename.ts` under the per-file LOC budget — it already
+ * carries mochikit + browser-mochitest + FTL handling.
  */
 import { type RollbackJournal } from '../../core/furnace-rollback.js';
 /**

package/dist/src/commands/furnace/rename-xpcshell.js

@@ -2,18 +2,15 @@
 /**
  * xpcshell scaffold rename helper extracted from `rename.ts`.
  *
- * 2026-04-24 eval Finding 5: `furnace create --with-tests --xpcshell`
- * writes a scaffold at `browser/base/content/test/<binary>-xpcshell/
- * <name>/` and `furnace rename` did not update it. The helper below
- * renames the directory, updates the test filename, rewrites the
- * `xpcshell.toml` section header, and re-writes the test body so word-
- * boundary occurrences of the old tag / underscored name map to the new
- * ones.
+ * `furnace create --with-tests --xpcshell` writes a scaffold at
+ * `browser/base/content/test/<binary>-xpcshell/<name>/`, which a rename must
+ * follow. This helper renames the directory, updates the test filename,
+ * rewrites the `xpcshell.toml` section header, and re-writes the test body
+ * so word-boundary occurrences of the old tag / underscored name map to the
+ * new ones.
  *
- * Extracted to keep `rename.ts` under the per-file LOC budget —
- * `rename.ts` already carries mochikit + browser-mochitest + FTL
- * handling, and tacking xpcshell onto that tree pushed the file past
- * the limit.
+ * Extracted to keep `rename.ts` under the per-file LOC budget — it already
+ * carries mochikit + browser-mochitest + FTL handling.
  */
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';

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

@@ -4,10 +4,10 @@ import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { isComponentSourceFile, resolveFtlChromeSubPath, resolveFtlDir, resolveFtlLocaleJarMnPath, tagNameToClassName, } from '../../core/furnace-constants.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
 import { addCustomElementRegistration, addJarMnEntries, addLocaleFtlJarMnEntry, removeCustomElementRegistration, removeJarMnEntries, removeLocaleFtlJarMnEntry, } from '../../core/furnace-registration.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
-import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { createRollbackJournal, recordCreatedDir, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getStoriesDir } from '../../core/furnace-stories.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
@@ -83,15 +83,14 @@ async function renameTestFiles(engineDir, projectRoot, oldName, newName, journal
     }
 }
 /**
- * Removes the deployed custom-widget directory at the old target path so
- * a subsequent `furnace apply` is the single writer of the new name's
+ * Removes the deployed custom-widget directory at the old target path so a
+ * subsequent `furnace apply` is the single writer of the new name's
  * deployment. Best-effort: logs a warning but never blocks the rename.
  *
- * 2026-04-21 eval: renaming `ff-chip-row` → `ff-chip-stack` registered
- * and deployed the new name correctly but left `engine/toolkit/content/
- * widgets/ff-chip-row/` in place. Subsequent `furnace sync` runs could
- * not clear the stale widget, and packaging would have pulled in both
- * copies. The snapshot is taken before the remove so the rollback
+ * Without it, a rename registers and deploys the new name correctly but
+ * leaves `engine/toolkit/content/widgets/<old>/` in place — subsequent
+ * `furnace sync` runs cannot clear the stale widget, and packaging pulls in
+ * both copies. The snapshot is taken before the remove so the rollback
  * journal restores the old directory if any later step in
  * `performRenameMutations` fails.
  */
@@ -110,19 +109,18 @@ async function removeStaleDeployedComponentDir(engineDir, oldTargetPath, journal
 }
 /**
  * Renames the mochikit test scaffold produced by `furnace create
- * --with-tests` when the default test style is used. The scaffold lives
- * at `engine/toolkit/content/tests/widgets/test_<name>.html`, and the
- * accompanying `chrome.toml` entry names the same file. Neither piece
- * was handled by the pre-0.16.0 rename, so operators were left with a
- * `test_<old>.html` file that still imported `chrome://global/content/
- * elements/<old>.mjs` and referenced `customElements.whenDefined("<old>")`
- * — the test ran against a component that no longer existed under that
- * name and either failed or (if the old component was still deployed)
- * passed for the wrong reason.
+ * --with-tests` when the default test style is used. The scaffold lives at
+ * `engine/toolkit/content/tests/widgets/test_<name>.html`, and the
+ * accompanying `chrome.toml` entry names the same file. Leaving both
+ * unhandled produces a `test_<old>.html` that still imports
+ * `chrome://global/content/elements/<old>.mjs` and references
+ * `customElements.whenDefined("<old>")` — running against a component that
+ * no longer exists under that name, and either failing or (if the old
+ * component is still deployed) passing for the wrong reason.
  *
- * Best-effort: individual failures log a warning. The same journal used
- * for the rest of the rename snapshots every touched file so a later
- * failure rolls the pair back together.
+ * Best-effort: individual failures log a warning. The same journal used for
+ * the rest of the rename snapshots every touched file so a later failure
+ * rolls the pair back together.
  */
 async function renameMochikitTestFiles(engineDir, oldName, newName, journal) {
     const testDir = join(engineDir, 'toolkit/content/tests/widgets');
@@ -223,13 +221,13 @@ async function performRenameMutations(args) {
                     continue;
                 const oldFileName = entry.name;
                 // Rename only when the filename starts with the component name — the
-                // scaffolding convention for both create and override is `${name}.ext`.
-                // A plain `replace(oldName, newName)` produced wrong results when the
-                // old name occurred more than once (e.g. `foo-foo.mjs` renamed `foo` →
-                // `bar` became `bar-foo.mjs` instead of `bar-bar.mjs`) and also when
-                // the old name appeared inside a file that was not the component
-                // scaffold itself (e.g. a sibling helper). Unrelated files (stray
-                // assets, editor backups) are copied verbatim.
+                // scaffolding convention for both create and override is
+                // `${name}.ext`. A plain `replace(oldName, newName)` produces wrong
+                // results when the old name occurs more than once (`foo-foo.mjs`
+                // renamed `foo` → `bar` becomes `bar-foo.mjs` instead of
+                // `bar-bar.mjs`) and when the old name appears inside a file that is
+                // not the component scaffold itself. Unrelated files (stray assets,
+                // editor backups) are copied verbatim.
                 const newFileName = renameComponentFileName(oldFileName, oldName, newName);
                 const oldPath = join(oldDir, oldFileName);
                 const newPath = join(newDir, newFileName);
@@ -279,28 +277,25 @@ async function performRenameMutations(args) {
             // 7. Rename test files created by `furnace create --with-tests` (custom only).
             if (isCustom && (await pathExists(args.engineDir))) {
                 await renameTestFiles(args.engineDir, projectRoot, oldName, newName, journal);
-                // Mochikit scaffold + widgets/chrome.toml live in a different
+                // The mochikit scaffold and widgets/chrome.toml live in a different
                 // tree than browser.toml-registered browser-chrome tests, so
-                // renameTestFiles doesn't reach them. 2026-04-21 eval: a rename
-                // left `engine/toolkit/content/tests/widgets/test_<old>.html`
-                // and its `chrome.toml` entry pointing at the old name, which
-                // either failed the test run outright or (worse) passed for the
-                // wrong component.
+                // renameTestFiles does not reach them — leaving
+                // `engine/toolkit/content/tests/widgets/test_<old>.html` and its
+                // `chrome.toml` entry pointing at the old name, which either fails
+                // the test run outright or passes for the wrong component.
                 await renameMochikitTestFiles(args.engineDir, oldName, newName, journal);
-                // 2026-04-24 eval Finding 5: xpcshell scaffolds live in yet
-                // another tree (`browser/base/content/test/<binary>-xpcshell/
-                // <name>/`). Before this call, renaming a component scaffolded
-                // with `--with-tests --xpcshell` left a directory whose name
-                // still referenced the pre-rename component, plus a test file
-                // whose underscored name referenced the old tag — both of
-                // which then failed to match the new component.
+                // xpcshell scaffolds live in yet another tree
+                // (`browser/base/content/test/<binary>-xpcshell/<name>/`). Without
+                // this call, renaming a component scaffolded with
+                // `--with-tests --xpcshell` leaves a directory whose name still
+                // references the pre-rename component, plus a test file whose
+                // underscored name references the old tag.
                 await renameXpcshellTestFiles(args.engineDir, projectRoot, oldName, newName, journal);
                 // Clear the stale deployed component directory so the next
-                // `furnace apply` is the single writer of the new name's
-                // deployment. Without this, eval runs showed the old widget
-                // still living at `engine/toolkit/content/widgets/<old>/`
-                // alongside the newly-deployed `engine/toolkit/content/
-                // widgets/<new>/`, with no signal to `status` / `verify`.
+                // `furnace apply` is the single writer of the new name's deployment.
+                // Without it the old widget stays at
+                // `engine/toolkit/content/widgets/<old>/` alongside the
+                // newly-deployed `<new>/`, with no signal to `status` / `verify`.
                 if (oldCustomTargetPath) {
                     await removeStaleDeployedComponentDir(args.engineDir, oldCustomTargetPath, journal);
                 }
@@ -308,9 +303,9 @@ async function performRenameMutations(args) {
             info(`Renamed ${componentType} component: ${oldName} → ${newName}`);
         }
         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();
+            // Extra best-effort step this site owns: the half-created new
+            // directory is not in the journal, so drop it before the shared
+            // restore puts the old one back.
             try {
                 if (await pathExists(newDir)) {
                     await removeDir(newDir);
@@ -319,14 +314,12 @@ async function performRenameMutations(args) {
             catch {
                 // Best effort cleanup
             }
-            try {
-                await restoreRollbackJournalOrThrow(journal, `Failed to rename component "${oldName}" to "${newName}"`);
-            }
-            catch (rollbackError) {
-                await recordFurnaceRollbackFailure(projectRoot, 'rename-rollback', `rename "${oldName}" → "${newName}": ${toError(rollbackError).message}`);
-                throw rollbackError;
-            }
-            throw error;
+            return await completeJournalRollback(ctx, journal, error, {
+                projectRoot,
+                operation: 'rename-rollback',
+                failureMessage: `Failed to rename component "${oldName}" to "${newName}"`,
+                subject: `rename "${oldName}" → "${newName}"`,
+            });
         }
     });
 }
@@ -360,11 +353,10 @@ async function updateEngineRegistrations(engineDir, oldName, newName, newDir, ft
         await removeFile(oldFtlPath);
     }
     // Re-wire the locale jar.mn chrome registration when the component is
-    // localized. Before this, `updateEngineRegistrations` renamed the .ftl
-    // file on disk but left the locale jar.mn pointing at
-    // `locale/.../${oldName}.ftl`, so `furnace validate` passed while the
-    // engine still carried a stale registration for the now-missing file
-    // (eval finding: stale old-name registration after rename).
+    // localized. `updateEngineRegistrations` renames the .ftl file on disk but
+    // leaves the locale jar.mn pointing at `locale/.../${oldName}.ftl`, so
+    // `furnace validate` passes while the engine still carries a stale
+    // registration for the now-missing file.
     if (isLocalized) {
         const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
         const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
@@ -408,13 +400,11 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
     // `componentType` is the furnace-state key (singular: `custom` /
     // `override`); the on-disk directory label differs — custom components
     // live under `components/custom/` (singular) while overrides live under
-    // `components/overrides/` (plural). Before 0.16.0, every rename
-    // user-facing message appended an `s` to `componentType`, which
-    // produced the wrong label `components/customs/` for custom components
-    // and was technically correct for overrides only by coincidence.
-    // `componentDirLabel` centralises the singular/plural pick so every
-    // operator-facing string names the directory that actually exists on
-    // disk.
+    // `components/overrides/` (plural). Appending an `s` to `componentType`
+    // produces the wrong label `components/customs/` for custom components
+    // and is correct for overrides only by coincidence. `componentDirLabel`
+    // centralises the pick so every operator-facing string names the
+    // directory that actually exists on disk.
     const componentDirLabel = isCustom ? 'custom' : 'overrides';
     const baseDir = isCustom ? furnacePaths.customDir : furnacePaths.overridesDir;
     const oldDir = join(baseDir, oldName);

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

@@ -1,13 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { confirm, multiselect, select } from '@clack/prompts';
-import { getProjectPaths } from '../../core/config.js';
+import { stdioIsInteractive } from '../../core/destructive.js';
 import { ensureFurnaceConfig, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation } from '../../core/furnace-operation.js';
-import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
+import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
+import { createRollbackJournal, snapshotFile } from '../../core/furnace-rollback.js';
 import { DEEP_SCAN_PATHS, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
-import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
-import { pathExists } from '../../utils/fs.js';
 import { cancel, info, intro, isCancel, note, outro, spinner, success, } from '../../utils/logger.js';
 import { furnaceOverrideCommand } from './override.js';
 /**
@@ -61,16 +59,15 @@ async function promptAddComponents(components, tracked, projectRoot) {
 /**
  * Persists discovered component tag names into the `stock` section of
  * furnace.json. Shared by the interactive confirm flow and the
- * non-interactive `--track` flag (0.34.0 field report: scan printed a full
- * inventory but persisted nothing and said nothing about where the
- * inventory goes).
+ * non-interactive `--track` flag — without it, scan prints a full inventory
+ * but persists nothing and says nothing about where the inventory goes.
  *
  * Wraps the furnace.json mutation in the standard furnace lifecycle so the
  * write goes through the furnace-wide lock and is visible to the global
  * SIGINT/SIGTERM rollback pathway. The journal snapshots furnace.json
  * *before* `ensureFurnaceConfig` runs, so a failed run after the file is
- * auto-created cleans up after itself instead of leaving an unwanted
- * default config behind.
+ * auto-created cleans up after itself instead of leaving an unwanted default
+ * config behind.
  */
 async function persistStockComponents(projectRoot, names) {
     await runFurnaceMutation(projectRoot, 'scan-rollback', async (ctx) => {
@@ -92,25 +89,18 @@ async function persistStockComponents(projectRoot, names) {
             await writeFurnaceConfig(projectRoot, config);
         }
         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 update furnace.json during scan');
-            }
-            catch (rollbackError) {
-                await recordFurnaceRollbackFailure(projectRoot, 'scan-rollback', `furnace.json update during scan: ${toError(rollbackError).message}`);
-                throw rollbackError;
-            }
-            throw error;
+            return await completeJournalRollback(ctx, journal, error, {
+                projectRoot: projectRoot,
+                operation: 'scan-rollback',
+                failureMessage: 'Failed to update furnace.json during scan',
+                subject: `furnace.json update during scan`,
+            });
         }
     });
 }
 /**
- * Renders a component's discovered capabilities as a display suffix.
- * Written twice before 0.41.0 — once for the interactive multiselect labels
- * and once for the report rows — which is part of what pinned
- * `furnaceScanCommand` at complexity 30/30.
+ * Renders a component's discovered capabilities as a display suffix. Shared
+ * by the interactive multiselect labels and the report rows.
  */
 function formatComponentFeatures(component) {
     const features = [];
@@ -129,10 +119,7 @@ function formatComponentFeatures(component) {
  */
 export async function furnaceScanCommand(projectRoot, options = {}) {
     intro(options.deep ? 'Furnace Scan (deep)' : 'Furnace Scan');
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
+    const { paths } = await assertFurnaceEngineReady(projectRoot);
     // Load scan paths from config if available, merge with deep paths if requested
     const extraScanPaths = [];
     if (await furnaceConfigExists(projectRoot)) {
@@ -165,8 +152,7 @@ export async function furnaceScanCommand(projectRoot, options = {}) {
             tracked.set(name, 'custom');
         }
     }
-    // Partition once and reuse: the tracked/untracked split was computed twice
-    // (imperatively here, declaratively again for --track) before 0.41.0.
+    // Partition once and reuse across the report and the `--track` path.
     const untrackedComponentList = components.filter((c) => !tracked.has(c.tagName));
     const untrackedCount = untrackedComponentList.length;
     const trackedCount = components.length - untrackedCount;
@@ -191,7 +177,7 @@ export async function furnaceScanCommand(projectRoot, options = {}) {
         outro('Scan complete');
         return;
     }
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     if (isInteractive && untrackedCount > 0) {
         await promptAddComponents(components, tracked, projectRoot);
         return;

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
-import { extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, } from '../../core/furnace-apply.js';
+import { extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, } from '../../core/furnace-apply-helpers.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
 import { checkRegistrationConsistency } from '../../core/furnace-validate-checks.js';
@@ -13,7 +13,11 @@ import { info, intro, note, outro, warn } from '../../utils/logger.js';
  * Displays detailed status for a single Furnace component, including registration drift.
  * @param name - Component tag name to inspect
  * @param config - Loaded Furnace configuration
+ * @param state - Loaded furnace state, for applied/engine checksums
  * @param projectRoot - Root directory of the project
+ * @param paths - Resolved project paths
+ * @param furnacePaths - Resolved Furnace-specific paths
+ * @param ftlDir - Engine-relative directory localized components deploy their `.ftl` into
  */
 async function showDetailedComponentStatus(name, config, state, projectRoot, paths, furnacePaths, ftlDir) {
     const customConfig = config.custom[name];
@@ -53,7 +57,7 @@ async function showDetailedComponentStatus(name, config, state, projectRoot, pat
             outro('Status complete');
             return;
         }
-        const engineDrifted = await hasOverrideEngineDrift(paths.engine, overrideDir, overrideConfig, ftlDir);
+        const engineDrifted = await hasOverrideEngineDrift({ engineDir: paths.engine, componentDir: overrideDir, ftlDir }, overrideConfig);
         lines.push(`${engineDrifted ? '\u2717' : '\u2713'} Engine matches override workspace`);
         note(lines.join('\n'), `${name} Override Status`);
         outro('Status complete');
@@ -167,11 +171,10 @@ export async function furnaceStatusCommand(projectRoot, name) {
          *
          * The engine probe sits behind `else if` deliberately: a component whose
          * workspace already changed does not need an engine comparison to decide
-         * what `status` reports, and the probe is the expensive half (it re-hashes
-         * deployed files). The consequence is that engine drift can go UNREPORTED
-         * for a component that also has workspace changes — the summary says
-         * "workspace changed", not both. Preserved verbatim from the two
-         * hand-written copies this replaced.
+         * what `status` reports, and the probe is the expensive half (it
+         * re-hashes deployed files). The consequence is that engine drift can go
+         * UNREPORTED for a component that also has workspace changes — the
+         * summary says "workspace changed", not both.
          */
         const scanFamily = async (entries, baseDir, kind, probeEngineDrift) => {
             for (const [componentName, componentConfig] of entries) {
@@ -189,8 +192,8 @@ export async function furnaceStatusCommand(projectRoot, name) {
                 }
             }
         };
-        await scanFamily(Object.entries(config.overrides), furnacePaths.overridesDir, 'override', (_name, componentDir, cfg) => hasOverrideEngineDrift(paths.engine, componentDir, cfg, ftlDir));
-        await scanFamily(Object.entries(config.custom), furnacePaths.customDir, 'custom', (name, componentDir, cfg) => hasCustomEngineDrift(projectRoot, name, componentDir, cfg, ftlDir));
+        await scanFamily(Object.entries(config.overrides), furnacePaths.overridesDir, 'override', (_name, componentDir, cfg) => hasOverrideEngineDrift({ engineDir: paths.engine, componentDir, ftlDir }, cfg));
+        await scanFamily(Object.entries(config.custom), furnacePaths.customDir, 'custom', (name, componentDir, cfg) => hasCustomEngineDrift({ root: projectRoot, name, componentDir, ftlDir }, cfg));
         if (drift.workspaceChanged) {
             warn('Components have been modified since last apply. Run `fireforge build` or `fireforge furnace apply`.');
         }

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

@@ -1,12 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { loadConfig } from '../../core/config.js';
 import { applyAllComponents } from '../../core/furnace-apply.js';
 import { logApplyResult } from '../../core/furnace-apply-output.js';
-import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, } from '../../core/furnace-config.js';
+import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
 import { reportJsconfigPathsSync } from '../../core/furnace-jsconfig.js';
 import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { containsMergeConflictMarkers } from '../../core/furnace-validate-structure.js';
 import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
@@ -63,15 +64,7 @@ async function findComponentsWithConflictMarkers(furnacePaths, config) {
  */
 export async function furnaceSyncCommand(projectRoot, options = {}) {
     intro('Furnace Sync');
-    // Pre-flight checks
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
-    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 { config } = await assertFurnaceReady(projectRoot);
     const forgeConfig = await loadConfig(projectRoot);
     const overrideCount = Object.keys(config.overrides).length;
     const customCount = Object.keys(config.custom).length;
@@ -100,11 +93,11 @@ export async function furnaceSyncCommand(projectRoot, options = {}) {
     }
     // Phase 2.5: post-refresh gates. Refresh deliberately leaves conflict
     // markers in workspace files and does NOT bump baseVersion on conflict —
-    // so before this gate existed, sync would warn about conflicts and then
-    // copy the marker-laden files straight into the engine via Phase 3,
-    // producing a broken build from the one command whose whole purpose is a
-    // safe upgrade. Apply/deploy both enforce a drift gate; sync must not be
-    // the back door around it.
+    // so without this gate sync warns about conflicts and then copies the
+    // marker-laden files straight into the engine via Phase 3, producing a
+    // broken build from the one command whose whole purpose is a safe upgrade.
+    // Apply and deploy both enforce a drift gate; sync must not be the back
+    // door around it.
     if (!options.dryRun) {
         const refreshedConfig = await loadFurnaceConfig(projectRoot);
         const furnacePaths = getFurnacePaths(projectRoot);