@vibecheckai/cli 3.5.0 → 3.5.1

package/mcp-server/truth-context.js

@@ -1,16 +1,15 @@
 /**
- * Truth Context – MCP Tools for Evidence‑Backed AI
- *
- * Core context-engine tools that surface **truth-backed** context for AI agents.
- * Every response is grounded in concrete evidence with file/line citations
- * and explicit confidence scores.
- *
- * This is the "Truth Firewall", exposed to agents as an "Evidence Pack" / "Truth Pack". [web:3]
- *
+ * Truth Context - MCP Tools for Evidence-Backed AI
+ * 
+ * Core Context Engine tools that provide truth-backed context for AI agents.
+ * All responses include citations (file/line) and confidence levels.
+ * 
+ * This is the "Truth Firewall" made visible as "Evidence Pack" / "Truth Pack".
+ * 
  * Tools:
- *   - vibecheck.ctx           – Build a repo-level Truth Pack (routes, auth, billing, env, schema)
- *   - vibecheck.verify_claim  – Check whether a claim is backed by real evidence
- *   - vibecheck.evidence      – Pull code-level evidence for a specific file/function
+ *   vibecheck.ctx          - Get repo truth bundle (routes, auth, billing, env, schema)
+ *   vibecheck.verify_claim - Verify a claim has evidence
+ *   vibecheck.evidence     - Get evidence for a specific file/function
  */
 
 import fs from "fs/promises";
@@ -24,72 +23,60 @@ import { execSync } from "child_process";
 export const TRUTH_CONTEXT_TOOLS = [
   {
     name: "vibecheck.ctx",
-    description: `📋 Build a repo Truth Pack: routes, auth, billing, env vars, schema.
-
-Generates an evidence-backed context bundle with file/line citations.
-Use this before the agent makes any architectural or behavioral claims
-about the codebase.
+    description: `📋 Get repo Truth Pack — routes, auth, billing, env vars, schema.
+    
+Returns evidence-backed context with file/line citations.
+Use this before making any claims about the codebase.
 
 Returns:
-- routes: All detected routes with handlers and middleware
-- auth: Auth guards, protected routes, auth flow indicators
-- billing: Payment gates, subscription checks, paid feature indicators
-- env: Environment variables (declared vs used, mismatches)
-- schema: Database schema and TypeScript contracts
-- confidence: Aggregate confidence score (0–1) for the extracted view`,
+- routes: All defined routes with handlers and middleware
+- auth: Auth guards, protected routes, auth flow
+- billing: Payment gates, subscription checks, paid features
+- env: Environment variables (declared vs used)
+- schema: Database schema, API contracts
+- confidence: Overall confidence score (0-1)`,
     inputSchema: {
       type: "object",
       properties: {
         scope: {
           type: "string",
           enum: ["all", "routes", "auth", "billing", "env", "schema"],
-          description: "Which slice of context to extract (default: all)",
+          description: "What context to extract (default: all)",
           default: "all",
         },
         path: {
           type: "string",
-          description: "Project root path (default: current working directory)",
+          description: "Project path (default: current directory)",
         },
       },
     },
   },
   {
     name: "vibecheck.verify_claim",
-    description: `🔍 Truth Firewall check – verify that a claim is backed by code.
-
-Run this before asserting that something exists, is configured, or is enforced.
-Returns concrete evidence (file/line) when the claim is supported,
-or a structured rejection with an explanation when it is not.
+    description: `🔍 Verify a claim has evidence — Truth Firewall check.
+    
+Before claiming something exists or works, verify it.
+Returns evidence (file/line) or rejection with reason.
 
 Examples:
-- "Route /api/users exists"        → VERIFIED with handler at src/routes/users.ts:45
-- "Auth is required for /admin"    → VERIFIED via middleware at src/middleware/auth.ts:12
-- "Stripe is configured"           → REJECTED: No evidence of Stripe integration found`,
+- "Route /api/users exists" → Verified with handler at src/routes/users.ts:45
+- "Auth is required for /admin" → Verified with middleware at src/middleware/auth.ts:12
+- "Stripe is configured" → REJECTED: No evidence of Stripe integration found`,
     inputSchema: {
       type: "object",
       properties: {
         claim_type: {
           type: "string",
-          enum: [
-            "route",
-            "endpoint",
-            "env_var",
-            "middleware",
-            "auth_guard",
-            "billing_gate",
-            "file",
-            "function",
-          ],
-          description: "Category of claim to verify",
+          enum: ["route", "endpoint", "env_var", "middleware", "auth_guard", "billing_gate", "file", "function"],
+          description: "Type of claim to verify",
         },
         claim: {
           type: "string",
-          description:
-            "The claim subject (e.g. '/api/users', 'AUTH_SECRET', 'authMiddleware')",
+          description: "The claim to verify (e.g., '/api/users', 'AUTH_SECRET', 'authMiddleware')",
         },
         path: {
           type: "string",
-          description: "Project root path (default: current working directory)",
+          description: "Project path (default: current directory)",
         },
       },
       required: ["claim_type", "claim"],
@@ -97,35 +84,33 @@ Examples:
   },
   {
     name: "vibecheck.evidence",
-    description: `📎 Retrieve code evidence for a file or symbol.
-
-Returns an annotated code snippet with line numbers for precise citation.
-Use this when the agent needs to quote or reason about specific code blocks
-in its response.`,
+    description: `📎 Get evidence for a file/function — citations with context.
+    
+Returns the actual code with line numbers for citation.
+Use this when you need to reference specific code in your response.`,
     inputSchema: {
       type: "object",
       properties: {
         file: {
           type: "string",
-          description: "File path relative to the project root",
+          description: "File path relative to project root",
         },
         function_name: {
           type: "string",
-          description: "Optional function/class name to locate within the file",
+          description: "Optional function/class name to find",
         },
         line: {
           type: "number",
-          description: "Optional 1-based line number to center the snippet on",
+          description: "Optional specific line number",
         },
         context_lines: {
           type: "number",
-          description:
-            "Number of lines of context before/after the target (default: 10)",
+          description: "Lines of context around target (default: 10)",
           default: 10,
         },
         path: {
           type: "string",
-          description: "Project root path (default: current working directory)",
+          description: "Project path (default: current directory)",
         },
       },
       required: ["file"],
@@ -134,7 +119,7 @@ in its response.`,
 ];
 
 // ============================================================================
-// TOOL DISPATCH
+// TOOL HANDLERS
 // ============================================================================
 
 export async function handleTruthContextTool(toolName, args) {
@@ -183,11 +168,10 @@ async function getTruthPack(projectPath, scope) {
       truthPack.sections.schema = await extractSchema(projectPath);
     }
 
+    // Calculate overall confidence
     const sections = Object.values(truthPack.sections);
     if (sections.length > 0) {
-      truthPack.confidence =
-        sections.reduce((sum, section) => sum + (section.confidence || 0), 0) /
-        sections.length;
+      truthPack.confidence = sections.reduce((sum, s) => sum + (s.confidence || 0), 0) / sections.length;
     }
 
     return truthPack;
@@ -195,7 +179,7 @@ async function getTruthPack(projectPath, scope) {
     return {
       error: error.message,
       projectPath,
-      suggestion: "Run `vibecheck init` to set up the project",
+      suggestion: "Run 'vibecheck init' to set up the project",
     };
   }
 }
@@ -209,12 +193,12 @@ async function extractRoutes(projectPath) {
   ];
 
   const files = await findSourceFiles(projectPath, [".ts", ".js", ".tsx", ".jsx"]);
-
-  for (const file of files.slice(0, 50)) {
+  
+  for (const file of files.slice(0, 50)) { // Limit for performance
     try {
       const content = await fs.readFile(file, "utf8");
       const relPath = path.relative(projectPath, file);
-
+      
       for (const pattern of routePatterns) {
         let match;
         pattern.lastIndex = 0;
@@ -239,7 +223,7 @@ async function extractRoutes(projectPath) {
 
   return {
     count: routes.length,
-    routes: routes.slice(0, 100),
+    routes: routes.slice(0, 100), // Limit output
     confidence: routes.length > 0 ? 0.8 : 0.2,
   };
 }
@@ -254,12 +238,12 @@ async function extractAuth(projectPath) {
   ];
 
   const files = await findSourceFiles(projectPath, [".ts", ".js"]);
-
+  
   for (const file of files.slice(0, 50)) {
     try {
       const content = await fs.readFile(file, "utf8");
       const relPath = path.relative(projectPath, file);
-
+      
       for (const pattern of authPatterns) {
         let match;
         pattern.lastIndex = 0;
@@ -281,12 +265,7 @@ async function extractAuth(projectPath) {
   return {
     count: authIndicators.length,
     indicators: authIndicators.slice(0, 50),
-    confidence:
-      authIndicators.length > 5
-        ? 0.8
-        : authIndicators.length > 0
-        ? 0.5
-        : 0.1,
+    confidence: authIndicators.length > 5 ? 0.8 : authIndicators.length > 0 ? 0.5 : 0.1,
   };
 }
 
@@ -300,12 +279,12 @@ async function extractBilling(projectPath) {
   ];
 
   const files = await findSourceFiles(projectPath, [".ts", ".js"]);
-
+  
   for (const file of files.slice(0, 30)) {
     try {
       const content = await fs.readFile(file, "utf8");
       const relPath = path.relative(projectPath, file);
-
+      
       for (const pattern of billingPatterns) {
         let match;
         pattern.lastIndex = 0;
@@ -327,12 +306,7 @@ async function extractBilling(projectPath) {
   return {
     count: billingIndicators.length,
     indicators: billingIndicators.slice(0, 30),
-    confidence:
-      billingIndicators.length > 3
-        ? 0.7
-        : billingIndicators.length > 0
-        ? 0.4
-        : 0.1,
+    confidence: billingIndicators.length > 3 ? 0.7 : billingIndicators.length > 0 ? 0.4 : 0.1,
   };
 }
 
@@ -340,6 +314,7 @@ async function extractEnvVars(projectPath) {
   const declared = [];
   const used = [];
 
+  // Check .env.example, .env.local.example, etc.
   const envFiles = [".env.example", ".env.local.example", ".env.sample"];
   for (const envFile of envFiles) {
     try {
@@ -356,10 +331,11 @@ async function extractEnvVars(projectPath) {
         }
       }
     } catch {
-      // File does not exist
+      // File doesn't exist
     }
   }
 
+  // Find process.env usage in code
   const files = await findSourceFiles(projectPath, [".ts", ".js"]);
   for (const file of files.slice(0, 30)) {
     try {
@@ -380,10 +356,11 @@ async function extractEnvVars(projectPath) {
     }
   }
 
-  const declaredNames = new Set(declared.map((d) => d.name));
-  const usedNames = new Set(used.map((u) => u.name));
-  const undeclared = [...usedNames].filter((name) => !declaredNames.has(name));
-  const unused = [...declaredNames].filter((name) => !usedNames.has(name));
+  // Find mismatches
+  const declaredNames = new Set(declared.map(d => d.name));
+  const usedNames = new Set(used.map(u => u.name));
+  const undeclared = [...usedNames].filter(n => !declaredNames.has(n));
+  const unused = [...declaredNames].filter(n => !usedNames.has(n));
 
   return {
     declared: declared.slice(0, 50),
@@ -399,6 +376,7 @@ async function extractEnvVars(projectPath) {
 async function extractSchema(projectPath) {
   const schemas = [];
 
+  // Check for Prisma schema
   try {
     const prismaPath = path.join(projectPath, "prisma", "schema.prisma");
     const content = await fs.readFile(prismaPath, "utf8");
@@ -411,15 +389,16 @@ async function extractSchema(projectPath) {
       });
     }
   } catch {
-    // No Prisma schema
+    // No Prisma
   }
 
+  // Check for TypeScript types/interfaces
   const files = await findSourceFiles(projectPath, [".ts", ".tsx"]);
   for (const file of files.slice(0, 20)) {
     try {
       const content = await fs.readFile(file, "utf8");
       const relPath = path.relative(projectPath, file);
-
+      
       const typeMatches = content.matchAll(/(?:interface|type)\s+(\w+)/g);
       for (const match of typeMatches) {
         const line = content.substring(0, match.index).split("\n").length;
@@ -438,8 +417,7 @@ async function extractSchema(projectPath) {
   return {
     count: schemas.length,
     schemas: schemas.slice(0, 50),
-    confidence:
-      schemas.length > 5 ? 0.7 : schemas.length > 0 ? 0.4 : 0.2,
+    confidence: schemas.length > 5 ? 0.7 : schemas.length > 0 ? 0.4 : 0.2,
   };
 }
 
@@ -458,7 +436,7 @@ async function verifyClaim(projectPath, claimType, claim) {
 
   try {
     switch (claimType) {
-      case "file": {
+      case "file":
         const filePath = path.join(projectPath, claim);
         try {
           await fs.access(filePath);
@@ -475,14 +453,11 @@ async function verifyClaim(projectPath, claimType, claim) {
           result.rejection = `File does not exist: ${claim}`;
         }
         break;
-      }
 
       case "route":
-      case "endpoint": {
+      case "endpoint":
         const routes = await extractRoutes(projectPath);
-        const matchingRoute = routes.routes.find(
-          (route) => route.path === claim || route.path.includes(claim),
-        );
+        const matchingRoute = routes.routes.find(r => r.path === claim || r.path.includes(claim));
         if (matchingRoute) {
           result.verified = true;
           result.confidence = 0.9;
@@ -491,31 +466,26 @@ async function verifyClaim(projectPath, claimType, claim) {
           result.rejection = `No route matching "${claim}" found in codebase`;
         }
         break;
-      }
 
-      case "env_var": {
+      case "env_var":
         const envData = await extractEnvVars(projectPath);
-        const isDeclared = envData.declared.some((env) => env.name === claim);
-        const isUsed = envData.used.some((env) => env.name === claim);
+        const isDeclared = envData.declared.some(d => d.name === claim);
+        const isUsed = envData.used.some(u => u.name === claim);
         if (isDeclared || isUsed) {
           result.verified = true;
           result.confidence = isDeclared && isUsed ? 1.0 : 0.7;
           result.evidence = {
             declared: isDeclared,
             used: isUsed,
-            locations: [
-              ...envData.declared.filter((env) => env.name === claim),
-              ...envData.used.filter((env) => env.name === claim),
-            ],
+            locations: [...envData.declared.filter(d => d.name === claim), ...envData.used.filter(u => u.name === claim)],
           };
         } else {
           result.rejection = `Environment variable "${claim}" not found`;
         }
         break;
-      }
 
       default:
-        result.rejection = `Claim type "${claimType}" verification is not implemented yet`;
+        result.rejection = `Claim type "${claimType}" verification not yet implemented`;
     }
   } catch (error) {
     result.rejection = `Verification error: ${error.message}`;
@@ -530,19 +500,17 @@ async function verifyClaim(projectPath, claimType, claim) {
 
 async function getEvidence(projectPath, file, options) {
   const filePath = path.join(projectPath, file);
-
+  
   try {
     const content = await fs.readFile(filePath, "utf8");
     const lines = content.split("\n");
-
+    
     let targetLine = options.line || 1;
     const contextLines = options.context_lines || 10;
-
+    
+    // If function_name provided, find it
     if (options.function_name) {
-      const pattern = new RegExp(
-        `(function|const|let|var|class)\\s+${options.function_name}`,
-        "i",
-      );
+      const pattern = new RegExp(`(function|const|let|var|class)\\s+${options.function_name}`, "i");
       for (let i = 0; i < lines.length; i++) {
         if (pattern.test(lines[i])) {
           targetLine = i + 1;
@@ -550,18 +518,14 @@ async function getEvidence(projectPath, file, options) {
         }
       }
     }
-
+    
     const startLine = Math.max(1, targetLine - contextLines);
     const endLine = Math.min(lines.length, targetLine + contextLines);
-
-    const snippet = lines
-      .slice(startLine - 1, endLine)
-      .map(
-        (line, index) =>
-          `${String(startLine + index).padStart(4, " ")} | ${line}`,
-      )
+    
+    const snippet = lines.slice(startLine - 1, endLine)
+      .map((line, i) => `${String(startLine + i).padStart(4, " ")} | ${line}`)
       .join("\n");
-
+    
     return {
       file,
       targetLine,
@@ -585,19 +549,14 @@ async function getEvidence(projectPath, file, options) {
 
 async function findSourceFiles(projectPath, extensions) {
   const files = [];
-
+  
   async function walk(dir) {
     try {
       const entries = await fs.readdir(dir, { withFileTypes: true });
       for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-          if (
-            !entry.name.startsWith(".") &&
-            entry.name !== "node_modules" &&
-            entry.name !== "dist" &&
-            entry.name !== "build"
-          ) {
+          if (!entry.name.startsWith(".") && entry.name !== "node_modules" && entry.name !== "dist" && entry.name !== "build") {
             await walk(fullPath);
           }
         } else if (entry.isFile()) {
@@ -611,7 +570,7 @@ async function findSourceFiles(projectPath, extensions) {
       // Skip inaccessible directories
     }
   }
-
+  
   await walk(projectPath);
   return files;
 }