preflight-dev 3.1.0 → 3.2.0

package/src/lib/contracts.ts

@@ -0,0 +1,354 @@
+// =============================================================================
+// Cross-Service Contract Registry
+// =============================================================================
+// Extracts, stores, and searches API contracts, types, and schemas
+// across projects for fast cross-service context lookups.
+// =============================================================================
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "fs";
+import { join, resolve, relative, basename, extname } from "path";
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { load as yamlLoad } from "js-yaml";
+
+// --- Types ---
+
+export interface Contract {
+  name: string;
+  kind: "interface" | "type" | "enum" | "route" | "schema" | "event" | "model";
+  file: string;
+  definition: string;
+  project: string;
+  extractedAt: string;
+}
+
+interface ManualContractField {
+  name: string;
+  type: string;
+  required?: boolean;
+}
+
+interface ManualContractEntry {
+  name: string;
+  kind: string;
+  fields?: ManualContractField[];
+  description?: string;
+}
+
+// --- Helpers ---
+
+const PREFLIGHT_DIR = join(homedir(), ".preflight");
+const PROJECTS_DIR = join(PREFLIGHT_DIR, "projects");
+
+function hashProjectDir(projectDir: string): string {
+  return createHash("sha256").update(resolve(projectDir)).digest("hex").slice(0, 12);
+}
+
+function contractsPath(projectHash: string): string {
+  return join(PROJECTS_DIR, projectHash, "contracts.json");
+}
+
+// --- File Discovery ---
+
+/** Recursively find files matching patterns, skipping node_modules/.git/dist */
+function findFiles(dir: string, patterns: RegExp[], maxDepth = 8, depth = 0): string[] {
+  if (depth > maxDepth) return [];
+  const results: string[] = [];
+  
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (entry === "node_modules" || entry === ".git" || entry === "dist" || entry === ".next" || entry === "build") continue;
+    const full = join(dir, entry);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    
+    if (st.isDirectory()) {
+      results.push(...findFiles(full, patterns, maxDepth, depth + 1));
+    } else if (patterns.some(p => p.test(full))) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+// --- Extraction ---
+
+const TS_CONTRACT_PATTERNS: RegExp[] = [
+  // types.ts, types/*.ts, interfaces.ts, *.d.ts
+  /\/types\.ts$/, /\/types\/[^/]+\.ts$/, /\/interfaces\.ts$/, /\.d\.ts$/,
+  // API routes
+  /\/api\/.*\.ts$/, /\/routes\/.*\.ts$/,
+  // Event schemas
+  /\/events\/.*\.ts$/, /\/schemas\/.*\.ts$/,
+];
+
+const PRISMA_PATTERN = /prisma\/schema\.prisma$/;
+const OPENAPI_PATTERN = /\/(openapi\.ya?ml|swagger\.json)$/;
+
+/** Extract TypeScript interfaces, types, and enums from source */
+function extractTsContracts(content: string, filePath: string, projectDir: string): Contract[] {
+  const contracts: Contract[] = [];
+  const relPath = relative(projectDir, filePath);
+  const now = new Date().toISOString();
+
+  // Match: export interface Foo { ... }
+  const interfaceRe = /export\s+interface\s+(\w+)(?:\s+extends\s+[^{]+)?\s*\{[^}]*(?:\{[^}]*\}[^}]*)*\}/g;
+  for (const m of content.matchAll(interfaceRe)) {
+    contracts.push({ name: m[1], kind: "interface", file: relPath, definition: m[0].slice(0, 500), project: projectDir, extractedAt: now });
+  }
+
+  // Match: export type Foo = ...
+  const typeRe = /export\s+type\s+(\w+)\s*(?:<[^>]*>)?\s*=[^;]+;/g;
+  for (const m of content.matchAll(typeRe)) {
+    contracts.push({ name: m[1], kind: "type", file: relPath, definition: m[0].slice(0, 500), project: projectDir, extractedAt: now });
+  }
+
+  // Match: export enum Foo { ... }
+  const enumRe = /export\s+enum\s+(\w+)\s*\{[^}]*\}/g;
+  for (const m of content.matchAll(enumRe)) {
+    contracts.push({ name: m[1], kind: "enum", file: relPath, definition: m[0].slice(0, 500), project: projectDir, extractedAt: now });
+  }
+
+  // Detect route definitions (Next.js/Express patterns)
+  const isRouteFile = /\/(api|routes)\//.test(filePath);
+  if (isRouteFile) {
+    // export async function GET/POST/PUT/DELETE/PATCH
+    const routeRe = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH|handler)\b[^{]*\{/g;
+    for (const m of content.matchAll(routeRe)) {
+      const routeName = `${m[1]} ${relPath.replace(/\.(ts|js)$/, "")}`;
+      const defStart = m.index!;
+      contracts.push({ name: routeName, kind: "route", file: relPath, definition: content.slice(defStart, defStart + 500), project: projectDir, extractedAt: now });
+    }
+    // router.get/post/put/delete
+    const expressRe = /router\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]/g;
+    for (const m of content.matchAll(expressRe)) {
+      contracts.push({ name: `${m[1].toUpperCase()} ${m[2]}`, kind: "route", file: relPath, definition: m[0].slice(0, 500), project: projectDir, extractedAt: now });
+    }
+  }
+
+  return contracts;
+}
+
+/** Extract Prisma models */
+function extractPrismaContracts(content: string, filePath: string, projectDir: string): Contract[] {
+  const contracts: Contract[] = [];
+  const relPath = relative(projectDir, filePath);
+  const now = new Date().toISOString();
+
+  const modelRe = /model\s+(\w+)\s*\{[^}]*\}/g;
+  for (const m of content.matchAll(modelRe)) {
+    contracts.push({ name: m[1], kind: "model", file: relPath, definition: m[0].slice(0, 500), project: projectDir, extractedAt: now });
+  }
+
+  const enumRe = /enum\s+(\w+)\s*\{[^}]*\}/g;
+  for (const m of content.matchAll(enumRe)) {
+    contracts.push({ name: m[1], kind: "enum", file: relPath, definition: m[0].slice(0, 500), project: projectDir, extractedAt: now });
+  }
+
+  return contracts;
+}
+
+/** Extract from OpenAPI/Swagger specs */
+function extractOpenApiContracts(content: string, filePath: string, projectDir: string): Contract[] {
+  const contracts: Contract[] = [];
+  const relPath = relative(projectDir, filePath);
+  const now = new Date().toISOString();
+
+  try {
+    const spec = filePath.endsWith(".json") ? JSON.parse(content) : yamlLoad(content) as any;
+    if (spec?.paths) {
+      for (const [path, methods] of Object.entries(spec.paths as Record<string, any>)) {
+        for (const method of Object.keys(methods)) {
+          if (["get", "post", "put", "delete", "patch"].includes(method)) {
+            const op = methods[method];
+            const name = `${method.toUpperCase()} ${path}`;
+            const def = JSON.stringify({ summary: op.summary, parameters: op.parameters, requestBody: op.requestBody }, null, 2);
+            contracts.push({ name, kind: "route", file: relPath, definition: def.slice(0, 500), project: projectDir, extractedAt: now });
+          }
+        }
+      }
+    }
+    if (spec?.components?.schemas) {
+      for (const [name, schema] of Object.entries(spec.components.schemas)) {
+        contracts.push({ name, kind: "schema", file: relPath, definition: JSON.stringify(schema, null, 2).slice(0, 500), project: projectDir, extractedAt: now });
+      }
+    }
+  } catch {
+    // Invalid spec, skip
+  }
+
+  return contracts;
+}
+
+// --- Public API ---
+
+/** Scan a project directory and extract all contracts */
+export function extractContracts(projectDir: string): Contract[] {
+  const absDir = resolve(projectDir);
+  const contracts: Contract[] = [];
+
+  // TypeScript files
+  const tsFiles = findFiles(absDir, TS_CONTRACT_PATTERNS);
+  for (const file of tsFiles) {
+    try {
+      const content = readFileSync(file, "utf-8");
+      contracts.push(...extractTsContracts(content, file, absDir));
+    } catch { /* skip unreadable */ }
+  }
+
+  // Prisma
+  const prismaFiles = findFiles(absDir, [PRISMA_PATTERN], 3);
+  for (const file of prismaFiles) {
+    try {
+      const content = readFileSync(file, "utf-8");
+      contracts.push(...extractPrismaContracts(content, file, absDir));
+    } catch { /* skip */ }
+  }
+
+  // OpenAPI
+  const openApiFiles = findFiles(absDir, [OPENAPI_PATTERN], 5);
+  for (const file of openApiFiles) {
+    try {
+      const content = readFileSync(file, "utf-8");
+      contracts.push(...extractOpenApiContracts(content, file, absDir));
+    } catch { /* skip */ }
+  }
+
+  return contracts;
+}
+
+/** Load manual contract definitions from .preflight/contracts/ */
+export function loadManualContracts(projectDir: string): Contract[] {
+  const contractsDir = join(projectDir, ".preflight", "contracts");
+  if (!existsSync(contractsDir)) return [];
+
+  const contracts: Contract[] = [];
+  const now = new Date().toISOString();
+
+  let entries: string[];
+  try { entries = readdirSync(contractsDir); } catch { return []; }
+
+  for (const entry of entries) {
+    if (![".yml", ".yaml"].includes(extname(entry))) continue;
+    const filePath = join(contractsDir, entry);
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const items = yamlLoad(content) as ManualContractEntry[];
+      if (!Array.isArray(items)) continue;
+
+      for (const item of items) {
+        if (!item.name || !item.kind) continue;
+        const def = item.fields
+          ? `${item.description || ""}\nFields: ${item.fields.map(f => `${f.name}: ${f.type}${f.required ? " (required)" : ""}`).join(", ")}`
+          : item.description || "";
+        contracts.push({
+          name: item.name,
+          kind: item.kind as Contract["kind"],
+          file: `.preflight/contracts/${entry}`,
+          definition: def.trim().slice(0, 500),
+          project: resolve(projectDir),
+          extractedAt: now,
+        });
+      }
+    } catch { /* skip invalid */ }
+  }
+
+  return contracts;
+}
+
+/** Load stored contracts for a project */
+export function loadContracts(projectHash: string): Contract[] {
+  const p = contractsPath(projectHash);
+  if (!existsSync(p)) return [];
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+
+/** Save contracts to storage */
+export function saveContracts(projectHash: string, contracts: Contract[]): void {
+  const dir = join(PROJECTS_DIR, projectHash);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(contractsPath(projectHash), JSON.stringify(contracts, null, 2));
+}
+
+/** Search contracts by query string (simple relevance scoring) */
+export function searchContracts(query: string, contracts: Contract[]): Contract[] {
+  const terms = query.toLowerCase().split(/\s+/).filter(t => t.length > 1);
+  if (terms.length === 0) return contracts;
+
+  const scored = contracts.map(c => {
+    const nameL = c.name.toLowerCase();
+    const defL = c.definition.toLowerCase();
+    const fileL = c.file.toLowerCase();
+    let score = 0;
+
+    for (const term of terms) {
+      // Exact name match is highest
+      if (nameL === term) score += 10;
+      // Name contains term
+      else if (nameL.includes(term)) score += 5;
+      // File contains term
+      if (fileL.includes(term)) score += 2;
+      // Definition contains term
+      if (defL.includes(term)) score += 1;
+    }
+
+    return { contract: c, score };
+  });
+
+  return scored
+    .filter(s => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map(s => s.contract);
+}
+
+/** Extract and save contracts for a project, merging with manual definitions */
+export function extractAndSaveContracts(projectDir: string): { count: number; hash: string } {
+  const absDir = resolve(projectDir);
+  const hash = hashProjectDir(absDir);
+  
+  const autoContracts = extractContracts(absDir);
+  const manualContracts = loadManualContracts(absDir);
+
+  // Manual contracts take precedence (same name = manual wins)
+  const manualNames = new Set(manualContracts.map(c => c.name));
+  const merged = [
+    ...manualContracts,
+    ...autoContracts.filter(c => !manualNames.has(c.name)),
+  ];
+
+  saveContracts(hash, merged);
+  return { count: merged.length, hash };
+}
+
+/** Load all contracts for a list of project directories */
+export function loadAllContracts(projectDirs: string[]): Contract[] {
+  const all: Contract[] = [];
+  for (const dir of projectDirs) {
+    const hash = hashProjectDir(resolve(dir));
+    all.push(...loadContracts(hash));
+  }
+  return all;
+}
+
+/** Format contracts for display in tool output */
+export function formatContracts(contracts: Contract[], limit = 10): string {
+  if (contracts.length === 0) return "";
+  
+  const lines = contracts.slice(0, limit).map(c => {
+    const proj = basename(c.project);
+    const defPreview = c.definition.split("\n")[0].slice(0, 120);
+    return `From ${proj}: ${c.kind} ${c.name} — ${defPreview} (${c.file})`;
+  });
+
+  return lines.join("\n");
+}

package/src/lib/patterns.ts

@@ -0,0 +1,210 @@
+/**
+ * Correction pattern learning system.
+ * Analyzes correction logs and extracts recurring patterns so preflight
+ * can warn about known pitfalls before they happen again.
+ */
+
+import { readLog, saveState, loadState } from "./state.js";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface CorrectionPattern {
+  id: string;
+  pattern: string;
+  keywords: string[];
+  frequency: number;
+  lastSeen: string;
+  context: string;
+  examples: string[];
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/** Extract meaningful keywords (3+ chars, lowercased, deduplicated). */
+function extractKeywords(text: string): string[] {
+  const stopWords = new Set([
+    "the", "and", "that", "this", "with", "for", "not", "but", "was", "are",
+    "you", "your", "have", "has", "had", "been", "were", "will", "would",
+    "could", "should", "can", "did", "does", "don", "isn", "isn't", "don't",
+    "use", "used", "using", "from", "into", "about", "just", "wrong", "again",
+    "said", "instead", "meant", "want", "wanted", "need", "like",
+  ]);
+  const words = text
+    .replace(/[^a-zA-Z0-9_\-/.]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length >= 3)
+    .map((w) => w.toLowerCase())
+    .filter((w) => !stopWords.has(w));
+  return [...new Set(words)];
+}
+
+/** Compute overlap ratio between two keyword sets. */
+function keywordOverlap(a: string[], b: string[]): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  const setB = new Set(b);
+  const shared = a.filter((w) => setB.has(w)).length;
+  return shared / Math.min(a.length, b.length);
+}
+
+// ── Core Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Read correction log and extract recurring patterns.
+ * Groups corrections by keyword similarity. If 2+ corrections share
+ * enough keywords, creates a pattern.
+ */
+export function extractPatterns(): CorrectionPattern[] {
+  const corrections = readLog("corrections.jsonl");
+  if (corrections.length === 0) return [];
+
+  // Build keyword index per correction
+  const entries = corrections.map((c) => ({
+    text: `${c.user_said || ""} ${c.wrong_action || ""} ${c.root_cause || ""}`,
+    keywords: extractKeywords(
+      `${c.user_said || ""} ${c.wrong_action || ""} ${c.root_cause || ""}`,
+    ),
+    timestamp: c.timestamp as string,
+    userSaid: (c.user_said || "") as string,
+  }));
+
+  // Group by similarity (greedy clustering)
+  const used = new Set<number>();
+  const groups: number[][] = [];
+
+  for (let i = 0; i < entries.length; i++) {
+    if (used.has(i)) continue;
+    const group = [i];
+    used.add(i);
+    for (let j = i + 1; j < entries.length; j++) {
+      if (used.has(j)) continue;
+      if (keywordOverlap(entries[i].keywords, entries[j].keywords) >= 0.3) {
+        group.push(j);
+        used.add(j);
+      }
+    }
+    if (group.length >= 2) {
+      groups.push(group);
+    }
+  }
+
+  // Convert groups to patterns
+  const patterns: CorrectionPattern[] = groups.map((group, idx) => {
+    const groupEntries = group.map((i) => entries[i]);
+
+    // Merge keywords, ranked by frequency
+    const kwFreq: Record<string, number> = {};
+    for (const e of groupEntries) {
+      for (const kw of e.keywords) {
+        kwFreq[kw] = (kwFreq[kw] || 0) + 1;
+      }
+    }
+    const topKeywords = Object.entries(kwFreq)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 8)
+      .map(([k]) => k);
+
+    // Most recent timestamp
+    const lastSeen = groupEntries
+      .map((e) => e.timestamp)
+      .filter(Boolean)
+      .sort()
+      .pop() || new Date().toISOString();
+
+    // Examples (up to 3 user_said messages)
+    const examples = groupEntries
+      .map((e) => e.userSaid)
+      .filter((s) => s.length > 0)
+      .slice(0, 3);
+
+    // Build human-readable pattern from top keywords
+    const patternDesc = `Recurring correction: ${topKeywords.slice(0, 4).join(", ")}`;
+
+    // Context from the most detailed correction
+    const longestEntry = groupEntries.sort((a, b) => b.text.length - a.text.length)[0];
+    const context = longestEntry.text.trim().slice(0, 300);
+
+    return {
+      id: `p${idx + 1}`,
+      pattern: patternDesc,
+      keywords: topKeywords,
+      frequency: group.length,
+      lastSeen,
+      context,
+      examples,
+    };
+  });
+
+  return patterns.sort((a, b) => b.frequency - a.frequency);
+}
+
+/**
+ * Check if a prompt matches any known patterns.
+ * Returns patterns whose keywords overlap with the prompt.
+ */
+export function matchPatterns(
+  prompt: string,
+  patterns: CorrectionPattern[],
+): CorrectionPattern[] {
+  if (patterns.length === 0) return [];
+  const promptKeywords = extractKeywords(prompt);
+  const promptLower = prompt.toLowerCase();
+
+  return patterns.filter((p) => {
+    // Direct keyword match: at least 2 keywords present in prompt
+    const hits = p.keywords.filter(
+      (kw) => promptLower.includes(kw.toLowerCase()),
+    );
+    return hits.length >= 2;
+  });
+}
+
+/** Save patterns to state. */
+export function savePatterns(patterns: CorrectionPattern[]): void {
+  saveState("patterns", { patterns, updated: new Date().toISOString() });
+}
+
+/** Load patterns from state. */
+export function loadPatterns(): CorrectionPattern[] {
+  const state = loadState("patterns");
+  return (state.patterns as CorrectionPattern[]) || [];
+}
+
+/**
+ * Re-extract patterns from corrections log and save them.
+ * Returns the updated patterns.
+ */
+export function refreshPatterns(): CorrectionPattern[] {
+  const patterns = extractPatterns();
+  savePatterns(patterns);
+  return patterns;
+}
+
+/**
+ * Format matched patterns for display.
+ */
+export function formatPatternMatches(matches: CorrectionPattern[]): string {
+  if (matches.length === 0) return "";
+
+  const lines = ["⚠️ Known patterns matched:", ""];
+  for (let i = 0; i < matches.length; i++) {
+    const p = matches[i];
+    const ago = formatTimeAgo(p.lastSeen);
+    lines.push(`${i + 1}. "${p.pattern}" (corrected ${p.frequency}x)`);
+    lines.push(`   Context: ${p.context.slice(0, 150)}`);
+    lines.push(`   Last triggered: ${ago}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function formatTimeAgo(isoDate: string): string {
+  try {
+    const diff = Date.now() - new Date(isoDate).getTime();
+    const days = Math.floor(diff / 86400000);
+    if (days === 0) return "today";
+    if (days === 1) return "yesterday";
+    return `${days} days ago`;
+  } catch {
+    return "unknown";
+  }
+}

package/src/lib/triage.ts

@@ -35,6 +35,8 @@ export interface TriageConfig {
   crossServiceKeywords?: string[];
   strictness?: string;       // 'relaxed' | 'standard' | 'strict'
   relatedAliases?: string[];
+  /** Number of matched correction patterns — boosts level to at least ambiguous. */
+  patternMatchCount?: number;
 }
 
 // ── Constants ──────────────────────────────────────────────────────────────

package/src/profiles.ts

@@ -32,6 +32,7 @@ const STANDARD_TOOLS = new Set([
   "checkpoint",
   "check_session_health",
   "log_correction",
+  "check_patterns",
   "audit_workspace",
   "session_handoff",
   "what_changed",
@@ -40,11 +41,14 @@ const STANDARD_TOOLS = new Set([
   "session_stats",
   "prompt_score",
   "generate_scorecard",
+  // Contract registry
+  "search_contracts",
   // Timeline tools — local embeddings, zero config
   "onboard_project",
   "search_history",
   "timeline_view",
   "scan_sessions",
+  "estimate_cost",
 ]);
 
 // Full = standard + OpenAI embedding option (needs API key)

package/src/tools/check-patterns.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { loadPatterns, matchPatterns, formatPatternMatches } from "../lib/patterns.js";
+
+export function registerCheckPatterns(server: McpServer): void {
+  server.tool(
+    "check_patterns",
+    "Check if the current prompt matches any learned correction patterns from past mistakes. Use this to avoid repeating known pitfalls.",
+    {
+      prompt: z.string().describe("The prompt to check against known patterns"),
+    },
+    async ({ prompt }) => {
+      const patterns = loadPatterns();
+
+      if (patterns.length === 0) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: "✅ No correction patterns learned yet. Patterns are extracted automatically as corrections are logged.",
+          }],
+        };
+      }
+
+      const matches = matchPatterns(prompt, patterns);
+
+      if (matches.length === 0) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: `✅ No known pitfalls matched. (${patterns.length} patterns tracked)`,
+          }],
+        };
+      }
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: formatPatternMatches(matches),
+        }],
+      };
+    },
+  );
+}

package/src/tools/clarify-intent.ts

@@ -5,7 +5,8 @@ import { findWorkspaceDocs, PROJECT_DIR } from "../lib/files.js";
 import { searchSemantic } from "../lib/timeline-db.js";
 import { getRelatedProjects } from "../lib/config.js";
 import { existsSync, readFileSync } from "fs";
-import { join, basename } from "path";
+import { join, basename, resolve } from "path";
+import { loadAllContracts, searchContracts, formatContracts } from "../lib/contracts.js";
 
 /** Parse test failures from common report formats without fragile shell pipelines */
 function getTestFailures(): string {
@@ -176,6 +177,14 @@ export function registerClarifyIntent(server: McpServer): void {
         hasDirtyFiles: dirtyCount > 0,
       });
 
+      // Check contracts FIRST (fast, no vector search)
+      const contractDirs = [resolve(PROJECT_DIR), ...getRelatedProjects()];
+      const allContracts = loadAllContracts(contractDirs);
+      const matchedContracts = searchContracts(user_message, allContracts);
+      if (matchedContracts.length > 0) {
+        sections.push(`## Matching Contracts\n${formatContracts(matchedContracts, 8)}`);
+      }
+
       // Search for cross-project context
       const crossProjectContext = await searchCrossProjectContext(user_message);
       if (crossProjectContext.length > 0) {