@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -25,14 +25,25 @@
  *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
  */
 export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath, sharedFtl) {
+    // A `*/` in the operator-supplied description would close the JSDoc block
+    // early and leave the remainder as stray code. Escaped here rather than
+    // rejected at input, because the same text is also rendered by
+    // create-dry-run.ts, where no escaping is wanted.
+    const jsDocDescription = (description || name).replace(/\*\//g, '*\\/');
     const ftlPath = sharedFtl !== undefined
         ? sharedFtl
         : ftlChromeSubPath !== undefined
             ? `${ftlChromeSubPath}/${name}.ftl`
             : `${name}.ftl`;
+    // Escape at the SINK, not at the validator. `ftlPath` reaches here from
+    // three sources — the `--shared-ftl` flag, the furnace.json `ftlBasePath`,
+    // and a derived `<name>.ftl` — and only the first passes through
+    // `validateSharedFtl`. `JSON.stringify` produces a correctly-escaped JS
+    // string literal for all of them, including the `"` and raw-newline cases
+    // that would otherwise break the generated module into a syntax error.
     const ftlModulePreamble = localized
         ? `
-window.MozXULElement?.insertFTLIfNeeded("${ftlPath}");
+window.MozXULElement?.insertFTLIfNeeded(${JSON.stringify(ftlPath)});
 `
         : '';
     const lifecycleHooks = localized
@@ -60,7 +71,7 @@ import { html } from "chrome://global/content/vendor/lit.all.mjs";
 import { MozLitElement } from "chrome://global/content/lit-utils.mjs";
 ${ftlModulePreamble}
 /**
- * ${description || name}
+ * ${jsDocDescription}
  *
  * @tagname ${name}
  */
@@ -108,19 +119,18 @@ export function xpcshellTestFileName(name) {
  * xpcshell cannot execute a component module that imports
  * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
  * `window` at module-load time and the xpcshell harness has no `window`
- * global. Before 0.16.0 the scaffold called `ChromeUtils.importESModule`
- * on the component's MJS, which reliably failed with
- * `ReferenceError: window is not defined` for every Lit-based fork
- * component. FireForge's diagnostics then misrouted the failure to the
- * "stale build artifacts" branch, sending operators on a rebuild loop
- * that couldn't fix a runtime-environment incompatibility.
+ * global. A scaffold that calls `ChromeUtils.importESModule` on the
+ * component's MJS therefore fails with `ReferenceError: window is not
+ * defined` for every Lit-based fork component, and FireForge's diagnostics
+ * misroute that to the "stale build artifacts" branch, sending operators on
+ * a rebuild loop that cannot fix a runtime-environment incompatibility.
  *
- * The rewrite here mirrors the chrome-doc packaging test: XCurProcD is
+ * This template mirrors the chrome-doc packaging test instead: XCurProcD is
  * probed at a pair of candidate layouts (dist/bin/browser and the macOS
- * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files
- * landed where jar.mn promised. That's the assertion xpcshell CAN make.
- * Functional tests that need DOM/shadow-root/keyboard behaviour belong
- * in a browser-chrome mochitest — scaffolded via
+ * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files landed
+ * where jar.mn promised. That is the assertion xpcshell CAN make. Functional
+ * tests that need DOM/shadow-root/keyboard behaviour belong in a
+ * browser-chrome mochitest — scaffolded via
  * `fireforge furnace create --test-style browser-chrome`.
  */
 export function generateXpcshellTestContent(name, header) {
@@ -225,26 +235,21 @@ export function mochikitTestFileName(name) {
  * MochiKit tests load the component module directly via the global chrome
  * URI and assert that `customElements.get(<tag>)` returns a constructor.
  * They run on forks whose top-level chrome document lacks a `tabbrowser`
- * (the class of bug that forces `--xpcshell` for storage code) because
- * they do not traverse `URILoadingHelper.openLinkIn`.
+ * because they do not traverse `URILoadingHelper.openLinkIn`.
  *
- * The scaffold here is a smoke test — the component is defined and the
- * constructor is a function. Real UI assertions (render output, l10n
- * wiring, keyboard interactions) are intentionally left out because they
- * depend on the component's shape; operators can extend the test using
- * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
- * rely on.
+ * The scaffold is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n wiring,
+ * keyboard interactions) are left out because they depend on the
+ * component's shape; operators can extend the test using the same SimpleTest
+ * APIs upstream toolkit widgets rely on.
  *
  * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
- * `add_task` owns the test lifecycle: when every queued task resolves,
- * the task harness calls `SimpleTest.finish()` on its own. Combining
- * `waitForExplicitFinish()` with `add_task` *and* no explicit
- * `SimpleTest.finish()` inside the task body makes the harness wait
- * forever, which the 2026-04-21 eval run tripped into as an indefinite
- * hang on a `fireforge test --headless` against a scaffolded widget
- * test. Leaving `waitForExplicitFinish()` out matches the convention
- * upstream toolkit widget tests use (see `test_moz-button.html` and
- * siblings under `toolkit/content/tests/widgets/`).
+ * `add_task` owns the test lifecycle: when every queued task resolves, the
+ * task harness calls `SimpleTest.finish()` itself. Combining
+ * `waitForExplicitFinish()` with `add_task` and no explicit
+ * `SimpleTest.finish()` in the task body makes the harness wait forever —
+ * an indefinite hang on `fireforge test --headless`. Omitting it matches the
+ * convention upstream toolkit widget tests use.
  */
 export function generateMochikitTestContent(name) {
     return `<!DOCTYPE html>

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

@@ -43,8 +43,8 @@ export async function scaffoldXpcshellTestFiles(componentName, license, forgeCon
     const testFileName = xpcshellTestFileName(componentName);
     const testFilePath = join(testDir, testFileName);
     if (await pathExists(testFilePath)) {
-        // Never clobber an existing test implementation (0.34.0 field report:
-        // the scaffold overwrote files owned by a different patch).
+        // Never clobber an existing test implementation: the scaffold must not
+        // overwrite files owned by a different patch.
         warn(`${testDirRel}/${testFileName} already exists — keeping the existing file.`);
     }
     else {

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

@@ -2,17 +2,17 @@
 import { join } from 'node:path';
 import { text } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { stdioIsInteractive } from '../../core/destructive.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { resolveFtlChromeSubPath, tagNameToClassName } from '../../core/furnace-constants.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.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 { resolveFtlChromeSubPath, tagNameToClassName, WIDGETS_DIR, } from '../../core/furnace-constants.js';
+import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, describeTagNameProblem, } from '../../core/furnace-registration-validate.js';
+import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { isComponentInEngine, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { validateSharedFtl } from '../../core/shared-ftl.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro } from '../../utils/logger.js';
 import { resolveValidatedTestDir, scaffoldTestFiles } from './create-browser-test.js';
@@ -70,6 +70,8 @@ function validateTagName(name) {
  * @param description - Human-readable component description
  * @param localized - Whether to include a Fluent file
  * @param license - Project license used for generated headers
+ * @param ftlChromeSubPath - chrome:// sub-path for the generated FTL reference, when localized
+ * @param sharedFtl - Explicit shared FTL path from `--shared-ftl`, when supplied
  * @param journal - Optional rollback journal that snapshots files before writes
  * @returns Relative filenames written for the component
  */
@@ -166,7 +168,7 @@ async function performCreateMutations(args) {
         files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, resolveFtlChromeSubPath(freshConfig.ftlBasePath), args.sharedFtl, journal);
         const customEntry = {
             description: args.description,
-            targetPath: `toolkit/content/widgets/${args.componentName}`,
+            targetPath: `${WIDGETS_DIR}/${args.componentName}`,
             register: args.register,
             localized: args.localized,
         };
@@ -199,15 +201,16 @@ async function performCreateMutations(args) {
         }
     }
     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.
-        args.operationContext?.markRolledBack();
-        try {
-            await restoreRollbackJournalOrThrow(journal, `Failed to create custom component "${args.componentName}"`);
-        }
-        catch (rollbackError) {
-            await recordFurnaceRollbackFailure(args.projectRoot, 'create-rollback', `component "${args.componentName}": ${toError(rollbackError).message}`);
-            throw rollbackError;
+        // `operationContext` is optional here (the dry-run and no-journal paths
+        // pass none), so the shared handler only applies when there is a
+        // lifecycle wrapper to tell.
+        if (args.operationContext) {
+            return await completeJournalRollback(args.operationContext, journal, error, {
+                projectRoot: args.projectRoot,
+                operation: 'create-rollback',
+                failureMessage: `Failed to create custom component "${args.componentName}"`,
+                subject: `component "${args.componentName}"`,
+            });
         }
         throw error;
     }
@@ -237,7 +240,7 @@ async function resolveDescription(isInteractive, options) {
  * @param options - CLI options for non-interactive mode
  */
 export async function furnaceCreateCommand(projectRoot, name, options = {}) {
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     const isDryRun = options.dryRun ?? false;
     intro(isDryRun ? 'Furnace Create (dry run)' : 'Furnace Create');
     // --- Resolve component name ---
@@ -264,7 +267,9 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         const nameResult = await text({
             message: 'Component tag name:',
             placeholder: 'moz-my-widget',
-            validate: (value) => validateTagName(value ?? ''),
+            // Message-returning form: the throwing `validateTagName` escaped
+            // clack's validation loop and killed the prompt on a bad name.
+            validate: (value) => describeTagNameProblem(value ?? ''),
         });
         if (isCancel(nameResult)) {
             cancel('Create cancelled');
@@ -304,6 +309,11 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // partial mutation behind.
     const testStyle = resolveTestStyle(options);
     const testDir = resolveValidatedTestDir(options.testDir, testStyle);
+    // Not routed through assertFurnaceEngineReady: this rung is CONDITIONAL on
+    // a test style being requested, and it names the component so the refusal
+    // identifies which create failed. Both are outside the shared helper's
+    // shape, and a scaffold without --with-tests must keep working with no
+    // engine present.
     if (testStyle !== 'none' && !(await pathExists(paths.engine))) {
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests, --xpcshell, or --test-style.', componentName);
     }
@@ -314,13 +324,13 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     if (await pathExists(componentDir)) {
         throw new FurnaceError(`Directory already exists: components/custom/${componentName}`, componentName);
     }
-    // --- Normalize and validate --shared-ftl ahead of any writes. Shares the
+    // Normalize and validate --shared-ftl ahead of any writes. Shares the
     // structural rules with furnace-config.ts so the command and the on-disk
-    // schema cannot diverge. Pass the resolved `localized` rather than a
-    // `true` literal so the validator's cross-field check stays anchored to
-    // the real feature selection — `resolveCreateFeatures` promotes localized
-    // upstream, but hard-coding `true` here would hide a regression if that
-    // promotion ever moved or dropped.
+    // schema cannot diverge. Pass the resolved `localized` rather than a `true`
+    // literal so the validator's cross-field check stays anchored to the real
+    // feature selection — `resolveCreateFeatures` promotes localized upstream,
+    // and hard-coding `true` here would hide a regression if that promotion
+    // ever moved or dropped.
     let sharedFtl;
     if (options.sharedFtl !== undefined) {
         const result = validateSharedFtl(options.sharedFtl, { localized });

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

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
-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 { getPersistableAppliedEntry, getStepFailureCount, persistSingleComponentState, shouldPersistSingleComponentState, } from '../../core/furnace-state-persist.js';
 import { hasBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftError, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { pathExists } from '../../utils/fs.js';
 import { info, intro, note, outro, spinner, warn } from '../../utils/logger.js';
 import { runDeployValidation } from './validation-output.js';
 /**
@@ -39,28 +39,29 @@ function getFailedComponentNames(result) {
     return failed;
 }
 /**
- * Applies a single named override or custom component in targeted deploy mode.
+ * Applies a single named override or custom component in targeted deploy
+ * mode.
  *
  * Delegates to {@link applyAllComponents} with a `componentName` filter so
  * targeted deploys run the exact same pipeline as deploy-all — including
  * workspace-deletion detection, engine orphan undeploy, and jar.mn /
- * customElements.js re-sync. The previous implementation called the
- * per-component apply helpers directly and never pruned: renaming a helper
- * file in the workspace left the old deployed file and its stale jar.mn
- * line in the engine (field report D1).
+ * customElements.js re-sync. Calling the per-component apply helpers
+ * directly never prunes: renaming a helper file in the workspace then leaves
+ * the old deployed file and its stale jar.mn line in the engine.
  *
  * `persistState: false` is load-bearing: the batch persist path *replaces*
  * `appliedChecksums` wholesale with only this run's entries, which for a
  * named deploy would wipe every other component's state. Named deploy keeps
  * its per-component state merge ({@link persistSingleComponentState}) and
- * its atomicity gate ({@link shouldPersistNamedDeployState}) at the call
- * site. Rollback on failure happens inside `applyAllComponents`; the
- * journal returned on success is ignored (the deploy keeps its files).
+ * its atomicity gate ({@link shouldPersistSingleComponentState}) at the call
+ * site. Rollback on failure happens inside `applyAllComponents`; the journal
+ * returned on success is ignored (the deploy keeps its files).
  *
  * @param name - Component name to apply
  * @param config - Loaded Furnace configuration
  * @param isDryRun - Whether file writes should be skipped
- * @returns Apply result for the named component, or `stock` for stock-only entries
+ * @returns Apply result for the named component, or `stock` for stock-only
+ *   entries
  */
 async function applyNamedComponent(name, config, isDryRun, projectRoot, operationContext) {
     if (!(name in config.overrides) && !(name in config.custom)) {
@@ -132,16 +133,7 @@ function enforceScopedOverrideVersionDriftPreflight(scopedDrift, force) {
 export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     const isDryRun = options.dryRun ?? false;
     intro(isDryRun ? 'Furnace Deploy (dry run)' : 'Furnace Deploy');
-    // 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 { config } = await assertFurnaceReady(projectRoot);
     const furnacePaths = getFurnacePaths(projectRoot);
     const overrideCount = Object.keys(config.overrides).length;
     const customCount = Object.keys(config.custom).length;
@@ -196,8 +188,8 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     applySpinner.stop(isDryRun ? 'Planned actions calculated' : 'Components applied');
     logApplyResult(result, isDryRun);
     // Keep the consumer jsconfig's chrome-module `paths` in step with the
-    // deployed module set (field report D3). Only after a clean apply —
-    // a rolled-back deploy must not advance the typecheck mapping either.
+    // deployed module set. Only after a clean apply — a rolled-back deploy
+    // must not advance the typecheck mapping either.
     if (result.errors.length === 0 && getStepFailureCount(result) === 0) {
         await reportJsconfigPathsSync(projectRoot, config, isDryRun);
     }

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

@@ -11,6 +11,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists, readText } from '../../utils/fs.js';
 import { formatErrorText, formatSuccessText, info, intro, outro } from '../../utils/logger.js';
+import { normalizePathSlashes } from '../../utils/paths.js';
 /**
  * Renders a multi-hunk unified diff between the two strings and returns a
  * flat list of display-ready lines. Each line has already had its marker
@@ -64,7 +65,11 @@ async function diffOverride(name, projectRoot, config) {
         if (!isComponentSourceFile(entry.name))
             continue;
         // git show takes a repo-relative path. paths.engine IS the repo root.
-        const enginePath = getOverrideEngineTargetPath(paths.engine, overrideConfig, entry.name, ftlDir).slice(paths.engine.length + 1);
+        // The slice leaves the host's separators behind, and `git show <ref>:<path>`
+        // only understands forward slashes — on Windows the unnormalized form makes
+        // every baseline read miss, so every overridden file is reported as a new
+        // file and `furnace diff` shows nothing.
+        const enginePath = normalizePathSlashes(getOverrideEngineTargetPath(paths.engine, overrideConfig, entry.name, ftlDir).slice(paths.engine.length + 1));
         const modifiedPath = join(overrideDir, entry.name);
         const baselineDisplayPath = enginePath;
         let originalContent;
@@ -99,16 +104,16 @@ async function diffOverride(name, projectRoot, config) {
     }
 }
 /**
- * Diffs a custom component's workspace files against the engine-deployed copy.
- * Shows what would change (or has changed) on the next `furnace apply`.
+ * Diffs a custom component's workspace files against the engine-deployed
+ * copy. Shows what would change (or has changed) on the next
+ * `furnace apply`.
  *
- * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via `applyCustomFtlFile`
- * — NOT to `customConfig.targetPath` — so the deployment-target lookup has
- * to branch on extension. Before this branch existed, a component's
- * localization file always reported "not yet deployed to engine (new
- * file)" after a successful apply/deploy because diff was looking for it
- * under the component's `targetPath` while apply had written it into the
- * locale tree.
+ * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via
+ * `applyCustomFtlFile` — NOT to `customConfig.targetPath` — so the
+ * deployment-target lookup has to branch on extension. Without the branch, a
+ * component's localization file always reports "not yet deployed to engine
+ * (new file)" after a successful apply, because diff looks for it under the
+ * component's `targetPath` while apply wrote it into the locale tree.
  */
 async function diffCustom(name, projectRoot, config) {
     const customConfig = config.custom[name];

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