@hominis/fireforge 0.10.1 → 0.11.0

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

@@ -2,13 +2,24 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { select, text } from '@clack/prompts';
-import { getProjectPaths, loadConfig } from '../../core/config.js';
-import { ensureFurnaceConfig, getFurnacePaths, writeFurnaceConfig, } from '../../core/furnace-config.js';
+import { getProjectPaths, loadConfig, loadState } from '../../core/config.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 { 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 { getComponentDetails, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
+import { toError } from '../../utils/errors.js';
 import { copyFile, ensureDir, pathExists, writeJson } from '../../utils/fs.js';
-import { cancel, intro, isCancel, note, outro } from '../../utils/logger.js';
+import { cancel, info, intro, isCancel, note, outro, warn } from '../../utils/logger.js';
+async function loadAuthoringFurnaceConfig(projectRoot) {
+    if (await furnaceConfigExists(projectRoot)) {
+        return loadFurnaceConfig(projectRoot);
+    }
+    return createDefaultFurnaceConfig();
+}
 /**
  * Copies the source files needed for a new override into the workspace.
  * @param srcDir - Original component directory in the engine checkout
@@ -16,7 +27,7 @@ import { cancel, intro, isCancel, note, outro } from '../../utils/logger.js';
  * @param overrideType - Requested override mode
  * @returns Filenames copied into the override directory
  */
-async function copyOverrideFiles(srcDir, destDir, overrideType) {
+async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasFTL, overrideType, ftlDir, journal) {
     await ensureDir(destDir);
     const entries = await readdir(srcDir, { withFileTypes: true });
     const copiedFiles = [];
@@ -26,18 +37,30 @@ async function copyOverrideFiles(srcDir, destDir, overrideType) {
         if (overrideType === 'css-only') {
             // Only copy .css files
             if (entry.name.endsWith('.css')) {
-                await copyFile(join(srcDir, entry.name), join(destDir, entry.name));
+                const dest = join(destDir, entry.name);
+                await snapshotFile(journal, dest);
+                await copyFile(join(srcDir, entry.name), dest);
                 copiedFiles.push(entry.name);
             }
         }
         else {
             // Full override: copy .mjs and .css files
             if (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')) {
-                await copyFile(join(srcDir, entry.name), join(destDir, entry.name));
+                const dest = join(destDir, entry.name);
+                await snapshotFile(journal, dest);
+                await copyFile(join(srcDir, entry.name), dest);
                 copiedFiles.push(entry.name);
             }
         }
     }
+    if (overrideType === 'full' && hasFTL) {
+        const ftlName = `${componentName}.ftl`;
+        const ftlSrc = join(engineDir, ftlDir, ftlName);
+        const dest = join(destDir, ftlName);
+        await snapshotFile(journal, dest);
+        await copyFile(ftlSrc, dest);
+        copiedFiles.push(ftlName);
+    }
     return copiedFiles;
 }
 /**
@@ -51,22 +74,55 @@ async function copyOverrideFiles(srcDir, destDir, overrideType) {
  * @param firefoxVersion - Firefox version recorded in the workspace config
  * @param config - Mutable Furnace config object to update
  */
-async function saveOverrideConfig(projectRoot, destDir, componentName, overrideType, description, details, firefoxVersion, config) {
+async function saveOverrideConfig(projectRoot, destDir, componentName, overrideType, description, details, firefoxVersion, config, journal, baseCommit) {
     const overrideJson = {
         type: overrideType,
         description,
         basePath: details.sourcePath,
         baseVersion: firefoxVersion,
+        ...(baseCommit ? { baseCommit } : {}),
     };
-    await writeJson(join(destDir, 'override.json'), overrideJson);
+    const overrideJsonPath = join(destDir, 'override.json');
+    await snapshotFile(journal, overrideJsonPath);
+    await writeJson(overrideJsonPath, overrideJson);
     config.overrides[componentName] = {
         type: overrideType,
         description,
         basePath: details.sourcePath,
         baseVersion: firefoxVersion,
+        ...(baseCommit ? { baseCommit } : {}),
     };
     await writeFurnaceConfig(projectRoot, config);
 }
+/**
+ * Performs the transactional mutation phase of furnace override under the
+ * shared lifecycle wrapper. Extracted from `furnaceOverrideCommand` so the
+ * main function stays under the `max-lines-per-function` threshold and so
+ * the rollback contract is colocated with the writes it guards.
+ */
+async function performOverrideMutations(args) {
+    return runFurnaceMutation(args.projectRoot, 'override-rollback', async (ctx) => {
+        const journal = createRollbackJournal();
+        ctx.registerJournal(journal);
+        recordCreatedDir(journal, args.destDir);
+        try {
+            const filesCopied = await copyOverrideFiles(args.engineDir, args.srcDir, args.destDir, args.componentName, args.details.hasFTL, args.overrideType, args.ftlDir, journal);
+            await snapshotFile(journal, args.furnacePaths.furnaceConfig);
+            await saveOverrideConfig(args.projectRoot, args.destDir, args.componentName, args.overrideType, args.description, args.details, args.firefoxVersion, args.config, journal, args.baseCommit);
+            return filesCopied;
+        }
+        catch (error) {
+            try {
+                await restoreRollbackJournalOrThrow(journal, `Failed to override component "${args.componentName}"`);
+            }
+            catch (rollbackError) {
+                await recordFurnaceRollbackFailure(args.projectRoot, 'override-rollback', toError(rollbackError).message);
+                throw rollbackError;
+            }
+            throw error;
+        }
+    });
+}
 /**
  * Runs the furnace override command to fork an existing engine component.
  * @param projectRoot - Root directory of the project
@@ -76,19 +132,33 @@ async function saveOverrideConfig(projectRoot, destDir, componentName, overrideT
 export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
     intro('Furnace Override');
-    // Load or create furnace.json
-    const config = await ensureFurnaceConfig(projectRoot);
+    // --- Validate config-independent inputs BEFORE auto-creating furnace.json
+    // so a failed authoring command never strands a fresh config in the
+    // project root. CLI-supplied name is checked here; the engine directory
+    // and component-resolution checks below also have no config dependency.
     const paths = getProjectPaths(projectRoot);
-    const furnacePaths = getFurnacePaths(projectRoot);
-    // Verify engine/ exists
+    if (name !== undefined && !CUSTOM_ELEMENT_TAG_PATTERN.test(name)) {
+        throw new InvalidArgumentError(`Invalid component name "${name}": ${CUSTOM_ELEMENT_TAG_RULES}`, 'name');
+    }
+    if (name === undefined && !isInteractive) {
+        throw new InvalidArgumentError('Component name is required in non-interactive mode.\n' +
+            '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.');
     }
+    // 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.
+    const config = await loadAuthoringFurnaceConfig(projectRoot);
+    const furnacePaths = getFurnacePaths(projectRoot);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
     // --- Resolve component name ---
     let componentName = name;
-    if (!componentName && isInteractive) {
-        // Scan for available components, filtering out already-overridden ones
-        const allComponents = await scanWidgetsDirectory(paths.engine);
+    if (!componentName) {
+        // Interactive prompt path; non-interactive missing-name was rejected above.
+        const allComponents = await scanWidgetsDirectory(paths.engine, ftlDir);
         const available = allComponents.filter((c) => !(c.tagName in config.overrides));
         if (available.length === 0) {
             throw new FurnaceError('No components available to override.');
@@ -109,20 +179,12 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         }
         componentName = selected;
     }
-    else if (!componentName) {
-        throw new InvalidArgumentError('Component name is required in non-interactive mode.\n' +
-            'Usage: fireforge furnace override <name> -t <type> -d "description"', 'name');
-    }
-    // Validate component name to prevent path traversal
-    if (!/^[a-z][a-z0-9]*-[a-z0-9-]*$/.test(componentName)) {
-        throw new InvalidArgumentError(`Invalid component name "${componentName}": must contain a hyphen (required for custom elements), with only lowercase letters, digits, and hyphens.`, 'name');
-    }
     // Check for existing override
     if (componentName in config.overrides) {
         throw new FurnaceError(`An override for "${componentName}" already exists in furnace.json`, componentName);
     }
     // Validate the component exists in engine
-    const details = await getComponentDetails(paths.engine, componentName);
+    const details = await getComponentDetails(paths.engine, componentName, ftlDir);
     if (!details) {
         throw new FurnaceError(`Component "${componentName}" not found in the engine source tree.`, componentName);
     }
@@ -172,8 +234,25 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         throw new FurnaceError(`Directory already exists: components/overrides/${componentName}`, componentName);
     }
     const forgeConfig = await loadConfig(projectRoot);
-    const copiedFiles = await copyOverrideFiles(srcDir, destDir, overrideType);
-    await saveOverrideConfig(projectRoot, destDir, componentName, overrideType, description, details, forgeConfig.firefox.version, config);
+    const state = await loadState(projectRoot);
+    // All validation is done. The mutation phase runs in a helper that owns
+    // the rollback journal, the furnace-wide lock, and SIGINT/SIGTERM-driven
+    // teardown via the lifecycle wrapper.
+    const copiedFiles = await performOverrideMutations({
+        projectRoot,
+        componentName,
+        overrideType,
+        description,
+        srcDir,
+        destDir,
+        engineDir: paths.engine,
+        details,
+        config,
+        furnacePaths,
+        ftlDir,
+        firefoxVersion: forgeConfig.firefox.version,
+        ...(state.baseCommit ? { baseCommit: state.baseCommit } : {}),
+    });
     // --- Success ---
     note(`Files copied to components/overrides/${componentName}/:\n` +
         copiedFiles.map((f) => `  ${f}`).join('\n') +
@@ -185,4 +264,115 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         '  3. Run "fireforge build" to apply and build', componentName);
     outro('Override created');
 }
+/**
+ * Creates multiple overrides in a single invocation. Each component is validated
+ * and created sequentially; failures on one component do not block the rest.
+ * @param projectRoot - Root directory of the project
+ * @param names - Component tag names to override
+ * @param options - CLI options applied to all overrides
+ */
+export async function furnaceBatchOverrideCommand(projectRoot, names, options = {}) {
+    intro(`Furnace Override (batch: ${names.length} components)`);
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    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.');
+    }
+    // Validate all names upfront before any mutations
+    for (const name of names) {
+        if (!CUSTOM_ELEMENT_TAG_PATTERN.test(name)) {
+            throw new InvalidArgumentError(`Invalid component name "${name}": ${CUSTOM_ELEMENT_TAG_RULES}`, 'name');
+        }
+    }
+    const config = await loadAuthoringFurnaceConfig(projectRoot);
+    const furnacePaths = getFurnacePaths(projectRoot);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
+    const forgeConfig = await loadConfig(projectRoot);
+    const state = await loadState(projectRoot);
+    // Check for duplicates and pre-existing overrides
+    const uniqueNames = [...new Set(names)];
+    for (const name of uniqueNames) {
+        if (name in config.overrides) {
+            throw new FurnaceError(`An override for "${name}" already exists in furnace.json`, name);
+        }
+    }
+    const succeeded = [];
+    const failed = [];
+    for (const componentName of uniqueNames) {
+        const details = await getComponentDetails(paths.engine, componentName, ftlDir);
+        if (!details) {
+            failed.push({ name: componentName, error: 'not found in engine source tree' });
+            continue;
+        }
+        let overrideType = options.type;
+        if (!overrideType) {
+            const typeResult = await select({
+                message: `Override type for ${componentName}:`,
+                options: [
+                    { value: 'css-only', label: 'CSS only — restyle the component' },
+                    { value: 'full', label: 'Full override — modify styling and behavior' },
+                ],
+            });
+            if (isCancel(typeResult)) {
+                info(`Skipping ${componentName} (cancelled)`);
+                continue;
+            }
+            overrideType = typeResult;
+        }
+        if (overrideType === 'css-only' && !details.hasCSS) {
+            failed.push({ name: componentName, error: 'no CSS files to override with --type css-only' });
+            continue;
+        }
+        const destDir = join(furnacePaths.overridesDir, componentName);
+        if (await pathExists(destDir)) {
+            failed.push({ name: componentName, error: 'directory already exists' });
+            continue;
+        }
+        try {
+            await performOverrideMutations({
+                projectRoot,
+                componentName,
+                overrideType,
+                description: options.description ?? '',
+                srcDir: join(paths.engine, details.sourcePath),
+                destDir,
+                engineDir: paths.engine,
+                details,
+                config,
+                furnacePaths,
+                ftlDir,
+                firefoxVersion: forgeConfig.firefox.version,
+                ...(state.baseCommit ? { baseCommit: state.baseCommit } : {}),
+            });
+            succeeded.push(componentName);
+        }
+        catch (error) {
+            failed.push({
+                name: componentName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    if (succeeded.length > 0) {
+        note(`Created ${succeeded.length} override(s):\n` +
+            succeeded.map((n) => `  components/overrides/${n}/`).join('\n') +
+            '\n\n' +
+            'Next steps:\n' +
+            '  1. Edit the copied files in each override directory\n' +
+            '  2. Run "fireforge furnace preview" to see changes\n' +
+            '  3. Run "fireforge build" to apply and build', 'Batch Override');
+    }
+    if (failed.length > 0) {
+        for (const f of failed) {
+            warn(`${f.name}: ${f.error}`);
+        }
+    }
+    if (succeeded.length === 0) {
+        throw new FurnaceError(`All ${uniqueNames.length} override(s) failed.`);
+    }
+    outro(`Batch override complete: ${succeeded.length} succeeded, ${failed.length} failed`);
+}
 //# sourceMappingURL=override.js.map

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

@@ -1,12 +1,77 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { getProjectPaths } from '../../core/config.js';
-import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
+import { applyAllComponents } from '../../core/furnace-apply.js';
+import { furnaceConfigExists, loadFurnaceConfig, updateFurnaceState, } from '../../core/furnace-config.js';
+import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { restoreRollbackJournal } from '../../core/furnace-rollback.js';
 import { cleanStories, syncStories } from '../../core/furnace-stories.js';
 import { runMach, runMachCapture } from '../../core/mach.js';
 import { FurnaceError } from '../../errors/furnace.js';
+import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
-import { info, intro, outro, spinner } from '../../utils/logger.js';
+import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
+/**
+ * Runs the two teardown steps — `cleanStories` and the rollback-journal
+ * restore — independently, collecting whatever errors either step throws.
+ * Both steps must run regardless of the other's outcome, because each
+ * operates on a different part of engine state and skipping one leaves
+ * the engine in a worse position than a single-step failure.
+ *
+ * Extracted from `furnacePreviewCommand` so the main function stays
+ * under the `max-lines-per-function` threshold and so the teardown
+ * contract is explicit in one place.
+ *
+ * @returns Collected teardown errors, or an empty array if both steps
+ *          succeeded (or no journal was ever created).
+ */
+async function runPreviewTeardown(engineDir, storiesCleanupRequired, journal) {
+    const errors = [];
+    if (storiesCleanupRequired) {
+        try {
+            await cleanStories(engineDir);
+        }
+        catch (error) {
+            const wrapped = toError(error);
+            errors.push(new Error(`Story cleanup: ${wrapped.message}`));
+        }
+    }
+    if (journal) {
+        try {
+            await restoreRollbackJournal(journal);
+        }
+        catch (error) {
+            const wrapped = toError(error);
+            errors.push(new Error(`Journal restore: ${wrapped.message}`));
+        }
+    }
+    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.
+ *
+ * @returns The total failure count if there were any (always non-zero when
+ *          this returns; the function throws after logging).
+ */
+function reportPreviewStagingFailures(stageResult) {
+    for (const err of stageResult.errors) {
+        warn(`Furnace: ${err.name} — ${err.error}`);
+    }
+    for (const applied of stageResult.applied) {
+        if (applied.stepErrors && applied.stepErrors.length > 0) {
+            for (const stepErr of applied.stepErrors) {
+                warn(`Furnace: ${applied.name} [${stepErr.step}] ${stepErr.error}`);
+            }
+        }
+    }
+    const appliedWithStepErrorsCount = stageResult.applied.filter((entry) => (entry.stepErrors?.length ?? 0) > 0).length;
+    const totalFailures = stageResult.errors.length + appliedWithStepErrorsCount;
+    throw new FurnaceError(`${totalFailures} component${totalFailures === 1 ? '' : 's'} failed to stage for preview`);
+}
 /**
  * Builds a targeted Storybook failure message from captured mach output.
  * @param output - Combined stdout and stderr from the Storybook command
@@ -55,37 +120,126 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
         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.');
     }
     let previewResult;
-    let storiesSynced = false;
-    try {
-        // Sync story files
-        const syncSpinner = spinner('Syncing component stories...');
-        const result = await syncStories(projectRoot);
-        storiesSynced = true;
-        const created = result.created.length;
-        const updated = result.updated.length;
-        const total = created + updated;
-        syncSpinner.stop(`Synced ${total} stories (${created} new, ${updated} updated)`);
-        // Force-reinstall Storybook dependencies if requested
-        if (options.install) {
-            const installSpinner = spinner('Reinstalling Storybook dependencies...');
-            const installCode = await runMach(['storybook', 'upgrade'], paths.engine);
-            if (installCode !== 0) {
-                installSpinner.stop('Failed to reinstall Storybook dependencies');
-                throw new FurnaceError('Storybook dependency reinstallation failed. Try running "python3 ./mach storybook upgrade" manually in the engine directory.');
+    // True once we are about to (or have) written to engine/.../stories/furnace.
+    // Intentionally set BEFORE `syncStories` is awaited so a mid-sync failure
+    // still triggers `cleanStories` during teardown. `cleanStories` is a
+    // full-directory wipe, so it is correct to run against partial state —
+    // including state with zero files, where it is a cheap no-op.
+    let storiesCleanupRequired = false;
+    let previewJournal;
+    let primaryError;
+    // The preview command runs under runFurnaceMutation so a SIGINT during
+    // Storybook still triggers cleanStories + journal restore via the CLI
+    // entrypoint's global signal handlers consulting the lifecycle registry.
+    // The body's own try/catch + teardown path handles the normal exit case
+    // (mach storybook returns or throws).
+    await runFurnaceMutation(projectRoot, 'preview-teardown', async (ctx) => {
+        // Register the stories cleanup as an extra teardown hook so the signal
+        // handler can wipe the staged stories directory in addition to the
+        // journal restore.
+        ctx.registerCleanup(async () => {
+            if (storiesCleanupRequired) {
+                await cleanStories(paths.engine);
+            }
+        });
+        try {
+            // Stage workspace override/custom files into engine/ so Storybook can
+            // resolve freshly edited chrome:// imports. Stock-only projects skip
+            // this step because stock components are never written from workspace
+            // sources.
+            if (overrideCount + customCount > 0) {
+                const stageSpinner = spinner('Staging components for preview...');
+                let stageResult;
+                try {
+                    stageResult = await applyAllComponents(projectRoot, false, {
+                        persistState: false,
+                        operationContext: ctx,
+                    });
+                }
+                catch (error) {
+                    stageSpinner.error('Failed to stage components');
+                    throw error;
+                }
+                previewJournal = stageResult.rollbackJournal;
+                if (previewJournal) {
+                    ctx.registerJournal(previewJournal);
+                }
+                const appliedWithStepErrorsCount = stageResult.applied.filter((entry) => (entry.stepErrors?.length ?? 0) > 0).length;
+                const totalFailures = stageResult.errors.length + appliedWithStepErrorsCount;
+                if (totalFailures > 0) {
+                    stageSpinner.error('Failed to stage components');
+                    reportPreviewStagingFailures(stageResult);
+                }
+                stageSpinner.stop(`Staged ${stageResult.applied.length} component${stageResult.applied.length === 1 ? '' : 's'} for preview`);
+            }
+            // Sync story files. Set the cleanup flag before the await so a partial
+            // write failure still triggers the teardown wipe — `syncStories` writes
+            // files incrementally with no internal cleanup of its own.
+            const syncSpinner = spinner('Syncing component stories...');
+            storiesCleanupRequired = true;
+            const result = await syncStories(projectRoot);
+            const created = result.created.length;
+            const updated = result.updated.length;
+            const total = created + updated;
+            syncSpinner.stop(`Synced ${total} stories (${created} new, ${updated} updated)`);
+            // Force-reinstall Storybook dependencies if requested
+            if (options.install) {
+                const installSpinner = spinner('Reinstalling Storybook dependencies...');
+                const installCode = await runMach(['storybook', 'upgrade'], paths.engine);
+                if (installCode !== 0) {
+                    installSpinner.stop('Failed to reinstall Storybook dependencies');
+                    throw new FurnaceError('Storybook dependency reinstallation failed. Try running "python3 ./mach storybook upgrade" manually in the engine directory.');
+                }
+                installSpinner.stop('Storybook dependencies reinstalled');
             }
-            installSpinner.stop('Storybook dependencies reinstalled');
+            // Start Storybook
+            info('Starting Storybook...');
+            info('Press Ctrl+C to stop\n');
+            previewResult = await runMachCapture(['storybook'], paths.engine);
         }
-        // Start Storybook
-        info('Starting Storybook...');
-        info('Press Ctrl+C to stop\n');
-        previewResult = await runMachCapture(['storybook'], paths.engine);
-    }
-    finally {
-        if (storiesSynced) {
-            await cleanStories(paths.engine);
+        catch (error) {
+            primaryError = error;
         }
-    }
-    if (previewResult.exitCode !== 0 &&
+        // 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.
+        const teardownErrors = await runPreviewTeardown(paths.engine, storiesCleanupRequired, previewJournal);
+        if (teardownErrors.length > 0) {
+            const teardownSummary = teardownErrors.map((err) => err.message).join('; ');
+            try {
+                await updateFurnaceState(projectRoot, (state) => ({
+                    ...state,
+                    pendingRepair: {
+                        operation: 'preview-teardown',
+                        timestamp: new Date().toISOString(),
+                        reason: teardownSummary,
+                    },
+                }));
+            }
+            catch (markError) {
+                warn(`Could not record pending-repair marker in .fireforge/furnace-state.json — ${toError(markError).message}. Engine may still be in a staged state; run "fireforge furnace apply" manually to reconcile.`);
+            }
+            const primarySuffix = primaryError
+                ? ` (original error: ${toError(primaryError).message})`
+                : '';
+            throw new FurnaceError(`Preview teardown could not restore the engine cleanly: ${teardownSummary}. The engine may contain staged workspace files. Run "fireforge doctor --repair-furnace" to reconcile, or run "fireforge furnace apply" manually.${primarySuffix}`);
+        }
+        if (primaryError) {
+            // Re-throwing the captured error preserves its original shape. The
+            // `toError` wrap normalises non-Error throws (strings, plain objects)
+            // into real Error instances so the eslint `only-throw-error` rule
+            // holds and downstream formatters always see a message/stack pair.
+            throw toError(primaryError);
+        }
+    });
+    if (previewResult &&
+        previewResult.exitCode !== 0 &&
         previewResult.exitCode !== 130 &&
         previewResult.exitCode !== 143) {
         const combinedOutput = `${previewResult.stdout}\n${previewResult.stderr}`;

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

@@ -0,0 +1,10 @@
+import type { FurnaceRefreshOptions } from '../../types/commands/index.js';
+/**
+ * Runs the furnace refresh command to merge upstream Firefox changes into
+ * an override component using three-way merge.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param name - Component tag name to refresh (omit when using --all)
+ * @param options - Command options
+ */
+export declare function furnaceRefreshCommand(projectRoot: string, name: string | undefined, options?: FurnaceRefreshOptions): Promise<void>;