@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/commands/furnace/create-browser-test.js

@@ -2,7 +2,7 @@
 /**
  * Browser-chrome test scaffolding for `furnace create --with-tests`,
  * including the `--test-dir` redirect and collision safety (existing
- * manifests are appended to; head.js and test implementations are never
+ * manifests are appended to, and head.js and test implementations are never
  * overwritten). Split out of `create.ts` to keep that command file within
  * the per-file line budget.
  */
@@ -83,12 +83,12 @@ export async function scaffoldTestFiles(componentName, license, forgeConfig, pat
     const jsHeader = getLicenseHeader(license, 'js');
     const hashHeader = getLicenseHeader(license, 'hash');
     const testFiles = [];
-    // browser.toml — create if missing, append entry if existing
+    // browser.toml: create if missing, append entry if existing.
     const tomlPath = join(testDir, 'browser.toml');
     if (await pathExists(tomlPath)) {
         // 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
+        // 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);
@@ -113,7 +113,7 @@ support-files = ["head.js"]
         await writeText(tomlPath, browserToml);
     }
     testFiles.push('browser.toml');
-    // head.js — only create if it doesn't exist (shared across components)
+    // head.js: only create if it doesn't exist (shared across components).
     const headPath = join(testDir, 'head.js');
     if (!(await pathExists(headPath))) {
         if (journal)

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -8,7 +8,7 @@ export interface DryRunPlanInput {
     /**
      * Feature-scoped Fluent bundle the component participates in (the same
      * value that will be written to `furnace.json`'s `sharedFtl`). When set,
-     * the component's own `.ftl` is NOT scaffolded and the plan preview
+     * the component's own `.ftl` is not scaffolded and the plan preview
      * reflects that. Omit the key for the default per-component scaffold.
      */
     sharedFtl?: string;
@@ -18,8 +18,8 @@ export interface DryRunPlanInput {
     /**
      * Resolved `--test-dir` override (engine-relative, already validated by
      * `resolveValidatedTestDir`). Omit for the default `<binaryName>`-derived
-     * scaffold directory. The formatters MUST receive the same value the
-     * scaffolders get — the plan used to recompute the default from
+     * scaffold directory. The formatters must receive the same value the
+     * scaffolders get. The plan used to recompute the default from
      * `binaryName` and named a directory the real run never wrote to.
      */
     testDir?: string;
@@ -35,7 +35,7 @@ export declare function formatSuccessNote(args: {
     testFiles: string[];
     testStyle: ResolvedTestStyle;
     binaryName: string;
-    /** Resolved `--test-dir` override; see {@link DryRunPlanInput.testDir}. */
+    /** Resolved `--test-dir` override. See {@link DryRunPlanInput.testDir}. */
     testDir?: string | undefined;
 }): string;
 /**

package/dist/src/commands/furnace/create-dry-run.js

@@ -3,8 +3,8 @@
  * Dry-run plan formatter for `furnace create`.
  *
  * Lives outside `create.ts` so the authoring command stays under the
- * per-file LOC budget. The formatter is pure — all inputs are already
- * resolved by the command's validation phase — so it can be exercised
+ * per-file LOC budget. The formatter is pure (all inputs are already
+ * resolved by the command's validation phase), so it can be exercised
  * independently of the mutation plumbing.
  */
 import { BROWSER_TEST_SCAFFOLD_ROOT, resolveBrowserChromeTestDir, resolveXpcshellTestDir, } from '../../core/furnace-constants.js';
@@ -23,7 +23,7 @@ function formatTestSection(args) {
     if (testStyle === 'browser-chrome') {
         // Same resolver as scaffoldTestFiles: the registration name is the
         // path below browser/base/content/test/, which under --test-dir is
-        // NOT the binary name.
+        // not the binary name.
         const testDirRel = resolveBrowserChromeTestDir(binaryName, testDir);
         const manifestName = testDirRel.slice(BROWSER_TEST_SCAFFOLD_ROOT.length);
         return (`\n\nWould create test files in engine/${testDirRel}/:\n` +
@@ -79,7 +79,7 @@ export function formatSuccessNote(args) {
 export function formatDryRunPlan(args) {
     const { componentName, localized, register, composes, stockAdditions, sharedFtl, testStyle, description, binaryName, testDir, } = args;
     const componentFiles = [`${componentName}.mjs`, `${componentName}.css`];
-    // A per-component .ftl is scaffolded only when the component does NOT
+    // A per-component .ftl is scaffolded only when the component does not
     // opt into a shared feature-scoped bundle. Mirrors writeComponentFiles.
     if (localized && !sharedFtl)
         componentFiles.push(`${componentName}.ftl`);

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

@@ -1,7 +1,7 @@
 /**
  * Feature-flag resolution for `furnace create`. Extracted from
  * `create.ts` so the authoring command stays under the per-file LOC
- * budget — the flag resolver has grown with each new opt-in (`--xpcshell`,
+ * budget. The flag resolver has grown with each new opt-in (`--xpcshell`,
  * `--test-style`, `--shared-ftl`).
  */
 import type { FurnaceCreateOptions } from '../../types/commands/index.js';
@@ -11,7 +11,7 @@ import type { FurnaceCreateOptions } from '../../types/commands/index.js';
  * `--shared-ftl` implies `localized` and short-circuits the interactive
  * prompt so the operator is not asked to flip a flag we are about to
  * enforce. `--no-localized` combined with `--shared-ftl` is rejected
- * fast-fail; the cross-field check in furnace-config would catch it
+ * fast-fail. The cross-field check in furnace-config would catch it
  * too, but later and without a clear command-line message.
  *
  * @param isInteractive - Whether interactive prompts are available

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

@@ -2,7 +2,7 @@
 /**
  * Feature-flag resolution for `furnace create`. Extracted from
  * `create.ts` so the authoring command stays under the per-file LOC
- * budget — the flag resolver has grown with each new opt-in (`--xpcshell`,
+ * budget. The flag resolver has grown with each new opt-in (`--xpcshell`,
  * `--test-style`, `--shared-ftl`).
  */
 import { multiselect } from '@clack/prompts';
@@ -14,7 +14,7 @@ import { cancel, isCancel } from '../../utils/logger.js';
  * `--shared-ftl` implies `localized` and short-circuits the interactive
  * prompt so the operator is not asked to flip a flag we are about to
  * enforce. `--no-localized` combined with `--shared-ftl` is rejected
- * fast-fail; the cross-field check in furnace-config would catch it
+ * fast-fail. The cross-field check in furnace-config would catch it
  * too, but later and without a clear command-line message.
  *
  * @param isInteractive - Whether interactive prompts are available

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

@@ -3,10 +3,10 @@
  * `fireforge furnace create --test-style=mochikit`.
  *
  * 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
+ * document, so forks with a bespoke chrome document that 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 —
+ * against any fork that registers the upstream toolkit test manifest tree,
  * including those without a tabbrowser.
  */
 import { type RollbackJournal } from '../../core/furnace-rollback.js';
@@ -21,7 +21,7 @@ import type { ProjectLicense } from '../../types/config.js';
  * Appends a per-test entry to the existing `chrome.toml` when present,
  * writes a fresh `[DEFAULT]`-headed one otherwise. The caller is still
  * responsible for ensuring the `toolkit/content/tests/widgets/chrome.toml`
- * path is registered somewhere in the moz.build tree; most forks inherit
+ * path is registered somewhere in the moz.build tree. Most forks inherit
  * this from upstream via `TEST_HARNESS_FILES += [...]`.
  */
 export declare function scaffoldMochikitTestFiles(componentName: string, license: ProjectLicense, paths: {

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

@@ -4,10 +4,10 @@
  * `fireforge furnace create --test-style=mochikit`.
  *
  * 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
+ * document, so forks with a bespoke chrome document that 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 —
+ * against any fork that registers the upstream toolkit test manifest tree,
  * including those without a tabbrowser.
  */
 import { join } from 'node:path';
@@ -26,7 +26,7 @@ import { generateMochikitChromeTomlEntry, generateMochikitChromeTomlSkeleton, ge
  * Appends a per-test entry to the existing `chrome.toml` when present,
  * writes a fresh `[DEFAULT]`-headed one otherwise. The caller is still
  * responsible for ensuring the `toolkit/content/tests/widgets/chrome.toml`
- * path is registered somewhere in the moz.build tree; most forks inherit
+ * path is registered somewhere in the moz.build tree. Most forks inherit
  * this from upstream via `TEST_HARNESS_FILES += [...]`.
  */
 export async function scaffoldMochikitTestFiles(componentName, license, paths, journal) {
@@ -50,9 +50,9 @@ export async function scaffoldMochikitTestFiles(componentName, license, paths, j
         await writeText(testFilePath, generateMochikitTestContent(componentName));
         writtenFiles.push(testFileName);
     }
-    // chrome.toml — append entry if the file already exists, otherwise write
-    // a fresh skeleton + entry. Idempotency: if the entry is already present
-    // the manifest is left untouched so re-runs don't double-register.
+    // chrome.toml: append an entry if the file already exists, otherwise
+    // write a fresh skeleton + entry. Idempotency: if the entry is already
+    // present the manifest is left untouched so re-runs don't double-register.
     const manifestPath = join(testDir, 'chrome.toml');
     const entry = generateMochikitChromeTomlEntry(componentName);
     if (await pathExists(manifestPath)) {

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

@@ -22,7 +22,7 @@ export interface GenerateMjsContentOptions {
 /**
  * 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`)
@@ -31,13 +31,13 @@ export interface GenerateMjsContentOptions {
  * 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(options: GenerateMjsContentOptions): string;
 /** Generates the .css file content for a custom component. */
@@ -50,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
@@ -61,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.).
  */
@@ -84,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.
  */
@@ -102,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,13 +16,13 @@
  * 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(options) {
     const { name, className, description, localized, header, ftlChromeSubPath, sharedFtl } = options;
@@ -36,10 +36,10 @@ export function generateMjsContent(options) {
         : 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
@@ -118,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
@@ -129,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) {
@@ -213,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.).
  */
@@ -238,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.
  */
@@ -281,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

@@ -86,7 +86,7 @@ async function writeComponentFiles(options) {
     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) {
@@ -106,7 +106,7 @@ async function writeComponentFiles(options) {
  * 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
@@ -135,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();
@@ -269,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',
@@ -315,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
@@ -334,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;
@@ -345,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,
@@ -357,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

@@ -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);

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);