preflight-dev 3.1.0

package/src/lib/git-extractor.ts

@@ -0,0 +1,137 @@
+/**
+ * git-extractor.ts — Extract git commit history as timeline events.
+ */
+import { execSync } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import type { TimelineEvent } from "./session-parser.js";
+
+// In git --format, %% produces a literal %. So we use %%…%% in the format
+// string, but the actual output contains %…%. We need separate constants.
+const COMMIT_SEP_FMT = "%%COMMIT_START%%";
+const COMMIT_END_FMT = "%%COMMIT_END%%";
+const FIELD_SEP_FMT = "%%F%%";
+// What appears in the output after git processes the format:
+const COMMIT_SEP = "%COMMIT_START%";
+const COMMIT_END = "%COMMIT_END%";
+const FIELD_SEP = "%F%";
+
+/**
+ * Extract git commits as TimelineEvent[].
+ */
+export function extractGitHistory(
+  projectDir: string,
+  opts?: { since?: Date; branch?: string; maxCount?: number },
+): TimelineEvent[] {
+  if (!existsSync(join(projectDir, ".git"))) {
+    // Try bare dir or parent — but most likely just not a repo
+    try {
+      execSync("git rev-parse --git-dir", { cwd: projectDir, stdio: "pipe" });
+    } catch {
+      return [];
+    }
+  }
+
+  const args: string[] = ["git", "log"];
+
+  if (opts?.branch) {
+    args.push(opts.branch);
+  } else {
+    args.push("--all");
+  }
+
+  const maxCount = opts?.maxCount ?? 10000;
+  args.push(`--max-count=${maxCount}`);
+
+  if (opts?.since) {
+    args.push(`--since=${opts.since.toISOString()}`);
+  }
+
+  // Format: structured fields separated by known delimiters
+  args.push(
+    `--format=${COMMIT_SEP_FMT}${FIELD_SEP_FMT}%H${FIELD_SEP_FMT}%aI${FIELD_SEP_FMT}%an${FIELD_SEP_FMT}%s${FIELD_SEP_FMT}%b${FIELD_SEP_FMT}${COMMIT_END_FMT}`,
+    "--stat",
+  );
+
+  let output: string;
+  try {
+    output = execSync(args.join(" "), {
+      cwd: projectDir,
+      encoding: "utf-8",
+      maxBuffer: 50 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (err: any) {
+    // No commits or other git error
+    if (err.stdout) output = err.stdout;
+    else return [];
+  }
+
+  if (!output.trim()) return [];
+
+  const projectName = projectDir.split("/").filter(Boolean).pop() ?? projectDir;
+  return parseGitOutput(output, projectDir, projectName);
+}
+
+// ── Internal ───────────────────────────────────────────────────────────────
+
+function parseGitOutput(raw: string, project: string, projectName: string): TimelineEvent[] {
+  const events: TimelineEvent[] = [];
+
+  // Split on COMMIT_START markers
+  const blocks = raw.split(COMMIT_SEP).filter((b) => b.includes(COMMIT_END));
+
+  for (const block of blocks) {
+    try {
+      const endIdx = block.indexOf(COMMIT_END);
+      const headerPart = block.slice(0, endIdx);
+      const statPart = block.slice(endIdx + COMMIT_END.length).trim();
+
+      const fields = headerPart.split(FIELD_SEP);
+      // fields: ["", hash, date, author, subject, body, ""]
+      const hash = fields[1]?.trim() ?? "";
+      const dateStr = fields[2]?.trim() ?? "";
+      const author = fields[3]?.trim() ?? "";
+      const subject = fields[4]?.trim() ?? "";
+      const body = fields[5]?.trim() ?? "";
+
+      if (!hash) continue;
+
+      const commitMsg = body ? `${subject}\n\n${body}` : subject;
+      const content = statPart ? `${commitMsg}\n\n${statPart}` : commitMsg;
+
+      // Parse diffstat summary (last line like " 3 files changed, 10 insertions(+), 2 deletions(-)")
+      const statMatch = statPart.match(
+        /(\d+) files? changed(?:,\s*(\d+) insertions?\(\+\))?(?:,\s*(\d+) deletions?\(-\))?/,
+      );
+
+      const metadata = JSON.stringify({
+        hash,
+        author,
+        files_changed: statMatch ? parseInt(statMatch[1], 10) : 0,
+        insertions: statMatch?.[2] ? parseInt(statMatch[2], 10) : 0,
+        deletions: statMatch?.[3] ? parseInt(statMatch[3], 10) : 0,
+      });
+
+      events.push({
+        id: randomUUID(),
+        timestamp: new Date(dateStr).toISOString(),
+        type: "commit",
+        project,
+        project_name: projectName,
+        branch: "all",
+        session_id: "",
+        source_file: `git:${hash}`,
+        source_line: 0,
+        content,
+        content_preview: subject.length > 120 ? subject.slice(0, 120) + "…" : subject,
+        metadata,
+      });
+    } catch (err) {
+      process.stderr.write(`[git-extractor] failed to parse commit block: ${err}\n`);
+    }
+  }
+
+  return events;
+}

package/src/lib/git.ts

@@ -0,0 +1,89 @@
+import { execFileSync } from "child_process";
+import { PROJECT_DIR } from "./files.js";
+import type { RunError } from "../types.js";
+
+/**
+ * Run a git command safely using execFileSync (no shell injection).
+ * Accepts an array of args (preferred) or a string (split on whitespace for backward compat).
+ * Returns stdout on success. On failure, returns a descriptive error string.
+ */
+export function run(argsOrCmd: string | string[], opts: { timeout?: number } = {}): string {
+  const args = typeof argsOrCmd === "string" ? argsOrCmd.split(/\s+/) : argsOrCmd;
+  try {
+    return execFileSync("git", args, {
+      cwd: PROJECT_DIR,
+      encoding: "utf-8",
+      timeout: opts.timeout || 10000,
+      maxBuffer: 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch (e: any) {
+    const timedOut = e.killed === true || e.signal === "SIGTERM";
+    if (timedOut) {
+      return `[timed out after ${opts.timeout || 10000}ms]`;
+    }
+    // Return stderr/stdout if available, otherwise the error message
+    const output = e.stdout?.trim() || e.stderr?.trim();
+    if (output) return output;
+    if (e.code === "ENOENT") return "[git not found]";
+    return `[command failed: git ${args.join(" ")} (exit ${e.status ?? "?"})]`;
+  }
+}
+
+/** Convenience: run a raw command string (split on spaces). Only for simple, known-safe commands. */
+function gitCmd(cmdStr: string, opts?: { timeout?: number }): string {
+  return run(cmdStr.split(/\s+/), opts);
+}
+
+/** Get the current branch name. */
+export function getBranch(): string {
+  return run(["branch", "--show-current"]);
+}
+
+/** Get short git status. */
+export function getStatus(): string {
+  return run(["status", "--short"]);
+}
+
+/** Get recent commits as oneline. */
+export function getRecentCommits(count = 5): string {
+  return run(["log", "--oneline", `-${count}`]);
+}
+
+/** Get the last commit as oneline. */
+export function getLastCommit(): string {
+  return run(["log", "--oneline", "-1"]);
+}
+
+/** Get the last commit timestamp. */
+export function getLastCommitTime(): string {
+  return run(["log", "-1", "--format=%ci"]);
+}
+
+/**
+ * Get files changed since `ref`. Falls back to HEAD~1, then "no commits".
+ * Uses explicit fallback steps instead of shell chaining.
+ */
+export function getDiffFiles(ref = "HEAD~3"): string {
+  const result = run(["diff", "--name-only", ref]);
+  if (!result.startsWith("[")) return result;
+  const fallback = run(["diff", "--name-only", "HEAD~1"]);
+  if (!fallback.startsWith("[")) return fallback;
+  return "no commits";
+}
+
+/** Get staged files. */
+export function getStagedFiles(): string {
+  return run(["diff", "--staged", "--name-only"]);
+}
+
+/**
+ * Get diff stat since `ref`. Falls back to HEAD~3.
+ */
+export function getDiffStat(ref = "HEAD~5"): string {
+  const result = run(["diff", ref, "--stat"]);
+  if (!result.startsWith("[")) return result;
+  const fallback = run(["diff", "HEAD~3", "--stat"]);
+  if (!fallback.startsWith("[")) return fallback;
+  return "no diff stats available";
+}

package/src/lib/session-parser.ts

@@ -0,0 +1,325 @@
+/**
+ * session-parser.ts — Parse Claude Code session JSONL files into timeline events.
+ */
+import { readFileSync, readdirSync, statSync, existsSync, createReadStream } from "fs";
+import { join, basename } from "path";
+import { homedir } from "os";
+import { randomUUID } from "crypto";
+import { createInterface } from "readline";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface TimelineEvent {
+  id: string;
+  timestamp: string;
+  type: string;
+  project: string;
+  project_name: string;
+  branch: string;
+  session_id: string;
+  source_file: string;
+  source_line: number;
+  content: string;
+  content_preview: string;
+  metadata: string;
+}
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+const LARGE_FILE_THRESHOLD = 10 * 1024 * 1024; // 10 MB
+
+const CORRECTION_PATTERNS = [
+  /\bno\b/i, /\bwrong\b/i, /\bnot that\b/i, /\bi meant\b/i,
+  /\bactually\b/i, /\binstead\b/i, /\bundo\b/i,
+];
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b: any) => b.type === "text" && typeof b.text === "string")
+      .map((b: any) => b.text)
+      .join("\n");
+  }
+  return "";
+}
+
+function extractToolUseBlocks(content: unknown): any[] {
+  if (!Array.isArray(content)) return [];
+  return content.filter((b: any) => b.type === "tool_use");
+}
+
+function normalizeTimestamp(ts: unknown, fallback: string): string {
+  if (!ts) return fallback;
+  if (typeof ts === "string") {
+    const d = new Date(ts);
+    return isNaN(d.getTime()) ? fallback : d.toISOString();
+  }
+  if (typeof ts === "number") {
+    // epoch seconds or ms
+    const d = new Date(ts < 1e12 ? ts * 1000 : ts);
+    return isNaN(d.getTime()) ? fallback : d.toISOString();
+  }
+  return fallback;
+}
+
+function preview(text: string, max = 120): string {
+  const line = text.split("\n")[0] ?? "";
+  return line.length > max ? line.slice(0, max) + "…" : line;
+}
+
+function isCorrection(text: string): boolean {
+  return CORRECTION_PATTERNS.some((p) => p.test(text));
+}
+
+function makeEvent(
+  partial: Omit<TimelineEvent, "id" | "content_preview"> & { content_preview?: string },
+): TimelineEvent {
+  return {
+    id: randomUUID(),
+    content_preview: partial.content_preview ?? preview(partial.content),
+    ...partial,
+  } as TimelineEvent;
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Discover all Claude project session directories.
+ */
+export function findSessionDirs(): { project: string; projectName: string; sessionDir: string }[] {
+  if (!existsSync(CLAUDE_PROJECTS_DIR)) return [];
+  const results: { project: string; projectName: string; sessionDir: string }[] = [];
+  for (const entry of readdirSync(CLAUDE_PROJECTS_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const sessionDir = join(CLAUDE_PROJECTS_DIR, entry.name);
+    // Decode project path: leading `-` → `/`, internal `-` are ambiguous
+    // but the last path segment is a reasonable "name"
+    const decoded = entry.name.replace(/^-/, "/").replace(/-/g, "/");
+    const projectName = decoded.split("/").filter(Boolean).pop() ?? entry.name;
+    results.push({ project: decoded, projectName, sessionDir });
+  }
+  return results;
+}
+
+/**
+ * List JSONL session files in a project directory (including subagent files).
+ */
+export function findSessionFiles(
+  projectDir: string,
+): { sessionId: string; path: string; mtime: Date }[] {
+  if (!existsSync(projectDir)) return [];
+  const results: { sessionId: string; path: string; mtime: Date }[] = [];
+
+  for (const entry of readdirSync(projectDir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      const p = join(projectDir, entry.name);
+      results.push({
+        sessionId: basename(entry.name, ".jsonl"),
+        path: p,
+        mtime: statSync(p).mtime,
+      });
+    }
+    // Check for subagent dirs: <uuid>/subagents/<sub-uuid>.jsonl
+    if (entry.isDirectory()) {
+      const subDir = join(projectDir, entry.name, "subagents");
+      if (existsSync(subDir)) {
+        for (const sub of readdirSync(subDir)) {
+          if (sub.endsWith(".jsonl")) {
+            const p = join(subDir, sub);
+            results.push({
+              sessionId: basename(sub, ".jsonl"),
+              path: p,
+              mtime: statSync(p).mtime,
+            });
+          }
+        }
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Parse a single JSONL session file into timeline events.
+ * For files >10MB, streams line-by-line.
+ */
+export function parseSession(
+  filePath: string,
+  project: string,
+  projectName: string,
+): TimelineEvent[] {
+  const stat = statSync(filePath);
+  const fallbackTs = stat.mtime.toISOString();
+
+  if (stat.size > LARGE_FILE_THRESHOLD) {
+    // Return empty — caller should use parseSessionAsync for large files
+    // But for sync API compat, read anyway with a buffer
+  }
+
+  const lines = readFileSync(filePath, "utf-8").split("\n");
+  return parseLinesSync(lines, filePath, project, projectName, fallbackTs);
+}
+
+/**
+ * Async streaming parser for large files.
+ */
+export async function parseSessionAsync(
+  filePath: string,
+  project: string,
+  projectName: string,
+): Promise<TimelineEvent[]> {
+  const stat = statSync(filePath);
+  const fallbackTs = stat.mtime.toISOString();
+  const events: TimelineEvent[] = [];
+  let branch = "";
+  let sessionId = basename(filePath, ".jsonl");
+  let lastType = "";
+  let lineNum = 0;
+
+  const rl = createInterface({ input: createReadStream(filePath, "utf-8"), crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    lineNum++;
+    if (!line.trim()) continue;
+    let obj: any;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      process.stderr.write(`[session-parser] malformed line ${lineNum} in ${filePath}\n`);
+      continue;
+    }
+    const evts = processRecord(obj, filePath, project, projectName, branch, sessionId, fallbackTs, lineNum, lastType);
+    if (obj.type === "summary") {
+      branch = obj.gitBranch ?? "";
+      if (obj.sessionId) sessionId = obj.sessionId;
+    }
+    if (obj.type === "user" || obj.type === "assistant") lastType = obj.type;
+    events.push(...evts);
+  }
+  return events;
+}
+
+// ── Internal ───────────────────────────────────────────────────────────────
+
+function parseLinesSync(
+  lines: string[],
+  filePath: string,
+  project: string,
+  projectName: string,
+  fallbackTs: string,
+): TimelineEvent[] {
+  const events: TimelineEvent[] = [];
+  let branch = "";
+  let sessionId = basename(filePath, ".jsonl");
+  let lastType = "";
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let obj: any;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      process.stderr.write(`[session-parser] malformed line ${i + 1} in ${filePath}\n`);
+      continue;
+    }
+
+    if (obj.type === "summary") {
+      branch = obj.gitBranch ?? "";
+      if (obj.sessionId) sessionId = obj.sessionId;
+      continue;
+    }
+
+    const evts = processRecord(obj, filePath, project, projectName, branch, sessionId, fallbackTs, i + 1, lastType);
+    if (obj.type === "user" || obj.type === "assistant") lastType = obj.type;
+    events.push(...evts);
+  }
+  return events;
+}
+
+function processRecord(
+  obj: any,
+  filePath: string,
+  project: string,
+  projectName: string,
+  branch: string,
+  sessionId: string,
+  fallbackTs: string,
+  lineNum: number,
+  lastType: string,
+): TimelineEvent[] {
+  const ts = normalizeTimestamp(obj.timestamp, fallbackTs);
+  const base = { project, project_name: projectName, branch, session_id: sessionId, source_file: filePath, source_line: lineNum };
+  const events: TimelineEvent[] = [];
+
+  if (obj.type === "user") {
+    const text = extractText(obj.message?.content);
+    if (!text) return events;
+    const isCorr = lastType === "assistant" && isCorrection(text);
+    events.push(makeEvent({ ...base, timestamp: ts, type: isCorr ? "correction" : "prompt", content: text, metadata: "{}" }));
+  } else if (obj.type === "assistant") {
+    const content = obj.message?.content;
+    const text = extractText(content);
+    if (text) {
+      events.push(makeEvent({ ...base, timestamp: ts, type: "assistant", content: text, metadata: JSON.stringify({ model: obj.model ?? "" }) }));
+    }
+    for (const tool of extractToolUseBlocks(content)) {
+      const name: string = tool.name ?? "unknown";
+      const argsStr = typeof tool.input === "string" ? tool.input : JSON.stringify(tool.input ?? {});
+      const isSub = name === "Task" || name === "dispatch_agent";
+      events.push(makeEvent({
+        ...base,
+        timestamp: ts,
+        type: isSub ? "sub_agent_spawn" : "tool_call",
+        content: `${name}: ${argsStr.slice(0, 100)}`,
+        metadata: JSON.stringify({ tool: name }),
+      }));
+    }
+  } else if (obj.type === "tool_result") {
+    const isErr = obj.is_error === true || (typeof obj.content === "string" && /stderr/i.test(obj.content));
+    if (isErr) {
+      const text = extractText(obj.content) || JSON.stringify(obj.content ?? "").slice(0, 200);
+      events.push(makeEvent({ ...base, timestamp: ts, type: "error", content: text, metadata: JSON.stringify({ tool_use_id: obj.tool_use_id ?? "" }) }));
+    }
+  } else if (obj.type === "system") {
+    const text = extractText(obj.message?.content ?? obj.content ?? "");
+    if (/compact/i.test(text) || obj.subtype === "compaction") {
+      events.push(makeEvent({ ...base, timestamp: ts, type: "compaction", content: text || "context compacted", metadata: "{}" }));
+    }
+  }
+
+  return events;
+}
+
+/**
+ * Parse all sessions for a project directory, optionally filtering by mtime.
+ */
+export function parseAllSessions(
+  projectDir: string,
+  opts?: { since?: Date },
+): TimelineEvent[] {
+  const files = findSessionFiles(projectDir);
+  const { project, projectName } = inferProject(projectDir);
+  const events: TimelineEvent[] = [];
+
+  for (const f of files) {
+    if (opts?.since && f.mtime < opts.since) continue;
+    try {
+      events.push(...parseSession(f.path, project, projectName));
+    } catch (err) {
+      process.stderr.write(`[session-parser] failed to parse ${f.path}: ${err}\n`);
+    }
+  }
+  return events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}
+
+function inferProject(projectDir: string): { project: string; projectName: string } {
+  const dir = basename(projectDir);
+  const decoded = dir.replace(/^-/, "/").replace(/-/g, "/");
+  const projectName = decoded.split("/").filter(Boolean).pop() ?? dir;
+  return { project: decoded, projectName };
+}

package/src/lib/state.ts

@@ -0,0 +1,86 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, statSync, renameSync } from "fs";
+import { join } from "path";
+import { PROJECT_DIR } from "./files.js";
+
+export const STATE_DIR = join(PROJECT_DIR, ".claude", "preflight-state");
+
+/** Max log file size in bytes (5 MB). Triggers rotation. */
+const MAX_LOG_SIZE = 5 * 1024 * 1024;
+
+/** Lazily ensures the state directory exists. Called before any write. */
+function ensureStateDir(): void {
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Load a JSON state file by name (without extension).
+ * Returns empty object if missing or corrupt.
+ */
+export function loadState(name: string): Record<string, any> {
+  const p = join(STATE_DIR, `${name}.json`);
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save a JSON state file by name (without extension).
+ */
+export function saveState(name: string, data: Record<string, any>): void {
+  ensureStateDir();
+  writeFileSync(join(STATE_DIR, `${name}.json`), JSON.stringify(data, null, 2));
+}
+
+/**
+ * Append a JSONL entry to a log file. Rotates if file exceeds MAX_LOG_SIZE.
+ */
+export function appendLog(filename: string, entry: Record<string, any>): void {
+  ensureStateDir();
+  const logFile = join(STATE_DIR, filename);
+
+  // Rotate if too large
+  if (existsSync(logFile)) {
+    try {
+      const size = statSync(logFile).size;
+      if (size > MAX_LOG_SIZE) {
+        const backup = logFile + ".old";
+        // Keep only one backup; overwrite previous
+        renameSync(logFile, backup);
+      }
+    } catch { /* stat/rename failure is non-fatal */ }
+  }
+
+  appendFileSync(logFile, JSON.stringify(entry) + "\n");
+}
+
+/**
+ * Read a JSONL log file. Pass `lastN` to only return the last N entries
+ * (still reads the file, but avoids allocating all parsed objects).
+ */
+export function readLog(filename: string, lastN?: number): Record<string, any>[] {
+  const logFile = join(STATE_DIR, filename);
+  if (!existsSync(logFile)) return [];
+  try {
+    const raw = readFileSync(logFile, "utf-8").trim();
+    if (!raw) return [];
+    const lines = raw.split("\n");
+    const subset = lastN != null && lastN > 0 ? lines.slice(-lastN) : lines;
+    const results: Record<string, any>[] = [];
+    for (const line of subset) {
+      try { results.push(JSON.parse(line)); } catch { /* skip corrupt line */ }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+
+/** ISO timestamp for the current moment. */
+export function now(): string {
+  return new Date().toISOString();
+}