@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/core/xpcshell-appdir.d.ts

@@ -9,7 +9,7 @@
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
  * directive is honoured. On a rebranded fork (appname=`mybrowser`) the
- * harness looks for `mybrowser-appdir` — the literal `firefox-appdir` line
+ * harness looks for `mybrowser-appdir`, so the literal `firefox-appdir` line
  * is silently ignored, `appPath` falls back to `xrePath`, and every
  * `resource:///modules/…` import throws `Failed to load
  * resource:///modules/<name>.sys.mjs` because xpcshell resolves the
@@ -21,7 +21,7 @@
  *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
  *    there is nothing to inject.
  * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
- *    first — if present, the harness already finds it. Fall back to
+ *    first. If present, the harness already finds it. Fall back to
  *    `firefox-appdir`. This ordering matches upstream precedence and avoids
  *    overriding an operator who already migrated.
  * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
@@ -30,7 +30,7 @@
  *    `dist/<bundle>.app/Contents/Resources/<value>` for the macOS packaged
  *    layout) and return it as the value to pass to `--app-path`.
  * 4. If multiple test paths disagree on the resolved value, refuse injection
- *    and return null — the operator can drop down to `--mach-arg`.
+ *    and return null. The operator can drop down to `--mach-arg`.
  *
  * Operator escape hatch: `--mach-arg=--app-path=…` always wins (handled in
  * test.ts, which skips injection when `--app-path=` already appears in the
@@ -60,7 +60,7 @@ export interface AppdirResolveResult {
  *  - Single- or double-quoted values
  *  - Whitespace either side of `=`
  *  - Continuation comments (`#` or `;`) at the end of the line
- *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`) — some
+ *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`). Some
  *    operators omit the quotes and the harness honours either form.
  *
  * Returns `undefined` when the key is absent or sits outside `[DEFAULT]`.
@@ -74,10 +74,10 @@ export declare function parseAppdirFromToml(tomlText: string, key: string): {
  * returns the absolute path of the first sibling `xpcshell.toml` found.
  * Stops at `engineDir` (inclusive) and returns null on miss.
  *
- * Special-cases `startPath` itself when it already ends with `xpcshell.toml`
- * — operators sometimes pass a manifest path directly.
+ * Special-cases `startPath` itself when it already ends with
+ * `xpcshell.toml`, since operators sometimes pass a manifest path directly.
  *
- * When `startPath` is a DIRECTORY, the walk starts at the directory itself
+ * When `startPath` is a directory, the walk starts at the directory itself
  * (checking `<dir>/xpcshell.toml` first) rather than at its parent.
  * Starting at the parent misses a directory's own manifest, so
  * `fireforge test <dir>` classifies it non-xpcshell and dispatches to the
@@ -86,31 +86,31 @@ export declare function parseAppdirFromToml(tomlText: string, key: string): {
 export declare function findNearestXpcshellManifest(engineDir: string, startPath: string): Promise<string | null>;
 /**
  * Reads `<objDir>/mozinfo.json` for the active app name. Returns
- * `"firefox"` when mozinfo cannot be read or the field is missing — that
+ * `"firefox"` when mozinfo cannot be read or the field is missing. That
  * is the safe default because it matches stock Firefox behaviour and
  * means the resolver will not inject anything (the manifest's
- * `firefox-appdir` value WILL be honoured by the upstream harness when
+ * `firefox-appdir` value is honoured by the upstream harness when
  * appname is firefox).
  */
 export declare function readMozinfoAppname(objDirPath: string): Promise<string>;
 /**
  * Probes the obj-dir's `dist/` subtree for the absolute path the harness
  * would have computed if the manifest key had been honoured. Returns null
- * when no candidate exists — better to skip injection silently than to point
+ * when no candidate exists: better to skip injection silently than to point
  * the harness at a path that does not exist, which fails with a different
  * error than the original symptom and confuses triage.
  *
  * Probe order differs by host platform:
  *
- * - **macOS (`darwin`)**: prefer
- *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` FIRST, then fall
+ * - macOS (`darwin`): prefer
+ *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` first, then fall
  *   back to `<objDir>/dist/bin/<value>`. On macOS `dist/bin` is symlinked to
- *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
- *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/` —
- *   NOT where `resource:///modules/` is rooted. Injecting that path looks
- *   successful in the log but points at a directory with no modules tree, so
- *   every `resource:///modules/…` import still throws.
- * - **non-macOS**: `dist/bin/<value>` first,
+ *   `dist/<App>.app/Contents/MacOS/` (the binaries directory), so
+ *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/`,
+ *   which is not where `resource:///modules/` is rooted. Injecting that path
+ *   looks successful in the log but points at a directory with no modules
+ *   tree, so every `resource:///modules/…` import still throws.
+ * - non-macOS: `dist/bin/<value>` first,
  *   `.app/Contents/Resources/<value>` as fallback.
  *
  * On both platforms the final `.app` fallback iterates every `*.app` entry
@@ -121,7 +121,7 @@ export declare function resolveAbsoluteAppPath(objDirAbs: string, relativeAppdir
  * Outcome carrier for {@link resolveXpcshellAppdirArg}. Distinguishes the
  * three "did nothing" cases so callers can shape diagnostics:
  *  - `none`: no manifest under any test path needs injection.
- *  - `mismatch`: at least two manifests resolved to different values; we
+ *  - `mismatch`: at least two manifests resolved to different values. We
  *    refuse to guess which one the operator meant.
  *  - `unresolved`: the manifest asks for `firefox-appdir = "<value>"` but
  *    no `dist/` candidate exists for that value.
@@ -143,7 +143,7 @@ export type XpcshellAppdirOutcome = {
 /**
  * Top-level resolver. Walks every test path, reads the nearest
  * xpcshell.toml, and returns the single absolute path to inject (or a
- * structured "no injection" outcome). Never throws — every fs / parse
+ * structured "no injection" outcome). Never throws: every fs / parse
  * error is folded into a `none` outcome so the test command always falls
  * through to the diagnostic hint instead of dying inside a helper.
  */

package/dist/src/core/xpcshell-appdir.js

@@ -10,7 +10,7 @@
  * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
  * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
  * directive is honoured. On a rebranded fork (appname=`mybrowser`) the
- * harness looks for `mybrowser-appdir` — the literal `firefox-appdir` line
+ * harness looks for `mybrowser-appdir`, so the literal `firefox-appdir` line
  * is silently ignored, `appPath` falls back to `xrePath`, and every
  * `resource:///modules/…` import throws `Failed to load
  * resource:///modules/<name>.sys.mjs` because xpcshell resolves the
@@ -22,7 +22,7 @@
  *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
  *    there is nothing to inject.
  * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
- *    first — if present, the harness already finds it. Fall back to
+ *    first. If present, the harness already finds it. Fall back to
  *    `firefox-appdir`. This ordering matches upstream precedence and avoids
  *    overriding an operator who already migrated.
  * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
@@ -31,7 +31,7 @@
  *    `dist/<bundle>.app/Contents/Resources/<value>` for the macOS packaged
  *    layout) and return it as the value to pass to `--app-path`.
  * 4. If multiple test paths disagree on the resolved value, refuse injection
- *    and return null — the operator can drop down to `--mach-arg`.
+ *    and return null. The operator can drop down to `--mach-arg`.
  *
  * Operator escape hatch: `--mach-arg=--app-path=…` always wins (handled in
  * test.ts, which skips injection when `--app-path=` already appears in the
@@ -51,7 +51,7 @@ import { isObject, isString } from '../utils/validation.js';
  *  - Single- or double-quoted values
  *  - Whitespace either side of `=`
  *  - Continuation comments (`#` or `;`) at the end of the line
- *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`) — some
+ *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`). Some
  *    operators omit the quotes and the harness honours either form.
  *
  * Returns `undefined` when the key is absent or sits outside `[DEFAULT]`.
@@ -93,7 +93,7 @@ function stripQuotes(raw) {
     if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
         return raw.slice(1, -1);
     }
-    // Bareword: must not contain whitespace; otherwise we are looking at
+    // Bareword: must not contain whitespace. Otherwise we are looking at
     // commentary that the regex's optional comment tail did not strip.
     if (/\s/.test(raw))
         return undefined;
@@ -104,10 +104,10 @@ function stripQuotes(raw) {
  * returns the absolute path of the first sibling `xpcshell.toml` found.
  * Stops at `engineDir` (inclusive) and returns null on miss.
  *
- * Special-cases `startPath` itself when it already ends with `xpcshell.toml`
- * — operators sometimes pass a manifest path directly.
+ * Special-cases `startPath` itself when it already ends with
+ * `xpcshell.toml`, since operators sometimes pass a manifest path directly.
  *
- * When `startPath` is a DIRECTORY, the walk starts at the directory itself
+ * When `startPath` is a directory, the walk starts at the directory itself
  * (checking `<dir>/xpcshell.toml` first) rather than at its parent.
  * Starting at the parent misses a directory's own manifest, so
  * `fireforge test <dir>` classifies it non-xpcshell and dispatches to the
@@ -122,8 +122,8 @@ export async function findNearestXpcshellManifest(engineDir, startPath) {
     const engineAbs = resolve(engineDir);
     let current = absStart;
     // First iteration resolves the starting directory (the path itself for a
-    // directory argument, its parent for a file); subsequent ones walk up.
-    // Cap iterations defensively — a pathological symlink loop would
+    // directory argument, its parent for a file). Subsequent ones walk up.
+    // Cap iterations defensively: a pathological symlink loop would
     // otherwise spin until the call stack overflows.
     for (let i = 0; i < 64; i += 1) {
         const dir = i === 0 ? (startIsDirectory ? absStart : dirname(absStart)) : dirname(current);
@@ -138,10 +138,10 @@ export async function findNearestXpcshellManifest(engineDir, startPath) {
 }
 /**
  * Reads `<objDir>/mozinfo.json` for the active app name. Returns
- * `"firefox"` when mozinfo cannot be read or the field is missing — that
+ * `"firefox"` when mozinfo cannot be read or the field is missing. That
  * is the safe default because it matches stock Firefox behaviour and
  * means the resolver will not inject anything (the manifest's
- * `firefox-appdir` value WILL be honoured by the upstream harness when
+ * `firefox-appdir` value is honoured by the upstream harness when
  * appname is firefox).
  */
 export async function readMozinfoAppname(objDirPath) {
@@ -156,28 +156,28 @@ export async function readMozinfoAppname(objDirPath) {
     }
     catch {
         // Malformed mozinfo is a build-system problem out of scope for the
-        // appdir resolver; treat as if appname were missing.
+        // appdir resolver. Treat as if appname were missing.
     }
     return 'firefox';
 }
 /**
  * Probes the obj-dir's `dist/` subtree for the absolute path the harness
  * would have computed if the manifest key had been honoured. Returns null
- * when no candidate exists — better to skip injection silently than to point
+ * when no candidate exists: better to skip injection silently than to point
  * the harness at a path that does not exist, which fails with a different
  * error than the original symptom and confuses triage.
  *
  * Probe order differs by host platform:
  *
- * - **macOS (`darwin`)**: prefer
- *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` FIRST, then fall
+ * - macOS (`darwin`): prefer
+ *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` first, then fall
  *   back to `<objDir>/dist/bin/<value>`. On macOS `dist/bin` is symlinked to
- *   `dist/<App>.app/Contents/MacOS/` (the *binaries* directory), so
- *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/` —
- *   NOT where `resource:///modules/` is rooted. Injecting that path looks
- *   successful in the log but points at a directory with no modules tree, so
- *   every `resource:///modules/…` import still throws.
- * - **non-macOS**: `dist/bin/<value>` first,
+ *   `dist/<App>.app/Contents/MacOS/` (the binaries directory), so
+ *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/`,
+ *   which is not where `resource:///modules/` is rooted. Injecting that path
+ *   looks successful in the log but points at a directory with no modules
+ *   tree, so every `resource:///modules/…` import still throws.
+ * - non-macOS: `dist/bin/<value>` first,
  *   `.app/Contents/Resources/<value>` as fallback.
  *
  * On both platforms the final `.app` fallback iterates every `*.app` entry
@@ -222,7 +222,7 @@ export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
 /**
  * Top-level resolver. Walks every test path, reads the nearest
  * xpcshell.toml, and returns the single absolute path to inject (or a
- * structured "no injection" outcome). Never throws — every fs / parse
+ * structured "no injection" outcome). Never throws: every fs / parse
  * error is folded into a `none` outcome so the test command always falls
  * through to the diagnostic hint instead of dying inside a helper.
  */
@@ -231,7 +231,7 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
         return { kind: 'none' };
     const objDirAbs = resolve(engineDir, objDirName);
     const appname = await readMozinfoAppname(objDirAbs);
-    // When appname IS "firefox" the upstream harness reads `firefox-appdir`
+    // When appname is "firefox" the upstream harness reads `firefox-appdir`
     // natively. Injecting in that case would be a no-op at best and an
     // override at worst, so bail out before doing any IO per-path.
     if (appname === 'firefox')
@@ -247,11 +247,11 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
             body = await readText(manifestPath);
         }
         catch {
-            // An unreadable manifest cannot declare an appdir; skip it and keep
+            // An unreadable manifest cannot declare an appdir. Skip it and keep
             // walking the remaining candidates.
             continue;
         }
-        // Operator already migrated — harness will read the appname-keyed
+        // Operator already migrated. The harness will read the appname-keyed
         // value directly. Nothing to do.
         if (parseAppdirFromToml(body, appnameKey) !== undefined)
             continue;

package/dist/src/core/xpcshell-profile-dir.d.ts

@@ -2,11 +2,11 @@ export declare const XPCSHELL_PROFILE_ENV_VAR = "XPCSHELL_TEST_PROFILE_DIR";
 /**
  * Runs `fn` with a fresh per-invocation xpcshell profile directory
  * injected into the environment, removing the directory afterwards
- * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
- * for the OS tmp reaper; the harness may still hold files briefly).
+ * (best-effort: a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper, and the harness may still hold files briefly).
  *
  * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
  * process environment) is respected verbatim: no directory is minted and
- * NOTHING is deleted — we never remove a directory we did not create.
+ * nothing is deleted, because we never remove a directory we did not create.
  */
 export declare function withXpcshellProfileDir<T>(baseEnv: Record<string, string> | undefined, fn: (env: Record<string, string>) => Promise<T>): Promise<T>;

package/dist/src/core/xpcshell-profile-dir.js

@@ -3,10 +3,10 @@
  * Per-invocation xpcshell profile directory.
  *
  * Firefox's xpcshell harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a
- * FIXED path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping
- * harness invocations — concurrent `fireforge test` processes, or future
- * verification-tree shards — corrupt each other's profiles. FireForge
- * never set the variable; this helper mints a fresh `mkdtemp` directory
+ * fixed path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping
+ * harness invocations (concurrent `fireforge test` processes, or future
+ * verification-tree shards) corrupt each other's profiles. FireForge
+ * never set the variable. This helper mints a fresh `mkdtemp` directory
  * per harness invocation and exports it through the mach env channel.
  */
 import { mkdtemp, rm } from 'node:fs/promises';
@@ -18,12 +18,12 @@ export const XPCSHELL_PROFILE_ENV_VAR = 'XPCSHELL_TEST_PROFILE_DIR';
 /**
  * Runs `fn` with a fresh per-invocation xpcshell profile directory
  * injected into the environment, removing the directory afterwards
- * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
- * for the OS tmp reaper; the harness may still hold files briefly).
+ * (best-effort: a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper, and the harness may still hold files briefly).
  *
  * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
  * process environment) is respected verbatim: no directory is minted and
- * NOTHING is deleted — we never remove a directory we did not create.
+ * nothing is deleted, because we never remove a directory we did not create.
  */
 export async function withXpcshellProfileDir(baseEnv, fn) {
     const operatorProvided = baseEnv?.[XPCSHELL_PROFILE_ENV_VAR] ?? process.env[XPCSHELL_PROFILE_ENV_VAR];

package/dist/src/errors/base.d.ts

@@ -26,7 +26,7 @@ export declare abstract class FireForgeError extends Error {
  * Numbering is derived from the array rather than written into each string.
  * Several classes vary their advice by context (`FurnaceError` drops the
  * validate step, `ChecksumMismatchError` adds a Developer Edition note), and
- * hand-numbered branches had to renumber every later step by hand — one
+ * hand-numbered branches had to renumber every later step by hand, one
  * conditional away from printing "2." twice.
  *
  * @param steps - The remedy lines, in order, without their numbers
@@ -48,8 +48,8 @@ export declare class GeneralError extends FireForgeError {
  * kebab-case refusal class that the `FIREFORGE-VERDICT:` line reports as an
  * additive `note=` key. Without it every preflight refusal reached an
  * unattended reader as the single token `reason=preflight`, which covers
- * everything from a missing build to a peer's packaging record — so the one
- * line that survives a truncating pipe could not say WHICH gate fired.
+ * everything from a missing build to a peer's packaging record, so the one
+ * line that survives a truncating pipe could not say which gate fired.
  */
 export declare class PreflightRefusalError extends GeneralError {
     /** Stable refusal class, e.g. `stale-browser`. */
@@ -59,7 +59,7 @@ export declare class PreflightRefusalError extends GeneralError {
     note: string);
 }
 /**
- * Raised when one of FireForge's own internal invariants did not hold —
+ * Raised when one of FireForge's own internal invariants did not hold:
  * the failure of a runtime assertion from `src/utils/assert.ts`.
  *
  * Dedicated subclass (rather than raw GeneralError) because an invariant
@@ -68,12 +68,12 @@ export declare class PreflightRefusalError extends GeneralError {
  * fix. That difference is worth carrying all the way to the exit status
  * (see {@link ExitCode.INTERNAL_ERROR}) so a CI job can escalate it
  * instead of retrying it, and it is the one error class the CLI boundary
- * prints a stack trace for — the stack is the report.
+ * prints a stack trace for, since the stack is the report.
  *
  * Assertions exist so that a violated invariant stops the run at the
  * first inconsistency instead of continuing to write. In the mutating
  * paths that means the surrounding rollback journal restores the engine
- * before this reaches the operator; see `docs/lifecycle-invariants.md`.
+ * before this reaches the operator. See `docs/lifecycle-invariants.md`.
  */
 export declare class InternalInvariantError extends FireForgeError {
     readonly code: 11;
@@ -81,7 +81,7 @@ export declare class InternalInvariantError extends FireForgeError {
 }
 /**
  * Raised when a legacy regex/brace-depth fallback parser decides it
- * cannot safely perform its mutation — e.g. because a block it expected
+ * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.
  *
@@ -113,9 +113,10 @@ export declare class InvalidArgumentError extends FireForgeError {
  *
  * Every `exec*` helper in `src/utils/process.ts` rejects with this type
  * instead of Node's bare `AbortError: The operation was aborted`, which
- * carries no command name, no elapsed time, and no hint that a timeout —
- * not the command — was responsible. See {@link GitIndexingTimeoutError} in
- * errors/git.ts for the git-specific variant.
+ * carries no command name, no elapsed time, and no hint that a timeout
+ * (rather than the command) was responsible. See
+ * {@link GitIndexingTimeoutError} in errors/git.ts for the git-specific
+ * variant.
  */
 export declare class ExecTimeoutError extends FireForgeError {
     /** Executable that was spawned (argv[0]). */
@@ -142,12 +143,12 @@ export declare class ExecTimeoutError extends FireForgeError {
     /**
      * The last few lines the command printed before it was killed, so an
      * operator can see what it was doing (a `git add -A` stuck on one path,
-     * a build step that hung) instead of a bare budget number. Prefers
-     * stderr; falls back to stdout when stderr is silent.
+     * a build step that hung) instead of a bare budget number. It prefers
+     * stderr and falls back to stdout when stderr is silent.
      */
     private outputTailForUser;
 }
-/** Output captured before an exec timeout fired; see {@link ExecTimeoutError}. */
+/** Output captured before an exec timeout fired. See {@link ExecTimeoutError}. */
 export interface ExecTimeoutOutput {
     stdout: string;
     stderr: string;
@@ -160,12 +161,12 @@ export interface ExecTimeoutOutput {
  * Dedicated subclass so the CLI boundary renders lock contention as the
  * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
  * is treated by `withErrorHandling` as an internal failure and printed with
- * a five-frame stack — a correct refusal that looks like a crash.
+ * a five-frame stack: a correct refusal that looks like a crash.
  *
  * Exit code 15, not 1: the run never started. A script that retries on
  * failure wants to re-queue this one, not treat it as a failure of the work
  * it asked for. Every lock in FireForge shares the class and therefore the
- * code — the fact is the same whichever lock was contended.
+ * code, because the fact is the same whichever lock was contended.
  */
 export declare class LockContentionError extends FireForgeError {
     readonly code: 15;
@@ -177,19 +178,19 @@ export declare class LockContentionError extends FireForgeError {
  *
  * Dedicated subclass for its exit code alone: as a `GeneralError` this
  * refusal exited 1 beside real test failures' 5, and a summary line reading
- * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
- * kind of fact. They are opposites — one suite failed, the other's result
- * was discarded — and only a distinct code makes "unknown, re-run"
+ * `FAIL, exit 1` next to `FAIL, exit 5` invites treating them as the same
+ * kind of fact. They are opposites (one suite failed, the other's result
+ * was discarded) and only a distinct code makes "unknown, re-run"
  * mechanically separable from "red".
  */
 export declare class InconclusiveVerdictError extends FireForgeError {
     readonly code: 14;
 }
 /**
- * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Error thrown when the user interrupts an interactive prompt: Esc or
  * Ctrl+C, i.e. `isCancel(...)`.
  *
- * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * Not for a prompt the operator answered "no" to: 130 is
  * 128+SIGINT, which claims an interrupt. A declined confirmation is a
  * successful run that chose not to proceed, and exits 0.
  */
@@ -208,7 +209,7 @@ export declare class ResolutionError extends FireForgeError {
  * without calling process.exit() from shared library code.
  *
  * The user-visible error message has already been logged by the time this
- * is thrown — the entrypoint only needs to read `.exitCode` and terminate.
+ * is thrown. The entrypoint only needs to read `.exitCode` and terminate.
  */
 export declare class CommandError extends Error {
     readonly exitCode: ExitCode;

package/dist/src/errors/base.js

@@ -18,7 +18,7 @@ export class FireForgeError extends Error {
             this.cause = cause;
         }
         // Trims the constructor frames off the stack. `engines` pins Node >= 22,
-        // so the V8-only `captureStackTrace` is always present — the former
+        // so the V8-only `captureStackTrace` is always present. The former
         // `typeof === 'function'` guard was an unreachable branch that coverage
         // could never close.
         Error.captureStackTrace(this, this.constructor);
@@ -38,7 +38,7 @@ export class FireForgeError extends Error {
  * Numbering is derived from the array rather than written into each string.
  * Several classes vary their advice by context (`FurnaceError` drops the
  * validate step, `ChecksumMismatchError` adds a Developer Edition note), and
- * hand-numbered branches had to renumber every later step by hand — one
+ * hand-numbered branches had to renumber every later step by hand, one
  * conditional away from printing "2." twice.
  *
  * @param steps - The remedy lines, in order, without their numbers
@@ -62,8 +62,8 @@ export class GeneralError extends FireForgeError {
  * kebab-case refusal class that the `FIREFORGE-VERDICT:` line reports as an
  * additive `note=` key. Without it every preflight refusal reached an
  * unattended reader as the single token `reason=preflight`, which covers
- * everything from a missing build to a peer's packaging record — so the one
- * line that survives a truncating pipe could not say WHICH gate fired.
+ * everything from a missing build to a peer's packaging record, so the one
+ * line that survives a truncating pipe could not say which gate fired.
  */
 export class PreflightRefusalError extends GeneralError {
     note;
@@ -75,7 +75,7 @@ export class PreflightRefusalError extends GeneralError {
     }
 }
 /**
- * Raised when one of FireForge's own internal invariants did not hold —
+ * Raised when one of FireForge's own internal invariants did not hold:
  * the failure of a runtime assertion from `src/utils/assert.ts`.
  *
  * Dedicated subclass (rather than raw GeneralError) because an invariant
@@ -84,12 +84,12 @@ export class PreflightRefusalError extends GeneralError {
  * fix. That difference is worth carrying all the way to the exit status
  * (see {@link ExitCode.INTERNAL_ERROR}) so a CI job can escalate it
  * instead of retrying it, and it is the one error class the CLI boundary
- * prints a stack trace for — the stack is the report.
+ * prints a stack trace for, since the stack is the report.
  *
  * Assertions exist so that a violated invariant stops the run at the
  * first inconsistency instead of continuing to write. In the mutating
  * paths that means the surrounding rollback journal restores the engine
- * before this reaches the operator; see `docs/lifecycle-invariants.md`.
+ * before this reaches the operator. See `docs/lifecycle-invariants.md`.
  */
 export class InternalInvariantError extends FireForgeError {
     code = ExitCode.INTERNAL_ERROR;
@@ -107,7 +107,7 @@ export class InternalInvariantError extends FireForgeError {
 }
 /**
  * Raised when a legacy regex/brace-depth fallback parser decides it
- * cannot safely perform its mutation — e.g. because a block it expected
+ * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.
  *
@@ -150,9 +150,10 @@ export class InvalidArgumentError extends FireForgeError {
  *
  * Every `exec*` helper in `src/utils/process.ts` rejects with this type
  * instead of Node's bare `AbortError: The operation was aborted`, which
- * carries no command name, no elapsed time, and no hint that a timeout —
- * not the command — was responsible. See {@link GitIndexingTimeoutError} in
- * errors/git.ts for the git-specific variant.
+ * carries no command name, no elapsed time, and no hint that a timeout
+ * (rather than the command) was responsible. See
+ * {@link GitIndexingTimeoutError} in errors/git.ts for the git-specific
+ * variant.
  */
 export class ExecTimeoutError extends FireForgeError {
     command;
@@ -189,8 +190,8 @@ export class ExecTimeoutError extends FireForgeError {
     /**
      * The last few lines the command printed before it was killed, so an
      * operator can see what it was doing (a `git add -A` stuck on one path,
-     * a build step that hung) instead of a bare budget number. Prefers
-     * stderr; falls back to stdout when stderr is silent.
+     * a build step that hung) instead of a bare budget number. It prefers
+     * stderr and falls back to stdout when stderr is silent.
      */
     outputTailForUser() {
         const source = this.stderr.trim().length > 0 ? this.stderr : this.stdout;
@@ -216,12 +217,12 @@ const EXEC_TIMEOUT_TAIL_LINES = 20;
  * Dedicated subclass so the CLI boundary renders lock contention as the
  * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
  * is treated by `withErrorHandling` as an internal failure and printed with
- * a five-frame stack — a correct refusal that looks like a crash.
+ * a five-frame stack: a correct refusal that looks like a crash.
  *
  * Exit code 15, not 1: the run never started. A script that retries on
  * failure wants to re-queue this one, not treat it as a failure of the work
  * it asked for. Every lock in FireForge shares the class and therefore the
- * code — the fact is the same whichever lock was contended.
+ * code, because the fact is the same whichever lock was contended.
  */
 export class LockContentionError extends FireForgeError {
     code = ExitCode.LOCK_TIMEOUT;
@@ -233,19 +234,19 @@ export class LockContentionError extends FireForgeError {
  *
  * Dedicated subclass for its exit code alone: as a `GeneralError` this
  * refusal exited 1 beside real test failures' 5, and a summary line reading
- * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
- * kind of fact. They are opposites — one suite failed, the other's result
- * was discarded — and only a distinct code makes "unknown, re-run"
+ * `FAIL, exit 1` next to `FAIL, exit 5` invites treating them as the same
+ * kind of fact. They are opposites (one suite failed, the other's result
+ * was discarded) and only a distinct code makes "unknown, re-run"
  * mechanically separable from "red".
  */
 export class InconclusiveVerdictError extends FireForgeError {
     code = ExitCode.INCONCLUSIVE;
 }
 /**
- * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Error thrown when the user interrupts an interactive prompt: Esc or
  * Ctrl+C, i.e. `isCancel(...)`.
  *
- * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * Not for a prompt the operator answered "no" to: 130 is
  * 128+SIGINT, which claims an interrupt. A declined confirmation is a
  * successful run that chose not to proceed, and exits 0.
  */
@@ -266,7 +267,7 @@ export class ResolutionError extends FireForgeError {
  * without calling process.exit() from shared library code.
  *
  * The user-visible error message has already been logged by the time this
- * is thrown — the entrypoint only needs to read `.exitCode` and terminate.
+ * is thrown. The entrypoint only needs to read `.exitCode` and terminate.
  */
 export class CommandError extends Error {
     exitCode;

package/dist/src/errors/build.d.ts

@@ -10,19 +10,19 @@ export declare class BuildError extends FireForgeError {
     get userMessage(): string;
 }
 /**
- * A test SUITE went red — assertions failed, or sharded runs did not all
- * pass. Distinct from its {@link BuildError} parent only in what it TELLS
- * the operator, deliberately not in its exit code: `docs/exit-codes.md`
+ * A test suite went red: assertions failed, or sharded runs did not all
+ * pass. Distinct from its {@link BuildError} parent only in what it tells
+ * the operator, and not in its exit code: `docs/exit-codes.md`
  * documents 5 as "a suite that FAILED", and consumers key CI on it.
  *
- * The parent's remedies are all build remedies — "check the build output",
- * "fireforge bootstrap", "delete obj-* directories" — and none of them apply
+ * The parent's remedies are all build remedies ("check the build output",
+ * "fireforge bootstrap", "delete obj-* directories") and none of them apply
  * to a failing assertion. Worse, the first points at the wrong half of the
  * log, which is exactly the half a `tail` keeps. Ground truth for a test red
  * is the harness's own output, so the remedies here name the failing tests,
  * the `FIREFORGE-VERDICT:` line, and the run log that survives a pipe.
  *
- * Note that `machineErrorCode` derives the `--json` error code from the class
+ * `machineErrorCode` derives the `--json` error code from the class
  * name, so this reports as `test-failure` rather than `build`.
  */
 export declare class TestFailureError extends BuildError {

package/dist/src/errors/build.js

@@ -22,19 +22,19 @@ export class BuildError extends FireForgeError {
     }
 }
 /**
- * A test SUITE went red — assertions failed, or sharded runs did not all
- * pass. Distinct from its {@link BuildError} parent only in what it TELLS
- * the operator, deliberately not in its exit code: `docs/exit-codes.md`
+ * A test suite went red: assertions failed, or sharded runs did not all
+ * pass. Distinct from its {@link BuildError} parent only in what it tells
+ * the operator, and not in its exit code: `docs/exit-codes.md`
  * documents 5 as "a suite that FAILED", and consumers key CI on it.
  *
- * The parent's remedies are all build remedies — "check the build output",
- * "fireforge bootstrap", "delete obj-* directories" — and none of them apply
+ * The parent's remedies are all build remedies ("check the build output",
+ * "fireforge bootstrap", "delete obj-* directories") and none of them apply
  * to a failing assertion. Worse, the first points at the wrong half of the
  * log, which is exactly the half a `tail` keeps. Ground truth for a test red
  * is the harness's own output, so the remedies here name the failing tests,
  * the `FIREFORGE-VERDICT:` line, and the run log that survives a pipe.
  *
- * Note that `machineErrorCode` derives the `--json` error code from the class
+ * `machineErrorCode` derives the `--json` error code from the class
  * name, so this reports as `test-failure` rather than `build`.
  */
 export class TestFailureError extends BuildError {