preflight-dev 3.1.0

package/src/cli/init.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// =============================================================================
+// preflight init — Zero-config MCP server setup for Claude Code
+// =============================================================================
+
+import { createInterface } from "node:readline";
+import { readFile, writeFile, mkdir, copyFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+function ask(question: string): Promise<string> {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+/** Create .preflight/ directory with template files */
+async function createPreflightConfig(): Promise<void> {
+  const preflightDir = join(process.cwd(), ".preflight");
+  
+  if (existsSync(preflightDir)) {
+    console.log("⚠️  .preflight/ directory already exists, skipping...\n");
+    return;
+  }
+
+  try {
+    await mkdir(preflightDir, { recursive: true });
+    
+    // Get the current module's directory to find templates
+    const currentFile = fileURLToPath(import.meta.url);
+    const srcDir = dirname(dirname(currentFile)); // Go up from cli/ to src/
+    const templatesDir = join(srcDir, "templates");
+    
+    // Copy template files
+    await copyFile(join(templatesDir, "config.yml"), join(preflightDir, "config.yml"));
+    await copyFile(join(templatesDir, "triage.yml"), join(preflightDir, "triage.yml"));
+    
+    console.log("✅ Created .preflight/ directory with template config files");
+    console.log("   Edit .preflight/config.yml to configure your project settings");
+    console.log("   Edit .preflight/triage.yml to customize prompt triage rules\n");
+  } catch (error) {
+    console.error(`❌ Failed to create .preflight/ directory: ${error}\n`);
+  }
+}
+
+interface McpConfig {
+  mcpServers: Record<string, {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+  }>;
+}
+
+async function main(): Promise<void> {
+  console.log("\n✈️ preflight — MCP server setup\n");
+
+  const mcpPath = join(process.cwd(), ".mcp.json");
+  let config: McpConfig;
+
+  try {
+    const existing = await readFile(mcpPath, "utf-8");
+    config = JSON.parse(existing);
+    if (!config.mcpServers) config.mcpServers = {};
+    console.log("Found existing .mcp.json\n");
+  } catch {
+    config = { mcpServers: {} };
+    console.log("Creating new .mcp.json\n");
+  }
+
+  console.log("Choose a profile:\n");
+  console.log("  1) minimal  — 4 tools: clarify_intent, check_session_health, session_stats, prompt_score");
+  console.log("  2) standard — 16 tools: all prompt discipline + session_stats + prompt_score");
+  console.log("  3) full     — 20 tools: everything + timeline/vector search (needs LanceDB)\n");
+
+  const choice = await ask("Profile [1/2/3] (default: 2): ");
+  const profileMap: Record<string, string> = { "1": "minimal", "2": "standard", "3": "full" };
+  const profile = profileMap[choice.trim()] || "standard";
+
+  // Ask about creating .preflight/ directory
+  console.log("\nPreflight can use either environment variables or a .preflight/ directory for configuration.");
+  console.log("The .preflight/ directory allows you to configure related projects, custom triage rules, and thresholds.\n");
+  
+  const createConfig = await ask("Create .preflight/ directory with template config? [y/N]: ");
+  if (createConfig.trim().toLowerCase() === "y" || createConfig.trim().toLowerCase() === "yes") {
+    await createPreflightConfig();
+  }
+
+  const env: Record<string, string> = {
+    PROMPT_DISCIPLINE_PROFILE: profile,
+  };
+
+  if (profile === "full") {
+    console.log("\nFull profile uses embeddings for vector search.");
+    const provider = await ask("Embedding provider [local/openai] (default: local): ");
+    if (provider.trim().toLowerCase() === "openai") {
+      const key = await ask("OpenAI API key (or set OPENAI_API_KEY later): ");
+      if (key.trim()) {
+        env.OPENAI_API_KEY = key.trim();
+      }
+      env.EMBEDDING_PROVIDER = "openai";
+    } else {
+      env.EMBEDDING_PROVIDER = "local";
+    }
+  }
+
+  config.mcpServers["preflight"] = {
+    command: "npx",
+    args: ["-y", "preflight-dev@latest"],
+    env,
+  };
+
+  // For the actual server entry point, we need to point to index.ts via tsx
+  // But npx will resolve the bin entry which is the init script
+  // So use a different approach: command runs the server
+  config.mcpServers["preflight"] = {
+    command: "npx",
+    args: ["-y", "tsx", "node_modules/preflight/src/index.ts"],
+    env,
+  };
+
+  await writeFile(mcpPath, JSON.stringify(config, null, 2) + "\n");
+
+  console.log(`\n✅ preflight added! (profile: ${profile})`);
+  console.log("Restart Claude Code to connect.\n");
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// =============================================================================
+// Preflight-Dev MCP Server — v3.0
+// =============================================================================
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { isToolEnabled, getProfile } from "./profiles.js";
+import { getConfig, hasPreflightConfig } from "./lib/config.js";
+import { existsSync } from "fs";
+
+// Main entry point
+import { registerPreflightCheck } from "./tools/preflight-check.js";
+// Category 1: Plans
+import { registerScopeWork } from "./tools/scope-work.js";
+// Category 2: Clarification
+import { registerClarifyIntent } from "./tools/clarify-intent.js";
+// Category 3: Delegation
+import { registerEnrichAgentTask } from "./tools/enrich-agent-task.js";
+// Category 4: Follow-up Specificity
+import { registerSharpenFollowup } from "./tools/sharpen-followup.js";
+// Category 5: Token Efficiency
+import { registerTokenAudit } from "./tools/token-audit.js";
+// Category 6: Sequencing
+import { registerSequenceTasks } from "./tools/sequence-tasks.js";
+// Category 7: Compaction Management
+import { registerCheckpoint } from "./tools/checkpoint.js";
+// Category 8: Session Lifecycle
+import { registerSessionHealth } from "./tools/session-health.js";
+// Category 9: Error Recovery
+import { registerLogCorrection } from "./tools/log-correction.js";
+// Category 10: Workspace Hygiene
+import { registerAuditWorkspace } from "./tools/audit-workspace.js";
+// Category 11: Cross-Session Continuity
+import { registerSessionHandoff } from "./tools/session-handoff.js";
+import { registerWhatChanged } from "./tools/what-changed.js";
+// Category 12: Verification
+import { registerVerifyCompletion } from "./tools/verify-completion.js";
+// New lightweight tools
+import { registerSessionStats } from "./tools/session-stats.js";
+import { registerPromptScore } from "./tools/prompt-score.js";
+// Timeline: Project Intelligence
+import { registerOnboardProject } from "./tools/onboard-project.js";
+import { registerSearchHistory } from "./tools/search-history.js";
+import { registerTimeline } from "./tools/timeline-view.js";
+import { registerScanSessions } from "./tools/scan-sessions.js";
+import { registerGenerateScorecard } from "./tools/generate-scorecard.js";
+
+// Validate related projects from config
+function validateRelatedProjects(): void {
+  const config = getConfig();
+  const projects = config.related_projects;
+  
+  if (projects.length === 0) return;
+
+  const invalid: string[] = [];
+  
+  for (const project of projects) {
+    if (!existsSync(project.path)) {
+      invalid.push(`${project.alias} (${project.path})`);
+    }
+  }
+  
+  if (invalid.length > 0) {
+    process.stderr.write(`preflight-dev: warning - related projects contain invalid paths: ${invalid.join(", ")}\n`);
+  } else {
+    process.stderr.write(`preflight-dev: related projects: ${projects.length} configured\n`);
+  }
+}
+
+// Load config and validate related projects on startup
+const config = getConfig();
+validateRelatedProjects();
+
+const profile = getProfile();
+const server = new McpServer({
+  name: "preflight",
+  version: "3.0.0",
+});
+
+// Register tools based on profile
+type RegisterFn = (server: McpServer) => void;
+
+const toolRegistry: Array<[string, RegisterFn]> = [
+  ["preflight_check", registerPreflightCheck],
+  ["scope_work", registerScopeWork],
+  ["clarify_intent", registerClarifyIntent],
+  ["enrich_agent_task", registerEnrichAgentTask],
+  ["sharpen_followup", registerSharpenFollowup],
+  ["token_audit", registerTokenAudit],
+  ["sequence_tasks", registerSequenceTasks],
+  ["checkpoint", registerCheckpoint],
+  ["check_session_health", registerSessionHealth],
+  ["log_correction", registerLogCorrection],
+  ["audit_workspace", registerAuditWorkspace],
+  ["session_handoff", registerSessionHandoff],
+  ["what_changed", registerWhatChanged],
+  ["verify_completion", registerVerifyCompletion],
+  ["session_stats", registerSessionStats],
+  ["prompt_score", registerPromptScore],
+  ["onboard_project", registerOnboardProject],
+  ["search_history", registerSearchHistory],
+  ["timeline_view", registerTimeline],
+  ["scan_sessions", registerScanSessions],
+  ["generate_scorecard", registerGenerateScorecard],
+];
+
+let registered = 0;
+for (const [name, register] of toolRegistry) {
+  if (isToolEnabled(name)) {
+    register(server);
+    registered++;
+  }
+}
+
+const configSource = hasPreflightConfig() ? ".preflight/" : "env vars";
+process.stderr.write(`preflight: profile=${profile}, tools=${registered}, config=${configSource}\n`);
+
+// Graceful shutdown
+function shutdown() {
+  process.stderr.write("preflight: shutting down\n");
+  process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+// Connect transport
+try {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("preflight: server started\n");
+} catch (err) {
+  process.stderr.write(`preflight: failed to start — ${err}\n`);
+  process.exit(1);
+}

package/src/lib/config.ts

@@ -0,0 +1,157 @@
+// =============================================================================
+// Preflight Configuration System
+// =============================================================================
+// Loads configuration from .preflight/ directory if present,
+// falls back to environment variables.
+// =============================================================================
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { load as yamlLoad } from "js-yaml";
+import { PROJECT_DIR } from "./files.js";
+
+export type Profile = "minimal" | "standard" | "full";
+export type EmbeddingProvider = "local" | "openai";
+export type TriageStrictness = "relaxed" | "standard" | "strict";
+
+export interface RelatedProject {
+  path: string;
+  alias: string;
+}
+
+export interface PreflightConfig {
+  profile: Profile;
+  related_projects: RelatedProject[];
+  thresholds: {
+    session_stale_minutes: number;
+    max_tool_calls_before_checkpoint: number;
+    correction_pattern_threshold: number;
+  };
+  embeddings: {
+    provider: EmbeddingProvider;
+    openai_api_key?: string;
+  };
+  triage: {
+    rules: {
+      always_check: string[];
+      skip: string[];
+      cross_service_keywords: string[];
+    };
+    strictness: TriageStrictness;
+  };
+}
+
+// Default configuration (env var fallback)
+const DEFAULT_CONFIG: PreflightConfig = {
+  profile: "standard",
+  related_projects: [],
+  thresholds: {
+    session_stale_minutes: 30,
+    max_tool_calls_before_checkpoint: 100,
+    correction_pattern_threshold: 3,
+  },
+  embeddings: {
+    provider: "local",
+  },
+  triage: {
+    rules: {
+      always_check: ["rewards", "permissions", "migration", "schema"],
+      skip: ["commit", "format", "lint"],
+      cross_service_keywords: ["auth", "notification", "event", "webhook"],
+    },
+    strictness: "standard",
+  },
+};
+
+let _config: PreflightConfig | null = null;
+
+/** Load config from .preflight/ directory or fall back to env vars */
+function loadConfig(): PreflightConfig {
+  const preflightDir = join(PROJECT_DIR, ".preflight");
+  const configPath = join(preflightDir, "config.yml");
+  const triagePath = join(preflightDir, "triage.yml");
+
+  // Start with defaults
+  let config: PreflightConfig = JSON.parse(JSON.stringify(DEFAULT_CONFIG));
+
+  // Load .preflight/config.yml if it exists
+  if (existsSync(configPath)) {
+    try {
+      const configYaml = readFileSync(configPath, "utf-8");
+      const configData = yamlLoad(configYaml) as any;
+      
+      if (configData) {
+        // Merge config data with defaults
+        if (configData.profile) config.profile = configData.profile;
+        if (configData.related_projects) config.related_projects = configData.related_projects;
+        if (configData.thresholds) config.thresholds = { ...config.thresholds, ...configData.thresholds };
+        if (configData.embeddings) config.embeddings = { ...config.embeddings, ...configData.embeddings };
+      }
+    } catch (error) {
+      console.warn(`preflight: warning - failed to parse .preflight/config.yml: ${error}`);
+    }
+  }
+
+  // Load .preflight/triage.yml if it exists
+  if (existsSync(triagePath)) {
+    try {
+      const triageYaml = readFileSync(triagePath, "utf-8");
+      const triageData = yamlLoad(triageYaml) as any;
+      
+      if (triageData) {
+        if (triageData.rules) config.triage.rules = { ...config.triage.rules, ...triageData.rules };
+        if (triageData.strictness) config.triage.strictness = triageData.strictness;
+      }
+    } catch (error) {
+      console.warn(`preflight: warning - failed to parse .preflight/triage.yml: ${error}`);
+    }
+  }
+
+  // Apply environment variable overrides (env vars are fallback, .preflight/ takes precedence)
+  // Only use env vars if .preflight/ directory doesn't exist
+  if (!existsSync(preflightDir)) {
+    // Profile
+    const envProfile = process.env.PROMPT_DISCIPLINE_PROFILE?.toLowerCase();
+    if (envProfile === "minimal" || envProfile === "standard" || envProfile === "full") {
+      config.profile = envProfile;
+    }
+
+    // Related projects
+    const envRelated = process.env.PREFLIGHT_RELATED;
+    if (envRelated) {
+      const projects = envRelated.split(",").map(p => p.trim()).filter(Boolean);
+      config.related_projects = projects.map(path => ({ path, alias: path.split("/").pop() || path }));
+    }
+
+    // Embedding provider
+    const envProvider = process.env.EMBEDDING_PROVIDER?.toLowerCase();
+    if (envProvider === "local" || envProvider === "openai") {
+      config.embeddings.provider = envProvider;
+    }
+
+    // OpenAI API key
+    if (process.env.OPENAI_API_KEY) {
+      config.embeddings.openai_api_key = process.env.OPENAI_API_KEY;
+    }
+  }
+
+  return config;
+}
+
+/** Get the singleton configuration object */
+export function getConfig(): PreflightConfig {
+  if (_config === null) {
+    _config = loadConfig();
+  }
+  return _config;
+}
+
+/** Get related projects as simple path array (backward compatibility) */
+export function getRelatedProjects(): string[] {
+  return getConfig().related_projects.map(p => p.path);
+}
+
+/** Check if .preflight/ directory exists */
+export function hasPreflightConfig(): boolean {
+  return existsSync(join(PROJECT_DIR, ".preflight"));
+}

package/src/lib/embeddings.ts

@@ -0,0 +1,118 @@
+import { pipeline } from "@xenova/transformers";
+
+// --- Types ---
+
+export interface EmbeddingProvider {
+  embed(text: string): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+  dimensions: number;
+}
+
+// --- Text Preprocessing ---
+
+export function preprocessText(text: string): string {
+  let t = text;
+  // Strip markdown formatting
+  t = t.replace(/```[\s\S]*?```/g, " "); // code blocks
+  t = t.replace(/`[^`]+`/g, " "); // inline code
+  t = t.replace(/[#*_~>\[\]()!]/g, ""); // markdown chars
+  t = t.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1"); // links
+  // Normalize whitespace
+  t = t.replace(/\s+/g, " ").trim();
+  // Truncate to ~512 tokens (~2048 chars as rough approximation)
+  if (t.length > 2048) t = t.slice(0, 2048);
+  return t;
+}
+
+// --- Local Provider (Xenova/transformers) ---
+
+let extractor: any = null;
+
+async function getExtractor(): Promise<any> {
+  if (!extractor) {
+    extractor = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
+  }
+  return extractor;
+}
+
+class LocalEmbeddingProvider implements EmbeddingProvider {
+  dimensions = 384;
+
+  async embed(text: string): Promise<number[]> {
+    const ext = await getExtractor();
+    const processed = preprocessText(text);
+    const output = await ext(processed, { pooling: "mean", normalize: true });
+    return Array.from(output.data as Float32Array);
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    const results: number[][] = [];
+    for (const text of texts) {
+      results.push(await this.embed(text));
+    }
+    return results;
+  }
+}
+
+// --- OpenAI Provider ---
+
+class OpenAIEmbeddingProvider implements EmbeddingProvider {
+  dimensions = 1536;
+  private apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const [result] = await this.embedBatch([text]);
+    return result;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    const results: number[][] = [];
+    const processed = texts.map(preprocessText);
+
+    // Batch up to 100 at a time
+    for (let i = 0; i < processed.length; i += 100) {
+      const batch = processed.slice(i, i + 100);
+      const resp = await fetch("https://api.openai.com/v1/embeddings", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ model: "text-embedding-3-small", input: batch }),
+      });
+
+      if (!resp.ok) {
+        const err = await resp.text();
+        throw new Error(`OpenAI embeddings API error ${resp.status}: ${err}`);
+      }
+
+      const data = await resp.json();
+      // Sort by index to preserve order
+      const sorted = data.data.sort((a: any, b: any) => a.index - b.index);
+      for (const item of sorted) {
+        results.push(item.embedding);
+      }
+    }
+
+    return results;
+  }
+}
+
+// --- Factory ---
+
+export interface EmbeddingConfig {
+  provider: "local" | "openai";
+  apiKey?: string;
+}
+
+export function createEmbeddingProvider(config: EmbeddingConfig): EmbeddingProvider {
+  if (config.provider === "openai") {
+    if (!config.apiKey) throw new Error("OpenAI API key required for openai embedding provider");
+    return new OpenAIEmbeddingProvider(config.apiKey);
+  }
+  return new LocalEmbeddingProvider();
+}

package/src/lib/files.ts

@@ -0,0 +1,59 @@
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import type { DocInfo, DocMeta } from "../types.js";
+
+/** Single source of truth for the project directory. */
+export const PROJECT_DIR = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+const MAX_SCAN_DEPTH = 10;
+
+/**
+ * Read a file relative to PROJECT_DIR, returning at most `maxLines` lines.
+ * Returns null if the file doesn't exist or can't be read as UTF-8.
+ */
+export function readIfExists(relPath: string, maxLines = 50): string | null {
+  const full = join(PROJECT_DIR, relPath);
+  if (!existsSync(full)) return null;
+  try {
+    const buf = readFileSync(full);
+    // Reject likely-binary files: check for null bytes in first 8KB
+    if (buf.subarray(0, 8192).includes(0)) return null;
+    const lines = buf.toString("utf-8").split("\n");
+    return lines.slice(0, maxLines).join("\n");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scan .claude/ for markdown docs. Returns content + metadata by default.
+ * Pass `metadataOnly: true` to skip reading file content.
+ */
+export function findWorkspaceDocs(opts?: { metadataOnly?: boolean }): Record<string, DocInfo> {
+  const docs: Record<string, DocInfo> = {};
+  const claudeDir = join(PROJECT_DIR, ".claude");
+  if (!existsSync(claudeDir)) return docs;
+
+  const scanDir = (dir: string, prefix = "", depth = 0): void => {
+    if (depth > MAX_SCAN_DEPTH) return;
+    try {
+      for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        const rel = prefix ? `${prefix}/${entry}` : entry;
+        const stat = statSync(full);
+        if (stat.isDirectory() && !entry.startsWith(".") && !entry.includes("node_modules") && entry !== "preflight-state") {
+          scanDir(full, rel, depth + 1);
+        } else if (entry.endsWith(".md") && stat.size < 50000) {
+          docs[rel] = {
+            content: opts?.metadataOnly ? "" : readFileSync(full, "utf-8").split("\n").slice(0, 40).join("\n"),
+            mtime: stat.mtime,
+            size: stat.size,
+          };
+        }
+      }
+    } catch { /* permission errors, etc. */ }
+  };
+
+  scanDir(claudeDir);
+  return docs;
+}