@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/types/config.d.ts

@@ -56,7 +56,7 @@ export interface ExternalToolRequirement {
     path?: string;
     /** Resolve the tool with `xcrun -find <name>` instead of PATH. */
     xcrun?: boolean;
-    /** Missing tool is an error by default; set false for advisory probes. */
+    /** Missing tool is an error by default. Set false for advisory probes. */
     required?: boolean;
 }
 /** Named group of project-specific external asset/build tools. */
@@ -158,14 +158,14 @@ export interface FireForgeConfig {
 /**
  * Configuration for the `fireforge typecheck` command. Distinct from
  * `patchLint.checkJs`: patch-lint runs every time `fireforge lint` runs
- * and is scoped to patch-owned `.sys.mjs`; typecheck runs whole projects
+ * and is scoped to patch-owned `.sys.mjs`. Typecheck runs whole projects
  * the operator points at via `projects` and is intended as a CI gate.
  */
 export interface TypecheckConfig {
     /**
      * Project-relative paths to jsconfig.json (or tsconfig.json) files
      * the typecheck command should run. Must be non-empty when the
-     * `typecheck` block is present — an empty array would silently turn
+     * `typecheck` block is present. An empty array would silently turn
      * the command into a no-op.
      */
     projects: string[];
@@ -174,14 +174,15 @@ export interface TypecheckConfig {
      * contents are concatenated to the built-in `FIREFOX_GLOBALS_SHIM`.
      * Lets projects declare component patterns like `MozLitElement` /
      * `MozXULElement` once instead of per-file. Concat order is
-     * built-in shim first, extraShim second — augment, don't redeclare.
+     * built-in shim first, extraShim second: augment, don't redeclare.
      */
     extraShim?: string;
     /**
      * Per-project override of {@link extraShim}, keyed by the project's path
      * exactly as it appears in {@link projects}. A string value points the
-     * project at a different `.d.ts`; `null` opts the project out of the shared
-     * extra shim entirely (it absorbs only the built-in Firefox globals shim).
+     * project at a different `.d.ts`. `null` opts the project out of the
+     * shared extra shim entirely (it absorbs only the built-in Firefox globals
+     * shim).
      *
      * Needed because the shared shim is injected into every project: a shim hub
      * that references Gecko declaration libs (`lib.gecko.dom.d.ts`, …) is wanted
@@ -194,7 +195,7 @@ export interface TypecheckConfig {
      * How to report undefined free identifiers (TS2304/TS2552). Default
      * `'warning'`: visible without failing the gate, since shim gaps produce
      * the same diagnostic as a genuine missing import. `'error'` makes them
-     * blocking; `'off'` suppresses them.
+     * blocking. `'off'` suppresses them.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
@@ -202,13 +203,13 @@ export interface TypecheckConfig {
  * Wire command configuration.
  */
 /**
- * One deliberately-unpackaged source, declared so the post-build audit stops
- * reporting it as a missing registration.
+ * One intentionally unpackaged source, declared so the post-build audit
+ * stops reporting it as a missing registration.
  *
  * `reason` is required and must be non-empty. A carve-out whose rationale
  * nobody wrote down is indistinguishable from a mistake by the time someone
  * reads it, and this is the one audit class FireForge cannot derive from the
- * tree — the file's own header may say "never loaded", but nothing in
+ * tree: the file's own header may say "never loaded", but nothing in
  * `moz.build` or `jar.mn` records that.
  */
 export interface BuildAuditUnpackagedDeclaration {
@@ -220,9 +221,9 @@ export interface BuildAuditUnpackagedDeclaration {
 /** Post-build packaging audit configuration. */
 export interface BuildAuditConfig {
     /**
-     * Sources the audit must treat as deliberately unpackaged. Admitted paths
-     * are LISTED in the audit output rather than silenced, and one that DOES
-     * resolve to a packaged artifact is reported as a stale carve-out.
+     * Sources the audit must treat as intentionally unpackaged. Admitted
+     * paths are listed in the audit output rather than silenced, and one that
+     * does resolve to a packaged artifact is reported as a stale carve-out.
      */
     unpackaged?: BuildAuditUnpackagedDeclaration[];
 }
@@ -231,7 +232,7 @@ export interface WireConfig {
     subscriptDir?: string;
 }
 /**
- * Severity gate for opt-in patch-lint rules. `'off'` disables the rule;
+ * Severity gate for opt-in patch-lint rules. `'off'` disables the rule.
  * `'warning'` and `'error'` emit issues at the matching severity.
  */
 export type PatchLintSeverityGate = 'off' | 'warning' | 'error';
@@ -242,7 +243,7 @@ export type PatchLintSeverityGate = 'off' | 'warning' | 'error';
  *
  * Boolean flags tighten the strict preset. The optional `paths` mapping
  * (each pattern may carry a single `*`) lets patch-owned modules be typed
- * from their real sources — e.g. `"resource:///modules/foo/*": ["./*"]` —
+ * from their real sources (e.g. `"resource:///modules/foo/*": ["./*"]`),
  * resolved host-side against the engine directory, so no `baseUrl` is set
  * (TS5090-safe) and no hand-generated ambient stub shim is needed. Other
  * options (`rootDir`, etc.) stay disallowed: they would fight the
@@ -263,10 +264,10 @@ export interface PatchLintCheckJsCompilerOptions {
 /**
  * Line-count thresholds for one `file-too-large` tier.
  *
- * Every field is optional; an omitted field keeps the built-in default.
+ * Every field is optional. An omitted field keeps the built-in default.
  * The three must stay ordered `notice <= warning <= error`, which the
- * config validator enforces — an out-of-order triple silently disables a
- * band rather than failing anything.
+ * config validator enforces, because an out-of-order triple silently
+ * disables a band rather than failing anything.
  */
 export interface PatchLintFileSizeTier {
     notice?: number;
@@ -303,7 +304,7 @@ export interface PatchLintConfig {
      */
     checkJsStrict?: boolean;
     /**
-     * Boolean overrides merged after the strict preset; only valid when
+     * Boolean overrides merged after the strict preset. Only valid when
      * `checkJsStrict` is true. Requires `checkJs: true`.
      */
     checkJsCompilerOptions?: PatchLintCheckJsCompilerOptions;
@@ -357,16 +358,16 @@ export interface PatchLintConfig {
      * `Services.scriptloader.loadSubScript`, e.g.
      * `browser/base/content/<binaryName>*.js`). Distinct from
      * `jsdocClassMethods` because chrome subscripts are parsed as scripts,
-     * not ES modules — using one flag for both would silently disable the
+     * not ES modules. Using one flag for both would silently disable the
      * rule when a chrome subscript was fed to the module parser. Default:
      * 'off'.
      */
     chromeScriptJsDoc?: PatchLintSeverityGate;
     /**
      * How the checkJs pass reports undefined free identifiers
-     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`;
-     * the two flows share the suppression policy so a patch
-     * cannot pass one and fail the other. Default: 'warning'.
+     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`.
+     * The two flows share the suppression policy so a patch cannot pass one
+     * and fail the other. Default: 'warning'.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }

package/dist/src/types/furnace.d.ts

@@ -47,7 +47,7 @@ export interface CustomComponentConfig {
     /** Whether to register in customElements.js */
     register: boolean;
     /**
-     * What the component IS. `'element'` (the default when unset) is a custom
+     * What the component is. `'element'` (the default when unset) is a custom
      * element with its own tag. `'library'` is a base class + helpers module
      * that defines no element of its own (e.g. a shared MozLitElement
      * subclass other components extend): `furnace validate` skips the
@@ -55,7 +55,7 @@ export interface CustomComponentConfig {
      * and the `missing-css` structural advisory for it, while headers, module
      * shape, `relative-import`, and (when a `.css` exists) the CSS
      * compatibility rules still apply. A library exports no element, so
-     * `kind: "library"` requires `register: false` — the combination with
+     * `kind: "library"` requires `register: false`. The combination with
      * `register: true` is rejected at config parse time.
      */
     kind?: 'element' | 'library';
@@ -85,18 +85,18 @@ export interface CustomComponentConfig {
      * participates in, in the same form used by `insertFTLIfNeeded` (for
      * example `browser/mybrowser-dock.ftl`). When set:
      *
-     *   - `furnace create --localized` does NOT scaffold a per-component
-     *     `.ftl` stub — the component shares the feature bundle.
+     *   - `furnace create --localized` does not scaffold a per-component
+     *     `.ftl` stub. The component shares the feature bundle.
      *   - The generated `.mjs` calls `insertFTLIfNeeded("<sharedFtl>")` at
      *     the shared path instead of the per-component one.
      *   - `furnace validate`'s `missing-ftl` structural rule is skipped for
      *     the component (there is no `<tag>.ftl` to require).
-     *   - `furnace apply` does NOT copy a per-component `.ftl` into the FTL
-     *     tree nor register a new entry in the locale `jar.mn` — the shared
+     *   - `furnace apply` does not copy a per-component `.ftl` into the FTL
+     *     tree nor register a new entry in the locale `jar.mn`. The shared
      *     file is owned by whoever authored the feature bundle.
      *
      * Requires `localized: true`. Mutually exclusive with the per-component
-     * `.ftl` scaffold. Does NOT auto-migrate previous per-component FTL
+     * `.ftl` scaffold. Does not auto-migrate previous per-component FTL
      * state: flipping an existing component onto `sharedFtl` leaves the
      * prior per-component entry in the engine tree and the locale `jar.mn`
      * until explicitly cleaned up.
@@ -120,12 +120,12 @@ export interface FurnaceConfig {
      * variables the fork does not own. `token coverage` counts matches as
      * `allowlisted` rather than `unknown` so a copied upstream baseline does
      * not drag fork-owned coverage percentages down. Defaults to `['--moz-']`
-     * when unset; pass an explicit empty array to count every prefix.
+     * when unset. Pass an explicit empty array to count every prefix.
      */
     platformPrefixes?: string[];
     /**
-     * Custom properties used as runtime state channels — written and read by the
-     * component itself (e.g. per-frame camera/tile positions) rather than
+     * Custom properties used as runtime state channels, written and read by
+     * the component itself (e.g. per-frame camera/tile positions) rather than
      * consumed as design tokens. Listed names are exempt from the
      * `token-prefix-violation` check even when they do not match `tokenPrefix`
      * and are not in `tokenAllowlist`. Use this for cross-component runtime
@@ -139,7 +139,7 @@ export interface FurnaceConfig {
      * the tokens CSS file is `<link>`ed. Forks with multiple chrome host
      * documents (e.g. `mybrowser.xhtml` beside the stock `browser.xhtml`) should
      * list every document that may own the link. When omitted, defaults to
-     * `['browser/base/content/browser.xhtml']` — the upstream Firefox path.
+     * `['browser/base/content/browser.xhtml']`, the upstream Firefox path.
      */
     tokenHostDocuments?: string[];
     /**
@@ -157,7 +157,7 @@ export interface FurnaceConfig {
      * `compilerOptions.paths` entries for deployed component modules
      * (`chrome://global/content/elements/<file>.mjs`) Furnace keeps in sync
      * on deploy. Only entries under that chrome prefix that map into
-     * `components/custom/` are managed; everything else is preserved.
+     * `components/custom/` are managed. Everything else is preserved.
      * Unset disables jsconfig maintenance.
      */
     typecheckJsconfig?: string;
@@ -189,11 +189,11 @@ export type FurnacePendingRepairOperation = (typeof FURNACE_PENDING_REPAIR_OPERA
  * out-of-band from what the state file records.
  */
 export interface FurnacePendingRepair {
-    /** The operation that failed to clean up; used by doctor to route the fix. */
+    /** The operation that failed to clean up. Doctor uses it to route the fix. */
     operation: FurnacePendingRepairOperation;
     /** ISO timestamp of when the repair marker was written. */
     timestamp: string;
-    /** Human-readable summary of the failure; shown by doctor. */
+    /** Human-readable summary of the failure. Doctor shows it. */
     reason: string;
 }
 /**
@@ -259,13 +259,13 @@ export interface ApplyResult {
     /**
      * Set to true when the rollback journal was restored after a partial failure.
      * When true, entries in `applied` reflect what was attempted, not what
-     * persisted — the engine has been restored to its pre-apply state.
+     * persisted. The engine has been restored to its pre-apply state.
      */
     rolledBack?: boolean;
     /**
      * Operator-facing warnings, printed by `logApplyResult`. Populated when
      * apply overwrote a deployed, patch-owned file whose engine bytes
-     * differed from the component source — the case where a
+     * differed from the component source, which is the case where a
      * shipped engine-only fix is silently reverted by the copy.
      */
     warnings?: string[];
@@ -331,7 +331,7 @@ export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'no
  * caller is never asked to invent a value it does not have.
  */
 export interface ComponentApplyContext {
-    /** Project root — what registration consistency resolves against. */
+    /** Project root, what registration consistency resolves against. */
     root: string;
     /** Firefox source directory the component deploys into. */
     engineDir: string;

package/dist/src/types/json.d.ts

@@ -1,8 +1,8 @@
 /**
  * Domain types for raw JSON documents (fireforge.json, furnace.json).
  *
- * FireForge deliberately reads and writes some documents in their raw,
- * unvalidated form — e.g. `fireforge config --force` round-trips keys that
+ * FireForge reads and writes some documents in their raw, unvalidated
+ * form. For example, `fireforge config --force` round-trips keys that
  * the validated `FireForgeConfig` schema would strip. These types give that
  * pipeline a concrete value contract: every value is JSON data, never a
  * function, class instance, symbol, or other non-serializable runtime value.
@@ -14,7 +14,7 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObj
 /**
  * A JSON object node. `undefined` is admitted as a property value (not a
  * `JsonValue`) so in-memory documents can be built field-by-field from
- * optional inputs; `JSON.stringify` drops such properties on write, exactly
+ * optional inputs. `JSON.stringify` drops such properties on write, exactly
  * like an absent key.
  */
 export interface JsonObject {

package/dist/src/types/json.js

@@ -2,8 +2,8 @@
 /**
  * Domain types for raw JSON documents (fireforge.json, furnace.json).
  *
- * FireForge deliberately reads and writes some documents in their raw,
- * unvalidated form — e.g. `fireforge config --force` round-trips keys that
+ * FireForge reads and writes some documents in their raw, unvalidated
+ * form. For example, `fireforge config --force` round-trips keys that
  * the validated `FireForgeConfig` schema would strip. These types give that
  * pipeline a concrete value contract: every value is JSON data, never a
  * function, class instance, symbol, or other non-serializable runtime value.

package/dist/src/types/typecheck.d.ts

@@ -23,9 +23,9 @@ export interface TypecheckIssue {
     /** Raw TypeScript diagnostic code (e.g. 2322 for a type mismatch). */
     code: number;
     /**
-     * Severity bucket — TS reports `Suggestion` and `Message` categories
-     * too, but `runTypecheck` collapses both into `'warning'` so the CLI
-     * has only two visible levels.
+     * Severity bucket. TS also reports `Suggestion` and `Message`
+     * categories, but `runTypecheck` collapses both into `'warning'` so
+     * the CLI has only two visible levels.
      */
     category: 'error' | 'warning';
     /** Human-readable message text (already flattened from chains). */

package/dist/src/utils/assert.d.ts

@@ -2,7 +2,7 @@
  * A failure description, or a thunk producing one.
  *
  * The thunk form exists so a hot call site pays nothing on the passing
- * path — `assert(ok, () => \`bad state: ${JSON.stringify(x)}\`)` builds
+ * path: `assert(ok, () => \`bad state: ${JSON.stringify(x)}\`)` builds
  * the string only when the assertion actually fails, where a plain
  * template literal would build it on every call.
  */

package/dist/src/utils/assert.js

@@ -2,17 +2,17 @@
 /**
  * Runtime assertions for FireForge's own internal invariants.
  *
- * These check state that FireForge itself established — a journal was
+ * These check state that FireForge itself established: a journal was
  * registered before the first mutation, a lock is held before a write,
- * manifest ordering is contiguous after a renumber. They are NOT input
- * validation: anything derived from user input, the filesystem, or a
+ * manifest ordering is contiguous after a renumber. They are not input
+ * validation. Anything derived from user input, the filesystem, or a
  * subprocess belongs in a typed error from `src/errors/` with a
  * `userMessage` that tells the operator what to do. An assertion failure
- * says the opposite — that nothing the operator could have done would
- * have prevented it.
+ * says the opposite: nothing the operator could have done would have
+ * prevented it.
  *
  * Every check routes through a helper here rather than being open-coded
- * as `if (!condition) throw`. That is deliberate: an inline throw adds a
+ * as `if (!condition) throw`. An inline throw adds a
  * permanently-uncovered branch to every function it appears in, and the
  * per-module coverage floors in `scripts/check-coverage-thresholds.mjs`
  * would pay for it in ~40 places. Routed through a call, the branch lives

package/dist/src/utils/build-info.d.ts

@@ -3,7 +3,7 @@ interface BuildIdentity {
     shortCommit: string;
     dirty: boolean;
     /**
-     * Content hash of the uncommitted diff, present only for a DIRTY installed
+     * Content hash of the uncommitted diff, present only for a dirty installed
      * build. Two packs from the same HEAD with different uncommitted content
      * share `shortCommit` and the `.dirty` marker, so without this they report
      * byte-identical `--version` strings and a report against
@@ -13,15 +13,15 @@ interface BuildIdentity {
      */
     dirtyHash?: string;
 }
-/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+/** @internal Reads the stamped dist/build-info.json. Null when absent/invalid. */
 export declare function readBuildInfoFile(packageRoot: string): BuildIdentity | null;
 type GitRunner = (args: string[]) => string;
-/** @internal Live git identity of the checkout; null when git is unusable. */
+/** @internal Live git identity of the checkout. Null when git is unusable. */
 export declare function readGitBuildIdentity(runGit?: GitRunner): BuildIdentity | null;
 /**
- * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`. Plain version on
  * null identity. The trailing content hash appears only for a dirty
- * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * installed build, where `dist/build-info.json` already carries it. Every
  * segment stays valid semver build metadata (dot-separated alphanumerics).
  */
 export declare function formatVersionWithIdentity(version: string, identity: BuildIdentity | null): string;

package/dist/src/utils/build-info.js

@@ -6,14 +6,14 @@
  * fingerprinting tarballs by sha256 to know which build a claim was verified
  * against. `--version` reports `<semver>+g<short-sha>[.dirty[.<content-hash>]]`:
  *
- * - In a git checkout (dev runs via tsx), identity comes from live git — a
+ * - In a git checkout (dev runs via tsx), identity comes from live git, so a
  *   stale `dist/build-info.json` from an old build must never win.
  * - In an installed package, it comes from `dist/build-info.json`, stamped
  *   by scripts/generate-build-info.mjs at build/pack time.
  * - When neither yields an identity, `--version` degrades to the plain
  *   semver. Reading identity must never throw.
  *
- * Deliberately NOT wired into the per-patch lint cache key: identity would
+ * Not wired into the per-patch lint cache key: identity would
  * churn the cache on every commit at the same semver for no correctness gain
  * (`getPackageVersion` stays the cache input).
  */
@@ -22,7 +22,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getPackageRoot, getPackageVersion } from './package-root.js';
 import { isObject } from './validation.js';
-/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+/** @internal Reads the stamped dist/build-info.json. Null when absent/invalid. */
 export function readBuildInfoFile(packageRoot) {
     try {
         const raw = readFileSync(join(packageRoot, 'dist', 'build-info.json'), 'utf-8');
@@ -49,7 +49,7 @@ const defaultGitRunner = (args) => execFileSync('git', args, {
     encoding: 'utf-8',
     stdio: ['ignore', 'pipe', 'ignore'],
 });
-/** @internal Live git identity of the checkout; null when git is unusable. */
+/** @internal Live git identity of the checkout. Null when git is unusable. */
 export function readGitBuildIdentity(runGit = defaultGitRunner) {
     try {
         const commit = runGit(['rev-parse', 'HEAD']).trim();
@@ -80,9 +80,9 @@ function getBuildIdentity() {
     }
 }
 /**
- * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`. Plain version on
  * null identity. The trailing content hash appears only for a dirty
- * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * installed build, where `dist/build-info.json` already carries it. Every
  * segment stays valid semver build metadata (dot-separated alphanumerics).
  */
 export function formatVersionWithIdentity(version, identity) {

package/dist/src/utils/child-env.d.ts

@@ -2,7 +2,7 @@
  * Environment construction for spawned children.
  *
  * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget; the logic belongs to the exec layer.
+ * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /** The `env` / `envUnset` slice of exec options this module needs. */
 interface ChildEnvOptions {
@@ -15,13 +15,13 @@ interface ChildEnvOptions {
  * The child's environment: `process.env`, with `env` merged over it, then
  * every `envUnset` key removed.
  *
- * One helper rather than five inline spreads — the removal step is easy to
+ * One helper rather than five inline spreads: the removal step is easy to
  * add at four of the five spawn sites and forget at the fifth, which would
  * make the option silently inert exactly where it was not tested.
  *
- * Removal is a real removal, not an assignment to `''`: mozbuild's
- * `is_running_under_coding_agent()` reads `CLAUDECODE` for its PRESENCE, so
- * an empty value would not unset it. `Reflect.deleteProperty` rather than
+ * Removal is a real removal rather than an assignment to `''`: mozbuild's
+ * `is_running_under_coding_agent()` reads `CLAUDECODE` only for its
+ * presence, so an empty value would not unset it. `Reflect.deleteProperty` rather than
  * `delete obj[key]` because the key is computed.
  *
  * @param options - Options carrying `env` / `envUnset`

package/dist/src/utils/child-env.js

@@ -3,19 +3,19 @@
  * Environment construction for spawned children.
  *
  * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget; the logic belongs to the exec layer.
+ * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /**
  * The child's environment: `process.env`, with `env` merged over it, then
  * every `envUnset` key removed.
  *
- * One helper rather than five inline spreads — the removal step is easy to
+ * One helper rather than five inline spreads: the removal step is easy to
  * add at four of the five spawn sites and forget at the fifth, which would
  * make the option silently inert exactly where it was not tested.
  *
- * Removal is a real removal, not an assignment to `''`: mozbuild's
- * `is_running_under_coding_agent()` reads `CLAUDECODE` for its PRESENCE, so
- * an empty value would not unset it. `Reflect.deleteProperty` rather than
+ * Removal is a real removal rather than an assignment to `''`: mozbuild's
+ * `is_running_under_coding_agent()` reads `CLAUDECODE` only for its
+ * presence, so an empty value would not unset it. `Reflect.deleteProperty` rather than
  * `delete obj[key]` because the key is computed.
  *
  * @param options - Options carrying `env` / `envUnset`

package/dist/src/utils/concurrency.d.ts

@@ -1,8 +1,8 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept deliberately tiny: one order-preserving
- * mapper, no queues, no cancellation.
+ * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
+ * queues, no cancellation.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/src/utils/concurrency.js

@@ -1,8 +1,8 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept deliberately tiny: one order-preserving
- * mapper, no queues, no cancellation.
+ * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
+ * queues, no cancellation.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export async function mapWithConcurrency(items, limit, fn) {

package/dist/src/utils/elapsed.js

@@ -6,7 +6,7 @@
  * `package` each hand-rolled the same minute/second split, so a change to
  * the format silently applied to some progress lines and not others.
  *
- * @param ms - Duration in milliseconds; negative input is clamped to zero.
+ * @param ms - Duration in milliseconds. Negative input is clamped to zero.
  * @returns The duration as `Xm Ys`, or `Ys` when under one minute.
  */
 function formatElapsed(ms) {

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

@@ -1,9 +1,9 @@
 /**
  * Throwable normalisation primitives.
  *
- * **This module must import nothing.** It sits at the very bottom of the
- * dependency graph — 81 modules across `core/`, `commands/`, `utils/` and
- * `bin/` reach it — so it is the one place a shared helper can live and be
+ * This module must import nothing. It sits at the very bottom of the
+ * dependency graph (81 modules across `core/`, `commands/`, `utils/` and
+ * `bin/` reach it), so it is the one place a shared helper can live and be
  * provably cycle-immune. Adding an import here makes that whole subtree
  * reachable from every util, and any future `src/errors/*` module wanting a
  * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
@@ -17,18 +17,18 @@ export declare function toError(error: unknown): Error;
  * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
  * unknown throwable, or `undefined` when the value carries no string `code`.
  *
- * The check is deliberately structural rather than `error instanceof Error`:
- * a plain object carrying `.code` — exactly the shape {@link toError} exists
- * to normalise — reaches errno consumers through rejected promises and
+ * The check is structural rather than `error instanceof Error`: a plain
+ * object carrying `.code` (exactly the shape {@link toError} exists to
+ * normalise) reaches errno consumers through rejected promises and
  * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
  * code".
  */
 export declare function getNodeErrorCode(error: unknown): string | undefined;
 /**
  * Checks whether a process with the given PID is still running, using
- * `kill(pid, 0)` — no signal is sent, only the existence check is performed.
+ * `kill(pid, 0)`: no signal is sent, only the existence check is performed.
  *
- * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
+ * Only `ESRCH` ("no such process") means dead. `EPERM` means alive: the
  * process exists but is owned by another uid, which happens routinely with
  * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
  * Reading EPERM as dead in a predicate that gates a recursive delete removes

package/dist/src/utils/errors.js

@@ -2,9 +2,9 @@
 /**
  * Throwable normalisation primitives.
  *
- * **This module must import nothing.** It sits at the very bottom of the
- * dependency graph — 81 modules across `core/`, `commands/`, `utils/` and
- * `bin/` reach it — so it is the one place a shared helper can live and be
+ * This module must import nothing. It sits at the very bottom of the
+ * dependency graph (81 modules across `core/`, `commands/`, `utils/` and
+ * `bin/` reach it), so it is the one place a shared helper can live and be
  * provably cycle-immune. Adding an import here makes that whole subtree
  * reachable from every util, and any future `src/errors/*` module wanting a
  * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
@@ -29,9 +29,9 @@ export function toError(error) {
  * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
  * unknown throwable, or `undefined` when the value carries no string `code`.
  *
- * The check is deliberately structural rather than `error instanceof Error`:
- * a plain object carrying `.code` — exactly the shape {@link toError} exists
- * to normalise — reaches errno consumers through rejected promises and
+ * The check is structural rather than `error instanceof Error`: a plain
+ * object carrying `.code` (exactly the shape {@link toError} exists to
+ * normalise) reaches errno consumers through rejected promises and
  * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
  * code".
  */
@@ -46,9 +46,9 @@ export function getNodeErrorCode(error) {
 }
 /**
  * Checks whether a process with the given PID is still running, using
- * `kill(pid, 0)` — no signal is sent, only the existence check is performed.
+ * `kill(pid, 0)`: no signal is sent, only the existence check is performed.
  *
- * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
+ * Only `ESRCH` ("no such process") means dead. `EPERM` means alive: the
  * process exists but is owned by another uid, which happens routinely with
  * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
  * Reading EPERM as dead in a predicate that gates a recursive delete removes

package/dist/src/utils/fs.d.ts

@@ -95,7 +95,7 @@ export declare function copyDir(src: string, dest: string): Promise<void>;
  * artefacts out of their listings without racing the rename.
  *
  * Intentionally anchored so a legitimately-named backup file like
- * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is not treated
  * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
  */
 export declare const FIREFORGE_TMP_PATH_PATTERN: RegExp;