whydid 1.0.0

package/dist/cli/commands/status.js

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import { requireEngineContext } from "../context.js";
+import { loadConfig } from "../../shared/config.js";
+import { printAiBudgetWarning } from "../ai-budget-warning.js";
+export function createStatusCommand() {
+    return new Command("status").description("Show current whydid status").action(() => {
+        const projectRoot = process.cwd();
+        const ctx = requireEngineContext(projectRoot);
+        const projectRow = ctx.db.raw.prepare(`SELECT * FROM projects ORDER BY created_at ASC LIMIT 1`).get();
+        if (!projectRow) {
+            console.log("whydid is not initialized here. Run `whydid init` first.");
+            ctx.db.close();
+            return;
+        }
+        const head = ctx.db.getHeadState(projectRow.id);
+        const changes = head ? ctx.db.getFileChanges(head.id) : [];
+        console.log(`Project: ${projectRow.name}`);
+        console.log(`Current state: #${head?.id.slice(0, 8)} (${head?.stateType})`);
+        console.log(`Last checkpoint: ${head?.createdAt}`);
+        console.log(`Files changed in last state: ${changes.length}`);
+        const config = loadConfig(ctx.whydidDir);
+        printAiBudgetWarning(ctx, projectRow.id, config);
+        ctx.db.close();
+    });
+}
+//# sourceMappingURL=status.js.map

package/dist/cli/commands/test.js

@@ -0,0 +1,33 @@
+import { Command } from "commander";
+import { requireEngineContext, requireProjectId } from "../context.js";
+import { loadConfig } from "../../shared/config.js";
+import { runTestCommand } from "../../core/test-runner.js";
+export function createTestCommand() {
+    return new Command("test").description("Run the project's configured test command").action(async () => {
+        const ctx = requireEngineContext(process.cwd());
+        const projectId = requireProjectId(ctx);
+        const config = loadConfig(ctx.whydidDir);
+        if (!config.test) {
+            console.log('No test command configured. Add this to .whydid/config.json:\n  "test": { "command": "npm test", "mode": "manual" }');
+            ctx.db.close();
+            return;
+        }
+        const head = ctx.db.getHeadState(projectId);
+        if (!head) {
+            console.log("No current state to attach test results to. Run `whydid checkpoint` first.");
+            ctx.db.close();
+            return;
+        }
+        console.log(`Running: ${config.test.command}`);
+        const result = await runTestCommand(ctx, head.id, config.test.command);
+        if (result.status === "passed") {
+            console.log(`✓ Tests passed (${result.durationMs}ms)`);
+        }
+        else {
+            console.log(`✗ Tests failed (exit ${result.exitCode}, ${result.durationMs}ms)`);
+            console.log(`See ${result.outputPath} for output.`);
+        }
+        ctx.db.close();
+    });
+}
+//# sourceMappingURL=test.js.map

package/dist/cli/commands/timeline.js

@@ -0,0 +1,23 @@
+import { Command } from "commander";
+import { requireEngineContext } from "../context.js";
+export function createTimelineCommand() {
+    return new Command("timeline").description("Show the project state timeline").action(() => {
+        const ctx = requireEngineContext(process.cwd());
+        const projectRow = ctx.db.raw.prepare(`SELECT * FROM projects ORDER BY created_at ASC LIMIT 1`).get();
+        if (!projectRow) {
+            console.log("whydid is not initialized here. Run `whydid init` first.");
+            ctx.db.close();
+            return;
+        }
+        const states = ctx.db.listStates(projectRow.id);
+        for (const s of states) {
+            const changes = ctx.db.getFileChanges(s.id);
+            const added = changes.reduce((sum, c) => sum + c.linesAdded, 0);
+            const removed = changes.reduce((sum, c) => sum + c.linesRemoved, 0);
+            console.log(`● ${s.createdAt}  ${s.label ?? s.stateType}`);
+            console.log(`  ${changes.length} files changed, +${added} / -${removed}`);
+        }
+        ctx.db.close();
+    });
+}
+//# sourceMappingURL=timeline.js.map

package/dist/cli/commands/why.js

@@ -0,0 +1,71 @@
+import { Command } from "commander";
+import { requireEngineContext } from "../context.js";
+import { computeFileDiff } from "../../core/diff.js";
+import { getFileHistory } from "../../core/file-history.js";
+import { loadConfig } from "../../shared/config.js";
+import { createLLMProvider } from "../../llm/factory.js";
+import { FileSecretStore } from "../../licensing/secret-store.js";
+export function createWhyCommand() {
+    return new Command("why")
+        .description("Explain a file's full change history — who changed it, why, and what built on top of what")
+        .argument("<file>", "file path to explain")
+        .option("--ask [question]", "ask your configured LLM to synthesize a fresh explanation")
+        .action(async (file, opts) => {
+        const ctx = requireEngineContext(process.cwd());
+        const projectRow = ctx.db.raw.prepare(`SELECT * FROM projects ORDER BY created_at ASC LIMIT 1`).get();
+        if (!projectRow) {
+            console.log("whydid is not initialized here. Run `whydid init` first.");
+            ctx.db.close();
+            return;
+        }
+        const history = getFileHistory(ctx.db, projectRow.id, file);
+        if (history.length === 0) {
+            console.log(`No recorded state introduces changes to ${file}.`);
+            ctx.db.close();
+            return;
+        }
+        console.log(`${file}\n`);
+        console.log(`History (${history.length} change${history.length === 1 ? "" : "s"}):\n`);
+        history.forEach((entry, i) => {
+            const when = new Date(entry.createdAt).toLocaleString();
+            console.log(`${i + 1}. State #${entry.stateId.slice(0, 8)} — ${entry.stateLabel ?? entry.stateType} (${when})`);
+            if (entry.turnPrompt) {
+                console.log(`   Prompt: "${entry.turnPrompt}"`);
+            }
+            if (entry.annotationReason) {
+                console.log(`   Why: ${entry.annotationReason}`);
+            }
+            else if (!entry.turnPrompt) {
+                console.log(`   Why: unavailable — inferred from project changes only.`);
+            }
+            if (entry.buildsOnPriorChange) {
+                console.log(`   ⚠ Builds on top of the previous entry's change to this file — reverting that one may affect this one.`);
+            }
+            console.log("");
+        });
+        const latest = history[history.length - 1];
+        const latestAnnotation = ctx.db.getAnnotation(latest.stateId);
+        if (opts.ask !== undefined) {
+            const question = typeof opts.ask === "string" ? opts.ask : `Why did ${file} change in this state?`;
+            const config = loadConfig(ctx.whydidDir);
+            const provider = await createLLMProvider(config.ai, new FileSecretStore(ctx.whydidDir));
+            if (provider.id === "noop") {
+                console.log("Ask AI: no LLM provider configured (set ai.provider in .whydid/config.json and the matching *_API_KEY env var).");
+                ctx.db.close();
+                return;
+            }
+            const change = ctx.db.getFileChanges(latest.stateId).find((c) => c.filePath === file);
+            const diffText = change ? computeFileDiff(ctx.store, change).unified : "";
+            const context = `File: ${file}\nFull history:\n${history.map((h, i) => `${i + 1}. ${h.turnPrompt ?? h.annotationSummary ?? h.stateLabel ?? h.stateType}`).join("\n")}\nLatest stored summary: ${latestAnnotation?.summary ?? "(none)"}\nLatest diff:\n${diffText}`;
+            try {
+                const answer = await provider.answerQuestion(question, context);
+                console.log(`Ask AI (${question}):\n${answer}\n`);
+            }
+            catch (err) {
+                console.log(`Ask AI failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        ctx.db.close();
+    });
+}
+//# sourceMappingURL=why.js.map

package/dist/cli/context.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { WhydidDatabase } from "../db/database.js";
+import { ObjectStore } from "../objects/store.js";
+import { IgnoreRules } from "../watcher/ignore-rules.js";
+import { loadConfig } from "../shared/config.js";
+export function whydidDirFor(projectRoot) {
+    return join(projectRoot, ".whydid");
+}
+export function buildEngineContext(projectRoot) {
+    const whydidDir = whydidDirFor(projectRoot);
+    mkdirSync(whydidDir, { recursive: true });
+    mkdirSync(join(whydidDir, "objects"), { recursive: true });
+    mkdirSync(join(whydidDir, "logs"), { recursive: true });
+    const config = loadConfig(whydidDir);
+    return {
+        projectRoot,
+        whydidDir,
+        db: new WhydidDatabase(join(whydidDir, "db.sqlite")),
+        store: new ObjectStore(join(whydidDir, "objects")),
+        ignoreRules: new IgnoreRules(projectRoot, config.ignoredPaths),
+    };
+}
+export function defaultProjectName(projectRoot) {
+    return basename(projectRoot);
+}
+export function whydidDirExists(projectRoot) {
+    return existsSync(whydidDirFor(projectRoot));
+}
+/**
+ * Like buildEngineContext, but for commands that only make sense on an
+ * already-initialized project: fails fast with a friendly message instead
+ * of silently creating a fresh, empty .whydid/ as a side effect of a
+ * read-only command like `status` or `timeline`.
+ */
+export function requireEngineContext(projectRoot) {
+    if (!whydidDirExists(projectRoot)) {
+        throw new Error("whydid is not initialized here. Run `whydid init` first.");
+    }
+    return buildEngineContext(projectRoot);
+}
+export function requireProjectId(ctx) {
+    const row = ctx.db.raw.prepare(`SELECT id FROM projects ORDER BY created_at ASC LIMIT 1`).get();
+    if (!row)
+        throw new Error("whydid is not initialized here. Run `whydid init` first.");
+    return row.id;
+}
+//# sourceMappingURL=context.js.map

package/dist/cli/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkSqliteSupport, printSqliteSupportError } from "./preflight.js";
+// dist/cli/index.js -> package root is two levels up (dist/cli -> dist -> root).
+// npm always includes package.json in a published tarball regardless of the
+// "files" allowlist, so this path is reliable in both a source checkout and
+// a real installed package.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..", "..");
+const PACKAGE_VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8")).version;
+// Loading every command module (and their transitive deps — LLM providers,
+// the state engine, chokidar, etc.) on every single invocation made simple
+// commands like `whydid status` noticeably slower to start than they need
+// to be, and was the real cause behind `whydid daemon start`'s background
+// process occasionally missing its own startup deadline. Only import the
+// module the invoked command actually needs; fall back to loading
+// everything only for --help / no-args / an unrecognized command, since
+// those need the full listing anyway and aren't a hot path.
+const loaders = {
+    init: async () => (await import("./commands/init.js")).createInitCommand(),
+    "agent-event": async () => (await import("./commands/agent-event.js")).createAgentEventCommand(),
+    status: async () => (await import("./commands/status.js")).createStatusCommand(),
+    checkpoint: async () => (await import("./commands/checkpoint.js")).createCheckpointCommand(),
+    timeline: async () => (await import("./commands/timeline.js")).createTimelineCommand(),
+    why: async () => (await import("./commands/why.js")).createWhyCommand(),
+    restore: async () => (await import("./commands/restore-fork.js")).createRestoreCommand(),
+    fork: async () => (await import("./commands/restore-fork.js")).createForkCommand(),
+    milestone: async () => (await import("./commands/milestone.js")).createMilestoneCommand(),
+    key: async () => (await import("./commands/key.js")).createKeyCommand(),
+    daemon: async () => (await import("./commands/daemon.js")).createDaemonCommand(),
+    test: async () => (await import("./commands/test.js")).createTestCommand(),
+    recap: async () => (await import("./commands/recap.js")).createRecapCommand(),
+    context: async () => (await import("./commands/context.js")).createContextCommand(),
+    export: async () => (await import("./commands/export.js")).createExportCommand(),
+    prompt: async () => (await import("./commands/prompt.js")).createPromptCommand(),
+    login: async () => (await import("./commands/license.js")).createLoginCommand(),
+    logout: async () => (await import("./commands/license.js")).createLogoutCommand(),
+    license: async () => (await import("./commands/license.js")).createLicenseCommand(),
+};
+async function main() {
+    const support = await checkSqliteSupport();
+    if (!support.ok) {
+        printSqliteSupportError(support);
+        process.exit(1);
+    }
+    const { Command } = await import("commander");
+    const program = new Command("whydid").description("A local time machine for AI-assisted coding").version(PACKAGE_VERSION, "-V, --version");
+    const rawArg = process.argv[2];
+    const commandArg = rawArg === "doctor" ? "recap" : rawArg; // doctor is an alias registered on the recap Command itself
+    const { commandNeedsLicense, printLicenseRequiredMessage } = await import("./license-gate.js");
+    if (commandNeedsLicense(commandArg)) {
+        const { createDefaultLicenseManager } = await import("../licensing/config.js");
+        const manager = await createDefaultLicenseManager();
+        await manager.refreshIfNeeded().catch(() => undefined); // best-effort, offline-tolerant
+        if (!manager.hasFeature("core")) {
+            console.error(printLicenseRequiredMessage());
+            process.exit(1);
+        }
+    }
+    const loader = commandArg ? loaders[commandArg] : undefined;
+    if (loader) {
+        program.addCommand(await loader());
+    }
+    else {
+        for (const load of Object.values(loaders)) {
+            program.addCommand(await load());
+        }
+    }
+    await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/license-gate.js

@@ -0,0 +1,26 @@
+import { PRICING_URL } from "../licensing/config.js";
+/** Never gated — a customer must be able to authenticate/check status/see this message without already having a valid license. */
+const EXEMPT_COMMANDS = new Set(["login", "logout", "license"]);
+export function commandNeedsLicense(commandArg) {
+    if (!commandArg)
+        return false; // no args -> shows help
+    if (commandArg === "--help" || commandArg === "-h")
+        return false;
+    if (commandArg === "--version" || commandArg === "-V")
+        return false;
+    return !EXEMPT_COMMANDS.has(commandArg);
+}
+export function printLicenseRequiredMessage() {
+    return [
+        "This product requires a license.",
+        "",
+        "Get a lifetime license:",
+        PRICING_URL,
+        "",
+        "Already purchased?",
+        "Run:",
+        "",
+        "  whydid login <licenseKey>",
+    ].join("\n");
+}
+//# sourceMappingURL=license-gate.js.map

package/dist/cli/preflight.js

@@ -0,0 +1,28 @@
+import { createRequire } from "node:module";
+const nodeRequire = createRequire(import.meta.url);
+export async function checkSqliteSupport() {
+    const nodeVersion = process.versions.node;
+    const execPath = process.execPath;
+    try {
+        nodeRequire("node:sqlite");
+        return { ok: true, nodeVersion, execPath };
+    }
+    catch {
+        return { ok: false, nodeVersion, execPath };
+    }
+}
+export function printSqliteSupportError(result) {
+    console.error(`whydid requires a Node.js build with the built-in "node:sqlite" module (Node 22.5+ with`);
+    console.error(`--experimental-sqlite, or Node 23.4+ / 24+ unflagged) — the recommended minimum is Node 24.`);
+    console.error("");
+    console.error(`Detected Node ${result.nodeVersion} at:`);
+    console.error(`  ${result.execPath}`);
+    console.error("");
+    console.error("If you have a newer Node install too, check for it and either call it directly or fix your PATH order:");
+    console.error("  which -a node");
+    console.error("  node --version");
+    console.error("");
+    console.error("With nvm:  nvm install 24 && nvm use 24");
+    console.error("With Homebrew (macOS):  brew install node@24 && brew link --overwrite node@24");
+}
+//# sourceMappingURL=preflight.js.map

package/dist/core/agent-context.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+const START = "<!-- whydid:context:start -->";
+const END = "<!-- whydid:context:end -->";
+const guidance = [
+    START,
+    "## whydid project context",
+    "",
+    "Before starting a task, read `WHYDID_SUMMARY.md` when it exists. Before changing files in a directory, read that directory's `CONTEXT.md` when it exists. These files record recent decisions, reasons, and the prompts behind prior changes; use them alongside the code and current task.",
+    "",
+    "After meaningful work, leave generated whydid context files intact so the next coding session can continue from the project's recorded decisions.",
+    END,
+].join("\n");
+const instructionFiles = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursor/rules/whydid-context.mdc",
+];
+function installInstructionFile(projectRoot, relativePath) {
+    const path = join(projectRoot, relativePath);
+    const isCursorRule = relativePath.endsWith(".mdc");
+    const defaultContent = isCursorRule
+        ? `---\ndescription: Read whydid project history before coding\nalwaysApply: true\n---\n\n${guidance}\n`
+        : `${guidance}\n`;
+    if (!existsSync(path)) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, defaultContent, "utf-8");
+        return true;
+    }
+    const current = readFileSync(path, "utf-8");
+    const start = current.indexOf(START);
+    const end = current.indexOf(END);
+    if (start !== -1 && end > start) {
+        const updated = `${current.slice(0, start)}${guidance}${current.slice(end + END.length)}`;
+        if (updated !== current)
+            writeFileSync(path, updated, "utf-8");
+        return updated !== current;
+    }
+    const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+    writeFileSync(path, `${current}${separator}\n${guidance}\n`, "utf-8");
+    return true;
+}
+export function installAgentContextInstructions(projectRoot) {
+    return instructionFiles.filter((relativePath) => installInstructionFile(projectRoot, relativePath));
+}
+//# sourceMappingURL=agent-context.js.map

package/dist/core/agent-hooks.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function installJsonHooks(projectRoot, relativePath, events) {
+    const path = join(projectRoot, relativePath);
+    let config = {};
+    if (existsSync(path)) {
+        try {
+            config = JSON.parse(readFileSync(path, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+        if (!config || typeof config !== "object" || Array.isArray(config))
+            return null;
+    }
+    if (config.hooks != null && (typeof config.hooks !== "object" || Array.isArray(config.hooks)))
+        return null;
+    if (!config.hooks)
+        config.hooks = {};
+    for (const [eventName, definition] of Object.entries(events)) {
+        if (config.hooks[eventName] != null && !Array.isArray(config.hooks[eventName]))
+            return null;
+        const entries = Array.isArray(config.hooks[eventName]) ? config.hooks[eventName] : [];
+        if (relativePath.startsWith(".codex/")) {
+            const command = definition.command;
+            const existing = entries.find((entry) => Array.isArray(entry?.hooks) && entry.hooks.some((hook) => hook?.command === command));
+            if (!existing)
+                entries.push({ hooks: [{ type: "command", command }] });
+        }
+        else {
+            const command = definition.command;
+            if (!entries.some((entry) => entry?.command === command))
+                entries.push({ command });
+        }
+        config.hooks[eventName] = entries;
+    }
+    if (relativePath.startsWith(".codex/"))
+        config.description ??= "whydid local session capture";
+    else
+        config.version ??= 1;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    return relativePath;
+}
+export function installAgentHookConfigs(projectRoot) {
+    const codexEvents = {
+        SessionStart: { command: "whydid agent-event codex" },
+        UserPromptSubmit: { command: "whydid agent-event codex" },
+        Stop: { command: "whydid agent-event codex" },
+        SessionEnd: { command: "whydid agent-event codex" },
+    };
+    const cursorEvents = {
+        beforeSubmitPrompt: { command: "whydid agent-event cursor" },
+        afterAgentResponse: { command: "whydid agent-event cursor" },
+        stop: { command: "whydid agent-event cursor" },
+    };
+    const installed = [];
+    const skipped = [];
+    for (const [path, events] of [[".codex/hooks.json", codexEvents], [".cursor/hooks.json", cursorEvents]]) {
+        const result = installJsonHooks(projectRoot, path, events);
+        if (result)
+            installed.push(result);
+        else
+            skipped.push(path);
+    }
+    return { installed, skipped };
+}
+//# sourceMappingURL=agent-hooks.js.map

package/dist/core/ai-budget.js

@@ -0,0 +1,27 @@
+import { estimateCostUsd, computeBudgetStatus } from "../llm/pricing.js";
+import { loadCommunityPricingCache } from "../llm/community-pricing.js";
+export function currentUtcMonthStartIso() {
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString();
+}
+/**
+ * Single source of truth for "where does this project stand against its
+ * monthly AI budget right now" — shared by the dashboard's GET /api/ai-budget
+ * and the CLI's checkpoint/status warnings, so the two can never disagree.
+ */
+export function computeCurrentAiBudget(ctx, projectId, config) {
+    const monthStart = currentUtcMonthStartIso();
+    const lookup = { overrides: config.pricingOverrides, community: loadCommunityPricingCache(ctx.whydidDir)?.models };
+    const byModel = ctx.db.getTokenUsageByModelSince(projectId, monthStart).map((m) => ({
+        ...m,
+        estimatedCostUsd: estimateCostUsd(m.model, m.inputTokens, m.outputTokens, lookup),
+    }));
+    const pricedModels = byModel.filter((m) => m.estimatedCostUsd !== null);
+    const hasUnpricedUsage = byModel.some((m) => m.estimatedCostUsd === null);
+    // Zero calls this month is known spend ($0), not "unknown" — only usage
+    // that exists but is entirely on unpriced models is genuinely unknown.
+    const spentUsd = byModel.length === 0 ? 0 : pricedModels.length > 0 ? pricedModels.reduce((sum, m) => sum + (m.estimatedCostUsd ?? 0), 0) : null;
+    const budget = computeBudgetStatus(config.aiBudget.monthlyLimitUsd, config.aiBudget.alertThresholdPercent, spentUsd);
+    return { ...budget, hasUnpricedUsage, monthStart };
+}
+//# sourceMappingURL=ai-budget.js.map

package/dist/core/chat-retrieval.js

@@ -0,0 +1,36 @@
+const RECENT_LIMIT = 20;
+const SEARCH_LIMIT = 15;
+/**
+ * Grounding context for a chat question: the most recent checkpoints (so
+ * "what did I do today/recently" works without the question needing to
+ * name anything) plus FTS5 keyword matches against the question's own text
+ * (so "why did we choose Stripe" reaches back further than the recent
+ * window). Deduped and hydrated into real content; states without a
+ * generated annotation are skipped — there's nothing useful to ground on.
+ */
+export function retrieveContextForQuestion(ctx, projectId, question) {
+    const recentStateIds = ctx.db.listStates(projectId, { limit: RECENT_LIMIT }).map((s) => s.id);
+    const searchStateIds = ctx.db.searchAnnotations(projectId, question, SEARCH_LIMIT);
+    const stateIds = [...new Set([...recentStateIds, ...searchStateIds])];
+    const entries = [];
+    for (const stateId of stateIds) {
+        const state = ctx.db.getState(stateId);
+        const annotation = ctx.db.getAnnotation(stateId);
+        if (!state || !annotation || annotation.status !== "generated" || !annotation.summary || !annotation.reason)
+            continue;
+        const changes = ctx.db.getFileChanges(stateId);
+        const prompt = state.turnId ? ctx.db.getTurn(state.turnId)?.prompt ?? null : null;
+        entries.push({
+            stateId,
+            createdAt: state.createdAt,
+            summary: annotation.summary,
+            reason: annotation.reason,
+            decisions: annotation.decisions,
+            riskLevel: annotation.riskLevel,
+            filesTouched: changes.map((c) => c.filePath),
+            prompt,
+        });
+    }
+    return entries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+//# sourceMappingURL=chat-retrieval.js.map

package/dist/core/context-tree.js

@@ -0,0 +1,135 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+const MAX_ENTRIES_PER_DIR = 8;
+const MAX_SUMMARY_ENTRIES = 8;
+const SUMMARY_FILE = "WHYDID_SUMMARY.md";
+/** The immediate parent directory of a project-relative file path, or "" for a root-level file. */
+export function directoryFor(filePath) {
+    const dir = dirname(filePath);
+    return dir === "." ? "" : dir;
+}
+function contextFileNameFor(dir) {
+    return dir === "" ? "CONTEXT.md" : `${dir}/CONTEXT.md`;
+}
+/**
+ * True for a file whydid itself writes (CONTEXT.md in any directory, the
+ * root WHYDID_SUMMARY.md) — never something a checkpoint should be created
+ * *for*. Regenerating these is a side effect of a real checkpoint, and that
+ * regeneration is itself a file write the watcher would otherwise see as a
+ * new change: without this check, a checkpoint's own doc update becomes the
+ * next checkpoint's trigger, forever, each one annotated and regenerating
+ * the docs again — a real incident (2026-09-24) that produced 11 checkpoints
+ * in nine minutes with no actual source change behind any of them.
+ */
+export function isAutoGeneratedDocFile(filePath) {
+    return filePath === SUMMARY_FILE || filePath === "CONTEXT.md" || filePath.endsWith("/CONTEXT.md");
+}
+function loadEntry(ctx, stateId) {
+    const state = ctx.db.getState(stateId);
+    const annotation = ctx.db.getAnnotation(stateId);
+    if (!state || !annotation || annotation.status !== "generated")
+        return null;
+    const changes = ctx.db.getFileChanges(stateId);
+    const prompt = state.turnId ? ctx.db.getTurn(state.turnId)?.prompt ?? null : null;
+    return {
+        createdAt: state.createdAt,
+        summary: annotation.summary ?? "Change",
+        reason: annotation.reason ?? "",
+        decisions: annotation.decisions,
+        riskLevel: annotation.riskLevel,
+        filesTouched: changes.map((c) => c.filePath),
+        prompt,
+    };
+}
+function renderMarkdown(title, intro, entries) {
+    const lines = [
+        `# ${title}`,
+        "",
+        `_${intro} Auto-generated by whydid from real AI coding sessions — do not edit by hand, it will be overwritten on the next annotated checkpoint here. Safe, and encouraged, to commit._`,
+        "",
+    ];
+    for (const e of entries) {
+        lines.push(`## ${e.summary}`);
+        lines.push(`_${new Date(e.createdAt).toLocaleString()}${e.riskLevel ? ` · ${e.riskLevel} risk` : ""}_`);
+        lines.push("");
+        if (e.prompt) {
+            lines.push(`**Prompt:** ${e.prompt}`);
+            lines.push("");
+        }
+        if (e.reason) {
+            lines.push(e.reason);
+            lines.push("");
+        }
+        if (e.decisions.length > 0) {
+            lines.push("**Decisions:**");
+            for (const d of e.decisions)
+                lines.push(`- ${d}`);
+            lines.push("");
+        }
+        lines.push(`**Files:** ${e.filesTouched.join(", ")}`);
+        lines.push("");
+        lines.push("---");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function writeContextFile(ctx, projectId, dir, entries) {
+    const relPath = contextFileNameFor(dir);
+    const abs = join(ctx.projectRoot, relPath);
+    const title = dir === "" ? "Context — project root" : `Context — ${dir}`;
+    const intro = dir === "" ? "Recent AI-assisted decisions behind the files directly in this directory." : `Recent AI-assisted decisions behind the files in \`${dir}/\`.`;
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, renderMarkdown(title, intro, entries), "utf-8");
+    ctx.db.upsertContextFile({ projectId, dirPath: dir, filePath: relPath, checkpointCount: entries.length, updatedAt: new Date().toISOString() });
+    return relPath;
+}
+function writeSummaryFile(ctx, projectId, entries) {
+    const abs = join(ctx.projectRoot, SUMMARY_FILE);
+    writeFileSync(abs, renderMarkdown("Project summary", "The most significant AI-assisted decisions across this project.", entries), "utf-8");
+    ctx.db.upsertContextFile({ projectId, dirPath: "", filePath: SUMMARY_FILE, checkpointCount: entries.length, updatedAt: new Date().toISOString() });
+    return SUMMARY_FILE;
+}
+function regenerateDirectory(ctx, projectId, dir) {
+    const stateIds = ctx.db.findAnnotatedStateIdsForDirectory(projectId, dir, MAX_ENTRIES_PER_DIR);
+    const entries = stateIds.map((id) => loadEntry(ctx, id)).filter((e) => e !== null);
+    if (entries.length === 0)
+        return null;
+    return writeContextFile(ctx, projectId, dir, entries);
+}
+function regenerateSummary(ctx, projectId) {
+    const stateIds = ctx.db.findAnnotatedStateIdsForDirectory(projectId, null, MAX_SUMMARY_ENTRIES);
+    const entries = stateIds.map((id) => loadEntry(ctx, id)).filter((e) => e !== null);
+    if (entries.length === 0)
+        return null;
+    return writeSummaryFile(ctx, projectId, entries);
+}
+/**
+ * Regenerates the CONTEXT.md for every directory touched by a just-annotated
+ * checkpoint, plus the project-wide summary. Call this right after an
+ * annotation succeeds (status "generated") — never on a failed/unavailable
+ * one, since there'd be nothing new to say.
+ */
+export async function updateContextTree(ctx, projectId, changedFilePaths) {
+    const dirs = new Set(changedFilePaths.map(directoryFor));
+    const updatedFiles = [...dirs].map((dir) => regenerateDirectory(ctx, projectId, dir));
+    updatedFiles.push(regenerateSummary(ctx, projectId));
+    return { updatedFiles: updatedFiles.filter((f) => f !== null) };
+}
+/**
+ * Rebuilds the entire context tree from a project's full annotated history —
+ * for backfilling an existing project the first time this feature runs, or a
+ * manual resync (`whydid context`).
+ */
+export async function regenerateAllContextFiles(ctx, projectId) {
+    const allStateIds = ctx.db.findAnnotatedStateIdsForDirectory(projectId, null, Number.MAX_SAFE_INTEGER);
+    const dirs = new Set();
+    for (const stateId of allStateIds) {
+        for (const change of ctx.db.getFileChanges(stateId)) {
+            dirs.add(directoryFor(change.filePath));
+        }
+    }
+    const updatedFiles = [...dirs].map((dir) => regenerateDirectory(ctx, projectId, dir));
+    updatedFiles.push(regenerateSummary(ctx, projectId));
+    return { updatedFiles: updatedFiles.filter((f) => f !== null) };
+}
+//# sourceMappingURL=context-tree.js.map