preflight-dev 3.1.0

package/src/tools/prompt-score.ts

@@ -0,0 +1,150 @@
+// =============================================================================
+// prompt_score — Gamified prompt quality scoring
+// =============================================================================
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+interface ScoreHistory {
+  scores: number[];
+  sessionStart: string;
+}
+
+const STATE_DIR = join(homedir(), ".preflight");
+const STATE_FILE = join(STATE_DIR, "score-history.json");
+
+async function loadHistory(): Promise<ScoreHistory> {
+  try {
+    const data = await readFile(STATE_FILE, "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return { scores: [], sessionStart: new Date().toISOString() };
+  }
+}
+
+async function saveHistory(history: ScoreHistory): Promise<void> {
+  await mkdir(STATE_DIR, { recursive: true });
+  await writeFile(STATE_FILE, JSON.stringify(history, null, 2));
+}
+
+interface ScoreResult {
+  specificity: number;
+  scope: number;
+  actionability: number;
+  doneCondition: number;
+  total: number;
+  grade: string;
+  feedback: string[];
+}
+
+function scorePrompt(text: string): ScoreResult {
+  const feedback: string[] = [];
+  let specificity = 0;
+  let scope = 0;
+  let actionability = 0;
+  let doneCondition = 0;
+
+  // Specificity: file paths, function names, specific identifiers
+  if (/[\/\\][\w.-]+\.\w+/.test(text) || /`[^`]+`/.test(text)) {
+    specificity = 25;
+  } else if (/\b(file|component|function|class|module|test|route)\b/i.test(text)) {
+    specificity = 15;
+    feedback.push("📁 Name the specific file/function for +10 points");
+  } else {
+    specificity = 5;
+    feedback.push("📁 No specific targets mentioned — which file? which function?");
+  }
+
+  // Scope: bounded task
+  if (/\b(only|just|single|one|specific|this)\b/i.test(text) || text.length > 100) {
+    scope = 25;
+  } else if (/\b(all|every|entire|whole)\b/i.test(text)) {
+    scope = 10;
+    feedback.push("🎯 'All/every' is broad — can you narrow the scope?");
+  } else {
+    scope = 10;
+    feedback.push("🎯 Scope unclear — how much should change?");
+  }
+
+  // Actionability: clear verb
+  const actionVerbs = /\b(add|remove|rename|refactor|fix|create|delete|update|change|replace|move|extract|implement|write|test|migrate)\b/i;
+  if (actionVerbs.test(text)) {
+    actionability = 25;
+  } else if (/\b(make|do|handle|work|improve|clean)\b/i.test(text)) {
+    actionability = 15;
+    feedback.push("⚡ Vague verb — 'fix' beats 'make work', 'extract' beats 'clean up'");
+  } else {
+    actionability = 5;
+    feedback.push("⚡ What's the action? Use a specific verb (add, remove, rename, etc.)");
+  }
+
+  // Done condition: verifiable outcome
+  if (/\b(should|must|expect|assert|return|output|pass|fail|error|log|print|display)\b/i.test(text)) {
+    doneCondition = 25;
+  } else if (/\?$/.test(text.trim())) {
+    doneCondition = 20; // questions are inherently verifiable
+  } else {
+    doneCondition = 5;
+    feedback.push("✅ No done condition — how will you know it worked?");
+  }
+
+  const total = specificity + scope + actionability + doneCondition;
+
+  let grade: string;
+  if (total >= 90) grade = "A+";
+  else if (total >= 85) grade = "A";
+  else if (total >= 80) grade = "A-";
+  else if (total >= 75) grade = "B+";
+  else if (total >= 70) grade = "B";
+  else if (total >= 65) grade = "B-";
+  else if (total >= 60) grade = "C+";
+  else if (total >= 55) grade = "C";
+  else if (total >= 45) grade = "D";
+  else grade = "F";
+
+  if (feedback.length === 0) {
+    feedback.push("🏆 Excellent prompt! Clear target, scope, action, and done condition.");
+  }
+
+  return { specificity, scope, actionability, doneCondition, total, grade, feedback };
+}
+
+export function registerPromptScore(server: McpServer): void {
+  server.tool(
+    "prompt_score",
+    "Score a prompt on specificity, scope, actionability, and done-condition. Returns a letter grade with specific improvement tips.",
+    {
+      prompt: z.string().describe("The prompt text to score"),
+    },
+    async ({ prompt }) => {
+      const result = scorePrompt(prompt);
+      const history = await loadHistory();
+      history.scores.push(result.total);
+      await saveHistory(history);
+
+      const avg = history.scores.length > 0
+        ? (history.scores.reduce((a, b) => a + b, 0) / history.scores.length).toFixed(0)
+        : result.total.toString();
+
+      const report = [
+        `🎯 Prompt Score: ${result.grade} (${result.total}/100)`,
+        `────────────────────────`,
+        `Specificity:    ${result.specificity}/25  ${result.specificity >= 20 ? "✓" : "✗"}`,
+        `Scope:          ${result.scope}/25  ${result.scope >= 20 ? "✓" : "✗"}`,
+        `Actionability:  ${result.actionability}/25  ${result.actionability >= 20 ? "✓" : "✗"}`,
+        `Done condition: ${result.doneCondition}/25  ${result.doneCondition >= 20 ? "✓" : "✗"}`,
+        ``,
+        ...result.feedback,
+        ``,
+        `Session average: ${avg}/100 (${history.scores.length} prompts scored)`,
+      ].join("\n");
+
+      return {
+        content: [{ type: "text" as const, text: report }],
+      };
+    }
+  );
+}

package/src/tools/scan-sessions.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as fs from "fs";
+import * as path from "path";
+import { findSessionDirs, findSessionFiles } from "../lib/session-parser.js";
+
+interface SessionInfo {
+  project: string;
+  projectName: string;
+  sessionId: string;
+  path: string;
+  mtime: Date;
+  size: number;
+  branch?: string;
+  lastMessage?: string;
+  messageCount?: number;
+}
+
+function formatAge(ms: number): string {
+  const mins = Math.floor(ms / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}min ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+function readLastLines(filePath: string, n: number): string[] {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const lines = content.trim().split("\n");
+    return lines.slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+function readFirstLine(filePath: string): string | null {
+  try {
+    const fd = fs.openSync(filePath, "r");
+    const buf = Buffer.alloc(4096);
+    const bytesRead = fs.readSync(fd, buf, 0, 4096, 0);
+    fs.closeSync(fd);
+    const text = buf.toString("utf-8", 0, bytesRead);
+    const nl = text.indexOf("\n");
+    return nl >= 0 ? text.slice(0, nl) : text;
+  } catch {
+    return null;
+  }
+}
+
+function extractBranchFromSession(firstLine: string | null): string | undefined {
+  if (!firstLine) return undefined;
+  try {
+    const obj = JSON.parse(firstLine);
+    return obj.branch || obj.metadata?.branch;
+  } catch {
+    return undefined;
+  }
+}
+
+function extractMessageContent(line: string): string | undefined {
+  try {
+    const obj = JSON.parse(line);
+    if (obj.type === "human" || obj.type === "prompt") return obj.content?.slice(0, 120);
+    if (obj.type === "assistant") return obj.content?.slice(0, 120);
+    if (obj.message?.content) return obj.message.content.slice(0, 120);
+    if (typeof obj.content === "string") return obj.content.slice(0, 120);
+  } catch {
+    // not JSON
+  }
+  return undefined;
+}
+
+export function registerScanSessions(server: McpServer) {
+  server.tool(
+    "scan_sessions",
+    "Live scan of Claude Code sessions on disk. Shows active and recent sessions, file sizes, and optionally last messages. Detects parallel sessions on the same branch.",
+    {
+      project: z.string().optional().describe("Project name or path. If omitted, scans all projects."),
+      active_only: z.boolean().default(false).describe("Only show sessions modified in last hour"),
+      include_messages: z.number().default(0).describe("Include last N messages from each session"),
+      sort: z.enum(["recent", "size", "messages"]).default("recent"),
+    },
+    async (params) => {
+      const allDirs = findSessionDirs();
+      const filtered = params.project
+        ? allDirs.filter(
+            (d) =>
+              d.projectName === params.project ||
+              d.project === params.project ||
+              d.projectName.toLowerCase().includes(params.project!.toLowerCase())
+          )
+        : allDirs;
+
+      if (filtered.length === 0) {
+        return { content: [{ type: "text", text: "## Sessions\n_No session directories found._" }] };
+      }
+
+      // Gather all sessions
+      const sessions: SessionInfo[] = [];
+      for (const dir of filtered) {
+        const files = findSessionFiles(dir.sessionDir);
+        for (const f of files) {
+          let size = 0;
+          try {
+            size = fs.statSync(f.path).size;
+          } catch {}
+
+          const firstLine = readFirstLine(f.path);
+          const branch = extractBranchFromSession(firstLine);
+
+          const info: SessionInfo = {
+            project: dir.project,
+            projectName: dir.projectName,
+            sessionId: f.sessionId,
+            path: f.path,
+            mtime: f.mtime,
+            size,
+            branch,
+          };
+
+          if (params.include_messages > 0) {
+            const lastLines = readLastLines(f.path, params.include_messages);
+            const messages = lastLines.map(extractMessageContent).filter(Boolean) as string[];
+            info.lastMessage = messages[messages.length - 1];
+            info.messageCount = messages.length;
+          }
+
+          sessions.push(info);
+        }
+      }
+
+      const now = Date.now();
+      const ONE_HOUR = 3600000;
+
+      // Filter active only
+      const visible = params.active_only
+        ? sessions.filter((s) => now - s.mtime.getTime() < ONE_HOUR)
+        : sessions;
+
+      if (visible.length === 0) {
+        return { content: [{ type: "text", text: "## Sessions\n_No active sessions found._" }] };
+      }
+
+      // Sort
+      if (params.sort === "recent") visible.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+      else if (params.sort === "size") visible.sort((a, b) => b.size - a.size);
+      else visible.sort((a, b) => (b.messageCount || 0) - (a.messageCount || 0));
+
+      // Group by project
+      const byProject = new Map<string, SessionInfo[]>();
+      for (const s of visible) {
+        if (!byProject.has(s.projectName)) byProject.set(s.projectName, []);
+        byProject.get(s.projectName)!.push(s);
+      }
+
+      const lines: string[] = ["## Active Sessions", ""];
+      const warnings: string[] = [];
+
+      for (const [projName, projSessions] of byProject) {
+        const activeCount = projSessions.filter((s) => now - s.mtime.getTime() < ONE_HOUR).length;
+        lines.push(`### ${projName} (${projSessions.length} session${projSessions.length !== 1 ? "s" : ""}${activeCount > 0 ? `, ${activeCount} active` : ""})`);
+
+        for (const s of projSessions) {
+          const isActive = now - s.mtime.getTime() < ONE_HOUR;
+          const prefix = isActive ? "⚡" : "  ";
+          const branch = s.branch || "unknown";
+          const age = formatAge(now - s.mtime.getTime());
+          const size = formatSize(s.size);
+
+          lines.push(`${prefix} **${s.sessionId.slice(0, 8)}** — ${branch} — Last active: ${age} — ${size}`);
+
+          if (s.lastMessage) {
+            lines.push(`   Last: "${s.lastMessage}"`);
+          }
+        }
+
+        // Detect parallel sessions (same branch, both active in last hour)
+        const branchGroups = new Map<string, SessionInfo[]>();
+        for (const s of projSessions) {
+          if (!s.branch || now - s.mtime.getTime() >= ONE_HOUR) continue;
+          if (!branchGroups.has(s.branch)) branchGroups.set(s.branch, []);
+          branchGroups.get(s.branch)!.push(s);
+        }
+        for (const [branch, group] of branchGroups) {
+          if (group.length > 1) {
+            warnings.push(`⚠️ Parallel session warning: ${projName} has ${group.length} sessions on \`${branch}\` branch`);
+          }
+        }
+
+        lines.push("");
+      }
+
+      if (warnings.length > 0) {
+        lines.push(...warnings);
+      }
+
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}

package/src/tools/scope-work.ts

@@ -0,0 +1,238 @@
+// CATEGORY 1: scope_work — Plans
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { run, getBranch, getRecentCommits, getStatus } from "../lib/git.js";
+import { readIfExists, findWorkspaceDocs, PROJECT_DIR } from "../lib/files.js";
+import { searchSemantic } from "../lib/timeline-db.js";
+import { getRelatedProjects } from "../lib/config.js";
+import { now } from "../lib/state.js";
+import { existsSync } from "fs";
+import { join, normalize, resolve, basename } from "path";
+
+const STOP_WORDS = new Set([
+  "the", "and", "for", "with", "from", "that", "this", "should", "would", "could",
+  "into", "have", "been", "will", "just", "also", "when", "then", "than", "what",
+  "where", "which", "there", "their", "about", "after", "before", "does", "make",
+  "like", "some", "each", "only", "need", "want", "please", "update", "change",
+]);
+
+/** Shell-escape a string for use inside single quotes */
+function shellEscape(s: string): string {
+  return s.replace(/'/g, "'\\''");
+}
+
+/** Safely parse git porcelain status lines */
+function parsePortelainFiles(porcelain: string): string[] {
+  if (!porcelain.trim()) return [];
+  return porcelain.split("\n").filter(Boolean).flatMap((line) => {
+    // Porcelain format: XY filename  or  XY orig -> renamed
+    if (line.length < 4) return [];
+    const status = line.slice(0, 2);
+    const rest = line.slice(3);
+    // Handle renames/copies: "R  old -> new"
+    if (status.startsWith("R") || status.startsWith("C")) {
+      const parts = rest.split(" -> ");
+      return parts.map((p) => p.trim()).filter(Boolean);
+    }
+    return [rest.trim()];
+  }).filter(Boolean);
+}
+
+/** Validate a dir path is within PROJECT_DIR (no traversal) */
+function isSafePath(dir: string): boolean {
+  const resolved = resolve(PROJECT_DIR, dir);
+  return resolved.startsWith(resolve(PROJECT_DIR));
+}
+
+/** Search for relevant cross-project context for scoping */
+async function searchRelatedProjectContext(task: string): Promise<string[]> {
+  const relatedProjects = getRelatedProjects();
+  if (relatedProjects.length === 0) return [];
+
+  // Generate targeted search queries for scoping
+  const queries = [
+    `${task} interface type definition`,
+    `${task} API endpoint service`,
+    `${task} component hook pattern`,
+    `${task} database schema model`,
+  ];
+
+  const contextItems: string[] = [];
+  
+  for (const query of queries) {
+    try {
+      const results = await searchSemantic(query, {
+        project_dirs: relatedProjects,
+        limit: 2,
+      });
+
+      for (const result of results) {
+        const projectName = basename(result.project);
+        const content = result.content.slice(0, 150);
+        const fileInfo = result.source_file ? ` (${result.source_file})` : "";
+        contextItems.push(`- **${projectName}:** ${content}${fileInfo}`);
+      }
+    } catch {
+      // Skip if search fails
+    }
+  }
+
+  return contextItems.slice(0, 4); // Limit to top 4 context items
+}
+
+export function registerScopeWork(server: McpServer): void {
+  server.tool(
+    "scope_work",
+    `Break down a task into a structured execution plan BEFORE writing any code. Call this tool whenever you receive a new task, feature request, or bug report. It analyzes the current project state (git, files, workspace docs) and returns an ordered plan with scope boundaries, complexity estimate, and done conditions. Use this to avoid scope creep and ensure you touch only what's needed.`,
+    {
+      task: z.string().describe("The raw user task or request to plan"),
+      branch: z.string().optional().describe("Git branch to scope against (defaults to current branch)"),
+    },
+    async ({ task, branch }) => {
+      const timestamp = now();
+      const currentBranch = branch ?? getBranch();
+      const recentCommits = getRecentCommits(10);
+      const porcelain = run("git status --porcelain");
+      const dirtyFiles = parsePortelainFiles(porcelain);
+      const diffStat = dirtyFiles.length > 0 ? run("git diff --stat") : "(clean working tree)";
+
+      // Scan for relevant files based on task keywords
+      const keywords = task.toLowerCase().split(/\s+/);
+      const scanDirs = [
+        { pattern: "test", dirs: ["tests/", "test/", "__tests__/", "spec/"] },
+        { pattern: "api", dirs: ["api/", "src/api/", "app/api/", "routes/"] },
+        { pattern: "app", dirs: ["app/", "src/app/", "src/pages/"] },
+        { pattern: "database", dirs: ["prisma/", "migrations/", "db/"] },
+        { pattern: "prisma", dirs: ["prisma/"] },
+        { pattern: "schema", dirs: ["prisma/", "schema/", "schemas/"] },
+        { pattern: "component", dirs: ["components/", "src/components/"] },
+        { pattern: "hook", dirs: ["hooks/", "src/hooks/"] },
+        { pattern: "style", dirs: ["styles/", "src/styles/"] },
+        { pattern: "config", dirs: ["config/", ".config/"] },
+      ];
+
+      const relevantDirs = new Set<string>();
+      for (const { pattern, dirs } of scanDirs) {
+        if (keywords.some((k) => k.includes(pattern))) {
+          dirs.forEach((d) => relevantDirs.add(d));
+        }
+      }
+
+      // Grep for files matching task keywords — sanitize for shell safety
+      let matchedFiles = "";
+      const grepTerms = keywords
+        .filter((k) => k.length > 3 && !STOP_WORDS.has(k))
+        .map((k) => k.replace(/[^a-z0-9_-]/g, "")) // strip non-alphanumeric to prevent injection
+        .filter((k) => k.length > 2)
+        .slice(0, 5);
+      if (grepTerms.length > 0) {
+        const pattern = shellEscape(grepTerms.join("|"));
+        matchedFiles = run(`git ls-files | head -500 | grep -iE '${pattern}' | head -30`);
+      }
+
+      // Check which relevant dirs actually exist (with path traversal protection)
+      const existingDirs: string[] = [];
+      for (const dir of relevantDirs) {
+        if (isSafePath(dir) && existsSync(join(PROJECT_DIR, dir))) {
+          existingDirs.push(dir);
+        }
+      }
+
+      // Workspace docs
+      const workspaceDocs = findWorkspaceDocs();
+      const docEntries = Object.entries(workspaceDocs);
+
+      // Project instructions
+      const claudeMd = readIfExists("CLAUDE.md", 50);
+      const agentsMd = readIfExists(".claude/AGENTS.md", 50);
+
+      // Complexity estimate — count unique files from matched + dirty
+      const allTouchedFiles = [
+        ...matchedFiles.split("\n").filter(Boolean),
+        ...dirtyFiles,
+      ];
+      const uniqueFiles = [...new Set(allTouchedFiles)];
+      const fileCount = uniqueFiles.length;
+      const complexity = fileCount <= 3 ? "SMALL" : fileCount <= 10 ? "MEDIUM" : "LARGE";
+
+      const dirLine = existingDirs.length > 0
+        ? `**Relevant directories:** ${existingDirs.map((d) => `\`${d}\``).join(", ")}`
+        : "";
+
+      const docLines = docEntries.length > 0
+        ? docEntries.map(([name]) => `- \`${name}\``).join("\n")
+        : "- (none found)";
+
+      // Get cross-project context
+      const relatedContext = await searchRelatedProjectContext(task);
+
+      const plan = `# 📋 Scope Work Plan
+**Generated:** ${timestamp}
+**Task:** ${task}
+**Branch:** ${currentBranch}
+**Complexity:** ${complexity} (${fileCount} files in scope)
+
+---
+
+## 🔍 Current State
+**Recent commits:**
+\`\`\`
+${recentCommits || "(no commits)"}
+\`\`\`
+
+**Working tree:**
+\`\`\`
+${porcelain || "(clean)"}
+\`\`\`
+
+${diffStat !== "(clean working tree)" ? `**Uncommitted changes:**\n\`\`\`\n${diffStat}\n\`\`\`` : ""}
+
+## 📁 Relevant Files
+${matchedFiles ? matchedFiles.split("\n").filter(Boolean).map((f) => `- \`${f}\``).join("\n") : "- (no direct file matches — explore manually)"}
+
+${dirLine}
+
+## 📚 Workspace Docs
+${docLines}
+${claudeMd ? "- `CLAUDE.md` exists (project instructions)" : ""}
+${agentsMd ? "- `.claude/AGENTS.md` exists" : ""}
+
+${relatedContext.length > 0 ? `## 🔗 Related Project Context\n${relatedContext.join("\n")}\n` : ""}
+---
+
+## 📝 Execution Plan
+
+### Steps:
+1. **Understand** — Read the relevant files listed above
+2. **Plan tests** — Identify or write failing tests first
+3. **Implement** — Make the minimal changes needed
+4. **Verify** — Run tests, check types, lint
+5. **Clean up** — Remove debug code, check diff is tight
+
+### Files to touch:
+${uniqueFiles.length > 0 ? uniqueFiles.slice(0, 20).map((f) => `- [ ] \`${f}\``).join("\n") : "- [ ] (determine after reading codebase)"}
+
+### Tests to run:
+- [ ] Identify test files related to changed code
+- [ ] Run full test suite before AND after changes
+
+### 🚫 Scope Boundaries:
+- Do NOT refactor unrelated code
+- Do NOT update dependencies unless required by the task
+- Do NOT change config files without explicit instruction
+${dirtyFiles.length > 0 ? "- ⚠️ Working tree is dirty — do NOT commit unrelated changes" : ""}
+
+### ✅ Done Conditions:
+- [ ] All planned steps completed
+- [ ] Tests pass
+- [ ] Types check
+- [ ] Diff reviewed — only expected changes present
+- [ ] No TODOs or debug code left behind
+
+---
+*Use this plan as your checklist. Deviate only with explicit user approval.*`;
+
+      return { content: [{ type: "text" as const, text: plan }] };
+    }
+  );
+}