@vibecheckai/cli 3.2.0 → 3.2.2

package/mcp-server/truth-context.js

@@ -1,15 +1,16 @@
 /**
- * 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".
- * 
+ * 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]
+ *
  * Tools:
- *   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
+ *   - 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
  */
 
 import fs from "fs/promises";
@@ -23,60 +24,72 @@ import { execSync } from "child_process";
 export const TRUTH_CONTEXT_TOOLS = [
   {
     name: "vibecheck.ctx",
-    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.
+    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.
 
 Returns:
-- 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)`,
+- 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`,
     inputSchema: {
       type: "object",
       properties: {
         scope: {
           type: "string",
           enum: ["all", "routes", "auth", "billing", "env", "schema"],
-          description: "What context to extract (default: all)",
+          description: "Which slice of context to extract (default: all)",
           default: "all",
         },
         path: {
           type: "string",
-          description: "Project path (default: current directory)",
+          description: "Project root path (default: current working directory)",
         },
       },
     },
   },
   {
     name: "vibecheck.verify_claim",
-    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.
+    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.
 
 Examples:
-- "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`,
+- "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`,
     inputSchema: {
       type: "object",
       properties: {
         claim_type: {
           type: "string",
-          enum: ["route", "endpoint", "env_var", "middleware", "auth_guard", "billing_gate", "file", "function"],
-          description: "Type of claim to verify",
+          enum: [
+            "route",
+            "endpoint",
+            "env_var",
+            "middleware",
+            "auth_guard",
+            "billing_gate",
+            "file",
+            "function",
+          ],
+          description: "Category of claim to verify",
         },
         claim: {
           type: "string",
-          description: "The claim to verify (e.g., '/api/users', 'AUTH_SECRET', 'authMiddleware')",
+          description:
+            "The claim subject (e.g. '/api/users', 'AUTH_SECRET', 'authMiddleware')",
         },
         path: {
           type: "string",
-          description: "Project path (default: current directory)",
+          description: "Project root path (default: current working directory)",
         },
       },
       required: ["claim_type", "claim"],
@@ -84,33 +97,35 @@ Examples:
   },
   {
     name: "vibecheck.evidence",
-    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.`,
+    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.`,
     inputSchema: {
       type: "object",
       properties: {
         file: {
           type: "string",
-          description: "File path relative to project root",
+          description: "File path relative to the project root",
         },
         function_name: {
           type: "string",
-          description: "Optional function/class name to find",
+          description: "Optional function/class name to locate within the file",
         },
         line: {
           type: "number",
-          description: "Optional specific line number",
+          description: "Optional 1-based line number to center the snippet on",
         },
         context_lines: {
           type: "number",
-          description: "Lines of context around target (default: 10)",
+          description:
+            "Number of lines of context before/after the target (default: 10)",
           default: 10,
         },
         path: {
           type: "string",
-          description: "Project path (default: current directory)",
+          description: "Project root path (default: current working directory)",
         },
       },
       required: ["file"],
@@ -119,7 +134,7 @@ Use this when you need to reference specific code in your response.`,
 ];
 
 // ============================================================================
-// TOOL HANDLERS
+// TOOL DISPATCH
 // ============================================================================
 
 export async function handleTruthContextTool(toolName, args) {
@@ -168,10 +183,11 @@ 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, s) => sum + (s.confidence || 0), 0) / sections.length;
+      truthPack.confidence =
+        sections.reduce((sum, section) => sum + (section.confidence || 0), 0) /
+        sections.length;
     }
 
     return truthPack;
@@ -179,7 +195,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",
     };
   }
 }
@@ -193,12 +209,12 @@ async function extractRoutes(projectPath) {
   ];
 
   const files = await findSourceFiles(projectPath, [".ts", ".js", ".tsx", ".jsx"]);
-  
-  for (const file of files.slice(0, 50)) { // Limit for performance
+
+  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 routePatterns) {
         let match;
         pattern.lastIndex = 0;
@@ -223,7 +239,7 @@ async function extractRoutes(projectPath) {
 
   return {
     count: routes.length,
-    routes: routes.slice(0, 100), // Limit output
+    routes: routes.slice(0, 100),
     confidence: routes.length > 0 ? 0.8 : 0.2,
   };
 }
@@ -238,12 +254,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;
@@ -265,7 +281,12 @@ 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,
   };
 }
 
@@ -279,12 +300,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;
@@ -306,7 +327,12 @@ 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,
   };
 }
 
@@ -314,7 +340,6 @@ 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 {
@@ -331,11 +356,10 @@ async function extractEnvVars(projectPath) {
         }
       }
     } catch {
-      // File doesn't exist
+      // File does not exist
     }
   }
 
-  // Find process.env usage in code
   const files = await findSourceFiles(projectPath, [".ts", ".js"]);
   for (const file of files.slice(0, 30)) {
     try {
@@ -356,11 +380,10 @@ async function extractEnvVars(projectPath) {
     }
   }
 
-  // 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));
+  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));
 
   return {
     declared: declared.slice(0, 50),
@@ -376,7 +399,6 @@ 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");
@@ -389,16 +411,15 @@ async function extractSchema(projectPath) {
       });
     }
   } catch {
-    // No Prisma
+    // No Prisma schema
   }
 
-  // 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;
@@ -417,7 +438,8 @@ 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,
   };
 }
 
@@ -436,7 +458,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);
@@ -453,11 +475,14 @@ 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(r => r.path === claim || r.path.includes(claim));
+        const matchingRoute = routes.routes.find(
+          (route) => route.path === claim || route.path.includes(claim),
+        );
         if (matchingRoute) {
           result.verified = true;
           result.confidence = 0.9;
@@ -466,26 +491,31 @@ 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(d => d.name === claim);
-        const isUsed = envData.used.some(u => u.name === claim);
+        const isDeclared = envData.declared.some((env) => env.name === claim);
+        const isUsed = envData.used.some((env) => env.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(d => d.name === claim), ...envData.used.filter(u => u.name === claim)],
+            locations: [
+              ...envData.declared.filter((env) => env.name === claim),
+              ...envData.used.filter((env) => env.name === claim),
+            ],
           };
         } else {
           result.rejection = `Environment variable "${claim}" not found`;
         }
         break;
+      }
 
       default:
-        result.rejection = `Claim type "${claimType}" verification not yet implemented`;
+        result.rejection = `Claim type "${claimType}" verification is not implemented yet`;
     }
   } catch (error) {
     result.rejection = `Verification error: ${error.message}`;
@@ -500,17 +530,19 @@ 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;
@@ -518,14 +550,18 @@ 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, i) => `${String(startLine + i).padStart(4, " ")} | ${line}`)
+
+    const snippet = lines
+      .slice(startLine - 1, endLine)
+      .map(
+        (line, index) =>
+          `${String(startLine + index).padStart(4, " ")} | ${line}`,
+      )
       .join("\n");
-    
+
     return {
       file,
       targetLine,
@@ -549,14 +585,19 @@ 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()) {
@@ -570,7 +611,7 @@ async function findSourceFiles(projectPath, extensions) {
       // Skip inaccessible directories
     }
   }
-  
+
   await walk(projectPath);
   return files;
 }