@hominis/fireforge 0.46.0 → 0.46.1

package/dist/bin/fireforge.d.ts

@@ -3,7 +3,7 @@
  * FireForge CLI entry point, and the only file that may call process.exit().
  * Library code propagates errors via CommandError or FireForgeError instead.
  *
- * The signal pipeline below composes several lifecycle modules; see
+ * The signal pipeline below composes several lifecycle modules. See
  * docs/lifecycle-invariants.md for who owns what.
  */
 export {};

package/dist/bin/fireforge.js

@@ -4,7 +4,7 @@
  * FireForge CLI entry point, and the only file that may call process.exit().
  * Library code propagates errors via CommandError or FireForgeError instead.
  *
- * The signal pipeline below composes several lifecycle modules; see
+ * The signal pipeline below composes several lifecycle modules. See
  * docs/lifecycle-invariants.md for who owns what.
  */
 import { installBrokenPipeHandler, main } from '../src/cli.js';
@@ -28,22 +28,22 @@ const SIGNAL_CRITICAL_SECTION_TIMEOUT_MS = 5_000;
  * under `run`/`test`, mach under `build`) to shut down after the signal was
  * forwarded to them. Must exceed the largest child grace window
  * (execSmokeRun's killGraceMs default of 10 s) so the SIGTERM → grace →
- * SIGKILL escalation can complete; exiting earlier orphans hung Firefox
+ * SIGKILL escalation can complete. Exiting earlier orphans hung Firefox
  * trees. A second Ctrl+C escalates to SIGKILL immediately.
  */
 const CHILD_SHUTDOWN_TIMEOUT_MS = 12_000;
 /**
  * Upper bound (ms) a delayed exit waits for stdout/stderr to drain. A pipe
- * is ASYNC, so `process.exit()` discards anything queued past the 64 KiB
- * kernel buffer — enough to truncate a JSON payload mid-object. Bounded so
- * a stalled reader cannot wedge a failing process; an EPIPE'd/closed pipe
- * releases the wait immediately.
+ * is async, so `process.exit()` discards anything queued past the 64 KiB
+ * kernel buffer, which is enough to truncate a JSON payload mid-object.
+ * Bounded so a stalled reader cannot wedge a failing process. An
+ * EPIPE'd/closed pipe releases the wait immediately.
  */
 const STDIO_FLUSH_TIMEOUT_MS = 5_000;
 /**
- * Drains stdio, then exits. Every delayed exit routes through here — only
- * the second-Ctrl+C force-exit (an explicit "out NOW") and this helper's
- * own call terminate directly.
+ * Drains stdio, then exits. Every delayed exit routes through here. Only
+ * the second-Ctrl+C force-exit (an explicit request to quit at once) and
+ * this helper's own call terminate directly.
  */
 function exitAfterStdioFlush(code) {
     void waitForStdioDrain(STDIO_FLUSH_TIMEOUT_MS).finally(() => {
@@ -76,9 +76,9 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // A diagnostic must never keep the process from exiting.
         }
         if (isSignalRollbackInFlight()) {
-            // A second Ctrl+C while we're already rolling back is a noisy "I want
-            // out now" — let the second signal terminate the process forcefully
-            // rather than queueing another rollback that will race the first.
+            // A second Ctrl+C while we're already rolling back means the user
+            // wants out now, so let it terminate the process forcefully rather
+            // than queueing another rollback that will race the first.
             process.exit(exitCode);
         }
         // Rollback, critical-section drain, and child shutdown run in parallel.
@@ -87,7 +87,7 @@ function installFurnaceSignalHandler(signal, exitCode) {
         // applied to the engine but a stale session file that mis-tracks progress
         // on `--continue`. Waiting on child shutdown keeps the parent alive through
         // the SIGTERM → grace → SIGKILL escalation execInherit/execSmokeRun forward
-        // to Firefox/mach; exiting first orphans those trees.
+        // to Firefox/mach. Exiting first orphans those trees.
         void Promise.allSettled([
             rollbackActiveOperationsForSignal(signal).catch((error) => {
                 console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
@@ -98,15 +98,15 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // `withFileLock`'s `finally { rm }` never runs across `process.exit`,
             // so both sweeps exist for the same reason. The generic one covers
             // every lock this process holds (engine session, patch directory,
-            // build); the furnace one stays because it carries rollback
+            // build). The furnace one stays because it carries rollback
             // bookkeeping the generic sweep does not, and runs after it so the
             // ownership checks see a settled tree.
             .then(() => forceReleaseHeldLocksForSignal())
             .then(() => forceReleaseFurnaceLocksForActiveOperations())
             // The run log's held partial line and queued writes do not survive
-            // `process.exit`; the command's own `finally` that would close it is
+            // `process.exit`. The command's own `finally` that would close it is
             // racing this handler and usually loses. Best-effort like the log
-            // itself — a diagnostic must never keep the process from exiting.
+            // itself: a diagnostic must never keep the process from exiting.
             .then(() => closeActiveRunLog().catch(() => undefined))
             .finally(() => {
             exitAfterStdioFlush(exitCode);
@@ -120,7 +120,7 @@ main().catch((error) => {
         exitAfterStdioFlush(error.exitCode);
         return;
     }
-    // Truly unexpected — CommandError should have been thrown by withErrorHandling
+    // Unexpected: withErrorHandling should have thrown a CommandError.
     console.error('Fatal error:', error);
     exitAfterStdioFlush(1);
 });

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.46.0",
-  "commit": "cffe7e47008c7a2af690abbbe352eb685d35d3f8",
-  "shortCommit": "cffe7e47008c",
+  "version": "0.46.1",
+  "commit": "821990fd7d076a205f37618055c0a01a95180aed",
+  "shortCommit": "821990fd7d07",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-09-05T19:28:43.539Z"
+  "buildTime": "2026-09-05T22:29:34.415Z"
 }

package/dist/src/cli-usage-error.d.ts

@@ -14,7 +14,7 @@ export declare function machineErrorCode(error: FireForgeError): string;
  * Whether the invocation asked for machine-readable output.
  *
  * Reading the flag from argv is blunt but exact: if the invocation asked for
- * machine output, stdout belongs to the payload from the first byte — before
+ * machine output, stdout belongs to the payload from the first byte, before
  * commander has parsed anything.
  *
  * @param argv - Process argv (defaults to `process.argv`)
@@ -30,14 +30,14 @@ export declare function wantsMachineOutput(argv?: readonly string[]): boolean;
  * already written their output, so those simply return. So does
  * `commander.help`: a command group invoked with no subcommand (`fireforge`,
  * `fireforge tree`), for which commander prints the group's help and would
- * exit 1. That is an informational invocation, not a wrong flag — `patch`,
- * `token` and `furnace` already answer it with help and exit 0 through an
- * explicit action, and the groups without one must not exit 8 (or leak
- * commander's `(outputHelp)` placeholder into a `--json` envelope) merely
- * for lacking it. A genuine usage error has already had its message written
- * to stderr by commander; it becomes exit 8, and under `--json` additionally
- * gets the standard refusal envelope on stdout so a scripted consumer sees a
- * parseable failure.
+ * exit 1. That is an informational invocation rather than a wrong flag.
+ * `patch`, `token` and `furnace` already answer it with help and exit 0
+ * through an explicit action, and the groups without one must not exit 8 (or
+ * leak commander's `(outputHelp)` placeholder into a `--json` envelope)
+ * merely for lacking it. A genuine usage error has already had its message
+ * written to stderr by commander. It becomes exit 8, and under `--json` it
+ * also gets the standard refusal envelope on stdout so a scripted consumer
+ * sees a parseable failure.
  *
  * @param error - Whatever `parseAsync` rejected with
  * @param machineOutput - Whether the invocation asked for `--json`/`--raw`

package/dist/src/cli-usage-error.js

@@ -5,8 +5,8 @@
  * Commander terminates the process itself on a usage error (unknown option,
  * missing argument, unknown command) with exit 1, which contradicts the
  * documented `INVALID_ARGUMENT` (8) in `docs/exit-codes.md` and bypasses the
- * `--json` refusal envelope because no action — and therefore no
- * `withErrorHandling` wrapper — ever runs. `createProgram` installs
+ * `--json` refusal envelope because no action (and therefore no
+ * `withErrorHandling` wrapper) ever runs. `createProgram` installs
  * `exitOverride()` so those failures surface as a thrown `CommanderError`,
  * and `main` routes them through here.
  */
@@ -33,7 +33,7 @@ export function machineErrorCode(error) {
  * Whether the invocation asked for machine-readable output.
  *
  * Reading the flag from argv is blunt but exact: if the invocation asked for
- * machine output, stdout belongs to the payload from the first byte — before
+ * machine output, stdout belongs to the payload from the first byte, before
  * commander has parsed anything.
  *
  * @param argv - Process argv (defaults to `process.argv`)
@@ -51,14 +51,14 @@ export function wantsMachineOutput(argv = process.argv) {
  * already written their output, so those simply return. So does
  * `commander.help`: a command group invoked with no subcommand (`fireforge`,
  * `fireforge tree`), for which commander prints the group's help and would
- * exit 1. That is an informational invocation, not a wrong flag — `patch`,
- * `token` and `furnace` already answer it with help and exit 0 through an
- * explicit action, and the groups without one must not exit 8 (or leak
- * commander's `(outputHelp)` placeholder into a `--json` envelope) merely
- * for lacking it. A genuine usage error has already had its message written
- * to stderr by commander; it becomes exit 8, and under `--json` additionally
- * gets the standard refusal envelope on stdout so a scripted consumer sees a
- * parseable failure.
+ * exit 1. That is an informational invocation rather than a wrong flag.
+ * `patch`, `token` and `furnace` already answer it with help and exit 0
+ * through an explicit action, and the groups without one must not exit 8 (or
+ * leak commander's `(outputHelp)` placeholder into a `--json` envelope)
+ * merely for lacking it. A genuine usage error has already had its message
+ * written to stderr by commander. It becomes exit 8, and under `--json` it
+ * also gets the standard refusal envelope on stdout so a scripted consumer
+ * sees a parseable failure.
  *
  * @param error - Whatever `parseAsync` rejected with
  * @param machineOutput - Whether the invocation asked for `--json`/`--raw`
@@ -71,7 +71,7 @@ export function handleParseError(error, machineOutput) {
     if (error.exitCode === 0 || error.code === 'commander.help') {
         return;
     }
-    // Commander's message carries its own `error: ` prefix; strip it so the
+    // Commander's message carries its own `error: ` prefix. Strip it so the
     // envelope text matches how every other refusal reads.
     const usage = new InvalidArgumentError(error.message.replace(/^error:\s*/, ''));
     if (machineOutput) {

package/dist/src/cli.d.ts

@@ -9,14 +9,15 @@ export declare function installBrokenPipeHandler(): void;
 /**
  * Removes the broken-pipe handler installed for CLI tests.
  *
- * @internal Exported only so tests can reach it; not part of the public surface.
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
  */
 export declare function resetBrokenPipeHandlerForTests(): void;
 /**
  * Gets the project root directory.
  * Walks up from the current working directory until a fireforge.json is found.
  * Throws a {@link ConfigNotFoundError} (code: CONFIG_ERROR) when no
- * fireforge.json is found within the walk depth limit — the error is
+ * fireforge.json is found within the walk depth limit. The error is
  * user-facing so `withErrorHandling` can print the guidance without
  * the stack dump that a plain `Error` would trigger.
  */

package/dist/src/cli.js

@@ -36,8 +36,8 @@ function getBrokenPipeHandler(state) {
 /**
  * Prints an error's `cause` chain under `--verbose`.
  *
- * Nine error classes declare a `cause` and twenty-two throw sites pass one;
- * without this the underlying git stderr, errno or parse failure never
+ * Nine error classes declare a `cause` and twenty-two throw sites pass one.
+ * Without this the underlying git stderr, errno or parse failure never
  * reaches the operator, because a `FireForgeError` renders as its
  * `userMessage` and stops.
  *
@@ -81,7 +81,8 @@ export function installBrokenPipeHandler() {
 /**
  * Removes the broken-pipe handler installed for CLI tests.
  *
- * @internal Exported only so tests can reach it; not part of the public surface.
+ * @internal Exported only so tests can reach it. It is not part of the
+ * public surface.
  */
 export function resetBrokenPipeHandlerForTests() {
     const state = getProcessState();
@@ -97,14 +98,14 @@ export function resetBrokenPipeHandlerForTests() {
  * Maximum number of directory levels to walk when searching for
  * `fireforge.json`. `dirname()` walking is pure string manipulation and
  * cannot cycle (the `parent === current` check already terminates at the
- * root); this cap only bounds the cost on pathologically deep paths.
+ * root). This cap only bounds the cost on pathologically deep paths.
  */
 const MAX_PROJECT_ROOT_WALK_DEPTH = 50;
 /**
  * Gets the project root directory.
  * Walks up from the current working directory until a fireforge.json is found.
  * Throws a {@link ConfigNotFoundError} (code: CONFIG_ERROR) when no
- * fireforge.json is found within the walk depth limit — the error is
+ * fireforge.json is found within the walk depth limit. The error is
  * user-facing so `withErrorHandling` can print the guidance without
  * the stack dump that a plain `Error` would trigger.
  */
@@ -132,9 +133,9 @@ export function getProjectRoot() {
  */
 export function withErrorHandling(handler) {
     return async (...args) => {
-        // Rule 3 of docs/machine-output.md: machine mode engages BEFORE any
-        // output. Anything that throws on the way in — most visibly
-        // `getProjectRoot`'s ConfigNotFoundError — would otherwise render a
+        // Rule 3 of docs/machine-output.md: machine mode engages before any
+        // output. Anything that throws on the way in (most visibly
+        // `getProjectRoot`'s ConfigNotFoundError) would otherwise render a
         // clack-styled block to stdout and leave a `--json` consumer with
         // un-parseable output. Reading the flag from argv is blunt but exact: if
         // the invocation asked for machine output, stdout belongs to the payload
@@ -155,9 +156,9 @@ export function withErrorHandling(handler) {
             }
             if (error instanceof CancellationError) {
                 cancel('Operation cancelled');
-                // 130 (128+SIGINT) is the conventional "user interrupted" code —
-                // scripts/CI can distinguish a deliberate prompt cancellation from
-                // a real failure (which exits 1).
+                // 130 (128+SIGINT) is the conventional "user interrupted" code, so
+                // scripts/CI can distinguish a prompt cancellation from a real
+                // failure (which exits 1).
                 throw new CommandError(ExitCode.USER_CANCELLED);
             }
             // An invariant failure is the one FireForgeError whose stack is part
@@ -178,7 +179,7 @@ export function withErrorHandling(handler) {
                 logError(error.userMessage);
                 printCauseChain(error);
                 // Not when a payload already owns stdout: `status --json --fail-on`
-                // writes its full document and THEN refuses, and appending an
+                // writes its full document and then refuses, and appending an
                 // envelope would make that two JSON documents.
                 if (machineOutput && !isStdoutSealed()) {
                     emitMachineError(machineErrorCode(error), error.message, error.code);
@@ -194,9 +195,9 @@ export function withErrorHandling(handler) {
         }
         finally {
             // Central machine-mode and stdout-seal reset. Commands leave both
-            // ENGAGED while an error propagates (a mid-throw restore would route
+            // engaged while an error propagates (a mid-throw restore would route
             // the styled error to stdout, corrupting the `--json`/`--raw` payload
-            // stream or displacing the FIREFORGE-VERDICT line); the reset happens
+            // stream or displacing the FIREFORGE-VERDICT line). The reset happens
             // here, after logError has picked its stream, so no state leaks into a
             // subsequent in-process invocation.
             setMachineOutputMode(false);
@@ -244,9 +245,9 @@ function buildGroupedHelpFormatter(manifest) {
             return formatHelpLine(term, desc, termWidth, helpWidth);
         });
         // -V/--version is handled in main() before commander parses (a real
-        // root-level `.version()` option would claim `--version` ANYWHERE in
+        // root-level `.version()` option would claim `--version` anywhere in
         // argv under commander's default parsing, breaking subcommand flags
-        // like `source set --version <v>`); advertise it here so root help
+        // like `source set --version <v>`). Advertise it here so root help
         // stays truthful.
         optionLines.unshift(formatHelpLine('-V, --version', 'output the version number', termWidth, helpWidth));
         if (optionLines.length > 0) {
@@ -328,7 +329,7 @@ export function createProgram() {
     const program = new Command();
     program
         .name('fireforge')
-        // Usage errors must NOT let commander call process.exit(1) itself: the
+        // Usage errors must not let commander call process.exit(1) itself: the
         // documented code is INVALID_ARGUMENT (8) and `--json` owes a refusal
         // envelope. Installed before any subcommand registers, because
         // `.command()` copies the override into the child at creation time.
@@ -342,9 +343,9 @@ export function createProgram() {
             setVerbose(true);
         }
     })
-        // Verification-tree guard: when the cwd resolves into a
-        // tree snapshot, refuse mutating commands before their action runs —
-        // one hook covers every command regardless of how the cwd got there.
+        // Verification-tree guard: when the cwd resolves into a tree snapshot,
+        // refuse mutating commands before their action runs. One hook covers
+        // every command regardless of how the cwd got there.
         .hook('preAction', async (thisCommand, actionCommand) => {
         await runTreeGuardHook(thisCommand.name(), actionCommand);
     });
@@ -359,7 +360,7 @@ export function createProgram() {
     // Uniform `--wait-lock`: scripted sequences blanket-append the flag, and a
     // subcommand that rejects it with "unknown option" kills the sequence with
     // a usage error instead of a lock message. Applied after registration so it
-    // covers every subcommand at every depth; commands that already declare the
+    // covers every subcommand at every depth. Commands that already declare the
     // honoring flag keep it untouched.
     ensureWaitLockOptionEverywhere(program);
     return program;
@@ -368,13 +369,13 @@ export function createProgram() {
  * Main CLI entry point.
  */
 export async function main() {
-    // Root-level --version/-V handling. Deliberately NOT a commander
-    // `.version()` option: under commander's default (non-positional)
-    // parsing, a root version option claims `--version` anywhere in argv and
-    // hijacks subcommand flags like `source set --version <v>`. The rule
-    // here: when NO subcommand was given, any -V/--version among the root
-    // flags prints the version — so `fireforge --verbose --version` works,
-    // and `fireforge source set --version 152` is untouched.
+    // Root-level --version/-V handling. This is not a commander `.version()`
+    // option, because under commander's default (non-positional) parsing a
+    // root version option claims `--version` anywhere in argv and hijacks
+    // subcommand flags like `source set --version <v>`. The rule here: when no
+    // subcommand was given, any -V/--version among the root flags prints the
+    // version, so `fireforge --verbose --version` works and
+    // `fireforge source set --version 152` is untouched.
     const userArgs = process.argv.slice(2);
     const hasSubcommand = userArgs.some((arg) => !arg.startsWith('-'));
     if (!hasSubcommand && userArgs.some((arg) => arg === '--version' || arg === '-V')) {

package/dist/src/commands/bootstrap-checks.js

@@ -13,7 +13,8 @@ export function detectBootstrapIssues(output) {
     const hasTraceback = /traceback \(most recent call last\):/i.test(normalized);
     const has403 = /\bhttp(?:\s+error)?\s*403\b/i.test(normalized) || /\b403\b.*forbidden/i.test(normalized);
     if (has403) {
-        // The traceback is just the stack trace from the HTTP error — report once.
+        // The traceback is just the stack trace from the HTTP error, so report
+        // it once.
         issues.push('sdk-fetch-403');
     }
     else if (hasTraceback) {

package/dist/src/commands/bootstrap.js

@@ -23,7 +23,7 @@ const BOOTSTRAP_FAILURE_SENTENCES = {
 function buildBootstrapFailureMessage(output) {
     // Delegates detection to the canonical scanner rather than keeping a
     // second copy of its six regexes. The copies had already disagreed: this
-    // one reported a traceback AND a 403 separately, while
+    // one reported a traceback and a 403 separately, while
     // `detectBootstrapIssues` collapses them, because a bootstrap traceback
     // accompanying a 403 is just the stack trace from that HTTP error.
     const issues = detectBootstrapIssues(output).map((issue) => BOOTSTRAP_FAILURE_SENTENCES[issue]);
@@ -79,7 +79,7 @@ export async function bootstrapCommand(projectRoot) {
         if (hasErrors) {
             outro('Build dependencies installed with errors');
             // Propagate the failure (mirroring doctor's exit-code handling)
-            // instead of exiting 0 — CI gating on bootstrap used to proceed to a
+            // instead of exiting 0. CI gating on bootstrap used to proceed to a
             // build that could not succeed because error-severity check results
             // were discarded here.
             return checksExitCode;

package/dist/src/commands/build.js

@@ -30,9 +30,9 @@ function parseJobCount(value) {
  * Patches `mozinfo.json` under the active obj-* directory so its recorded
  * paths match the current engine checkout, then runs `mach configure` to
  * regenerate every other generated path alongside it. Throws with the
- * original mismatch guidance when the rewriter refuses to proceed — that
- * always covers the unsafe cases, so the operator still gets the correct
- * fallback recovery instruction.
+ * original mismatch guidance when the rewriter refuses to proceed. That
+ * covers the unsafe cases, so the operator still gets the correct fallback
+ * recovery instruction.
  */
 async function rewriteAndReconfigure(engineDir, objDir, mismatchMessage) {
     const rewriteSpinner = spinner('Rewriting mozinfo.json paths...');
@@ -201,7 +201,7 @@ async function runBuildCommandBody(projectRoot, options) {
     // and fail fast naming `fireforge bootstrap` instead of dying ~8s into
     // configure with mach's "./mach bootstrap" remediation text. Fail-soft by
     // design: only a definitively parsed minimum vs a definitively probed host
-    // version can fail here; anything uncertain proceeds to mach, where the
+    // version can fail here. Anything uncertain proceeds to mach, where the
     // mach-error-hints translator still names the right remedy.
     const toolchainMismatches = await runToolchainPreflight(paths.engine);
     if (toolchainMismatches.length > 0) {
@@ -217,7 +217,7 @@ async function runBuildCommandBody(projectRoot, options) {
             // Safe-relocation rewrite path: patch mozinfo.json paths in place so
             // `mach configure` can regenerate the backend without scrubbing the
             // whole obj tree. The rewriter refuses anything that is not a pure
-            // prefix-move; on refusal we surface the refusal reason alongside
+            // prefix-move. On refusal we surface the refusal reason alongside
             // the original mismatch guidance and abort.
             await rewriteAndReconfigure(paths.engine, buildCheck.objDir, mismatchMessage);
         }
@@ -275,7 +275,7 @@ async function runBuildCommandBody(projectRoot, options) {
         // overlapping `fireforge build` / `fireforge build --ui` commands
         // against the same engine tree serialise instead of racing through the
         // same obj-*. A `build --ui` launched during an in-progress full build
-        // otherwise hits `No rule to make target 'XUL'` in mach — the
+        // otherwise hits `No rule to make target 'XUL'` in mach, the
         // downstream consequence of an incomplete backend, with no clue that a
         // concurrent build caused it. The lock turns the second invocation's
         // failure into an explicit refusal naming the holder PID.
@@ -313,9 +313,10 @@ async function runBuildCommandBody(projectRoot, options) {
     // Matching only (1) leaves operators on the (2) path seeing mach's own
     // "Configure complete!" and "run |mach build|" lines unexplained between
     // mach's "Your build was successful!" and FireForge's "Build completed in
-    // Xm Ys" outro — a contradictory tail. Both shapes route through the same
-    // annotation, emitted BEFORE FireForge's outro so the operator's last
-    // terminal line is the explanation, not the confusing mach guard text.
+    // Xm Ys" outro, a contradictory tail. Both shapes route through the same
+    // annotation, emitted before FireForge's outro so the operator's last
+    // terminal line is the explanation instead of the confusing mach guard
+    // text.
     const staleConfigurePatterns = [
         /config\.status is out of date/i,
         /Config object not found by mach\.[\s\S]*Configure complete!/i,
@@ -329,7 +330,7 @@ async function runBuildCommandBody(projectRoot, options) {
     }
     // Warn-only post-build audit: surfaces silent packaging drops (files
     // edited in engine/ but never registered for packaging) against the
-    // previous-build baseline. Never fails the build; the worst case is a
+    // previous-build baseline. Never fails the build. The worst case is a
     // warning an operator chooses to investigate.
     try {
         await auditBuildArtifacts(projectRoot, paths.engine, previousBaseline, {
@@ -346,7 +347,7 @@ async function runBuildCommandBody(projectRoot, options) {
     outro(`Build completed in ${timeStr}!`);
 }
 /**
- * Persists the full-coverage baseline; a failed write never fails the build.
+ * Persists the full-coverage baseline. A failed write never fails the build.
  * `--ui` is a `mach build faster`, so it is recorded as such: its `jar.mn`
  * fingerprints are carried forward from the previous baseline rather than
  * refreshed, which is why that baseline is threaded through.

package/dist/src/commands/config.js

@@ -89,7 +89,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         throw new GeneralError('No fireforge.json found. Run "fireforge setup" to create a project.');
     }
     if (value === undefined) {
-        // Get mode — read the raw document rather than the validated config so
+        // Get mode: read the raw document rather than the validated config so
         // keys persisted via `fireforge config <key> --force` remain readable.
         // `validateConfig` builds a typed clone containing only the known schema
         // fields, so relying on it here would hide forced-write keys and surface
@@ -110,7 +110,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         }
     }
     else {
-        // Set mode — validate key prefix
+        // Set mode: validate key prefix
         const topLevelKey = key.split('.')[0] ?? key;
         if (!SUPPORTED_CONFIG_ROOT_KEYS.includes(topLevelKey) &&
             !options.force) {
@@ -126,7 +126,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
             // Serialise the read → mutate → write round-trip behind the sidecar
             // config lock so two concurrent `fireforge config` invocations cannot
             // each read the pre-state, mutate their own copy, and clobber each
-            // other on write — both exiting 0 with one key silently lost. Atomic
+            // other on write, both exiting 0 with one key silently lost. Atomic
             // file writes (temp + rename) are not enough on their own: the lost
             // update happens before the rename, inside the read-modify step.
             // Readers stay lock-free (see `withConfigFileLock`).
@@ -143,12 +143,12 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                 if (deepEqual(currentValue, parsedValue)) {
                     return true;
                 }
-                // `--force` is an escape hatch for *unknown* keys; it must not also
-                // let the user write a structurally invalid value for a *known* key.
+                // `--force` is an escape hatch for unknown keys. It must not also
+                // let the user write a structurally invalid value for a known key.
                 // Strict validation applies whenever the key is listed in
                 // SUPPORTED_CONFIG_PATHS, regardless of --force.
                 //
-                // BOTH branches seed the mutation from the raw on-disk document.
+                // Both branches seed the mutation from the raw on-disk document.
                 // Round-tripping the known-key branch through `loadConfig` →
                 // `validateConfig` builds a typed clone containing only the known
                 // schema fields, so any ordinary `fireforge config <key> <value>`
@@ -160,7 +160,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                 }
                 else {
                     // Mutate the raw document (preserving unknown keys), then run
-                    // strict validation on the RESULT — validateConfig checks the
+                    // strict validation on the result. validateConfig checks the
                     // known schema fields and ignores unknown keys, so this keeps
                     // exactly the old validation strength while writing the
                     // unstripped document.
@@ -174,7 +174,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         catch (error) {
             // Only value/validation problems are the user's "invalid value".
             // Lock-acquisition timeouts and I/O failures must keep their own
-            // types and messages — re-labelling a lock timeout as `Invalid value
+            // types and messages. Re-labelling a lock timeout as `Invalid value
             // for "<key>"` points diagnosis at the value (and returns the wrong
             // exit-code class) when the real problem is a concurrent fireforge
             // process holding the config lock.
@@ -195,7 +195,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
 /**
  * Structural equality check covering the shapes `fireforge config` accepts:
  * primitives (strings, numbers, booleans), `null`, arrays of primitives, and
- * nested objects. Used to short-circuit no-op writes — when the parsed value
+ * nested objects. Used to short-circuit no-op writes: when the parsed value
  * matches the current on-disk value, the mutate + write step is skipped
  * entirely.
  */

package/dist/src/commands/destructive-decision.d.ts

@@ -6,12 +6,12 @@ import type { DestructiveOpResult } from '../core/destructive.js';
  * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
  * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
  * The dry-run wording is a user-facing contract that must not drift between
- * commands, so it lives here; the declined wording is per-command and stays a
- * parameter.
+ * commands, so it lives here. The declined wording is per-command and stays
+ * a parameter.
  *
  * `confirmDestructive` never mutates on its own, so a caller that forgets this
- * check silently performs a "dry run" for real — hence a boolean return the
- * caller must act on rather than a helper that returns void.
+ * check silently performs a "dry run" for real. That is why this returns a
+ * boolean the caller must act on instead of being a helper that returns void.
  * @param decision - The result from `confirmDestructive`.
  * @param declinedOutro - Outro to print when the operator answered "no".
  * @returns True when the caller should proceed with the mutation.

package/dist/src/commands/destructive-decision.js

@@ -8,12 +8,12 @@ const DRY_RUN_OUTRO = 'Dry run complete — no changes made';
  * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
  * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
  * The dry-run wording is a user-facing contract that must not drift between
- * commands, so it lives here; the declined wording is per-command and stays a
- * parameter.
+ * commands, so it lives here. The declined wording is per-command and stays
+ * a parameter.
  *
  * `confirmDestructive` never mutates on its own, so a caller that forgets this
- * check silently performs a "dry run" for real — hence a boolean return the
- * caller must act on rather than a helper that returns void.
+ * check silently performs a "dry run" for real. That is why this returns a
+ * boolean the caller must act on instead of being a helper that returns void.
  * @param decision - The result from `confirmDestructive`.
  * @param declinedOutro - Outro to print when the operator answered "no".
  * @returns True when the caller should proceed with the mutation.

package/dist/src/commands/discard.js

@@ -103,7 +103,7 @@ async function discardDirectoryEntries(projectRoot, engineDir, patchesDir, dirPa
             }
         }
         catch {
-            // Furnace config may not exist — skip silently
+            // Furnace config may not exist, so skip silently.
         }
         if (failures.length > 0) {
             throw new GeneralError(`Failed to discard ${failures.length} file(s) under ${dirPath}/. See warnings above.`);
@@ -131,7 +131,7 @@ export async function discardCommand(projectRoot, file, options = {}) {
     const statusEntries = await expandUntrackedDirectoryEntries(paths.engine, await getWorkingTreeStatus(paths.engine));
     const statusEntry = statusEntries.find((entry) => entry.file === file || entry.originalPath === file);
     // Directory recursion fallback: when the explicit path does not match a
-    // single status entry but DOES correspond to one or more entries below it,
+    // single status entry but does correspond to one or more entries below it,
     // treat the input as a directory and discard everything inside. Otherwise
     // `discard <dir> --yes` fails with "no changes to discard" even though
     // `status --unmanaged` lists files under that directory, forcing the
@@ -159,8 +159,8 @@ export async function discardCommand(projectRoot, file, options = {}) {
         throw new GeneralError(`File "${file}" has no changes to discard.`);
     }
     if (options.dryRun) {
-        // Show the rename pair regardless of which side the operator passed —
-        // passing the NEW path of a rename used to hide that discarding also
+        // Show the rename pair regardless of which side the operator passed.
+        // Passing the new path of a rename used to hide that discarding also
         // resurrects the old path, exactly when the full picture matters most.
         info(`Would discard changes to: ${dryRunLabel(plan)}`);
         outro('Dry run complete — no changes made');
@@ -182,7 +182,7 @@ export async function discardCommand(projectRoot, file, options = {}) {
             }
         }
         catch {
-            // Furnace config may not exist — skip silently
+            // Furnace config may not exist, so skip silently.
         }
         outro(describeDiscardOutcome(plan, options.toUpstream === true));
     }