@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -3,10 +3,26 @@
  * command entrypoint so the generator is unit-testable in isolation and the
  * command file stays under the per-file LOC budget.
  */
+export interface GenerateMjsContentOptions {
+    /** Custom element tag name. */
+    name: string;
+    /** Generated component class name. */
+    className: string;
+    /** Human-readable component description. */
+    description: string;
+    /** Whether to emit the Fluent wiring. */
+    localized: boolean;
+    /** License header prepended to the module. */
+    header: string;
+    /** chrome:// sub-path for the generated FTL reference, when localized. */
+    ftlChromeSubPath: string | undefined;
+    /** Explicit shared FTL path, used verbatim when supplied. */
+    sharedFtl: string | undefined;
+}
 /**
  * Generates the .mjs file content for a custom component.
  *
- * `MozLitElement` does NOT expose `insertFTLIfNeeded` — that method lives on
+ * `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`)
@@ -15,15 +31,15 @@
  * that pattern here so `--localized` produces functional code.
  *
  * Path resolution precedence (when `localized` is true):
- *   1. `sharedFtl` — used verbatim. The caller has resolved it from
- *      `--shared-ftl` / `furnace.json`; this template does no rewriting.
+ *   1. `sharedFtl`: used verbatim. The caller has resolved it from
+ *      `--shared-ftl` / `furnace.json`. This template does no rewriting.
  *      Use this when the component participates in a feature-scoped
  *      bundle that another component owns.
- *   2. `<ftlChromeSubPath>/<name>.ftl` — the default per-component path,
+ *   2. `<ftlChromeSubPath>/<name>.ftl`: the default per-component path,
  *      matching the locale jar.mn entry that `furnace apply` writes.
- *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
+ *   3. `<name>.ftl`: fallback when no chrome sub-path was resolvable.
  */
-export declare function generateMjsContent(name: string, className: string, description: string, localized: boolean, header: string, ftlChromeSubPath: string | undefined, sharedFtl: string | undefined): string;
+export declare function generateMjsContent(options: GenerateMjsContentOptions): 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. */
@@ -34,7 +50,7 @@ export declare function xpcshellTestFileName(name: string): string;
  * Generates an xpcshell test file for a custom component.
  *
  * xpcshell cannot execute a component module that imports
- * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
+ * `chrome://global/content/vendor/lit.all.mjs`: the Lit bundle touches
  * `window` at module-load time and the xpcshell harness has no `window`
  * global. A scaffold that calls `ChromeUtils.importESModule` on the
  * component's MJS therefore fails with `ReferenceError: window is not
@@ -45,15 +61,15 @@ export declare function xpcshellTestFileName(name: string): string;
  * 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 is the assertion xpcshell CAN make. Functional
+ * 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
+ * browser-chrome mochitest, scaffolded via
  * `fireforge furnace create --test-style browser-chrome`.
  */
 export declare function generateXpcshellTestContent(name: string, header: string): string;
 /**
  * Generates an `xpcshell.toml` manifest for a custom component's test
- * directory. Kept minimal — adding prefs, head.js, and support-files is
+ * directory. Kept minimal: adding prefs, head.js, and support-files is
  * left to the operator because those decisions depend on what the
  * component actually touches (Services.storage, observer topics, etc.).
  */
@@ -68,17 +84,17 @@ export declare function mochikitTestFileName(name: string): string;
  * They run on forks whose top-level chrome document lacks a `tabbrowser`
  * because they do not traverse `URILoadingHelper.openLinkIn`.
  *
- * The scaffold is a smoke test — the component is defined and the
+ * 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
+ * component's shape. Operators can extend the test using the same SimpleTest
  * APIs upstream toolkit widgets rely on.
  *
- * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
+ * The template omits `SimpleTest.waitForExplicitFinish()` on purpose.
  * `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 —
+ * `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.
  */
@@ -86,7 +102,7 @@ export declare function generateMochikitTestContent(name: string): string;
 /**
  * Generates the `chrome.toml` entry block to append for a newly scaffolded
  * mochikit test. When the manifest already exists the caller appends this
- * snippet; when absent, the caller writes a file that starts with a
+ * snippet. When it is absent, the caller writes a file that starts with a
  * `[DEFAULT]` stanza followed by this block.
  */
 export declare function generateMochikitChromeTomlEntry(name: string): string;

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

@@ -7,7 +7,7 @@
 /**
  * Generates the .mjs file content for a custom component.
  *
- * `MozLitElement` does NOT expose `insertFTLIfNeeded` — that method lives on
+ * `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`)
@@ -16,15 +16,16 @@
  * that pattern here so `--localized` produces functional code.
  *
  * Path resolution precedence (when `localized` is true):
- *   1. `sharedFtl` — used verbatim. The caller has resolved it from
- *      `--shared-ftl` / `furnace.json`; this template does no rewriting.
+ *   1. `sharedFtl`: used verbatim. The caller has resolved it from
+ *      `--shared-ftl` / `furnace.json`. This template does no rewriting.
  *      Use this when the component participates in a feature-scoped
  *      bundle that another component owns.
- *   2. `<ftlChromeSubPath>/<name>.ftl` — the default per-component path,
+ *   2. `<ftlChromeSubPath>/<name>.ftl`: the default per-component path,
  *      matching the locale jar.mn entry that `furnace apply` writes.
- *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
+ *   3. `<name>.ftl`: fallback when no chrome sub-path was resolvable.
  */
-export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath, sharedFtl) {
+export function generateMjsContent(options) {
+    const { name, className, description, localized, header, ftlChromeSubPath, sharedFtl } = options;
     // 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
@@ -35,10 +36,10 @@ export function generateMjsContent(name, className, description, localized, head
         : 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
+    // Escaping happens at the sink rather than 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
@@ -117,7 +118,7 @@ export function xpcshellTestFileName(name) {
  * Generates an xpcshell test file for a custom component.
  *
  * xpcshell cannot execute a component module that imports
- * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
+ * `chrome://global/content/vendor/lit.all.mjs`: the Lit bundle touches
  * `window` at module-load time and the xpcshell harness has no `window`
  * global. A scaffold that calls `ChromeUtils.importESModule` on the
  * component's MJS therefore fails with `ReferenceError: window is not
@@ -128,9 +129,9 @@ export function xpcshellTestFileName(name) {
  * 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 is the assertion xpcshell CAN make. Functional
+ * 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
+ * browser-chrome mochitest, scaffolded via
  * `fireforge furnace create --test-style browser-chrome`.
  */
 export function generateXpcshellTestContent(name, header) {
@@ -212,7 +213,7 @@ add_task(async function test_${taskSuffix}_files_packaged() {
 }
 /**
  * Generates an `xpcshell.toml` manifest for a custom component's test
- * directory. Kept minimal — adding prefs, head.js, and support-files is
+ * directory. Kept minimal: adding prefs, head.js, and support-files is
  * left to the operator because those decisions depend on what the
  * component actually touches (Services.storage, observer topics, etc.).
  */
@@ -237,17 +238,17 @@ export function mochikitTestFileName(name) {
  * They run on forks whose top-level chrome document lacks a `tabbrowser`
  * because they do not traverse `URILoadingHelper.openLinkIn`.
  *
- * The scaffold is a smoke test — the component is defined and the
+ * 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
+ * component's shape. Operators can extend the test using the same SimpleTest
  * APIs upstream toolkit widgets rely on.
  *
- * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
+ * The template omits `SimpleTest.waitForExplicitFinish()` on purpose.
  * `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 —
+ * `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.
  */
@@ -280,7 +281,7 @@ export function generateMochikitTestContent(name) {
 /**
  * Generates the `chrome.toml` entry block to append for a newly scaffolded
  * mochikit test. When the manifest already exists the caller appends this
- * snippet; when absent, the caller writes a file that starts with a
+ * snippet. When it is absent, the caller writes a file that starts with a
  * `[DEFAULT]` stanza followed by this block.
  */
 export function generateMochikitChromeTomlEntry(name) {

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

@@ -10,15 +10,15 @@ import type { ProjectLicense } from '../../types/config.js';
  *
  * xpcshell is the appropriate harness for storage-layer code on forks
  * without a `tabbrowser` (no `openLinkIn` → `URILoadingHelper`). Browser
- * chrome mochitests require tabbrowser; xpcshell does not, so storage,
+ * chrome mochitests require tabbrowser, but xpcshell does not, so storage,
  * observers, and ESM-loading logic can be covered headless.
  *
  * Writes `test_<name>_packaged.js` and an `xpcshell.toml` manifest
  * into `engine/browser/base/content/test/<binary-name>-xpcshell/
- * <component-name>/`. moz.build registration is intentionally left to the
- * operator — wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a
- * deliberate choice about which moz.build should own it, and an
- * auto-insertion that guessed wrong would be worse than a note.
+ * <component-name>/`. moz.build registration is left to the operator:
+ * wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a choice about which
+ * moz.build should own it, and an auto-insertion that guessed wrong would
+ * be worse than a note.
  */
 export declare function scaffoldXpcshellTestFiles(componentName: string, license: ProjectLicense, forgeConfig: {
     binaryName: string;

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

@@ -16,20 +16,20 @@ import { generateXpcshellManifestContent, generateXpcshellTestContent, xpcshellT
  *
  * xpcshell is the appropriate harness for storage-layer code on forks
  * without a `tabbrowser` (no `openLinkIn` → `URILoadingHelper`). Browser
- * chrome mochitests require tabbrowser; xpcshell does not, so storage,
+ * chrome mochitests require tabbrowser, but xpcshell does not, so storage,
  * observers, and ESM-loading logic can be covered headless.
  *
  * Writes `test_<name>_packaged.js` and an `xpcshell.toml` manifest
  * into `engine/browser/base/content/test/<binary-name>-xpcshell/
- * <component-name>/`. moz.build registration is intentionally left to the
- * operator — wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a
- * deliberate choice about which moz.build should own it, and an
- * auto-insertion that guessed wrong would be worse than a note.
+ * <component-name>/`. moz.build registration is left to the operator:
+ * wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a choice about which
+ * moz.build should own it, and an auto-insertion that guessed wrong would
+ * be worse than a note.
  */
 export async function scaffoldXpcshellTestFiles(componentName, license, forgeConfig, paths, journal, testDirOverride) {
     const parentRelDir = xpcshellTestParentDir(forgeConfig.binaryName);
     const parentDirName = parentRelDir.split('/').slice(-1)[0] ?? `${forgeConfig.binaryName}-xpcshell`;
-    // --test-dir names the FINAL directory (no per-component segment is
+    // --test-dir names the final directory (no per-component segment is
     // appended) so the operator controls the exact scaffold target.
     const testDirRel = resolveXpcshellTestDir(forgeConfig.binaryName, componentName, testDirOverride);
     const testDir = join(paths.engine, testDirRel);
@@ -53,8 +53,8 @@ export async function scaffoldXpcshellTestFiles(componentName, license, forgeCon
         await writeText(testFilePath, generateXpcshellTestContent(componentName, jsHeader));
         testFiles.push(testFileName);
     }
-    // xpcshell.toml — append the test entry to an existing manifest instead
-    // of scaffolding over it; write a fresh one only when absent.
+    // xpcshell.toml: append the test entry to an existing manifest instead
+    // of scaffolding over it. Write a fresh one only when absent.
     const manifestPath = join(testDir, 'xpcshell.toml');
     if (await pathExists(manifestPath)) {
         const existing = await readText(manifestPath);

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

@@ -7,7 +7,7 @@ import type { ResolvedTestStyle } from '../../types/furnace.js';
  * Invariants:
  * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
  * - `--with-tests` alone (no `--test-style`) defaults to `browser-chrome`
- *   (multi-process mochitest; reliable on macOS for interactive chrome).
+ *   (multi-process mochitest, reliable on macOS for interactive chrome).
  *   Forks whose chrome document has no `tabbrowser` should pass
  *   `--test-style=mochikit` explicitly.
  * - When both `--xpcshell` and `--with-tests` are set, `--xpcshell` wins

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

@@ -3,7 +3,7 @@ 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 { getFurnacePaths, writeFurnaceConfig } from '../../core/furnace-config.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';
@@ -15,6 +15,7 @@ import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro } from '../../utils/logger.js';
+import { loadAuthoringFurnaceConfig } from './authoring-config.js';
 import { resolveValidatedTestDir, scaffoldTestFiles } from './create-browser-test.js';
 import { formatDryRunPlan, formatSuccessNote } from './create-dry-run.js';
 import { resolveCreateFeatures } from './create-features.js';
@@ -23,12 +24,6 @@ import { assertCustomEntryPersisted } from './create-readback.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
 import { validateCreateAgainstConfig } from './create-validation.js';
 import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
-async function loadAuthoringFurnaceConfig(projectRoot) {
-    if (await furnaceConfigExists(projectRoot)) {
-        return loadFurnaceConfig(projectRoot);
-    }
-    return createDefaultFurnaceConfig();
-}
 function knownComponentSet(config) {
     return new Set([
         ...config.stock,
@@ -64,24 +59,25 @@ function validateTagName(name) {
 }
 /**
  * Writes the scaffolded component source files to disk.
- * @param componentDir - Destination component directory
- * @param componentName - Custom element tag name
- * @param className - Generated component class 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
+ * @param options - See {@link WriteComponentFilesOptions}
  * @returns Relative filenames written for the component
  */
-async function writeComponentFiles(componentDir, componentName, className, description, localized, license, ftlChromeSubPath, sharedFtl, journal) {
+async function writeComponentFiles(options) {
+    const { componentDir, componentName, className, description, localized, license, ftlChromeSubPath, sharedFtl, journal, } = options;
     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'), ftlChromeSubPath, sharedFtl);
+    const mjsContent = generateMjsContent({
+        name: componentName,
+        className,
+        description,
+        localized,
+        header: getLicenseHeader(license, 'js'),
+        ftlChromeSubPath,
+        sharedFtl,
+    });
     await writeText(mjsPath, mjsContent);
     const cssPath = join(componentDir, `${componentName}.css`);
     if (journal)
@@ -90,7 +86,7 @@ async function writeComponentFiles(componentDir, componentName, className, descr
     await writeText(cssPath, cssContent);
     // Skip the per-component .ftl stub when the component participates in a
     // pre-existing feature-scoped bundle. The shared bundle is owned
-    // elsewhere; dropping a stub here would clutter the workspace with
+    // elsewhere. Dropping a stub here would clutter the workspace with
     // empty files that never get packaged (furnace apply also skips copying
     // them in this mode).
     if (localized && !sharedFtl) {
@@ -110,7 +106,7 @@ async function writeComponentFiles(componentDir, componentName, className, descr
  * Invariants:
  * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
  * - `--with-tests` alone (no `--test-style`) defaults to `browser-chrome`
- *   (multi-process mochitest; reliable on macOS for interactive chrome).
+ *   (multi-process mochitest, reliable on macOS for interactive chrome).
  *   Forks whose chrome document has no `tabbrowser` should pass
  *   `--test-style=mochikit` explicitly.
  * - When both `--xpcshell` and `--with-tests` are set, `--xpcshell` wins
@@ -139,8 +135,8 @@ export function resolveTestStyle(options) {
  * state.
  */
 async function performCreateMutations(args) {
-    // Invariant: the journal MUST be registered with the operation context
-    // BEFORE any filesystem mutation (including recordCreatedDir, whose entries
+    // 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();
@@ -165,7 +161,17 @@ async function performCreateMutations(args) {
         // 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, resolveFtlChromeSubPath(freshConfig.ftlBasePath), args.sharedFtl, journal);
+        files = await writeComponentFiles({
+            componentDir: args.componentDir,
+            componentName: args.componentName,
+            className: args.className,
+            description: args.description,
+            localized: args.localized,
+            license: args.license,
+            ftlChromeSubPath: resolveFtlChromeSubPath(freshConfig.ftlBasePath),
+            sharedFtl: args.sharedFtl,
+            journal,
+        });
         const customEntry = {
             description: args.description,
             targetPath: `${WIDGETS_DIR}/${args.componentName}`,
@@ -263,7 +269,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     const license = forgeConfig.license ?? DEFAULT_LICENSE;
     const furnacePaths = getFurnacePaths(projectRoot);
     if (!componentName) {
-        // Interactive prompt path; non-interactive missing-name was rejected above.
+        // Interactive prompt path. Non-interactive missing-name was rejected above.
         const nameResult = await text({
             message: 'Component tag name:',
             placeholder: 'moz-my-widget',
@@ -309,7 +315,7 @@ 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
+    // 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
@@ -328,7 +334,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // 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,
+    // feature selection. `resolveCreateFeatures` promotes localized upstream,
     // and hard-coding `true` here would hide a regression if that promotion
     // ever moved or dropped.
     let sharedFtl;
@@ -339,10 +345,10 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         }
         sharedFtl = result.value;
     }
-    // Dry-run exits here — every validation that does not need a write has
+    // Dry-run exits here. Every validation that does not need a write has
     // already run, so the plan we render reflects exactly what the real
     // command would do. The mutation phase and its rollback journal are
-    // intentionally skipped so no furnace.json/engine state is touched.
+    // skipped so no furnace.json/engine state is touched.
     if (isDryRun) {
         const plan = formatDryRunPlan({
             componentName,
@@ -351,7 +357,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
             composes,
             stockAdditions,
             // Spread rather than assign so the key is absent when sharedFtl is
-            // undefined — the DryRunPlanInput type uses strict-optional shape.
+            // undefined. The DryRunPlanInput type uses a strict-optional shape.
             ...(sharedFtl !== undefined ? { sharedFtl } : {}),
             testStyle,
             description,

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

@@ -2,7 +2,7 @@
 import { loadConfig } from '../../core/config.js';
 import { applyAllComponents } from '../../core/furnace-apply.js';
 import { logApplyResult } from '../../core/furnace-apply-output.js';
-import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
+import { getFurnacePaths } from '../../core/furnace-config.js';
 import { reportJsconfigPathsSync } from '../../core/furnace-jsconfig.js';
 import { runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceReady } from '../../core/furnace-precondition.js';
@@ -43,18 +43,18 @@ function getFailedComponentNames(result) {
  * mode.
  *
  * Delegates to {@link applyAllComponents} with a `componentName` filter so
- * targeted deploys run the exact same pipeline as deploy-all — including
+ * targeted deploys run the exact same pipeline as deploy-all, including
  * workspace-deletion detection, engine orphan undeploy, and jar.mn /
  * 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*
+ * `persistState: false` matters here: 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 shouldPersistSingleComponentState}) at the call
- * site. Rollback on failure happens inside `applyAllComponents`; the journal
+ * 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
@@ -188,7 +188,7 @@ 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. Only after a clean apply — a rolled-back deploy
+    // 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);
@@ -203,7 +203,16 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     }
     const validateSpinner = spinner(isDryRun ? 'Validating (read-only)...' : 'Validating...');
     const failedComponents = getFailedComponentNames(result);
-    const validation = await runDeployValidation(validateSpinner, name, config, furnacePaths, failedComponents, isDryRun, projectRoot, result.actions);
+    const validation = await runDeployValidation({
+        validateSpinner,
+        name,
+        config,
+        furnacePaths,
+        failedComponents,
+        isDryRun,
+        projectRoot,
+        dryRunActions: result.actions,
+    });
     if (validation.done)
         return;
     const { totalErrors, totalWarnings, componentCount, skippedValidationCount } = validation;

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

@@ -15,9 +15,9 @@ import { normalizePathSlashes } from '../../utils/paths.js';
 /**
  * Renders a multi-hunk unified diff between the two strings and returns a
  * flat list of display-ready lines. Each line has already had its marker
- * prefix and color applied by this function; the caller just emits them.
+ * prefix and color applied by this function. The caller just emits them.
  *
- * Pure delegation to the `diff-hunks` module — kept here as a thin wrapper
+ * Pure delegation to the `diff-hunks` module, kept here as a thin wrapper
  * so the command file does not need to care about the hunk data shape.
  */
 function formatUnifiedDiff(original, modified) {
@@ -48,7 +48,7 @@ async function diffOverride(name, projectRoot, config) {
     if (!(await pathExists(overrideDir))) {
         throw new FurnaceError(`Override directory not found: components/overrides/${name}`, name);
     }
-    // Prefer the per-override baseCommit (survives download --force); fall back
+    // Prefer the per-override baseCommit (survives download --force). Fall back
     // to the project-wide value for overrides created before this field existed.
     const state = await loadState(projectRoot);
     const baseCommit = overrideConfig.baseCommit ?? state.baseCommit;
@@ -64,9 +64,9 @@ async function diffOverride(name, projectRoot, config) {
             continue;
         if (!isComponentSourceFile(entry.name))
             continue;
-        // git show takes a repo-relative path. paths.engine IS the repo root.
+        // git show takes a repo-relative path. paths.engine is the repo root.
         // The slice leaves the host's separators behind, and `git show <ref>:<path>`
-        // only understands forward slashes — on Windows the unnormalized form makes
+        // only understands forward slashes. On Windows the unnormalized form makes
         // every baseline read miss, so every overridden file is reported as a new
         // file and `furnace diff` shows nothing.
         const enginePath = normalizePathSlashes(getOverrideEngineTargetPath(paths.engine, overrideConfig, entry.name, ftlDir).slice(paths.engine.length + 1));
@@ -109,7 +109,7 @@ async function diffOverride(name, projectRoot, config) {
  * `furnace apply`.
  *
  * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via
- * `applyCustomFtlFile` — NOT to `customConfig.targetPath` — so the
+ * `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
@@ -138,7 +138,7 @@ async function diffCustom(name, projectRoot, config) {
         const workspacePath = join(customDir, entry.name);
         const workspaceContent = await readText(workspacePath);
         // `.ftl` files deploy to the locale tree, not the component's
-        // targetPath; mirror `applyCustomFtlFile`'s target computation so the
+        // targetPath. Mirror `applyCustomFtlFile`'s target computation so the
         // diff header and the existence probe name the same path apply
         // writes to. Any change here must stay in lock-step with
         // `src/core/furnace-apply-ftl.ts`.

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

@@ -35,7 +35,7 @@ function registerFurnaceApplyCommand(furnace, context) {
         .option('-w, --watch', 'Watch component directories and re-apply on changes');
     addWaitLockOption(apply).action(withErrorHandling(async (name, options) => {
         const { waitLock, ...rest } = options ?? {};
-        // Resolved ONCE and used twice: the engine session lock below, and
+        // Resolved once and used twice: the engine session lock below, and
         // the furnace lock the mutation takes inside it. Resolving twice
         // would be the same value today and a drift risk tomorrow.
         const waitLockSeconds = resolveWaitLockSeconds(waitLock);