@hominis/fireforge 0.13.2 → 0.15.1

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-templates.d.ts

@@ -0,0 +1,26 @@
+/**
+ * File-content templates for `fireforge furnace create`. Extracted from the
+ * command entrypoint so the generator is unit-testable in isolation and the
+ * command file stays under the per-file LOC budget.
+ */
+/**
+ * Generates the .mjs file content for a custom component.
+ *
+ * `MozLitElement` does NOT expose `insertFTLIfNeeded` — that method lives on
+ * `MozXULElement`. Calling it from `connectedCallback` on a Lit-based
+ * component throws `TypeError: this.insertFTLIfNeeded is not a function` at
+ * every connect. Upstream Firefox components (e.g. `moz-input-folder.mjs`)
+ * solve this with a module-level guarded call on `window.MozXULElement` and
+ * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
+ * that pattern here so `--localized` produces functional code.
+ *
+ * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
+ * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
+ * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
+ * widgets ship.
+ */
+export declare function generateMjsContent(name: string, className: string, description: string, localized: boolean, header: string, ftlChromeSubPath: string | undefined): string;
+/** Generates the .css file content for a custom component. */
+export declare function generateCssContent(header: string): string;
+/** Generates the .ftl file content for a custom component. */
+export declare function generateFtlContent(name: string, header: string): string;

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

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * File-content templates for `fireforge furnace create`. Extracted from the
+ * command entrypoint so the generator is unit-testable in isolation and the
+ * command file stays under the per-file LOC budget.
+ */
+/**
+ * Generates the .mjs file content for a custom component.
+ *
+ * `MozLitElement` does NOT expose `insertFTLIfNeeded` — that method lives on
+ * `MozXULElement`. Calling it from `connectedCallback` on a Lit-based
+ * component throws `TypeError: this.insertFTLIfNeeded is not a function` at
+ * every connect. Upstream Firefox components (e.g. `moz-input-folder.mjs`)
+ * solve this with a module-level guarded call on `window.MozXULElement` and
+ * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
+ * that pattern here so `--localized` produces functional code.
+ *
+ * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
+ * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
+ * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
+ * widgets ship.
+ */
+export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath) {
+    const ftlPath = ftlChromeSubPath !== undefined ? `${ftlChromeSubPath}/${name}.ftl` : `${name}.ftl`;
+    const ftlModulePreamble = localized
+        ? `
+window.MozXULElement?.insertFTLIfNeeded("${ftlPath}");
+`
+        : '';
+    const lifecycleHooks = localized
+        ? `
+  connectedCallback() {
+    super.connectedCallback();
+    this.ownerDocument.l10n?.connectRoot(this.shadowRoot);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.ownerDocument.l10n?.disconnectRoot(this.shadowRoot);
+  }
+`
+        : '';
+    return `${header}
+
+import { html } from "chrome://global/content/vendor/lit.all.mjs";
+import { MozLitElement } from "chrome://global/content/lit-utils.mjs";
+${ftlModulePreamble}
+/**
+ * ${description || name}
+ *
+ * @tagname ${name}
+ */
+class ${className} extends MozLitElement {
+  static properties = {};
+
+  constructor() {
+    super();
+  }
+${lifecycleHooks}
+  render() {
+    return html\`
+      <link rel="stylesheet" href="chrome://global/content/elements/${name}.css" />
+      <slot></slot>
+    \`;
+  }
+}
+customElements.define("${name}", ${className});
+`;
+}
+/** Generates the .css file content for a custom component. */
+export function generateCssContent(header) {
+    return `${header}
+
+:host {
+  display: block;
+}
+`;
+}
+/** Generates the .ftl file content for a custom component. */
+export function generateFtlContent(name, header) {
+    return `${header}
+
+## Strings for the ${name} component
+`;
+}
+//# sourceMappingURL=create-templates.js.map

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

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { multiselect, text } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { createDefaultFurnaceConfig, detectComposesCycles, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { tagNameToClassName } from '../../core/furnace-constants.js';
+import { resolveFtlChromeSubPath, tagNameToClassName } from '../../core/furnace-constants.js';
 import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -15,6 +15,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
+import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
 async function loadAuthoringFurnaceConfig(projectRoot) {
     if (await furnaceConfigExists(projectRoot)) {
         return loadFurnaceConfig(projectRoot);
@@ -46,65 +47,6 @@ function checkNameConflict(config, name) {
     }
     return undefined;
 }
-/**
- * Generates the .mjs file content for a custom component.
- */
-function generateMjsContent(name, className, description, localized, header) {
-    const connectedCallback = localized
-        ? `
-  connectedCallback() {
-    super.connectedCallback();
-    this.insertFTLIfNeeded("${name}.ftl");
-  }
-`
-        : '';
-    return `${header}
-
-import { html } from "chrome://global/content/vendor/lit.all.mjs";
-import { MozLitElement } from "chrome://global/content/lit-utils.mjs";
-
-/**
- * ${description || name}
- *
- * @tagname ${name}
- */
-class ${className} extends MozLitElement {
-  static properties = {};
-
-  constructor() {
-    super();
-  }
-${connectedCallback}
-  render() {
-    return html\`
-      <link rel="stylesheet" href="chrome://global/content/elements/${name}.css" />
-      <slot></slot>
-    \`;
-  }
-}
-customElements.define("${name}", ${className});
-`;
-}
-/**
- * Generates the .css file content for a custom component.
- */
-function generateCssContent(header) {
-    return `${header}
-
-:host {
-  display: block;
-}
-`;
-}
-/**
- * Generates the .ftl file content for a custom component.
- */
-function generateFtlContent(name, header) {
-    return `${header}
-
-## Strings for the ${name} component
-`;
-}
 /**
  * Scaffolds browser mochitest files for a newly created custom component.
  * @param componentName - Custom element tag name
@@ -134,7 +76,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)
@@ -254,13 +200,13 @@ async function resolveCreateFeatures(isInteractive, options) {
  * @param journal - Optional rollback journal that snapshots files before writes
  * @returns Relative filenames written for the component
  */
-async function writeComponentFiles(componentDir, componentName, className, description, localized, license, journal) {
+async function writeComponentFiles(componentDir, componentName, className, description, localized, license, ftlChromeSubPath, journal) {
     await ensureDir(componentDir);
     const files = [`${componentName}.mjs`, `${componentName}.css`];
     const mjsPath = join(componentDir, `${componentName}.mjs`);
     if (journal)
         await snapshotFile(journal, mjsPath);
-    const mjsContent = generateMjsContent(componentName, className, description, localized, getLicenseHeader(license, 'js'));
+    const mjsContent = generateMjsContent(componentName, className, description, localized, getLicenseHeader(license, 'js'), ftlChromeSubPath);
     await writeText(mjsPath, mjsContent);
     const cssPath = join(componentDir, `${componentName}.css`);
     if (journal)
@@ -284,15 +230,22 @@ 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 {
-        files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, journal);
+        // 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, args.ftlChromeSubPath, journal);
         const customEntry = {
             description: args.description,
             targetPath: `toolkit/content/widgets/${args.componentName}`,
@@ -322,6 +275,58 @@ async function performCreateMutations(args) {
     }
     return { files, testFiles };
 }
+/**
+ * Prompts the operator for a description when the command is interactive and
+ * the operator did not pass `-d`. Returns the resolved description string.
+ */
+async function resolveDescription(isInteractive, options) {
+    let description = options.description ?? '';
+    if (!description && isInteractive) {
+        const descResult = await text({
+            message: 'Description (optional):',
+            placeholder: 'A brief description of the component',
+        });
+        if (!isCancel(descResult)) {
+            description = String(descResult);
+        }
+    }
+    return description;
+}
+/**
+ * Validates the `--compose` targets against registered components and runs
+ * cycle detection if the new component is introduced into the graph. Throws
+ * on any failure; returns when the graph is clean.
+ */
+function validateComposesTargets(config, componentName, composes) {
+    if (!composes || composes.length === 0)
+        return;
+    const known = new Set([
+        ...config.stock,
+        ...Object.keys(config.overrides),
+        ...Object.keys(config.custom),
+    ]);
+    for (const tag of composes) {
+        if (tag === componentName) {
+            throw new FurnaceError(`Component "${componentName}" cannot compose itself.`);
+        }
+        if (!known.has(tag)) {
+            throw new FurnaceError(`Cannot compose unknown component "${tag}". ` +
+                'The referenced component must be registered as stock, override, or custom.');
+        }
+    }
+    // Check for cycles that would be introduced by adding this component.
+    const tempCustom = {
+        ...config.custom,
+        [componentName]: {
+            description: '',
+            targetPath: `toolkit/content/widgets/${componentName}`,
+            register: true,
+            localized: false,
+            composes,
+        },
+    };
+    detectComposesCycles(tempCustom);
+}
 /**
  * Runs the furnace create command to scaffold a new custom component.
  * @param projectRoot - Root directory of the project
@@ -383,16 +388,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         warn(`Name "${componentName}" does not start with the configured prefix "${config.componentPrefix}".`);
     }
     // --- Resolve description ---
-    let description = options.description ?? '';
-    if (!description && isInteractive) {
-        const descResult = await text({
-            message: 'Description (optional):',
-            placeholder: 'A brief description of the component',
-        });
-        if (!isCancel(descResult)) {
-            description = String(descResult);
-        }
-    }
+    const description = await resolveDescription(isInteractive, options);
     // --- Resolve features ---
     const featureSelection = await resolveCreateFeatures(isInteractive, options);
     if (!featureSelection) {
@@ -417,39 +413,16 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // --- Validate --compose targets BEFORE any writes so a failed validation
     // does not strand component files behind.
     const composes = options.compose;
-    if (composes && composes.length > 0) {
-        const known = new Set([
-            ...config.stock,
-            ...Object.keys(config.overrides),
-            ...Object.keys(config.custom),
-        ]);
-        for (const tag of composes) {
-            if (tag === componentName) {
-                throw new FurnaceError(`Component "${componentName}" cannot compose itself.`);
-            }
-            if (!known.has(tag)) {
-                throw new FurnaceError(`Cannot compose unknown component "${tag}". ` +
-                    'The referenced component must be registered as stock, override, or custom.');
-            }
-        }
-        // Check for cycles that would be introduced by adding this component.
-        const tempCustom = {
-            ...config.custom,
-            [componentName]: {
-                description: '',
-                targetPath: `toolkit/content/widgets/${componentName}`,
-                register: true,
-                localized: false,
-                composes,
-            },
-        };
-        detectComposesCycles(tempCustom);
-    }
+    validateComposesTargets(config, componentName, composes);
     // All validation is done. Hand off to the transactional mutation helper
     // so any failure restores the workspace and engine to their pre-command
     // state via the shared rollback journal. The mutation runs under the
     // furnace-wide lock and is registered with the global SIGINT/SIGTERM
     // rollback pathway.
+    // Derive the FTL chrome sub-path from the configured ftlBasePath so the
+    // generated `.mjs` calls `insertFTLIfNeeded` at a URI that actually matches
+    // the locale jar.mn entry `furnace apply` will write.
+    const ftlChromeSubPath = resolveFtlChromeSubPath(config.ftlBasePath);
     const { files, testFiles } = await runFurnaceMutation(projectRoot, 'create-rollback', (ctx) => performCreateMutations({
         projectRoot,
         componentName,
@@ -465,6 +438,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         paths,
         license,
         withTests,
+        ftlChromeSubPath,
         operationContext: ctx,
     }));
     // --- Success ---

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,
@@ -147,7 +162,7 @@ async function restoreNamedDeployRollback(rollbackJournal, name, projectRoot) {
  * @param isDryRun - Whether file writes should be skipped
  * @returns Apply result for the named component, or `stock` for stock-only entries
  */
-async function applyNamedComponent(name, engineDir, furnacePaths, config, ftlDir, isDryRun, operationContext, projectRoot) {
+async function applyNamedComponent(name, engineDir, furnacePaths, config, ftlDir, isDryRun, operationContext, projectRoot, markerComment) {
     const rollbackJournal = isDryRun ? undefined : createRollbackJournal();
     if (rollbackJournal && operationContext) {
         operationContext.registerJournal(rollbackJournal);
@@ -186,7 +201,7 @@ async function applyNamedComponent(name, engineDir, furnacePaths, config, ftlDir
             throw new FurnaceError(`Component directory not found: components/custom/${name}`, name);
         }
         try {
-            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, isDryRun, rollbackJournal);
+            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, isDryRun, rollbackJournal, markerComment !== undefined ? { markerComment } : {});
             if (isDryRun && actions) {
                 result.actions = actions;
             }
@@ -302,7 +317,7 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     // `furnace deploy` runs only contend on the actual mutation.
     const applyOutcome = await runFurnaceMutation(projectRoot, 'deploy-rollback', async (ctx) => {
         if (name) {
-            const namedApplyResult = await applyNamedComponent(name, paths.engine, furnacePaths, config, ftlDir, isDryRun, ctx, projectRoot);
+            const namedApplyResult = await applyNamedComponent(name, paths.engine, furnacePaths, config, ftlDir, isDryRun, ctx, projectRoot, forgeConfig.markerComment);
             if (namedApplyResult === 'stock') {
                 return { kind: 'stock' };
             }