@hominis/fireforge 0.10.1 → 0.11.0

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

@@ -3,42 +3,85 @@ import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
+import { info } from '../utils/logger.js';
 import { getProjectPaths } from './config.js';
-import { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, prefixChecksums, } from './furnace-apply-helpers.js';
+import { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, diffDeletedFiles, extractComponentChecksums, getOverrideEngineTargetPath, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, undeployCustomFiles, undeployOverrideFiles, } from './furnace-apply-helpers.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, } from './furnace-config.js';
-import { createRollbackJournal, restoreRollbackJournalOrThrow, } from './furnace-rollback.js';
-export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, prefixChecksums, } from './furnace-apply-helpers.js';
+import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from './furnace-constants.js';
+import { topologicalSortCustom } from './furnace-graph-utils.js';
+import { recordFurnaceRollbackFailure } from './furnace-operation.js';
+import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
+import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
+import { runPostApplyConsistencyChecks } from './furnace-validate-registration.js';
+export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
 function addMissingComponentError(result, name, directoryPath) {
     result.errors.push({
         name,
         error: `Component directory not found: ${directoryPath}`,
     });
 }
-async function applyOverrideBatch(config, furnacePaths, state, engineDir, dryRun, result, allActions, newChecksums, rollbackJournal) {
-    for (const [name, overrideConfig] of Object.entries(config.overrides)) {
+function buildOverrideUndeployActions(name, config, engineDir, deletedFiles, ftlDir) {
+    return deletedFiles.map((fileName) => ({
+        component: name,
+        action: 'undeploy-restore',
+        target: getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir),
+        description: `Restore engine/${fileName.endsWith('.ftl') ? `${ftlDir}/${fileName}` : `${config.basePath}/${fileName}`} to Firefox baseline`,
+    }));
+}
+async function applyOverrideBatch(config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName) {
+    const overrideEntries = Object.entries(config.overrides).filter(([name]) => !componentName || name === componentName);
+    const totalOverrides = overrideEntries.length;
+    let overrideIndex = 0;
+    for (const [name, overrideConfig] of overrideEntries) {
+        overrideIndex++;
+        if (!dryRun && totalOverrides > 1) {
+            info(`Applying override ${name} (${overrideIndex}/${totalOverrides})...`);
+        }
         const componentDir = join(furnacePaths.overridesDir, name);
         if (!(await pathExists(componentDir))) {
             addMissingComponentError(result, name, `components/overrides/${name}`);
             continue;
         }
+        const previous = extractComponentChecksums(state.appliedChecksums, 'override', name);
         if (!dryRun) {
-            const previous = extractComponentChecksums(state.appliedChecksums, 'override', name);
             const changed = await hasComponentChanged(componentDir, previous);
             if (!changed) {
-                result.skipped.push({ name, reason: 'No changes since last apply' });
-                Object.assign(newChecksums, prefixChecksums(previous, 'override', name));
-                continue;
+                // Fast path holds only if the engine still reflects what we deployed.
+                // reset/download/manual edits can silently erase engine files; the
+                // checksum record alone cannot detect that.
+                const cachedEngine = extractComponentChecksums(state.engineChecksums, 'override', name);
+                const drifted = await hasOverrideEngineDrift(engineDir, componentDir, overrideConfig, ftlDir, cachedEngine);
+                if (!drifted) {
+                    result.skipped.push({ name, reason: 'No changes since last apply' });
+                    Object.assign(newChecksums, prefixChecksums(previous, 'override', name));
+                    continue;
+                }
             }
         }
         try {
-            const { affectedPaths: filesAffected, actions } = await applyOverrideComponent(engineDir, name, componentDir, overrideConfig, dryRun, rollbackJournal);
+            const filesAffectedTotal = [];
+            // Compute which files (if any) were removed from the workspace since
+            // the last apply. We do this for both dry-run and real runs so the
+            // planned-actions output stays honest.
+            const currentChecksums = await computeComponentChecksums(componentDir);
+            const deletedFiles = diffDeletedFiles(previous, currentChecksums);
+            if (dryRun) {
+                if (deletedFiles.length > 0) {
+                    allActions.push(...buildOverrideUndeployActions(name, overrideConfig, engineDir, deletedFiles, ftlDir));
+                }
+            }
+            else if (deletedFiles.length > 0) {
+                const { restored, removed } = await undeployOverrideFiles(engineDir, overrideConfig, deletedFiles, ftlDir, rollbackJournal);
+                filesAffectedTotal.push(...restored, ...removed);
+            }
+            const { affectedPaths: filesAffected, actions } = await applyOverrideComponent(engineDir, name, componentDir, overrideConfig, ftlDir, dryRun, rollbackJournal);
             if (dryRun && actions) {
                 allActions.push(...actions);
             }
-            result.applied.push({ name, type: 'override', filesAffected });
+            filesAffectedTotal.push(...filesAffected);
+            result.applied.push({ name, type: 'override', filesAffected: filesAffectedTotal });
             if (!dryRun) {
-                const checksums = await computeComponentChecksums(componentDir);
-                Object.assign(newChecksums, prefixChecksums(checksums, 'override', name));
+                Object.assign(newChecksums, prefixChecksums(currentChecksums, 'override', name));
             }
         }
         catch (error) {
@@ -49,38 +92,178 @@ async function applyOverrideBatch(config, furnacePaths, state, engineDir, dryRun
         }
     }
 }
-async function applyCustomBatch(config, furnacePaths, state, engineDir, dryRun, result, allActions, newChecksums, rollbackJournal) {
-    for (const [name, customConfig] of Object.entries(config.custom)) {
+function buildCustomUndeployActions(name, config, engineDir, deletedFiles, ftlDir) {
+    const actions = [];
+    for (const fileName of deletedFiles) {
+        const enginePath = fileName.endsWith('.ftl')
+            ? join(engineDir, ftlDir, fileName)
+            : join(engineDir, config.targetPath, fileName);
+        actions.push({
+            component: name,
+            action: 'undeploy-remove',
+            target: enginePath,
+            description: `Remove orphaned ${fileName} from engine`,
+        });
+    }
+    // jar.mn re-sync planned for any custom-file deletion when registered.
+    if (config.register && deletedFiles.some((f) => f.endsWith('.mjs') || f.endsWith('.css'))) {
+        actions.push({
+            component: name,
+            action: 'unregister-jar',
+            description: `Re-sync ${name} jar.mn entries to drop deleted files`,
+        });
+    }
+    if (config.register && deletedFiles.some((f) => f === `${name}.mjs`)) {
+        actions.push({
+            component: name,
+            action: 'unregister-ce',
+            description: `Deregister ${name} from customElements.js (.mjs deleted)`,
+        });
+    }
+    return actions;
+}
+/**
+ * After undeploying deleted files, the in-engine jar.mn and
+ * customElements.js still carry entries for the removed files. Re-sync them
+ * by removing all of `name`'s jar.mn entries and re-adding only those that
+ * still exist in the workspace; if the .mjs itself was deleted, also drop
+ * the customElements.js registration. Snapshots are taken under the same
+ * journal so the undo path is symmetric with apply.
+ */
+async function reconcileCustomRegistrationAfterUndeploy(engineDir, name, config, deletedFiles, currentChecksums, rollbackJournal, filesAffected) {
+    if (!config.register || deletedFiles.length === 0)
+        return;
+    const deletedRegistrationFiles = deletedFiles.filter((f) => f.endsWith('.mjs') || f.endsWith('.css'));
+    if (deletedRegistrationFiles.length === 0)
+        return;
+    // jar.mn re-sync. addJarMnEntries is idempotent on duplicates but does not
+    // drop stale entries, so we need a remove-then-add cycle. The journal
+    // snapshot before each mutation gives us a clean rollback target.
+    if (rollbackJournal) {
+        await snapshotFile(rollbackJournal, join(engineDir, JAR_MN));
+    }
+    await removeJarMnEntries(engineDir, name);
+    const liveJarFiles = Object.keys(currentChecksums).filter((f) => f.endsWith('.mjs') || f.endsWith('.css'));
+    if (liveJarFiles.length > 0) {
+        // applyCustomComponent has already added live entries; the remove above
+        // dropped them too, so re-add now to leave jar.mn in the correct state.
+        await addJarMnEntries(engineDir, name, liveJarFiles);
+    }
+    filesAffected.push(JAR_MN);
+    // If the .mjs file itself was deleted, the customElements registration
+    // must go too — otherwise we leave a dangling import in the Pattern B
+    // block that fails at runtime.
+    if (deletedFiles.includes(`${name}.mjs`)) {
+        if (rollbackJournal) {
+            await snapshotFile(rollbackJournal, join(engineDir, CUSTOM_ELEMENTS_JS));
+        }
+        await removeCustomElementRegistration(engineDir, name);
+        filesAffected.push(CUSTOM_ELEMENTS_JS);
+    }
+}
+async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName) {
+    const allKnown = new Set([
+        ...config.stock,
+        ...Object.keys(config.overrides),
+        ...Object.keys(config.custom),
+    ]);
+    // Build a set of component names that failed during the override batch so
+    // custom components that compose them can be skipped. This includes both
+    // hard errors and step-error failures.
+    const failedDependencies = new Set();
+    for (const entry of result.errors) {
+        failedDependencies.add(entry.name);
+    }
+    for (const entry of result.applied) {
+        if (entry.stepErrors && entry.stepErrors.length > 0) {
+            failedDependencies.add(entry.name);
+        }
+    }
+    const sortedNames = topologicalSortCustom(config.custom).filter((name) => !componentName || name === componentName);
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- names from Object.keys
+    const customEntries = sortedNames.map((name) => [name, config.custom[name]]);
+    const totalCustom = customEntries.length;
+    let customIndex = 0;
+    for (const [name, customConfig] of customEntries) {
+        customIndex++;
+        if (!dryRun && totalCustom > 1) {
+            info(`Applying custom component ${name} (${customIndex}/${totalCustom})...`);
+        }
+        if (customConfig.composes) {
+            const missing = customConfig.composes.filter((ref) => !allKnown.has(ref));
+            if (missing.length > 0) {
+                result.errors.push({
+                    name,
+                    error: `Composes unknown component(s): ${missing.join(', ')}. Each reference must be registered as stock, override, or custom.`,
+                });
+                failedDependencies.add(name);
+                continue;
+            }
+            // Skip this component if any of its composed dependencies failed.
+            const failedRefs = customConfig.composes.filter((ref) => failedDependencies.has(ref));
+            if (failedRefs.length > 0) {
+                result.errors.push({
+                    name,
+                    error: `Skipped: composed dependency ${failedRefs.join(', ')} failed to apply.`,
+                });
+                failedDependencies.add(name);
+                continue;
+            }
+        }
         const componentDir = join(furnacePaths.customDir, name);
         if (!(await pathExists(componentDir))) {
             addMissingComponentError(result, name, `components/custom/${name}`);
             continue;
         }
+        const previous = extractComponentChecksums(state.appliedChecksums, 'custom', name);
         if (!dryRun) {
-            const previous = extractComponentChecksums(state.appliedChecksums, 'custom', name);
             const changed = await hasComponentChanged(componentDir, previous);
             if (!changed) {
-                result.skipped.push({ name, reason: 'No changes since last apply' });
-                Object.assign(newChecksums, prefixChecksums(previous, 'custom', name));
-                continue;
+                // As with overrides, the checksum record is not sufficient on its
+                // own: a reset/download that cleared the engine must trigger a
+                // re-apply even though the workspace is unchanged.
+                const drifted = await hasCustomEngineDrift(root, name, componentDir, customConfig, ftlDir);
+                if (!drifted) {
+                    result.skipped.push({ name, reason: 'No changes since last apply' });
+                    Object.assign(newChecksums, prefixChecksums(previous, 'custom', name));
+                    continue;
+                }
             }
         }
         try {
-            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, dryRun, rollbackJournal);
+            const filesAffectedTotal = [];
+            // Diff against previous to find files the developer has deleted from
+            // the workspace since last apply. Run for both dry-run and real apply
+            // so plan output and execution stay aligned.
+            const currentChecksums = await computeComponentChecksums(componentDir);
+            const deletedFiles = diffDeletedFiles(previous, currentChecksums);
+            if (dryRun) {
+                if (deletedFiles.length > 0) {
+                    allActions.push(...buildCustomUndeployActions(name, customConfig, engineDir, deletedFiles, ftlDir));
+                }
+            }
+            else if (deletedFiles.length > 0) {
+                const removed = await undeployCustomFiles(engineDir, customConfig, deletedFiles, ftlDir, rollbackJournal);
+                filesAffectedTotal.push(...removed);
+            }
+            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, dryRun, rollbackJournal);
             if (dryRun && actions) {
                 allActions.push(...actions);
             }
+            if (!dryRun && deletedFiles.length > 0 && stepErrors.length === 0) {
+                await reconcileCustomRegistrationAfterUndeploy(engineDir, name, customConfig, deletedFiles, currentChecksums, rollbackJournal, filesAffectedTotal);
+            }
+            filesAffectedTotal.push(...filesAffected);
             result.applied.push({
                 name,
                 type: 'custom',
-                filesAffected,
+                filesAffected: filesAffectedTotal,
                 ...(stepErrors.length > 0 ? { stepErrors } : {}),
             });
             // Only store checksums when the component applied without step errors,
             // so that partially failed components are re-applied on the next run.
             if (!dryRun && stepErrors.length === 0) {
-                const checksums = await computeComponentChecksums(componentDir);
-                Object.assign(newChecksums, prefixChecksums(checksums, 'custom', name));
+                Object.assign(newChecksums, prefixChecksums(currentChecksums, 'custom', name));
             }
         }
         catch (error) {
@@ -98,19 +281,36 @@ async function applyCustomBatch(config, furnacePaths, state, engineDir, dryRun,
  * 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 async function applyAllComponents(root, dryRun = false) {
+export async function applyAllComponents(root, dryRun = false, options) {
+    const persistState = options?.persistState ?? true;
+    const operationContext = options?.operationContext;
     const config = await loadFurnaceConfig(root);
     const state = await loadFurnaceState(root);
     const { engine: engineDir } = getProjectPaths(root);
     const furnacePaths = getFurnacePaths(root);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
     if (!(await pathExists(engineDir))) {
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
     }
     const rollbackJournal = dryRun ? undefined : createRollbackJournal();
+    if (rollbackJournal && operationContext) {
+        operationContext.registerJournal(rollbackJournal);
+    }
     const result = {
         applied: [],
         skipped: [],
@@ -118,26 +318,57 @@ export async function applyAllComponents(root, dryRun = false) {
     };
     const allActions = [];
     const newChecksums = {};
-    await applyOverrideBatch(config, furnacePaths, state, engineDir, dryRun, result, allActions, newChecksums, rollbackJournal);
-    await applyCustomBatch(config, furnacePaths, state, engineDir, dryRun, result, allActions, newChecksums, rollbackJournal);
+    const componentName = options?.componentName;
+    // When a single component is requested, validate it exists before running
+    // the batch functions (which would silently skip an unknown name).
+    if (componentName) {
+        const isKnown = componentName in config.overrides || componentName in config.custom;
+        if (!isKnown) {
+            throw new FurnaceError(`Component "${componentName}" not found in furnace.json. Run "fireforge furnace list" to see registered components.`, componentName);
+        }
+    }
+    await applyOverrideBatch(config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName);
+    await applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName);
     // Check for any partial failures (step errors on applied components).
     const hasStepErrors = result.applied.some((entry) => 'stepErrors' in entry && entry.stepErrors.length > 0);
     // Orphaned components are implicitly cleaned up: newChecksums only
     // contains entries for components that still exist in furnace.json,
     // and it fully replaces state.appliedChecksums below.
+    if (!dryRun && !hasStepErrors && result.errors.length === 0) {
+        await runPostApplyConsistencyChecks(root, config, result, ftlDir);
+    }
     // --- Rollback on failure, persist on success (skip for dry-run) ---
     if (!dryRun) {
         if (result.errors.length > 0 || hasStepErrors) {
             if (rollbackJournal) {
-                await restoreRollbackJournalOrThrow(rollbackJournal, 'Furnace apply failed');
+                try {
+                    await restoreRollbackJournalOrThrow(rollbackJournal, 'Furnace apply failed');
+                    result.rolledBack = true;
+                }
+                catch (rollbackError) {
+                    // Rollback itself failed: the engine is in a partially restored
+                    // state. Persist a pending-repair marker so the next `fireforge
+                    // doctor --repair-furnace` run knows to reconcile.
+                    await recordFurnaceRollbackFailure(root, 'apply-rollback', toError(rollbackError).message);
+                    throw rollbackError;
+                }
             }
         }
-        else {
+        else if (persistState) {
+            // After a successful apply, workspace checksums equal the engine content
+            // (we just copied workspace → engine). Store them as engineChecksums so
+            // drift detection can compare engine files against the cached hash
+            // instead of byte-comparing against workspace sources.
             await updateFurnaceState(root, {
                 lastApply: new Date().toISOString(),
                 appliedChecksums: newChecksums,
+                engineChecksums: { ...newChecksums },
             });
         }
+        else if (rollbackJournal) {
+            // Caller owns the journal and will restore on teardown.
+            result.rollbackJournal = rollbackJournal;
+        }
     }
     if (dryRun) {
         result.actions = allActions;

package/dist/src/core/furnace-checksum-utils.d.ts

@@ -0,0 +1,4 @@
+/** Extracts per-component checksums from the flattened state-file checksum map. */
+export declare function extractComponentChecksums(allChecksums: Record<string, string> | undefined, type: string, name: string): Record<string, string>;
+/** Prefixes component checksums so they can be stored in the flattened state format. */
+export declare function prefixChecksums(checksums: Record<string, string>, type: string, name: string): Record<string, string>;

package/dist/src/core/furnace-checksum-utils.js

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** 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;
+}
+//# sourceMappingURL=furnace-checksum-utils.js.map

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

@@ -1,4 +1,6 @@
 import type { FurnaceConfig, FurnaceState } from '../types/furnace.js';
+import { detectComposesCycles } from './furnace-graph-utils.js';
+export { detectComposesCycles };
 /** Name of the furnace configuration file */
 export declare const FURNACE_CONFIG_FILENAME = "furnace.json";
 /** Name of the furnace state file */
@@ -36,6 +38,22 @@ export declare function getFurnacePaths(root: string): FurnacePaths;
  * @returns True if furnace.json exists
  */
 export declare function furnaceConfigExists(root: string): Promise<boolean>;
+/**
+ * Migrates a furnace config from an older schema version to the current one.
+ * Returns the data unchanged if it is already at the current version.
+ *
+ * When a future version 2 is introduced, add a `case 1:` that transforms
+ * v1 data into v2 shape and falls through to validation. The pattern is:
+ *
+ * ```
+ * case 1:
+ *   data = migrateV1ToV2(data);
+ *   // fallthrough
+ * case 2:
+ *   break;
+ * ```
+ */
+export declare function migrateFurnaceConfig(data: Record<string, unknown>): Record<string, unknown>;
 /**
  * Validates a raw config object and returns a typed FurnaceConfig.
  * @param data - Raw data to validate
@@ -91,4 +109,13 @@ export declare function saveFurnaceState(root: string, state: FurnaceState): Pro
  * @param updates - Fields to update, or a transactional updater function
  */
 export declare function updateFurnaceState(root: string, updates: Partial<FurnaceState> | ((current: FurnaceState) => FurnaceState)): Promise<void>;
-export {};
+/**
+ * Collects engine-relative path prefixes that are managed by the Furnace
+ * component system (overrides, custom components, and their Fluent l10n
+ * files). Used by `status` and `export-all` to classify engine changes
+ * as Furnace-managed rather than unmanaged drift.
+ *
+ * Returns an empty set when no furnace config exists (opt-in subsystem).
+ * Prefixes always end with `/` so callers can use `startsWith()`.
+ */
+export declare function collectFurnaceManagedPrefixes(root: string): Promise<Set<string>>;