whydid 1.0.0

package/dist/core/diff.js

@@ -0,0 +1,30 @@
+import { createTwoFilesPatch, diffLines } from "diff";
+export function lineDiffStats(before, after) {
+    const parts = diffLines(before, after);
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    for (const part of parts) {
+        const lineCount = part.value.endsWith("\n") ? part.value.split("\n").length - 1 : part.value.split("\n").length;
+        if (part.added)
+            linesAdded += lineCount;
+        if (part.removed)
+            linesRemoved += lineCount;
+    }
+    return { linesAdded, linesRemoved };
+}
+export function unifiedDiff(filePath, before, after) {
+    return createTwoFilesPatch(filePath, filePath, before, after, "before", "after");
+}
+const isProbablyBinary = (buf) => buf.subarray(0, 8000).includes(0);
+export function computeFileDiff(store, change) {
+    const beforeBuf = change.beforeHash ? store.read(change.beforeHash) : Buffer.alloc(0);
+    const afterBuf = change.afterHash ? store.read(change.afterHash) : Buffer.alloc(0);
+    if (isProbablyBinary(beforeBuf) || isProbablyBinary(afterBuf)) {
+        return { unified: "Binary file differs.", linesAdded: 0, linesRemoved: 0, binary: true };
+    }
+    const before = beforeBuf.toString("utf-8");
+    const after = afterBuf.toString("utf-8");
+    const stats = lineDiffStats(before, after);
+    return { unified: unifiedDiff(change.filePath, before, after), ...stats, binary: false };
+}
+//# sourceMappingURL=diff.js.map

package/dist/core/engine.js

@@ -0,0 +1,321 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { buildManifest, diffManifests } from "./manifest.js";
+import { computeFileDiff } from "./diff.js";
+import { detectGit } from "../git/git.js";
+import { hashContent } from "../objects/store.js";
+import { isAutoGeneratedDocFile } from "./context-tree.js";
+// A fixed-size digest of "every tracked file's path and content hash",
+// stored per state as a cheap way to tell whether two states represent an
+// identical working tree. This was previously storing the raw, un-hashed
+// "path:hash\npath:hash\n..." string directly — at thousands of tracked
+// files that's hundreds of KB of text duplicated into every single state
+// row, unconditionally, and was confirmed (via dbstat on a synthetic
+// 4,000-file, 300-checkpoint project) to be the actual dominant cost in
+// db.sqlite — over 10x bigger than state_manifest itself, not just a
+// secondary factor. Nothing in the codebase reads working_tree_hash for
+// comparison today, so this was pure write-only dead weight; hashing it
+// down to 64 hex chars keeps the field genuinely useful for that purpose
+// going forward at negligible storage cost.
+function manifestFingerprint(manifest) {
+    const raw = manifest.map((m) => `${m.filePath}:${m.contentHash}`).join("\n");
+    return hashContent(Buffer.from(raw, "utf-8"));
+}
+function storeManifestBlobs(ctx, manifest, changes) {
+    const changedPaths = new Set(changes.filter((c) => c.changeType !== "deleted").map((c) => c.filePath));
+    for (const entry of manifest) {
+        if (!changedPaths.has(entry.filePath))
+            continue;
+        if (ctx.store.has(entry.contentHash))
+            continue;
+        const content = readFileSync(join(ctx.projectRoot, entry.filePath));
+        ctx.store.write(content);
+    }
+}
+function withLineStats(ctx, changes) {
+    return changes.map((change) => {
+        const diff = computeFileDiff(ctx.store, change);
+        return { ...change, linesAdded: diff.linesAdded, linesRemoved: diff.linesRemoved };
+    });
+}
+// Every Nth regular checkpoint gets a full manifest snapshot ("keyframe");
+// the rest rely on getStateManifest's delta-chain reconstruction. Bounds
+// reconstruction to at most this many ancestor hops (the initial state is
+// always a keyframe, so the walk always terminates) while cutting
+// state_manifest's write volume by roughly this factor — confirmed via a
+// synthetic 4,000-file, 300-checkpoint run: state_manifest was the
+// dominant driver of db.sqlite growing ~1.1MB/checkpoint. Deliberately
+// small enough that a restore/fork's reconstruction replay (bounded by
+// this same interval) stays fast even on a large project.
+const MANIFEST_KEYFRAME_INTERVAL = 20;
+// Safety snapshots (before restore/fork) and restore/fork states themselves
+// always keep a full manifest (see snapshotCurrentDisk, restoreState,
+// forkState) — they're comparatively rare, and keeping them fully
+// keyframed means anything forked or restored from is immediately fast to
+// reconstruct from. Only this regular, high-frequency checkpoint path is
+// sparsified.
+function shouldStoreFullManifest(ctx, parentStateId) {
+    let cur = parentStateId;
+    for (let i = 0; i < MANIFEST_KEYFRAME_INTERVAL; i++) {
+        if (!cur)
+            return false;
+        if (ctx.db.hasFullManifest(cur))
+            return false;
+        cur = ctx.db.getState(cur)?.parentStateId ?? undefined;
+    }
+    return true;
+}
+function requireSingleProjectId(ctx) {
+    const row = ctx.db.raw.prepare(`SELECT id FROM projects ORDER BY created_at ASC LIMIT 1`).get();
+    if (!row)
+        throw new Error("No project registered in this .whydid database.");
+    return row.id;
+}
+export async function initProject(ctx, projectName) {
+    const git = await detectGit(ctx.projectRoot);
+    const projectId = randomUUID();
+    ctx.db.insertProject({ id: projectId, name: projectName, rootPath: ctx.projectRoot, gitRoot: git.root });
+    const manifest = await buildManifest(ctx.projectRoot, ctx.ignoreRules);
+    const changes = diffManifests([], manifest);
+    storeManifestBlobs(ctx, manifest, changes);
+    const changesWithStats = withLineStats(ctx, changes);
+    const stateId = randomUUID();
+    ctx.db.insertState({
+        id: stateId, projectId, parentStateId: null, sessionId: null, turnId: null,
+        stateType: "initial", label: "Initial state", summary: null, reason: null,
+        decisionNotes: null, riskLevel: null, createdAt: new Date().toISOString(),
+        gitCommitSha: git.commitSha, workingTreeHash: manifestFingerprint(manifest),
+    });
+    ctx.db.insertFileChanges(stateId, changesWithStats);
+    ctx.db.insertStateManifest(stateId, manifest);
+    ctx.db.setHeadState(projectId, stateId);
+    ctx.db.insertEvent({ id: randomUUID(), projectId, type: "project_initialized", payloadJson: "{}" });
+    return { projectId, stateId };
+}
+export async function createCheckpoint(ctx, opts = {}) {
+    const projectId = opts.projectId ?? requireSingleProjectId(ctx);
+    const head = ctx.db.getHeadState(projectId);
+    if (!head)
+        throw new Error("No head state found — run initProject first.");
+    const previousManifest = ctx.db.getStateManifest(head.id);
+    const currentManifest = await buildManifest(ctx.projectRoot, ctx.ignoreRules);
+    const changes = diffManifests(previousManifest, currentManifest);
+    if (changes.length === 0) {
+        return { stateId: head.id, changed: false, fileChanges: [] };
+    }
+    // A checkpoint whose *only* changes are whydid's own auto-generated docs
+    // (CONTEXT.md, WHYDID_SUMMARY.md) is a checkpoint about nothing — those
+    // files only ever change as a side effect of a real checkpoint's own
+    // annotation, so treating that write as itself checkpoint-worthy is what
+    // causes a self-sustaining loop: checkpoint -> regenerate docs -> that
+    // regeneration looks like a new change -> checkpoint again, forever. A
+    // checkpoint that changes real files *and* incidentally touches these is
+    // unaffected — only an all-docs diff is skipped.
+    if (changes.every((c) => isAutoGeneratedDocFile(c.filePath))) {
+        return { stateId: head.id, changed: false, fileChanges: [] };
+    }
+    storeManifestBlobs(ctx, currentManifest, changes);
+    const changesWithStats = withLineStats(ctx, changes);
+    const git = await detectGit(ctx.projectRoot);
+    const stateId = randomUUID();
+    ctx.db.insertState({
+        id: stateId, projectId, parentStateId: head.id, sessionId: opts.sessionId ?? null, turnId: opts.turnId ?? null,
+        stateType: opts.stateType ?? "checkpoint", label: opts.label ?? null, summary: null,
+        reason: null, decisionNotes: null, riskLevel: null, createdAt: new Date().toISOString(),
+        gitCommitSha: git.commitSha, workingTreeHash: manifestFingerprint(currentManifest),
+    });
+    ctx.db.insertFileChanges(stateId, changesWithStats);
+    if (shouldStoreFullManifest(ctx, head.id)) {
+        ctx.db.insertStateManifest(stateId, currentManifest);
+    }
+    ctx.db.setHeadState(projectId, stateId);
+    ctx.db.insertEvent({ id: randomUUID(), projectId, type: "checkpoint_created", payloadJson: JSON.stringify({ stateId }) });
+    return { stateId, changed: true, fileChanges: changesWithStats };
+}
+function readdirSyncSafe(dir) {
+    return existsSync(dir) ? readdirSync(dir, { withFileTypes: true }) : [];
+}
+function collectFiles(dir, root, ignoreRules, out) {
+    for (const entry of readdirSyncSafe(dir)) {
+        const abs = join(dir, entry.name);
+        const rel = relative(root, abs).split("\\").join("/");
+        if (ignoreRules.isIgnored(entry.isDirectory() ? `${rel}/` : rel))
+            continue;
+        if (entry.isDirectory())
+            collectFiles(abs, root, ignoreRules, out);
+        else if (entry.isFile())
+            out.push(abs);
+    }
+}
+function applyManifestToDisk(ctx, targetManifest) {
+    const targetPaths = new Set(targetManifest.map((e) => e.filePath));
+    const currentAbsFiles = [];
+    collectFiles(ctx.projectRoot, ctx.projectRoot, ctx.ignoreRules, currentAbsFiles);
+    for (const abs of currentAbsFiles) {
+        const rel = relative(ctx.projectRoot, abs).split("\\").join("/");
+        if (!targetPaths.has(rel)) {
+            unlinkSync(abs);
+        }
+    }
+    for (const entry of targetManifest) {
+        const abs = join(ctx.projectRoot, entry.filePath);
+        const content = ctx.store.read(entry.contentHash);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+    }
+}
+async function snapshotCurrentDisk(ctx, projectId, parentStateId, stateType, label) {
+    const previousManifest = ctx.db.getStateManifest(parentStateId);
+    const currentManifest = await buildManifest(ctx.projectRoot, ctx.ignoreRules);
+    const changes = diffManifests(previousManifest, currentManifest);
+    storeManifestBlobs(ctx, currentManifest, changes);
+    const changesWithStats = withLineStats(ctx, changes);
+    const stateId = randomUUID();
+    const git = await detectGit(ctx.projectRoot);
+    ctx.db.insertState({
+        id: stateId, projectId, parentStateId, sessionId: null, turnId: null,
+        stateType, label, summary: null, reason: null, decisionNotes: null, riskLevel: null,
+        createdAt: new Date().toISOString(), gitCommitSha: git.commitSha,
+        workingTreeHash: manifestFingerprint(currentManifest),
+    });
+    ctx.db.insertFileChanges(stateId, changesWithStats);
+    ctx.db.insertStateManifest(stateId, currentManifest);
+    return stateId;
+}
+export async function restoreState(ctx, projectId, targetStateId) {
+    const head = ctx.db.getHeadState(projectId);
+    if (!head)
+        throw new Error("No head state found.");
+    const target = ctx.db.getState(targetStateId);
+    if (!target)
+        throw new Error(`Unknown state: ${targetStateId}`);
+    // Preserve whatever is currently on disk as a real state first.
+    const safetyStateId = await snapshotCurrentDisk(ctx, projectId, head.id, "checkpoint", "Before restore");
+    // Apply target manifest to the working tree.
+    const targetManifest = ctx.db.getStateManifest(targetStateId);
+    applyManifestToDisk(ctx, targetManifest);
+    // Record the restore as a new state, parented on the actual restore
+    // target — not the safety snapshot — so the state graph shows the real
+    // branch: the target now has two futures, the original one (preserved via
+    // the safety snapshot, itself parented on the pre-restore head) and this
+    // new restored one. This is what makes the timeline an actual graph
+    // instead of a straight line no matter how many times you restore.
+    const restoredStateId = randomUUID();
+    const git = await detectGit(ctx.projectRoot);
+    const changesFromSafety = withLineStats(ctx, diffManifests(ctx.db.getStateManifest(safetyStateId), targetManifest));
+    ctx.db.insertState({
+        id: restoredStateId, projectId, parentStateId: targetStateId, sessionId: null, turnId: null,
+        stateType: "restore", label: `Restored to ${target.label ?? target.id}`, summary: null,
+        reason: null, decisionNotes: null, riskLevel: null, createdAt: new Date().toISOString(),
+        gitCommitSha: git.commitSha, workingTreeHash: manifestFingerprint(targetManifest),
+    });
+    ctx.db.insertFileChanges(restoredStateId, changesFromSafety);
+    ctx.db.insertStateManifest(restoredStateId, targetManifest);
+    ctx.db.setHeadState(projectId, restoredStateId);
+    ctx.db.insertEvent({
+        id: randomUUID(), projectId, type: "state_restored",
+        payloadJson: JSON.stringify({ targetStateId, safetyStateId, restoredStateId }),
+    });
+    return { safetyStateId, restoredStateId };
+}
+/**
+ * Restores only specific files from a target state, leaving everything
+ * else on disk exactly as it is. For a file the target state didn't have
+ * (it was added after that point), "restoring" it means deleting it now —
+ * matching what a full restore would do to that same file.
+ *
+ * Unlike a full restore, the resulting state is parented on the safety
+ * snapshot, not the target — the disk state here is overwhelmingly a
+ * continuation of current work with a few files patched in from history,
+ * not a jump back to the target's own timeline. A full restore's "the
+ * target now has two futures" framing doesn't apply when only one file
+ * out of dozens came from that target.
+ */
+export async function restoreFiles(ctx, projectId, targetStateId, filePaths) {
+    const head = ctx.db.getHeadState(projectId);
+    if (!head)
+        throw new Error("No head state found.");
+    const target = ctx.db.getState(targetStateId);
+    if (!target)
+        throw new Error(`Unknown state: ${targetStateId}`);
+    if (filePaths.length === 0)
+        throw new Error("No files specified to restore.");
+    const safetyStateId = await snapshotCurrentDisk(ctx, projectId, head.id, "checkpoint", "Before selective restore");
+    const targetManifest = ctx.db.getStateManifest(targetStateId);
+    const targetByPath = new Map(targetManifest.map((e) => [e.filePath, e]));
+    const filesRestored = [];
+    for (const filePath of filePaths) {
+        const abs = join(ctx.projectRoot, filePath);
+        const entry = targetByPath.get(filePath);
+        if (entry) {
+            const content = ctx.store.read(entry.contentHash);
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, content);
+            filesRestored.push(filePath);
+        }
+        else if (existsSync(abs)) {
+            unlinkSync(abs);
+            filesRestored.push(filePath);
+        }
+    }
+    const safetyManifest = ctx.db.getStateManifest(safetyStateId);
+    const restoredSet = new Set(filesRestored);
+    const newManifest = safetyManifest.filter((e) => !restoredSet.has(e.filePath));
+    for (const filePath of filesRestored) {
+        const entry = targetByPath.get(filePath);
+        if (entry)
+            newManifest.push(entry);
+    }
+    const restoredStateId = randomUUID();
+    const git = await detectGit(ctx.projectRoot);
+    const changesFromSafety = withLineStats(ctx, diffManifests(safetyManifest, newManifest));
+    ctx.db.insertState({
+        id: restoredStateId, projectId, parentStateId: safetyStateId, sessionId: null, turnId: null,
+        stateType: "restore",
+        label: `Restored ${filesRestored.length} file${filesRestored.length === 1 ? "" : "s"} from ${target.label ?? target.id.slice(0, 8)}`,
+        summary: null, reason: null, decisionNotes: null, riskLevel: null, createdAt: new Date().toISOString(),
+        gitCommitSha: git.commitSha, workingTreeHash: manifestFingerprint(newManifest),
+    });
+    ctx.db.insertFileChanges(restoredStateId, changesFromSafety);
+    ctx.db.insertStateManifest(restoredStateId, newManifest);
+    ctx.db.setHeadState(projectId, restoredStateId);
+    ctx.db.insertEvent({
+        id: randomUUID(), projectId, type: "state_restored",
+        payloadJson: JSON.stringify({ targetStateId, safetyStateId, restoredStateId, filePaths: filesRestored, selective: true }),
+    });
+    return { safetyStateId, restoredStateId, filesRestored };
+}
+export async function forkState(ctx, projectId, sourceStateId, forkName) {
+    const head = ctx.db.getHeadState(projectId);
+    if (!head)
+        throw new Error("No head state found.");
+    const source = ctx.db.getState(sourceStateId);
+    if (!source)
+        throw new Error(`Unknown state: ${sourceStateId}`);
+    const safetyStateId = await snapshotCurrentDisk(ctx, projectId, head.id, "checkpoint", "Before fork");
+    const sourceManifest = ctx.db.getStateManifest(sourceStateId);
+    applyManifestToDisk(ctx, sourceManifest);
+    // Same reasoning as restoreState: parent the fork on its actual source
+    // state so it becomes a real sibling branch of the source's other
+    // children, not a dead-end hanging off the safety snapshot.
+    const forkStateId = randomUUID();
+    const git = await detectGit(ctx.projectRoot);
+    const changesFromSafety = withLineStats(ctx, diffManifests(ctx.db.getStateManifest(safetyStateId), sourceManifest));
+    ctx.db.insertState({
+        id: forkStateId, projectId, parentStateId: sourceStateId, sessionId: null, turnId: null,
+        stateType: "fork", label: `Fork: ${forkName}`, summary: null, reason: null,
+        decisionNotes: null, riskLevel: null, createdAt: new Date().toISOString(),
+        gitCommitSha: git.commitSha, workingTreeHash: manifestFingerprint(sourceManifest),
+    });
+    ctx.db.insertFileChanges(forkStateId, changesFromSafety);
+    ctx.db.insertStateManifest(forkStateId, sourceManifest);
+    ctx.db.setHeadState(projectId, forkStateId);
+    ctx.db.insertFork({ id: randomUUID(), projectId, sourceStateId, name: forkName });
+    ctx.db.insertEvent({
+        id: randomUUID(), projectId, type: "state_forked",
+        payloadJson: JSON.stringify({ sourceStateId, forkStateId, forkName }),
+    });
+    return { safetyStateId, forkStateId };
+}
+//# sourceMappingURL=engine.js.map

package/dist/core/export.js

@@ -0,0 +1,98 @@
+export function buildExportData(db, project) {
+    const states = db.listStates(project.id).map((s) => {
+        const annotation = db.getAnnotation(s.id);
+        const changes = db.getFileChanges(s.id);
+        return {
+            id: s.id,
+            label: s.label,
+            stateType: s.stateType,
+            createdAt: s.createdAt,
+            riskLevel: annotation?.riskLevel ?? s.riskLevel,
+            summary: annotation?.status === "generated" ? annotation.summary : s.summary,
+            reason: annotation?.status === "generated" ? annotation.reason : s.reason,
+            decisions: annotation?.status === "generated" ? annotation.decisions : [],
+            annotationStatus: annotation?.status ?? null,
+            fileChanges: changes.map((c) => ({
+                filePath: c.filePath, changeType: c.changeType, linesAdded: c.linesAdded, linesRemoved: c.linesRemoved,
+            })),
+        };
+    });
+    return { project: { name: project.name, exportedAt: new Date().toISOString() }, states };
+}
+export function exportAsJson(data) {
+    return JSON.stringify(data, null, 2);
+}
+export function exportAsMarkdown(data) {
+    const lines = [`# ${data.project.name} — whydid export`, "", `Exported: ${data.project.exportedAt}`, ""];
+    for (const s of data.states) {
+        lines.push(`## ${s.label ?? s.stateType} (#${s.id.slice(0, 8)})`, "");
+        lines.push(`- Type: ${s.stateType}`, `- Created: ${s.createdAt}`);
+        if (s.riskLevel)
+            lines.push(`- Risk: ${s.riskLevel}`);
+        lines.push("");
+        if (s.reason)
+            lines.push(`**Why:** ${s.reason}`, "");
+        if (s.decisions.length > 0) {
+            lines.push("**Decisions:**");
+            for (const d of s.decisions)
+                lines.push(`- ${d}`);
+            lines.push("");
+        }
+        lines.push(`**Files changed (${s.fileChanges.length}):**`);
+        for (const c of s.fileChanges)
+            lines.push(`- \`${c.filePath}\` (${c.changeType}, +${c.linesAdded}/-${c.linesRemoved})`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+export function exportAsHtml(data) {
+    const stateBlocks = data.states
+        .map((s) => {
+        const decisions = s.decisions.map((d) => `<li>${escapeHtml(d)}</li>`).join("");
+        const files = s.fileChanges
+            .map((c) => `<li><code>${escapeHtml(c.filePath)}</code> <span class="change-type">${c.changeType}</span> <span class="stats">+${c.linesAdded}/-${c.linesRemoved}</span></li>`)
+            .join("");
+        return `
+        <section class="state">
+          <h2>${escapeHtml(s.label ?? s.stateType)} <span class="state-id">#${s.id.slice(0, 8)}</span></h2>
+          <p class="meta">${escapeHtml(s.stateType)} · ${escapeHtml(s.createdAt)}${s.riskLevel ? ` · <span class="risk risk-${s.riskLevel}">${s.riskLevel} risk</span>` : ""}</p>
+          ${s.reason ? `<p class="why"><strong>Why:</strong> ${escapeHtml(s.reason)}</p>` : ""}
+          ${decisions ? `<p><strong>Decisions:</strong></p><ul>${decisions}</ul>` : ""}
+          <p><strong>Files changed (${s.fileChanges.length}):</strong></p>
+          <ul class="files">${files}</ul>
+        </section>`;
+    })
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>${escapeHtml(data.project.name)} — whydid export</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 760px; margin: 0 auto; padding: 2rem 1.5rem; color: #1a1a1a; background: #fff; }
+  h1 { font-size: 1.6rem; }
+  h2 { font-size: 1.15rem; margin-bottom: 0.25rem; }
+  .state-id { color: #888; font-weight: normal; font-size: 0.85em; }
+  .meta { color: #666; font-size: 0.9em; margin-top: 0; }
+  .why { background: #f6f6f6; padding: 0.75rem 1rem; border-radius: 6px; }
+  .risk { padding: 0.1rem 0.5rem; border-radius: 4px; font-size: 0.8em; }
+  .risk-low { background: #dcfce7; color: #166534; }
+  .risk-medium { background: #fef3c7; color: #92400e; }
+  .risk-high { background: #fee2e2; color: #991b1b; }
+  ul.files { font-size: 0.9em; }
+  .change-type { color: #888; text-transform: uppercase; font-size: 0.75em; }
+  .stats { color: #888; font-size: 0.85em; }
+  section.state { border-top: 1px solid #e5e5e5; padding: 1.5rem 0; }
+</style>
+</head>
+<body>
+  <h1>${escapeHtml(data.project.name)}</h1>
+  <p class="meta">whydid export — ${escapeHtml(data.project.exportedAt)}</p>
+  ${stateBlocks}
+</body>
+</html>`;
+}
+//# sourceMappingURL=export.js.map

package/dist/core/file-history.js

@@ -0,0 +1,31 @@
+/**
+ * Every state that touched a given file, oldest first, across the whole
+ * project history (not just one branch) — so a later change that lands on
+ * top of an earlier one in the same file is visible, even if the user asks
+ * about it long after both happened.
+ */
+export function getFileHistory(db, projectId, filePath) {
+    const states = db.listStates(projectId).slice().reverse(); // oldest first
+    const entries = [];
+    for (const state of states) {
+        const change = db.getFileChanges(state.id).find((c) => c.filePath === filePath);
+        if (!change)
+            continue;
+        const annotation = db.getAnnotation(state.id);
+        const turn = state.turnId ? db.getTurn(state.turnId) : undefined;
+        entries.push({
+            stateId: state.id,
+            stateLabel: state.label,
+            stateType: state.stateType,
+            createdAt: state.createdAt,
+            changeType: change.changeType,
+            turnPrompt: turn?.prompt ?? null,
+            annotationSummary: annotation?.status === "generated" ? annotation.summary : null,
+            annotationReason: annotation?.status === "generated" ? annotation.reason : null,
+            annotationStatus: annotation?.status ?? null,
+            buildsOnPriorChange: entries.length > 0 && change.changeType !== "added",
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=file-history.js.map

package/dist/core/manifest.js

@@ -0,0 +1,102 @@
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { hashContent } from "../objects/store.js";
+const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024;
+function walk(dir, root, ignoreRules, out) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const abs = join(dir, entry.name);
+        const rel = relative(root, abs).split("\\").join("/");
+        if (ignoreRules.isIgnored(entry.isDirectory() ? `${rel}/` : rel))
+            continue;
+        if (entry.isDirectory()) {
+            walk(abs, root, ignoreRules, out);
+        }
+        else if (entry.isFile()) {
+            out.push(abs);
+        }
+    }
+}
+// Guard against the classic "racy stat cache" bug (the same one git works
+// around): if a file's mtime is very close to "now", a filesystem with
+// coarse (e.g. 1s) mtime resolution could report the same mtime for two
+// different writes made in quick succession. Refuse to cache — and refuse
+// to trust a cached entry for — any file whose mtime falls within this
+// window of the current scan, so a same-tick rewrite always gets re-hashed
+// instead of silently reusing a stale hash.
+const RACY_WINDOW_MS = 1100;
+// Every checkpoint used to re-read and re-hash every tracked file's full
+// content, even when nothing about the file changed. On a project with
+// tens of thousands of tracked files that made every checkpoint cost
+// seconds regardless of how small the actual edit was. Content hashes are
+// immutable for a given (path, mtime, size) triple in real editing
+// workflows, so this cache lets a file skip its content read+hash
+// entirely when neither its mtime nor its size moved since the last scan
+// of this project root — the returned manifest is byte-identical either
+// way, only the cost of producing it changes. The cache is in-memory only
+// (keyed by project root) and rebuilds itself on first scan after a
+// process restart, so there is no persistence/correctness surface to get
+// wrong.
+const statCache = new Map();
+export async function buildManifest(projectRoot, ignoreRules, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE) {
+    const absFiles = [];
+    walk(projectRoot, projectRoot, ignoreRules, absFiles);
+    let cache = statCache.get(projectRoot);
+    if (!cache) {
+        cache = new Map();
+        statCache.set(projectRoot, cache);
+    }
+    const scanStartMs = Date.now();
+    const entries = [];
+    const seenPaths = new Set();
+    for (const abs of absFiles) {
+        const stat = statSync(abs);
+        if (stat.size > maxFileSizeBytes)
+            continue;
+        const relPath = relative(projectRoot, abs).split("\\").join("/");
+        seenPaths.add(relPath);
+        const isRacy = scanStartMs - stat.mtimeMs < RACY_WINDOW_MS;
+        const cached = cache.get(relPath);
+        let contentHash;
+        if (!isRacy && cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+            contentHash = cached.contentHash;
+        }
+        else {
+            const content = readFileSync(abs);
+            contentHash = hashContent(content);
+            if (!isRacy)
+                cache.set(relPath, { mtimeMs: stat.mtimeMs, size: stat.size, contentHash });
+            else
+                cache.delete(relPath);
+        }
+        entries.push({ filePath: relPath, contentHash, sizeBytes: stat.size });
+    }
+    // Drop cache entries for files that no longer exist so the cache doesn't
+    // grow unbounded across a project's lifetime (renames, deletes, etc.).
+    for (const cachedPath of cache.keys()) {
+        if (!seenPaths.has(cachedPath))
+            cache.delete(cachedPath);
+    }
+    entries.sort((a, b) => a.filePath.localeCompare(b.filePath));
+    return entries;
+}
+export function diffManifests(before, after) {
+    const beforeMap = new Map(before.map((e) => [e.filePath, e]));
+    const afterMap = new Map(after.map((e) => [e.filePath, e]));
+    const changes = [];
+    for (const [filePath, afterEntry] of afterMap) {
+        const beforeEntry = beforeMap.get(filePath);
+        if (!beforeEntry) {
+            changes.push({ filePath, changeType: "added", beforeHash: null, afterHash: afterEntry.contentHash, linesAdded: 0, linesRemoved: 0 });
+        }
+        else if (beforeEntry.contentHash !== afterEntry.contentHash) {
+            changes.push({ filePath, changeType: "modified", beforeHash: beforeEntry.contentHash, afterHash: afterEntry.contentHash, linesAdded: 0, linesRemoved: 0 });
+        }
+    }
+    for (const [filePath, beforeEntry] of beforeMap) {
+        if (!afterMap.has(filePath)) {
+            changes.push({ filePath, changeType: "deleted", beforeHash: beforeEntry.contentHash, afterHash: null, linesAdded: 0, linesRemoved: 0 });
+        }
+    }
+    return changes;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/core/recap.js

@@ -0,0 +1,49 @@
+const SKIP_SEGMENTS = new Set(["src", "lib", "app", "apps", "packages", "test", "tests", "__tests__"]);
+function deriveArea(filePath) {
+    const parts = filePath.split("/");
+    const directories = parts.slice(0, -1).filter((p) => !SKIP_SEGMENTS.has(p.toLowerCase()));
+    if (directories.length === 0)
+        return null;
+    const raw = directories[0];
+    return raw.charAt(0).toUpperCase() + raw.slice(1);
+}
+export function computeRecap(db, projectId, sinceIso) {
+    const states = db.listStates(projectId).filter((s) => s.createdAt >= sinceIso && s.stateType !== "initial");
+    const fileChurn = new Map();
+    const areaCounts = new Map();
+    const riskyAreas = new Set();
+    let unexplainedChanges = 0;
+    for (const state of states) {
+        const changes = db.getFileChanges(state.id);
+        for (const change of changes) {
+            fileChurn.set(change.filePath, (fileChurn.get(change.filePath) ?? 0) + 1);
+            const area = deriveArea(change.filePath);
+            if (area)
+                areaCounts.set(area, (areaCounts.get(area) ?? 0) + 1);
+        }
+        const annotation = db.getAnnotation(state.id);
+        if (!annotation || annotation.status !== "generated") {
+            unexplainedChanges += 1;
+        }
+        else if (annotation.riskLevel === "medium" || annotation.riskLevel === "high") {
+            riskyAreas.add(annotation.summary || state.label || `State #${state.id.slice(0, 8)}`);
+        }
+    }
+    const highChurnFiles = [...fileChurn.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([filePath, changes]) => ({ filePath, changes }));
+    const mainAreas = [...areaCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([area]) => area);
+    return {
+        totalChanges: states.length,
+        mainAreas,
+        highChurnFiles,
+        riskyAreas: [...riskyAreas].slice(0, 5),
+        unexplainedChanges,
+        latestTestRun: db.getLatestTestRunForProject(projectId) ?? null,
+    };
+}
+//# sourceMappingURL=recap.js.map

package/dist/core/test-runner.js

@@ -0,0 +1,23 @@
+import { randomUUID } from "node:crypto";
+import { exec } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+export async function runTestCommand(ctx, stateId, command, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const logsDir = join(ctx.whydidDir, "logs");
+    mkdirSync(logsDir, { recursive: true });
+    const outputPath = join(logsDir, `test-${stateId}.log`);
+    const start = Date.now();
+    const { exitCode, output } = await new Promise((resolve) => {
+        exec(command, { cwd: ctx.projectRoot, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({ exitCode: error ? (typeof error.code === "number" ? error.code : 1) : 0, output: `${stdout}\n${stderr}` });
+        });
+    });
+    const durationMs = Date.now() - start;
+    writeFileSync(outputPath, output);
+    const status = exitCode === 0 ? "passed" : "failed";
+    const id = randomUUID();
+    ctx.db.insertTestRun({ id, stateId, command, status, exitCode, durationMs, outputPath });
+    return { id, status, exitCode, durationMs, outputPath };
+}
+//# sourceMappingURL=test-runner.js.map