@hominis/fireforge 0.13.1 → 0.14.0

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

@@ -39,59 +39,157 @@ function checksumMapsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Builds a watch-loop apply-failure message tailored to the error class so
+ * transient filesystem errors (EACCES, ENOSPC, lock timeout) look different
+ * from genuine apply-level failures; the previous generic "Apply failed: ..."
+ * collapsed all causes into one string and made diagnosis difficult.
+ */
+function classifyWatchApplyError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof FurnaceError) {
+        return `Apply failed: ${message}`;
+    }
+    const code = err instanceof Error ? err.code : undefined;
+    switch (code) {
+        case 'EACCES':
+        case 'EPERM':
+            return `Apply failed: permission denied — ${message}`;
+        case 'ENOSPC':
+            return `Apply failed: disk full — ${message}`;
+        case 'EBUSY':
+        case 'ETXTBSY':
+            return `Apply failed: file is in use — ${message}`;
+        case 'ENOENT':
+            return `Apply failed: missing file — ${message}`;
+        case 'ETIMEDOUT':
+            return `Apply failed: operation timed out — ${message}`;
+        default:
+            return `Apply failed: ${message}`;
+    }
+}
 async function runWatchLoop(projectRoot) {
     const furnacePaths = getFurnacePaths(projectRoot);
+    // Both categories are eligible targets. The set is fixed; only existence
+    // varies over time — a component dir created AFTER watch started (e.g.
+    // the user runs `furnace create` in another terminal) must be picked up
+    // without restarting watch. The prior one-shot `pathExists` check at
+    // startup captured only the dirs that existed then, leaving any later
+    // creation invisible.
+    const candidateDirs = [furnacePaths.overridesDir, furnacePaths.customDir];
     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;
-    }
+    const watchers = new Map();
     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);
+    // Coalesces changes that arrive while an apply is running. Without this
+    // flag, a second edit during an in-flight apply is debounced, the timer
+    // fires while applyInFlight is true, and the change is dropped entirely
+    // because the post-apply checksum snapshot already reflects the edit so
+    // the 30s poll also sees no diff.
+    let pendingChange = false;
+    let lastChecksums = new Map();
+    let pollTimer = null;
+    const runApplyCycle = async () => {
+        applyInFlight = true;
+        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(classifyWatchApplyError(err));
+        }
+        finally {
+            applyInFlight = false;
+            // Update checksums after apply so the next poll does not re-trigger
+            // for changes that are already reflected in the engine.
+            lastChecksums = await snapshotWatchedChecksums(watchDirs);
+        }
+        // Another change arrived while we were applying — run again so the edit
+        // is not silently absorbed into the post-apply checksum bump.
+        if (pendingChange) {
+            pendingChange = false;
+            await runApplyCycle();
+        }
+    };
     const triggerApply = () => {
+        if (applyInFlight) {
+            // An apply is already running; record the change so runApplyCycle
+            // re-runs after it completes. Do not schedule a new debounce: the
+            // in-flight apply will observe this flag when it finishes.
+            pendingChange = true;
+            return;
+        }
         if (debounceTimer)
             clearTimeout(debounceTimer);
         debounceTimer = setTimeout(() => {
-            if (applyInFlight)
+            debounceTimer = null;
+            if (applyInFlight) {
+                // Race with a change that started its own apply between the debounce
+                // scheduling and the timer firing. Record the pending change; the
+                // in-flight apply will pick it up.
+                pendingChange = true;
                 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)}`);
+            }
+            void runApplyCycle();
+        }, 300);
+    };
+    const installWatcher = (dir) => {
+        if (watchers.has(dir))
+            return false;
+        try {
+            const watcher = fsWatch(dir, { recursive: true }, (_event, filename) => {
+                if (!filename)
+                    return;
+                if (isComponentSourceFile(filename)) {
+                    triggerApply();
                 }
-                finally {
-                    applyInFlight = false;
-                    // Update checksums after apply so the next poll does not re-trigger.
-                    lastChecksums = await snapshotWatchedChecksums(watchDirs);
+            });
+            watcher.on('error', (err) => {
+                warn(`Watcher error on ${dir}: ${err.message}. Periodic poll will continue as fallback.`);
+            });
+            watchers.set(dir, watcher);
+            watchDirs.push(dir);
+            return true;
+        }
+        catch (err) {
+            // Directory vanished between the pathExists check and fs.watch, or
+            // fs.watch otherwise refused. refreshWatchers will retry on the next
+            // poll tick.
+            warn(`Could not start watcher on ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    };
+    // Scans candidate dirs for ones we are not yet watching and installs a
+    // watcher for each that now exists. Returns true when at least one new
+    // watcher was installed so the caller can trigger an apply cycle for
+    // the just-noticed content.
+    const refreshWatchers = async () => {
+        let added = false;
+        for (const dir of candidateDirs) {
+            if (watchers.has(dir))
+                continue;
+            if (await pathExists(dir)) {
+                if (installWatcher(dir)) {
+                    info(`Now watching ${dir}`);
+                    added = true;
                 }
-            })();
-        }, 300);
+            }
+        }
+        return added;
     };
     // 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)
+        for (const w of watchers.values())
             w.close();
         if (debounceTimer)
             clearTimeout(debounceTimer);
@@ -100,26 +198,28 @@ async function runWatchLoop(projectRoot) {
     };
     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).
+    await refreshWatchers();
+    lastChecksums = await snapshotWatchedChecksums(watchDirs);
+    if (watchDirs.length === 0) {
+        info('No component directories exist yet — will retry every 30s. Create one with "fireforge furnace override" or "fireforge furnace create" in another terminal to begin watching.');
+    }
+    else {
+        info(`Watching ${watchDirs.length} directory(ies) for changes... (Ctrl+C to stop)`);
+    }
+    // Periodic checksum-based poll that also picks up newly-created component
+    // dirs (fs.watch was not installed for them at startup because they did
+    // not yet exist).
     pollTimer = setInterval(() => {
         if (applyInFlight)
             return;
         void (async () => {
             try {
+                const added = await refreshWatchers();
+                if (added) {
+                    lastChecksums = await snapshotWatchedChecksums(watchDirs);
+                    triggerApply();
+                    return;
+                }
                 const current = await snapshotWatchedChecksums(watchDirs);
                 if (!checksumMapsEqual(current, lastChecksums)) {
                     triggerApply();

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

@@ -134,7 +134,11 @@ async function scaffoldTestFiles(componentName, license, forgeConfig, paths, jou
     // browser.toml — create if missing, append entry if existing
     const tomlPath = join(testDir, 'browser.toml');
     if (await pathExists(tomlPath)) {
-        // Append the new test entry if not already present
+        // Defensive guard: only append if the entry is not already present.
+        // With a fresh journal per create, the same test file name cannot be
+        // appended twice in a single run — but retaining the check protects
+        // against accidental re-entrance or a future refactor that reuses the
+        // helper with a stale test directory.
         const existingToml = await readText(tomlPath);
         if (!existingToml.includes(`["${testFileName}"]`)) {
             if (journal)
@@ -284,14 +288,21 @@ async function writeComponentFiles(componentDir, componentName, className, descr
  * state.
  */
 async function performCreateMutations(args) {
+    // Invariant: the journal MUST be registered with the operation context
+    // BEFORE any filesystem mutation (including recordCreatedDir, whose entries
+    // are consulted by SIGINT rollback). The try/catch below assumes signal
+    // handlers can find the journal for any partial write that follows.
     const journal = createRollbackJournal();
     if (args.operationContext) {
         args.operationContext.registerJournal(journal);
     }
-    recordCreatedDir(journal, args.componentDir);
     const testFiles = [];
     let files;
     try {
+        // Record the componentDir creation entry immediately after registration
+        // so signal-driven rollback can clean it up even if writeComponentFiles
+        // is interrupted mid-ensureDir.
+        recordCreatedDir(journal, args.componentDir);
         files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, journal);
         const customEntry = {
             description: args.description,

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

@@ -44,10 +44,25 @@ function getFailedComponentNames(result) {
 }
 function getPersistableAppliedEntry(name, appliedEntry) {
     if (!appliedEntry) {
-        throw new FurnaceError(`Named deploy for "${name}" completed without an applied entry.`);
+        throw new FurnaceError(`Deploy for "${name}" finished without producing an applied component entry; ` +
+            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to ` +
+            `reconcile state, then retry the deploy. If this persists, file a bug with the ` +
+            `output of "fireforge doctor".`);
     }
     if (appliedEntry.type !== 'override' && appliedEntry.type !== 'custom') {
-        throw new FurnaceError(`Named deploy for "${name}" returned unsupported component type "${appliedEntry.type}".`);
+        throw new FurnaceError(`Deploy for "${name}" returned an unsupported component type "${appliedEntry.type}"; ` +
+            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to reconcile, ` +
+            `then verify the component with "fireforge furnace validate" before retrying.`);
+    }
+    // Guard against future refactors that might reorder or misroute the
+    // applied[] array: named deploy persists state under a single component
+    // name, so the first applied entry MUST be that component. Persisting a
+    // different component's checksums here would cause the next status/apply
+    // run to mis-report health for both components involved.
+    if (name !== undefined && appliedEntry.name !== name) {
+        throw new FurnaceError(`Deploy for "${name}" returned an applied entry for a different component ` +
+            `("${appliedEntry.name}"); refusing to persist mismatched state. ` +
+            `Run "fireforge doctor --repair-furnace" to reconcile, then retry the deploy.`);
     }
     return {
         name: appliedEntry.name,

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

@@ -51,7 +51,9 @@ async function diffOverride(name, projectRoot, config) {
     const state = await loadState(projectRoot);
     const baseCommit = overrideConfig.baseCommit ?? state.baseCommit;
     if (!baseCommit) {
-        throw new FurnaceError('Cannot diff: baseCommit not found. Re-run "fireforge download" to establish a baseline.', name);
+        throw new FurnaceError(`Cannot diff "${name}": baseCommit not recorded for this override. ` +
+            `Run "fireforge furnace refresh --reset-base ${name}" to stamp the current engine HEAD as the baseline, ` +
+            `or re-run "fireforge download" to re-establish a project-wide baseline.`, name);
     }
     const entries = await readdir(overrideDir, { withFileTypes: true });
     let hasDifferences = false;

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

@@ -1,8 +1,30 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { isAbsolute, normalize } from 'node:path';
 import { text } from '@clack/prompts';
 import { createDefaultFurnaceConfig, furnaceConfigExists, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { cancel, info, intro, isCancel, note, outro, success } from '../../utils/logger.js';
+/**
+ * Validates an FTL base path before writing it to furnace.json. Rejects
+ * absolute paths, null bytes, and any normalised segment starting with
+ * `..` — the previous `includes('..')` substring check caught the common
+ * case but missed `./../../` and absolute paths that are arguably worse.
+ */
+function validateFtlBasePath(value) {
+    if (value.length === 0) {
+        throw new FurnaceError('ftlBasePath must not be empty.');
+    }
+    if (value.includes('\0')) {
+        throw new FurnaceError('ftlBasePath must not contain null bytes.');
+    }
+    if (isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) {
+        throw new FurnaceError(`ftlBasePath "${value}" must be a relative path inside the engine checkout, not absolute.`);
+    }
+    const normalized = normalize(value.replace(/\\/g, '/'));
+    if (normalized === '..' || normalized.startsWith('../')) {
+        throw new FurnaceError(`ftlBasePath "${value}" must not escape the engine checkout via parent-directory segments.`);
+    }
+}
 /**
  * Runs the furnace init command to create a default furnace.json with
  * user-specified settings.
@@ -15,7 +37,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
         throw new FurnaceError('furnace.json already exists. Use --force to overwrite it.');
     }
     const config = createDefaultFurnaceConfig();
-    const isInteractive = process.stdin.isTTY;
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
     // Resolve componentPrefix
     if (options.prefix !== undefined) {
         config.componentPrefix = options.prefix;
@@ -38,9 +60,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
     }
     // Resolve ftlBasePath
     if (options.ftlBasePath !== undefined) {
-        if (options.ftlBasePath.includes('..')) {
-            throw new FurnaceError('ftlBasePath must not contain ".." (path traversal)');
-        }
+        validateFtlBasePath(options.ftlBasePath);
         config.ftlBasePath = options.ftlBasePath;
     }
     else if (isInteractive) {
@@ -54,9 +74,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
         }
         const ftlValue = ftlResult.trim();
         if (ftlValue) {
-            if (ftlValue.includes('..')) {
-                throw new FurnaceError('ftlBasePath must not contain ".." (path traversal)');
-            }
+            validateFtlBasePath(ftlValue);
             config.ftlBasePath = ftlValue;
         }
     }

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

@@ -9,15 +9,23 @@ import { formatErrorText, formatSuccessText, info, intro, note, outro, } from '.
  * its workspace checksums have changed since the last apply.
  */
 async function getHealthIndicator(componentDir, type, name, appliedChecksums) {
-    if (!(await pathExists(componentDir))) {
-        return formatErrorText('missing');
+    try {
+        if (!(await pathExists(componentDir))) {
+            return formatErrorText('missing');
+        }
+        const previous = extractComponentChecksums(appliedChecksums, type, name);
+        if (Object.keys(previous).length === 0) {
+            return formatErrorText('not applied');
+        }
+        const changed = await hasComponentChanged(componentDir, previous);
+        return changed ? formatErrorText('modified') : formatSuccessText('clean');
     }
-    const previous = extractComponentChecksums(appliedChecksums, type, name);
-    if (Object.keys(previous).length === 0) {
-        return formatErrorText('not applied');
+    catch {
+        // A race with `furnace remove`, filesystem permission change, or a
+        // transient IO failure must not crash the entire `list -v` output —
+        // render a degraded state so the rest of the table still shows.
+        return formatErrorText('unavailable');
     }
-    const changed = await hasComponentChanged(componentDir, previous);
-    return changed ? formatErrorText('modified') : formatSuccessText('clean');
 }
 /**
  * Runs the furnace list command to display all registered components.

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { select, text } from '@clack/prompts';
 import { getProjectPaths, loadConfig, loadState } from '../../core/config.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
@@ -31,6 +31,24 @@ async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasF
     await ensureDir(destDir);
     const entries = await readdir(srcDir, { withFileTypes: true });
     const copiedFiles = [];
+    // Snapshot-then-copy helper: ensures the destination's parent dir exists
+    // before snapshot + copy, and surfaces the failing filename on error so
+    // partial-state rollback has the context needed to report cleanly.
+    const snapshotAndCopy = async (from, dest, displayName) => {
+        await ensureDir(dirname(dest));
+        try {
+            await snapshotFile(journal, dest);
+        }
+        catch (error) {
+            throw new FurnaceError(`Failed to snapshot "${displayName}" before override: ${toError(error).message}`, componentName);
+        }
+        try {
+            await copyFile(from, dest);
+        }
+        catch (error) {
+            throw new FurnaceError(`Failed to copy "${displayName}" into the override: ${toError(error).message}`, componentName);
+        }
+    };
     for (const entry of entries) {
         if (!entry.isFile())
             continue;
@@ -38,8 +56,7 @@ async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasF
             // Only copy .css files
             if (entry.name.endsWith('.css')) {
                 const dest = join(destDir, entry.name);
-                await snapshotFile(journal, dest);
-                await copyFile(join(srcDir, entry.name), dest);
+                await snapshotAndCopy(join(srcDir, entry.name), dest, entry.name);
                 copiedFiles.push(entry.name);
             }
         }
@@ -47,8 +64,7 @@ async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasF
             // Full override: copy .mjs and .css files
             if (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')) {
                 const dest = join(destDir, entry.name);
-                await snapshotFile(journal, dest);
-                await copyFile(join(srcDir, entry.name), dest);
+                await snapshotAndCopy(join(srcDir, entry.name), dest, entry.name);
                 copiedFiles.push(entry.name);
             }
         }
@@ -57,8 +73,7 @@ async function copyOverrideFiles(engineDir, srcDir, destDir, componentName, hasF
         const ftlName = `${componentName}.ftl`;
         const ftlSrc = join(engineDir, ftlDir, ftlName);
         const dest = join(destDir, ftlName);
-        await snapshotFile(journal, dest);
-        await copyFile(ftlSrc, dest);
+        await snapshotAndCopy(ftlSrc, dest, ftlName);
         copiedFiles.push(ftlName);
     }
     return copiedFiles;
@@ -123,6 +138,24 @@ async function performOverrideMutations(args) {
         }
     });
 }
+/**
+ * Throws if `componentName` is already classified anywhere in the furnace
+ * config. Without this guard, `writeFurnaceConfig` would happily produce a
+ * file where the same tag appears under multiple categories (stock +
+ * override, custom + override) and later commands would no longer be able
+ * to reason about that component cleanly.
+ */
+function assertNoComponentCollision(config, componentName) {
+    if (componentName in config.overrides) {
+        throw new FurnaceError(`An override for "${componentName}" already exists in furnace.json`, componentName);
+    }
+    if (config.stock.includes(componentName)) {
+        throw new FurnaceError(`"${componentName}" is already registered as a stock component. Remove it from config.stock before creating an override.`, componentName);
+    }
+    if (componentName in config.custom) {
+        throw new FurnaceError(`"${componentName}" is already registered as a custom component. Custom components cannot also be overrides.`, componentName);
+    }
+}
 /**
  * Runs the furnace override command to fork an existing engine component.
  * @param projectRoot - Root directory of the project
@@ -179,10 +212,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         }
         componentName = selected;
     }
-    // Check for existing override
-    if (componentName in config.overrides) {
-        throw new FurnaceError(`An override for "${componentName}" already exists in furnace.json`, componentName);
-    }
+    assertNoComponentCollision(config, componentName);
     // Validate the component exists in engine
     const details = await getComponentDetails(paths.engine, componentName, ftlDir);
     if (!details) {
@@ -292,12 +322,14 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
     const ftlDir = resolveFtlDir(config.ftlBasePath);
     const forgeConfig = await loadConfig(projectRoot);
     const state = await loadState(projectRoot);
-    // Check for duplicates and pre-existing overrides
+    // Check for duplicates and pre-existing classifications across every
+    // bucket in furnace.json. Missing these collisions silently double-
+    // classifies a tag (e.g. both stock and override) and leaves the
+    // workspace in a state that later `furnace status`/`apply` cannot
+    // reason about cleanly.
     const uniqueNames = [...new Set(names)];
     for (const name of uniqueNames) {
-        if (name in config.overrides) {
-            throw new FurnaceError(`An override for "${name}" already exists in furnace.json`, name);
-        }
+        assertNoComponentCollision(config, name);
     }
     const succeeded = [];
     const failed = [];