@hominis/fireforge 0.10.1 → 0.11.0

package/dist/src/core/furnace-apply-helpers.js

@@ -4,30 +4,86 @@ import { readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
-import { copyFile, ensureDir, pathExists, readText } from '../utils/fs.js';
+import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-import { addCustomElementRegistration, addJarMnEntries } from './furnace-registration.js';
+import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnEntries, } from './furnace-registration.js';
 import { recordCreatedDir, snapshotFile } from './furnace-rollback.js';
-/** Path to the Fluent localization directory for toolkit global components */
-const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
+import { checkRegistrationConsistency } from './furnace-validate-registration.js';
+import { isGitRepository } from './git.js';
+import { fileExistsInHead, restoreTrackedPath } from './git-file-ops.js';
+function isRegularFile(entry) {
+    if (!entry.isFile())
+        return false;
+    if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink())
+        return false;
+    return true;
+}
 function isChecksummedComponentFile(name) {
     return name.endsWith('.mjs') || name.endsWith('.css') || name.endsWith('.ftl');
 }
-function isOverrideCopyCandidate(entryName, type) {
+/**
+ * Filter deciding which files in an override workspace directory are candidates
+ * for copying into the engine. Exported so `furnace remove` can invert apply
+ * using the exact same file set — the "files to restore" set is defined as the
+ * inverse of the "files apply would have written" set.
+ */
+export function isOverrideCopyCandidate(entryName, type) {
     if (entryName === 'override.json') {
         return false;
     }
     if (type === 'css-only') {
         return entryName.endsWith('.css');
     }
-    return entryName.endsWith('.mjs') || entryName.endsWith('.css');
+    return entryName.endsWith('.mjs') || entryName.endsWith('.css') || entryName.endsWith('.ftl');
+}
+/** Resolves the engine destination path for a single override-managed file. */
+export function getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir) {
+    return fileName.endsWith('.ftl')
+        ? join(engineDir, ftlDir, fileName)
+        : join(engineDir, config.basePath, fileName);
+}
+/**
+ * Restores a single override-deployed engine file to its pristine HEAD state,
+ * inverting whatever apply wrote into that path.
+ *
+ * Behaviour matches the per-file branch of `restoreOverrideEngineFiles` in
+ * `furnace remove`: snapshot first, then either `git restore` (if the file
+ * exists in HEAD) or hard-delete (if the override introduced the file). The
+ * caller MUST guarantee `engineDir` is a git repository — this helper does
+ * not re-check, because both `furnace remove` and `furnace apply` already
+ * own the precondition check at their entry points and re-checking on every
+ * file would balloon git invocations.
+ *
+ * Returns the action taken so the caller can produce accurate user-facing
+ * counts (`restored` vs `removed`). `noop` means the file was neither in HEAD
+ * nor on disk, which can happen when the engine was reset out-of-band — the
+ * caller should treat that as a successful no-op rather than an error.
+ */
+export async function restoreOverrideFileToBaseline(engineDir, enginePath, journal) {
+    const relPath = relative(engineDir, enginePath);
+    // Snapshot before mutation so a later rollback can undo both restoration
+    // (writes whatever content we removed back) and deletion (recreates the
+    // file). Snapshotting a missing path records `{ existed: false }`, which
+    // restoreFile turns into a delete — exactly the inverse of "we just
+    // wrote a file here", which is correct for the noop case too.
+    await snapshotFile(journal, enginePath);
+    if (await fileExistsInHead(engineDir, relPath)) {
+        await restoreTrackedPath(engineDir, relPath);
+        return 'restored';
+    }
+    if (await pathExists(enginePath)) {
+        await removeFile(enginePath);
+        return 'removed';
+    }
+    return 'noop';
 }
 /** Computes stable checksums for the source files that define a component. */
 export async function computeComponentChecksums(componentDir) {
     const checksums = {};
     const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
     for (const entry of entries) {
-        if (!entry.isFile())
+        if (!isRegularFile(entry))
             continue;
         if (entry.name === 'override.json')
             continue;
@@ -40,6 +96,92 @@ export async function computeComponentChecksums(componentDir) {
     }
     return checksums;
 }
+/**
+ * Returns the filenames present in `previous` that are absent from `current`
+ * — i.e. files we know we deployed last time but the workspace has since
+ * deleted. The order of returned names is intentionally stable
+ * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ */
+export function diffDeletedFiles(previous, current) {
+    const deleted = [];
+    for (const key of Object.keys(previous)) {
+        if (!(key in current)) {
+            deleted.push(key);
+        }
+    }
+    return deleted.sort();
+}
+/**
+ * Removes engine copies of files that the developer has deleted from a custom
+ * component's workspace since the last apply. `.ftl` files live under the
+ * shared Fluent tree (`engine/${FTL_DIR}`); everything else lives under
+ * `engine/${config.targetPath}`. Snapshots each removal into the journal so a
+ * mid-apply failure can roll the engine back to its pre-undeploy state. Files
+ * that are already missing from the engine are silently no-op (the engine
+ * may have been reset out-of-band — refusing here would surface a confusing
+ * error in a recovery path).
+ *
+ * Does **not** touch jar.mn or customElements.js: registration churn is the
+ * caller's responsibility, since it must coordinate with the new file list
+ * computed by the regular apply step that follows.
+ */
+export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDir, rollbackJournal) {
+    const removed = [];
+    for (const fileName of deletedFiles) {
+        const enginePath = fileName.endsWith('.ftl')
+            ? join(engineDir, ftlDir, fileName)
+            : join(engineDir, config.targetPath, fileName);
+        if (rollbackJournal) {
+            await snapshotFile(rollbackJournal, enginePath);
+        }
+        if (await pathExists(enginePath)) {
+            await removeFile(enginePath);
+            removed.push(relative(engineDir, enginePath));
+        }
+    }
+    return removed;
+}
+/**
+ * Restores or removes engine copies of files that the developer has deleted
+ * from an override component's workspace since the last apply. Each file is
+ * routed through `restoreOverrideFileToBaseline`, which restores it from
+ * HEAD if it was a Firefox baseline file or hard-deletes it if the override
+ * had introduced it.
+ *
+ * Requires `engineDir` to be a git repository — overrides cannot be inverted
+ * without git HEAD as the source of truth. The caller is expected to have
+ * already validated this precondition for the apply path; we re-check here
+ * so unit tests that exercise this helper directly cannot accidentally
+ * silent-fail on a non-git fixture.
+ */
+export async function undeployOverrideFiles(engineDir, config, deletedFiles, ftlDir, rollbackJournal) {
+    if (deletedFiles.length === 0) {
+        return { restored: [], removed: [] };
+    }
+    if (!rollbackJournal) {
+        throw new FurnaceError('Internal: undeployOverrideFiles requires a rollback journal so deletions can be undone on failure.');
+    }
+    if (!(await isGitRepository(engineDir))) {
+        throw new FurnaceError('Cannot undeploy override files: engine is not a git repository. Run "fireforge download" to initialise it.');
+    }
+    // Note: we deliberately do not re-filter `deletedFiles` through
+    // `isOverrideCopyCandidate(fileName, config.type)`. A file recorded in
+    // `previous` was already a valid copy candidate when it was deployed, and
+    // re-filtering would block cleanup if the override type later flipped
+    // from `full` to `css-only` — exactly the case we need cleanup for.
+    const restored = [];
+    const removed = [];
+    for (const fileName of deletedFiles) {
+        const enginePath = getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir);
+        const action = await restoreOverrideFileToBaseline(engineDir, enginePath, rollbackJournal);
+        const relPath = relative(engineDir, enginePath);
+        if (action === 'restored')
+            restored.push(relPath);
+        else if (action === 'removed')
+            removed.push(relPath);
+    }
+    return { restored, removed };
+}
 /** Compares current component file checksums against the previously recorded state. */
 export async function hasComponentChanged(componentDir, previousChecksums) {
     const current = await computeComponentChecksums(componentDir);
@@ -55,10 +197,99 @@ export async function hasComponentChanged(componentDir, previousChecksums) {
     }
     return false;
 }
-async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries) {
+function normalizeForChecksum(content) {
+    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+}
+/**
+ * Detects whether an override component's deployed files are missing from the
+ * engine or differ from the source. Used as a guard before skipping apply on a
+ * checksum match, so that reset/download/manual engine edits do not leave the
+ * caller with a stale "up to date" report.
+ *
+ * When `cachedEngineChecksums` is provided (populated on last successful apply),
+ * the function computes a SHA-256 hash of the engine file and compares it
+ * against the cached value. This avoids reading the full workspace source for
+ * the comparison when the engine hash still matches, which is the common case
+ * for projects with many components.
+ */
+export async function hasOverrideEngineDrift(engineDir, componentDir, config, ftlDir, cachedEngineChecksums) {
+    const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
+    for (const entry of entries) {
+        if (!isRegularFile(entry))
+            continue;
+        if (!isOverrideCopyCandidate(entry.name, config.type))
+            continue;
+        const enginePath = getOverrideEngineTargetPath(engineDir, config, entry.name, ftlDir);
+        if (!(await pathExists(enginePath))) {
+            return true;
+        }
+        const engineContent = normalizeForChecksum(await readText(enginePath));
+        // Fast path: compare engine content hash against cached value from last apply
+        if (cachedEngineChecksums) {
+            const engineHash = createHash('sha256').update(engineContent).digest('hex');
+            const cachedHash = cachedEngineChecksums[entry.name];
+            if (cachedHash && engineHash !== cachedHash) {
+                return true;
+            }
+            if (cachedHash)
+                continue; // Hash match — skip full source comparison
+        }
+        // Slow path: byte-compare engine content against workspace source
+        const srcContent = normalizeForChecksum(await readText(join(componentDir, entry.name)));
+        if (srcContent !== engineContent) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Detects whether a custom component's deployed copies, jar.mn entries, or
+ * customElements.js registration are missing from the engine or out of sync.
+ * Delegates to `checkRegistrationConsistency` so the oracle stays aligned with
+ * the validate command.
+ */
+export async function hasCustomEngineDrift(root, name, componentDir, config, ftlDir) {
+    const status = await checkRegistrationConsistency(root, name, config, ftlDir);
+    if (!status.targetExists || !status.filesInSync) {
+        return true;
+    }
+    if (status.missingTargetFiles.length > 0 || status.driftedFiles.length > 0) {
+        return true;
+    }
+    if (!config.register) {
+        return false;
+    }
+    // Registration drift: only check jar.mn entries for the file types that
+    // actually exist in source. jarMn{Mjs,Css} are substring checks, so a
+    // component with only .mjs (no .css) should not be flagged when jarMnCss
+    // is false — that is the expected post-apply state, not drift.
+    const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
+    let hasMjs = false;
+    let hasCss = false;
+    for (const entry of entries) {
+        if (!isRegularFile(entry))
+            continue;
+        if (entry.name.endsWith('.mjs'))
+            hasMjs = true;
+        else if (entry.name.endsWith('.css'))
+            hasCss = true;
+    }
+    if (!status.customElementsPresent || !status.customElementsCorrectBlock) {
+        return true;
+    }
+    if (hasMjs && !status.jarMnMjs) {
+        return true;
+    }
+    if (hasCss && !status.jarMnCss) {
+        return true;
+    }
+    return false;
+}
+async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir) {
     const actions = [];
+    const stepErrors = [];
     for (const entry of entries) {
-        if (!entry.isFile())
+        if (!isRegularFile(entry))
             continue;
         if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
             continue;
@@ -78,12 +309,22 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
                 component: name,
                 action: 'copy-ftl',
                 source: ftlSrc,
-                target: join(engineDir, FTL_DIR, ftlFile),
-                description: `Copy ${ftlFile} to ${FTL_DIR}`,
+                target: join(engineDir, ftlDir, ftlFile),
+                description: `Copy ${ftlFile} to ${ftlDir}`,
             });
         }
     }
     if (config.register) {
+        try {
+            const modulePath = `chrome://global/content/elements/${name}.mjs`;
+            await validateCustomElementRegistration(engineDir, name, modulePath);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'customElements.js registration',
+                error: toError(error).message,
+            });
+        }
         actions.push({
             component: name,
             action: 'register-ce',
@@ -91,27 +332,40 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
         });
     }
     const copiedFileNames = entries
-        .filter((entry) => entry.isFile() && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
+        .filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
         .map((entry) => entry.name);
     if (copiedFileNames.length > 0) {
+        try {
+            await validateJarMnEntries(engineDir, name, copiedFileNames);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'jar.mn registration',
+                error: toError(error).message,
+            });
+        }
         actions.push({
             component: name,
             action: 'register-jar',
             description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
         });
     }
-    return actions;
+    return { actions, stepErrors };
 }
 /** Applies a custom component into the engine tree and captures registration step errors. */
-export async function applyCustomComponent(engineDir, name, componentDir, config, dryRun = false, rollbackJournal) {
+export async function applyCustomComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal) {
     if (!/^[a-z][a-z0-9-]*$/.test(name)) {
         throw new FurnaceError(`Invalid component name "${name}": must match /^[a-z][a-z0-9-]*$/`);
     }
     const targetDir = join(engineDir, config.targetPath);
     const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
+    const customSymlinks = entries.filter((e) => typeof e.isSymbolicLink === 'function' && e.isSymbolicLink());
+    if (customSymlinks.length > 0) {
+        verbose(`Skipped ${customSymlinks.length} symlink(s) in "${name}": ${customSymlinks.map((e) => e.name).join(', ')}`);
+    }
     if (dryRun) {
-        const actions = await buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries);
-        return { affectedPaths: [], stepErrors: [], actions };
+        const { actions, stepErrors } = await buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir);
+        return { affectedPaths: [], stepErrors, actions };
     }
     if (rollbackJournal && !(await pathExists(targetDir))) {
         recordCreatedDir(rollbackJournal, targetDir);
@@ -120,25 +374,30 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     const affectedPaths = [];
     const stepErrors = [];
     const copiedFileNames = [];
-    for (const entry of entries) {
-        if (!entry.isFile())
-            continue;
-        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
-            continue;
-        const src = join(componentDir, entry.name);
+    // Collect copy candidates, then snapshot + copy in parallel. Snapshots
+    // must complete before any copy (they read the original content), but
+    // independent files can be processed concurrently.
+    const filesToCopy = entries.filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')));
+    // Snapshot phase (serial — journal is not concurrent-safe for the same path)
+    for (const entry of filesToCopy) {
         const dest = join(targetDir, entry.name);
         if (rollbackJournal) {
             await snapshotFile(rollbackJournal, dest);
         }
+    }
+    // Copy phase (parallel — independent file writes to different paths)
+    await Promise.all(filesToCopy.map(async (entry) => {
+        const src = join(componentDir, entry.name);
+        const dest = join(targetDir, entry.name);
         await copyFile(src, dest);
         affectedPaths.push(relative(engineDir, dest));
         copiedFileNames.push(entry.name);
-    }
+    }));
     if (config.localized) {
         const ftlFile = `${name}.ftl`;
         const ftlSrc = join(componentDir, ftlFile);
         if (await pathExists(ftlSrc)) {
-            const ftlDest = join(engineDir, FTL_DIR, ftlFile);
+            const ftlDest = join(engineDir, ftlDir, ftlFile);
             if (rollbackJournal) {
                 await snapshotFile(rollbackJournal, ftlDest);
             }
@@ -180,21 +439,25 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     return { affectedPaths, stepErrors };
 }
 /** Applies an override component by copying its matching files onto the engine tree. */
-export async function applyOverrideComponent(engineDir, name, componentDir, config, dryRun = false, rollbackJournal) {
+export async function applyOverrideComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal) {
     const targetDir = join(engineDir, config.basePath);
     if (!(await pathExists(targetDir))) {
         throw new FurnaceError(`Override target path not found in engine: ${config.basePath}`, name);
     }
     const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
+    const overrideSymlinks = entries.filter((e) => typeof e.isSymbolicLink === 'function' && e.isSymbolicLink());
+    if (overrideSymlinks.length > 0) {
+        verbose(`Skipped ${overrideSymlinks.length} symlink(s) in "${name}": ${overrideSymlinks.map((e) => e.name).join(', ')}`);
+    }
     if (dryRun) {
         const actions = entries
-            .filter((entry) => entry.isFile() && isOverrideCopyCandidate(entry.name, config.type))
+            .filter((entry) => isRegularFile(entry) && isOverrideCopyCandidate(entry.name, config.type))
             .map((entry) => ({
             component: name,
             action: 'copy',
             source: join(componentDir, entry.name),
-            target: join(targetDir, entry.name),
-            description: `Override ${entry.name} in ${config.basePath}`,
+            target: getOverrideEngineTargetPath(engineDir, config, entry.name, ftlDir),
+            description: `Override ${entry.name} in ${entry.name.endsWith('.ftl') ? ftlDir : config.basePath}`,
         }));
         if (actions.length === 0) {
             throw new FurnaceError(`No matching files found in override directory for "${name}"`, name);
@@ -202,43 +465,25 @@ export async function applyOverrideComponent(engineDir, name, componentDir, conf
         return { affectedPaths: [], actions };
     }
     const affectedPaths = [];
-    for (const entry of entries) {
-        if (!entry.isFile() || !isOverrideCopyCandidate(entry.name, config.type)) {
-            continue;
-        }
-        const src = join(componentDir, entry.name);
-        const dest = join(targetDir, entry.name);
+    const candidateEntries = entries.filter((entry) => isRegularFile(entry) && isOverrideCopyCandidate(entry.name, config.type));
+    // Snapshot phase (serial)
+    for (const entry of candidateEntries) {
+        const dest = getOverrideEngineTargetPath(engineDir, config, entry.name, ftlDir);
         if (rollbackJournal) {
             await snapshotFile(rollbackJournal, dest);
         }
+    }
+    // Copy phase (parallel)
+    await Promise.all(candidateEntries.map(async (entry) => {
+        const src = join(componentDir, entry.name);
+        const dest = getOverrideEngineTargetPath(engineDir, config, entry.name, ftlDir);
         await copyFile(src, dest);
         affectedPaths.push(relative(engineDir, dest));
-    }
+    }));
     if (affectedPaths.length === 0) {
         throw new FurnaceError(`No matching files found in override directory for "${name}"`, name);
     }
     return { affectedPaths };
 }
-/** Extracts per-component checksums from the flattened state-file checksum map. */
-export function extractComponentChecksums(allChecksums, type, name) {
-    if (!allChecksums)
-        return {};
-    const prefix = `${type}/${name}/`;
-    const result = {};
-    for (const [key, value] of Object.entries(allChecksums)) {
-        if (key.startsWith(prefix)) {
-            result[key.slice(prefix.length)] = value;
-        }
-    }
-    return result;
-}
-/** Prefixes component checksums so they can be stored in the flattened state format. */
-export function prefixChecksums(checksums, type, name) {
-    const prefix = `${type}/${name}/`;
-    const result = {};
-    for (const [key, value] of Object.entries(checksums)) {
-        result[`${prefix}${key}`] = value;
-    }
-    return result;
-}
+export { extractComponentChecksums, prefixChecksums } from './furnace-checksum-utils.js';
 //# sourceMappingURL=furnace-apply-helpers.js.map

package/dist/src/core/furnace-apply-output.d.ts

@@ -0,0 +1,16 @@
+import type { ApplyResult, DryRunAction } from '../types/furnace.js';
+type ApplyResultWithActions = ApplyResult & {
+    actions?: DryRunAction[];
+};
+/**
+ * Prints a standard summary of an apply result for both normal and dry-run flows.
+ *
+ * Dry-run output lists the planned actions collected by the apply helpers.
+ * Normal output lists applied files, skipped components, and any step errors.
+ * Errors are always printed after the main body.
+ *
+ * @param result - Result returned by applyAllComponents
+ * @param isDryRun - Whether apply was invoked with dryRun=true
+ */
+export declare function logApplyResult(result: ApplyResultWithActions, isDryRun: boolean): void;
+export {};

package/dist/src/core/furnace-apply-output.js

@@ -0,0 +1,57 @@
+import { error, info, success, warn } from '../utils/logger.js';
+/**
+ * Prints a standard summary of an apply result for both normal and dry-run flows.
+ *
+ * Dry-run output lists the planned actions collected by the apply helpers.
+ * Normal output lists applied files, skipped components, and any step errors.
+ * Errors are always printed after the main body.
+ *
+ * @param result - Result returned by applyAllComponents
+ * @param isDryRun - Whether apply was invoked with dryRun=true
+ */
+export function logApplyResult(result, isDryRun) {
+    if (isDryRun && result.actions && result.actions.length > 0) {
+        info('Planned actions:');
+        for (const action of result.actions) {
+            info(`  [${action.action}] ${action.component}: ${action.description}`);
+        }
+    }
+    else if (isDryRun) {
+        info('No actions would be performed.');
+    }
+    else if (result.rolledBack) {
+        // When the rollback journal was restored, entries in `applied` reflect
+        // what was attempted but no longer exists in the engine. Print them as
+        // "attempted" rather than "success" to avoid misleading the operator.
+        if (result.applied.length > 0) {
+            warn('The following components were applied but have been rolled back due to errors:');
+            for (const applied of result.applied) {
+                warn(`  ${applied.name} (${applied.type}) — rolled back`);
+                if (applied.stepErrors && applied.stepErrors.length > 0) {
+                    for (const stepErr of applied.stepErrors) {
+                        warn(`    ${applied.name}: [${stepErr.step}] ${stepErr.error}`);
+                    }
+                }
+            }
+        }
+    }
+    else {
+        for (const applied of result.applied) {
+            success(`${applied.name} (${applied.type}) → ${applied.filesAffected.length} files`);
+        }
+        for (const skipped of result.skipped) {
+            info(`${skipped.name} — ${skipped.reason}`);
+        }
+        for (const applied of result.applied) {
+            if (applied.stepErrors && applied.stepErrors.length > 0) {
+                for (const stepErr of applied.stepErrors) {
+                    warn(`${applied.name}: [${stepErr.step}] ${stepErr.error}`);
+                }
+            }
+        }
+    }
+    for (const err of result.errors) {
+        error(`${err.name} — ${err.error}`);
+    }
+}
+//# sourceMappingURL=furnace-apply-output.js.map

package/dist/src/core/furnace-apply.d.ts

@@ -1,5 +1,7 @@
 import type { ApplyResult, DryRunAction } from '../types/furnace.js';
-export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, prefixChecksums, } from './furnace-apply-helpers.js';
+import { type FurnaceOperationContext } from './furnace-operation.js';
+import { type RollbackJournal } from './furnace-rollback.js';
+export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
 /**
  * Applies all override and custom components to the engine source tree.
  *
@@ -7,10 +9,26 @@ export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums
  * fails, FireForge restores only the engine files touched during this apply
  * attempt and leaves the state file unchanged.
  *
+ * When `options.persistState` is false, the furnace state file is left alone
+ * on success and the rollback journal is returned on the result so the caller
+ * can restore the engine later (used by `furnace preview` to stage workspace
+ * files for Storybook and then roll them back on teardown).
+ *
  * @param root - Root directory of the project
  * @param dryRun - If true, enumerate planned actions without writing
- * @returns Summary of applied, skipped, and errored components (with actions when dry-run)
+ * @param options - Optional behavior flags. `persistState` controls whether
+ *   the furnace state file is updated on success (preview teardown sets this
+ *   to false to keep ownership of the journal). `operationContext` is the
+ *   lifecycle-wrapper hook used by `runFurnaceMutation` so a Ctrl+C mid-apply
+ *   can find the in-flight rollback journal.
+ * @returns Summary of applied, skipped, and errored components (with actions
+ *          when dry-run, and with rollbackJournal when persistState=false)
  */
-export declare function applyAllComponents(root: string, dryRun?: boolean): Promise<ApplyResult & {
+export declare function applyAllComponents(root: string, dryRun?: boolean, options?: {
+    persistState?: boolean;
+    operationContext?: FurnaceOperationContext;
+    componentName?: string;
+}): Promise<ApplyResult & {
     actions?: DryRunAction[];
+    rollbackJournal?: RollbackJournal;
 }>;