@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -3,13 +3,12 @@
  * MochiKit (chrome://mochikit) test-harness scaffolder for
  * `fireforge furnace create --test-style=mochikit`.
  *
- * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
- * the top-level chrome document. Forks with a bespoke chrome document
- * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
- * browser-chrome tests today. MochiKit tests load the component module
- * directly via `chrome://global/` and assert against `customElements`, so
- * they work against any fork that registers the upstream toolkit test
- * manifest tree — including those without a tabbrowser.
+ * Browser-chrome mochitests require a `tabbrowser` in the top-level chrome
+ * document, so forks with a bespoke chrome document that deliberately omits
+ * one cannot run them. MochiKit tests load the component module directly via
+ * `chrome://global/` and assert against `customElements`, so they work
+ * against any fork that registers the upstream toolkit test manifest tree —
+ * including those without a tabbrowser.
  */
 import { join } from 'node:path';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -41,8 +40,8 @@ export async function scaffoldMochikitTestFiles(componentName, license, paths, j
     const testFileName = mochikitTestFileName(componentName);
     const testFilePath = join(testDir, testFileName);
     if (await pathExists(testFilePath)) {
-        // Never clobber an existing test implementation (0.34.0 collision
-        // safety, matching the browser-chrome and xpcshell scaffolds).
+        // Never clobber an existing test implementation, matching the
+        // browser-chrome and xpcshell scaffolds.
         warn(`toolkit/content/tests/widgets/${testFileName} already exists — keeping the existing file.`);
     }
     else {

package/dist/src/commands/furnace/create-readback.d.ts

@@ -4,20 +4,19 @@
  * budget.
  */
 /**
- * Asserts that the just-written furnace.json contains the expected
- * custom component entry. The eval run's finding #9 observed a
- * scenario where `furnace create --allow-prefix-mismatch` reported
- * success and wrote the component files, but the subsequent
- * `furnace status` found `custom: {}` in furnace.json — an invariant
- * violation with no clear smoking gun in the code path. Local repros
- * do not trigger it, so the defensive readback is the safest recovery
- * contract we can offer: if the new entry is not visible on the next
- * load, throw a `FurnaceError` so the rollback journal restores the
- * pre-command state and the operator sees the failure instead of a
- * phantom success.
+ * Asserts that the just-written furnace.json contains the expected custom
+ * component entry.
+ *
+ * A `furnace create` that reports success and writes the component files
+ * while the next `furnace status` finds `custom: {}` is an invariant
+ * violation with no obvious smoking gun in the code path. This defensive
+ * readback is the recovery contract: if the new entry is not visible on the
+ * next load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a phantom
+ * success.
  *
  * @param projectRoot - Root of the FireForge project
- * @param componentName - Custom-element tag name that must be present
- *   in `config.custom` after the write. Throws when absent.
+ * @param componentName - Custom-element tag name that must be present in
+ *   `config.custom` after the write. Throws when absent.
  */
 export declare function assertCustomEntryPersisted(projectRoot: string, componentName: string): Promise<void>;

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

@@ -7,21 +7,20 @@
 import { loadFurnaceConfig } from '../../core/furnace-config.js';
 import { FurnaceError } from '../../errors/furnace.js';
 /**
- * Asserts that the just-written furnace.json contains the expected
- * custom component entry. The eval run's finding #9 observed a
- * scenario where `furnace create --allow-prefix-mismatch` reported
- * success and wrote the component files, but the subsequent
- * `furnace status` found `custom: {}` in furnace.json — an invariant
- * violation with no clear smoking gun in the code path. Local repros
- * do not trigger it, so the defensive readback is the safest recovery
- * contract we can offer: if the new entry is not visible on the next
- * load, throw a `FurnaceError` so the rollback journal restores the
- * pre-command state and the operator sees the failure instead of a
- * phantom success.
+ * Asserts that the just-written furnace.json contains the expected custom
+ * component entry.
+ *
+ * A `furnace create` that reports success and writes the component files
+ * while the next `furnace status` finds `custom: {}` is an invariant
+ * violation with no obvious smoking gun in the code path. This defensive
+ * readback is the recovery contract: if the new entry is not visible on the
+ * next load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a phantom
+ * success.
  *
  * @param projectRoot - Root of the FireForge project
- * @param componentName - Custom-element tag name that must be present
- *   in `config.custom` after the write. Throws when absent.
+ * @param componentName - Custom-element tag name that must be present in
+ *   `config.custom` after the write. Throws when absent.
  */
 export async function assertCustomEntryPersisted(projectRoot, componentName) {
     const persisted = await loadFurnaceConfig(projectRoot);

package/dist/src/commands/furnace/create-templates.d.ts

@@ -36,19 +36,18 @@ export declare function xpcshellTestFileName(name: string): string;
  * xpcshell cannot execute a component module that imports
  * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
  * `window` at module-load time and the xpcshell harness has no `window`
- * global. Before 0.16.0 the scaffold called `ChromeUtils.importESModule`
- * on the component's MJS, which reliably failed with
- * `ReferenceError: window is not defined` for every Lit-based fork
- * component. FireForge's diagnostics then misrouted the failure to the
- * "stale build artifacts" branch, sending operators on a rebuild loop
- * that couldn't fix a runtime-environment incompatibility.
+ * global. A scaffold that calls `ChromeUtils.importESModule` on the
+ * component's MJS therefore fails with `ReferenceError: window is not
+ * defined` for every Lit-based fork component, and FireForge's diagnostics
+ * misroute that to the "stale build artifacts" branch, sending operators on
+ * a rebuild loop that cannot fix a runtime-environment incompatibility.
  *
- * The rewrite here mirrors the chrome-doc packaging test: XCurProcD is
+ * This template mirrors the chrome-doc packaging test instead: XCurProcD is
  * probed at a pair of candidate layouts (dist/bin/browser and the macOS
- * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files
- * landed where jar.mn promised. That's the assertion xpcshell CAN make.
- * Functional tests that need DOM/shadow-root/keyboard behaviour belong
- * in a browser-chrome mochitest — scaffolded via
+ * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files landed
+ * where jar.mn promised. That is the assertion xpcshell CAN make. Functional
+ * tests that need DOM/shadow-root/keyboard behaviour belong in a
+ * browser-chrome mochitest — scaffolded via
  * `fireforge furnace create --test-style browser-chrome`.
  */
 export declare function generateXpcshellTestContent(name: string, header: string): string;
@@ -67,26 +66,21 @@ export declare function mochikitTestFileName(name: string): string;
  * MochiKit tests load the component module directly via the global chrome
  * URI and assert that `customElements.get(<tag>)` returns a constructor.
  * They run on forks whose top-level chrome document lacks a `tabbrowser`
- * (the class of bug that forces `--xpcshell` for storage code) because
- * they do not traverse `URILoadingHelper.openLinkIn`.
+ * because they do not traverse `URILoadingHelper.openLinkIn`.
  *
- * The scaffold here is a smoke test — the component is defined and the
- * constructor is a function. Real UI assertions (render output, l10n
- * wiring, keyboard interactions) are intentionally left out because they
- * depend on the component's shape; operators can extend the test using
- * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
- * rely on.
+ * The scaffold is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n wiring,
+ * keyboard interactions) are left out because they depend on the
+ * component's shape; operators can extend the test using the same SimpleTest
+ * APIs upstream toolkit widgets rely on.
  *
  * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
- * `add_task` owns the test lifecycle: when every queued task resolves,
- * the task harness calls `SimpleTest.finish()` on its own. Combining
- * `waitForExplicitFinish()` with `add_task` *and* no explicit
- * `SimpleTest.finish()` inside the task body makes the harness wait
- * forever, which the 2026-04-21 eval run tripped into as an indefinite
- * hang on a `fireforge test --headless` against a scaffolded widget
- * test. Leaving `waitForExplicitFinish()` out matches the convention
- * upstream toolkit widget tests use (see `test_moz-button.html` and
- * siblings under `toolkit/content/tests/widgets/`).
+ * `add_task` owns the test lifecycle: when every queued task resolves, the
+ * task harness calls `SimpleTest.finish()` itself. Combining
+ * `waitForExplicitFinish()` with `add_task` and no explicit
+ * `SimpleTest.finish()` in the task body makes the harness wait forever —
+ * an indefinite hang on `fireforge test --headless`. Omitting it matches the
+ * convention upstream toolkit widget tests use.
  */
 export declare function generateMochikitTestContent(name: string): string;
 /**

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

@@ -25,14 +25,25 @@
  *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
  */
 export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath, sharedFtl) {
+    // A `*/` in the operator-supplied description would close the JSDoc block
+    // early and leave the remainder as stray code. Escaped here rather than
+    // rejected at input, because the same text is also rendered by
+    // create-dry-run.ts, where no escaping is wanted.
+    const jsDocDescription = (description || name).replace(/\*\//g, '*\\/');
     const ftlPath = sharedFtl !== undefined
         ? sharedFtl
         : ftlChromeSubPath !== undefined
             ? `${ftlChromeSubPath}/${name}.ftl`
             : `${name}.ftl`;
+    // Escape at the SINK, not at the validator. `ftlPath` reaches here from
+    // three sources — the `--shared-ftl` flag, the furnace.json `ftlBasePath`,
+    // and a derived `<name>.ftl` — and only the first passes through
+    // `validateSharedFtl`. `JSON.stringify` produces a correctly-escaped JS
+    // string literal for all of them, including the `"` and raw-newline cases
+    // that would otherwise break the generated module into a syntax error.
     const ftlModulePreamble = localized
         ? `
-window.MozXULElement?.insertFTLIfNeeded("${ftlPath}");
+window.MozXULElement?.insertFTLIfNeeded(${JSON.stringify(ftlPath)});
 `
         : '';
     const lifecycleHooks = localized
@@ -60,7 +71,7 @@ import { html } from "chrome://global/content/vendor/lit.all.mjs";
 import { MozLitElement } from "chrome://global/content/lit-utils.mjs";
 ${ftlModulePreamble}
 /**
- * ${description || name}
+ * ${jsDocDescription}
  *
  * @tagname ${name}
  */
@@ -108,19 +119,18 @@ export function xpcshellTestFileName(name) {
  * xpcshell cannot execute a component module that imports
  * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
  * `window` at module-load time and the xpcshell harness has no `window`
- * global. Before 0.16.0 the scaffold called `ChromeUtils.importESModule`
- * on the component's MJS, which reliably failed with
- * `ReferenceError: window is not defined` for every Lit-based fork
- * component. FireForge's diagnostics then misrouted the failure to the
- * "stale build artifacts" branch, sending operators on a rebuild loop
- * that couldn't fix a runtime-environment incompatibility.
+ * global. A scaffold that calls `ChromeUtils.importESModule` on the
+ * component's MJS therefore fails with `ReferenceError: window is not
+ * defined` for every Lit-based fork component, and FireForge's diagnostics
+ * misroute that to the "stale build artifacts" branch, sending operators on
+ * a rebuild loop that cannot fix a runtime-environment incompatibility.
  *
- * The rewrite here mirrors the chrome-doc packaging test: XCurProcD is
+ * This template mirrors the chrome-doc packaging test instead: XCurProcD is
  * probed at a pair of candidate layouts (dist/bin/browser and the macOS
- * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files
- * landed where jar.mn promised. That's the assertion xpcshell CAN make.
- * Functional tests that need DOM/shadow-root/keyboard behaviour belong
- * in a browser-chrome mochitest — scaffolded via
+ * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files landed
+ * where jar.mn promised. That is the assertion xpcshell CAN make. Functional
+ * tests that need DOM/shadow-root/keyboard behaviour belong in a
+ * browser-chrome mochitest — scaffolded via
  * `fireforge furnace create --test-style browser-chrome`.
  */
 export function generateXpcshellTestContent(name, header) {
@@ -225,26 +235,21 @@ export function mochikitTestFileName(name) {
  * MochiKit tests load the component module directly via the global chrome
  * URI and assert that `customElements.get(<tag>)` returns a constructor.
  * They run on forks whose top-level chrome document lacks a `tabbrowser`
- * (the class of bug that forces `--xpcshell` for storage code) because
- * they do not traverse `URILoadingHelper.openLinkIn`.
+ * because they do not traverse `URILoadingHelper.openLinkIn`.
  *
- * The scaffold here is a smoke test — the component is defined and the
- * constructor is a function. Real UI assertions (render output, l10n
- * wiring, keyboard interactions) are intentionally left out because they
- * depend on the component's shape; operators can extend the test using
- * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
- * rely on.
+ * The scaffold is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n wiring,
+ * keyboard interactions) are left out because they depend on the
+ * component's shape; operators can extend the test using the same SimpleTest
+ * APIs upstream toolkit widgets rely on.
  *
  * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
- * `add_task` owns the test lifecycle: when every queued task resolves,
- * the task harness calls `SimpleTest.finish()` on its own. Combining
- * `waitForExplicitFinish()` with `add_task` *and* no explicit
- * `SimpleTest.finish()` inside the task body makes the harness wait
- * forever, which the 2026-04-21 eval run tripped into as an indefinite
- * hang on a `fireforge test --headless` against a scaffolded widget
- * test. Leaving `waitForExplicitFinish()` out matches the convention
- * upstream toolkit widget tests use (see `test_moz-button.html` and
- * siblings under `toolkit/content/tests/widgets/`).
+ * `add_task` owns the test lifecycle: when every queued task resolves, the
+ * task harness calls `SimpleTest.finish()` itself. Combining
+ * `waitForExplicitFinish()` with `add_task` and no explicit
+ * `SimpleTest.finish()` in the task body makes the harness wait forever —
+ * an indefinite hang on `fireforge test --headless`. Omitting it matches the
+ * convention upstream toolkit widget tests use.
  */
 export function generateMochikitTestContent(name) {
     return `<!DOCTYPE html>

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

@@ -43,8 +43,8 @@ export async function scaffoldXpcshellTestFiles(componentName, license, forgeCon
     const testFileName = xpcshellTestFileName(componentName);
     const testFilePath = join(testDir, testFileName);
     if (await pathExists(testFilePath)) {
-        // Never clobber an existing test implementation (0.34.0 field report:
-        // the scaffold overwrote files owned by a different patch).
+        // Never clobber an existing test implementation: the scaffold must not
+        // overwrite files owned by a different patch.
         warn(`${testDirRel}/${testFileName} already exists — keeping the existing file.`);
     }
     else {

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

@@ -2,17 +2,17 @@
 import { join } from 'node:path';
 import { text } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { stdioIsInteractive } from '../../core/destructive.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.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';
+import { resolveFtlChromeSubPath, tagNameToClassName, WIDGETS_DIR, } from '../../core/furnace-constants.js';
+import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, describeTagNameProblem, } from '../../core/furnace-registration-validate.js';
+import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { isComponentInEngine, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { validateSharedFtl } from '../../core/shared-ftl.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro } from '../../utils/logger.js';
 import { resolveValidatedTestDir, scaffoldTestFiles } from './create-browser-test.js';
@@ -70,6 +70,8 @@ function validateTagName(name) {
  * @param description - Human-readable component description
  * @param localized - Whether to include a Fluent file
  * @param license - Project license used for generated headers
+ * @param ftlChromeSubPath - chrome:// sub-path for the generated FTL reference, when localized
+ * @param sharedFtl - Explicit shared FTL path from `--shared-ftl`, when supplied
  * @param journal - Optional rollback journal that snapshots files before writes
  * @returns Relative filenames written for the component
  */
@@ -166,7 +168,7 @@ async function performCreateMutations(args) {
         files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, resolveFtlChromeSubPath(freshConfig.ftlBasePath), args.sharedFtl, journal);
         const customEntry = {
             description: args.description,
-            targetPath: `toolkit/content/widgets/${args.componentName}`,
+            targetPath: `${WIDGETS_DIR}/${args.componentName}`,
             register: args.register,
             localized: args.localized,
         };
@@ -199,15 +201,16 @@ async function performCreateMutations(args) {
         }
     }
     catch (error) {
-        // This body owns its rollback end to end, so tell the lifecycle wrapper
-        // not to restore the same journal again on the way out.
-        args.operationContext?.markRolledBack();
-        try {
-            await restoreRollbackJournalOrThrow(journal, `Failed to create custom component "${args.componentName}"`);
-        }
-        catch (rollbackError) {
-            await recordFurnaceRollbackFailure(args.projectRoot, 'create-rollback', `component "${args.componentName}": ${toError(rollbackError).message}`);
-            throw rollbackError;
+        // `operationContext` is optional here (the dry-run and no-journal paths
+        // pass none), so the shared handler only applies when there is a
+        // lifecycle wrapper to tell.
+        if (args.operationContext) {
+            return await completeJournalRollback(args.operationContext, journal, error, {
+                projectRoot: args.projectRoot,
+                operation: 'create-rollback',
+                failureMessage: `Failed to create custom component "${args.componentName}"`,
+                subject: `component "${args.componentName}"`,
+            });
         }
         throw error;
     }
@@ -237,7 +240,7 @@ async function resolveDescription(isInteractive, options) {
  * @param options - CLI options for non-interactive mode
  */
 export async function furnaceCreateCommand(projectRoot, name, options = {}) {
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     const isDryRun = options.dryRun ?? false;
     intro(isDryRun ? 'Furnace Create (dry run)' : 'Furnace Create');
     // --- Resolve component name ---
@@ -264,7 +267,9 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         const nameResult = await text({
             message: 'Component tag name:',
             placeholder: 'moz-my-widget',
-            validate: (value) => validateTagName(value ?? ''),
+            // Message-returning form: the throwing `validateTagName` escaped
+            // clack's validation loop and killed the prompt on a bad name.
+            validate: (value) => describeTagNameProblem(value ?? ''),
         });
         if (isCancel(nameResult)) {
             cancel('Create cancelled');
@@ -304,6 +309,11 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // partial mutation behind.
     const testStyle = resolveTestStyle(options);
     const testDir = resolveValidatedTestDir(options.testDir, testStyle);
+    // Not routed through assertFurnaceEngineReady: this rung is CONDITIONAL on
+    // a test style being requested, and it names the component so the refusal
+    // identifies which create failed. Both are outside the shared helper's
+    // shape, and a scaffold without --with-tests must keep working with no
+    // engine present.
     if (testStyle !== 'none' && !(await pathExists(paths.engine))) {
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests, --xpcshell, or --test-style.', componentName);
     }
@@ -314,13 +324,13 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     if (await pathExists(componentDir)) {
         throw new FurnaceError(`Directory already exists: components/custom/${componentName}`, componentName);
     }
-    // --- Normalize and validate --shared-ftl ahead of any writes. Shares the
+    // Normalize and validate --shared-ftl ahead of any writes. Shares the
     // structural rules with furnace-config.ts so the command and the on-disk
-    // schema cannot diverge. Pass the resolved `localized` rather than a
-    // `true` literal so the validator's cross-field check stays anchored to
-    // the real feature selection — `resolveCreateFeatures` promotes localized
-    // upstream, but hard-coding `true` here would hide a regression if that
-    // promotion ever moved or dropped.
+    // schema cannot diverge. Pass the resolved `localized` rather than a `true`
+    // literal so the validator's cross-field check stays anchored to the real
+    // feature selection — `resolveCreateFeatures` promotes localized upstream,
+    // and hard-coding `true` here would hide a regression if that promotion
+    // ever moved or dropped.
     let sharedFtl;
     if (options.sharedFtl !== undefined) {
         const result = validateSharedFtl(options.sharedFtl, { localized });

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

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { loadConfig } from '../../core/config.js';
 import { applyAllComponents } from '../../core/furnace-apply.js';
 import { logApplyResult } from '../../core/furnace-apply-output.js';
-import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, } from '../../core/furnace-config.js';
+import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
 import { reportJsconfigPathsSync } from '../../core/furnace-jsconfig.js';
 import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { getPersistableAppliedEntry, getStepFailureCount, persistSingleComponentState, shouldPersistSingleComponentState, } from '../../core/furnace-state-persist.js';
 import { hasBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftError, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { pathExists } from '../../utils/fs.js';
 import { info, intro, note, outro, spinner, warn } from '../../utils/logger.js';
 import { runDeployValidation } from './validation-output.js';
 /**
@@ -39,28 +39,29 @@ function getFailedComponentNames(result) {
     return failed;
 }
 /**
- * Applies a single named override or custom component in targeted deploy mode.
+ * Applies a single named override or custom component in targeted deploy
+ * mode.
  *
  * Delegates to {@link applyAllComponents} with a `componentName` filter so
  * targeted deploys run the exact same pipeline as deploy-all — including
  * workspace-deletion detection, engine orphan undeploy, and jar.mn /
- * customElements.js re-sync. The previous implementation called the
- * per-component apply helpers directly and never pruned: renaming a helper
- * file in the workspace left the old deployed file and its stale jar.mn
- * line in the engine (field report D1).
+ * customElements.js re-sync. Calling the per-component apply helpers
+ * directly never prunes: renaming a helper file in the workspace then leaves
+ * the old deployed file and its stale jar.mn line in the engine.
  *
  * `persistState: false` is load-bearing: the batch persist path *replaces*
  * `appliedChecksums` wholesale with only this run's entries, which for a
  * named deploy would wipe every other component's state. Named deploy keeps
  * its per-component state merge ({@link persistSingleComponentState}) and
- * its atomicity gate ({@link shouldPersistNamedDeployState}) at the call
- * site. Rollback on failure happens inside `applyAllComponents`; the
- * journal returned on success is ignored (the deploy keeps its files).
+ * its atomicity gate ({@link shouldPersistSingleComponentState}) at the call
+ * site. Rollback on failure happens inside `applyAllComponents`; the journal
+ * returned on success is ignored (the deploy keeps its files).
  *
  * @param name - Component name to apply
  * @param config - Loaded Furnace configuration
  * @param isDryRun - Whether file writes should be skipped
- * @returns Apply result for the named component, or `stock` for stock-only entries
+ * @returns Apply result for the named component, or `stock` for stock-only
+ *   entries
  */
 async function applyNamedComponent(name, config, isDryRun, projectRoot, operationContext) {
     if (!(name in config.overrides) && !(name in config.custom)) {
@@ -132,16 +133,7 @@ function enforceScopedOverrideVersionDriftPreflight(scopedDrift, force) {
 export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     const isDryRun = options.dryRun ?? false;
     intro(isDryRun ? 'Furnace Deploy (dry run)' : 'Furnace Deploy');
-    // Verify engine exists
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
-    // Load furnace config
-    if (!(await furnaceConfigExists(projectRoot))) {
-        throw new FurnaceError('No furnace.json found. Run "fireforge furnace create" or "fireforge furnace override" to get started.');
-    }
-    const config = await loadFurnaceConfig(projectRoot);
+    const { config } = await assertFurnaceReady(projectRoot);
     const furnacePaths = getFurnacePaths(projectRoot);
     const overrideCount = Object.keys(config.overrides).length;
     const customCount = Object.keys(config.custom).length;
@@ -196,8 +188,8 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     applySpinner.stop(isDryRun ? 'Planned actions calculated' : 'Components applied');
     logApplyResult(result, isDryRun);
     // Keep the consumer jsconfig's chrome-module `paths` in step with the
-    // deployed module set (field report D3). Only after a clean apply —
-    // a rolled-back deploy must not advance the typecheck mapping either.
+    // deployed module set. Only after a clean apply — a rolled-back deploy
+    // must not advance the typecheck mapping either.
     if (result.errors.length === 0 && getStepFailureCount(result) === 0) {
         await reportJsconfigPathsSync(projectRoot, config, isDryRun);
     }

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

@@ -99,16 +99,16 @@ async function diffOverride(name, projectRoot, config) {
     }
 }
 /**
- * Diffs a custom component's workspace files against the engine-deployed copy.
- * Shows what would change (or has changed) on the next `furnace apply`.
+ * Diffs a custom component's workspace files against the engine-deployed
+ * copy. Shows what would change (or has changed) on the next
+ * `furnace apply`.
  *
- * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via `applyCustomFtlFile`
- * — NOT to `customConfig.targetPath` — so the deployment-target lookup has
- * to branch on extension. Before this branch existed, a component's
- * localization file always reported "not yet deployed to engine (new
- * file)" after a successful apply/deploy because diff was looking for it
- * under the component's `targetPath` while apply had written it into the
- * locale tree.
+ * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via
+ * `applyCustomFtlFile` — NOT to `customConfig.targetPath` — so the
+ * deployment-target lookup has to branch on extension. Without the branch, a
+ * component's localization file always reports "not yet deployed to engine
+ * (new file)" after a successful apply, because diff looks for it under the
+ * component's `targetPath` while apply wrote it into the locale tree.
  */
 async function diffCustom(name, projectRoot, config) {
     const customConfig = config.custom[name];