@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/checkpoints/shadow-git.js

@@ -0,0 +1,670 @@
+/**
+ * Per-task shadow git repo — file-state checkpoint surface.
+ *
+ * Inspired by Cline `CheckpointTracker.ts` (Apache-2.0).
+ * independent implementation TypeScript implementation following Pugi conventions.
+ *
+ * Goal: every Pugi-orchestrated file mutation lands in a per-task
+ * shadow git history kept entirely separate from the user's real
+ * `.git/`. The operator can list / diff / restore checkpoints with
+ * zero pollution of their own commit graph.
+ *
+ * Design choices:
+ *
+ *  - Shadow `.git` lives at `<cwd>/.pugi/checkpoints/<task-id>/.git`
+ *    (a regular non-bare repo whose `objects/` + `refs/` stay there).
+ *    The "shadow repo" is the dir containing `.git`; that parent dir
+ *    itself is empty — we drive git via `--git-dir=<shadow>/.git
+ *    --work-tree=<cwd>` so the shadow tracks the user's working tree
+ *    in-place WITHOUT a separate clone of the file contents.
+ *
+ *  - We never `git init` inside `<cwd>`. The shadow's `.git` dir is
+ *    under `.pugi/checkpoints/<task-id>/` so the user's real repo
+ *    (if any) is untouched. Auto-ignore `.pugi/` so the shadow does
+ *    not recurse into its own metadata.
+ *
+ *  - All git invocations go through `spawnSync` with explicit argv
+ *    (no shell, no string interpolation). The shadow `.git` dir is
+ *    chmod 700 so file-content snapshots do not leak to other Unix
+ *    accounts on shared boxes (memory rule: "shadow `.git` MUST be
+ *    chmod 700").
+ *
+ *  - Operations are atomic-or-no-op: `initShadowRepo` writes a tmp
+ *    `.gitignore` and only flips the canonical `.gitignore` once the
+ *    `git init` + initial commit complete, so a crash between steps
+ *    leaves a clean "not initialised yet" state on retry.
+ *
+ *  - The commit author / committer is pinned to
+ *    `Pugi Shadow <shadow@pugi.local>` and `GIT_*_DATE` env vars are
+ *    set per-commit so the shadow log is reproducible regardless of
+ *    the host's git config.
+ *
+ *  - Errors that originate from a missing `git` binary surface as
+ *    `ShadowGitUnavailableError`; the dispatcher's hook treats that
+ *    as best-effort (logs but does not block the edit).
+ */
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { join, relative, resolve } from 'node:path';
+/**
+ * Reserved task-id used for ad-hoc / "no active task" checkpoints when
+ * the dispatcher cannot supply a real task id. Kept as an exported
+ * constant so callers in tests and integration glue agree on the
+ * fallback bucket.
+ */
+export const DEFAULT_TASK_ID = 'default';
+/**
+ * Default git author for shadow commits. Kept deterministic so the
+ * shadow log is stable across hosts and reproducible in tests.
+ */
+const SHADOW_AUTHOR_NAME = 'Pugi Shadow';
+const SHADOW_AUTHOR_EMAIL = 'shadow@pugi.local';
+/**
+ * Default ignore template applied to the shadow on init. Excludes the
+ * `.pugi/` metadata directory (so shadow operations cannot recurse
+ * into their own state) along with the heavy build-output directories
+ * that would otherwise turn every dispatch commit into a multi-MB
+ * blob churn.
+ *
+ * Lives as a constant rather than a fixture file so the contents are
+ * inspectable from the tests without IO.
+ */
+export const SHADOW_GITIGNORE_TEMPLATE = [
+    '# Pugi shadow git ignore — managed by core/checkpoints/shadow-git.ts',
+    '# Do not edit by hand; reset via `pugi checkpoint reset` once that ships.',
+    '.pugi/',
+    'node_modules/',
+    '.next/',
+    'dist/',
+    'build/',
+    'coverage/',
+    '.turbo/',
+    '.cache/',
+    '*.log',
+    '',
+].join('\n');
+/**
+ * Thrown when `git` is missing or the spawn fails in a way that cannot
+ * be recovered. Best-effort callers (the dispatch hook) catch + log
+ * + continue; explicit callers (REPL slash commands) surface the
+ * message to the operator.
+ */
+export class ShadowGitUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ShadowGitUnavailableError';
+    }
+}
+/** Resolve the on-disk shadow root for a (cwd, taskId) pair. */
+export function shadowRoot(cwd, taskId) {
+    return resolve(cwd, '.pugi', 'checkpoints', sanitizeTaskId(taskId));
+}
+/**
+ * Resolve the shadow `.git` directory. Convention: regular (non-bare)
+ * repo so `git -C <root>` would Just Work if the operator ever needed
+ * to introspect it directly.
+ */
+export function shadowGitDir(cwd, taskId) {
+    return join(shadowRoot(cwd, taskId), '.git');
+}
+/**
+ * Idempotent init. When the shadow `.git` already exists this is a
+ * no-op (returns `{ created: false }`). On first call:
+ *
+ *  1. mkdir parent dir tree.
+ *  2. `git init` the shadow `.git` (no working tree at the shadow
+ *     root; we drive every later command with `--work-tree=<cwd>`).
+ *  3. Write the canonical `.gitignore` to the shadow root + chmod
+ *     the shadow `.git` to 0o700 to keep snapshot content owner-only.
+ *  4. Stage `.gitignore` + commit an initial "shadow init" so later
+ *     `git log` always has at least one entry to compare against.
+ *
+ * Throws `ShadowGitUnavailableError` when `git` is missing.
+ */
+export function initShadowRepo(cwd, taskId) {
+    const root = shadowRoot(cwd, taskId);
+    const gitDir = shadowGitDir(cwd, taskId);
+    if (existsSync(gitDir)) {
+        return { created: false, root, gitDir };
+    }
+    mkdirSync(root, { recursive: true });
+    // `git init <root>` creates `<root>/.git/` as the git dir. We can't
+    // pass `gitDir` directly because that would nest as
+    // `<root>/.git/.git/`. Init from `root` then verify `gitDir` exists.
+    const initRes = spawnGit(['init', '--quiet', root], { cwd: root });
+    if (initRes.error || initRes.status !== 0) {
+        throw new ShadowGitUnavailableError(`git init failed for ${root}: ${describeSpawn(initRes)}`);
+    }
+    try {
+        chmodSync(gitDir, 0o700);
+    }
+    catch {
+        // Non-fatal on platforms (Windows / restrictive sandboxes) where
+        // chmod does not have effect. The bare path is still under the
+        // user's $HOME so the practical exposure is unchanged.
+    }
+    // Write the exclude template at the shadow root. This file is
+    // referenced via `core.excludesFile` on every shadow command — it
+    // is NOT committed into the shadow's tree, so it never appears as
+    // a phantom delete when `--work-tree` points at the user's `cwd`.
+    writeFileSync(join(root, '.gitignore'), SHADOW_GITIGNORE_TEMPLATE);
+    // Empty initial commit so `git log` always has at least one anchor.
+    // We point `--work-tree` at the user's `cwd` even for the init —
+    // `--allow-empty` + nothing staged means no files are touched.
+    const commitInit = spawnGit([
+        '--git-dir',
+        gitDir,
+        '--work-tree',
+        cwd,
+        'commit',
+        '--quiet',
+        '--allow-empty',
+        '-m',
+        'pugi shadow init',
+    ], { cwd, env: shadowEnv() });
+    if (commitInit.status !== 0) {
+        throw new ShadowGitUnavailableError(`shadow init commit failed: ${describeSpawn(commitInit)}`);
+    }
+    return { created: true, root, gitDir };
+}
+/**
+ * Stage everything in `cwd` (respecting `.gitignore`) and commit a
+ * snapshot to the shadow. Returns the new commit SHA, or `null` when
+ * the snapshot was a no-op (working tree clean vs. last shadow head).
+ *
+ * The dispatcher hook calls this AFTER every successful edit. We
+ * deliberately tolerate a no-op (no SHA) so a tool that ran but did
+ * not actually touch a tracked file does not litter the shadow log
+ * with empty commits.
+ *
+ * `message` is the operator-facing commit body. Convention:
+ *
+ *    pugi <task-id> step <n>: <tool-name> <relative-path>
+ *
+ * The dispatcher composes this; the shadow module stores it verbatim.
+ */
+export function commitCheckpoint(cwd, taskId, message) {
+    const gitDir = shadowGitDir(cwd, taskId);
+    if (!existsSync(gitDir)) {
+        initShadowRepo(cwd, taskId);
+    }
+    // Apply our exclude template through `core.excludesFile` so the
+    // shadow does not pull in `.pugi/`, `node_modules/`, `dist/`, etc.
+    // Cannot just place a `.gitignore` in the working tree — that would
+    // pollute the user's repo. The exclude file lives under the shadow
+    // root and is referenced per-command.
+    const excludeFile = join(shadowRoot(cwd, taskId), '.gitignore');
+    const add = spawnGit([
+        '-c',
+        `core.excludesFile=${excludeFile}`,
+        '--git-dir',
+        gitDir,
+        '--work-tree',
+        cwd,
+        'add',
+        '-A',
+    ], { cwd, env: shadowEnv() });
+    if (add.status !== 0) {
+        throw new ShadowGitUnavailableError(`shadow add failed: ${describeSpawn(add)}`);
+    }
+    // Check whether there is anything staged. `git diff --cached
+    // --quiet` exits 0 iff the index matches HEAD; non-zero (specifically
+    // 1) means we have content to commit. Any other exit is an error.
+    const diff = spawnGit(['--git-dir', gitDir, '--work-tree', cwd, 'diff', '--cached', '--quiet'], { cwd, env: shadowEnv() });
+    if (diff.status === 0) {
+        return null;
+    }
+    if (diff.status !== 1) {
+        throw new ShadowGitUnavailableError(`shadow diff probe failed: ${describeSpawn(diff)}`);
+    }
+    const commit = spawnGit([
+        '--git-dir',
+        gitDir,
+        '--work-tree',
+        cwd,
+        'commit',
+        '--quiet',
+        '-m',
+        message,
+    ], { cwd, env: shadowEnv() });
+    if (commit.status !== 0) {
+        throw new ShadowGitUnavailableError(`shadow commit failed: ${describeSpawn(commit)}`);
+    }
+    const sha = spawnGit(['--git-dir', gitDir, '--work-tree', cwd, 'rev-parse', 'HEAD'], { cwd, env: shadowEnv() });
+    if (sha.status !== 0) {
+        throw new ShadowGitUnavailableError(`shadow rev-parse HEAD failed: ${describeSpawn(sha)}`);
+    }
+    return sha.stdout.trim();
+}
+/**
+ * List recent checkpoints for `taskId`, newest-first. Returns an
+ * empty array when the shadow does not exist (no edits committed
+ * yet) — the operator hint ("no checkpoints recorded") lives in the
+ * REPL renderer, not here.
+ *
+ * `limit` is clamped to [1, 200].
+ */
+export function listCheckpoints(cwd, taskId, limit = 20) {
+    const gitDir = shadowGitDir(cwd, taskId);
+    if (!existsSync(gitDir))
+        return [];
+    const clamped = Math.max(1, Math.min(200, Math.floor(limit)));
+    const log = spawnGit([
+        '--git-dir',
+        gitDir,
+        '--work-tree',
+        cwd,
+        'log',
+        `--max-count=${clamped}`,
+        // Tab-delimited so we can split on a char that does not appear
+        // in commit messages (we sanitise tabs out when composing the
+        // dispatcher message).
+        '--pretty=format:%H%x09%ct%x09%s',
+    ], { cwd, env: shadowEnv() });
+    if (log.status !== 0) {
+        // The shadow exists but `git log` failed (likely corrupt). Return
+        // empty — the REPL renderer surfaces "no checkpoints" rather than
+        // tearing through error UX. Callers that need to know about the
+        // corruption should use `verifyShadow` (future).
+        return [];
+    }
+    const out = [];
+    for (const line of log.stdout.split('\n')) {
+        if (line.length === 0)
+            continue;
+        const [sha, ctRaw, ...rest] = line.split('\t');
+        if (!sha || !ctRaw)
+            continue;
+        const ct = Number.parseInt(ctRaw, 10);
+        if (!Number.isFinite(ct))
+            continue;
+        out.push({
+            sha,
+            shortSha: sha.slice(0, 7),
+            message: rest.join('\t'),
+            committedAt: ct * 1000,
+        });
+    }
+    return out;
+}
+/**
+ * Thrown when the operator declines the confirmation prompt OR when
+ * the prompt times out. Distinct from `ShadowGitUnavailableError` so
+ * callers can differentiate "operator-said-no" from "git-broke".
+ */
+export class CheckpointRestoreCancelledError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CheckpointRestoreCancelledError';
+    }
+}
+const DEFAULT_RESTORE_PROMPT_TIMEOUT_MS = 30_000;
+/**
+ * Restore the working tree to the snapshot at `sha`. Destructive:
+ * runs `git checkout --` against every tracked path, overwriting
+ * local changes.
+ *
+ * Triple-review P1-3 — before this fix `restoreCheckpoint` ran
+ * without any confirmation. The slash-handler enforced UX out-of-band,
+ * but a direct API caller (a future `pugi-mcp` tool, a test, an agent
+ * toolcall) would happily overwrite the work tree. The gate here keeps
+ * the function safe-by-default while still letting callers opt out
+ * with `--yes` or by piping stdin (non-TTY auto-yes — matches every
+ * Unix `rm -i` convention).
+ *
+ * Implementation note: we use `git checkout <sha> -- :/` (path pattern
+ * matching the whole work tree) rather than `reset --hard` because
+ * `reset --hard` would move the shadow's HEAD, breaking the
+ * "checkpoint <sha>" anchor for any later `restoreCheckpoint` call.
+ * Operators expect к be able to restore checkpoint A, then checkpoint
+ * B, then checkpoint A again — `checkout` preserves that property
+ * because HEAD stays put.
+ */
+export async function restoreCheckpoint(cwd, taskId, sha, options = {}) {
+    const gitDir = shadowGitDir(cwd, taskId);
+    if (!existsSync(gitDir)) {
+        throw new ShadowGitUnavailableError(`no shadow repo for task ${sanitizeTaskId(taskId)}`);
+    }
+    if (!/^[0-9a-f]{4,40}$/i.test(sha)) {
+        throw new ShadowGitUnavailableError(`refuse to restore: '${sha}' does not look like a git SHA`);
+    }
+    // Confirmation gate. `--yes` skips. Non-TTY stdin auto-confirms
+    // (scripted contexts must not block indefinitely on a prompt). When
+    // stdin is a TTY we ask y/N with a 30s timeout — default-N to
+    // "did nothing destructive" rather than "operator presumed agreement".
+    if (!options.yes && process.stdin.isTTY) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_RESTORE_PROMPT_TIMEOUT_MS;
+        const question = `restore shadow checkpoint ${sha.slice(0, 7)}? destroys local changes in ${cwd}. [y/N]: `;
+        const reply = options.prompt
+            ? await options.prompt(question, timeoutMs)
+            : await defaultPrompt(question, timeoutMs);
+        if (!/^y(es)?$/i.test(reply.trim())) {
+            throw new CheckpointRestoreCancelledError(`restore cancelled by operator (answered '${reply.trim()}')`);
+        }
+    }
+    // Verify the SHA resolves to a real commit before we touch the work
+    // tree. `git cat-file -t <sha>` returns "commit" for a commit;
+    // anything else (or non-zero exit) we refuse.
+    const probe = spawnGit(['--git-dir', gitDir, '--work-tree', cwd, 'cat-file', '-t', sha], { cwd, env: shadowEnv() });
+    if (probe.status !== 0 || probe.stdout.trim() !== 'commit') {
+        throw new ShadowGitUnavailableError(`refuse to restore: ${sha} is not a commit in shadow repo`);
+    }
+    const checkout = spawnGit([
+        '--git-dir',
+        gitDir,
+        '--work-tree',
+        cwd,
+        'checkout',
+        sha,
+        '--',
+        ':/',
+    ], { cwd, env: shadowEnv() });
+    if (checkout.status !== 0) {
+        throw new ShadowGitUnavailableError(`shadow restore failed: ${describeSpawn(checkout)}`);
+    }
+}
+/**
+ * Return the diff between `sha` and the current working tree (HEAD
+ * of shadow). Format is unified diff text; the REPL renders it
+ * verbatim with monospace + colour gates. Empty string when there
+ * are no differences.
+ */
+export function diffCheckpoint(cwd, taskId, sha) {
+    const gitDir = shadowGitDir(cwd, taskId);
+    if (!existsSync(gitDir)) {
+        throw new ShadowGitUnavailableError(`no shadow repo for task ${sanitizeTaskId(taskId)}`);
+    }
+    if (!/^[0-9a-f]{4,40}$/i.test(sha)) {
+        throw new ShadowGitUnavailableError(`refuse to diff: '${sha}' does not look like a git SHA`);
+    }
+    const diff = spawnGit([
+        '--git-dir',
+        gitDir,
+        '--work-tree',
+        cwd,
+        'diff',
+        '--no-color',
+        sha,
+        '--',
+    ], { cwd, env: shadowEnv() });
+    if (diff.status !== 0 && diff.status !== 1) {
+        // Git diff exit 0 = no diff, 1 = diff present; anything else is an
+        // error.
+        throw new ShadowGitUnavailableError(`shadow diff failed: ${describeSpawn(diff)}`);
+    }
+    return diff.stdout;
+}
+/**
+ * Garbage-collect old shadow repos under `<cwd>/.pugi/checkpoints/`.
+ * Removes a directory iff:
+ *
+ *  - Its mtime is older than `maxAgeDays` days, OR
+ *  - The aggregate disk usage of the checkpoints root exceeds
+ *    `maxSizeMB` (oldest entries removed first until back under).
+ *
+ * Returns a `PruneReport`. Best-effort: per-entry failures are
+ * swallowed and excluded from `removedIds`, but the scan continues.
+ */
+export function pruneOldShadows(cwd, maxAgeDays = 7, maxSizeMB = 100) {
+    const root = resolve(cwd, '.pugi', 'checkpoints');
+    if (!existsSync(root)) {
+        return { scanned: 0, removed: 0, removedIds: [], totalBytesFreed: 0 };
+    }
+    const rawEntries = readdirSync(root, { withFileTypes: true });
+    const entries = rawEntries
+        .filter((d) => d.isDirectory())
+        .map((d) => {
+        const name = d.name;
+        const p = join(root, name);
+        const s = safeStat(p);
+        const size = computeDirSize(p);
+        return {
+            id: name,
+            path: p,
+            mtimeMs: s ? Number(s.mtimeMs) : 0,
+            sizeBytes: size,
+        };
+    });
+    // Triple-review P1-2 — explicit mtime ascending sort so the
+    // oldest entries land at index 0 and both passes (age + size) prune
+    // the right ones. The sort key is `statSync(p).mtimeMs` (via
+    // `safeStat` for the directory itself); stat-failed entries get
+    // mtime=0 and naturally sort first (preferred — broken checkpoints
+    // should be cleaned up before well-formed ones). Tie-breaker by id
+    // makes the sweep order deterministic for tests. We re-sort
+    // defensively before the size pass to keep the invariant if a
+    // future refactor reorders the array between passes.
+    const mtimeSort = (a, b) => a.mtimeMs - b.mtimeMs || a.id.localeCompare(b.id);
+    entries.sort(mtimeSort);
+    const ageCutoffMs = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    const removed = [];
+    let freed = 0;
+    const remove = (idx) => {
+        const entry = entries[idx];
+        if (!entry)
+            return;
+        try {
+            rmSync(entry.path, { recursive: true, force: true });
+            removed.push(entry.id);
+            freed += entry.sizeBytes;
+            entries.splice(idx, 1);
+        }
+        catch {
+            // Skip — operator can clean up by hand.
+        }
+    };
+    // Pass 1 — age. Walk forwards-with-splice so indices stay valid.
+    let i = 0;
+    while (i < entries.length) {
+        const entry = entries[i];
+        if (entry && entry.mtimeMs > 0 && entry.mtimeMs < ageCutoffMs) {
+            remove(i);
+        }
+        else {
+            i += 1;
+        }
+    }
+    // Pass 2 — size cap. Defensive re-sort: pass 1 used splice к remove
+    // entries which preserves relative order, but a future refactor
+    // (parallel-scan, async stat) might reorder. Re-sorting before the
+    // size pass guarantees `entries[0]` remains the oldest survivor.
+    entries.sort(mtimeSort);
+    const maxBytes = maxSizeMB * 1024 * 1024;
+    let total = entries.reduce((sum, e) => sum + e.sizeBytes, 0);
+    while (total > maxBytes && entries.length > 0) {
+        const before = entries[0]?.sizeBytes ?? 0;
+        remove(0);
+        total -= before;
+    }
+    return {
+        scanned: removed.length + entries.length,
+        removed: removed.length,
+        removedIds: removed,
+        totalBytesFreed: freed,
+    };
+}
+/**
+ * Compute on-disk usage for a directory tree. Pure utility — exposed
+ * so `pruneOldShadows` can be tested deterministically and so future
+ * `pugi doctor` surfaces can read the same number.
+ */
+export function computeDirSize(dir) {
+    if (!existsSync(dir))
+        return 0;
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const next = stack.pop();
+        if (!next)
+            break;
+        let kids = [];
+        try {
+            kids = readdirSync(next, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const k of kids) {
+            const name = k.name;
+            const p = join(next, name);
+            if (k.isDirectory()) {
+                stack.push(p);
+                continue;
+            }
+            const s = safeStat(p);
+            if (s)
+                total += Number(s.size);
+        }
+    }
+    return total;
+}
+/**
+ * Sanitise an operator-supplied taskId so it cannot escape the
+ * checkpoints directory tree. Reject anything containing path
+ * separators or `..` segments; fall back to `DEFAULT_TASK_ID`.
+ */
+export function sanitizeTaskId(taskId) {
+    const trimmed = (taskId ?? '').trim();
+    if (trimmed.length === 0)
+        return DEFAULT_TASK_ID;
+    if (trimmed.includes('/') || trimmed.includes('\\') || trimmed.includes('..')) {
+        return DEFAULT_TASK_ID;
+    }
+    // Whitelist: alphanumerics, dot, dash, underscore.
+    if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) {
+        return DEFAULT_TASK_ID;
+    }
+    return trimmed;
+}
+/**
+ * Compose the canonical commit message for a dispatcher hook step.
+ * Exposed as a helper so the dispatcher and tests agree on the
+ * exact format the slash list renderer can parse back.
+ *
+ * Format: `pugi <task-id> step <n>: <tool-name> <relative-path>`
+ *
+ * `relativePath` is normalised against `cwd` so absolute paths from
+ * the applicator turn into workspace-relative entries.
+ */
+export function formatCheckpointMessage(input) {
+    const safeTask = sanitizeTaskId(input.taskId);
+    const rel = relative(input.cwd, input.absPath) || input.absPath;
+    // Sanitise control chars (tabs / newlines) so the `git log` parser
+    // can rely on tab-delimited output (see `listCheckpoints`).
+    const safeTool = input.toolName.replace(/[\s\t\r\n]+/g, '_');
+    const safeRel = rel.replace(/[\t\r\n]+/g, ' ');
+    return `pugi ${safeTask} step ${input.step}: ${safeTool} ${safeRel}`;
+}
+/* ------------------------------ internals ------------------------------ */
+/**
+ * Per-call env for shadow git invocations. Pins author + committer +
+ * dates к deterministic values so the shadow log is reproducible and
+ * never leaks the operator's host identity. We do NOT inherit the
+ * user's `process.env` GIT_* overrides; the spawn wrapper merges this
+ * onto the parent env explicitly.
+ *
+ * Triple-review P1-1 — `/dev/null` is the Unix bit-bucket; Windows
+ * uses `NUL`. Passing `/dev/null` к `GIT_CONFIG_*` on Windows makes
+ * git try to open a literal file named `/dev/null`, which either
+ * silently fails or, worse, on a misconfigured CI box succeeds and
+ * gets created as a file under the shadow root. The fix routes by
+ * `process.platform`.
+ *
+ * Triple-review P1-4 — pin `GIT_AUTHOR_DATE` + `GIT_COMMITTER_DATE`
+ * to the supplied timestamp (ISO 8601) so `git log` output is
+ * reproducible across hosts. When no timestamp is supplied the caller
+ * is expected to be `initShadowRepo` whose commit is bootstrap-only;
+ * we still emit a stable ISO date so test corpora hash-stable.
+ */
+function shadowEnv(now = Date.now()) {
+    const nullDevice = process.platform === 'win32' ? 'NUL' : '/dev/null';
+    const isoDate = new Date(now).toISOString();
+    return {
+        ...process.env,
+        GIT_AUTHOR_NAME: SHADOW_AUTHOR_NAME,
+        GIT_AUTHOR_EMAIL: SHADOW_AUTHOR_EMAIL,
+        GIT_COMMITTER_NAME: SHADOW_AUTHOR_NAME,
+        GIT_COMMITTER_EMAIL: SHADOW_AUTHOR_EMAIL,
+        // Pin commit dates for reproducible shadow logs. ISO 8601 is the
+        // format git natively accepts; the GIT_*_DATE pair propagates к
+        // both `git commit -m` and `git --git-dir … commit` calls.
+        GIT_AUTHOR_DATE: isoDate,
+        GIT_COMMITTER_DATE: isoDate,
+        // Disable any global hook config so the shadow can't fire the
+        // operator's commit-msg / pre-commit hooks from the user's repo.
+        GIT_CONFIG_GLOBAL: nullDevice,
+        GIT_CONFIG_SYSTEM: nullDevice,
+    };
+}
+function spawnGit(args, opts) {
+    const res = spawnSync('git', args, {
+        cwd: opts.cwd,
+        env: opts.env ?? process.env,
+        encoding: 'utf8',
+    });
+    return {
+        status: res.status,
+        stdout: typeof res.stdout === 'string' ? res.stdout : String(res.stdout ?? ''),
+        stderr: typeof res.stderr === 'string' ? res.stderr : String(res.stderr ?? ''),
+        error: res.error,
+    };
+}
+function describeSpawn(res) {
+    const stderr = res.stderr.trim();
+    const stdout = res.stdout.trim();
+    if (res.error)
+        return `${res.error.message}${stderr ? ` | ${stderr}` : ''}`;
+    const status = res.status ?? 'n/a';
+    return [
+        `exit=${status}`,
+        stderr ? `stderr=${stderr}` : '',
+        stdout && !stderr ? `stdout=${stdout}` : '',
+    ]
+        .filter((s) => s.length > 0)
+        .join(' ');
+}
+function safeStat(p) {
+    try {
+        return statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Default readline-based prompt with a hard timeout. Resolves к the
+ * empty string on timeout, which the caller interprets as "operator
+ * declined". We deliberately do NOT use `process.stdin.once('data')`
+ * directly because that breaks Ctrl-C: readline gives us the standard
+ * signal handlers for free.
+ *
+ * Lifted out as a module-level helper so the spec can inject a stub
+ * via `RestoreCheckpointOptions.prompt` without touching real stdin.
+ */
+function defaultPrompt(question, timeoutMs) {
+    return new Promise((resolveOuter) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                rl.close();
+            }
+            catch {
+                /* ignore */
+            }
+            resolveOuter(value);
+        };
+        const timer = setTimeout(() => finish(''), Math.max(100, timeoutMs));
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        rl.question(question, (answer) => {
+            clearTimeout(timer);
+            finish(answer);
+        });
+    });
+}
+//# sourceMappingURL=shadow-git.js.map