@hominis/fireforge 0.10.1 → 0.11.1

package/dist/src/commands/export.js

@@ -3,18 +3,21 @@ import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { appendHistory, confirmDestructive } from '../core/destructive.js';
+import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getStatusWithCodes, isGitRepository } from '../core/git.js';
 import { generateBinaryFilePatch, generateFullFilePatch } from '../core/git-diff.js';
 import { isBinaryFile } from '../core/git-file-ops.js';
 import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { commitExportedPatch } from '../core/patch-export.js';
-import { GeneralError } from '../errors/base.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
-import { PATCH_CATEGORIES } from '../utils/validation.js';
+import { parsePositiveIntegerFlag, PATCH_CATEGORIES } from '../utils/validation.js';
+import { commitPlacementExport, placementSummary, projectPlacementForLint, renderDryRunPreview, resolvePlacementPlan, } from './export-flow.js';
 import { autoFixLicenseHeaders, confirmSupersedePatches, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
@@ -90,8 +93,23 @@ async function generatePatchDiff(engineDir, allFiles) {
  * @param files - File or directory paths to export (relative to engine/)
  * @param options - Export options
  */
+// The command body is intentionally linear: validation → diff → placement
+// gate → dry-run/placement/default write. Splitting it further would
+// spread the error-handling (spinner.error, try/catch) across multiple
+// helpers and hurt readability more than it would help.
+// eslint-disable-next-line max-lines-per-function
 export async function exportCommand(projectRoot, files, options) {
-    intro('FireForge Export');
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge Export (dry run)' : 'FireForge Export');
+    // Placement flags are mutually exclusive with each other.
+    const placementFlagCount = [
+        options.order !== undefined,
+        options.before !== undefined,
+        options.after !== undefined,
+    ].filter(Boolean).length;
+    if (placementFlagCount > 1) {
+        throw new InvalidArgumentError('--order, --before, and --after are mutually exclusive.', 'export placement');
+    }
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
@@ -101,7 +119,19 @@ export async function exportCommand(projectRoot, files, options) {
     if (!(await isGitRepository(paths.engine))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
-    const allFiles = await collectExportFiles(paths, files);
+    let allFiles = await collectExportFiles(paths, files);
+    // Filter out furnace-managed files when --exclude-furnace is set
+    if (options.excludeFurnace) {
+        const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+        if (furnacePrefixes.size > 0) {
+            const before = allFiles.length;
+            allFiles = allFiles.filter((file) => ![...furnacePrefixes].some((prefix) => file.startsWith(prefix)));
+            const excluded = before - allFiles.length;
+            if (excluded > 0) {
+                info(`Excluded ${excluded} furnace-managed file${excluded === 1 ? '' : 's'} from export`);
+            }
+        }
+    }
     if (allFiles.length === 0) {
         const pathList = files.join(', ');
         throw new GeneralError(`Paths "${pathList}" have no changes to export.\n\n` +
@@ -124,11 +154,120 @@ export async function exportCommand(projectRoot, files, options) {
     if (!metadata)
         return;
     const { patchName, selectedCategory, description } = metadata;
-    const s = spinner('Exporting patch...');
+    const s = spinner(isDryRun ? 'Planning export...' : 'Exporting patch...');
     try {
         // Extract affected files from diff
         const filesAffected = extractAffectedFiles(diff);
         await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint);
+        // Resolve placement (if any flag was given). Placement is mutually
+        // exclusive with supersede — the semantics overlap confusingly.
+        let placementPlan = null;
+        if (placementFlagCount > 0) {
+            if (options.supersede) {
+                throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
+            }
+            placementPlan = await resolvePlacementPlan(paths.patches, options, selectedCategory, patchName);
+            const conflicts = await projectPlacementForLint(paths.patches, placementPlan, diff);
+            const summary = placementSummary(placementPlan);
+            const renameCount = placementPlan.renameMap.size;
+            // Route through confirmDestructive when the operation is destructive
+            // enough to warrant a prompt (more than one rename) OR when the user
+            // asked for a dry-run. The dry-run branch must always print the
+            // placement summary — previously, single-rename/no-rename dry-runs
+            // exited silently with no filename or projected layout.
+            if (renameCount > 1 || isDryRun) {
+                s.stop();
+                const decision = await confirmDestructive({
+                    operation: 'export-order',
+                    title: `Export with placement at order ${placementPlan.insertionOrder}`,
+                    summary,
+                    yes: options.yes === true,
+                    dryRun: isDryRun,
+                    unsafeOverride: options.forceUnsafe === true,
+                    conflicts,
+                });
+                if (decision === 'dry-run') {
+                    outro('Dry run complete — no changes made');
+                    return;
+                }
+                if (decision === 'cancelled') {
+                    outro('Export cancelled');
+                    return;
+                }
+            }
+            else if (conflicts && options.forceUnsafe !== true) {
+                s.stop();
+                throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. Pass --force-unsafe to override.`, '--force-unsafe');
+            }
+        }
+        // Dry-run path: compute the plan and print it, never write.
+        if (isDryRun && !placementPlan) {
+            s.stop('Plan ready');
+            await renderDryRunPreview({
+                patchesDir: paths.patches,
+                category: selectedCategory,
+                name: patchName,
+                description,
+                filesAffected,
+                sourceEsrVersion: config.firefox.version,
+                explicitSupersede: options.supersede === true,
+            });
+            outro('Dry run complete — no changes made');
+            return;
+        }
+        // Placement path (non-dry-run): run the renumber + write + manifest
+        // update under a single patch directory lock so concurrent exports
+        // cannot race into the renumber gap. Dry-runs with a placement plan
+        // are fully handled in the placement gate above and never reach here.
+        if (placementPlan) {
+            const placementMetadata = {
+                filename: placementPlan.newFilename,
+                order: placementPlan.insertionOrder,
+                category: selectedCategory,
+                name: patchName,
+                description,
+                createdAt: new Date().toISOString(),
+                sourceEsrVersion: config.firefox.version,
+                filesAffected,
+            };
+            const committedPlan = await commitPlacementExport({
+                patchesDir: paths.patches,
+                options,
+                category: selectedCategory,
+                name: patchName,
+                diff,
+                metadata: placementMetadata,
+                expectedPlan: placementPlan,
+                unsafeOverride: options.forceUnsafe === true,
+                // History append runs inside the same lock as the mutation so
+                // concurrent placement exports cannot interleave their records
+                // and a crash between mutation and record cannot orphan the
+                // audit entry.
+                onCommitted: async (finalPlan) => {
+                    await appendHistory(paths.patches, {
+                        operation: 'export-order',
+                        args: {
+                            filename: finalPlan.newFilename,
+                            order: finalPlan.insertionOrder,
+                            renames: Array.from(finalPlan.renameMap.entries()).map(([from, entry]) => ({
+                                from,
+                                to: entry.newFilename,
+                                order: entry.newOrder,
+                            })),
+                        },
+                        ...(options.yes === true ? { yes: true } : {}),
+                        ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
+                        result: 'ok',
+                    });
+                },
+            });
+            s.stop(`Exported to ${committedPlan.newFilename}`);
+            info(`\nPatch saved to: patches/${committedPlan.newFilename}`);
+            info(`Files affected: ${filesAffected.join(', ')}`);
+            outro('Export complete');
+            return;
+        }
+        // Default (no dry-run, no placement) path: the pre-existing behavior.
         // Check how many existing patches would be superseded
         const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
         if (!shouldProceed)
@@ -167,6 +306,13 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('-d, --description <desc>', 'Description of the patch')
         .option('--supersede', 'Allow superseding multiple existing patches')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
+        .option('--dry-run', 'Print the export plan (including supersede preview) without writing')
+        .addOption(new Option('--order <N>', 'Place the new patch at this ordinal, shifting subsequent patches up').argParser((v) => parsePositiveIntegerFlag('--order', v)))
+        .option('--before <anchor>', 'Place the new patch immediately before <anchor>')
+        .option('--after <anchor>', 'Place the new patch immediately after <anchor>')
+        .option('-y, --yes', 'Skip confirmation for placement renumbers (required for non-TTY)')
+        .option('--force-unsafe', 'Bypass cross-patch lint refusal on projected placement')
+        .option('--exclude-furnace', 'Exclude furnace-managed file paths from the export')
         .action(withErrorHandling(async (paths, options) => {
         const { category, ...rest } = options;
         await exportCommand(getProjectRoot(), paths, {

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

@@ -1,7 +1,8 @@
 import type { FurnaceApplyOptions } from '../../types/commands/index.js';
 /**
- * Runs the furnace apply command to apply all components to the engine.
+ * Runs the furnace apply command to apply components to the engine.
  * @param projectRoot - Root directory of the project
+ * @param name - Optional component name to apply a single component
  * @param options - Apply options
  */
-export declare function furnaceApplyCommand(projectRoot: string, options?: FurnaceApplyOptions): Promise<void>;
+export declare function furnaceApplyCommand(projectRoot: string, name?: string, options?: FurnaceApplyOptions): Promise<void>;

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

@@ -1,17 +1,155 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { getProjectPaths } from '../../core/config.js';
-import { applyAllComponents } from '../../core/furnace-apply.js';
-import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
+import { watch as fsWatch } from 'node:fs';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { applyAllComponents, computeComponentChecksums } from '../../core/furnace-apply.js';
+import { logApplyResult } from '../../core/furnace-apply-output.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, } from '../../core/furnace-config.js';
+import { isComponentSourceFile } from '../../core/furnace-constants.js';
+import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftError, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { pathExists } from '../../utils/fs.js';
-import { error, info, intro, outro, spinner, success, warn } from '../../utils/logger.js';
+import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
+/** Interval (ms) for the periodic checksum poll that catches events missed by fs.watch. */
+const WATCH_POLL_INTERVAL_MS = 30_000;
 /**
- * Runs the furnace apply command to apply all components to the engine.
+ * Collects a combined checksum snapshot across all watched directories.
+ */
+async function snapshotWatchedChecksums(watchDirs) {
+    const combined = new Map();
+    for (const dir of watchDirs) {
+        try {
+            const checksums = await computeComponentChecksums(dir);
+            for (const [file, hash] of Object.entries(checksums)) {
+                combined.set(`${dir}/${file}`, hash);
+            }
+        }
+        catch {
+            // Directory may have been removed between iterations — ignore.
+        }
+    }
+    return combined;
+}
+function checksumMapsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [key, value] of a) {
+        if (b.get(key) !== value)
+            return false;
+    }
+    return true;
+}
+async function runWatchLoop(projectRoot) {
+    const furnacePaths = getFurnacePaths(projectRoot);
+    const watchDirs = [];
+    if (await pathExists(furnacePaths.overridesDir))
+        watchDirs.push(furnacePaths.overridesDir);
+    if (await pathExists(furnacePaths.customDir))
+        watchDirs.push(furnacePaths.customDir);
+    if (watchDirs.length === 0) {
+        info('No component directories to watch.');
+        return;
+    }
+    if (process.platform === 'linux') {
+        warn('Watch mode uses fs.watch with recursive: true, which may miss changes ' +
+            'in deeply nested directories on Linux. A periodic poll runs every 30s as a fallback.');
+    }
+    info(`Watching ${watchDirs.length} directory(ies) for changes... (Ctrl+C to stop)`);
+    let debounceTimer = null;
+    let applyInFlight = false;
+    let lastChecksums = await snapshotWatchedChecksums(watchDirs);
+    const triggerApply = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            if (applyInFlight)
+                return;
+            applyInFlight = true;
+            void (async () => {
+                try {
+                    info('\nChange detected — re-applying...');
+                    const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
+                    logApplyResult(result, false);
+                    const applied = result.applied.length;
+                    const skipped = result.skipped.length;
+                    info(`Re-applied: ${applied} applied, ${skipped} skipped`);
+                }
+                catch (err) {
+                    warn(`Apply failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                finally {
+                    applyInFlight = false;
+                    // Update checksums after apply so the next poll does not re-trigger.
+                    lastChecksums = await snapshotWatchedChecksums(watchDirs);
+                }
+            })();
+        }, 300);
+    };
+    // Register signal-driven cleanup BEFORE creating watchers so there is no
+    // race window where a SIGINT could arrive after watchers exist but before
+    // cleanup handlers are registered.
+    const watchers = [];
+    let pollTimer = null;
+    const cleanup = () => {
+        for (const w of watchers)
+            w.close();
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        if (pollTimer)
+            clearInterval(pollTimer);
+    };
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+    for (const dir of watchDirs) {
+        const watcher = fsWatch(dir, { recursive: true }, (_event, filename) => {
+            if (!filename)
+                return;
+            if (isComponentSourceFile(filename)) {
+                triggerApply();
+            }
+        });
+        watcher.on('error', (err) => {
+            warn(`Watcher error on ${dir}: ${err.message}. Periodic poll will continue as fallback.`);
+        });
+        watchers.push(watcher);
+    }
+    // Periodic checksum-based poll to catch events missed by fs.watch (known
+    // issue on Linux with recursive: true and certain filesystems).
+    pollTimer = setInterval(() => {
+        if (applyInFlight)
+            return;
+        void (async () => {
+            try {
+                const current = await snapshotWatchedChecksums(watchDirs);
+                if (!checksumMapsEqual(current, lastChecksums)) {
+                    triggerApply();
+                }
+            }
+            catch {
+                // Best effort — errors here are transient filesystem issues.
+            }
+        })();
+    }, WATCH_POLL_INTERVAL_MS);
+    // Block until signal. The cleanup function registered above closes all
+    // watchers when SIGINT/SIGTERM arrives. The finally block is a safety net
+    // in case the Promise settles through some other path.
+    try {
+        await new Promise(() => { });
+    }
+    finally {
+        cleanup();
+        process.removeListener('SIGINT', cleanup);
+        process.removeListener('SIGTERM', cleanup);
+    }
+}
+/**
+ * Runs the furnace apply command to apply components to the engine.
  * @param projectRoot - Root directory of the project
+ * @param name - Optional component name to apply a single component
  * @param options - Apply options
  */
-export async function furnaceApplyCommand(projectRoot, options = {}) {
-    intro('Furnace Apply');
+export async function furnaceApplyCommand(projectRoot, name, options = {}) {
+    intro(name ? `Furnace Apply (${name})` : 'Furnace Apply');
     // Verify engine exists
     const paths = getProjectPaths(projectRoot);
     if (!(await pathExists(paths.engine))) {
@@ -29,42 +167,33 @@ export async function furnaceApplyCommand(projectRoot, options = {}) {
         outro('Done');
         return;
     }
+    // Warn on baseVersion drift before mutating the engine. This is advisory
+    // only: apply continues, because a silent divergence is worse than a
+    // noisy one and the operator is the only authority on whether the
+    // upstream component has actually changed shape.
+    const forgeConfig = await loadConfig(projectRoot);
+    const driftEntries = findOverrideBaseVersionDrift(config, forgeConfig.firefox.version);
+    for (const entry of driftEntries) {
+        warn(formatOverrideBaseVersionDriftWarning(entry));
+    }
     const dryRun = options.dryRun ?? false;
+    const force = options.force ?? false;
+    if (!force && driftEntries.length > 0) {
+        throw new FurnaceError(formatOverrideBaseVersionDriftError(driftEntries));
+    }
     const applySpinner = dryRun ? undefined : spinner('Applying components to engine...');
-    const result = await applyAllComponents(projectRoot, dryRun);
+    const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, dryRun, {
+        operationContext: ctx,
+        ...(name !== undefined ? { componentName: name } : {}),
+    }), { dryRun });
     if (applySpinner) {
         applySpinner.stop('Components applied');
     }
-    // Report applied
-    for (const applied of result.applied) {
-        const prefix = dryRun ? '[dry-run] Would apply' : '';
-        const label = dryRun
-            ? `${prefix} ${applied.name} (${applied.type}) → ${applied.filesAffected.length} files`
-            : `${applied.name} (${applied.type}) → ${applied.filesAffected.length} files`;
-        if (dryRun) {
-            info(label);
-        }
-        else {
-            success(label);
-        }
-        if (applied.stepErrors && applied.stepErrors.length > 0) {
-            for (const stepErr of applied.stepErrors) {
-                warn(`${applied.name}: [${stepErr.step}] ${stepErr.error}`);
-            }
-        }
-    }
-    // Report skipped
-    for (const skipped of result.skipped) {
-        info(`${skipped.name} — ${skipped.reason}`);
-    }
-    // Report errors
-    for (const err of result.errors) {
-        error(`${err.name} — ${err.error}`);
-    }
-    const stepFailureCount = dryRun
+    logApplyResult(result, dryRun);
+    const appliedWithStepErrorsCount = dryRun
         ? 0
         : result.applied.filter((entry) => (entry.stepErrors?.length ?? 0) > 0).length;
-    const totalApplyFailures = result.errors.length + stepFailureCount;
+    const totalApplyFailures = result.errors.length + appliedWithStepErrorsCount;
     if (totalApplyFailures > 0) {
         throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
     }
@@ -76,5 +205,9 @@ export async function furnaceApplyCommand(projectRoot, options = {}) {
     else {
         outro(`Applied ${appliedCount}, skipped ${skippedCount}`);
     }
+    // Watch mode: re-apply on file changes in component directories
+    if (options.watch && !dryRun) {
+        await runWatchLoop(projectRoot);
+    }
 }
 //# sourceMappingURL=apply.js.map