@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/discard-baseline.js

@@ -3,15 +3,15 @@
  * Patch-aware restore planning for `fireforge discard`.
  *
  * The engine convention is: HEAD = pristine upstream Firefox, and the
- * applied patch queue lives as UNCOMMITTED worktree changes on top of it
+ * applied patch queue lives as uncommitted worktree changes on top of it
  * (`git apply` without `--index` → patch-edited tracked files are unstaged
  * modifications, patch-created files are untracked). A purely git-mechanical
- * discard — restore to HEAD, delete untracked files — therefore reverts
- * patch-backed files PAST their owning patch and deletes patch-created files
+ * discard (restore to HEAD, delete untracked files) therefore reverts
+ * patch-backed files past their owning patch and deletes patch-created files
  * outright.
  *
  * This module classifies each status entry against the patch manifest's
- * ownership claims and plans the correct restore target: the PATCH-APPLIED
+ * ownership claims and plans the correct restore target: the patch-applied
  * baseline (HEAD content folded through every affecting patch in order) for
  * claimed files, and the plain git mechanics for unmanaged ones.
  */
@@ -24,19 +24,19 @@ import { createPatchedContentContext } from './patch-apply.js';
 import { loadPatchesManifestState } from './patch-manifest-io.js';
 import { parseDiffSections } from './patch-parse.js';
 import { buildPatchClaims } from './status-classify.js';
-/** Builds an all-unmanaged plan set — the `--to-upstream` (legacy) shape. */
+/** Builds an all-unmanaged plan set, the `--to-upstream` (legacy) shape. */
 export function planUpstreamDiscards(entries) {
     return entries.map((entry) => ({ entry, kind: 'unmanaged', owners: [], conflicted: false }));
 }
 /**
  * Plans the restore target for each status entry. Entries claimed by the
- * patch manifest restore to the patch-applied baseline; unclaimed entries
+ * patch manifest restore to the patch-applied baseline. Unclaimed entries
  * keep the plain git mechanics. A missing patches dir or empty manifest
  * degrades every plan to `unmanaged`.
  *
- * A corrupt manifest or an unreconstructible patch baseline REFUSES with a
- * GeneralError naming `--to-upstream` — silently falling back to pristine
- * HEAD is exactly the data-loss path this module exists to close.
+ * A corrupt manifest or an unreconstructible patch baseline refuses with a
+ * GeneralError naming `--to-upstream`. Silently falling back to pristine
+ * HEAD is the data-loss path this module exists to close.
  */
 export async function planDiscardBaselines(patchesDir, engineDir, entries) {
     const state = await loadPatchesManifestState(patchesDir);
@@ -71,7 +71,7 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
     // `computePatchedContent` folds a deletion into an empty string (an
     // apply-to-content limitation), which is indistinguishable from a
     // legitimately empty file. Consult the owning patches' diff sections
-    // directly: the LAST section (highest-ordered owner) naming the path
+    // directly: the last section (highest-ordered owner) naming the path
     // decides whether the baseline is "absent".
     const sectionCache = new Map();
     const isDeletedAtBaseline = async (path, owners) => {
@@ -86,11 +86,10 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
                 }
                 catch (error) {
                     // Fail closed. Swallowing this yields no sections, which falls
-                    // through to `return false` — "not deleted at baseline" — so a path
-                    // the owning patch DELETES would be restored as present, i.e.
+                    // through to `return false` ("not deleted at baseline"), so a
+                    // path the owning patch deletes would be restored as present, i.e.
                     // rewritten instead of removed: silent data loss on the command
-                    // whose header promises a refusal for exactly this class of
-                    // failure.
+                    // whose header promises a refusal for this class of failure.
                     //
                     // `computeExpected` above reads the same patch first and refuses,
                     // so this is defence-in-depth against a TOCTOU (the patch file
@@ -160,7 +159,7 @@ export async function applyDiscardBaseline(engineDir, plan) {
     }
     const { entry } = plan;
     // Drop any staged edits/adds/renames first so the rewritten content is a
-    // plain worktree state (harmless when nothing is staged; skipped for
+    // plain worktree state (harmless when nothing is staged, and skipped for
     // purely-untracked entries which have no index footprint).
     if (!entry.isUntracked) {
         const indexPaths = entry.originalPath !== undefined ? [entry.file, entry.originalPath] : [entry.file];
@@ -172,7 +171,7 @@ export async function applyDiscardBaseline(engineDir, plan) {
     else {
         await writeText(join(engineDir, entry.file), plan.expectedContent);
     }
-    // A rename/copy's original side restores to ITS baseline too: the patch
+    // A rename/copy's original side restores to its baseline too: the patch
     // baseline when claimed, else the legacy HEAD restore (matching what
     // discardStatusEntry does for that side).
     if (entry.originalPath !== undefined) {
@@ -226,22 +225,22 @@ export function summarizeDiscardBaselines(plans, succeeded) {
     const deleted = plans.filter((p) => p.kind === 'patch-deleted').length;
     const unmanaged = plans.filter((p) => p.kind === 'unmanaged').length;
     if (patchBacked + created + deleted === 0) {
-        return `${String(succeeded)} file(s) restored to upstream state`;
+        return `${succeeded} file(s) restored to upstream state`;
     }
     const parts = [];
     if (patchBacked > 0)
-        parts.push(`${String(patchBacked)} to patch baseline`);
+        parts.push(`${patchBacked} to patch baseline`);
     if (created > 0)
-        parts.push(`${String(created)} re-materialized`);
+        parts.push(`${created} re-materialized`);
     if (deleted > 0)
-        parts.push(`${String(deleted)} removed per patch baseline`);
+        parts.push(`${deleted} removed per patch baseline`);
     if (unmanaged > 0)
-        parts.push(`${String(unmanaged)} to upstream state`);
-    return `${String(succeeded)} file(s) restored: ${parts.join(', ')}`;
+        parts.push(`${unmanaged} to upstream state`);
+    return `${succeeded} file(s) restored: ${parts.join(', ')}`;
 }
 /** Warn text for a multi-owner (conflicted) restore. */
 export function describeConflictWarning(plan) {
-    return (`${plan.entry.file} is claimed by ${String(plan.owners.length)} patches ` +
+    return (`${plan.entry.file} is claimed by ${plan.owners.length} patches ` +
         `(${plan.owners.join(', ')}). Restored the cumulative baseline; run ` +
         '"fireforge status --ownership" to resolve ownership.');
 }

package/dist/src/core/display-state.d.ts

@@ -3,15 +3,15 @@
  *
  * `TIMEOUT … application timed out after N seconds with no output` /
  * `Ran 0 checks` has three known causes, one of them purely environmental:
- * a HEADED run on an unattended machine whose display is asleep or locked.
+ * a headed run on an unattended machine whose display is asleep or locked.
  * A headed Firefox on a sleeping display never paints, never reaches its
- * first test, and dies at the no-output timeout — indistinguishable, from
- * the log alone, from a product hang.
+ * first test, and dies at the no-output timeout, which from the log alone
+ * is indistinguishable from a product hang.
  *
- * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
- * display that is already asleep, so wrapping the run changes nothing once
- * the machine has dimmed. `fireforge test` defaults to headed, so an
- * unattended run walks straight into this.
+ * `caffeinate -disu` does not cure it. It prevents sleep, but it cannot
+ * wake a display that is already asleep, so wrapping the run changes
+ * nothing once the machine has dimmed. `fireforge test` defaults to
+ * headed, so an unattended run walks straight into this.
  *
  * The probe is advisory and fail-open: anything unexpected reports
  * `'unknown'` and the caller degrades to the generic triage list rather than
@@ -30,10 +30,10 @@ export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
  * ```
  *
  * Only the `IODisplayWrangler` row matters, and only its first numeric
- * column (the current power state). Any other shape — no such row, a
- * non-numeric column, an error message — is `'unknown'`, never a guess.
+ * column (the current power state). Any other shape (no such row, a
+ * non-numeric column, an error message) is `'unknown'`, never a guess.
  *
- * Pure; exported for direct unit testing.
+ * Pure. Exported for direct unit testing.
  *
  * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
  * @returns The measured state, or `'unknown'`
@@ -41,7 +41,7 @@ export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
 export declare function parseDisplayPowerState(stdout: string): DisplaySleepState;
 /**
  * Probes the display's power state. Non-darwin platforms report `'unknown'`
- * without spawning anything — the stall shape this serves is macOS-specific
+ * without spawning anything: the stall shape this serves is macOS-specific
  * and no equivalent single-command probe is wired for other platforms.
  *
  * @param platform - `process.platform`-style id (injected for testability)

package/dist/src/core/display-state.js

@@ -4,15 +4,15 @@
  *
  * `TIMEOUT … application timed out after N seconds with no output` /
  * `Ran 0 checks` has three known causes, one of them purely environmental:
- * a HEADED run on an unattended machine whose display is asleep or locked.
+ * a headed run on an unattended machine whose display is asleep or locked.
  * A headed Firefox on a sleeping display never paints, never reaches its
- * first test, and dies at the no-output timeout — indistinguishable, from
- * the log alone, from a product hang.
+ * first test, and dies at the no-output timeout, which from the log alone
+ * is indistinguishable from a product hang.
  *
- * `caffeinate -disu` does not cure it. It PREVENTS sleep; it cannot WAKE a
- * display that is already asleep, so wrapping the run changes nothing once
- * the machine has dimmed. `fireforge test` defaults to headed, so an
- * unattended run walks straight into this.
+ * `caffeinate -disu` does not cure it. It prevents sleep, but it cannot
+ * wake a display that is already asleep, so wrapping the run changes
+ * nothing once the machine has dimmed. `fireforge test` defaults to
+ * headed, so an unattended run walks straight into this.
  *
  * The probe is advisory and fail-open: anything unexpected reports
  * `'unknown'` and the caller degrades to the generic triage list rather than
@@ -25,7 +25,7 @@ import { exec } from '../utils/process.js';
 const DISPLAY_PROBE_TIMEOUT_MS = 5_000;
 /**
  * IOKit power state at which `IODisplayWrangler` is fully lit. Lower
- * states are dimmed or off; macOS reports 4 for a live display.
+ * states are dimmed or off. macOS reports 4 for a live display.
  */
 const DISPLAY_AWAKE_POWER_STATE = 4;
 /**
@@ -39,10 +39,10 @@ const DISPLAY_AWAKE_POWER_STATE = 4;
  * ```
  *
  * Only the `IODisplayWrangler` row matters, and only its first numeric
- * column (the current power state). Any other shape — no such row, a
- * non-numeric column, an error message — is `'unknown'`, never a guess.
+ * column (the current power state). Any other shape (no such row, a
+ * non-numeric column, an error message) is `'unknown'`, never a guess.
  *
- * Pure; exported for direct unit testing.
+ * Pure. Exported for direct unit testing.
  *
  * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
  * @returns The measured state, or `'unknown'`
@@ -61,7 +61,7 @@ export function parseDisplayPowerState(stdout) {
 }
 /**
  * Probes the display's power state. Non-darwin platforms report `'unknown'`
- * without spawning anything — the stall shape this serves is macOS-specific
+ * without spawning anything: the stall shape this serves is macOS-specific
  * and no equivalent single-command probe is wired for other platforms.
  *
  * @param platform - `process.platform`-style id (injected for testability)

package/dist/src/core/engine-changes.d.ts

@@ -6,7 +6,7 @@
 import type { BuildBaseline } from './build-baseline-types.js';
 /**
  * Collects engine-relative paths changed since the baseline's HEAD SHA,
- * plus any workdir modifications (tracked and untracked). Defensive — git
+ * plus any workdir modifications (tracked and untracked). Defensive: git
  * failures surface as verbose lines and return the files collected so far,
  * so an empty result means "no drift we can prove" rather than "no drift
  * occurred". When the baseline is missing or the engine has no HEAD yet,
@@ -27,7 +27,7 @@ export declare function collectChangedEnginePaths(engineDir: string, baseline: B
  * full-build escalation in `build-prepare` (`buildInputFingerprints`).
  *
  * A path with no recorded entry, an unreadable file, or a differing hash
- * is kept — "cannot prove unchanged" must never turn into "unchanged".
+ * is kept, since "cannot prove unchanged" must never turn into "unchanged".
  * With no fingerprint set at all (a baseline written before the field
  * existed) every path is kept, which is the path-only comparison the
  * fingerprints refine.

package/dist/src/core/engine-changes.js

@@ -12,7 +12,7 @@ import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
 /**
  * Collects engine-relative paths changed since the baseline's HEAD SHA,
- * plus any workdir modifications (tracked and untracked). Defensive — git
+ * plus any workdir modifications (tracked and untracked). Defensive: git
  * failures surface as verbose lines and return the files collected so far,
  * so an empty result means "no drift we can prove" rather than "no drift
  * occurred". When the baseline is missing or the engine has no HEAD yet,
@@ -67,7 +67,7 @@ export async function collectChangedEnginePaths(engineDir, baseline, contextLabe
  * full-build escalation in `build-prepare` (`buildInputFingerprints`).
  *
  * A path with no recorded entry, an unreadable file, or a differing hash
- * is kept — "cannot prove unchanged" must never turn into "unchanged".
+ * is kept, since "cannot prove unchanged" must never turn into "unchanged".
  * With no fingerprint set at all (a baseline written before the field
  * existed) every path is kept, which is the path-only comparison the
  * fingerprints refine.

package/dist/src/core/engine-precondition.d.ts

@@ -14,20 +14,13 @@
 export interface EngineGitReadyOptions {
     /**
      * Appended to the unborn-HEAD remediation, e.g. `', then retry the rebase.'`
-     * The base message deliberately ends WITHOUT punctuation so the suffix
-     * reads as one sentence; callers that pass nothing get a plain full stop.
+     * The base message ends without punctuation on purpose so the suffix
+     * reads as one sentence. Callers that pass nothing get a plain full stop.
      */
     unbornHeadSuffix?: string;
 }
 /**
- * Error factory for callers whose domain uses a class other than
- * `GeneralError`. The furnace family raises `FurnaceError`, which carries
- * its own `userMessage` and exit code 9, so a helper hardcoding
- * `GeneralError` would silently change both.
- */
-export type PreconditionErrorFactory = (message: string) => Error;
-/**
- * Asserts only that the engine checkout EXISTS.
+ * Asserts only that the engine checkout exists.
  *
  * The first rung of {@link assertEngineGitReady}. Most callers want exactly
  * this rung and no more: `build`, `run`, `test`, `package`, `watch`,
@@ -36,12 +29,11 @@ export type PreconditionErrorFactory = (message: string) => Error;
  * would refuse runs that work today.
  *
  * @param engineDir - Absolute path to the engine checkout
- * @param errorFactory - Optional domain-specific error constructor
  */
-export declare function assertEngineExists(engineDir: string, errorFactory?: PreconditionErrorFactory): Promise<void>;
+export declare function assertEngineExists(engineDir: string): Promise<void>;
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
- * commit — in that order, so the operator gets the most specific applicable
+ * commit, in that order, so the operator gets the most specific applicable
  * remediation rather than a downstream git error.
  *
  * @param engineDir - Absolute path to the engine checkout

package/dist/src/core/engine-precondition.js

@@ -20,10 +20,8 @@ const UNBORN_HEAD_REMEDIATION = 'Engine repository has no baseline commit yet
     // No terminating period: the suffix below supplies its own punctuation, and
     // hardcoding one here rendered as "…cleanly., then retry the rebase."
     'Re-run "fireforge download --force" to recreate the baseline repository cleanly';
-/** Default factory: the message every non-furnace command already used. */
-const defaultErrorFactory = (message) => new GeneralError(message);
 /**
- * Asserts only that the engine checkout EXISTS.
+ * Asserts only that the engine checkout exists.
  *
  * The first rung of {@link assertEngineGitReady}. Most callers want exactly
  * this rung and no more: `build`, `run`, `test`, `package`, `watch`,
@@ -32,25 +30,22 @@ const defaultErrorFactory = (message) => new GeneralError(message);
  * would refuse runs that work today.
  *
  * @param engineDir - Absolute path to the engine checkout
- * @param errorFactory - Optional domain-specific error constructor
  */
-export async function assertEngineExists(engineDir, errorFactory = defaultErrorFactory) {
+export async function assertEngineExists(engineDir) {
     if (!(await pathExists(engineDir))) {
-        throw errorFactory('Firefox source not found. Run "fireforge download" first.');
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
 }
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
- * commit — in that order, so the operator gets the most specific applicable
+ * commit, in that order, so the operator gets the most specific applicable
  * remediation rather than a downstream git error.
  *
  * @param engineDir - Absolute path to the engine checkout
  * @param options - Optional per-command message tailoring
  */
 export async function assertEngineGitReady(engineDir, options = {}) {
-    if (!(await pathExists(engineDir))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
+    await assertEngineExists(engineDir);
     if (!(await isGitRepository(engineDir))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }

package/dist/src/core/engine-session-lock.d.ts

@@ -9,13 +9,13 @@ export interface EngineSessionLockOptions {
     waitLockSeconds?: number | undefined;
 }
 /**
- * Formats the notice printed when the wait budget is EXTENDED because the
+ * Formats the notice printed when the wait budget is extended because the
  * queue advanced.
  *
- * Exported for direct unit testing. It names both figures — the requested
- * budget and the one now in force — because the whole point is that the two
- * have diverged, and an operator comparing the elapsed time against the
- * number they typed would otherwise conclude the timeout is broken.
+ * Exported for direct unit testing. It names both figures, the requested
+ * budget and the one now in force, because they have diverged and an
+ * operator comparing the elapsed time against the number they typed would
+ * otherwise conclude the timeout is broken.
  */
 export declare function formatWaitExtendedLine(ahead: number, budgetMs: number, requestedMs: number): string;
 /**
@@ -24,8 +24,8 @@ export declare function formatWaitExtendedLine(ahead: number, budgetMs: number,
  */
 export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
 /**
- * Inspects the project's engine-session lock without acquiring it —
- * backing `fireforge status --lock`.
+ * Inspects the project's engine-session lock without acquiring it, backing
+ * `fireforge status --lock`.
  *
  * @param projectRoot - Project root containing `.fireforge/`
  * @returns Holder identity, hold duration, and queue depth
@@ -52,7 +52,7 @@ export declare function snapshotEngineGeneration(engineDir: string): Promise<str
  */
 export declare function isIndexLockError(error: unknown): boolean;
 /**
- * True when a generation token records a failed probe — i.e. nothing was
+ * True when a generation token records a failed probe, i.e. nothing was
  * measured, so the token must never be compared (or hashed) as if it
  * described the engine's state.
  */
@@ -62,8 +62,8 @@ export declare function unavailableGenerationReason(token: string): string;
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
- * The refusal used to say only THAT the engine changed, which left the
- * operator to reconstruct the writer by hand — `find -newermt` against the
+ * The refusal used to say only that the engine changed, which left the
+ * operator to reconstruct the writer by hand: `find -newermt` against the
  * run window, minus the objdir, minus git's own bookkeeping. Everything
  * needed to answer it is already in the two tokens, so the refusal answers
  * it. Pure and total: an unparseable token yields an empty list rather than
@@ -72,7 +72,7 @@ export declare function unavailableGenerationReason(token: string): string;
  *
  * @param before - Token captured before the run
  * @param after - Token captured after the run
- * @returns Human-readable lines describing the delta; empty when nothing
+ * @returns Human-readable lines describing the delta. Empty when nothing
  *   could be attributed
  */
 export declare function describeEngineGenerationDelta(before: string, after: string): string[];
@@ -80,25 +80,25 @@ export declare function describeEngineGenerationDelta(before: string, after: str
  * Throws when the engine's generation token differs from `before`, i.e. the
  * engine was mutated by another writer while a test run was in flight.
  *
- * **An unmeasurable engine warns rather than throws.** `engine/` is not
- * always a git checkout — `fireforge download` extracts a source tarball —
+ * An unmeasurable engine warns rather than throws. `engine/` is not
+ * always a git checkout (`fireforge download` extracts a source tarball),
  * so a failed probe is a legitimate state and must not fail the run.
  *
- * What it must also not do is pass *silently*. A failure token compared for
+ * It must also not pass silently. A failure token compared for
  * equality like any other would let a git failure that reproduces across
  * both probes (unreadable `.git`, a permissions problem, a corrupt index)
  * take the `after === before` early return and bless a verdict the guard
- * never verified. Two *differing* failure messages are worse still: they
+ * never verified. Two differing failure messages are worse still: they
  * fall through to the mutation branch and report a spurious
  * "engine/ changed". Hence the prefix comparison rather than a token
- * comparison — the token embeds the error message, and two genuine failures
+ * comparison: the token embeds the error message, and two genuine failures
  * rarely phrase it identically.
  *
- * The tolerance is deliberately limited to a probe that failed *both* times:
+ * The tolerance is limited to a probe that failed both times:
  * that is the steady state of a non-git `engine/`, and it warns. A one-sided
  * transition is not that state. An `engine/` that was measurable and then
  * was not means the second probe measured nothing about a checkout that
- * demonstrably had something to measure; the reverse means there was never a
+ * demonstrably had something to measure. The reverse means there was never a
  * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
 export declare function assertEngineGenerationUnchanged(engineDir: string, before: string): Promise<void>;