@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,349 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { applyAllComponents } from '../../core/furnace-apply.js';
-import { updateFurnaceState } from '../../core/furnace-config.js';
-import { runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
-import { assertFurnaceReady } from '../../core/furnace-precondition.js';
-import { restoreRollbackJournal } from '../../core/furnace-rollback.js';
-import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
-import { cleanStories, syncStories } from '../../core/furnace-stories.js';
-import { hasBuildArtifacts, 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, 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.
- *
- * Never returns: it always throws after logging, which is what the `never`
- * return type states.
- */
-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 = countEntriesWithBlockingStepErrors(stageResult.applied);
-    const totalFailures = stageResult.errors.length + appliedWithStepErrorsCount;
-    throw new FurnaceError(`${totalFailures} component${totalFailures === 1 ? '' : 's'} failed to stage for preview`);
-}
-/**
- * Filenames emitted by the Firefox build backend (not by Storybook's npm
- * package set). Their absence means `mach build` has not produced its
- * post-configure artifacts, which is a different failure mode from a missing
- * Storybook workspace dependency tree. A
- * `FileNotFoundError: [...] chrome-map.json` after a successful Storybook
- * `npm install` is the case a dep-focused heuristic misdiagnoses, sending
- * the operator back to `--install`. The pattern list is narrow on purpose so
- * the backend-rebuild hint only fires when it is confident.
- */
-const BACKEND_ARTIFACT_PATTERNS = [
-    /chrome-map\.json/i,
-    /config\.status/i,
-    /obj-[^\s/]+\/dist\/bin\/\.lldbinit/i,
-];
-/**
- * Builds a targeted Storybook failure message from captured mach output.
- *
- * Exported for the test suite: the heuristic has three branches (backend
- * artifact missing, Storybook dep missing, generic) and regression
- * testing each is easier when the classifier is addressable directly.
- *
- * @param output - Combined stdout and stderr from the Storybook command
- * @param installRequested - Whether the caller requested a dependency reinstall first
- * @returns User-facing guidance for the specific failure mode
- */
-export function buildStorybookFailureMessage(output, installRequested) {
-    const installHint = installRequested
-        ? 'Try running "python3 ./mach storybook upgrade" manually in the engine directory.'
-        : 'Run "fireforge furnace preview --install" to bootstrap Storybook dependencies, or run "python3 ./mach storybook upgrade" manually in engine/.';
-    const hasFileNotFoundSignal = /(ENOENT|No such file or directory|FileNotFoundError)/i.test(output);
-    // Check the backend-artifact signal first: a missing chrome-map.json looks
-    // like any other "No such file" error to a naïve regex, but the fix is
-    // to rerun `fireforge build`, not to reinstall Storybook dependencies.
-    if (hasFileNotFoundSignal && BACKEND_ARTIFACT_PATTERNS.some((p) => p.test(output))) {
-        return ('Storybook failed because the Firefox build backend artifacts are missing or stale ' +
-            '(chrome-map.json / config.status / obj-*/dist/bin/.lldbinit). ' +
-            'This is a Firefox-build completeness issue, not a Storybook dependency issue.\n\n' +
-            'Rerun "fireforge build" and let it finish, then retry "fireforge furnace preview". ' +
-            'A full rebuild regenerates the backend artifacts Storybook reads.');
-    }
-    if (hasFileNotFoundSignal && /storybook|backend/i.test(output)) {
-        return ('Storybook failed because the Firefox checkout appears to be missing Storybook workspace files or backend dependencies.\n\n' +
-            installHint);
-    }
-    return ('Storybook failed to start. Check the output above for the specific Firefox-side error.\n\n' +
-        installHint);
-}
-/**
- * Preflights the Firefox build + toolchain prerequisites `mach storybook`
- * quietly assumes. Without it, preview stages components and launches a
- * ~1000-package `mach storybook upgrade` npm install before the backend
- * surfaces a "missing chrome-map.json" / Cargo-config failure. This refuses
- * fast and leaves the workspace untouched.
- *
- * @param engineDir - Resolved engine directory
- * @throws FurnaceError when the Firefox build has not produced dist/, or
- *   when `.cargo/config.toml` is absent
- */
-async function assertPreviewPrerequisites(engineDir) {
-    const buildCheck = await hasBuildArtifacts(engineDir);
-    if (!buildCheck.exists) {
-        throw new FurnaceError('Furnace preview requires a completed Firefox build. ' +
-            '`mach storybook` consumes `obj-*/dist/chrome-map.json` and the packaged chrome resources under `dist/`, neither of which is present before `fireforge build` completes.\n\n' +
-            'Run "fireforge build" and wait for it to finish, then rerun "fireforge furnace preview". ' +
-            'This preflight avoids a multi-minute `mach storybook upgrade` npm install on an engine that cannot start Storybook anyway.');
-    }
-    // Accept either `.cargo/config.toml` (post-configure) or
-    // `.cargo/config.toml.in` (post-bootstrap template, consumed at
-    // `mach configure` time). Insisting on the plain file makes operators who
-    // follow the remediation instruction ("run bootstrap then rerun preview")
-    // hit the same refusal on the retry, because `fireforge bootstrap` alone
-    // produces only `.in`. Either name is sufficient to prove the Rust
-    // toolchain is registered. The stronger `hasBuildArtifacts` check above
-    // already guards against a completely un-configured tree.
-    const cargoConfigPath = join(engineDir, '.cargo', 'config.toml');
-    const cargoConfigInPath = join(engineDir, '.cargo', 'config.toml.in');
-    const cargoConfigPresent = (await pathExists(cargoConfigPath)) || (await pathExists(cargoConfigInPath));
-    if (!cargoConfigPresent) {
-        throw new FurnaceError("Furnace preview requires the engine's Rust toolchain to be bootstrapped. " +
-            'Neither `.cargo/config.toml` nor `.cargo/config.toml.in` exists under the engine directory — ' +
-            '`mach storybook` fails deep inside the Storybook backend compile without either of them.\n\n' +
-            'Run "fireforge bootstrap" (or the underlying `mach bootstrap` in the engine) to populate the toolchain config, then rerun "fireforge furnace preview".');
-    }
-}
-/**
- * Emits a framing banner when the Storybook workspace has not yet had its npm
- * dependencies installed. `mach storybook` drives the install internally and
- * prints ELSPROBLEMS / UNMET DEPENDENCY lines verbatim. Without this banner
- * operators reliably read the npm output as a failure.
- *
- * Skipped when `--install` was explicitly requested, since that path runs
- * `mach storybook upgrade` before the preview launches, so the npm output
- * for the subsequent `mach storybook` invocation is a no-op.
- */
-async function announceStorybookFirstRunIfNeeded(engineDir, installRequested) {
-    if (installRequested)
-        return;
-    const storybookNodeModules = join(engineDir, 'browser', 'components', 'storybook', 'node_modules');
-    const storybookDepsMissing = !(await pathExists(storybookNodeModules));
-    if (!storybookDepsMissing)
-        return;
-    info('Storybook workspace dependencies are not yet installed. The next step will install ~1000 npm packages via `mach storybook`; expect npm error-style output below. This is a one-time first-run cost — Storybook will start once the install finishes.');
-}
-/**
- * Surfaces an explicit success banner after a clean mach-storybook
- * exit so the operator's scrollback visually terminates the npm noise
- * from the first-run install. Only fires on expected exit codes. Non-zero
- * cases fall through to the existing `buildStorybookFailureMessage`
- * classification.
- */
-function announceStorybookCleanExitIfApplicable(exitCode) {
-    if (exitCode === 0 || exitCode === 130 || exitCode === 143) {
-        info('Storybook stopped cleanly.');
-    }
-}
-/**
- * Runs the furnace preview command to start Storybook for component preview.
- * @param projectRoot - Root directory of the project
- * @param options - Command options
- */
-export async function furnacePreviewCommand(projectRoot, options = {}) {
-    intro('Furnace Preview (Storybook)');
-    const { paths, config } = await assertFurnaceReady(projectRoot);
-    const stockCount = config.stock.length;
-    const overrideCount = Object.keys(config.overrides).length;
-    const customCount = Object.keys(config.custom).length;
-    const totalCount = stockCount + overrideCount + customCount;
-    if (totalCount === 0) {
-        info('No components to preview.');
-        outro('Done');
-        return;
-    }
-    const storybookRoot = join(paths.engine, 'browser', 'components', 'storybook');
-    if (!(await pathExists(storybookRoot))) {
-        throw new FurnaceError('This Firefox checkout does not contain browser/components/storybook. Furnace preview requires the upstream Storybook workspace to exist before stories can be synced.');
-    }
-    // Build + toolchain preflight, extracted into a helper so the function
-    // below stays under the per-function LOC budget.
-    await assertPreviewPrerequisites(paths.engine);
-    let previewResult;
-    // True once we are about to (or have) written to engine/.../stories/furnace.
-    // 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).
-    const mutate = 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 = countEntriesWithBlockingStepErrors(stageResult.applied);
-                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');
-            }
-            // Frame the npm noise `mach storybook` emits on first run as expected
-            // progress rather than a failure.
-            await announceStorybookFirstRunIfNeeded(paths.engine, options.install ?? false);
-            // Start Storybook
-            info('Starting Storybook...');
-            info('Press Ctrl+C to stop\n');
-            previewResult = await runMachCapture(['storybook'], paths.engine);
-            announceStorybookCleanExitIfApplicable(previewResult.exitCode);
-        }
-        catch (error) {
-            primaryError = error;
-        }
-        // Teardown runs unconditionally and never short-circuits: a failure in
-        // cleanStories must not prevent the journal restore, and vice versa.
-        // Running teardown in a `finally` that calls
-        // `restoreRollbackJournalOrThrow` throws synchronously, bypassing the
-        // primary error and skipping downstream handling, so the engine is left
-        // with staged files and the user gets a teardown message with no
-        // guidance. Both failures are collected instead and, if anything went
-        // wrong, a `pendingRepair` marker is persisted for `fireforge doctor` to
-        // finish the reconciliation.
-        //
-        // Teardown restores the journal itself, so the lifecycle wrapper must
-        // not restore it again when the throw below propagates out of this body.
-        ctx.markRolledBack();
-        const teardownErrors = await runPreviewTeardown(paths.engine, storiesCleanupRequired, previewJournal);
-        if (teardownErrors.length > 0) {
-            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);
-        }
-    };
-    await runFurnaceMutation(projectRoot, 'preview-teardown', mutate, waitLockMutationOptions(options.waitLockSeconds));
-    if (previewResult &&
-        previewResult.exitCode !== 0 &&
-        previewResult.exitCode !== 130 &&
-        previewResult.exitCode !== 143) {
-        const combinedOutput = `${previewResult.stdout}\n${previewResult.stderr}`;
-        throw new FurnaceError(buildStorybookFailureMessage(combinedOutput, options.install ?? false));
-    }
-    outro('Storybook stopped');
-}

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

@@ -1,10 +0,0 @@
-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>;

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

@@ -1,303 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { getProjectPaths, loadConfig, loadState } from '../../core/config.js';
-import { getOverrideEngineTargetPath } from '../../core/furnace-apply-helpers.js';
-import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { resolveFtlDir } from '../../core/furnace-constants.js';
-import { isComponentSourceFile } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
-import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
-import { refreshOverrideFile } from '../../core/furnace-refresh.js';
-import { createRollbackJournal, restoreRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
-import { getHead } from '../../core/git.js';
-import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
-import { pathExists } from '../../utils/fs.js';
-import { formatErrorText, formatSuccessText, info, intro, note, outro, warn, } from '../../utils/logger.js';
-function displayRefreshResults(results, name, currentVersion, dryRun) {
-    const merged = results.filter((r) => r.status === 'merged');
-    const conflicts = results.filter((r) => r.status === 'conflict');
-    const unchanged = results.filter((r) => r.status === 'unchanged');
-    const newFiles = results.filter((r) => r.status === 'new-file');
-    for (const r of merged) {
-        info(formatSuccessText(`  merged: ${r.fileName}`));
-    }
-    for (const r of unchanged) {
-        info(`  unchanged: ${r.fileName}`);
-    }
-    for (const r of newFiles) {
-        info(`  new file: ${r.fileName}`);
-    }
-    if (conflicts.length > 0) {
-        for (const r of conflicts) {
-            info(formatErrorText(`  CONFLICT: ${r.fileName} (${r.conflictMarkers} marker(s))`));
-        }
-        warn('Conflict markers have been left in the affected files. ' +
-            `Resolve them manually, then re-run "fireforge furnace refresh ${name}" to update baseVersion.`);
-    }
-    const summary = `${merged.length} merged, ${unchanged.length} unchanged, ` +
-        `${newFiles.length} new, ${conflicts.length} conflicts`;
-    if (dryRun) {
-        note(summary, 'Dry Run Summary');
-        outro('Dry run complete (no files modified)');
-    }
-    else if (conflicts.length > 0) {
-        note(summary, 'Refresh Summary');
-        outro('Refresh complete with conflicts — resolve before applying');
-    }
-    else {
-        note(`${summary}\nbaseVersion updated to ${currentVersion} in furnace.json`, 'Refresh Summary');
-        outro('Refresh complete');
-    }
-}
-/**
- * Refreshes a single override component against the current Firefox source.
- * Returns the per-file merge results.
- */
-async function refreshSingleOverride(projectRoot, name, options = {}) {
-    const config = await loadFurnaceConfig(projectRoot);
-    const paths = getProjectPaths(projectRoot);
-    const furnacePaths = getFurnacePaths(projectRoot);
-    const ftlDir = resolveFtlDir(config.ftlBasePath);
-    // Only overrides can be refreshed
-    const overrideConfig = config.overrides[name];
-    if (!overrideConfig) {
-        throw new FurnaceError(`"${name}" is not an override component. Only overrides can be refreshed against upstream.`, name);
-    }
-    const overrideDir = join(furnacePaths.overridesDir, name);
-    if (!(await pathExists(overrideDir))) {
-        throw new FurnaceError(`Override directory not found: components/overrides/${name}`, name);
-    }
-    const forgeConfig = await loadConfig(projectRoot);
-    const currentVersion = forgeConfig.firefox.version;
-    const state = await loadState(projectRoot);
-    // --reset-base: skip three-way merge and re-snapshot the current engine
-    // state as the new baseline. This recovers from unreachable baseCommits
-    // (e.g. after history rewrite or re-clone).
-    if (options.resetBase) {
-        const headCommit = await getHead(paths.engine);
-        info(`Resetting "${name}" baseline to Firefox ${currentVersion} (${headCommit.slice(0, 8)}). ` +
-            'Three-way merge skipped — current workspace content is preserved as-is.');
-        if (!options.dryRun) {
-            const freshConfig = await loadFurnaceConfig(projectRoot);
-            freshConfig.overrides[name] = {
-                ...overrideConfig,
-                baseVersion: currentVersion,
-                baseCommit: headCommit,
-            };
-            await writeFurnaceConfig(projectRoot, freshConfig);
-        }
-        return { results: [], currentVersion };
-    }
-    // Prefer the per-override baseCommit (survives download --force). Fall
-    // back to the project-wide value for overrides created before this field existed.
-    const baseCommit = overrideConfig.baseCommit ?? state.baseCommit;
-    if (!baseCommit) {
-        throw new FurnaceError('Cannot refresh: baseCommit not found. Re-run "fireforge download" to establish a baseline, ' +
-            'or use --reset-base to snapshot the current engine as the new baseline.', name);
-    }
-    // If there's no version drift, refreshing is a no-op
-    if (overrideConfig.baseVersion === currentVersion) {
-        info(`Override "${name}" is already at Firefox ${currentVersion}. Nothing to refresh.`);
-        return { results: [], currentVersion };
-    }
-    info(`Refreshing "${name}": Firefox ${overrideConfig.baseVersion} → ${currentVersion}`);
-    // Collect override files
-    const entries = await readdir(overrideDir, { withFileTypes: true });
-    const overrideFiles = entries.filter((e) => e.isFile() && isComponentSourceFile(e.name));
-    if (overrideFiles.length === 0) {
-        info('No source files to refresh.');
-        return { results: [], currentVersion };
-    }
-    const dryRun = options.dryRun ?? false;
-    const strategy = options.strategy;
-    // Run all merges within a transactional mutation so failures can be rolled back
-    const results = await runFurnaceMutation(projectRoot, 'refresh-rollback', async (ctx) => {
-        const journal = createRollbackJournal();
-        ctx.registerJournal(journal);
-        try {
-            const fileResults = [];
-            if (!dryRun) {
-                // Snapshot all override files before mutation
-                await snapshotDir(journal, overrideDir);
-                await snapshotFile(journal, furnacePaths.furnaceConfig);
-            }
-            for (const entry of overrideFiles) {
-                const overridePath = join(overrideDir, entry.name);
-                const engineRelPath = getOverrideEngineTargetPath(paths.engine, overrideConfig, entry.name, ftlDir).slice(paths.engine.length + 1);
-                const result = await refreshOverrideFile({
-                    engineDir: paths.engine,
-                    overridePath,
-                    engineRelPath,
-                    baseCommit,
-                    fileName: entry.name,
-                    dryRun,
-                    strategy,
-                });
-                fileResults.push(result);
-            }
-            // Update baseVersion and baseCommit on clean merge (not dry-run, no conflicts)
-            const hasConflicts = fileResults.some((r) => r.status === 'conflict');
-            if (!dryRun && !hasConflicts) {
-                // Re-load config to pick up any concurrent changes from a prior override
-                // in a batch refresh.
-                const freshConfig = await loadFurnaceConfig(projectRoot);
-                freshConfig.overrides[name] = {
-                    ...overrideConfig,
-                    baseVersion: currentVersion,
-                    baseCommit: await getHead(paths.engine),
-                };
-                await writeFurnaceConfig(projectRoot, freshConfig);
-            }
-            return fileResults;
-        }
-        catch (error) {
-            // A dry run wrote nothing, so there is no journal to restore. It
-            // rethrows without touching the lifecycle wrapper.
-            if (!dryRun) {
-                return await completeJournalRollback(ctx, journal, error, {
-                    projectRoot,
-                    operation: 'refresh-rollback',
-                    failureMessage: `Failed to refresh override "${name}"`,
-                    subject: `override "${name}"`,
-                });
-            }
-            throw error;
-        }
-    }, { dryRun, ...waitLockMutationOptions(options.waitLockSeconds) });
-    return { results, currentVersion };
-}
-/**
- * Refreshes every override sequentially, tallying merged/conflict/
- * unchanged file counts. Per-override errors are expected (warned and
- * recorded as failures) and do not abort the batch. Only an error that
- * escapes this function entirely warrants the caller's journal rollback.
- */
-async function runBatchRefresh(projectRoot, overrideNames, options) {
-    let totalMerged = 0;
-    let totalConflicts = 0;
-    let totalUnchanged = 0;
-    let totalSkipped = 0;
-    const conflictComponents = [];
-    const failedOverrides = [];
-    for (const overrideName of overrideNames) {
-        try {
-            const { results } = await refreshSingleOverride(projectRoot, overrideName, options);
-            if (results.length === 0) {
-                totalSkipped++;
-                continue;
-            }
-            for (const r of results) {
-                if (r.status === 'merged')
-                    totalMerged++;
-                else if (r.status === 'conflict') {
-                    totalConflicts++;
-                    if (!conflictComponents.includes(overrideName)) {
-                        conflictComponents.push(overrideName);
-                    }
-                }
-                else if (r.status === 'unchanged')
-                    totalUnchanged++;
-            }
-        }
-        catch (error) {
-            const message = toError(error).message;
-            warn(`${overrideName}: ${message}`);
-            failedOverrides.push({ name: overrideName, message });
-        }
-    }
-    return {
-        totalMerged,
-        totalConflicts,
-        totalUnchanged,
-        totalSkipped,
-        conflictComponents,
-        failedOverrides,
-    };
-}
-/**
- * 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 async function furnaceRefreshCommand(projectRoot, name, options = {}) {
-    const refreshAll = options.all ?? false;
-    if (!name && !refreshAll) {
-        throw new FurnaceError('Specify a component name or use --all to refresh every override.');
-    }
-    if (name && refreshAll) {
-        throw new FurnaceError('Cannot specify both a component name and --all. Use one or the other.');
-    }
-    // Verify engine exists: refresh reads engine files for three-way merge
-    // and --reset-base reads engine HEAD. Without this check, the user gets
-    // an obscure git error instead of a clear precondition message.
-    await assertFurnaceEngineReady(projectRoot);
-    const dryRun = options.dryRun ?? false;
-    if (name) {
-        intro('Furnace Refresh');
-        if (dryRun) {
-            info('Dry run — showing what would change without modifying files.');
-        }
-        const { results, currentVersion } = await refreshSingleOverride(projectRoot, name, options);
-        if (results.length > 0) {
-            displayRefreshResults(results, name, currentVersion, dryRun);
-        }
-        else {
-            outro('Done');
-        }
-        return;
-    }
-    // --all mode: refresh every override sequentially
-    intro('Furnace Refresh (all overrides)');
-    if (dryRun) {
-        info('Dry run — showing what would change without modifying files.');
-    }
-    const config = await loadFurnaceConfig(projectRoot);
-    const overrideNames = Object.keys(config.overrides);
-    if (overrideNames.length === 0) {
-        info('No overrides to refresh.');
-        outro('Done');
-        return;
-    }
-    // Snapshot furnace.json before the batch loop so an unexpected failure
-    // (process crash, unhandled error) can be recovered from. Per-component
-    // errors caught below are expected and do not trigger a restore. Only
-    // an error that escapes the loop entirely warrants rolling back.
-    const batchJournal = dryRun ? undefined : createRollbackJournal();
-    if (batchJournal) {
-        const furnacePaths = getFurnacePaths(projectRoot);
-        await snapshotFile(batchJournal, furnacePaths.furnaceConfig);
-    }
-    let tally;
-    try {
-        tally = await runBatchRefresh(projectRoot, overrideNames, options);
-    }
-    catch (error) {
-        // Unexpected batch-level failure: restore furnace.json to its
-        // pre-batch state so the config is not left partially updated.
-        if (batchJournal) {
-            await restoreRollbackJournal(batchJournal);
-        }
-        throw error;
-    }
-    const { totalMerged, totalConflicts, totalUnchanged, totalSkipped } = tally;
-    const { conflictComponents, failedOverrides } = tally;
-    const summary = `${overrideNames.length} override(s) processed, ${totalSkipped} already up-to-date\n` +
-        `${totalMerged} file(s) merged, ${totalUnchanged} unchanged, ${totalConflicts} conflict(s), ` +
-        `${failedOverrides.length} failed`;
-    if (conflictComponents.length > 0) {
-        warn(`Conflicts in: ${conflictComponents.join(', ')}. ` +
-            'Resolve conflict markers, then re-run refresh for those components to update baseVersion.');
-    }
-    note(summary, dryRun ? 'Dry Run Summary' : 'Refresh Summary');
-    if (failedOverrides.length > 0) {
-        outro(dryRun ? 'Dry run completed with failures' : 'Refresh completed with failures');
-        throw new FurnaceError(`Failed to refresh ${failedOverrides.length} override(s): ` +
-            failedOverrides.map((failure) => `${failure.name}: ${failure.message}`).join('; '));
-    }
-    outro(dryRun ? 'Dry run complete' : 'Refresh complete');
-}