whydid 1.0.0

package/dist/cli/commands/daemon.js

@@ -0,0 +1,139 @@
+import { Command } from "commander";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { openSync } from "node:fs";
+import { requireEngineContext, requireProjectId } from "../context.js";
+import { createDaemonApp } from "../../daemon/server.js";
+import { readPidFile, writePidFile, removePidFile, isProcessAlive } from "../../daemon/pidfile.js";
+import { listenWithPortReuse } from "../../daemon/listen.js";
+import { ProjectWatcher } from "../../watcher/watcher.js";
+import { loadConfig } from "../../shared/config.js";
+import { createLLMProvider } from "../../llm/factory.js";
+import { FileSecretStore } from "../../licensing/secret-store.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Waits specifically for *this* start's pidfile, not just "a pidfile" — a
+// stale file from a crashed previous run is still sitting there when the
+// new child spawns, so polling for mere existence would report success
+// immediately with the wrong (dead) pid/port.
+async function waitForPidFile(whydidDir, timeoutMs, expectedPid) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const pidFile = readPidFile(whydidDir);
+        if (pidFile && pidFile.pid === expectedPid)
+            return pidFile;
+        await sleep(100);
+    }
+    return null;
+}
+const __dirname = dirname(fileURLToPath(import.meta.url));
+async function runForeground(projectRoot) {
+    // A long-running local daemon should degrade, not die, on an unexpected
+    // async error — an uncaught rejection anywhere outside the Express
+    // request cycle (a background poll, a fire-and-forget call missing a
+    // .catch) otherwise takes the whole process down by default, silently
+    // orphaning every open dashboard tab.
+    process.on("uncaughtException", (err) => {
+        console.error("[whydid daemon] uncaught exception (daemon is still running):", err);
+    });
+    process.on("unhandledRejection", (reason) => {
+        console.error("[whydid daemon] unhandled rejection (daemon is still running):", reason);
+    });
+    const ctx = requireEngineContext(projectRoot);
+    const projectId = requireProjectId(ctx);
+    const config = loadConfig(ctx.whydidDir);
+    const llmProvider = await createLLMProvider(config.ai, new FileSecretStore(ctx.whydidDir));
+    ctx.db.pruneOldSocialPosts(projectId, config.buildInPublic.retentionDays);
+    const watcher = new ProjectWatcher(ctx, projectId, config.checkpoint, llmProvider, undefined, undefined, config.privacy, config.contextTree.enabled, config.buildInPublic.enabled, config.buildInPublic.retentionDays);
+    watcher.start();
+    // Reuse the previous run's port and token when they're available (e.g.
+    // after a crash, or a plain restart) so a dashboard tab left open from
+    // before can often just be reloaded instead of needing a brand-new URL.
+    const previous = readPidFile(ctx.whydidDir);
+    const token = previous?.token ?? randomBytes(16).toString("hex");
+    const app = createDaemonApp(ctx, projectId, token, watcher);
+    const server = await listenWithPortReuse(app, previous?.port);
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : 0;
+    writePidFile(ctx.whydidDir, { pid: process.pid, port, token });
+    console.log(`whydid dashboard: http://127.0.0.1:${port}/?token=${token}`);
+    const shutdown = () => {
+        removePidFile(ctx.whydidDir);
+        void watcher.stop();
+        server.close(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+export function createDaemonCommand() {
+    const daemon = new Command("daemon").description("Manage the whydid local daemon");
+    daemon
+        .command("start")
+        .description("Start the local daemon and print the dashboard URL")
+        .option("--foreground", "run in the foreground instead of detaching")
+        .action(async (opts) => {
+        const projectRoot = process.cwd();
+        const ctx = requireEngineContext(projectRoot);
+        const existing = readPidFile(ctx.whydidDir);
+        ctx.db.close();
+        if (existing && isProcessAlive(existing.pid)) {
+            console.log(`Daemon already running (pid ${existing.pid}) at http://127.0.0.1:${existing.port}/?token=${existing.token}`);
+            return;
+        }
+        if (existing) {
+            console.log(`Found a stale daemon record (pid ${existing.pid} is no longer running) — starting fresh.`);
+        }
+        if (opts.foreground) {
+            await runForeground(projectRoot);
+            return;
+        }
+        const logFd = openSync(join(ctx.whydidDir, "logs", "daemon.log"), "a");
+        const child = spawn(process.execPath, [join(__dirname, "..", "..", "..", "dist", "cli", "index.js"), "daemon", "start", "--foreground"], { cwd: projectRoot, detached: true, stdio: ["ignore", logFd, logFd] });
+        child.unref();
+        const started = await waitForPidFile(ctx.whydidDir, 8000, child.pid);
+        if (started) {
+            console.log(`whydid dashboard: http://127.0.0.1:${started.port}/?token=${started.token}`);
+        }
+        else {
+            console.log("Daemon is taking longer than expected to start.");
+            console.log(`Check .whydid/logs/daemon.log or run \`whydid daemon status\`.`);
+        }
+    });
+    daemon.command("stop").description("Stop the running daemon").action(() => {
+        const ctx = requireEngineContext(process.cwd());
+        const existing = readPidFile(ctx.whydidDir);
+        ctx.db.close();
+        if (!existing) {
+            console.log("Daemon is not running.");
+            return;
+        }
+        if (!isProcessAlive(existing.pid)) {
+            console.log("Daemon process not found; clearing stale pidfile.");
+            removePidFile(ctx.whydidDir);
+            return;
+        }
+        try {
+            process.kill(existing.pid, "SIGTERM");
+            console.log("Daemon stopped.");
+        }
+        catch {
+            console.log("Daemon process not found; clearing stale pidfile.");
+        }
+        removePidFile(ctx.whydidDir);
+    });
+    daemon.command("status").description("Show whether the daemon is running and its URL").action(() => {
+        const ctx = requireEngineContext(process.cwd());
+        const existing = readPidFile(ctx.whydidDir);
+        ctx.db.close();
+        if (!existing || !isProcessAlive(existing.pid)) {
+            console.log("Daemon is not running.");
+            return;
+        }
+        console.log(`Daemon running (pid ${existing.pid}): http://127.0.0.1:${existing.port}/?token=${existing.token}`);
+    });
+    return daemon;
+}
+//# sourceMappingURL=daemon.js.map

package/dist/cli/commands/export.js

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { requireEngineContext, requireProjectId } from "../context.js";
+import { buildExportData, exportAsJson, exportAsMarkdown, exportAsHtml } from "../../core/export.js";
+const EXTENSIONS = { json: "json", markdown: "md", html: "html" };
+export function createExportCommand() {
+    return new Command("export")
+        .description("Export the project's whydid history as JSON, Markdown, or HTML")
+        .option("--format <format>", "json | markdown | html", "json")
+        .option("--out <path>", "output file path (default: whydid-export.<ext> in the current directory)")
+        .action((opts) => {
+        const ctx = requireEngineContext(process.cwd());
+        const projectId = requireProjectId(ctx);
+        const project = ctx.db.getProject(projectId);
+        const data = buildExportData(ctx.db, project);
+        let content;
+        if (opts.format === "markdown")
+            content = exportAsMarkdown(data);
+        else if (opts.format === "html")
+            content = exportAsHtml(data);
+        else if (opts.format === "json")
+            content = exportAsJson(data);
+        else {
+            console.log(`Unknown format: ${opts.format}. Use json, markdown, or html.`);
+            ctx.db.close();
+            return;
+        }
+        const ext = EXTENSIONS[opts.format];
+        const outPath = opts.out ?? join(process.cwd(), `whydid-export.${ext}`);
+        writeFileSync(outPath, content, "utf-8");
+        console.log(`✓ Exported ${data.states.length} states to ${outPath}`);
+        ctx.db.close();
+    });
+}
+//# sourceMappingURL=export.js.map

package/dist/cli/commands/init.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { Command } from "commander";
+import { buildEngineContext, defaultProjectName, whydidDirExists } from "../context.js";
+import { initProject, createCheckpoint } from "../../core/engine.js";
+import { detectGit } from "../../git/git.js";
+import { DEFAULT_CONFIG, saveConfig } from "../../shared/config.js";
+import { installAgentContextInstructions } from "../../core/agent-context.js";
+import { installAgentHookConfigs } from "../../core/agent-hooks.js";
+function ensureGitignored(projectRoot) {
+    const path = join(projectRoot, ".gitignore");
+    const entry = ".whydid/";
+    if (!existsSync(path)) {
+        writeFileSync(path, `${entry}\n`);
+        return;
+    }
+    const content = readFileSync(path, "utf-8");
+    if (content.split("\n").some((line) => line.trim() === entry || line.trim() === ".whydid"))
+        return;
+    appendFileSync(path, `${content.endsWith("\n") || content === "" ? "" : "\n"}${entry}\n`);
+}
+export async function runInit(projectRoot) {
+    const alreadyInitialized = whydidDirExists(projectRoot);
+    const ctx = buildEngineContext(projectRoot);
+    saveConfig(ctx.whydidDir, { ...DEFAULT_CONFIG, projectName: defaultProjectName(projectRoot) });
+    ensureGitignored(projectRoot);
+    const agentInstructionFiles = installAgentContextInstructions(projectRoot);
+    const agentHooks = installAgentHookConfigs(projectRoot);
+    if (alreadyInitialized) {
+        const row = ctx.db.raw.prepare(`SELECT id FROM projects ORDER BY created_at ASC LIMIT 1`).get();
+        if (row) {
+            const result = await createCheckpoint(ctx, { projectId: row.id });
+            ctx.db.close();
+            return { projectId: row.id, stateId: result.stateId, agentInstructionFiles, agentHookFiles: agentHooks.installed, skippedAgentHookFiles: agentHooks.skipped };
+        }
+    }
+    const result = await initProject(ctx, defaultProjectName(projectRoot));
+    ctx.db.close();
+    return { ...result, agentInstructionFiles, agentHookFiles: agentHooks.installed, skippedAgentHookFiles: agentHooks.skipped };
+}
+export function createInitCommand() {
+    return new Command("init").description("Initialize whydid for the current project").action(async () => {
+        const projectRoot = process.cwd();
+        console.log("whydid\n");
+        const git = await detectGit(projectRoot);
+        const result = await runInit(projectRoot);
+        console.log(`✓ Project detected: ${projectRoot.split("/").pop()}`);
+        console.log(git.isRepo ? "✓ Git repository detected" : "  Git repository not detected (whydid still works)");
+        console.log("✓ Local database initialized");
+        console.log(`✓ Initial project state captured (${result.stateId.slice(0, 8)})`);
+        if (result.agentInstructionFiles.length > 0) {
+            console.log(`✓ Shared whydid context instructions installed for ${result.agentInstructionFiles.length} coding-agent entry point${result.agentInstructionFiles.length === 1 ? "" : "s"}`);
+        }
+        if (result.agentHookFiles.length > 0) {
+            console.log(`✓ Local Codex/Cursor session hooks configured (${result.agentHookFiles.join(", ")})`);
+        }
+        if (result.skippedAgentHookFiles.length > 0) {
+            console.log(`  Could not update invalid hook config: ${result.skippedAgentHookFiles.join(", ")}`);
+        }
+        console.log("\nwhydid is ready.\n\nRun `whydid daemon start` to open the local dashboard.");
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/commands/key.js

@@ -0,0 +1,65 @@
+import { Command } from "commander";
+import { requireEngineContext } from "../context.js";
+import { FileSecretStore, getSecretStatuses } from "../../licensing/secret-store.js";
+export async function runSetKey(projectRoot, provider, value) {
+    const ctx = requireEngineContext(projectRoot);
+    const store = new FileSecretStore(ctx.whydidDir);
+    await store.set(provider, value);
+    ctx.db.close();
+}
+export async function runClearKey(projectRoot, provider) {
+    const ctx = requireEngineContext(projectRoot);
+    const store = new FileSecretStore(ctx.whydidDir);
+    await store.delete(provider);
+    ctx.db.close();
+}
+export async function runListKeys(projectRoot) {
+    const ctx = requireEngineContext(projectRoot);
+    const store = new FileSecretStore(ctx.whydidDir);
+    const statuses = await getSecretStatuses(store);
+    ctx.db.close();
+    return statuses;
+}
+export function createKeyCommand() {
+    const key = new Command("key").description("Manage local API keys for AI providers (stored per-project in .whydid/secrets.json)");
+    key
+        .command("set")
+        .description("Save an API key locally for this project — takes precedence over a same-provider environment variable")
+        .argument("<provider>", 'provider name, e.g. "anthropic" or "openai"')
+        .argument("<value>", "the API key")
+        .action(async (provider, value) => {
+        const name = provider.toLowerCase();
+        await runSetKey(process.cwd(), name, value);
+        console.log(`✓ Saved a local ${name} key for this project.`);
+        console.log(`  It's used instead of any ${name.toUpperCase()}_API_KEY environment variable, for this project only.`);
+    });
+    key
+        .command("clear")
+        .description("Remove a locally saved API key for this project")
+        .argument("<provider>", 'provider name, e.g. "anthropic" or "openai"')
+        .action(async (provider) => {
+        const name = provider.toLowerCase();
+        await runClearKey(process.cwd(), name);
+        console.log(`✓ Removed the local ${name} key for this project.`);
+        console.log(`  If ${name.toUpperCase()}_API_KEY is set in your environment, that will be used instead.`);
+    });
+    key
+        .command("list")
+        .description("Show which providers have a key configured, and where it's coming from")
+        .action(async () => {
+        const statuses = await runListKeys(process.cwd());
+        for (const s of statuses) {
+            if (!s.configured) {
+                console.log(`${s.provider}: not set`);
+            }
+            else if (s.source === "file") {
+                console.log(`${s.provider}: ${s.masked}  (saved locally for this project)`);
+            }
+            else {
+                console.log(`${s.provider}: ${s.masked}  (from ${s.provider.toUpperCase()}_API_KEY in your environment)`);
+            }
+        }
+    });
+    return key;
+}
+//# sourceMappingURL=key.js.map

package/dist/cli/commands/license.js

@@ -0,0 +1,57 @@
+import { Command } from "commander";
+import { createDefaultLicenseManager, PRICING_URL } from "../../licensing/config.js";
+export async function runLogin(manager, licenseKey) {
+    await manager.activate(licenseKey);
+}
+export async function runLogout(manager) {
+    await manager.deactivate();
+}
+/** Reads only the locally-stored, already-verified license — no network call, matching whydid's local-first design even for its own status check. */
+export async function runLicenseStatus(manager) {
+    if (!manager.isActivated())
+        return null;
+    return manager.getLicense();
+}
+export function createLoginCommand() {
+    return new Command("login")
+        .description("Activate whydid with your license key")
+        .argument("<licenseKey>", "the license key from your purchase email")
+        .action(async (licenseKey) => {
+        const manager = await createDefaultLicenseManager();
+        try {
+            await runLogin(manager, licenseKey);
+            console.log("✓ Activated. Run `whydid license` any time to check status.");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            console.error(`Manage your devices: ${PRICING_URL.replace("/pricing", "/account/devices")}`);
+            process.exitCode = 1;
+        }
+    });
+}
+export function createLogoutCommand() {
+    return new Command("logout")
+        .description("Deactivate this machine")
+        .action(async () => {
+        const manager = await createDefaultLicenseManager();
+        await runLogout(manager);
+        console.log("✓ Deactivated this machine.");
+    });
+}
+export function createLicenseCommand() {
+    return new Command("license")
+        .description("Show local license status (no network call)")
+        .action(async () => {
+        const manager = await createDefaultLicenseManager();
+        const status = await runLicenseStatus(manager);
+        if (!status) {
+            console.log("Not activated. Run `whydid login <licenseKey>`.");
+            return;
+        }
+        console.log(`Product:  ${status.product}`);
+        console.log(`Plan:     ${status.plan}`);
+        console.log(`Features: ${status.features.join(", ")}`);
+        console.log(`Last validated: ${status.lastValidatedAt}`);
+    });
+}
+//# sourceMappingURL=license.js.map

package/dist/cli/commands/milestone.js

@@ -0,0 +1,64 @@
+import { Command } from "commander";
+import { requireEngineContext, requireProjectId } from "../context.js";
+export function runSetMilestone(projectRoot, stateId, label) {
+    const ctx = requireEngineContext(projectRoot);
+    requireProjectId(ctx);
+    const state = ctx.db.getState(stateId);
+    if (!state) {
+        ctx.db.close();
+        throw new Error(`Unknown state: ${stateId}`);
+    }
+    ctx.db.setStateMilestone(stateId, label);
+    ctx.db.close();
+    return { stateId, milestoneLabel: label };
+}
+export function runListMilestones(projectRoot) {
+    const ctx = requireEngineContext(projectRoot);
+    const projectId = requireProjectId(ctx);
+    const milestones = ctx.db.listMilestones(projectId);
+    ctx.db.close();
+    return milestones;
+}
+export function createMilestoneCommand() {
+    return new Command("milestone")
+        .description("Tag a state as a milestone (e.g. \"v1 launch\"), or list all tagged milestones")
+        .argument("[stateId]", "state id to tag — omit to list all milestones")
+        .argument("[label]", "milestone label — omit with --clear to remove")
+        .option("--clear", "remove the milestone tag from this state")
+        .action((stateId, label, opts) => {
+        const projectRoot = process.cwd();
+        if (!stateId) {
+            const milestones = runListMilestones(projectRoot);
+            if (milestones.length === 0) {
+                console.log("No milestones tagged yet. Run `whydid milestone <stateId> <label>` to tag one.");
+                return;
+            }
+            for (const m of milestones) {
+                console.log(`★ ${m.milestoneLabel}  —  #${m.id.slice(0, 8)}  (${new Date(m.createdAt).toLocaleString()})`);
+            }
+            return;
+        }
+        if (opts.clear) {
+            try {
+                runSetMilestone(projectRoot, stateId, null);
+                console.log(`✓ Removed milestone tag from #${stateId.slice(0, 8)}`);
+            }
+            catch (err) {
+                console.log(err instanceof Error ? err.message : String(err));
+            }
+            return;
+        }
+        if (!label) {
+            console.log("A label is required, e.g. `whydid milestone <stateId> \"v1 launch\"`, or pass --clear to remove one.");
+            return;
+        }
+        try {
+            runSetMilestone(projectRoot, stateId, label);
+            console.log(`★ Tagged #${stateId.slice(0, 8)} as milestone: "${label}"`);
+        }
+        catch (err) {
+            console.log(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=milestone.js.map

package/dist/cli/commands/prompt.js

@@ -0,0 +1,75 @@
+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";
+import { generateAgentPrompt } from "../../llm/agent-prompt.js";
+export function createPromptCommand() {
+    return new Command("prompt")
+        .description("Generate a ready-to-paste prompt for your AI coding agent to revert or build on a past change")
+        .argument("<file>", "file path")
+        .option("--state <stateId>", "which state's change to target (default: the most recent change to this file)")
+        .option("--mode <mode>", "revert | continue", "revert")
+        .option("--instruction <text>", "required with --mode continue: what to build on top")
+        .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 mode = opts.mode;
+        if (mode !== "revert" && mode !== "continue") {
+            console.log(`Unknown mode: ${opts.mode}. Use "revert" or "continue".`);
+            ctx.db.close();
+            return;
+        }
+        if (mode === "continue" && !opts.instruction) {
+            console.log("`--mode continue` requires `--instruction \"what to build on top\"`.");
+            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;
+        }
+        const targetIndex = opts.state ? history.findIndex((h) => h.stateId === opts.state) : history.length - 1;
+        if (targetIndex === -1) {
+            console.log(`State ${opts.state} did not change ${file}. Run \`whydid why ${file}\` to see the real history.`);
+            ctx.db.close();
+            return;
+        }
+        const targetEntry = history[targetIndex];
+        const laterEntries = history.slice(targetIndex + 1);
+        const config = loadConfig(ctx.whydidDir);
+        const provider = await createLLMProvider(config.ai, new FileSecretStore(ctx.whydidDir));
+        if (provider.id === "noop") {
+            console.log("Generating an agent prompt requires an LLM provider (set ai.provider in .whydid/config.json and the matching *_API_KEY env var).");
+            ctx.db.close();
+            return;
+        }
+        const change = ctx.db.getFileChanges(targetEntry.stateId).find((c) => c.filePath === file);
+        const targetDiff = change ? computeFileDiff(ctx.store, change).unified : "(diff unavailable)";
+        try {
+            const prompt = await generateAgentPrompt(provider, {
+                filePath: file,
+                targetEntry,
+                laterEntries,
+                targetDiff,
+                mode,
+                continueInstruction: opts.instruction,
+            });
+            console.log(prompt);
+        }
+        catch (err) {
+            console.log(`Failed to generate a prompt: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        ctx.db.close();
+    });
+}
+//# sourceMappingURL=prompt.js.map

package/dist/cli/commands/recap.js

@@ -0,0 +1,48 @@
+import { Command } from "commander";
+import { requireEngineContext, requireProjectId } from "../context.js";
+import { computeRecap } from "../../core/recap.js";
+function startOfToday() {
+    const now = new Date();
+    return new Date(now.getFullYear(), now.getMonth(), now.getDate()).toISOString();
+}
+export function createRecapCommand() {
+    return new Command("recap")
+        .alias("doctor")
+        .description("Summarize today's AI-assisted changes: churn, risk, unexplained work")
+        .action(() => {
+        const ctx = requireEngineContext(process.cwd());
+        const projectId = requireProjectId(ctx);
+        const recap = computeRecap(ctx.db, projectId, startOfToday());
+        console.log("PROJECT RECAP\n");
+        console.log(`You made ${recap.totalChanges} AI-assisted change${recap.totalChanges === 1 ? "" : "s"} today.\n`);
+        if (recap.mainAreas.length > 0) {
+            console.log("Main areas:");
+            for (const area of recap.mainAreas)
+                console.log(`• ${area}`);
+            console.log("");
+        }
+        if (recap.highChurnFiles.length > 0) {
+            console.log("High-churn files:");
+            for (const f of recap.highChurnFiles)
+                console.log(`• ${f.filePath} — ${f.changes} change${f.changes === 1 ? "" : "s"}`);
+            console.log("");
+        }
+        if (recap.riskyAreas.length > 0) {
+            console.log("Potentially risky areas:");
+            for (const r of recap.riskyAreas)
+                console.log(`• ${r}`);
+            console.log("");
+        }
+        if (recap.latestTestRun) {
+            console.log("Tests:");
+            console.log(recap.latestTestRun.status === "passed" ? `✓ passed (${recap.latestTestRun.durationMs}ms)` : `✗ failed (exit ${recap.latestTestRun.exitCode})`);
+            console.log("");
+        }
+        else {
+            console.log("Tests:\nNo test results recorded. Configure `test.command` and run `whydid test`.\n");
+        }
+        console.log(`Unexplained changes:\n${recap.unexplainedChanges}`);
+        ctx.db.close();
+    });
+}
+//# sourceMappingURL=recap.js.map

package/dist/cli/commands/restore-fork.js

@@ -0,0 +1,101 @@
+import { Command } from "commander";
+import { createInterface } from "node:readline/promises";
+import { requireEngineContext, requireProjectId } from "../context.js";
+import { createCheckpoint, restoreState, restoreFiles, forkState } from "../../core/engine.js";
+export async function runCheckpoint(projectRoot) {
+    const ctx = requireEngineContext(projectRoot);
+    const result = await createCheckpoint(ctx);
+    ctx.db.close();
+    return { stateId: result.stateId };
+}
+export async function runRestore(projectRoot, targetStateId) {
+    const ctx = requireEngineContext(projectRoot);
+    const projectId = requireProjectId(ctx);
+    const result = await restoreState(ctx, projectId, targetStateId);
+    ctx.db.close();
+    return result;
+}
+export async function runRestoreFiles(projectRoot, targetStateId, filePaths) {
+    const ctx = requireEngineContext(projectRoot);
+    const projectId = requireProjectId(ctx);
+    const result = await restoreFiles(ctx, projectId, targetStateId, filePaths);
+    ctx.db.close();
+    return result;
+}
+export async function runFork(projectRoot, sourceStateId, name) {
+    const ctx = requireEngineContext(projectRoot);
+    const projectId = requireProjectId(ctx);
+    const result = await forkState(ctx, projectId, sourceStateId, name);
+    ctx.db.close();
+    return result;
+}
+async function confirm(message) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question(`${message} [y/N] `);
+    rl.close();
+    return answer.trim().toLowerCase() === "y";
+}
+export function createRestoreCommand() {
+    return new Command("restore")
+        .description("Safely restore an earlier state (current state is preserved automatically)")
+        .argument("<stateId>", "state id to restore")
+        .option("--yes", "skip confirmation prompt")
+        .option("--only <paths>", "comma-separated list of file paths to restore, instead of the whole state")
+        .action(async (stateId, opts) => {
+        const projectRoot = process.cwd();
+        const ctx = requireEngineContext(projectRoot);
+        const projectId = requireProjectId(ctx);
+        const target = ctx.db.getState(stateId);
+        if (!target) {
+            console.log(`No state found matching "${stateId}". Run \`whydid timeline\` to see valid state ids.`);
+            ctx.db.close();
+            return;
+        }
+        const fileCount = ctx.db.getStateManifest(stateId).length;
+        ctx.db.close();
+        const only = opts.only?.split(",").map((p) => p.trim()).filter(Boolean);
+        if (only && only.length > 0) {
+            console.log(`Restore ${only.length} file${only.length === 1 ? "" : "s"} from State #${stateId.slice(0, 8)} — ${target.label ?? target.stateType}?\n`);
+            only.forEach((p) => console.log(`  ${p}`));
+            console.log("\nEverything else in your current state stays exactly as it is.");
+            if (!opts.yes && !(await confirm("\nProceed?"))) {
+                console.log("Cancelled.");
+                return;
+            }
+            const result = await runRestoreFiles(projectRoot, stateId, only);
+            console.log(`\n✓ Restored ${result.filesRestored.length} file${result.filesRestored.length === 1 ? "" : "s"} from #${stateId.slice(0, 8)}`);
+            console.log(`Your previous state was preserved as: #${result.safetyStateId.slice(0, 8)}`);
+            return;
+        }
+        console.log(`Restore State #${stateId.slice(0, 8)} — ${target.label ?? target.stateType}?\n`);
+        console.log("Your current state will be preserved automatically.");
+        console.log(`${fileCount} file${fileCount === 1 ? "" : "s"} in the target state.\n`);
+        if (!opts.yes && !(await confirm("Proceed?"))) {
+            console.log("Cancelled.");
+            return;
+        }
+        const result = await runRestore(projectRoot, stateId);
+        console.log(`\n✓ Restored to #${stateId.slice(0, 8)}`);
+        console.log(`Your previous state was preserved as: #${result.safetyStateId.slice(0, 8)}`);
+    });
+}
+export function createForkCommand() {
+    return new Command("fork")
+        .description("Fork a new branch from a state")
+        .argument("<stateId>", "state id to fork from")
+        .argument("<name>", "fork name")
+        .action(async (stateId, name) => {
+        const projectRoot = process.cwd();
+        const ctx = requireEngineContext(projectRoot);
+        requireProjectId(ctx);
+        const target = ctx.db.getState(stateId);
+        ctx.db.close();
+        if (!target) {
+            console.log(`No state found matching "${stateId}". Run \`whydid timeline\` to see valid state ids.`);
+            return;
+        }
+        const result = await runFork(projectRoot, stateId, name);
+        console.log(`✓ Forked "${name}" from #${stateId.slice(0, 8)} → new state #${result.forkStateId.slice(0, 8)}`);
+    });
+}
+//# sourceMappingURL=restore-fork.js.map