@ulpi/cli 0.1.0

package/dist/history-ATTUKOHO.js

@@ -0,0 +1,934 @@
+import {
+  DEFAULT_HISTORY_CONFIG,
+  buildSessionSummary,
+  entryExists,
+  findReviewPlansForCommit,
+  findSessionForCommit,
+  getCommitDiffStats,
+  getCommitMetadata,
+  getCommitRawDiff,
+  getCurrentHead,
+  historyBranchExists,
+  initHistoryBranch,
+  listRecentCommits,
+  loadActiveGuards,
+  readBranchMeta,
+  readEntryRawData,
+  readHistoryEntry,
+  readTimeline,
+  updateEntryEnrichment,
+  writeHistoryEntry
+} from "./chunk-NNUWU6CV.js";
+import "./chunk-YM2HV4IA.js";
+import {
+  DEFAULT_AI_MODEL,
+  REVIEWS_DIR,
+  getHistoryBranch
+} from "./chunk-7LXY5UVC.js";
+import "./chunk-4VNS5WPM.js";
+
+// src/commands/history.ts
+import chalk from "chalk";
+import * as path2 from "path";
+import * as fs2 from "fs";
+import * as readline from "readline";
+
+// src/history/enricher.ts
+import { execFileSync, spawn } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+function resolveClaudePath() {
+  try {
+    const result = execFileSync("which", ["claude"], { stdio: "pipe", timeout: 3e3 }).toString().trim();
+    if (result) return result;
+  } catch {
+  }
+  const home = os.homedir();
+  const candidates = [
+    path.join(home, ".local", "bin", "claude"),
+    path.join(home, ".claude", "bin", "claude"),
+    "/usr/local/bin/claude"
+  ];
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) return p;
+    } catch {
+    }
+  }
+  return null;
+}
+var cachedClaudePath;
+function getClaudePath() {
+  if (cachedClaudePath === void 0) {
+    cachedClaudePath = resolveClaudePath();
+  }
+  return cachedClaudePath;
+}
+function isClaudeCliAvailable() {
+  const p = getClaudePath();
+  if (!p) return false;
+  try {
+    execFileSync(p, ["--version"], { stdio: "pipe", timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function computeAntiPatternMetrics(events) {
+  const rawFileEdits = {};
+  for (const ev of events) {
+    if ((ev.toolName === "Write" || ev.toolName === "Edit") && ev.filePath) {
+      rawFileEdits[ev.filePath] = (rawFileEdits[ev.filePath] ?? 0) + 1;
+    }
+  }
+  const fileEditCounts = {};
+  for (const [file, count] of Object.entries(rawFileEdits)) {
+    if (count >= 3) fileEditCounts[file] = count;
+  }
+  const postcondFailRates = {};
+  for (const ev of events) {
+    if (ev.event === "postcondition_run" && ev.command) {
+      if (!postcondFailRates[ev.command]) {
+        postcondFailRates[ev.command] = { success: 0, fail: 0 };
+      }
+      postcondFailRates[ev.command].success++;
+    }
+    if (ev.event === "postcondition_failed" && ev.command) {
+      if (!postcondFailRates[ev.command]) {
+        postcondFailRates[ev.command] = { success: 0, fail: 0 };
+      }
+      postcondFailRates[ev.command].fail++;
+    }
+  }
+  const blockRetrySequences = [];
+  let currentBlock = null;
+  for (const ev of events) {
+    if (ev.event === "tool_blocked" && ev.toolName) {
+      const key = `${ev.toolName}|${ev.filePath ?? ""}|${ev.ruleName ?? ""}`;
+      if (currentBlock && `${currentBlock.tool}|${currentBlock.file}|${currentBlock.rule}` === key) {
+        currentBlock.count++;
+      } else {
+        if (currentBlock && currentBlock.count >= 2) {
+          blockRetrySequences.push({ ...currentBlock });
+        }
+        currentBlock = {
+          tool: ev.toolName,
+          file: ev.filePath ?? "",
+          rule: ev.ruleName ?? "",
+          count: 1
+        };
+      }
+    } else {
+      if (currentBlock && currentBlock.count >= 2) {
+        blockRetrySequences.push({ ...currentBlock });
+      }
+      currentBlock = null;
+    }
+  }
+  if (currentBlock && currentBlock.count >= 2) {
+    blockRetrySequences.push({ ...currentBlock });
+  }
+  const rawCmdCounts = {};
+  for (const ev of events) {
+    if (ev.toolName === "Bash" && ev.command) {
+      rawCmdCounts[ev.command] = (rawCmdCounts[ev.command] ?? 0) + 1;
+    }
+  }
+  const commandRepeatCounts = {};
+  for (const [cmd, count] of Object.entries(rawCmdCounts)) {
+    if (count >= 5) commandRepeatCounts[cmd] = count;
+  }
+  return { fileEditCounts, postcondFailRates, blockRetrySequences, commandRepeatCounts };
+}
+function buildEnrichmentPrompt(entry, rawEvents) {
+  const sections = [];
+  sections.push("You are analyzing a commit captured by ULPI, a rules engine for AI coding agents.");
+  sections.push("Fill in the structured output fields:");
+  sections.push("- summary: A concise 1-2 sentence description of what this commit accomplishes.");
+  sections.push("- intent: The high-level goal or motivation behind the changes.");
+  sections.push("- challenges: Specific difficulties encountered during this session (e.g. test failures, blocked tools, repeated edits). Be concrete, not vague.");
+  sections.push("- ruleInsights: Observations about which guardian rules helped, which were too strict, or what rules could be added. Reference specific rule names when possible.");
+  sections.push("");
+  sections.push("## Commit");
+  sections.push(`SHA: ${entry.commit.shortSha}`);
+  sections.push(`Subject: ${entry.commit.subject}`);
+  sections.push(`Author: ${entry.commit.authorName}`);
+  sections.push(`Date: ${entry.commit.authorDate}`);
+  sections.push(`Branch: ${entry.commit.branch}`);
+  if (entry.commit.message !== entry.commit.subject) {
+    sections.push(`Message:
+${entry.commit.message}`);
+  }
+  sections.push("");
+  sections.push("## Diff Stats");
+  sections.push(`Files changed: ${entry.diff.filesChanged}`);
+  sections.push(`Insertions: +${entry.diff.insertions}`);
+  sections.push(`Deletions: -${entry.diff.deletions}`);
+  if (entry.diff.files.length > 0) {
+    sections.push("Files:");
+    for (const f of entry.diff.files.slice(0, 30)) {
+      sections.push(`  ${f.status} ${f.path} (+${f.additions}/-${f.deletions})`);
+    }
+    if (entry.diff.files.length > 30) {
+      sections.push(`  ... and ${entry.diff.files.length - 30} more files`);
+    }
+  }
+  sections.push("");
+  if (entry.session) {
+    const s = entry.session;
+    sections.push("## Session Summary");
+    sections.push(`Session: ${s.sessionId}${s.sessionName ? ` (${s.sessionName})` : ""}`);
+    sections.push(`Total events: ${s.totalEvents}`);
+    sections.push(`Rules enforced: ${s.stats.rulesEnforced}`);
+    sections.push(`Actions blocked: ${s.stats.actionsBlocked}`);
+    sections.push(`Auto-approved: ${s.stats.autoActionsRun}`);
+    sections.push(`Files read: ${s.stats.filesRead}, written: ${s.stats.filesWritten}, deleted: ${s.stats.filesDeleted}`);
+    sections.push(`Commands run: ${s.stats.commandsRun}`);
+    sections.push(`Tests: ${s.stats.testsRun ? s.stats.testsPassed ? "passed" : "failed/unknown" : "not run"}`);
+    sections.push(`Lint: ${s.stats.lintRun ? "run" : "not run"}, Build: ${s.stats.buildRun ? "run" : "not run"}`);
+    if (s.blockedTools.length > 0) {
+      sections.push(`Blocked tools: ${s.blockedTools.join(", ")}`);
+    }
+    if (s.preconditionsFired.length > 0) {
+      sections.push(`Preconditions fired: ${s.preconditionsFired.join(", ")}`);
+    }
+    if (s.postconditionsRun.length > 0) {
+      sections.push(`Postconditions run: ${s.postconditionsRun.join(", ")}`);
+    }
+    if (s.skillsInjected.length > 0) {
+      sections.push(`Skills injected: ${s.skillsInjected.join(", ")}`);
+    }
+    sections.push("");
+  }
+  if (rawEvents && rawEvents.length > 0) {
+    const metrics = computeAntiPatternMetrics(rawEvents);
+    const hasMetrics = Object.keys(metrics.fileEditCounts).length > 0 || Object.keys(metrics.postcondFailRates).length > 0 || metrics.blockRetrySequences.length > 0 || Object.keys(metrics.commandRepeatCounts).length > 0;
+    if (hasMetrics) {
+      sections.push("## Anti-Pattern Metrics");
+      if (Object.keys(metrics.fileEditCounts).length > 0) {
+        sections.push("Files edited 3+ times (possible churn):");
+        for (const [file, count] of Object.entries(metrics.fileEditCounts)) {
+          sections.push(`  ${file}: ${count} edits`);
+        }
+      }
+      if (metrics.blockRetrySequences.length > 0) {
+        sections.push("Block-retry sequences (tool blocked then retried):");
+        for (const seq of metrics.blockRetrySequences) {
+          sections.push(`  ${seq.tool}${seq.file ? ` on ${seq.file}` : ""}${seq.rule ? ` by ${seq.rule}` : ""}: ${seq.count}x`);
+        }
+      }
+      const failedPostconds = Object.entries(metrics.postcondFailRates).filter(
+        ([, v]) => v.fail > 0
+      );
+      if (failedPostconds.length > 0) {
+        sections.push("Postcondition failure rates:");
+        for (const [cmd, rates] of failedPostconds) {
+          sections.push(`  ${cmd}: ${rates.success} pass, ${rates.fail} fail`);
+        }
+      }
+      if (Object.keys(metrics.commandRepeatCounts).length > 0) {
+        sections.push("Commands run 5+ times:");
+        for (const [cmd, count] of Object.entries(metrics.commandRepeatCounts)) {
+          sections.push(`  ${cmd}: ${count}x`);
+        }
+      }
+      sections.push("");
+    }
+  }
+  if (entry.rawDiff) {
+    const maxAiDiff = 1e4;
+    const diffExcerpt = entry.rawDiff.length > maxAiDiff ? entry.rawDiff.slice(0, maxAiDiff) + "\n... (truncated)" : entry.rawDiff;
+    sections.push("## Raw Diff (excerpt)");
+    sections.push(diffExcerpt);
+    sections.push("");
+  }
+  sections.push("Fill in all fields based on the data above. Be specific and concrete.");
+  return sections.join("\n");
+}
+function toAiEnrichment(parsed, model, generatedAt) {
+  return {
+    summary: typeof parsed.summary === "string" ? parsed.summary : "",
+    intent: typeof parsed.intent === "string" ? parsed.intent : void 0,
+    challenges: Array.isArray(parsed.challenges) ? parsed.challenges : void 0,
+    ruleInsights: Array.isArray(parsed.ruleInsights) ? parsed.ruleInsights : void 0,
+    model,
+    generatedAt
+  };
+}
+function parseEnrichmentResponse(response, model) {
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    const envelope = JSON.parse(response.trim());
+    if (envelope.structured_output && typeof envelope.structured_output === "object") {
+      return toAiEnrichment(envelope.structured_output, model, generatedAt);
+    }
+    if (typeof envelope.result === "string" && envelope.result.trim().startsWith("{")) {
+      const parsed = JSON.parse(envelope.result);
+      return toAiEnrichment(parsed, model, generatedAt);
+    }
+    if (typeof envelope.summary === "string") {
+      return toAiEnrichment(envelope, model, generatedAt);
+    }
+  } catch {
+  }
+  const jsonMatch = response.match(/```json\s*\n?([\s\S]*?)\n?\s*```/);
+  if (jsonMatch) {
+    try {
+      const parsed = JSON.parse(jsonMatch[1]);
+      return toAiEnrichment(parsed, model, generatedAt);
+    } catch {
+    }
+  }
+  try {
+    const parsed = JSON.parse(response.trim());
+    return toAiEnrichment(parsed, model, generatedAt);
+  } catch {
+  }
+  return {
+    summary: response.trim().slice(0, 500),
+    model,
+    generatedAt
+  };
+}
+var ENRICHMENT_SCHEMA = JSON.stringify({
+  type: "object",
+  properties: {
+    summary: { type: "string", description: "Concise 1-2 sentence description of what this commit accomplishes" },
+    intent: { type: "string", description: "High-level goal or motivation behind the changes" },
+    challenges: {
+      type: "array",
+      items: { type: "string" },
+      description: "Specific difficulties encountered (test failures, blocked tools, repeated edits)"
+    },
+    ruleInsights: {
+      type: "array",
+      items: { type: "string" },
+      description: "Observations about which guardian rules helped, which were too strict, or what rules could be added"
+    }
+  },
+  required: ["summary"]
+});
+function enrichEntry(entry, rawEvents, model = DEFAULT_AI_MODEL) {
+  const prompt = buildEnrichmentPrompt(entry, rawEvents);
+  return new Promise((resolve, reject) => {
+    const timeout = 2 * 60 * 1e3;
+    const claudePath = getClaudePath();
+    if (!claudePath) {
+      reject(new Error("Claude CLI not found"));
+      return;
+    }
+    const proc = spawn(claudePath, [
+      "--print",
+      "--model",
+      model,
+      "--output-format",
+      "json",
+      "--json-schema",
+      ENRICHMENT_SCHEMA,
+      "--permission-mode",
+      "bypassPermissions"
+    ], {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+    const timer = setTimeout(() => {
+      proc.kill("SIGTERM");
+      reject(new Error("AI enrichment timed out after 2 minutes"));
+    }, timeout);
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`claude CLI exited with code ${code}: ${stderr.slice(0, 500)}`));
+      } else {
+        resolve(parseEnrichmentResponse(stdout, model));
+      }
+    });
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      reject(new Error(`Failed to run claude CLI: ${err.message}`));
+    });
+  });
+}
+
+// src/commands/history.ts
+async function runHistory(args, projectDir) {
+  const branch = getHistoryBranch();
+  const subcommand = args[0];
+  switch (subcommand) {
+    case "init":
+      return await initSubcommand(projectDir);
+    case "capture":
+      return await captureSubcommand(args.slice(1), projectDir);
+    case "backfill":
+      return await backfillSubcommand(args.slice(1), projectDir);
+    case "list":
+      return listSubcommand(args.slice(1), projectDir);
+    case "show":
+      return showSubcommand(args.slice(1), projectDir);
+    case "enrich":
+      return await enrichSubcommand(args.slice(1), projectDir);
+    case "rewind":
+      return await rewindSubcommand(args.slice(1), projectDir);
+    default:
+      console.log(`
+Usage: ulpi history <subcommand>
+
+Subcommands:
+  init                    Initialize the ${branch} branch
+  capture [sha...]        Capture entries for specific commits (default: HEAD)
+  backfill [--limit N]    Backfill recent commits (default: 20)
+  list [--limit N]        List timeline entries
+  show <sha>              Show entry details
+  enrich [sha...] [--model <id>]  AI-enrich entries
+  rewind <sha>            Rewind working tree to a captured commit
+`.trim());
+  }
+}
+async function initSubcommand(projectDir) {
+  const branch = getHistoryBranch();
+  console.log(chalk.bold("\nULPI History \u2014 Initialize\n"));
+  if (historyBranchExists(projectDir)) {
+    console.log(chalk.red(`Error: ${branch} branch already exists.`));
+    console.log(chalk.dim("Use 'history capture' or 'history backfill' to add entries."));
+    return;
+  }
+  const reviewPlansDir = REVIEWS_DIR;
+  let collectReviewPlans = false;
+  if (fs2.existsSync(reviewPlansDir)) {
+    const answer = await askQuestion(
+      "ULPI Review plans detected. Include in history? (Y/n) "
+    );
+    collectReviewPlans = answer.trim().toLowerCase() !== "n";
+  }
+  const projectName = path2.basename(projectDir);
+  try {
+    initHistoryBranch(projectDir, projectName, "0.1.0");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.log(chalk.red(`Error: ${message}`));
+    return;
+  }
+  if (collectReviewPlans) {
+    try {
+      const { withWorktree, writeAndStage, commitInWorktree } = await import("./dist-RJGCUS3L.js");
+      const meta = readBranchMeta(projectDir);
+      if (meta) {
+        meta.config.collectReviewPlans = true;
+        await withWorktree(projectDir, branch, (worktreeDir) => {
+          writeAndStage(worktreeDir, "meta.json", JSON.stringify(meta, null, 2) + "\n");
+          commitInWorktree(worktreeDir, "Enable review plan collection");
+        });
+      }
+    } catch {
+    }
+  }
+  console.log(chalk.green(`\u2713 Initialized ${branch} branch`));
+  console.log(chalk.dim(`  Branch: ${branch}`));
+  console.log(chalk.dim(`  Project: ${projectName}`));
+  if (collectReviewPlans) {
+    console.log(chalk.dim("  Review plans: enabled"));
+  }
+  const installHooksAnswer = await askQuestion(
+    "Install git hooks (prepare-commit-msg, post-commit, pre-push)? (Y/n) "
+  );
+  if (installHooksAnswer.trim().toLowerCase() !== "n") {
+    try {
+      const { installGitHooks } = await import("./dist-RJGCUS3L.js");
+      const { getBinaryPath } = await import("./dist-RKOGLK7R.js");
+      const binaryPath = getBinaryPath();
+      const result = installGitHooks(projectDir, binaryPath);
+      if (result.installed.length > 0) {
+        console.log(chalk.green(`  \u2713 Installed hooks: ${result.installed.join(", ")}`));
+      }
+      if (result.skipped.length > 0) {
+        console.log(chalk.dim(`  Skipped (already installed): ${result.skipped.join(", ")}`));
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.log(chalk.yellow(`  Warning: Could not install git hooks: ${message}`));
+    }
+  }
+  console.log(chalk.dim("\nNext: run 'ulpi history backfill' to capture recent commits."));
+}
+async function captureSubcommand(args, projectDir) {
+  const branch = getHistoryBranch();
+  if (!historyBranchExists(projectDir)) {
+    console.log(chalk.red(`Error: ${branch} branch not found. Run 'history init' first.`));
+    return;
+  }
+  let shas = args.filter((a) => !a.startsWith("--"));
+  if (shas.length === 0) {
+    const head = getCurrentHead(projectDir);
+    if (!head) {
+      console.log(chalk.red("Error: Could not determine HEAD. Is this a git repository?"));
+      return;
+    }
+    shas = [head];
+  }
+  const maxDiffSize = DEFAULT_HISTORY_CONFIG.maxDiffSize;
+  for (const sha of shas) {
+    try {
+      if (entryExists(projectDir, sha)) {
+        console.log(chalk.yellow(`  Skipped ${sha.slice(0, 7)} \u2014 already captured`));
+        continue;
+      }
+      const metadata = getCommitMetadata(projectDir, sha);
+      const diffStats = getCommitDiffStats(projectDir, sha);
+      const rawDiffResult = getCommitRawDiff(projectDir, sha, maxDiffSize);
+      const guardsYaml = loadActiveGuards(projectDir);
+      const entry = {
+        version: 1,
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        commit: metadata,
+        diff: diffStats,
+        rawDiff: rawDiffResult.diff || void 0,
+        diffTruncated: rawDiffResult.truncated || void 0,
+        session: null,
+        enrichment: null,
+        reviewPlans: null
+      };
+      await writeHistoryEntry(projectDir, entry, {
+        state: null,
+        events: [],
+        guardsYaml
+      });
+      console.log(chalk.green(`  \u2713 ${metadata.shortSha}`) + chalk.dim(` ${truncate(metadata.subject, 50)}`));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.log(chalk.red(`  \u2717 ${sha.slice(0, 7)}: ${message}`));
+    }
+  }
+}
+async function backfillSubcommand(args, projectDir) {
+  const branch = getHistoryBranch();
+  if (!historyBranchExists(projectDir)) {
+    console.log(chalk.red(`Error: ${branch} branch not found. Run 'history init' first.`));
+    return;
+  }
+  const limitFlag = args.find((a) => a.startsWith("--limit"));
+  let limit = 20;
+  if (limitFlag) {
+    const idx = args.indexOf(limitFlag);
+    if (limitFlag.includes("=")) {
+      limit = parseInt(limitFlag.split("=")[1], 10) || 20;
+    } else if (args[idx + 1]) {
+      limit = parseInt(args[idx + 1], 10) || 20;
+    }
+  }
+  if (args[0] && !args[0].startsWith("--") && /^\d+$/.test(args[0])) {
+    limit = parseInt(args[0], 10);
+  }
+  console.log(chalk.bold(`
+ULPI History \u2014 Backfill (last ${limit} commits)
+`));
+  const commits = listRecentCommits(projectDir, limit);
+  if (commits.length === 0) {
+    console.log(chalk.yellow("No commits found."));
+    return;
+  }
+  const meta = readBranchMeta(projectDir);
+  const config = meta?.config ?? DEFAULT_HISTORY_CONFIG;
+  const maxDiffSize = config.maxDiffSize;
+  let captured = 0;
+  let skipped = 0;
+  let withSession = 0;
+  let withReview = 0;
+  for (const sha of commits) {
+    if (entryExists(projectDir, sha)) {
+      skipped++;
+      continue;
+    }
+    try {
+      const metadata = getCommitMetadata(projectDir, sha);
+      const diffStats = getCommitDiffStats(projectDir, sha);
+      const rawDiffResult = getCommitRawDiff(projectDir, sha, maxDiffSize);
+      const guardsYaml = loadActiveGuards(projectDir);
+      let sessionSummary = null;
+      let sessionState = null;
+      let sessionEvents = [];
+      const sessionMatch = findSessionForCommit(projectDir, metadata.authorDate);
+      if (sessionMatch) {
+        sessionSummary = buildSessionSummary(sessionMatch.state, sessionMatch.events);
+        sessionState = sessionMatch.state;
+        sessionEvents = sessionMatch.events;
+        withSession++;
+      }
+      let reviewSnapshots = null;
+      let reviewRawData;
+      if (config.collectReviewPlans) {
+        const sessionStart = sessionState?.startedAt;
+        const reviewResult = findReviewPlansForCommit(metadata.authorDate, sessionStart, projectDir);
+        if (reviewResult) {
+          reviewSnapshots = reviewResult.snapshots;
+          reviewRawData = reviewResult.rawData;
+          withReview++;
+        }
+      }
+      const entry = {
+        version: 1,
+        capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        commit: metadata,
+        diff: diffStats,
+        rawDiff: rawDiffResult.diff || void 0,
+        diffTruncated: rawDiffResult.truncated || void 0,
+        session: sessionSummary,
+        enrichment: null,
+        reviewPlans: reviewSnapshots
+      };
+      await writeHistoryEntry(projectDir, entry, {
+        state: sessionState,
+        events: sessionEvents,
+        guardsYaml,
+        reviewPlans: reviewRawData
+      });
+      const tags = [];
+      if (sessionSummary) tags.push(chalk.cyan("session"));
+      if (reviewSnapshots) tags.push(chalk.magenta("review"));
+      const tagStr = tags.length > 0 ? ` [${tags.join(", ")}]` : "";
+      console.log(
+        chalk.green(`  \u2713 ${metadata.shortSha}`) + chalk.dim(` ${truncate(metadata.subject, 40)}`) + tagStr
+      );
+      captured++;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.log(chalk.red(`  \u2717 ${sha.slice(0, 7)}: ${message}`));
+    }
+  }
+  console.log("");
+  console.log(chalk.bold("Summary:"));
+  console.log(`  Captured: ${chalk.green(String(captured))}`);
+  if (skipped > 0) console.log(`  Skipped (already captured): ${chalk.dim(String(skipped))}`);
+  if (withSession > 0) console.log(`  With session data: ${chalk.cyan(String(withSession))}`);
+  if (withReview > 0) console.log(`  With review plans: ${chalk.magenta(String(withReview))}`);
+  console.log(`  Git-only (no session): ${chalk.dim(String(captured - withSession))}`);
+}
+function listSubcommand(args, projectDir) {
+  const branch = getHistoryBranch();
+  if (!historyBranchExists(projectDir)) {
+    console.log(chalk.red(`Error: ${branch} branch not found. Run 'history init' first.`));
+    return;
+  }
+  const limitFlag = args.find((a) => a.startsWith("--limit"));
+  let limit = 30;
+  if (limitFlag) {
+    const idx = args.indexOf(limitFlag);
+    if (limitFlag.includes("=")) {
+      limit = parseInt(limitFlag.split("=")[1], 10) || 30;
+    } else if (args[idx + 1]) {
+      limit = parseInt(args[idx + 1], 10) || 30;
+    }
+  }
+  const timeline = readTimeline(projectDir);
+  if (!timeline || timeline.entries.length === 0) {
+    console.log(chalk.yellow("No history entries found. Run 'history capture' or 'history backfill'."));
+    return;
+  }
+  const entries = timeline.entries.slice(0, limit);
+  console.log(chalk.bold("\nULPI History Timeline\n"));
+  console.log(
+    chalk.dim("  Date       ") + chalk.dim("SHA     ") + chalk.dim("Branch          ") + chalk.dim("Subject                                  ") + chalk.dim("Ses ") + chalk.dim("Rev ") + chalk.dim("AI")
+  );
+  console.log(chalk.dim("  " + "-".repeat(95)));
+  for (const e of entries) {
+    const date = formatShortDate(e.date);
+    const sha = chalk.yellow(e.shortSha);
+    const branch2 = padRight(e.branch === "unknown" ? "" : e.branch, 16).slice(0, 16);
+    const subject = padRight(truncate(e.subject, 40), 40);
+    const session = e.hasSession ? chalk.green(" Y  ") : chalk.dim(" -  ");
+    const review = e.hasReviewPlans ? chalk.green(" Y  ") : chalk.dim(" -  ");
+    const ai = e.hasEnrichment ? chalk.green(" Y") : chalk.dim(" -");
+    console.log(`  ${date}  ${sha}  ${chalk.dim(branch2)}  ${subject}  ${session}${review}${ai}`);
+  }
+  if (timeline.entries.length > limit) {
+    console.log(chalk.dim(`
+  Showing ${limit} of ${timeline.entries.length} entries. Use --limit to see more.`));
+  }
+  console.log("");
+}
+function showSubcommand(args, projectDir) {
+  const branch = getHistoryBranch();
+  const sha = args[0];
+  if (!sha) {
+    console.log(chalk.red("Usage: ulpi history show <sha>"));
+    return;
+  }
+  if (!historyBranchExists(projectDir)) {
+    console.log(chalk.red(`Error: ${branch} branch not found. Run 'history init' first.`));
+    return;
+  }
+  const entry = readHistoryEntry(projectDir, sha);
+  if (!entry) {
+    console.log(chalk.red(`Entry not found for SHA: ${sha}`));
+    console.log(chalk.dim("Use 'history list' to see available entries."));
+    return;
+  }
+  console.log(chalk.bold("\nCommit"));
+  console.log(`  SHA:     ${chalk.yellow(entry.commit.sha)}`);
+  console.log(`  Subject: ${entry.commit.subject}`);
+  if (entry.commit.message !== entry.commit.subject) {
+    console.log(`  Message: ${entry.commit.message}`);
+  }
+  console.log(`  Author:  ${entry.commit.authorName} <${entry.commit.authorEmail}>`);
+  console.log(`  Date:    ${entry.commit.authorDate}`);
+  console.log(`  Branch:  ${entry.commit.branch}`);
+  console.log(chalk.bold("\nDiff Stats"));
+  console.log(`  Files changed: ${entry.diff.filesChanged}`);
+  console.log(`  Insertions:    ${chalk.green("+" + entry.diff.insertions)}`);
+  console.log(`  Deletions:     ${chalk.red("-" + entry.diff.deletions)}`);
+  if (entry.diff.files.length > 0) {
+    console.log(chalk.dim("  Files:"));
+    for (const f of entry.diff.files.slice(0, 15)) {
+      const statusColor = f.status === "added" ? chalk.green : f.status === "deleted" ? chalk.red : f.status === "renamed" ? chalk.blue : chalk.dim;
+      console.log(`    ${statusColor(f.status.padEnd(8))} ${f.path} (+${f.additions}/-${f.deletions})`);
+    }
+    if (entry.diff.files.length > 15) {
+      console.log(chalk.dim(`    ... and ${entry.diff.files.length - 15} more files`));
+    }
+  }
+  if (entry.session) {
+    const s = entry.session;
+    console.log(chalk.bold("\nSession"));
+    console.log(`  ID:             ${s.sessionId}${s.sessionName ? ` (${s.sessionName})` : ""}`);
+    console.log(`  Total events:   ${s.totalEvents}`);
+    console.log(`  Rules enforced: ${s.stats.rulesEnforced}`);
+    console.log(`  Blocked:        ${s.stats.actionsBlocked}`);
+    console.log(`  Auto-approved:  ${s.stats.autoActionsRun}`);
+    console.log(`  Files:          ${s.stats.filesRead} read, ${s.stats.filesWritten} written, ${s.stats.filesDeleted} deleted`);
+    console.log(`  Commands:       ${s.stats.commandsRun}`);
+    console.log(`  Tests:          ${s.stats.testsRun ? s.stats.testsPassed ? chalk.green("passed") : chalk.red("failed") : chalk.dim("not run")}`);
+    console.log(`  Lint:           ${s.stats.lintRun ? chalk.green("run") : chalk.dim("not run")}`);
+    console.log(`  Build:          ${s.stats.buildRun ? chalk.green("run") : chalk.dim("not run")}`);
+    if (s.blockedTools.length > 0) {
+      console.log(`  Blocked tools:  ${chalk.red(s.blockedTools.join(", "))}`);
+    }
+    if (s.preconditionsFired.length > 0) {
+      console.log(`  Preconditions:  ${chalk.yellow(s.preconditionsFired.join(", "))}`);
+    }
+  } else {
+    console.log(chalk.dim("\nSession: none (git-only capture)"));
+  }
+  if (entry.reviewPlans && entry.reviewPlans.length > 0) {
+    console.log(chalk.bold("\nReview Plans"));
+    for (const plan of entry.reviewPlans) {
+      const decision = plan.version.decision ? plan.version.decision.behavior === "allow" ? chalk.green("approved") : chalk.red("denied") : chalk.dim("pending");
+      console.log(`  ${chalk.magenta(plan.title)} \u2014 ${decision}`);
+    }
+  }
+  if (entry.enrichment) {
+    const e = entry.enrichment;
+    console.log(chalk.bold("\nAI Enrichment") + chalk.dim(` (${e.model}, ${e.generatedAt})`));
+    console.log(`  Summary: ${e.summary}`);
+    if (e.intent) {
+      console.log(`  Intent:  ${e.intent}`);
+    }
+    if (e.challenges && e.challenges.length > 0) {
+      console.log(chalk.yellow("  Challenges:"));
+      for (const c of e.challenges) {
+        console.log(chalk.yellow(`    - ${c}`));
+      }
+    }
+    if (e.ruleInsights && e.ruleInsights.length > 0) {
+      console.log(chalk.cyan("  Rule Insights:"));
+      for (const r of e.ruleInsights) {
+        console.log(chalk.cyan(`    - ${r}`));
+      }
+    }
+  }
+  console.log("");
+}
+async function enrichSubcommand(args, projectDir) {
+  const branch = getHistoryBranch();
+  if (!historyBranchExists(projectDir)) {
+    console.log(chalk.red(`Error: ${branch} branch not found. Run 'history init' first.`));
+    return;
+  }
+  if (!isClaudeCliAvailable()) {
+    console.log(chalk.red("Error: Claude CLI not found on PATH."));
+    console.log(chalk.dim("Install it from: https://docs.anthropic.com/en/docs/claude-cli"));
+    return;
+  }
+  const modelIdx = args.findIndex((a) => a === "--model");
+  let model = DEFAULT_AI_MODEL;
+  if (modelIdx !== -1 && args[modelIdx + 1]) {
+    model = args[modelIdx + 1];
+  }
+  const modelEqFlag = args.find((a) => a.startsWith("--model="));
+  if (modelEqFlag) {
+    model = modelEqFlag.split("=")[1];
+  }
+  let shas = args.filter((a) => !a.startsWith("--") && (modelIdx === -1 || args.indexOf(a) !== modelIdx + 1));
+  if (shas.length === 0) {
+    const timeline = readTimeline(projectDir);
+    if (!timeline || timeline.entries.length === 0) {
+      console.log(chalk.yellow("No history entries found."));
+      return;
+    }
+    shas = timeline.entries.filter((e) => !e.hasEnrichment).map((e) => e.sha);
+    if (shas.length === 0) {
+      console.log(chalk.green("All entries are already enriched."));
+      return;
+    }
+    console.log(chalk.bold(`
+ULPI History \u2014 AI Enrichment (${shas.length} entries, model: ${model})
+`));
+  } else {
+    console.log(chalk.bold(`
+ULPI History \u2014 AI Enrichment (model: ${model})
+`));
+  }
+  let enriched = 0;
+  let failed = 0;
+  for (const sha of shas) {
+    const entry = readHistoryEntry(projectDir, sha);
+    if (!entry) {
+      console.log(chalk.yellow(`  Skipped ${sha.slice(0, 7)} \u2014 entry not found`));
+      continue;
+    }
+    let rawEvents = [];
+    const rawData = readEntryRawData(projectDir, sha);
+    if (rawData.events) {
+      try {
+        rawEvents = rawData.events.split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+      } catch {
+      }
+    }
+    try {
+      process.stdout.write(chalk.dim(`  Enriching ${entry.commit.shortSha}...`));
+      const enrichment = await enrichEntry(entry, rawEvents, model);
+      await updateEntryEnrichment(projectDir, sha, enrichment);
+      console.log(chalk.green(" done"));
+      enriched++;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.log(chalk.red(` failed: ${message}`));
+      failed++;
+    }
+  }
+  console.log("");
+  console.log(chalk.bold("Summary:"));
+  console.log(`  Enriched: ${chalk.green(String(enriched))}`);
+  if (failed > 0) console.log(`  Failed:   ${chalk.red(String(failed))}`);
+}
+async function rewindSubcommand(args, projectDir) {
+  const branch = getHistoryBranch();
+  const sha = args[0];
+  if (!sha) {
+    console.log(chalk.red("Usage: ulpi history rewind <sha>"));
+    return;
+  }
+  if (!historyBranchExists(projectDir)) {
+    console.log(chalk.red(`Error: ${branch} branch not found. Run 'history init' first.`));
+    return;
+  }
+  const { execFileSync: execFileSync2 } = await import("child_process");
+  try {
+    execFileSync2("git", ["diff", "--quiet"], {
+      cwd: projectDir,
+      encoding: "utf-8",
+      timeout: 5e3
+    });
+    execFileSync2("git", ["diff", "--cached", "--quiet"], {
+      cwd: projectDir,
+      encoding: "utf-8",
+      timeout: 5e3
+    });
+  } catch {
+    console.log(chalk.red("Error: You have uncommitted changes."));
+    console.log(chalk.dim("Commit or stash your changes before rewinding."));
+    return;
+  }
+  const timeline = readTimeline(projectDir);
+  if (!timeline) {
+    console.log(chalk.red("No timeline found. Run 'ulpi history backfill' first."));
+    return;
+  }
+  const match = timeline.entries.find(
+    (e) => e.sha === sha || e.shortSha === sha || e.sha.startsWith(sha)
+  );
+  if (!match) {
+    console.log(chalk.red(`No history entry found for SHA: ${sha}`));
+    return;
+  }
+  console.log(chalk.bold(`
+Rewind to: ${match.shortSha} -- ${match.subject}`));
+  console.log(chalk.dim(`Date: ${match.date}`));
+  console.log(chalk.dim(`Branch: ${match.branch}`));
+  console.log(chalk.dim(`Files changed: ${match.filesChanged}`));
+  console.log("");
+  try {
+    const diffStat = execFileSync2("git", ["diff", "--stat", `HEAD...${match.sha}`], {
+      cwd: projectDir,
+      encoding: "utf-8",
+      timeout: 1e4
+    }).trim();
+    if (diffStat) {
+      console.log(chalk.dim("Changes to apply:"));
+      console.log(diffStat);
+      console.log("");
+    }
+  } catch {
+  }
+  const entry = readHistoryEntry(projectDir, match.sha);
+  if (entry?.transcriptSize && entry.transcriptSize > 0) {
+    console.log(chalk.dim(`Transcript available (${(entry.transcriptSize / 1024).toFixed(1)} KB)`));
+  }
+  const answer = await askQuestion(chalk.yellow("This will reset your working tree. Continue? (y/N) "));
+  if (answer.trim().toLowerCase() !== "y") {
+    console.log(chalk.dim("Rewind cancelled."));
+    return;
+  }
+  try {
+    execFileSync2("git", ["reset", "--hard", match.sha], {
+      cwd: projectDir,
+      encoding: "utf-8",
+      timeout: 1e4
+    });
+    console.log(chalk.green(`
+\u2713 Rewound to ${match.shortSha}`));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.log(chalk.red(`Rewind failed: ${message}`));
+  }
+}
+function askQuestion(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 3) + "...";
+}
+function padRight(str, len) {
+  return str.length >= len ? str : str + " ".repeat(len - str.length);
+}
+function formatShortDate(iso) {
+  try {
+    const d = new Date(iso);
+    const month = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${d.getFullYear()}-${month}-${day}`;
+  } catch {
+    return iso.slice(0, 10);
+  }
+}
+export {
+  runHistory
+};