@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -39,16 +39,16 @@ function hasFtlFileExtension(value) {
 /**
  * Validates an FTL base path before writing it to furnace.json.
  * Rejects:
- *  - empty values and null bytes;
- *  - absolute paths (POSIX or Windows-drive) that escape the engine;
- *  - `..` segments that escape the engine;
+ *  - empty values and null bytes
+ *  - absolute paths (POSIX or Windows-drive) that escape the engine
+ *  - `..` segments that escape the engine
  *  - file-shaped values ending in `.ftl` / `.properties` / `.dtd`
- *    (these are locale resources, not directories — the operator
- *    almost certainly meant to name the parent directory).
+ *    (these are locale resources, not directories, so the operator
+ *    almost certainly meant to name the parent directory)
  *
  * When {@link engineDir} is provided and exists on disk, the resolved
- * `engine/${value}` path is probed: if it exists but is not a
- * directory, the same file-shape error fires; if it does not exist yet,
+ * `engine/${value}` path is probed. If it exists but is not a
+ * directory, the same file-shape error fires. If it does not exist yet,
  * a non-blocking warning is logged (a fresh project that has not
  * `fireforge download`-ed yet is the legitimate pre-existence case).
  */
@@ -87,16 +87,16 @@ async function validateFtlBasePath(value, engineDir) {
         }
         catch (error) {
             // FurnaceError (from the `isDirectory()` branch above) is a real
-            // shape failure — re-throw so the operator sees it.
+            // shape failure, so re-throw and let the operator see it.
             if (error instanceof FurnaceError)
                 throw error;
             // ENOENT is expected on a fresh project before `fireforge
-            // download` has populated engine/; only warn.
+            // download` has populated engine/. Only warn.
             const code = getNodeErrorCode(error);
             if (code === 'ENOENT') {
                 warn(`ftlBasePath "${value}" does not yet exist at ${resolved}. This is fine if you have not run "fireforge download" yet; rerun "fireforge furnace init --force" after the engine is extracted to re-validate.`);
             }
-            // Any other stat error is also best-effort ignored here — a
+            // Any other stat error is also ignored here as best-effort: a
             // permission issue or malformed engine checkout will surface on
             // the next command that actually reads the FTL tree.
         }
@@ -116,7 +116,7 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
     const paths = getProjectPaths(projectRoot);
     // Seed the default furnace config with a tokenPrefix derived from
     // fireforge.json's binaryName so `token coverage` sees real tokens on the
-    // very first run — without the prefix default, a fresh init → token add →
+    // very first run. Without the prefix default, a fresh init → token add →
     // coverage sequence reports `0 tokens / N unknown` because the scan has
     // nothing to key off. Loading fireforge.json here is best-effort: a
     // project without one (mid-setup) falls through to the prefix-less
@@ -197,8 +197,8 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
  * Scaffolds the default tokens CSS file under the engine and registers
  * its path in `fireforge.json`'s `patchLint.rawColorAllowlist`. Both
  * operations are skipped silently when the engine directory does not
- * yet exist (a fresh project that hasn't `fireforge download`ed yet);
- * the scaffold is re-driven on the next `furnace init --force`.
+ * yet exist (a fresh project that hasn't `fireforge download`ed yet).
+ * The scaffold is re-driven on the next `furnace init --force`.
  *
  * Returns the scaffolded path when the file was actually created, so
  * the init command can surface it in the summary note.
@@ -258,12 +258,12 @@ async function scaffoldTokensCss(projectRoot) {
     // is owned end-to-end by tooling. Scaffolding and allowlisting it without
     // registering leaves the very next `fireforge status` correctly flagging
     // it as unmanaged + unregistered while `furnace deploy --dry-run` reports
-    // nothing to deploy — a documented init command turning a clean project
+    // nothing to deploy, a documented init command turning a clean project
     // unclean. The CSS lives at the canonical
     // `browser/themes/shared/<binaryName>-tokens.css` path the shared-CSS rule
     // already targets, so it gets the same
     // `skin/classic/browser/<name>.css (../shared/<name>.css)` entry as any
-    // other shared CSS. Idempotent — `furnace init --force` against a
+    // other shared CSS. It is idempotent: `furnace init --force` against a
     // registered tree is a no-op.
     try {
         const fileBase = `${forgeConfig.binaryName}-tokens.css`;

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

@@ -22,8 +22,8 @@ async function getHealthIndicator(componentDir, type, name, appliedChecksums) {
     }
     catch {
         // A race with `furnace remove`, filesystem permission change, or a
-        // transient IO failure must not crash the entire `list -v` output —
-        // render a degraded state so the rest of the table still shows.
+        // transient IO failure must not crash the entire `list -v` output, so
+        // render a degraded state and the rest of the table still shows.
         return formatErrorText('unavailable');
     }
 }

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

@@ -8,7 +8,7 @@ import type { FurnaceOverrideOptions } from '../../types/commands/index.js';
 export declare function furnaceOverrideCommand(projectRoot: string, name?: string, options?: FurnaceOverrideOptions): Promise<void>;
 /**
  * Creates multiple overrides in a single invocation. Each component is validated
- * and created sequentially; failures on one component do not block the rest.
+ * and created sequentially. Failures on one component do not block the rest.
  * @param projectRoot - Root directory of the project
  * @param names - Component tag names to override
  * @param options - CLI options applied to all overrides

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

@@ -79,7 +79,7 @@ async function copyOverrideFiles(options) {
  * override entry. Re-reads the current on-disk furnace.json inside the
  * operation lock and splices the new entry onto the fresh state, so two
  * concurrent `furnace override` commands cannot race their read-modify-write
- * cycles into a single surviving entry — otherwise both report success and
+ * cycles into a single surviving entry. Otherwise both report success and
  * furnace.json keeps only the second writer's.
  */
 async function saveOverrideConfig(options) {
@@ -96,8 +96,8 @@ async function saveOverrideConfig(options) {
     await writeJson(overrideJsonPath, overrideJson);
     // Re-read the current furnace.json inside the lock. The outer caller
     // loaded a snapshot before entering `runFurnaceMutation`, but another
-    // furnace mutation (override / init / sync) may have landed in between
-    // — writing back the stale snapshot would drop that concurrent write.
+    // furnace mutation (override / init / sync) may have landed in between,
+    // and writing back the stale snapshot would drop that concurrent write.
     const freshConfig = await loadAuthoringFurnaceConfig(projectRoot);
     freshConfig.overrides[componentName] = {
         type: overrideType,
@@ -164,11 +164,11 @@ async function performOverrideMutations(args) {
 }
 /**
  * Throws if `componentName` is already classified as something `override`
- * cannot coexist with. A stock-bucket entry is NOT a hard conflict — the
- * whole point of `override` is to fork a component out of the stock bucket
- * into the overrides bucket, and requiring manual `furnace.json` surgery
- * first was a pure footgun. `promoteStockToOverrideIfNeeded` handles the
- * transition in-memory; this guard only rejects the other two cases where
+ * cannot coexist with. A stock-bucket entry is not a hard conflict:
+ * `override` exists to fork a component out of the stock bucket into the
+ * overrides bucket, and requiring manual `furnace.json` surgery first was
+ * a footgun. `promoteStockToOverrideIfNeeded` handles the
+ * transition in-memory. This guard only rejects the other two cases where
  * a rename actually contradicts existing state.
  */
 function assertNoComponentCollision(config, componentName) {
@@ -185,7 +185,7 @@ function assertNoComponentCollision(config, componentName) {
  * the subsequent `writeFurnaceConfig` inside the mutation phase persists
  * the stock → override promotion atomically alongside the new override
  * entry. Returns true when a promotion happened so the caller can emit a
- * one-line note; false when the component was not stock.
+ * one-line note. Returns false when the component was not stock.
  */
 function promoteStockToOverrideIfNeeded(config, componentName) {
     const index = config.stock.indexOf(componentName);
@@ -203,9 +203,9 @@ function promoteStockToOverrideIfNeeded(config, componentName) {
 export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
     const isInteractive = stdioIsInteractive();
     intro('Furnace Override');
-    // --- Validate config-independent inputs BEFORE auto-creating furnace.json
+    // --- Validate config-independent inputs before auto-creating furnace.json
     // so a failed authoring command never strands a fresh config in the
-    // project root. CLI-supplied name is checked here; the engine directory
+    // project root. CLI-supplied name is checked here. The engine directory
     // and component-resolution checks below also have no config dependency.
     const paths = getProjectPaths(projectRoot);
     if (name !== undefined && !CUSTOM_ELEMENT_TAG_PATTERN.test(name)) {
@@ -226,7 +226,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
     // --- Resolve component name ---
     let componentName = name;
     if (!componentName) {
-        // Interactive prompt path; non-interactive missing-name was rejected above.
+        // Interactive prompt path. Non-interactive missing-name was rejected above.
         const allComponents = await scanWidgetsDirectory(paths.engine, ftlDir);
         const available = allComponents.filter((c) => !(c.tagName in config.overrides));
         if (available.length === 0) {
@@ -336,7 +336,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
 }
 /**
  * Creates multiple overrides in a single invocation. Each component is validated
- * and created sequentially; failures on one component do not block the rest.
+ * and created sequentially. Failures on one component do not block the rest.
  * @param projectRoot - Root directory of the project
  * @param names - Component tag names to override
  * @param options - CLI options applied to all overrides
@@ -362,8 +362,8 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
     const state = await loadState(projectRoot);
     // Check for duplicates and pre-existing classifications across every
     // bucket in furnace.json. A stock-bucket entry is promoted in-memory
-    // here (see `promoteStockToOverrideIfNeeded`) rather than rejected —
-    // the operator's intent is to fork that specific stock component. The
+    // here (see `promoteStockToOverrideIfNeeded`) rather than rejected,
+    // since the operator's intent is to fork that specific stock component. The
     // collision guard still rejects name conflicts that would double-
     // classify a tag in a way `writeFurnaceConfig` cannot safely produce
     // (two overrides, or an override + custom).

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

@@ -13,8 +13,8 @@ import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
 /**
- * Runs the two teardown steps — `cleanStories` and the rollback-journal
- * restore — independently, collecting whatever errors either step throws.
+ * Runs the two teardown steps (`cleanStories` and the rollback-journal
+ * restore) independently, collecting whatever errors either step throws.
  * Both steps must run regardless of the other's outcome, because each
  * operates on a different part of engine state and skipping one leaves
  * the engine in a worse position than a single-step failure.
@@ -72,10 +72,10 @@ function reportPreviewStagingFailures(stageResult) {
 }
 /**
  * Filenames emitted by the Firefox build backend (not by Storybook's npm
- * package set) — their absence means `mach build` has not produced its
+ * package set). Their absence means `mach build` has not produced its
  * post-configure artifacts, which is a different failure mode from a missing
  * Storybook workspace dependency tree. A
- * `FileNotFoundError: [...] chrome-map.json` AFTER a successful Storybook
+ * `FileNotFoundError: [...] chrome-map.json` after a successful Storybook
  * `npm install` is the case a dep-focused heuristic misdiagnoses, sending
  * the operator back to `--install`. The pattern list is narrow on purpose so
  * the backend-rebuild hint only fires when it is confident.
@@ -101,7 +101,7 @@ export function buildStorybookFailureMessage(output, installRequested) {
         ? 'Try running "python3 ./mach storybook upgrade" manually in the engine directory.'
         : 'Run "fireforge furnace preview --install" to bootstrap Storybook dependencies, or run "python3 ./mach storybook upgrade" manually in engine/.';
     const hasFileNotFoundSignal = /(ENOENT|No such file or directory|FileNotFoundError)/i.test(output);
-    // Check backend-artifact signal first — a missing chrome-map.json looks
+    // Check the backend-artifact signal first: a missing chrome-map.json looks
     // like any other "No such file" error to a naïve regex, but the fix is
     // to rerun `fireforge build`, not to reinstall Storybook dependencies.
     if (hasFileNotFoundSignal && BACKEND_ARTIFACT_PATTERNS.some((p) => p.test(output))) {
@@ -122,7 +122,7 @@ export function buildStorybookFailureMessage(output, installRequested) {
  * Preflights the Firefox build + toolchain prerequisites `mach storybook`
  * quietly assumes. Without it, preview stages components and launches a
  * ~1000-package `mach storybook upgrade` npm install before the backend
- * surfaces a "missing chrome-map.json" / Cargo-config failure; this refuses
+ * surfaces a "missing chrome-map.json" / Cargo-config failure. This refuses
  * fast and leaves the workspace untouched.
  *
  * @param engineDir - Resolved engine directory
@@ -143,7 +143,7 @@ async function assertPreviewPrerequisites(engineDir) {
     // follow the remediation instruction ("run bootstrap then rerun preview")
     // hit the same refusal on the retry, because `fireforge bootstrap` alone
     // produces only `.in`. Either name is sufficient to prove the Rust
-    // toolchain is registered; the stronger `hasBuildArtifacts` check above
+    // toolchain is registered. The stronger `hasBuildArtifacts` check above
     // already guards against a completely un-configured tree.
     const cargoConfigPath = join(engineDir, '.cargo', 'config.toml');
     const cargoConfigInPath = join(engineDir, '.cargo', 'config.toml.in');
@@ -158,10 +158,10 @@ async function assertPreviewPrerequisites(engineDir) {
 /**
  * Emits a framing banner when the Storybook workspace has not yet had its npm
  * dependencies installed. `mach storybook` drives the install internally and
- * prints ELSPROBLEMS / UNMET DEPENDENCY lines verbatim; without this banner
+ * prints ELSPROBLEMS / UNMET DEPENDENCY lines verbatim. Without this banner
  * operators reliably read the npm output as a failure.
  *
- * Skipped when `--install` was explicitly requested — that path already runs
+ * Skipped when `--install` was explicitly requested, since that path runs
  * `mach storybook upgrade` before the preview launches, so the npm output
  * for the subsequent `mach storybook` invocation is a no-op.
  */
@@ -177,9 +177,9 @@ async function announceStorybookFirstRunIfNeeded(engineDir, installRequested) {
 /**
  * Surfaces an explicit success banner after a clean mach-storybook
  * exit so the operator's scrollback visually terminates the npm noise
- * from the first-run install. Only fires on expected exit codes — non-
- * zero cases fall through to the existing
- * `buildStorybookFailureMessage` classification.
+ * from the first-run install. Only fires on expected exit codes. Non-zero
+ * cases fall through to the existing `buildStorybookFailureMessage`
+ * classification.
  */
 function announceStorybookCleanExitIfApplicable(exitCode) {
     if (exitCode === 0 || exitCode === 130 || exitCode === 143) {
@@ -212,9 +212,9 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
     await assertPreviewPrerequisites(paths.engine);
     let previewResult;
     // True once we are about to (or have) written to engine/.../stories/furnace.
-    // Intentionally set BEFORE `syncStories` is awaited so a mid-sync failure
-    // still triggers `cleanStories` during teardown. `cleanStories` is a
-    // full-directory wipe, so it is correct to run against partial state —
+    // Set before `syncStories` is awaited so a mid-sync failure still
+    // triggers `cleanStories` during teardown. `cleanStories` is a
+    // full-directory wipe, so it is correct to run against partial state,
     // including state with zero files, where it is a cheap no-op.
     let storiesCleanupRequired = false;
     let previewJournal;
@@ -264,7 +264,7 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
                 stageSpinner.stop(`Staged ${stageResult.applied.length} component${stageResult.applied.length === 1 ? '' : 's'} for preview`);
             }
             // Sync story files. Set the cleanup flag before the await so a partial
-            // write failure still triggers the teardown wipe — `syncStories` writes
+            // write failure still triggers the teardown wipe. `syncStories` writes
             // files incrementally with no internal cleanup of its own.
             const syncSpinner = spinner('Syncing component stories...');
             storiesCleanupRequired = true;
@@ -299,7 +299,7 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
         // cleanStories must not prevent the journal restore, and vice versa.
         // Running teardown in a `finally` that calls
         // `restoreRollbackJournalOrThrow` throws synchronously, bypassing the
-        // primary error and skipping downstream handling — the engine is left
+        // primary error and skipping downstream handling, so the engine is left
         // with staged files and the user gets a teardown message with no
         // guidance. Both failures are collected instead and, if anything went
         // wrong, a `pendingRepair` marker is persisted for `fireforge doctor` to

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

@@ -90,8 +90,8 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
         }
         return { results: [], currentVersion };
     }
-    // Prefer the per-override baseCommit (survives download --force); fall back
-    // to the project-wide value for overrides created before this field existed.
+    // Prefer the per-override baseCommit (survives download --force). Fall
+    // back to the project-wide value for overrides created before this field existed.
     const baseCommit = overrideConfig.baseCommit ?? state.baseCommit;
     if (!baseCommit) {
         throw new FurnaceError('Cannot refresh: baseCommit not found. Re-run "fireforge download" to establish a baseline, ' +
@@ -153,7 +153,7 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
             return fileResults;
         }
         catch (error) {
-            // A dry run wrote nothing, so there is no journal to restore — it
+            // A dry run wrote nothing, so there is no journal to restore. It
             // rethrows without touching the lifecycle wrapper.
             if (!dryRun) {
                 return await completeJournalRollback(ctx, journal, error, {
@@ -171,7 +171,7 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
 /**
  * Refreshes every override sequentially, tallying merged/conflict/
  * unchanged file counts. Per-override errors are expected (warned and
- * recorded as failures) and do not abort the batch; only an error that
+ * recorded as failures) and do not abort the batch. Only an error that
  * escapes this function entirely warrants the caller's journal rollback.
  */
 async function runBatchRefresh(projectRoot, overrideNames, options) {
@@ -232,7 +232,7 @@ export async function furnaceRefreshCommand(projectRoot, name, options = {}) {
     if (name && refreshAll) {
         throw new FurnaceError('Cannot specify both a component name and --all. Use one or the other.');
     }
-    // Verify engine exists — refresh reads engine files for three-way merge
+    // Verify engine exists: refresh reads engine files for three-way merge
     // and --reset-base reads engine HEAD. Without this check, the user gets
     // an obscure git error instead of a clear precondition message.
     await assertFurnaceEngineReady(projectRoot);
@@ -265,7 +265,7 @@ export async function furnaceRefreshCommand(projectRoot, name, options = {}) {
     }
     // Snapshot furnace.json before the batch loop so an unexpected failure
     // (process crash, unhandled error) can be recovered from. Per-component
-    // errors caught below are expected and do not trigger a restore — only
+    // errors caught below are expected and do not trigger a restore. Only
     // an error that escapes the loop entirely warrants rolling back.
     const batchJournal = dryRun ? undefined : createRollbackJournal();
     if (batchJournal) {

package/dist/src/commands/furnace/remove-mutations.d.ts

@@ -2,7 +2,7 @@ import type { FurnacePaths } from '../../core/furnace-config.js';
 import type { RollbackJournal } from '../../core/furnace-rollback.js';
 import type { FurnaceConfig, FurnaceState } from '../../types/furnace.js';
 /**
- * Engine-side and workspace-side removal for an OVERRIDE component.
+ * Engine-side and workspace-side removal for an override component.
  *
  * Runs inside the caller's rollback journal rather than opening its own, so
  * a failure anywhere in the remove still restores the whole operation as a
@@ -20,8 +20,8 @@ export declare function performOverrideRemovalMutations(args: {
     journal: RollbackJournal;
 }): Promise<void>;
 /**
- * Engine-side and workspace-side removal for a CUSTOM component.
- * Sibling of {@link performOverrideRemovalMutations}; see its note.
+ * Engine-side and workspace-side removal for a custom component.
+ * Sibling of {@link performOverrideRemovalMutations}. See its note.
  */
 export declare function performCustomRemovalMutations(args: {
     projectRoot: string;

package/dist/src/commands/furnace/remove-mutations.js

@@ -7,7 +7,7 @@
  * `furnaceRemoveCommand` at the per-function cap. Extracting them inside the
  * same file would trade a function-length problem for a file-length one.
  *
- * Both run inside the CALLER's rollback journal rather than opening their
+ * Both run inside the caller's rollback journal rather than opening their
  * own, so a failure anywhere in the remove still restores the whole
  * operation as a single unit.
  */
@@ -27,12 +27,12 @@ import { removeDeployedCustomFiles } from './remove-state.js';
 /**
  * Restores every override-deployed file in `engine/` to its pristine HEAD
  * state, inverting what `applyOverrideComponent` would have written. Files that
- * existed in HEAD are restored via `git restore`; files the override
+ * existed in HEAD are restored via `git restore`. Files the override
  * introduced (not in HEAD) are deleted outright.
  *
- * The restore set is the **union** of (a) files currently in the override
- * workspace directory and (b) filenames recorded in `previousChecksumKeys`
- * — i.e. files we know we deployed last time, even if the developer has
+ * The restore set is the union of (a) files currently in the override
+ * workspace directory and (b) filenames recorded in `previousChecksumKeys`,
+ * i.e. files we know we deployed last time, even if the developer has
  * since deleted them from the workspace. Without (b), a workspace deletion
  * leaves an orphaned engine copy that `furnace remove` would never see.
  *
@@ -43,14 +43,15 @@ import { removeDeployedCustomFiles } from './remove-state.js';
 async function restoreOverrideEngineFiles(engineDir, overrideDir, overrideConfig, previousChecksumKeys, ftlDir, journal) {
     // Engine-as-git is a hard precondition for restoration: git HEAD is the only
     // honest oracle for "what was there before the override". If the engine is
-    // not a git repo we refuse rather than silently leaving files behind — the
-    // previous warn-and-continue behaviour is exactly what this fix removes.
+    // not a git repo we refuse rather than silently leaving files behind. The
+    // previous behaviour was to warn and continue, which is what this fix
+    // removes.
     if (!(await isGitRepository(engineDir))) {
         throw new FurnaceError('Cannot restore override files: engine is not a git repository. Run "fireforge download" to initialise it.');
     }
     // Build the union of "files we still see on disk" and "files state.json
     // claims we deployed". The state set is the only authority for files that
-    // were deployed and later deleted from the workspace; the workspace set is
+    // were deployed and later deleted from the workspace. The workspace set is
     // the only authority for files added since last apply that have not yet
     // been recorded in state. We need both.
     const fileSet = new Set();
@@ -80,7 +81,7 @@ async function restoreOverrideEngineFiles(engineDir, overrideDir, overrideConfig
     return { restored, removed };
 }
 /**
- * Engine-side and workspace-side removal for an OVERRIDE component.
+ * Engine-side and workspace-side removal for an override component.
  *
  * Runs inside the caller's rollback journal rather than opening its own, so
  * a failure anywhere in the remove still restores the whole operation as a
@@ -90,10 +91,10 @@ export async function performOverrideRemovalMutations(args) {
     const { name, paths, furnacePaths, freshConfig, freshState, ftlDir, journal } = args;
     const overrideConfig = freshConfig.overrides[name];
     const dir = join(furnacePaths.overridesDir, name);
-    // Restore deployed engine files BEFORE removing the workspace
+    // Restore deployed engine files before removing the workspace
     // directory. The restore set is the union of (a) files currently in
-    // the workspace and (b) files state.json says we deployed last time
-    // — without (b), source-side deletions would orphan engine copies
+    // the workspace and (b) files state.json says we deployed last time.
+    // Without (b), source-side deletions would orphan engine copies
     // that this command can never see again.
     if (overrideConfig?.basePath) {
         const previousKeys = Object.keys(extractComponentChecksums(freshState.appliedChecksums, 'override', name));
@@ -112,8 +113,8 @@ export async function performOverrideRemovalMutations(args) {
     }
 }
 /**
- * Engine-side and workspace-side removal for a CUSTOM component.
- * Sibling of {@link performOverrideRemovalMutations}; see its note.
+ * Engine-side and workspace-side removal for a custom component.
+ * Sibling of {@link performOverrideRemovalMutations}. See its note.
  */
 export async function performCustomRemovalMutations(args) {
     const { projectRoot, name, paths, furnacePaths, freshConfig, ftlDir, journal } = args;
@@ -140,12 +141,12 @@ export async function performCustomRemovalMutations(args) {
         await removeDir(dir);
         info(`Deleted components/custom/${name}/`);
     }
-    // Clean up deployed files in engine (per-file — see helper doc).
+    // Clean up deployed files in engine (per-file, see helper doc).
     if (customConfig?.targetPath) {
         await removeDeployedCustomFiles(projectRoot, paths.engine, name, customConfig.targetPath, journal);
     }
     // Localized components deploy a .ftl outside targetPath into the
-    // shared Fluent tree; apply writes it, so remove must delete it too
+    // shared Fluent tree. Apply writes it, so remove must delete it too
     // or the locale payload is orphaned.
     if (customConfig?.localized) {
         const ftlRel = join(ftlDir, `${name}.ftl`);
@@ -154,12 +155,12 @@ export async function performCustomRemovalMutations(args) {
             await snapshotFile(journal, ftlPath);
             await removeFile(ftlPath);
             // `ftlRel` is a native join, so on Windows an interpolated
-            // `engine/${ftlRel}` renders as `engine/toolkit\locales\...` — one
+            // `engine/${ftlRel}` renders as `engine/toolkit\locales\...`, one
             // message with both separators. Print the engine-relative form.
             info(`Deleted localized file engine/${normalizePathSlashes(ftlRel)}`);
         }
         // Drop the locale jar.mn chrome registration that `applyCustomFtlFile`
-        // wrote during deploy — otherwise the engine is left with a
+        // wrote during deploy. Otherwise the engine is left with a
         // `locale/.../${name}.ftl` entry pointing at a file just deleted, which
         // breaks the next package-manifest validation.
         await removeCustomFtlJarMnEntry(paths.engine, `${name}.ftl`, ftlDir, customConfig, journal);

package/dist/src/commands/furnace/remove-state.d.ts

@@ -10,7 +10,7 @@ export declare function dropChecksumsByPrefix(state: FurnaceState, prefix: strin
  * Per-file, never a recursive `removeDir` of the whole directory: nothing
  * stops two components from sharing a targetPath (or a hand-edited config
  * from pointing at an upstream-shared directory), and the recursive delete
- * permanently destroyed the co-located files on success — the rollback
+ * permanently destroyed the co-located files on success. The rollback
  * journal only protects the failure path. Deployed files come from the
  * component's state checksums, falling back to the conventional
  * `<name>.{mjs,css,ftl}` set when state carries no record (cleared by a

package/dist/src/commands/furnace/remove-state.js

@@ -24,7 +24,7 @@ export function dropChecksumsByPrefix(state, prefix) {
  * Per-file, never a recursive `removeDir` of the whole directory: nothing
  * stops two components from sharing a targetPath (or a hand-edited config
  * from pointing at an upstream-shared directory), and the recursive delete
- * permanently destroyed the co-located files on success — the rollback
+ * permanently destroyed the co-located files on success. The rollback
  * journal only protects the failure path. Deployed files come from the
  * component's state checksums, falling back to the conventional
  * `<name>.{mjs,css,ftl}` set when state carries no record (cleared by a

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

@@ -218,7 +218,7 @@ async function cleanupCustomMochikitTestFiles(name, projectRoot, journal) {
  * leaves an operator who ran `furnace create --with-tests --xpcshell`
  * followed by `furnace remove` with orphan `xpcshell.toml` +
  * `test_<name>_packaged.js` files still referencing the removed component.
- * This pass mirrors the mochitest one — snapshot before removal,
+ * This pass mirrors the mochitest one: snapshot before removal,
  * warn-and-continue semantics, explicit summary on partial failures.
  */
 async function cleanupCustomXpcshellTestFiles(name, projectRoot, journal) {
@@ -307,7 +307,7 @@ async function confirmFurnaceRemove(name, type, options, isInteractive) {
 }
 /**
  * Enforces the engine-as-git precondition for both override and custom
- * removals. Runs BEFORE the lock is acquired or a journal is registered so
+ * removals. Runs before the lock is acquired or a journal is registered so
  * the failure path does not involve any rollback infrastructure.
  */
 async function requireGitEngineForRemove(type, name, engineDir) {

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

@@ -10,7 +10,7 @@ export function updateBrowserChromeTestContent(content, oldName, newName, binary
     const newUnderscored = newName.replace(/-/g, '_');
     const oldTestStem = deriveTestStem(oldName, binaryName);
     const newTestStem = deriveTestStem(newName, binaryName);
-    // ONE pass over the content, not four chained `.replace()` calls.
+    // One pass over the content, instead of four chained `.replace()` calls.
     //
     // Chaining let each rule see the previous rule's output. Renaming
     // `acme-widget` to `acme-widget-v2` rewrote `test_acme_widget_defined` to
@@ -23,12 +23,12 @@ export function updateBrowserChromeTestContent(content, oldName, newName, binary
     // alternative that matches at a given position.
     const alternatives = [
         // The stem is a short bare fragment (`moz-` and binary prefixes stripped,
-        // hyphens underscored) — `panel` for `moz-panel`. Matching it loose, even
+        // hyphens underscored), so `panel` for `moz-panel`. Matching it loose, even
         // with hyphen guards, rewrote unrelated underscore-delimited identifiers
         // such as `test_panel_group_integration`, because `_` must stay a legal
         // neighbour for the generated name to match at all. The scaffold emits the
         // stem in exactly one shape, so anchor to that shape instead of guessing
-        // from boundaries — with its own guards, so the anchored shape cannot
+        // from boundaries. The anchored shape carries its own guards so it cannot
         // match inside a longer identifier (`mytest_panel_defined_extra`).
         {
             pattern: `(?<![\\w-])test_${escapeRegex(oldTestStem)}_defined(?![\\w-])`,
@@ -37,10 +37,10 @@ export function updateBrowserChromeTestContent(content, oldName, newName, binary
         // Word-boundary-aware, matching `furnace/rename.ts` and
         // `rename-xpcshell.ts`: without the guards a rename of `moz-panel` rewrote
         // `moz-panel-group`. `_` stays a legal neighbour for the underscored form
-        // because it is deliberately embedded in generated identifiers; `-` does
+        // because it is embedded in generated identifiers on purpose. `-` is
         // not.
         //
-        // Skipped when the underscored form IS the tag name (a hyphen-less
+        // Skipped when the underscored form is the tag name (a hyphen-less
         // component): both rules then match the same text and this one would win
         // on order, substituting `newUnderscored` where the tag `newName` was
         // meant. The stem rule still covers the one generated identifier shape.
@@ -55,9 +55,10 @@ export function updateBrowserChromeTestContent(content, oldName, newName, binary
         { pattern: `(?<![\\w-])${escapeRegex(oldName)}(?![\\w-])`, to: newName },
         { pattern: `\\b${escapeRegex(oldClassName)}\\b`, to: newClassName },
     ];
-    // Each alternative is its own capture group and the replacement is picked by
-    // the group that matched — not by matched TEXT, which is ambiguous whenever
-    // two rules can produce the same match with different substitutions.
+    // Each alternative is its own capture group and the replacement is picked
+    // by the group that matched, rather than by the matched text, which is
+    // ambiguous whenever two rules can produce the same match with different
+    // substitutions.
     const combined = new RegExp(alternatives.map(({ pattern }) => `(${pattern})`).join('|'), 'g');
     return content.replace(combined, (matched, ...args) => {
         const groups = args.slice(0, alternatives.length);

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

@@ -8,7 +8,7 @@
  * so word-boundary occurrences of the old tag / underscored name map to the
  * new ones.
  *
- * Extracted to keep `rename.ts` under the per-file LOC budget — it already
+ * Extracted to keep `rename.ts` under the per-file LOC budget. It already
  * carries mochikit + browser-mochitest + FTL handling.
  */
 import { type RollbackJournal } from '../../core/furnace-rollback.js';
@@ -19,7 +19,7 @@ import { type RollbackJournal } from '../../core/furnace-rollback.js';
  * old tag / old underscored name inside the test body.
  *
  * Best-effort: any failure logs a warning through the shared logger
- * but never throws — the component rename itself has already succeeded
+ * but never throws. The component rename itself has already succeeded
  * at this point, and blocking on a test rewrite would leave the
  * operator with a half-renamed component.
  *

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

@@ -9,7 +9,7 @@
  * so word-boundary occurrences of the old tag / underscored name map to the
  * new ones.
  *
- * Extracted to keep `rename.ts` under the per-file LOC budget — it already
+ * Extracted to keep `rename.ts` under the per-file LOC budget. It already
  * carries mochikit + browser-mochitest + FTL handling.
  */
 import { readdir } from 'node:fs/promises';
@@ -28,7 +28,7 @@ import { escapeRegex } from '../../utils/regex.js';
  * old tag / old underscored name inside the test body.
  *
  * Best-effort: any failure logs a warning through the shared logger
- * but never throws — the component rename itself has already succeeded
+ * but never throws. The component rename itself has already succeeded
  * at this point, and blocking on a test rewrite would leave the
  * operator with a half-renamed component.
  *
@@ -59,7 +59,7 @@ export async function renameXpcshellTestFiles(engineDir, projectRoot, oldName, n
     const newTestFileName = `test_${newUnderscored}_packaged.js`;
     try {
         // Journal the new scaffold dir + files so rollback (including the
-        // SIGINT path) removes them; only the old-name files were journaled
+        // SIGINT path) removes them. Only the old-name files were journaled
         // before, so a failed rename stranded the new-name scaffold.
         recordCreatedDir(journal, newScaffoldDir);
         await ensureDir(newScaffoldDir);