@hominis/fireforge 0.9.0

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

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { createHash } from 'node:crypto';
+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 { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
+import { addCustomElementRegistration, addJarMnEntries } 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';
+function isChecksummedComponentFile(name) {
+    return name.endsWith('.mjs') || name.endsWith('.css') || name.endsWith('.ftl');
+}
+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');
+}
+/** 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())
+            continue;
+        if (entry.name === 'override.json')
+            continue;
+        if (!isChecksummedComponentFile(entry.name))
+            continue;
+        const content = await readText(join(componentDir, entry.name));
+        const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+        const hash = createHash('sha256').update(normalized).digest('hex');
+        checksums[entry.name] = hash;
+    }
+    return checksums;
+}
+/** Compares current component file checksums against the previously recorded state. */
+export async function hasComponentChanged(componentDir, previousChecksums) {
+    const current = await computeComponentChecksums(componentDir);
+    const currentKeys = Object.keys(current);
+    const previousKeys = Object.keys(previousChecksums);
+    if (currentKeys.length !== previousKeys.length) {
+        return true;
+    }
+    for (const key of currentKeys) {
+        if (current[key] !== previousChecksums[key]) {
+            return true;
+        }
+    }
+    return false;
+}
+async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries) {
+    const actions = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
+            continue;
+        actions.push({
+            component: name,
+            action: 'copy',
+            source: join(componentDir, entry.name),
+            target: join(targetDir, entry.name),
+            description: `Copy ${entry.name} to ${config.targetPath}`,
+        });
+    }
+    if (config.localized) {
+        const ftlFile = `${name}.ftl`;
+        const ftlSrc = join(componentDir, ftlFile);
+        if (await pathExists(ftlSrc)) {
+            actions.push({
+                component: name,
+                action: 'copy-ftl',
+                source: ftlSrc,
+                target: join(engineDir, FTL_DIR, ftlFile),
+                description: `Copy ${ftlFile} to ${FTL_DIR}`,
+            });
+        }
+    }
+    if (config.register) {
+        actions.push({
+            component: name,
+            action: 'register-ce',
+            description: `Register ${name} in customElements.js (DOMContentLoaded block)`,
+        });
+    }
+    const copiedFileNames = entries
+        .filter((entry) => entry.isFile() && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
+        .map((entry) => entry.name);
+    if (copiedFileNames.length > 0) {
+        actions.push({
+            component: name,
+            action: 'register-jar',
+            description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
+        });
+    }
+    return actions;
+}
+/** Applies a custom component into the engine tree and captures registration step errors. */
+export async function applyCustomComponent(engineDir, name, componentDir, config, 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' });
+    if (dryRun) {
+        const actions = await buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries);
+        return { affectedPaths: [], stepErrors: [], actions };
+    }
+    if (rollbackJournal && !(await pathExists(targetDir))) {
+        recordCreatedDir(rollbackJournal, targetDir);
+    }
+    await ensureDir(targetDir);
+    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);
+        const dest = join(targetDir, entry.name);
+        if (rollbackJournal) {
+            await snapshotFile(rollbackJournal, dest);
+        }
+        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);
+            if (rollbackJournal) {
+                await snapshotFile(rollbackJournal, ftlDest);
+            }
+            await copyFile(ftlSrc, ftlDest);
+            affectedPaths.push(relative(engineDir, ftlDest));
+        }
+    }
+    if (config.register) {
+        try {
+            const modulePath = `chrome://global/content/elements/${name}.mjs`;
+            if (rollbackJournal) {
+                await snapshotFile(rollbackJournal, join(engineDir, CUSTOM_ELEMENTS_JS));
+            }
+            await addCustomElementRegistration(engineDir, name, modulePath);
+            affectedPaths.push(CUSTOM_ELEMENTS_JS);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'customElements.js registration',
+                error: toError(error).message,
+            });
+        }
+    }
+    if (copiedFileNames.length > 0) {
+        try {
+            if (rollbackJournal) {
+                await snapshotFile(rollbackJournal, join(engineDir, JAR_MN));
+            }
+            await addJarMnEntries(engineDir, name, copiedFileNames);
+            affectedPaths.push(JAR_MN);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'jar.mn registration',
+                error: toError(error).message,
+            });
+        }
+    }
+    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) {
+    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' });
+    if (dryRun) {
+        const actions = entries
+            .filter((entry) => entry.isFile() && 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}`,
+        }));
+        if (actions.length === 0) {
+            throw new FurnaceError(`No matching files found in override directory for "${name}"`, name);
+        }
+        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);
+        if (rollbackJournal) {
+            await snapshotFile(rollbackJournal, dest);
+        }
+        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;
+}
+//# sourceMappingURL=furnace-apply-helpers.js.map

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

@@ -0,0 +1,16 @@
+import type { ApplyResult, DryRunAction } from '../types/furnace.js';
+export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, prefixChecksums, } from './furnace-apply-helpers.js';
+/**
+ * Applies all override and custom components to the engine source tree.
+ *
+ * Unchanged components (matching checksums) are skipped. If any component
+ * fails, FireForge restores only the engine files touched during this apply
+ * attempt and leaves the state file unchanged.
+ *
+ * @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)
+ */
+export declare function applyAllComponents(root: string, dryRun?: boolean): Promise<ApplyResult & {
+    actions?: DryRunAction[];
+}>;

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

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { getProjectPaths } from './config.js';
+import { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, prefixChecksums, } 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';
+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)) {
+        const componentDir = join(furnacePaths.overridesDir, name);
+        if (!(await pathExists(componentDir))) {
+            addMissingComponentError(result, name, `components/overrides/${name}`);
+            continue;
+        }
+        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;
+            }
+        }
+        try {
+            const { affectedPaths: filesAffected, actions } = await applyOverrideComponent(engineDir, name, componentDir, overrideConfig, dryRun, rollbackJournal);
+            if (dryRun && actions) {
+                allActions.push(...actions);
+            }
+            result.applied.push({ name, type: 'override', filesAffected });
+            if (!dryRun) {
+                const checksums = await computeComponentChecksums(componentDir);
+                Object.assign(newChecksums, prefixChecksums(checksums, 'override', name));
+            }
+        }
+        catch (error) {
+            result.errors.push({
+                name,
+                error: toError(error).message,
+            });
+        }
+    }
+}
+async function applyCustomBatch(config, furnacePaths, state, engineDir, dryRun, result, allActions, newChecksums, rollbackJournal) {
+    for (const [name, customConfig] of Object.entries(config.custom)) {
+        const componentDir = join(furnacePaths.customDir, name);
+        if (!(await pathExists(componentDir))) {
+            addMissingComponentError(result, name, `components/custom/${name}`);
+            continue;
+        }
+        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;
+            }
+        }
+        try {
+            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, dryRun, rollbackJournal);
+            if (dryRun && actions) {
+                allActions.push(...actions);
+            }
+            result.applied.push({
+                name,
+                type: 'custom',
+                filesAffected,
+                ...(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));
+            }
+        }
+        catch (error) {
+            result.errors.push({
+                name,
+                error: toError(error).message,
+            });
+        }
+    }
+}
+/**
+ * Applies all override and custom components to the engine source tree.
+ *
+ * Unchanged components (matching checksums) are skipped. If any component
+ * fails, FireForge restores only the engine files touched during this apply
+ * attempt and leaves the state file unchanged.
+ *
+ * @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)
+ */
+export async function applyAllComponents(root, dryRun = false) {
+    const config = await loadFurnaceConfig(root);
+    const state = await loadFurnaceState(root);
+    const { engine: engineDir } = getProjectPaths(root);
+    const furnacePaths = getFurnacePaths(root);
+    if (!(await pathExists(engineDir))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
+    }
+    const rollbackJournal = dryRun ? undefined : createRollbackJournal();
+    const result = {
+        applied: [],
+        skipped: [],
+        errors: [],
+    };
+    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);
+    // 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.
+    // --- 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');
+            }
+        }
+        else {
+            await updateFurnaceState(root, {
+                lastApply: new Date().toISOString(),
+                appliedChecksums: newChecksums,
+            });
+        }
+    }
+    if (dryRun) {
+        result.actions = allActions;
+    }
+    return result;
+}
+//# sourceMappingURL=furnace-apply.js.map

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

@@ -0,0 +1,94 @@
+import type { FurnaceConfig, FurnaceState } from '../types/furnace.js';
+/** Name of the furnace configuration file */
+export declare const FURNACE_CONFIG_FILENAME = "furnace.json";
+/** Name of the furnace state file */
+export declare const FURNACE_STATE_FILENAME = "furnace-state.json";
+/** Name of the components directory */
+export declare const COMPONENTS_DIR = "components";
+/** Name of the overrides subdirectory */
+export declare const OVERRIDES_DIR = "overrides";
+/** Name of the custom subdirectory */
+export declare const CUSTOM_DIR = "custom";
+/**
+ * Paths for furnace-related files and directories.
+ */
+interface FurnacePaths {
+    /** Path to furnace.json */
+    furnaceConfig: string;
+    /** Path to components directory */
+    componentsDir: string;
+    /** Path to components/overrides directory */
+    overridesDir: string;
+    /** Path to components/custom directory */
+    customDir: string;
+    /** Path to .fireforge/furnace-state.json */
+    furnaceState: string;
+}
+/**
+ * Gets all furnace-related paths based on a root directory.
+ * @param root - Root directory of the project
+ * @returns All furnace paths
+ */
+export declare function getFurnacePaths(root: string): FurnacePaths;
+/**
+ * Checks if a furnace.json exists in the given directory.
+ * @param root - Root directory to check
+ * @returns True if furnace.json exists
+ */
+export declare function furnaceConfigExists(root: string): Promise<boolean>;
+/**
+ * Validates a raw config object and returns a typed FurnaceConfig.
+ * @param data - Raw data to validate
+ * @returns Validated FurnaceConfig
+ * @throws Error if validation fails
+ */
+export declare function validateFurnaceConfig(data: unknown): FurnaceConfig;
+/**
+ * Validates a parsed furnace state object and returns a typed FurnaceState.
+ * @param data - Parsed JSON state data
+ * @returns Validated FurnaceState
+ */
+export declare function validateFurnaceState(data: unknown): FurnaceState;
+/**
+ * Loads and validates the furnace.json configuration.
+ * @param root - Root directory of the project
+ * @returns Validated FurnaceConfig
+ * @throws Error if config doesn't exist or is invalid
+ */
+export declare function loadFurnaceConfig(root: string): Promise<FurnaceConfig>;
+/**
+ * Writes a furnace configuration to furnace.json.
+ * @param root - Root directory of the project
+ * @param config - Configuration to write
+ */
+export declare function writeFurnaceConfig(root: string, config: FurnaceConfig): Promise<void>;
+/**
+ * Creates a default furnace configuration.
+ * @returns A valid empty FurnaceConfig
+ */
+export declare function createDefaultFurnaceConfig(): FurnaceConfig;
+/**
+ * Loads furnace config if it exists, or creates and writes a default config.
+ * @param root - Root directory of the project
+ * @returns FurnaceConfig (existing or newly created)
+ */
+export declare function ensureFurnaceConfig(root: string): Promise<FurnaceConfig>;
+/**
+ * Loads the furnace state, or returns defaults if it doesn't exist.
+ * @param root - Root directory of the project
+ * @returns Furnace state
+ */
+export declare function loadFurnaceState(root: string): Promise<FurnaceState>;
+/**
+ * Saves the furnace state.
+ * @param root - Root directory of the project
+ * @param state - State to save
+ */
+export declare function saveFurnaceState(root: string, state: FurnaceState): Promise<void>;
+/**
+ * Updates furnace state fields transactionally under the state file lock.
+ * @param root - Root directory of the project
+ * @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 {};