preflight-dev 3.1.0

package/src/tools/token-audit.ts

@@ -0,0 +1,259 @@
+// CATEGORY 5: token_audit — Token Efficiency
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { run } from "../lib/git.js";
+import { readIfExists, findWorkspaceDocs, PROJECT_DIR } from "../lib/files.js";
+import { loadState, saveState, now, STATE_DIR } from "../lib/state.js";
+import { readFileSync, existsSync, statSync } from "fs";
+import { join } from "path";
+
+/** Shell-escape a filename for safe interpolation */
+function shellEscape(s: string): string {
+  return s.replace(/'/g, "'\\''");
+}
+
+/**
+ * Grade thresholds rationale:
+ * - A (0-10):  Minimal waste — small diffs, targeted reads, lean context
+ * - B (11-25): Minor waste — a few large files or slightly bloated docs
+ * - C (26-45): Moderate waste — repeated reads, large diffs, or context bloat
+ * - D (46-65): Significant waste — multiple anti-patterns compounding
+ * - F (66+):   Severe waste — session is burning tokens on avoidable overhead
+ *
+ * Each pattern contributes a weighted score reflecting its relative token cost.
+ */
+
+const MAX_TOOL_LOG_BYTES = 5 * 1024 * 1024; // 5MB limit for tool log parsing
+
+export function registerTokenAudit(server: McpServer): void {
+  server.tool(
+    "token_audit",
+    `Detect token waste patterns in Claude Code sessions — repeated reads, large file dumps, context bloat, skill paste overhead. Call periodically to check efficiency, especially in long sessions.`,
+    {
+      session_actions: z.string().optional().describe("Description of recent actions if available"),
+      check_mode: z.enum(["quick", "deep"]).default("quick").describe("Quick checks git/files; deep also analyzes tool call patterns"),
+    },
+    async ({ session_actions, check_mode }) => {
+      const patterns: string[] = [];
+      const recommendations: string[] = [];
+      let wasteScore = 0;
+
+      // 1. Git diff size & dirty file count
+      const diffStat = run("git diff --stat --no-color 2>/dev/null");
+      const dirtyFiles = run("git diff --name-only 2>/dev/null");
+      const dirtyList = dirtyFiles.split("\n").filter(Boolean);
+      const dirtyCount = dirtyList.length;
+
+      const summaryLine = diffStat.split("\n").pop() || "";
+      const insertionsMatch = summaryLine.match(/(\d+) insertion/);
+      const deletionsMatch = summaryLine.match(/(\d+) deletion/);
+      const totalChanges = (parseInt(insertionsMatch?.[1] || "0") || 0) + (parseInt(deletionsMatch?.[1] || "0") || 0);
+
+      if (totalChanges > 2000) {
+        patterns.push(`Large uncommitted diff: ~${totalChanges} changed lines across ${dirtyCount} files`);
+        recommendations.push("Commit more frequently — large diffs bloat context when re-read");
+        wasteScore += 15;
+      }
+
+      // 2. Estimated context size from dirty files (safe line counting)
+      const AVG_LINE_BYTES = 45;
+      const AVG_TOKENS_PER_BYTE = 0.25;
+      let estimatedContextTokens = 0;
+      const largeFiles: string[] = [];
+
+      for (const f of dirtyList.slice(0, 30)) {
+        // Use shell-safe quoting instead of interpolation
+        const wc = run(`wc -l < '${shellEscape(f)}' 2>/dev/null`);
+        const lines = parseInt(wc) || 0;
+        estimatedContextTokens += lines * AVG_LINE_BYTES * AVG_TOKENS_PER_BYTE;
+        if (lines > 500) {
+          largeFiles.push(`${f} (${lines} lines)`);
+        }
+      }
+
+      if (largeFiles.length > 0) {
+        patterns.push(`Large files in working set (>500 lines): ${largeFiles.join(", ")}`);
+        recommendations.push("Use offset/limit when reading large files — avoid dumping entire contents");
+        wasteScore += largeFiles.length * 8;
+      }
+
+      // 3. CLAUDE.md bloat check
+      const claudeMd = readIfExists("CLAUDE.md", 1);
+      if (claudeMd !== null) {
+        const stat = run(`wc -c < '${shellEscape("CLAUDE.md")}' 2>/dev/null`);
+        const bytes = parseInt(stat) || 0;
+        if (bytes > 5120) {
+          patterns.push(`CLAUDE.md is ${(bytes / 1024).toFixed(1)}KB — injected every session, burns tokens on paste`);
+          recommendations.push("Trim CLAUDE.md to essentials (<5KB). Move reference docs to files read on-demand");
+          wasteScore += 12;
+        }
+      }
+
+      // 4. Workspace doc bloat
+      const docs = findWorkspaceDocs();
+      const docValues = Object.values(docs);
+      const totalDocSize = docValues.length > 0
+        ? docValues.reduce((sum, d) => sum + (d.size || 0), 0)
+        : 0;
+      if (totalDocSize > 20000) {
+        patterns.push(`Workspace context docs total ~${(totalDocSize / 1024).toFixed(1)}KB`);
+        recommendations.push("Consolidate or slim workspace docs — every byte is injected each turn");
+        wasteScore += 8;
+      }
+
+      // 5. Sub-agent count — check multiple possible state locations
+      let subAgentCount = 0;
+      const stateLocations = [
+        join(STATE_DIR, "session.json"),
+        join(PROJECT_DIR, ".claude", "state.json"),
+      ];
+      for (const loc of stateLocations) {
+        if (!existsSync(loc)) continue;
+        try {
+          const content = readFileSync(loc, "utf-8");
+          const state = JSON.parse(content);
+          subAgentCount = state.subAgents?.length || state.sub_agents?.length || 0;
+          if (subAgentCount > 0) break;
+        } catch { /* ignore malformed state */ }
+      }
+      if (subAgentCount > 5) {
+        patterns.push(`${subAgentCount} sub-agents spawned this session`);
+        recommendations.push("Batch related work to reduce sub-agent overhead — each carries full context");
+        wasteScore += subAgentCount * 3;
+      }
+
+      // 6. Deep mode: tool call pattern analysis (with size limit)
+      let repeatedReads: Record<string, number> = {};
+      let totalToolCalls = 0;
+
+      if (check_mode === "deep") {
+        const toolLogPath = join(STATE_DIR, "tool-calls.jsonl");
+        if (existsSync(toolLogPath)) {
+          try {
+            const stat = statSync(toolLogPath);
+            if (stat.size > MAX_TOOL_LOG_BYTES) {
+              patterns.push(`Tool call log is ${(stat.size / 1024 / 1024).toFixed(1)}MB — too large for full analysis, sampling tail`);
+              wasteScore += 5;
+            }
+
+            // Read with size cap: take the tail if too large
+            const raw = stat.size <= MAX_TOOL_LOG_BYTES
+              ? readFileSync(toolLogPath, "utf-8")
+              : run(`tail -c ${MAX_TOOL_LOG_BYTES} '${shellEscape(toolLogPath)}'`);
+
+            const lines = raw.trim().split("\n").filter(Boolean);
+            totalToolCalls = lines.length;
+            const readCounts: Record<string, number> = {};
+
+            for (const line of lines) {
+              try {
+                const entry = JSON.parse(line);
+                const tool = entry.tool || entry.name || "";
+                const filePath = entry.params?.path || entry.params?.file_path || "";
+                if ((tool === "Read" || tool === "read") && filePath) {
+                  readCounts[filePath] = (readCounts[filePath] || 0) + 1;
+                }
+              } catch { /* skip malformed lines */ }
+            }
+
+            repeatedReads = Object.fromEntries(
+              Object.entries(readCounts).filter(([, count]) => count >= 3)
+            );
+
+            if (Object.keys(repeatedReads).length > 0) {
+              const top = Object.entries(repeatedReads)
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 5)
+                .map(([f, c]) => `${f} (${c}x)`)
+                .join(", ");
+              patterns.push(`Repeated file reads: ${top}`);
+              recommendations.push("Cache file contents or use targeted reads (offset/limit) to avoid re-reading");
+              wasteScore += Object.keys(repeatedReads).length * 6;
+            }
+
+            if (totalToolCalls > 100) {
+              patterns.push(`High tool call volume: ${totalToolCalls} calls in session`);
+              recommendations.push("Plan multi-step work before executing — fewer, more precise tool calls save tokens");
+              wasteScore += 10;
+            }
+          } catch { /* ignore */ }
+        }
+      }
+
+      // 7. Session action hints
+      if (session_actions) {
+        const lower = session_actions.toLowerCase();
+        if (lower.includes("read") && lower.includes("same file")) {
+          patterns.push("User reports repeated reads of same file");
+          wasteScore += 10;
+        }
+        if (lower.includes("full file") || lower.includes("entire file")) {
+          patterns.push("User reports full-file reads where partial would suffice");
+          wasteScore += 8;
+        }
+      }
+
+      // Score calculation
+      const clampedWaste = Math.min(wasteScore, 100);
+      const grade =
+        clampedWaste <= 10 ? "A" :
+        clampedWaste <= 25 ? "B" :
+        clampedWaste <= 45 ? "C" :
+        clampedWaste <= 65 ? "D" : "F";
+
+      const savingsEstimate =
+        clampedWaste <= 10 ? "< 5%" :
+        clampedWaste <= 25 ? "5–15%" :
+        clampedWaste <= 45 ? "15–30%" :
+        clampedWaste <= 65 ? "30–50%" : "50%+";
+
+      if (patterns.length === 0) {
+        patterns.push("No significant token waste patterns detected");
+      }
+      if (recommendations.length === 0) {
+        recommendations.push("Session looks efficient — keep using targeted reads and incremental commits");
+      }
+
+      // Persist audit state
+      saveState("token_audit", {
+        ts: now(),
+        grade,
+        wasteScore: clampedWaste,
+        savingsEstimate,
+        patternsFound: patterns.length,
+        mode: check_mode,
+      });
+
+      const report = [
+        `## Token Efficiency Audit (${check_mode} mode)`,
+        "",
+        `**Score: ${grade}** (waste index: ${clampedWaste}/100)`,
+        `**Estimated savings if addressed: ${savingsEstimate}**`,
+        "",
+        "### Grading Scale",
+        "| Grade | Waste | Meaning |",
+        "|-------|-------|---------|",
+        "| A | 0–10 | Minimal waste |",
+        "| B | 11–25 | Minor inefficiencies |",
+        "| C | 26–45 | Moderate — worth addressing |",
+        "| D | 46–65 | Significant token burn |",
+        "| F | 66+ | Severe — immediate action needed |",
+        "",
+        "### Working Set",
+        `- Dirty files: ${dirtyCount}`,
+        `- Uncommitted changes: ~${totalChanges} lines`,
+        `- Est. context from dirty files: ~${Math.round(estimatedContextTokens).toLocaleString()} tokens`,
+        `- Sub-agents spawned: ${subAgentCount}`,
+        ...(check_mode === "deep" ? [`- Total tool calls analyzed: ${totalToolCalls}`, `- Files read 3+ times: ${Object.keys(repeatedReads).length}`] : []),
+        "",
+        "### Waste Patterns",
+        ...patterns.map((p) => `- ⚠️ ${p}`),
+        "",
+        "### Recommendations",
+        ...recommendations.map((r) => `- 💡 ${r}`),
+      ].join("\n");
+
+      return { content: [{ type: "text" as const, text: report }] };
+    }
+  );
+}

package/src/tools/verify-completion.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { run, getStatus } from "../lib/git.js";
+import { PROJECT_DIR } from "../lib/files.js";
+import { existsSync } from "fs";
+import { join } from "path";
+
+/** Detect package manager from lockfiles */
+function detectPM(): string {
+  if (existsSync(join(PROJECT_DIR, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(PROJECT_DIR, "yarn.lock"))) return "yarn";
+  if (existsSync(join(PROJECT_DIR, "bun.lockb"))) return "bun";
+  return "npx";
+}
+
+/** Detect test runner from config/dependencies */
+function detectTestRunner(): string | null {
+  // Check for common test configs
+  const configs = [
+    "playwright.config.ts", "playwright.config.js",
+    "vitest.config.ts", "vitest.config.js",
+    "jest.config.ts", "jest.config.js", "jest.config.mjs",
+  ];
+  for (const c of configs) {
+    if (existsSync(join(PROJECT_DIR, c))) {
+      if (c.startsWith("playwright")) return "playwright";
+      if (c.startsWith("vitest")) return "vitest";
+      if (c.startsWith("jest")) return "jest";
+    }
+  }
+  return null;
+}
+
+/** Check if a build script exists in package.json */
+function hasBuildScript(): boolean {
+  try {
+    const pkg = JSON.parse(run("cat package.json 2>/dev/null"));
+    return !!pkg?.scripts?.build;
+  } catch { return false; }
+}
+
+export function registerVerifyCompletion(server: McpServer): void {
+  server.tool(
+    "verify_completion",
+    `Verify that work is actually complete before declaring done. Runs type check, relevant tests, checks for uncommitted files, and validates against the original task criteria. Call this BEFORE saying "done" or committing final work.`,
+    {
+      task_description: z.string().describe("What was the task? Used to check if success criteria are met."),
+      test_scope: z.string().optional().describe("Which tests to run: 'all', a directory/keyword, or a specific spec file path. Default: auto-detect from changed files."),
+      skip_tests: z.boolean().optional().describe("Skip running tests (only check types + git state). Default: false."),
+      skip_build: z.boolean().optional().describe("Skip build check. Default: false."),
+    },
+    async ({ task_description, test_scope, skip_tests, skip_build }) => {
+      const pm = detectPM();
+      const sections: string[] = [];
+      const checks: { name: string; passed: boolean; detail: string }[] = [];
+
+      // 1. Type check (single invocation, extract both result and count)
+      const tscOutput = run(`${pm === "npx" ? "npx" : pm} tsc --noEmit 2>&1 | tail -20`);
+      const errorLines = tscOutput.split("\n").filter(l => /error TS\d+/.test(l));
+      const typePassed = errorLines.length === 0;
+      checks.push({
+        name: "Type Check",
+        passed: typePassed,
+        detail: typePassed
+          ? "✅ Clean"
+          : `❌ ${errorLines.length} errors\n${errorLines.slice(0, 10).join("\n")}${errorLines.length > 10 ? `\n... and ${errorLines.length - 10} more` : ""}`,
+      });
+
+      // 2. Git state
+      const dirty = getStatus();
+      const dirtyCount = dirty ? dirty.split("\n").filter(Boolean).length : 0;
+      checks.push({
+        name: "Git State",
+        passed: true, // informational, not a blocker
+        detail: dirtyCount > 0
+          ? `${dirtyCount} uncommitted files:\n\`\`\`\n${dirty}\n\`\`\``
+          : "✅ Clean working tree",
+      });
+
+      // 3. Tests
+      if (!skip_tests) {
+        const runner = detectTestRunner();
+        const changedFiles = run("git diff --name-only HEAD~1 2>/dev/null").split("\n").filter(Boolean);
+        let testCmd = "";
+
+        if (runner === "playwright") {
+          const runnerCmd = `${pm === "npx" ? "npx" : `${pm} exec`} playwright test`;
+          if (test_scope && test_scope !== "all") {
+            testCmd = test_scope.endsWith(".spec.ts") || test_scope.endsWith(".test.ts")
+              ? `${runnerCmd} ${test_scope} --reporter=line 2>&1 | tail -20`
+              : `${runnerCmd} --grep "${test_scope}" --reporter=line 2>&1 | tail -20`;
+          } else {
+            // Auto-detect from changed files
+            const changedTests = changedFiles.filter(f => /\.(spec|test)\.(ts|tsx|js)$/.test(f)).slice(0, 5);
+            if (changedTests.length > 0) {
+              testCmd = `${runnerCmd} ${changedTests.join(" ")} --reporter=line 2>&1 | tail -20`;
+            }
+          }
+        } else if (runner === "vitest" || runner === "jest") {
+          const runnerCmd = `${pm === "npx" ? "npx" : `${pm} exec`} ${runner}`;
+          if (test_scope && test_scope !== "all") {
+            testCmd = `${runnerCmd} --run ${test_scope} 2>&1 | tail -20`;
+          } else {
+            const changedTests = changedFiles.filter(f => /\.(spec|test)\.(ts|tsx|js)$/.test(f)).slice(0, 5);
+            if (changedTests.length > 0) {
+              testCmd = `${runnerCmd} --run ${changedTests.join(" ")} 2>&1 | tail -20`;
+            }
+          }
+        } else if (test_scope) {
+          // No recognized runner but scope given — try npm test
+          testCmd = `${pm} test 2>&1 | tail -20`;
+        }
+
+        if (testCmd) {
+          const testResult = run(testCmd, { timeout: 120000 });
+          const testPassed = /pass/i.test(testResult) && !/fail/i.test(testResult);
+          checks.push({
+            name: "Tests",
+            passed: testPassed,
+            detail: testPassed ? `✅ Tests passed\n${testResult}` : `❌ Tests failed\n${testResult}`,
+          });
+        } else {
+          checks.push({
+            name: "Tests",
+            passed: true,
+            detail: `⚠️ No relevant tests identified${runner ? ` (runner: ${runner})` : ""}. Consider running full suite.`,
+          });
+        }
+      }
+
+      // 4. Build check (only if build script exists and not skipped)
+      if (!skip_build && hasBuildScript()) {
+        const buildCheck = run(`${pm === "npx" ? "npm run" : pm} build 2>&1 | tail -10`, { timeout: 60000 });
+        const buildPassed = !/\b[Ee]rror\b/.test(buildCheck) || /Successfully compiled/.test(buildCheck);
+        checks.push({
+          name: "Build",
+          passed: buildPassed,
+          detail: buildPassed ? "✅ Build succeeds" : `❌ Build failed\n${buildCheck}`,
+        });
+      } else if (!skip_build) {
+        checks.push({ name: "Build", passed: true, detail: "⚠️ No build script found — skipped" });
+      }
+
+      const allPassed = checks.every(c => c.passed);
+      sections.push(`## Verification Report\n**Task**: ${task_description}\n\n${checks.map(c => `### ${c.name}\n${c.detail}`).join("\n\n")}`);
+
+      sections.push(`## Verdict\n${allPassed
+        ? "✅ **ALL CHECKS PASSED.** Safe to commit and declare done."
+        : "❌ **CHECKS FAILED.** Fix the issues above before committing."
+      }`);
+
+      if (!allPassed) {
+        sections.push(`## Do NOT:\n- Commit with failing checks\n- Say "done" without green tests\n- Push broken code to remote\n\n## DO:\n- Fix each failing check\n- Re-run \`verify_completion\` after fixes\n- Then commit`);
+      }
+
+      return { content: [{ type: "text" as const, text: sections.join("\n\n") }] };
+    }
+  );
+}

package/src/tools/what-changed.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { run, getBranch, getDiffStat } from "../lib/git.js";
+
+export function registerWhatChanged(server: McpServer): void {
+  server.tool(
+    "what_changed",
+    `Summarize what changed recently. Useful after sub-agents finish, after a break, when context was compacted, or at the start of a new session. Returns diff summary with commit messages.`,
+    {
+      since: z.string().optional().describe("Git ref: 'HEAD~5', 'HEAD~3', etc. Default: HEAD~5"),
+    },
+    async ({ since }) => {
+      const ref = since || "HEAD~5";
+      const diffStat = getDiffStat(ref);
+      const diffFiles = run(`git diff ${ref} --name-only 2>/dev/null || git diff HEAD~3 --name-only`);
+      const log = run(`git log ${ref}..HEAD --oneline 2>/dev/null || git log -5 --oneline`);
+      const branch = getBranch();
+
+      const fileList = diffFiles.split("\n").filter(Boolean);
+      const fileCount = fileList.length;
+      const commitCount = log.split("\n").filter(Boolean).length;
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: `## What Changed (since ${ref})
+Branch: ${branch}
+**${commitCount} commits**, **${fileCount} files** changed
+
+### Commits
+\`\`\`
+${log || "no commits in range"}
+\`\`\`
+
+### Files Changed (${fileCount})
+\`\`\`
+${diffFiles || "none"}
+\`\`\`
+
+### Stats
+\`\`\`
+${diffStat || "no changes"}
+\`\`\``,
+        }],
+      };
+    }
+  );
+}

package/src/types.ts

@@ -0,0 +1,87 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export type RegisterToolFn = (server: McpServer) => void;
+
+/** Standard MCP tool return format. */
+export type ToolResult = { content: Array<{ type: "text"; text: string }> };
+
+export interface DocInfo {
+  content: string;
+  mtime: Date;
+  size: number;
+}
+
+/** Metadata-only doc info (no content read). */
+export interface DocMeta {
+  mtime: Date;
+  size: number;
+}
+
+export interface CorrectionEntry {
+  timestamp: string;
+  branch: string;
+  user_said: string;
+  wrong_action: string;
+  root_cause: string;
+  category: string;
+}
+
+export interface CheckpointLogEntry {
+  timestamp: string;
+  branch: string;
+  summary: string;
+  next_steps: string;
+  blockers: string | null;
+  dirty_files: number;
+}
+
+/** Error details from a failed shell command. */
+export interface RunError {
+  exitCode: number | null;
+  timedOut: boolean;
+  stderr: string;
+  stdout: string;
+}
+
+/** Per-project metadata stored alongside the LanceDB */
+export interface ProjectMeta {
+  project_dir: string;
+  onboarded_at: string;
+  event_count: number;
+}
+
+/** Project registry entry in index.json */
+export interface ProjectRegistryEntry {
+  hash: string;
+  onboarded_at: string;
+}
+
+/** Project registry mapping absolute paths to metadata */
+export type ProjectRegistry = Record<string, ProjectRegistryEntry>;
+
+/** Search scope for timeline queries */
+export type SearchScope = "current" | "related" | "all";
+
+/** Triage classification levels for prompt analysis */
+export type TriageLevel = 'trivial' | 'clear' | 'ambiguous' | 'cross-service' | 'multi-step';
+
+/** Result from triage classification with recommendations */
+export interface TriageResult {
+  level: TriageLevel;
+  confidence: number; // 0-1
+  reasons: string[];  // why this classification
+  recommended_tools: string[]; // which tools should fire
+  cross_service_hits?: string[]; // which related projects matched
+}
+
+/** Configuration for preflight checks and triage system */
+export interface PreflightConfig {
+  related_projects?: Record<string, string>; // alias -> path mapping
+  triage?: {
+    always_check?: string[];
+    skip?: string[];
+    cross_service_keywords?: string[];
+    strictness?: 'relaxed' | 'standard' | 'strict';
+  };
+  correction_pattern_count?: number;
+}