@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,247 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * 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
- * (`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
- * outright.
- *
- * This module classifies each status entry against the patch manifest's
- * 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.
- */
-import { join } from 'node:path';
-import { GeneralError } from '../errors/base.js';
-import { toError } from '../utils/errors.js';
-import { readText, removeFile, writeText } from '../utils/fs.js';
-import { discardStatusEntry, fileExistsInHead, listTrackedInHead, restoreTrackedPath, unstageFiles, } from './git-file-ops.js';
-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` 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
- * 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 the data-loss path this module exists to close.
- */
-export async function planDiscardBaselines(patchesDir, engineDir, entries) {
-    const state = await loadPatchesManifestState(patchesDir);
-    if (state.exists && state.parseError) {
-        throw new GeneralError('patches/patches.json is unreadable — refusing to discard while patch ownership cannot be ' +
-            'determined. Fix the manifest, or pass --to-upstream to explicitly revert to pristine ' +
-            'upstream (HEAD).');
-    }
-    const claims = state.manifest
-        ? buildPatchClaims(state.manifest.patches)
-        : new Map();
-    const plans = [];
-    const claimedEntries = entries.filter((entry) => claims.has(entry.file) || (entry.originalPath !== undefined && claims.has(entry.originalPath)));
-    if (claimedEntries.length === 0) {
-        return planUpstreamDiscards(entries);
-    }
-    const { computePatched, prefetchBase } = await createPatchedContentContext(patchesDir, engineDir);
-    const claimedFiles = [
-        ...new Set(claimedEntries.flatMap((entry) => entry.originalPath !== undefined ? [entry.file, entry.originalPath] : [entry.file])),
-    ];
-    const trackedInHead = await listTrackedInHead(engineDir, claimedFiles);
-    await prefetchBase(claimedFiles);
-    const computeExpected = async (path) => {
-        try {
-            return await computePatched(path);
-        }
-        catch (error) {
-            throw new GeneralError(`Cannot reconstruct the patch baseline for ${path} (${toError(error).message}). ` +
-                'Fix the owning patch, or pass --to-upstream to explicitly revert to pristine ' +
-                'upstream (HEAD).');
-        }
-    };
-    // `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
-    // decides whether the baseline is "absent".
-    const sectionCache = new Map();
-    const isDeletedAtBaseline = async (path, owners) => {
-        for (let i = owners.length - 1; i >= 0; i--) {
-            const owner = owners[i];
-            if (owner === undefined)
-                continue;
-            let sections = sectionCache.get(owner);
-            if (!sections) {
-                try {
-                    sections = parseDiffSections(await readText(join(patchesDir, owner)));
-                }
-                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.
-                    // rewritten instead of removed: silent data loss on the command
-                    // 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
-                    // removed or made unreadable mid-plan) rather than a reachable
-                    // branch today. It uses the same remediation as its sibling so the
-                    // two cannot drift into disagreeing.
-                    throw new GeneralError(`Cannot read the owning patch ${owner} to determine the baseline for ${path} ` +
-                        `(${toError(error).message}). ` +
-                        'Fix the owning patch, or pass --to-upstream to explicitly revert to pristine ' +
-                        'upstream (HEAD).');
-                }
-                sectionCache.set(owner, sections);
-            }
-            for (const section of sections) {
-                if (section.targetPath === path || section.sourcePath === path) {
-                    return section.isDeletedFile;
-                }
-            }
-        }
-        return false;
-    };
-    for (const entry of entries) {
-        const owners = [
-            ...new Set([
-                ...(claims.get(entry.file) ?? []),
-                ...(entry.originalPath !== undefined ? (claims.get(entry.originalPath) ?? []) : []),
-            ]),
-        ];
-        if (owners.length === 0) {
-            plans.push({ entry, kind: 'unmanaged', owners, conflicted: false });
-            continue;
-        }
-        let expectedContent = claims.has(entry.file) ? await computeExpected(entry.file) : null;
-        if (expectedContent !== null &&
-            (await isDeletedAtBaseline(entry.file, claims.get(entry.file) ?? []))) {
-            expectedContent = null;
-        }
-        const expectedOriginalContent = entry.originalPath !== undefined && claims.has(entry.originalPath)
-            ? await computeExpected(entry.originalPath)
-            : undefined;
-        const kind = expectedContent === null
-            ? 'patch-deleted'
-            : trackedInHead.has(entry.file)
-                ? 'patch-backed'
-                : 'patch-created';
-        plans.push({
-            entry,
-            kind,
-            owners,
-            conflicted: owners.length > 1,
-            expectedContent,
-            ...(expectedOriginalContent !== undefined ? { expectedOriginalContent } : {}),
-        });
-    }
-    return plans;
-}
-/**
- * Applies one restore plan. Patch-claimed paths end up exactly as `import`
- * leaves them: patched content as an unstaged worktree state (tracked files
- * read ` M`, created files `??`), nothing staged. Unmanaged plans delegate
- * to the plain git {@link discardStatusEntry} mechanics.
- */
-export async function applyDiscardBaseline(engineDir, plan) {
-    if (plan.kind === 'unmanaged') {
-        await discardStatusEntry(engineDir, plan.entry);
-        return;
-    }
-    const { entry } = plan;
-    // Drop any staged edits/adds/renames first so the rewritten content is a
-    // 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];
-        await unstageFiles(engineDir, indexPaths);
-    }
-    if (plan.expectedContent === null || plan.expectedContent === undefined) {
-        await removeFile(join(engineDir, entry.file));
-    }
-    else {
-        await writeText(join(engineDir, entry.file), plan.expectedContent);
-    }
-    // A rename/copy's original side restores to its baseline too: the patch
-    // baseline when claimed, else the HEAD restore (matching what
-    // discardStatusEntry does for that side).
-    if (entry.originalPath !== undefined) {
-        if (plan.expectedOriginalContent !== undefined) {
-            if (plan.expectedOriginalContent === null) {
-                await removeFile(join(engineDir, entry.originalPath));
-            }
-            else {
-                await writeText(join(engineDir, entry.originalPath), plan.expectedOriginalContent);
-            }
-        }
-        else if (await fileExistsInHead(engineDir, entry.originalPath)) {
-            await restoreTrackedPath(engineDir, entry.originalPath);
-        }
-    }
-}
-/** One-line annotation for dry-run listings and confirmation summaries. */
-export function describeDiscardBaseline(plan) {
-    const owners = plan.owners.join(' + ');
-    switch (plan.kind) {
-        case 'unmanaged':
-            return plan.entry.isUntracked ? 'unmanaged — delete' : 'unmanaged — revert to upstream';
-        case 'patch-backed':
-            return `patch baseline: ${owners}${plan.conflicted ? ' (conflict)' : ''}`;
-        case 'patch-created':
-            return `re-materialize from ${owners}${plan.conflicted ? ' (conflict)' : ''}`;
-        case 'patch-deleted':
-            return `delete — ${owners} removes it`;
-    }
-}
-/** Single-file outro naming the baseline that was restored. */
-export function describeDiscardOutcome(plan, toUpstream) {
-    if (toUpstream)
-        return 'File restored to pristine upstream (HEAD)';
-    const owners = plan.owners.join(' + ');
-    switch (plan.kind) {
-        case 'unmanaged':
-            return 'File restored to original state';
-        case 'patch-backed':
-            return `File restored to patch baseline (${owners})`;
-        case 'patch-created':
-            return `File re-materialized from patch baseline (${owners})`;
-        case 'patch-deleted':
-            return `File removed to match patch baseline (${owners} deletes it)`;
-    }
-}
-/** Batch outro summarising how many files restored to which baseline. */
-export function summarizeDiscardBaselines(plans, succeeded) {
-    const patchBacked = plans.filter((p) => p.kind === 'patch-backed').length;
-    const created = plans.filter((p) => p.kind === 'patch-created').length;
-    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 `${succeeded} file(s) restored to upstream state`;
-    }
-    const parts = [];
-    if (patchBacked > 0)
-        parts.push(`${patchBacked} to patch baseline`);
-    if (created > 0)
-        parts.push(`${created} re-materialized`);
-    if (deleted > 0)
-        parts.push(`${deleted} removed per patch baseline`);
-    if (unmanaged > 0)
-        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 ${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

@@ -1,50 +0,0 @@
-/**
- * macOS display power-state probe for the headed no-output stall.
- *
- * `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 Firefox on a sleeping display never paints, never reaches its
- * 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, 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
- * asserting an environment it could not measure.
- */
-/** Measured display power state, or `'unknown'` when nothing was measured. */
-export type DisplaySleepState = 'asleep' | 'awake' | 'unknown';
-/**
- * Parses `pmset -g powerstate IODisplayWrangler` output.
- *
- * The command prints a header row and then one row per driver, e.g.
- *
- * ```
- * Current power states:
- *   IODisplayWrangler             4       12    -1
- * ```
- *
- * 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.
- *
- * Pure. Exported for direct unit testing.
- *
- * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
- * @returns The measured state, or `'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
- * and no equivalent single-command probe is wired for other platforms.
- *
- * @param platform - `process.platform`-style id (injected for testability)
- * @returns The measured state, or `'unknown'` when unmeasurable
- */
-export declare function probeDisplaySleepState(platform: string): Promise<DisplaySleepState>;

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

@@ -1,87 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * macOS display power-state probe for the headed no-output stall.
- *
- * `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 Firefox on a sleeping display never paints, never reaches its
- * 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, 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
- * asserting an environment it could not measure.
- */
-import { toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { exec } from '../utils/process.js';
-/** Bound on the probe so a wedged `pmset` cannot extend a failing run. */
-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.
- */
-const DISPLAY_AWAKE_POWER_STATE = 4;
-/**
- * Parses `pmset -g powerstate IODisplayWrangler` output.
- *
- * The command prints a header row and then one row per driver, e.g.
- *
- * ```
- * Current power states:
- *   IODisplayWrangler             4       12    -1
- * ```
- *
- * 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.
- *
- * Pure. Exported for direct unit testing.
- *
- * @param stdout - Raw `pmset -g powerstate IODisplayWrangler` output
- * @returns The measured state, or `'unknown'`
- */
-export function parseDisplayPowerState(stdout) {
-    for (const line of stdout.split(/\r?\n/)) {
-        if (!line.includes('IODisplayWrangler'))
-            continue;
-        const match = /IODisplayWrangler\s+(\d+)/.exec(line);
-        const state = match?.[1];
-        if (state === undefined)
-            continue;
-        return Number.parseInt(state, 10) >= DISPLAY_AWAKE_POWER_STATE ? 'awake' : 'asleep';
-    }
-    return 'unknown';
-}
-/**
- * Probes the display's power state. Non-darwin platforms report `'unknown'`
- * 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)
- * @returns The measured state, or `'unknown'` when unmeasurable
- */
-export async function probeDisplaySleepState(platform) {
-    if (platform !== 'darwin')
-        return 'unknown';
-    try {
-        const result = await exec('pmset', ['-g', 'powerstate', 'IODisplayWrangler'], {
-            timeout: DISPLAY_PROBE_TIMEOUT_MS,
-        });
-        if (result.exitCode !== 0) {
-            verbose(`Display power-state probe failed (pmset exit ${result.exitCode}).`);
-            return 'unknown';
-        }
-        return parseDisplayPowerState(result.stdout);
-    }
-    catch (error) {
-        verbose(`Display power-state probe failed: ${toError(error).message}`);
-        return 'unknown';
-    }
-}

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

@@ -1,40 +0,0 @@
-/**
- * Shared collector for "what changed in the engine tree since the last
- * successful build", used by `build-audit`, `build-prepare` and
- * `test-stale-check`.
- */
-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
- * 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,
- * falls back to workdir-only collection. The result is sorted.
- *
- * @param engineDir - Path to the engine directory
- * @param baseline - Last-build baseline, when one exists
- * @param contextLabel - Prefix for verbose-log lines (e.g. `Audit`,
- *   `Auto-configure`, `Stale-build preflight`) so operators can attribute
- *   the probe that emitted them
- * @returns Sorted engine-relative POSIX paths
- */
-export declare function collectChangedEnginePaths(engineDir: string, baseline: BuildBaseline | undefined, contextLabel: string): Promise<string[]>;
-/**
- * Drops every path whose live content still matches the fingerprint the
- * last successful build recorded for it, keeping the rest. Shared by the
- * stale-build preflight (`packageableFingerprints`) and the auto-configure /
- * full-build escalation in `build-prepare` (`buildInputFingerprints`).
- *
- * A path with no recorded entry, an unreadable file, or a differing hash
- * 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.
- *
- * @param engineDir - Path to the engine directory
- * @param paths - Candidate engine-relative POSIX paths
- * @param fingerprints - Recorded hashes keyed by engine-relative path
- * @returns The subset of `paths` that cannot be proven unchanged
- */
-export declare function dropPathsMatchingFingerprints(engineDir: string, paths: readonly string[], fingerprints: Record<string, string> | undefined): Promise<string[]>;

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

@@ -1,95 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Shared collector for "what changed in the engine tree since the last
- * successful build", used by `build-audit`, `build-prepare` and
- * `test-stale-check`.
- */
-import { toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { hashEngineFile } from './coverage-extend.js';
-import { hasChanges, isMissingHeadError } from './git.js';
-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
- * 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,
- * falls back to workdir-only collection. The result is sorted.
- *
- * @param engineDir - Path to the engine directory
- * @param baseline - Last-build baseline, when one exists
- * @param contextLabel - Prefix for verbose-log lines (e.g. `Audit`,
- *   `Auto-configure`, `Stale-build preflight`) so operators can attribute
- *   the probe that emitted them
- * @returns Sorted engine-relative POSIX paths
- */
-export async function collectChangedEnginePaths(engineDir, baseline, contextLabel) {
-    const collected = new Set();
-    if (baseline?.engineHeadSha) {
-        try {
-            const output = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
-            for (const line of output.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-        }
-        catch (error) {
-            if (!isMissingHeadError(error)) {
-                verbose(`${contextLabel}: could not diff engine against baseline — ${toError(error).message}`);
-            }
-        }
-    }
-    try {
-        if (await hasChanges(engineDir)) {
-            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
-            for (const line of worktreeDiff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-            for (const untracked of await getUntrackedFiles(engineDir)) {
-                collected.add(untracked);
-            }
-        }
-    }
-    catch (error) {
-        verbose(`${contextLabel}: could not enumerate workdir changes — ${toError(error).message}`);
-    }
-    return [...collected].sort();
-}
-/**
- * Drops every path whose live content still matches the fingerprint the
- * last successful build recorded for it, keeping the rest. Shared by the
- * stale-build preflight (`packageableFingerprints`) and the auto-configure /
- * full-build escalation in `build-prepare` (`buildInputFingerprints`).
- *
- * A path with no recorded entry, an unreadable file, or a differing hash
- * 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.
- *
- * @param engineDir - Path to the engine directory
- * @param paths - Candidate engine-relative POSIX paths
- * @param fingerprints - Recorded hashes keyed by engine-relative path
- * @returns The subset of `paths` that cannot be proven unchanged
- */
-export async function dropPathsMatchingFingerprints(engineDir, paths, fingerprints) {
-    if (!fingerprints)
-        return [...paths];
-    const kept = [];
-    for (const path of paths) {
-        const recorded = fingerprints[path];
-        if (recorded === undefined) {
-            kept.push(path);
-            continue;
-        }
-        const live = await hashEngineFile(engineDir, path);
-        if (live === undefined || live !== recorded)
-            kept.push(path);
-    }
-    return kept;
-}

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

@@ -1,42 +0,0 @@
-/**
- * Shared engine precondition ladder for commands that read or mutate
- * `engine/` through git.
- *
- * The rungs matter in order. Skipping the unborn-HEAD guard and going
- * straight to enumerating working-tree status makes the whole ~300k-file
- * Firefox tree read as untracked, so an engine left half-initialised by an
- * interrupted `download` produces a nonsensical result instead of an
- * actionable refusal.
- *
- * The remediation wording lives here once so the callers cannot drift apart.
- */
-/** Options for {@link assertEngineGitReady}. */
-export interface EngineGitReadyOptions {
-    /**
-     * Appended to the unborn-HEAD remediation, e.g. `', then retry the rebase.'`
-     * 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;
-}
-/**
- * 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`,
- * `import` and `bootstrap` never run git against the engine and each has its
- * own richer follow-up gate, so promoting them to the full three-rung ladder
- * would refuse runs that work today.
- *
- * @param engineDir - Absolute path to the engine checkout
- */
-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
- * remediation rather than a downstream git error.
- *
- * @param engineDir - Absolute path to the engine checkout
- * @param options - Optional per-command message tailoring
- */
-export declare function assertEngineGitReady(engineDir: string, options?: EngineGitReadyOptions): Promise<void>;

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

@@ -1,60 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Shared engine precondition ladder for commands that read or mutate
- * `engine/` through git.
- *
- * The rungs matter in order. Skipping the unborn-HEAD guard and going
- * straight to enumerating working-tree status makes the whole ~300k-file
- * Firefox tree read as untracked, so an engine left half-initialised by an
- * interrupted `download` produces a nonsensical result instead of an
- * actionable refusal.
- *
- * The remediation wording lives here once so the callers cannot drift apart.
- */
-import { GeneralError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
-import { getHead, isGitRepository, isMissingHeadError } from './git.js';
-/** Remediation for an engine whose baseline commit was never created. */
-const UNBORN_HEAD_REMEDIATION = 'Engine repository has no baseline commit yet — a previous "fireforge download" was ' +
-    'interrupted before git created the initial Firefox source commit. ' +
-    // 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';
-/**
- * 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`,
- * `import` and `bootstrap` never run git against the engine and each has its
- * own richer follow-up gate, so promoting them to the full three-rung ladder
- * would refuse runs that work today.
- *
- * @param engineDir - Absolute path to the engine checkout
- */
-export async function assertEngineExists(engineDir) {
-    if (!(await pathExists(engineDir))) {
-        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
- * 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 = {}) {
-    await assertEngineExists(engineDir);
-    if (!(await isGitRepository(engineDir))) {
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    try {
-        await getHead(engineDir);
-    }
-    catch (headError) {
-        if (!isMissingHeadError(headError))
-            throw headError;
-        throw new GeneralError(`${UNBORN_HEAD_REMEDIATION}${options.unbornHeadSuffix ?? '.'}`);
-    }
-}