@contentful/experience-design-system-cli 2.12.0 → 2.12.1-dev-build-bae15c7.0

package/dist/src/runs/resolve-run-target.js

@@ -0,0 +1,45 @@
+import { homedir } from 'node:os';
+import { resolve as resolvePath } from 'node:path';
+import { findAllRunsBySavePath, getRun } from './store.js';
+/**
+ * Decide whether a positional CLI arg refers to a run-id or a filesystem path,
+ * then look up the corresponding RunRecord.
+ *
+ * Mirrors `git checkout` accepting either a sha or a ref: anything that *looks
+ * like* a path is treated as one; otherwise we fall back to a run-id lookup.
+ *
+ * Path detection: arg starts with `/`, `./`, `../`, or `~/`, OR equals `.`,
+ * OR equals `~`.
+ */
+export async function resolveRunTarget(arg) {
+    if (looksLikePath(arg)) {
+        const absolute = resolvePath(expandHome(arg));
+        const matches = await findAllRunsBySavePath(absolute);
+        if (matches.length === 0) {
+            throw new Error(`No run recorded for path ${absolute}. Run 'experiences runs' to list known runs.`);
+        }
+        if (matches.length === 1) {
+            return matches[0];
+        }
+        // Multi-match: newest createdAt wins. ISO UTC timestamps compare
+        // lexicographically (see store.ts: createdAt = new Date().toISOString()).
+        const sorted = [...matches].sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+        const newest = sorted[0];
+        const olderCount = matches.length - 1;
+        process.stderr.write(`Multiple runs at ${absolute}; using newest ${newest.id} (createdAt ${newest.createdAt}). ${olderCount} older candidates ignored.\n`);
+        return newest;
+    }
+    return getRun(arg);
+}
+function looksLikePath(arg) {
+    if (arg === '.' || arg === '~')
+        return true;
+    return arg.startsWith('/') || arg.startsWith('./') || arg.startsWith('../') || arg.startsWith('~/');
+}
+function expandHome(arg) {
+    if (arg === '~')
+        return homedir();
+    if (arg.startsWith('~/'))
+        return resolvePath(homedir(), arg.slice(2));
+    return arg;
+}

package/dist/src/runs/run-picker-mount.d.ts

@@ -0,0 +1,46 @@
+import { type RunRecord } from './store.js';
+/**
+ * Flags whose presence suppresses the run-picker. The picker is meant for the
+ * fresh interactive `experiences import` entry point; any flag that already
+ * routes the wizard down a non-default path means the operator has been
+ * specific about intent, so we honor that and skip silently.
+ *
+ * Flag names match the camelCase option object commander hands to the action
+ * handler (see `command.ts`).
+ */
+export type RunPickerFlags = {
+    pushFromRun?: string;
+    modify?: string;
+    /** Set only when the operator explicitly passed `--project`. */
+    project?: string;
+    autoAcceptScope?: boolean;
+    printPrompt?: boolean;
+    dryRun?: boolean;
+};
+export type ShouldShowRunPickerInput = {
+    flags: RunPickerFlags;
+    isTTY: boolean;
+    /** Absolute path to runs.json. Defaults to the platform-standard path. */
+    runsJsonPath?: string;
+};
+export type ShouldShowRunPickerResult = {
+    shouldShow: boolean;
+    runs: RunRecord[];
+};
+/**
+ * Pure decision helper for whether the wizard should open with the run picker.
+ *
+ * Picker shows iff ALL hold:
+ *   1. `~/.config/experiences/runs.json` exists
+ *   2. The file has >=1 run entry
+ *   3. None of `--push-from-run`, `--modify`, `--project`,
+ *      `--auto-accept-scope`, `--print-prompt`, or `--dry-run` were passed
+ *   4. stdin is a TTY
+ *
+ * On any failure (including ENOENT or a parse error), the helper returns
+ * `{ shouldShow: false, runs: [] }`. We deliberately swallow parse errors
+ * here: the wizard's normal entry point is more important than surfacing a
+ * malformed runs.json — the operator can still use `experiences runs ls` to
+ * diagnose later.
+ */
+export declare function shouldShowRunPicker(input: ShouldShowRunPickerInput): Promise<ShouldShowRunPickerResult>;

package/dist/src/runs/run-picker-mount.js

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { READABLE_VERSIONS, runsFilePath } from './store.js';
+function migrateRecord(rec) {
+    return {
+        ...rec,
+        tokensPath: rec.tokensPath ?? null,
+        tokenSessionId: rec.tokenSessionId ?? null,
+    };
+}
+function hasBlockingFlag(flags) {
+    if (flags.pushFromRun !== undefined)
+        return true;
+    if (flags.modify !== undefined)
+        return true;
+    if (flags.project !== undefined)
+        return true;
+    if (flags.autoAcceptScope)
+        return true;
+    if (flags.printPrompt)
+        return true;
+    if (flags.dryRun)
+        return true;
+    return false;
+}
+/**
+ * Pure decision helper for whether the wizard should open with the run picker.
+ *
+ * Picker shows iff ALL hold:
+ *   1. `~/.config/experiences/runs.json` exists
+ *   2. The file has >=1 run entry
+ *   3. None of `--push-from-run`, `--modify`, `--project`,
+ *      `--auto-accept-scope`, `--print-prompt`, or `--dry-run` were passed
+ *   4. stdin is a TTY
+ *
+ * On any failure (including ENOENT or a parse error), the helper returns
+ * `{ shouldShow: false, runs: [] }`. We deliberately swallow parse errors
+ * here: the wizard's normal entry point is more important than surfacing a
+ * malformed runs.json — the operator can still use `experiences runs ls` to
+ * diagnose later.
+ */
+export async function shouldShowRunPicker(input) {
+    if (!input.isTTY)
+        return { shouldShow: false, runs: [] };
+    if (hasBlockingFlag(input.flags))
+        return { shouldShow: false, runs: [] };
+    const path = input.runsJsonPath ?? runsFilePath();
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return { shouldShow: false, runs: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { shouldShow: false, runs: [] };
+    }
+    // Accept any version this CLI can read (see store.ts READABLE_VERSIONS).
+    // Pre-PR-#78 v1 files are migrated to v2 in memory below; gating on strict
+    // equality with RUNS_FILE_VERSION would silently hide every v1 run.
+    if (!READABLE_VERSIONS.has(parsed.version)) {
+        return { shouldShow: false, runs: [] };
+    }
+    const rawRuns = Array.isArray(parsed.runs) ? parsed.runs : [];
+    if (rawRuns.length === 0)
+        return { shouldShow: false, runs: [] };
+    const runs = rawRuns.map(migrateRecord);
+    return { shouldShow: true, runs };
+}

package/dist/src/runs/run-picker.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { RunRecord } from './store.js';
+export type RunPickerAction = 'push' | 'modify' | 'new';
+export type RunPickerSelection = {
+    /** null only when `action === 'new'`. */
+    runId: string | null;
+    action: RunPickerAction;
+};
+export type RunPickerProps = {
+    runs: RunRecord[];
+    /** Optional set of run ids that have been classified stale by the
+     *  invalidation check. Rows in this set render with a dim "(stale)" tag. */
+    staleRunIds?: ReadonlySet<string>;
+    onSelect: (selection: RunPickerSelection) => void;
+    onCancel: () => void;
+};
+export declare function RunPicker({ runs, staleRunIds, onSelect, onCancel }: RunPickerProps): React.ReactElement;

package/dist/src/runs/run-picker.js

@@ -0,0 +1,145 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text } from 'ink';
+import { useImmediateInput } from '../analyze/select/tui/hooks/useImmediateInput.js';
+const COLLAPSED_LIMIT = 3;
+/**
+ * The picker collapses to top 3 + Show all only when there are 5+ total.
+ * Four or fewer runs render in full.
+ */
+const COLLAPSE_THRESHOLD = 5;
+/**
+ * Format the createdAt timestamp as `YYYY-MM-DD HH:MM` in the operator's
+ * local timezone. We intentionally use local time (not UTC) because the
+ * picker is for human recognition — operators expect to see times in the
+ * same zone they were when the run happened.
+ */
+function formatCreatedAt(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, '0');
+    const dd = String(d.getDate()).padStart(2, '0');
+    const hh = String(d.getHours()).padStart(2, '0');
+    const mi = String(d.getMinutes()).padStart(2, '0');
+    return `${yyyy}-${mm}-${dd} ${hh}:${mi}`;
+}
+function runLine(run) {
+    const date = formatCreatedAt(run.createdAt);
+    const pushedTag = run.pushedTo ? 'pushed' : 'not pushed';
+    const count = `${run.componentCount} component${run.componentCount === 1 ? '' : 's'}`;
+    return `${run.id} - ${date} - ${run.projectPath} (${count}, ${pushedTag})`;
+}
+const ACTION_OPTIONS = [
+    { key: 'push', label: 'Push', description: "Push this run's recorded session to Contentful." },
+    { key: 'modify', label: 'Modify', description: 'Re-open the wizard at final-review with this run pre-filled.' },
+    { key: 'cancel', label: 'Cancel', description: 'Back to the run list.' },
+];
+function ActionScreen({ runId, onChoose, onBack, }) {
+    const [focusIdx, setFocusIdx] = useState(0);
+    const fire = (opt) => {
+        if (opt === 'cancel')
+            return onBack();
+        onChoose(opt);
+    };
+    useImmediateInput((rawInput, key) => {
+        if (key.upArrow || rawInput === 'k') {
+            setFocusIdx((i) => (i - 1 + ACTION_OPTIONS.length) % ACTION_OPTIONS.length);
+            return;
+        }
+        if (key.downArrow || rawInput === 'j') {
+            setFocusIdx((i) => (i + 1) % ACTION_OPTIONS.length);
+            return;
+        }
+        if (key.return) {
+            fire(ACTION_OPTIONS[focusIdx].key);
+            return;
+        }
+        if (key.escape || rawInput === 'q') {
+            onBack();
+            return;
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsx(Text, { bold: true, children: "Push or modify?" }), _jsxs(Text, { dimColor: true, children: ["Run ", runId] }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: ACTION_OPTIONS.map((opt, i) => {
+                    const focused = i === focusIdx;
+                    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: focused ? 'cyan' : undefined, children: focused ? '>' : ' ' }), _jsx(Text, { color: focused ? 'cyan' : undefined, children: opt.label }), _jsxs(Text, { dimColor: true, children: ["- ", opt.description] })] }, opt.key));
+                }) }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[j/k] Navigate" }), _jsx(Text, { dimColor: true, children: "[Enter] Select" }), _jsx(Text, { dimColor: true, children: "[Esc] Back" })] })] }));
+}
+function buildRows(runs, expanded) {
+    const showAll = expanded || runs.length < COLLAPSE_THRESHOLD;
+    const visible = showAll ? runs : runs.slice(0, COLLAPSED_LIMIT);
+    const rows = visible.map((run) => ({ kind: 'run', run }));
+    if (!showAll)
+        rows.push({ kind: 'show-all' });
+    rows.push({ kind: 'new' });
+    return rows;
+}
+export function RunPicker({ runs, staleRunIds, onSelect, onCancel }) {
+    const [expanded, setExpanded] = useState(false);
+    const [focusIdx, setFocusIdx] = useState(0);
+    // When non-null, render the Push/Modify/Cancel sub-screen for this run.
+    const [actionRunId, setActionRunId] = useState(null);
+    const rows = buildRows(runs, expanded);
+    // Clamp focus if the row count shrinks (e.g. after expansion changes layout).
+    const clampedFocus = Math.min(focusIdx, rows.length - 1);
+    const selectRow = (row) => {
+        if (row.kind === 'show-all') {
+            setExpanded(true);
+            // Keep cursor on the first newly-revealed run for continuity.
+            setFocusIdx(COLLAPSED_LIMIT);
+            return;
+        }
+        if (row.kind === 'new') {
+            onSelect({ runId: null, action: 'new' });
+            return;
+        }
+        setActionRunId(row.run.id);
+    };
+    useImmediateInput((rawInput, key) => {
+        if (actionRunId !== null) {
+            // Sub-screen owns input while it's active. (ActionScreen also installs
+            // its own useImmediateInput; only one is mounted at a time so there's
+            // no double-handle.)
+            return;
+        }
+        if (key.upArrow || rawInput === 'k') {
+            setFocusIdx((i) => (i - 1 + rows.length) % rows.length);
+            return;
+        }
+        if (key.downArrow || rawInput === 'j') {
+            setFocusIdx((i) => (i + 1) % rows.length);
+            return;
+        }
+        if (rawInput === 'n') {
+            onSelect({ runId: null, action: 'new' });
+            return;
+        }
+        if (rawInput === 'q' || key.escape) {
+            onCancel();
+            return;
+        }
+        if (key.return) {
+            const row = rows[clampedFocus];
+            if (row)
+                selectRow(row);
+            return;
+        }
+    });
+    if (actionRunId !== null) {
+        return (_jsx(ActionScreen, { runId: actionRunId, onChoose: (action) => onSelect({ runId: actionRunId, action }), onBack: () => setActionRunId(null) }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Text, { bold: true, children: ["Found ", runs.length, " prior run", runs.length === 1 ? '' : 's', ". Continue from one?"] }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: rows.map((row, i) => {
+                    const focused = i === clampedFocus;
+                    const color = focused ? 'cyan' : undefined;
+                    const cursor = focused ? '>' : ' ';
+                    if (row.kind === 'run') {
+                        const isStale = staleRunIds?.has(row.run.id) ?? false;
+                        return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: color, children: cursor }), _jsx(Text, { color: color, children: runLine(row.run) }), isStale ? _jsx(Text, { dimColor: true, children: " (stale)" }) : null] }, `run-${row.run.id}`));
+                    }
+                    if (row.kind === 'show-all') {
+                        return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: color, children: cursor }), _jsxs(Text, { color: color, children: ["Show all (", runs.length, ")"] })] }, "show-all"));
+                    }
+                    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: color, children: cursor }), _jsx(Text, { color: color, children: "[n] Start a new run" })] }, "new"));
+                }) }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[j/k] Navigate" }), _jsx(Text, { dimColor: true, children: "[Enter] Select" }), _jsx(Text, { dimColor: true, children: "[n] New" }), _jsx(Text, { dimColor: true, children: "[q] Quit" })] })] }));
+}

package/dist/src/runs/save-conflict.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+export type SaveConflictGateProps = {
+    path: string;
+    onOverwrite: () => void;
+    onNew: () => void;
+    onCancel: () => void;
+};
+export declare function SaveConflictGate({ path, onOverwrite, onNew, onCancel }: SaveConflictGateProps): React.ReactElement;

package/dist/src/runs/save-conflict.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Box, Text } from 'ink';
+import { useImmediateInput } from '../analyze/select/tui/hooks/useImmediateInput.js';
+const OPTIONS = [
+    { key: 'overwrite', label: 'overwrite', description: 'Replace existing files at this path.' },
+    { key: 'new', label: 'new', description: 'Write to a timestamped subdirectory.' },
+    { key: 'cancel', label: 'cancel', description: 'Go back and pick a different path.' },
+];
+export function SaveConflictGate({ path, onOverwrite, onNew, onCancel }) {
+    // Default cursor on "new" (index 1) — the safer non-destructive choice.
+    const [focusIdx, setFocusIdx] = useState(1);
+    const fire = (opt) => {
+        if (opt === 'overwrite')
+            onOverwrite();
+        else if (opt === 'new')
+            onNew();
+        else
+            onCancel();
+    };
+    useImmediateInput((rawInput, key) => {
+        if (rawInput === 'o') {
+            fire('overwrite');
+            return;
+        }
+        if (rawInput === 'n') {
+            fire('new');
+            return;
+        }
+        if (rawInput === 'c') {
+            fire('cancel');
+            return;
+        }
+        if (key.upArrow) {
+            setFocusIdx((i) => (i - 1 + OPTIONS.length) % OPTIONS.length);
+            return;
+        }
+        if (key.downArrow) {
+            setFocusIdx((i) => (i + 1) % OPTIONS.length);
+            return;
+        }
+        if (key.return) {
+            fire(OPTIONS[focusIdx].key);
+            return;
+        }
+        if (key.escape) {
+            onCancel();
+            return;
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, paddingX: 2, paddingY: 1, children: [_jsx(Text, { bold: true, color: "yellow", children: "A prior export exists at:" }), _jsx(Text, { children: path }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: OPTIONS.map((opt, i) => {
+                    const focused = i === focusIdx;
+                    const shortcut = opt.label[0];
+                    return (_jsxs(Box, { gap: 1, children: [_jsx(Text, { color: focused ? 'cyan' : undefined, children: focused ? '❯' : ' ' }), _jsxs(Text, { color: focused ? 'cyan' : undefined, children: ["[", shortcut, "]", opt.label.slice(1)] }), _jsxs(Text, { dimColor: true, children: ["\u2014 ", opt.description] })] }, opt.key));
+                }) }), _jsxs(Box, { gap: 3, marginTop: 1, children: [_jsx(Text, { dimColor: true, children: "[o/n/c] Shortcut" }), _jsx(Text, { dimColor: true, children: "[\u2191/\u2193 + Enter] Navigate" }), _jsx(Text, { dimColor: true, children: "[Esc] Cancel" })] })] }));
+}

package/dist/src/runs/save-path-resolver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Returns true if `components.json` or `tokens.json` already exists at `path`.
+ * Used by the wizard to decide whether to render the save-conflict gate before
+ * writing.
+ */
+export declare function detectSaveConflict(path: string): Promise<boolean>;
+/**
+ * Build a timestamped subdirectory under `base` for the "new" branch of the
+ * save-conflict gate. Format: `<base>/dsi-YYYYMMDD-HHMMSS` (local time).
+ */
+export declare function buildTimestampedSubdir(base: string, now?: Date): string;
+/**
+ * Headless conflict-resolution mode for `experiences import --on-conflict`.
+ *
+ * - `overwrite` — write through; replace any existing files.
+ * - `skip`      — write to a timestamped subdir under the requested path.
+ * - `fail`      — refuse to write; surface the conflicting filenames.
+ */
+export type OnConflictMode = 'overwrite' | 'skip' | 'fail';
+export type ResolveSavePathOptions = {
+    /** When provided, applies the chosen mode automatically (no interactive gate). */
+    onConflict?: OnConflictMode;
+    /** Injected for deterministic tests; falls back to `new Date()`. */
+    now?: Date;
+};
+/**
+ * Result of resolving a save path.
+ *
+ * `no-conflict` / `conflict` preserve the original two-state shape consumed by
+ * the wizard's interactive gate. `write` and `fail` are the headless variants
+ * produced when `onConflict` is supplied — `write` means "go ahead with this
+ * path" and `fail` carries the conflicting filenames for the operator error.
+ */
+export type ResolveSavePathResult = {
+    kind: 'no-conflict';
+    path: string;
+} | {
+    kind: 'conflict';
+    path: string;
+} | {
+    kind: 'write';
+    path: string;
+} | {
+    kind: 'fail';
+    conflict: {
+        path: string;
+        files: string[];
+    };
+};
+/**
+ * Probe the requested save path and report whether the wizard needs to render
+ * the conflict gate, or — when `onConflict` is supplied — resolve the conflict
+ * headlessly using the chosen mode.
+ */
+export declare function resolveSavePath(path: string, options?: ResolveSavePathOptions): Promise<ResolveSavePathResult>;

package/dist/src/runs/save-path-resolver.js

@@ -0,0 +1,71 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * The set of files the wizard / CLI may overwrite in the save directory.
+ * Centralised so conflict detection and conflict reporting stay in lock-step.
+ */
+const SAVE_FILES = ['components.json', 'tokens.json'];
+/**
+ * Returns the subset of `SAVE_FILES` that already exist at `path`. Order is
+ * stable so test assertions can reason about it.
+ */
+async function listConflictingFiles(path) {
+    const conflicts = [];
+    for (const name of SAVE_FILES) {
+        try {
+            await access(join(path, name));
+            conflicts.push(name);
+        }
+        catch {
+            // ENOENT — file not present, keep checking the others.
+        }
+    }
+    return conflicts;
+}
+/**
+ * Returns true if `components.json` or `tokens.json` already exists at `path`.
+ * Used by the wizard to decide whether to render the save-conflict gate before
+ * writing.
+ */
+export async function detectSaveConflict(path) {
+    return (await listConflictingFiles(path)).length > 0;
+}
+function pad2(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+/**
+ * Build a timestamped subdirectory under `base` for the "new" branch of the
+ * save-conflict gate. Format: `<base>/dsi-YYYYMMDD-HHMMSS` (local time).
+ */
+export function buildTimestampedSubdir(base, now = new Date()) {
+    const y = now.getFullYear();
+    const m = pad2(now.getMonth() + 1);
+    const d = pad2(now.getDate());
+    const hh = pad2(now.getHours());
+    const mm = pad2(now.getMinutes());
+    const ss = pad2(now.getSeconds());
+    return join(base, `dsi-${y}${m}${d}-${hh}${mm}${ss}`);
+}
+/**
+ * Probe the requested save path and report whether the wizard needs to render
+ * the conflict gate, or — when `onConflict` is supplied — resolve the conflict
+ * headlessly using the chosen mode.
+ */
+export async function resolveSavePath(path, options = {}) {
+    const conflicts = await listConflictingFiles(path);
+    const hasConflict = conflicts.length > 0;
+    if (options.onConflict === undefined) {
+        return hasConflict ? { kind: 'conflict', path } : { kind: 'no-conflict', path };
+    }
+    if (!hasConflict) {
+        return { kind: 'write', path };
+    }
+    switch (options.onConflict) {
+        case 'overwrite':
+            return { kind: 'write', path };
+        case 'skip':
+            return { kind: 'write', path: buildTimestampedSubdir(path, options.now ?? new Date()) };
+        case 'fail':
+            return { kind: 'fail', conflict: { path, files: conflicts } };
+    }
+}

package/dist/src/runs/staleness.d.ts

@@ -0,0 +1,38 @@
+import type { RunRecord } from './store.js';
+export type Staleness = {
+    stale: boolean;
+    /** Component names whose source file's mtime no longer matches the
+     *  recorded fingerprint. */
+    staleComponents: string[];
+    /** True when the raw tokens file's mtime OR content hash drifted (or the
+     *  file went missing). */
+    staleTokens: boolean;
+    /** True when components.json on disk differs from the hash recorded at
+     *  save time, OR the file is missing. */
+    savedComponentsEdited: boolean;
+    /** True when tokens.json on disk differs from the hash recorded at save
+     *  time, OR the file is missing while a hash was recorded. */
+    savedTokensEdited: boolean;
+    /** Absolute paths of source files that were fingerprinted but have since
+     *  disappeared. Empty when nothing is missing. */
+    missingSourceFiles: string[];
+};
+/**
+ * Re-stat the source files and re-hash the saved artifacts captured by a
+ * run record's fingerprints, and report what (if anything) drifted.
+ *
+ * Returns `stale: false` when the run is missing a source fingerprint
+ * entirely (v2 records pre-dating runs.json v3 — treat as UNKNOWN, not
+ * stale, so existing runs keep replaying).
+ */
+export declare function checkRunStaleness(run: RunRecord): Promise<Staleness>;
+/**
+ * Render a short human-readable summary of a Staleness result, e.g.
+ * `src: 3, tokens, saved`. Returns the empty string when not stale.
+ */
+export declare function shortStalenessSummary(s: Staleness): string;
+/**
+ * Render a multi-line detail block for staleness output (used by `runs <id>`
+ * detail view and replay refusals). Caps long lists at 5 entries.
+ */
+export declare function formatStalenessDetail(s: Staleness): string[];