@hominis/fireforge 0.10.1 → 0.11.0

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

@@ -6,7 +6,10 @@ import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { isArray, isBoolean, isObject, isString } from '../utils/validation.js';
 import { FIREFORGE_DIR } from './config.js';
+import { resolveFtlDir } from './furnace-constants.js';
+import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { quarantineStateFile, withStateFileLock } from './state-file.js';
+export { detectComposesCycles };
 /** Name of the furnace configuration file */
 export const FURNACE_CONFIG_FILENAME = 'furnace.json';
 /** Name of the furnace state file */
@@ -81,6 +84,7 @@ function parseOverrideConfig(data, name) {
         description: data['description'],
         basePath: data['basePath'],
         baseVersion: data['baseVersion'],
+        ...(isString(data['baseCommit']) ? { baseCommit: data['baseCommit'] } : {}),
     };
 }
 /**
@@ -117,6 +121,37 @@ function parseCustomConfig(data, name) {
             : {}),
     };
 }
+/** The current (and only) config schema version. */
+const CURRENT_CONFIG_VERSION = 1;
+/**
+ * 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 function migrateFurnaceConfig(data) {
+    const version = data['version'];
+    if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+        throw new FurnaceError(`Furnace config: "version" must be a positive integer (got ${JSON.stringify(version)}). ` +
+            `Current schema version is ${CURRENT_CONFIG_VERSION}.`);
+    }
+    if (version > CURRENT_CONFIG_VERSION) {
+        throw new FurnaceError(`Furnace config: version ${version} is newer than what this version of FireForge supports (${CURRENT_CONFIG_VERSION}). ` +
+            'Upgrade FireForge to read this config.');
+    }
+    // Today only version 1 exists, so no migration is needed. When future
+    // versions are added, migration steps will be chained here.
+    return data;
+}
 /**
  * Validates a raw config object and returns a typed FurnaceConfig.
  * @param data - Raw data to validate
@@ -127,27 +162,39 @@ export function validateFurnaceConfig(data) {
     if (!isObject(data)) {
         throw new FurnaceError('Furnace config must be an object');
     }
-    if (data['version'] !== 1) {
-        throw new FurnaceError('Furnace config: "version" must be 1');
+    // Run migration before validation so older configs are transparently upgraded.
+    const migrated = migrateFurnaceConfig(data);
+    if (migrated['version'] !== CURRENT_CONFIG_VERSION) {
+        throw new FurnaceError(`Furnace config: "version" must be ${CURRENT_CONFIG_VERSION} after migration`);
     }
-    if (!isString(data['componentPrefix'])) {
+    if (!isString(migrated['componentPrefix'])) {
         throw new FurnaceError('Furnace config: "componentPrefix" must be a string');
     }
     // Validate optional tokenPrefix
-    if (data['tokenPrefix'] !== undefined && !isString(data['tokenPrefix'])) {
+    if (migrated['tokenPrefix'] !== undefined && !isString(migrated['tokenPrefix'])) {
         throw new FurnaceError('Furnace config: "tokenPrefix" must be a string if provided');
     }
     // Validate optional tokenAllowlist
-    if (data['tokenAllowlist'] !== undefined) {
-        parseStringArray(data['tokenAllowlist'], 'tokenAllowlist');
+    if (migrated['tokenAllowlist'] !== undefined) {
+        parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
+    }
+    const stock = parseStringArray(migrated['stock'], 'stock');
+    const stockSet = new Set();
+    for (const name of stock) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            throw new FurnaceError(`Furnace config: stock entry "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
+        }
+        if (stockSet.has(name)) {
+            throw new FurnaceError(`Furnace config: duplicate stock entry "${name}"`);
+        }
+        stockSet.add(name);
     }
-    const stock = parseStringArray(data['stock'], 'stock');
     // Validate overrides
-    if (!isObject(data['overrides'])) {
+    if (!isObject(migrated['overrides'])) {
         throw new FurnaceError('Furnace config: "overrides" must be an object');
     }
     const overrides = {};
-    for (const [name, value] of Object.entries(data['overrides'])) {
+    for (const [name, value] of Object.entries(migrated['overrides'])) {
         if (!/^[a-z][a-z0-9-]*$/.test(name)) {
             throw new FurnaceError(`Furnace config: override name "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
         }
@@ -157,11 +204,11 @@ export function validateFurnaceConfig(data) {
         overrides[name] = parseOverrideConfig(value, name);
     }
     // Validate custom
-    if (!isObject(data['custom'])) {
+    if (!isObject(migrated['custom'])) {
         throw new FurnaceError('Furnace config: "custom" must be an object');
     }
     const custom = {};
-    for (const [name, value] of Object.entries(data['custom'])) {
+    for (const [name, value] of Object.entries(migrated['custom'])) {
         if (!/^[a-z][a-z0-9-]*$/.test(name)) {
             throw new FurnaceError(`Furnace config: custom name "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
         }
@@ -170,18 +217,42 @@ export function validateFurnaceConfig(data) {
         }
         custom[name] = parseCustomConfig(value, name);
     }
+    // Detect circular composes references among custom components.
+    detectComposesCycles(custom);
+    // Validate that every composes reference points to a known component.
+    validateComposesReferences(stock, overrides, custom);
     const config = {
-        version: 1,
-        componentPrefix: data['componentPrefix'],
+        version: CURRENT_CONFIG_VERSION,
+        componentPrefix: migrated['componentPrefix'],
         stock,
         overrides,
         custom,
     };
-    if (data['tokenPrefix'] !== undefined) {
-        config.tokenPrefix = data['tokenPrefix'];
+    if (migrated['tokenPrefix'] !== undefined) {
+        config.tokenPrefix = migrated['tokenPrefix'];
     }
-    if (data['tokenAllowlist'] !== undefined) {
-        config.tokenAllowlist = parseStringArray(data['tokenAllowlist'], 'tokenAllowlist');
+    if (migrated['tokenAllowlist'] !== undefined) {
+        config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
+    }
+    // Validate optional ftlBasePath
+    if (migrated['ftlBasePath'] !== undefined) {
+        if (!isString(migrated['ftlBasePath'])) {
+            throw new FurnaceError('Furnace config: "ftlBasePath" must be a string if provided');
+        }
+        if (migrated['ftlBasePath'].includes('..')) {
+            throw new FurnaceError('Furnace config: "ftlBasePath" must not contain ".." (path traversal)');
+        }
+        config.ftlBasePath = migrated['ftlBasePath'];
+    }
+    // Validate optional scanPaths
+    if (migrated['scanPaths'] !== undefined) {
+        const paths = parseStringArray(migrated['scanPaths'], 'scanPaths');
+        for (const p of paths) {
+            if (p.includes('..')) {
+                throw new FurnaceError('Furnace config: "scanPaths" entries must not contain ".." (path traversal)');
+            }
+        }
+        config.scanPaths = paths;
     }
     return config;
 }
@@ -197,6 +268,39 @@ export function validateFurnaceState(data) {
     }
     return result.state;
 }
+const PENDING_REPAIR_OPERATIONS = [
+    'preview-teardown',
+    'apply-rollback',
+    'deploy-rollback',
+    'remove-rollback',
+    'create-rollback',
+    'override-rollback',
+    'scan-rollback',
+    'rename-rollback',
+    'refresh-rollback',
+];
+function parsePendingRepair(data) {
+    if (!isObject(data)) {
+        return { error: 'field "pendingRepair" must be an object' };
+    }
+    if (!isString(data['operation']) ||
+        !PENDING_REPAIR_OPERATIONS.includes(data['operation'])) {
+        return {
+            error: `pendingRepair.operation must be one of: ${PENDING_REPAIR_OPERATIONS.join(', ')}`,
+        };
+    }
+    if (!isString(data['timestamp'])) {
+        return { error: 'pendingRepair.timestamp must be a string' };
+    }
+    if (!isString(data['reason'])) {
+        return { error: 'pendingRepair.reason must be a string' };
+    }
+    return {
+        operation: data['operation'],
+        timestamp: data['timestamp'],
+        reason: data['reason'],
+    };
+}
 function sanitizeFurnaceState(data) {
     if (!isObject(data)) {
         return {
@@ -238,6 +342,33 @@ function sanitizeFurnaceState(data) {
             }
         }
     }
+    if (data['engineChecksums'] !== undefined) {
+        if (!isObject(data['engineChecksums'])) {
+            issues.push('field "engineChecksums" must be an object of string checksum values');
+        }
+        else {
+            const engineChecksums = {};
+            for (const [filePath, checksum] of Object.entries(data['engineChecksums'])) {
+                if (isString(checksum)) {
+                    engineChecksums[filePath] = checksum;
+                }
+            }
+            if (Object.keys(engineChecksums).length > 0) {
+                state.engineChecksums = engineChecksums;
+                recoveredFields.push('engineChecksums');
+            }
+        }
+    }
+    if (data['pendingRepair'] !== undefined) {
+        const parsed = parsePendingRepair(data['pendingRepair']);
+        if ('error' in parsed) {
+            issues.push(parsed.error);
+        }
+        else {
+            state.pendingRepair = parsed;
+            recoveredFields.push('pendingRepair');
+        }
+    }
     return { state, issues, recoveredFields };
 }
 async function recoverInvalidFurnaceState(statePath, result, alreadyLocked = false) {
@@ -369,4 +500,36 @@ export async function updateFurnaceState(root, updates) {
         await writeJson(paths.furnaceState, validateFurnaceState(nextState));
     });
 }
+/**
+ * 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 async function collectFurnaceManagedPrefixes(root) {
+    if (!(await furnaceConfigExists(root)))
+        return new Set();
+    const config = await loadFurnaceConfig(root);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
+    const prefixes = new Set();
+    for (const [, overrideCfg] of Object.entries(config.overrides)) {
+        const base = overrideCfg.basePath.endsWith('/')
+            ? overrideCfg.basePath
+            : overrideCfg.basePath + '/';
+        prefixes.add(base);
+    }
+    for (const [, customCfg] of Object.entries(config.custom)) {
+        const target = customCfg.targetPath.endsWith('/')
+            ? customCfg.targetPath
+            : customCfg.targetPath + '/';
+        prefixes.add(target);
+        if (customCfg.localized) {
+            prefixes.add(ftlDir.endsWith('/') ? ftlDir : ftlDir + '/');
+        }
+    }
+    return prefixes;
+}
 //# sourceMappingURL=furnace-config.js.map

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

@@ -2,3 +2,25 @@
 export declare const CUSTOM_ELEMENTS_JS = "toolkit/content/customElements.js";
 /** Path to jar.mn within the engine source tree (toolkit global) */
 export declare const JAR_MN = "toolkit/content/jar.mn";
+/** Default Fluent localization directory for toolkit global components, relative to engine root */
+export declare const FTL_DIR = "toolkit/locales/en-US/toolkit/global";
+/** File extensions that constitute a Furnace component's source files. */
+export declare const COMPONENT_FILE_EXTENSIONS: readonly [".mjs", ".css", ".ftl"];
+/** Returns true when `fileName` has one of the standard component file extensions. */
+export declare function isComponentSourceFile(fileName: string): boolean;
+/**
+ * Resolves the FTL base path, preferring the user-configured value from
+ * `furnace.json` over the built-in default.
+ */
+export declare function resolveFtlDir(configuredPath?: string): string;
+/**
+ * Converts a kebab-case tag name to PascalCase class name.
+ * e.g. "moz-sidebar-panel" → "MozSidebarPanel"
+ */
+export declare function tagNameToClassName(tagName: string): string;
+/**
+ * Strips a known component prefix from a tag name to produce a concise
+ * display name. Falls back to the full tag name when the prefix doesn't
+ * match, so callers never receive an empty string.
+ */
+export declare function stripComponentPrefix(tagName: string, componentPrefix: string): string;

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

@@ -3,4 +3,40 @@
 export const CUSTOM_ELEMENTS_JS = 'toolkit/content/customElements.js';
 /** Path to jar.mn within the engine source tree (toolkit global) */
 export const JAR_MN = 'toolkit/content/jar.mn';
+/** Default Fluent localization directory for toolkit global components, relative to engine root */
+export const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
+/** File extensions that constitute a Furnace component's source files. */
+export const COMPONENT_FILE_EXTENSIONS = ['.mjs', '.css', '.ftl'];
+/** Returns true when `fileName` has one of the standard component file extensions. */
+export function isComponentSourceFile(fileName) {
+    return COMPONENT_FILE_EXTENSIONS.some((ext) => fileName.endsWith(ext));
+}
+/**
+ * Resolves the FTL base path, preferring the user-configured value from
+ * `furnace.json` over the built-in default.
+ */
+export function resolveFtlDir(configuredPath) {
+    return configuredPath ?? FTL_DIR;
+}
+/**
+ * Converts a kebab-case tag name to PascalCase class name.
+ * e.g. "moz-sidebar-panel" → "MozSidebarPanel"
+ */
+export function tagNameToClassName(tagName) {
+    return tagName
+        .split('-')
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+}
+/**
+ * Strips a known component prefix from a tag name to produce a concise
+ * display name. Falls back to the full tag name when the prefix doesn't
+ * match, so callers never receive an empty string.
+ */
+export function stripComponentPrefix(tagName, componentPrefix) {
+    if (componentPrefix && tagName.startsWith(componentPrefix)) {
+        return tagName.slice(componentPrefix.length);
+    }
+    return tagName;
+}
 //# sourceMappingURL=furnace-constants.js.map

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

@@ -0,0 +1,11 @@
+import type { CustomComponentConfig, FurnaceConfig } from '../types/furnace.js';
+/** Throws a {@link FurnaceError} if the composes graph among custom components contains a cycle. */
+export declare function detectComposesCycles(custom: FurnaceConfig['custom']): void;
+/** Validates that every `composes` reference in custom components points to a known component. */
+export declare function validateComposesReferences(stock: string[], overrides: FurnaceConfig['overrides'], custom: FurnaceConfig['custom']): void;
+/**
+ * Returns custom component names in topological order so that components
+ * depended upon via `composes` are applied before those that compose them.
+ * Falls back to insertion order when there are no composes edges.
+ */
+export declare function topologicalSortCustom(custom: Record<string, CustomComponentConfig>): string[];

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

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { FurnaceError } from '../errors/furnace.js';
+/** Throws a {@link FurnaceError} if the composes graph among custom components contains a cycle. */
+export function detectComposesCycles(custom) {
+    const visited = new Set();
+    const stack = new Set();
+    function visit(name, path) {
+        if (stack.has(name)) {
+            const cycle = [...path.slice(path.indexOf(name)), name];
+            throw new FurnaceError(`Furnace config: circular composes dependency detected: ${cycle.join(' → ')}`);
+        }
+        if (visited.has(name))
+            return;
+        stack.add(name);
+        path.push(name);
+        const deps = custom[name]?.composes;
+        if (deps) {
+            for (const dep of deps) {
+                if (dep in custom) {
+                    visit(dep, path);
+                }
+            }
+        }
+        path.pop();
+        stack.delete(name);
+        visited.add(name);
+    }
+    for (const name of Object.keys(custom)) {
+        visit(name, []);
+    }
+}
+/** Validates that every `composes` reference in custom components points to a known component. */
+export function validateComposesReferences(stock, overrides, custom) {
+    const known = new Set([...stock, ...Object.keys(overrides), ...Object.keys(custom)]);
+    for (const [name, config] of Object.entries(custom)) {
+        if (!config.composes)
+            continue;
+        for (const ref of config.composes) {
+            if (!known.has(ref)) {
+                throw new FurnaceError(`Furnace config: custom "${name}" composes unknown component "${ref}". ` +
+                    'The referenced component must be registered as stock, override, or custom.');
+            }
+        }
+    }
+}
+/**
+ * Returns custom component names in topological order so that components
+ * depended upon via `composes` are applied before those that compose them.
+ * Falls back to insertion order when there are no composes edges.
+ */
+export function topologicalSortCustom(custom) {
+    const names = Object.keys(custom);
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const name of names) {
+        inDegree.set(name, 0);
+        dependents.set(name, []);
+    }
+    for (const [name, config] of Object.entries(custom)) {
+        if (!config.composes)
+            continue;
+        for (const dep of config.composes) {
+            if (dep in custom) {
+                inDegree.set(name, (inDegree.get(name) ?? 0) + 1);
+                dependents.get(dep)?.push(name);
+            }
+        }
+    }
+    const queue = names.filter((n) => (inDegree.get(n) ?? 0) === 0);
+    const sorted = [];
+    while (queue.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guarded by while condition
+        const current = queue.shift();
+        sorted.push(current);
+        for (const dep of dependents.get(current) ?? []) {
+            const newDegree = (inDegree.get(dep) ?? 1) - 1;
+            inDegree.set(dep, newDegree);
+            if (newDegree === 0) {
+                queue.push(dep);
+            }
+        }
+    }
+    // If a cycle was somehow missed by config validation, fall back to insertion order
+    // for any nodes not reached.
+    if (sorted.length < names.length) {
+        for (const name of names) {
+            if (!sorted.includes(name)) {
+                sorted.push(name);
+            }
+        }
+    }
+    return sorted;
+}
+//# sourceMappingURL=furnace-graph-utils.js.map

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

@@ -0,0 +1,108 @@
+import type { FurnacePendingRepairOperation } from '../types/furnace.js';
+import { type RollbackJournal } from './furnace-rollback.js';
+/**
+ * The signal names the lifecycle wrapper knows how to react to. Spelled out
+ * as a literal union (rather than `NodeJS.Signals`) so the public type
+ * surface does not depend on the NodeJS global namespace — consumers of
+ * `@hominis/fireforge` may compile against tsconfigs that omit `@types/node`.
+ */
+export type FurnaceShutdownSignal = 'SIGINT' | 'SIGTERM';
+/**
+ * Context handed to a furnace mutation body so it can register the in-flight
+ * rollback journal with the lifecycle wrapper. The wrapper uses the registered
+ * journal to perform rollback when the process receives SIGINT/SIGTERM mid-run.
+ */
+export interface FurnaceOperationContext {
+    /**
+     * Registers the rollback journal for the current operation. Must be called
+     * once the body has constructed its journal so the signal handler can find
+     * it. Calling more than once replaces the prior reference (this is fine for
+     * commands that build the journal lazily).
+     */
+    registerJournal(journal: RollbackJournal): void;
+    /**
+     * Registers an extra cleanup callback to run during signal-driven teardown
+     * in addition to the journal restore. Used by `furnace preview` to make
+     * sure `cleanStories` runs even when the user hits Ctrl+C mid-run. The
+     * callback should be best-effort and idempotent: cleanup errors are
+     * collected, not re-thrown.
+     */
+    registerCleanup(cleanup: () => Promise<void>): void;
+}
+/** Options for `runFurnaceMutation`. */
+export interface RunFurnaceMutationOptions {
+    /**
+     * If true, skip lock acquisition and signal-handler installation entirely.
+     * Used by dry-run paths where no engine mutation occurs.
+     *
+     * Note: a dry-run can overlap with a real mutation because it does not
+     * acquire the lock. This is safe because dry-runs only read; however, a
+     * dry-run that starts before a real mutation and finishes after it may
+     * observe partially-written engine state. Accept this trade-off so that
+     * concurrent dry-runs never block each other or a real apply.
+     */
+    dryRun?: boolean;
+    /**
+     * Override the default 30s lock timeout. The watch-mode caller may want a
+     * shorter window so an interactive rebuild fails fast instead of stalling.
+     */
+    lockTimeoutMs?: number;
+    /**
+     * If true, skip the pendingRepair pre-flight check. Used by `doctor
+     * --repair-furnace` which must be able to mutate the engine even when a
+     * pendingRepair marker is set.
+     */
+    skipPendingRepairCheck?: boolean;
+}
+/**
+ * Returns true while a signal-driven rollback is in progress. The bin entry
+ * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
+ * trigger a second rollback that races the first. Exposed for the bin shim
+ * (and the test suite); production callers should not need it.
+ */
+export declare function isSignalRollbackInFlight(): boolean;
+/**
+ * Rolls back every in-flight furnace operation and writes a pendingRepair
+ * marker for each. Each cleanup callback and journal restore is bounded by a
+ * timeout so a stuck I/O operation cannot hang the process indefinitely.
+ */
+export declare function rollbackActiveOperationsForSignal(signal: FurnaceShutdownSignal): Promise<void>;
+/**
+ * Resolves the path of the lock directory used to serialize furnace mutations
+ * for a given project root. Exposed for tests; production callers should not
+ * touch this directly.
+ */
+export declare function getFurnaceLockPath(root: string): string;
+/**
+ * Runs a furnace-mutating body under the apply-wide lock and registers it
+ * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
+ * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
+ * working copy; the CLI entrypoint's global signal handlers consult this
+ * registry and invoke rollback (writing a `pendingRepair` marker when needed)
+ * if the user hits Ctrl+C mid-run.
+ *
+ * Dry-run callers should pass `options.dryRun = true` so the wrapper skips
+ * the lock entirely (concurrent dry-runs are safe and shouldn't block each
+ * other).
+ *
+ * The body receives a {@link FurnaceOperationContext}; it must call
+ * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
+ * Bodies that don't manage a journal directly (e.g. apply, which delegates to
+ * `applyAllComponents`) can pass an internal callback through.
+ */
+export declare function runFurnaceMutation<T>(root: string, kind: FurnacePendingRepairOperation, body: (ctx: FurnaceOperationContext) => Promise<T>, options?: RunFurnaceMutationOptions): Promise<T>;
+/**
+ * Persists an `apply-rollback` (or other operation-kind) `pendingRepair`
+ * marker on behalf of a caller that detected a rollback failure outside the
+ * signal-handler path (e.g. apply's own catch-around-restore). Exposed so
+ * `furnace-apply.ts` can write the marker without taking on a dependency on
+ * the lifecycle wrapper's internals.
+ */
+export declare function recordFurnaceRollbackFailure(root: string, operation: FurnacePendingRepairOperation, reason: string): Promise<void>;
+/**
+ * Test-only helper: tears down the module-scoped state. Vitest workers may
+ * reuse the module across tests, so the test suite must call this between
+ * cases that exercise the signal pathway. Not exported from the package
+ * entry point.
+ */
+export declare function __resetFurnaceOperationStateForTests(): void;