mandrel 1.57.0

package/.agents/scripts/lib/bootstrap/gh-preflight.js

@@ -0,0 +1,306 @@
+/**
+ * bootstrap/gh-preflight — `gh` CLI + runtime-dependency preflight
+ *
+ * Provider-agnostic preflight helpers extracted from
+ * `agents-bootstrap-github.js` (Story #3349). Holds the version-comparison
+ * arithmetic (`parseGhVersion` / `compareSemver`), the `gh` CLI probe
+ * (`preflightGh`), and the runtime-dependency probe (`preflightRuntimeDeps`).
+ * Keeping these free of any provider coupling lets the bootstrap orchestrator
+ * stay focused on sequencing.
+ */
+
+import { spawnSync } from 'node:child_process';
+import {
+  GhAuthError,
+  GhNotInstalledError,
+  GhVersionError,
+  MissingRuntimeDepsError,
+} from '../errors/index.js';
+
+/**
+ * Minimum `gh` version the bootstrap supports. Set conservatively per
+ * Tech Spec #1350 ("Risks & Mitigations → `gh` version skew"): older
+ * releases miss flags the eventual `gh-exec` shim relies on. Bumping this
+ * is a deliberate, operator-visible change — keep it tracked here.
+ */
+export const MIN_GH_VERSION = '2.40.0';
+
+const GH_INSTALL_HINT =
+  'Install gh: https://cli.github.com/ — then re-run this command.';
+const GH_AUTH_HINT =
+  'Run `gh auth login` (choose GitHub.com → HTTPS → login with a web browser), then re-run this command.';
+const GH_PROJECT_SCOPE_NOTE =
+  'token lacks the "project" scope — skipping GitHub Projects V2 board provisioning (matches the runtime `resolveProject` graceful path). To enable board provisioning, run `gh auth refresh -s project` (re-auth in the browser when prompted) and re-run this command.';
+const GH_SCOPES_UNREADABLE_NOTE =
+  'token scopes not reported by `gh auth status` (fine-grained PAT?) — skipping the classic project-scope assertion. If Projects V2 provisioning later fails, grant the Projects permission (fine-grained) or run `gh auth refresh -s project` (classic).';
+
+/**
+ * Framework runtime deps the consumer must have installed in
+ * `node_modules/` before this script reaches the dynamic
+ * `config-resolver` import. `ajv` is the sentinel — if it cannot
+ * resolve, the operator skipped `/agents-bootstrap-project` (or its
+ * Step 2c/2d dependency-install never ran). The list mirrors the floor
+ * in `agents-bootstrap-project.md` Step 2c; keep them in sync.
+ */
+const REQUIRED_RUNTIME_DEPS = Object.freeze(['ajv']);
+
+const RUNTIME_DEPS_HINT =
+  'Run `/agents-bootstrap-project` (or `node .agents/scripts/agents-bootstrap-project.js` when present) to merge the framework runtime dependencies into your package.json and install them, then re-run this command.';
+
+/**
+ * Default runner: synchronously execs `gh <args>` and returns
+ * `{ status, stdout, stderr, error }`. Extracted so the preflight tests
+ * can inject a stub without spawning a real child process. Forerunner of
+ * the `lib/gh-exec.js` shim described in Tech Spec #1350; once that
+ * lands, this helper deletes and the preflight calls `gh.exec(...)`.
+ *
+ * @param {string[]} args
+ * @returns {{ status: number|null, stdout: string, stderr: string,
+ *             error?: NodeJS.ErrnoException }}
+ */
+// Story #2990: this preflight runner intentionally stays on raw
+// `spawnSync('gh', …)` (not the `lib/gh-exec.js` facade) because it
+// runs *before* auth is resolved — `gh --version` and `gh auth status`
+// are the very probes that decide whether the facade can be used at
+// all. Routing through the provider layer would create a circular
+// dependency: the facade assumes a working, authenticated `gh`.
+function defaultGhRunner(args) {
+  const result = spawnSync('gh', args, { encoding: 'utf8' });
+  return {
+    status: result.status,
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    error: result.error,
+  };
+}
+
+/**
+ * Parse the first `MAJOR.MINOR.PATCH` triple out of `gh --version` stdout.
+ * Returns `null` when the shape is unrecognized so callers can decide
+ * whether to surface an error or proceed.
+ *
+ * @param {string} stdout
+ * @returns {string|null}
+ */
+export function parseGhVersion(stdout) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(stdout || '');
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+
+/**
+ * Numeric comparison of two `MAJOR.MINOR.PATCH` strings.
+ * Returns negative if `a < b`, positive if `a > b`, zero if equal.
+ * Missing segments are treated as `0`. Non-numeric segments compare as 0.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function compareSemver(a, b) {
+  const pa = String(a)
+    .split('.')
+    .map((n) => Number.parseInt(n, 10) || 0);
+  const pb = String(b)
+    .split('.')
+    .map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Preflight the `gh` CLI before any provider call. Three failure modes,
+ * each surfaced as a typed error so callers (CLI `main`, future
+ * orchestrators, tests) can `instanceof`-match without parsing strings:
+ *
+ *   - {@link GhNotInstalledError} — `gh` not on PATH (ENOENT) or the
+ *     `--version` invocation reported a non-zero exit suggesting the
+ *     binary is missing/broken.
+ *   - {@link GhVersionError} — `gh` is present but older than
+ *     {@link MIN_GH_VERSION}; carries `{ found, required }` for the
+ *     CLI to render an upgrade hint.
+ *   - {@link GhAuthError} — `gh auth status` exited non-zero, meaning
+ *     no host is logged in.
+ *
+ * On success returns `{ version }` so the caller can log the resolved
+ * version. The `runner` seam defaults to a real `spawnSync('gh', …)`;
+ * tests inject a stub returning the canonical
+ * `{ status, stdout, stderr, error }` shape.
+ *
+ * @param {{ runner?: (args: string[]) => {
+ *   status: number|null, stdout: string, stderr: string,
+ *   error?: NodeJS.ErrnoException
+ * } }} [opts]
+ * @returns {Promise<{ version: string }>}
+ */
+export async function preflightGh(opts = {}) {
+  const runner = opts.runner ?? defaultGhRunner;
+  const version = resolveGhVersion(runner);
+  assertGhVersionFloor(version);
+  assertGhAuth(runner);
+  return { version };
+}
+
+/**
+ * Resolve the installed `gh` version via `gh --version`, throwing
+ * {@link GhNotInstalledError} for every "not installed correctly" shape
+ * (ENOENT, non-zero exit, unparseable output).
+ *
+ * @param {(args: string[]) => object} runner
+ * @returns {string}
+ */
+function resolveGhVersion(runner) {
+  const versionResult = runner(['--version']);
+  if (versionResult.error?.code === 'ENOENT') {
+    throw new GhNotInstalledError(
+      `gh CLI not found on PATH. ${GH_INSTALL_HINT}`,
+    );
+  }
+  if (versionResult.status !== 0) {
+    // Non-ENOENT failure of `gh --version` is treated as "not installed
+    // correctly" — same remediation, same exit semantics.
+    const stderrSnippet = (versionResult.stderr || '').trim().slice(0, 200);
+    throw new GhNotInstalledError(
+      `gh --version failed (exit ${versionResult.status}): ${stderrSnippet}. ${GH_INSTALL_HINT}`,
+    );
+  }
+  const version = parseGhVersion(versionResult.stdout);
+  if (!version) {
+    throw new GhNotInstalledError(
+      `Could not parse gh version from output: ${(versionResult.stdout || '').slice(0, 200)}. ${GH_INSTALL_HINT}`,
+    );
+  }
+  return version;
+}
+
+/**
+ * Enforce the {@link MIN_GH_VERSION} floor, throwing {@link GhVersionError}
+ * with `{ found, required }` when the installed version is older.
+ *
+ * @param {string} version
+ */
+function assertGhVersionFloor(version) {
+  if (compareSemver(version, MIN_GH_VERSION) < 0) {
+    throw new GhVersionError(
+      `gh ${version} is older than required ${MIN_GH_VERSION}. Upgrade with your package manager (e.g. \`brew upgrade gh\`, \`winget upgrade GitHub.cli\`, or see https://cli.github.com/) and re-run this command.`,
+      { found: version, required: MIN_GH_VERSION },
+    );
+  }
+}
+
+/**
+ * Assert `gh auth status` reports a logged-in host, throwing
+ * {@link GhAuthError} (or {@link GhNotInstalledError} on a PATH race).
+ *
+ * @param {(args: string[]) => object} runner
+ */
+function assertGhAuth(runner) {
+  const authResult = runner(['auth', 'status']);
+  if (authResult.error?.code === 'ENOENT') {
+    // Defensive — `gh --version` already passed, so ENOENT here would be a
+    // PATH race. Treat the same as not-installed.
+    throw new GhNotInstalledError(
+      `gh CLI disappeared between version and auth check. ${GH_INSTALL_HINT}`,
+    );
+  }
+  if (authResult.status !== 0) {
+    throw new GhAuthError(
+      `gh auth status failed: not logged in. ${GH_AUTH_HINT}`,
+    );
+  }
+}
+
+/**
+ * Check that the authenticated `gh` token carries the `project` scope, which
+ * the bootstrap needs to read and modify GitHub Projects V2. Parses the
+ * `Token scopes:` line from `gh auth status` (some gh versions print it to
+ * stderr, others to stdout — we scan both) and looks for a `project` scope.
+ *
+ * Returns a check record `{ name, ok, remedy?, detail? }` rather than
+ * throwing, so the preflight aggregator can surface it alongside the other
+ * checks. An unreadable scopes line — the normal case for fine-grained PATs
+ * and for `gh` builds that omit it — PASSES with a warning `detail` (Story
+ * #3690). A present-but-`project`-less scopes line — the normal case for a
+ * vanilla `gh auth login` token — also PASSES with a warning `detail`
+ * (Story #3893, Finding A.5): the bootstrap's runtime `resolveProject`
+ * already degrades to warn-and-skip-board for exactly this condition, so
+ * failing the preflight closed was stricter than the code it guards and
+ * created a guaranteed first-run → browser → re-run loop. The check never
+ * fails the gate on the project scope; the warning `detail` carries the
+ * `gh auth refresh -s project` remediation for operators who want boards.
+ *
+ * @param {{ runner?: (args: string[]) => {
+ *   status: number|null, stdout: string, stderr: string,
+ *   error?: NodeJS.ErrnoException
+ * } }} [opts]
+ * @returns {Promise<{ name: string, ok: boolean, remedy?: string,
+ *   detail?: string }>}
+ */
+export async function checkProjectScopes(opts = {}) {
+  const runner = opts.runner ?? defaultGhRunner;
+  const result = runner(['auth', 'status']);
+  const text = `${result.stdout || ''}\n${result.stderr || ''}`;
+  return classifyProjectScopes(/Token scopes:([^\n]*)/i.exec(text));
+}
+
+/**
+ * Map a (possibly absent) `Token scopes:` match onto the check record.
+ * Pure — exported only through {@link checkProjectScopes}.
+ *
+ * @param {RegExpExecArray|null} scopeLine
+ * @returns {{ name: string, ok: boolean, remedy?: string, detail?: string }}
+ */
+function classifyProjectScopes(scopeLine) {
+  if (!scopeLine) {
+    return {
+      name: 'gh-project-scope',
+      ok: true,
+      detail: GH_SCOPES_UNREADABLE_NOTE,
+    };
+  }
+  if (/\bproject\b/i.test(scopeLine[1])) {
+    return { name: 'gh-project-scope', ok: true };
+  }
+  return {
+    name: 'gh-project-scope',
+    ok: true,
+    detail: GH_PROJECT_SCOPE_NOTE,
+  };
+}
+
+/**
+ * Preflight the framework's runtime dependencies before dynamic-importing
+ * `config-resolver.js` (which transitively pulls in `ajv` via
+ * `config-settings-schema.js`). A fresh consumer who skipped
+ * `/agents-bootstrap-project` will not have `ajv` installed, and the
+ * raw `ERR_MODULE_NOT_FOUND` from the dynamic import is opaque. This
+ * preflight converts that into a {@link MissingRuntimeDepsError} that
+ * names the missing packages and points the operator at the right
+ * workflow.
+ *
+ * The `resolver` seam lets tests inject a stub without touching the real
+ * module graph; production uses `import.meta.resolve(specifier)`.
+ *
+ * @param {{ resolver?: (specifier: string) => string | Promise<string> }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function preflightRuntimeDeps(opts = {}) {
+  const resolver =
+    opts.resolver ?? ((specifier) => import.meta.resolve(specifier));
+  const missing = [];
+  for (const specifier of REQUIRED_RUNTIME_DEPS) {
+    try {
+      await resolver(specifier);
+    } catch {
+      missing.push(specifier);
+    }
+  }
+  if (missing.length > 0) {
+    throw new MissingRuntimeDepsError(
+      `Framework runtime dependencies missing from node_modules/: ${missing.join(', ')}. ${RUNTIME_DEPS_HINT}`,
+      { missing },
+    );
+  }
+}

package/.agents/scripts/lib/bootstrap/hitl-confirm.js

@@ -0,0 +1,89 @@
+/**
+ * bootstrap/hitl-confirm — Epic #1235 Story 5; consent-first opt-in (#3526)
+ *
+ * Renders a structured diff to stdout and prompts the operator y/N when
+ * stdout is a TTY. When not a TTY (CI, sub-agent, redirected pipe), the
+ * gate returns `false` and logs the canonical abort message to stderr —
+ * silent-apply is a non-feature. The `opts.assume` override lets tests
+ * and automation pin the answer deterministically:
+ *
+ *   - `opts.assume === 'yes'` → returns true, skips the prompt entirely.
+ *   - `opts.assume === 'no'`  → returns false, skips the prompt.
+ *
+ * The default render is intentionally simple: a single-line summary
+ * followed by a JSON dump of `{ current, proposed }`. Callers that want
+ * a richer view (per-field colour, contextual unified diff) can wrap
+ * `confirm` and render their own preamble before calling.
+ *
+ * Consent-first install (Story #3526): the GitHub-admin phase group — the
+ * irreversible remote mutations (labels, Projects V2, branch protection,
+ * merge methods) — is gated by an explicit opt-in, not merely a TTY. A
+ * non-TTY run that has not opted in records every group as declined, so the
+ * abort hint names BOTH the dedicated `--approve-github-admin` flag (consent
+ * to just the remote mutations) and `--assume-yes` (accept every group).
+ */
+
+import { createInterface } from 'node:readline';
+
+const ABORT_MESSAGE =
+  '[bootstrap] aborting: no TTY available for HITL confirm (opt in with --approve-github-admin for GitHub-admin mutations, or --assume-yes to accept every phase group)';
+
+/**
+ * @param {object} args
+ * @param {string} args.summary - One-line description of the diff.
+ * @param {*} [args.current] - Live state (rendered as JSON).
+ * @param {*} [args.proposed] - Target state (rendered as JSON).
+ * @param {{
+ *   assume?: 'yes' | 'no',
+ *   stdin?: NodeJS.ReadableStream,
+ *   stdout?: NodeJS.WritableStream,
+ *   stderr?: NodeJS.WritableStream,
+ *   isTTY?: boolean,
+ * }} [opts] - Overrides for tests / automation. `isTTY` defaults to
+ *   `process.stdout.isTTY`. `stdin`/`stdout`/`stderr` default to the
+ *   respective `process.*` streams.
+ * @returns {Promise<boolean>} - true ⇒ apply, false ⇒ abort.
+ */
+export async function confirm({ summary, current, proposed }, opts = {}) {
+  if (opts.assume === 'yes') return true;
+  if (opts.assume === 'no') return false;
+
+  const stdout = opts.stdout ?? process.stdout;
+  const stderr = opts.stderr ?? process.stderr;
+  const stdin = opts.stdin ?? process.stdin;
+  const isTTY = opts.isTTY ?? stdout?.isTTY ?? false;
+
+  if (!isTTY) {
+    stderr.write(`${ABORT_MESSAGE}\n`);
+    return false;
+  }
+
+  // Render the diff. Single-line summary, then a JSON block so the
+  // operator can pipe the prompt to a logger and still recover the
+  // structured shape.
+  stdout.write(`\n[bootstrap] HITL confirm: ${summary}\n`);
+  stdout.write(
+    `  current:  ${JSON.stringify(current ?? null, null, 2)
+      .split('\n')
+      .join('\n  ')}\n`,
+  );
+  stdout.write(
+    `  proposed: ${JSON.stringify(proposed ?? null, null, 2)
+      .split('\n')
+      .join('\n  ')}\n`,
+  );
+
+  const rl = createInterface({ input: stdin, output: stdout, terminal: false });
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question('  apply? [y/N] ', resolve);
+    });
+    return /^y(es)?$/i.test(String(answer).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+// Re-export the abort message so tests can assert against the single
+// source of truth.
+export { ABORT_MESSAGE };

package/.agents/scripts/lib/bootstrap/install-ledger.js

@@ -0,0 +1,174 @@
+/**
+ * bootstrap/install-ledger — durable record of what an install applied, for
+ * a future `mandrel uninstall` to consume (Story #3524, Feature #3515,
+ * Epic #3438).
+ *
+ * A successful bootstrap run writes a ledger to
+ * `<projectRoot>/.agents/.install-manifest.json` enumerating exactly the
+ * mutation-manifest entries that were APPROVED and applied (the approved
+ * subset of `buildMutationManifest`, never the full manifest). The ledger is
+ * the single artifact `mandrel uninstall` will later read to know which
+ * reversible mutations to undo and which irreversible (GitHub-admin) ones to
+ * surface for manual rollback.
+ *
+ * The ledger is gitignored (`.agents/.install-manifest.json` is added to the
+ * consumer `.gitignore` by the bootstrap) because it is a per-clone install
+ * record, not a checked-in source artifact.
+ *
+ * This module performs filesystem writes but no network I/O.
+ *
+ * @module bootstrap/install-ledger
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Path of the install ledger, relative to the project root. The bootstrap's
+ * `.gitignore` step keys its ignore entry off this exact POSIX path.
+ *
+ * @type {string}
+ */
+export const LEDGER_RELATIVE_PATH = '.agents/.install-manifest.json';
+
+/**
+ * Current ledger schema version. A future `mandrel uninstall` reads this to
+ * detect a ledger it cannot interpret (hard-cutover contract — no read-side
+ * tolerance branch, just a clean refusal).
+ *
+ * v2 (Story #3895): each entry now carries `executedAction` — the *live*
+ * outcome of the bootstrap phase that produced it (e.g. `seeded` vs
+ * `already-present` for `.agentrc.json`). Uninstall keys destructive reversal
+ * off this so a pre-existing, operator-authored file the install merely left
+ * in place (`already-present`) is never deleted.
+ *
+ * @type {number}
+ */
+export const LEDGER_SCHEMA_VERSION = 2;
+
+/**
+ * Map a mutation-manifest `target` (POSIX-relative path) to the bootstrap
+ * **phase name** whose execution outcome describes that target. Only targets
+ * whose reversal is destructive enough to need the live outcome are mapped;
+ * everything else is reversed content-aware and needs no execution hint.
+ *
+ * The `.agentrc.json` `create` entry is produced by the `agentrc` phase
+ * (`ensureAgentrc`), which returns `{ action: 'seeded' }` when it wrote the
+ * file from the starter and `{ action: 'already-present' }` when an
+ * operator-authored file was left untouched. Recording that distinction lets
+ * uninstall skip deleting a file the install did not create (Story #3895).
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const TARGET_TO_PHASE = Object.freeze({
+  '.agentrc.json': 'agentrc',
+});
+
+/**
+ * Resolve the live executed action for a manifest entry from the bootstrap
+ * report, when one is available. Pure — derives entirely from the entry +
+ * report. Returns `undefined` when the target has no mapped phase, the report
+ * is absent, or the phase produced no `action` (so older callers/tests that
+ * omit the report degrade to "no hint" rather than throwing).
+ *
+ * The `.agentrc.json` quality-gates `merge` entry shares the same target as
+ * the repo-config `create` entry but is keyed by phase, not target — both
+ * manifest entries resolve to the same `agentrc` outcome, which is correct:
+ * reversal dedupes them to a single `revertAgentrc` call anyway.
+ *
+ * @param {{ target: string }} entry
+ * @param {Record<string, { action?: string }>} [report]
+ * @returns {string|undefined}
+ */
+export function resolveExecutedAction(entry, report) {
+  if (!report) return undefined;
+  const phaseName = TARGET_TO_PHASE[entry.target];
+  if (!phaseName) return undefined;
+  const action = report[phaseName]?.action;
+  return typeof action === 'string' ? action : undefined;
+}
+
+/**
+ * Resolve the absolute ledger path for a project root.
+ *
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function ledgerPath(projectRoot) {
+  return path.join(projectRoot, '.agents', '.install-manifest.json');
+}
+
+/**
+ * Build the ledger record from the approved manifest entries. Pure helper —
+ * no I/O — so the shape is unit-testable in isolation. The `appliedAt`
+ * timestamp is injectable for deterministic tests.
+ *
+ * @param {object} args
+ * @param {import('./manifest.js').MutationManifestEntry[]} args.entries
+ *   — the APPROVED subset of the mutation manifest that was applied.
+ * @param {string[]} args.approvedGroups — the phase groups the operator
+ *   approved (sorted for stable output).
+ * @param {{ owner?: string, repo?: string }} [args.answers]
+ * @param {string} [args.appliedAt] — ISO-8601 timestamp (default: now).
+ * @param {Record<string, { action?: string }>} [args.report] — the live
+ *   bootstrap execution report (phase name → outcome). When present, each
+ *   entry whose target maps to a phase records that phase's `action` as
+ *   `executedAction` so uninstall can distinguish `seeded` from
+ *   `already-present` (Story #3895).
+ * @returns {{ schemaVersion: number, appliedAt: string,
+ *   repo: string|null, approvedGroups: string[],
+ *   entries: Array<import('./manifest.js').MutationManifestEntry
+ *     & { executedAction?: string }> }}
+ */
+export function buildLedgerRecord(args) {
+  const { entries, approvedGroups, answers, appliedAt, report } = args;
+  const repo =
+    answers?.owner && answers?.repo ? `${answers.owner}/${answers.repo}` : null;
+  return {
+    schemaVersion: LEDGER_SCHEMA_VERSION,
+    appliedAt: appliedAt ?? new Date().toISOString(),
+    repo,
+    approvedGroups: [...approvedGroups].sort(),
+    entries: entries.map((e) => {
+      const executedAction = resolveExecutedAction(e, report);
+      return {
+        phaseGroup: e.phaseGroup,
+        target: e.target,
+        action: e.action,
+        reversible: e.reversible,
+        ...(executedAction !== undefined ? { executedAction } : {}),
+      };
+    }),
+  };
+}
+
+/**
+ * Write the install ledger to `<projectRoot>/.agents/.install-manifest.json`,
+ * creating the `.agents/` directory if needed. The file is overwritten on
+ * each successful install so the ledger always reflects the most recent run
+ * (a re-install with a different approval set replaces, never appends).
+ *
+ * @param {string} projectRoot
+ * @param {ReturnType<typeof buildLedgerRecord>} record
+ * @returns {{ path: string, written: boolean, entryCount: number }}
+ */
+export function writeInstallLedger(projectRoot, record) {
+  const target = ledgerPath(projectRoot);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+  return { path: target, written: true, entryCount: record.entries.length };
+}
+
+/**
+ * Read and parse the install ledger. Returns `null` when no ledger exists
+ * (never installed, or the ledger was removed). A future `mandrel uninstall`
+ * is the primary consumer.
+ *
+ * @param {string} projectRoot
+ * @returns {ReturnType<typeof buildLedgerRecord>|null}
+ */
+export function readInstallLedger(projectRoot) {
+  const target = ledgerPath(projectRoot);
+  if (!fs.existsSync(target)) return null;
+  return JSON.parse(fs.readFileSync(target, 'utf8'));
+}