@vibecheckai/cli 2.8.2 → 3.0.0

package/bin/runners/lib/contracts/guard.js

@@ -0,0 +1,168 @@
+/**
+ * Contract Guard
+ * Validates code against contracts - CI gate functionality
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { validateAgainstRouteContract } = require("./route-contract");
+const { validateAgainstEnvContract } = require("./env-contract");
+const { validateAuthContract } = require("./auth-contract");
+const { validateExternalContract } = require("./external-contract");
+
+/**
+ * Load contracts from .vibecheck/contracts/
+ */
+function loadContracts(repoRoot) {
+  const contractDir = path.join(repoRoot, ".vibecheck", "contracts");
+  const contracts = {};
+
+  const files = {
+    routes: "routes.json",
+    env: "env.json",
+    auth: "auth.json",
+    external: "external.json"
+  };
+
+  for (const [key, file] of Object.entries(files)) {
+    const filePath = path.join(contractDir, file);
+    if (fs.existsSync(filePath)) {
+      try {
+        contracts[key] = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      } catch (e) {
+        console.warn(`Warning: Could not parse ${file}: ${e.message}`);
+      }
+    }
+  }
+
+  return contracts;
+}
+
+/**
+ * Save contracts to .vibecheck/contracts/
+ */
+function saveContracts(repoRoot, contracts) {
+  const contractDir = path.join(repoRoot, ".vibecheck", "contracts");
+  fs.mkdirSync(contractDir, { recursive: true });
+
+  const files = {
+    routes: "routes.json",
+    env: "env.json",
+    auth: "auth.json",
+    external: "external.json"
+  };
+
+  for (const [key, file] of Object.entries(files)) {
+    if (contracts[key]) {
+      const filePath = path.join(contractDir, file);
+      fs.writeFileSync(filePath, JSON.stringify(contracts[key], null, 2), "utf8");
+    }
+  }
+}
+
+/**
+ * Guard: Validate current code against contracts
+ */
+function guardContracts(contracts, truthpack, options = {}) {
+  const violations = [];
+
+  // Route contract validation
+  if (contracts.routes && truthpack?.routes?.clientRefs) {
+    const routeViolations = validateAgainstRouteContract(
+      contracts.routes,
+      truthpack.routes.clientRefs
+    );
+    violations.push(...routeViolations);
+  }
+
+  // Env contract validation
+  if (contracts.env && truthpack?.env?.vars) {
+    const envViolations = validateAgainstEnvContract(
+      contracts.env,
+      truthpack.env.vars
+    );
+    violations.push(...envViolations);
+  }
+
+  // Auth contract validation
+  if (contracts.auth && truthpack?.routes?.server) {
+    const authViolations = validateAuthContract(
+      contracts.auth,
+      truthpack.routes.server,
+      options.realityResults
+    );
+    violations.push(...authViolations);
+  }
+
+  // External contract validation
+  if (contracts.external) {
+    const externalViolations = validateExternalContract(contracts.external);
+    violations.push(...externalViolations);
+  }
+
+  return {
+    valid: violations.filter(v => v.severity === "BLOCK").length === 0,
+    violations,
+    blocks: violations.filter(v => v.severity === "BLOCK"),
+    warns: violations.filter(v => v.severity === "WARN")
+  };
+}
+
+/**
+ * Get guard summary for CI output
+ */
+function getGuardSummary(guardResult) {
+  const { valid, blocks, warns } = guardResult;
+
+  return {
+    verdict: valid ? (warns.length ? "WARN" : "PASS") : "BLOCK",
+    exitCode: valid ? (warns.length ? 1 : 0) : 2,
+    summary: {
+      blocks: blocks.length,
+      warns: warns.length,
+      total: blocks.length + warns.length
+    },
+    violations: guardResult.violations
+  };
+}
+
+/**
+ * Format guard result for console output
+ */
+function formatGuardResult(guardResult) {
+  const lines = [];
+  const { violations, blocks, warns } = guardResult;
+
+  if (violations.length === 0) {
+    lines.push("✓ All contracts satisfied");
+    return lines.join("\n");
+  }
+
+  if (blocks.length > 0) {
+    lines.push(`\n🛑 BLOCKS (${blocks.length}):`);
+    for (const v of blocks) {
+      lines.push(`  ✗ [${v.type}] ${v.message}`);
+      if (v.route) lines.push(`    Route: ${v.route}`);
+      if (v.name) lines.push(`    Var: ${v.name}`);
+    }
+  }
+
+  if (warns.length > 0) {
+    lines.push(`\n⚠️ WARNINGS (${warns.length}):`);
+    for (const v of warns) {
+      lines.push(`  ⚠ [${v.type}] ${v.message}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  loadContracts,
+  saveContracts,
+  guardContracts,
+  getGuardSummary,
+  formatGuardResult
+};

package/bin/runners/lib/contracts/index.js

@@ -0,0 +1,89 @@
+/**
+ * Context Contracts - Module Index
+ * 
+ * Exports all contract functionality for CLI and MCP use
+ */
+
+"use strict";
+
+const { buildRouteContract, validateAgainstRouteContract, diffRouteContracts } = require("./route-contract");
+const { buildEnvContract, validateAgainstEnvContract, diffEnvContracts } = require("./env-contract");
+const { buildAuthContract, validateAuthContract, diffAuthContracts } = require("./auth-contract");
+const { buildExternalContract, validateExternalContract, diffExternalContracts } = require("./external-contract");
+const { loadContracts, saveContracts, guardContracts, getGuardSummary, formatGuardResult } = require("./guard");
+const { validatePlan, parsePlanActions, formatValidationResult } = require("./plan-validator");
+
+/**
+ * Build all contracts from truthpack
+ */
+function buildAllContracts(truthpack) {
+  return {
+    routes: buildRouteContract(truthpack),
+    env: buildEnvContract(truthpack),
+    auth: buildAuthContract(truthpack),
+    external: buildExternalContract(truthpack)
+  };
+}
+
+/**
+ * Diff all contracts
+ */
+function diffAllContracts(before, after) {
+  return {
+    routes: before.routes && after.routes ? diffRouteContracts(before.routes, after.routes) : null,
+    env: before.env && after.env ? diffEnvContracts(before.env, after.env) : null,
+    auth: before.auth && after.auth ? diffAuthContracts(before.auth, after.auth) : null,
+    external: before.external && after.external ? diffExternalContracts(before.external, after.external) : null
+  };
+}
+
+/**
+ * Check if contracts have meaningful changes
+ */
+function hasContractChanges(diff) {
+  if (!diff) return false;
+  
+  const checkDiff = (d) => {
+    if (!d) return false;
+    return (d.added?.length > 0) || (d.removed?.length > 0) || (d.changed?.length > 0) ||
+           (d.protectedAdded?.length > 0) || (d.protectedRemoved?.length > 0);
+  };
+
+  return checkDiff(diff.routes) || checkDiff(diff.env) || 
+         checkDiff(diff.auth) || checkDiff(diff.external);
+}
+
+module.exports = {
+  // Contract builders
+  buildRouteContract,
+  buildEnvContract,
+  buildAuthContract,
+  buildExternalContract,
+  buildAllContracts,
+  
+  // Contract validation
+  validateAgainstRouteContract,
+  validateAgainstEnvContract,
+  validateAuthContract,
+  validateExternalContract,
+  
+  // Contract diffing
+  diffRouteContracts,
+  diffEnvContracts,
+  diffAuthContracts,
+  diffExternalContracts,
+  diffAllContracts,
+  hasContractChanges,
+  
+  // Guard (CI gate)
+  loadContracts,
+  saveContracts,
+  guardContracts,
+  getGuardSummary,
+  formatGuardResult,
+  
+  // Plan validation (hallucination stopper)
+  validatePlan,
+  parsePlanActions,
+  formatValidationResult
+};

package/bin/runners/lib/contracts/plan-validator.js

@@ -0,0 +1,311 @@
+/**
+ * Plan Validator
+ * Validates AI agent plans against contracts
+ * This is the core of the "hallucination stopper"
+ */
+
+"use strict";
+
+/**
+ * Validate an AI-generated plan against contracts
+ * Returns validation result with specific violations
+ */
+function validatePlan(plan, contracts) {
+  const result = {
+    valid: true,
+    violations: [],
+    warnings: [],
+    suggestions: []
+  };
+
+  // Parse plan to extract intended actions
+  const actions = parsePlanActions(plan);
+
+  // Validate route references
+  if (contracts.routes) {
+    const routeResult = validateRouteActions(actions, contracts.routes);
+    result.violations.push(...routeResult.violations);
+    result.warnings.push(...routeResult.warnings);
+  }
+
+  // Validate env references
+  if (contracts.env) {
+    const envResult = validateEnvActions(actions, contracts.env);
+    result.violations.push(...envResult.violations);
+    result.warnings.push(...envResult.warnings);
+  }
+
+  // Validate auth assumptions
+  if (contracts.auth) {
+    const authResult = validateAuthActions(actions, contracts.auth);
+    result.violations.push(...authResult.violations);
+    result.warnings.push(...authResult.warnings);
+  }
+
+  // Validate external service usage
+  if (contracts.external) {
+    const externalResult = validateExternalActions(actions, contracts.external);
+    result.violations.push(...externalResult.violations);
+    result.warnings.push(...externalResult.warnings);
+  }
+
+  result.valid = result.violations.length === 0;
+  return result;
+}
+
+/**
+ * Parse plan to extract intended actions
+ */
+function parsePlanActions(plan) {
+  const actions = {
+    routes: [],
+    envVars: [],
+    files: [],
+    authAssumptions: [],
+    externalCalls: []
+  };
+
+  // Handle different plan formats
+  const planText = typeof plan === "string" ? plan : JSON.stringify(plan);
+
+  // Extract route references
+  const routePatterns = [
+    /(?:fetch|axios|api\.)\s*\(\s*['"`]([/][^'"`]+)['"`]/gi,
+    /(?:GET|POST|PUT|PATCH|DELETE)\s+([/][^\s]+)/gi,
+    /\/api\/[a-z0-9/_-]+/gi
+  ];
+
+  for (const pattern of routePatterns) {
+    let match;
+    while ((match = pattern.exec(planText)) !== null) {
+      const path = match[1] || match[0];
+      if (path.startsWith("/")) {
+        actions.routes.push({
+          path: path.replace(/['"`]/g, ""),
+          method: inferMethod(match[0])
+        });
+      }
+    }
+  }
+
+  // Extract env var references
+  const envPatterns = [
+    /process\.env\.([A-Z_][A-Z0-9_]*)/gi,
+    /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/gi,
+    /\$\{?([A-Z_][A-Z0-9_]*)\}?/g
+  ];
+
+  for (const pattern of envPatterns) {
+    let match;
+    while ((match = pattern.exec(planText)) !== null) {
+      if (match[1] && /^[A-Z]/.test(match[1])) {
+        actions.envVars.push(match[1]);
+      }
+    }
+  }
+
+  // Extract file references
+  const filePatterns = [
+    /(?:create|modify|edit|update|delete|add to)\s+['"`]?([a-z0-9/_.-]+\.[a-z]+)['"`]?/gi,
+    /(?:in|at|file)\s+['"`]([^'"`]+)['"`]/gi
+  ];
+
+  for (const pattern of filePatterns) {
+    let match;
+    while ((match = pattern.exec(planText)) !== null) {
+      if (match[1]) {
+        actions.files.push(match[1]);
+      }
+    }
+  }
+
+  // Extract auth assumptions
+  const authPatterns = [
+    /(?:authenticated|logged in|auth required|protected)/gi,
+    /(?:public|no auth|unauthenticated)/gi
+  ];
+
+  if (/(?:authenticated|logged in|auth required|protected)/i.test(planText)) {
+    actions.authAssumptions.push({ type: "requires_auth" });
+  }
+  if (/(?:public|no auth|unauthenticated)/i.test(planText)) {
+    actions.authAssumptions.push({ type: "no_auth" });
+  }
+
+  // Extract external service references
+  const externalPatterns = [
+    /stripe\./gi,
+    /github\./gi,
+    /sendgrid\./gi,
+    /twilio\./gi,
+    /supabase\./gi
+  ];
+
+  for (const pattern of externalPatterns) {
+    if (pattern.test(planText)) {
+      const service = pattern.source.replace(/\\\./g, "").toLowerCase();
+      actions.externalCalls.push({ service });
+    }
+  }
+
+  return actions;
+}
+
+function inferMethod(text) {
+  const upper = text.toUpperCase();
+  if (upper.includes("POST")) return "POST";
+  if (upper.includes("PUT")) return "PUT";
+  if (upper.includes("PATCH")) return "PATCH";
+  if (upper.includes("DELETE")) return "DELETE";
+  return "GET";
+}
+
+/**
+ * Validate route actions against contract
+ */
+function validateRouteActions(actions, routeContract) {
+  const violations = [];
+  const warnings = [];
+  const contractRoutes = new Set(routeContract.routes.map(r => r.path));
+
+  for (const route of actions.routes) {
+    // Check exact match
+    if (!contractRoutes.has(route.path)) {
+      // Check parameterized match
+      const match = routeContract.routes.find(r => matchesParameterized(r.path, route.path));
+      
+      if (!match) {
+        violations.push({
+          type: "invented_route",
+          severity: "BLOCK",
+          route: route.path,
+          method: route.method,
+          message: `Plan references route ${route.method} ${route.path} which does not exist in contract`,
+          suggestion: `Available routes: ${routeContract.routes.slice(0, 5).map(r => r.path).join(", ")}...`
+        });
+      }
+    }
+  }
+
+  return { violations, warnings };
+}
+
+/**
+ * Validate env actions against contract
+ */
+function validateEnvActions(actions, envContract) {
+  const violations = [];
+  const warnings = [];
+  const contractVars = new Set(envContract.vars.map(v => v.name));
+
+  for (const varName of actions.envVars) {
+    if (!contractVars.has(varName)) {
+      warnings.push({
+        type: "undeclared_env",
+        severity: "WARN",
+        name: varName,
+        message: `Plan uses env var ${varName} which is not in contract`,
+        suggestion: "Add to .vibecheck/contracts/env.json or .env.example"
+      });
+    }
+  }
+
+  return { violations, warnings };
+}
+
+/**
+ * Validate auth actions against contract
+ */
+function validateAuthActions(actions, authContract) {
+  const violations = [];
+  const warnings = [];
+
+  // Check for auth assumptions that conflict with contract
+  for (const assumption of actions.authAssumptions) {
+    if (assumption.type === "no_auth") {
+      // Plan assumes no auth - check if referenced routes are actually public
+      warnings.push({
+        type: "auth_assumption",
+        severity: "WARN",
+        message: "Plan assumes some routes are public - verify against auth contract",
+        suggestion: `Protected patterns: ${authContract.protectedPatterns.slice(0, 3).join(", ")}...`
+      });
+    }
+  }
+
+  return { violations, warnings };
+}
+
+/**
+ * Validate external service actions against contract
+ */
+function validateExternalActions(actions, externalContract) {
+  const violations = [];
+  const warnings = [];
+  const contractServices = new Set(externalContract.services.map(s => s.name));
+
+  for (const call of actions.externalCalls) {
+    if (!contractServices.has(call.service)) {
+      warnings.push({
+        type: "undeclared_service",
+        severity: "WARN",
+        service: call.service,
+        message: `Plan uses ${call.service} which is not declared in external contract`,
+        suggestion: "Add to .vibecheck/contracts/external.json"
+      });
+    }
+  }
+
+  return { violations, warnings };
+}
+
+function matchesParameterized(pattern, actual) {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const actualParts = actual.split("/").filter(Boolean);
+
+  if (patternParts.length !== actualParts.length) return false;
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const p = patternParts[i];
+    if (p.startsWith(":") || p.startsWith("*")) continue;
+    if (p !== actualParts[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Format validation result for display
+ */
+function formatValidationResult(result) {
+  const lines = [];
+
+  if (result.valid) {
+    lines.push("✓ Plan validated against contracts");
+  } else {
+    lines.push("✗ Plan validation failed");
+  }
+
+  if (result.violations.length > 0) {
+    lines.push(`\n🛑 VIOLATIONS (${result.violations.length}):`);
+    for (const v of result.violations) {
+      lines.push(`  ✗ ${v.message}`);
+      if (v.suggestion) lines.push(`    → ${v.suggestion}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push(`\n⚠️ WARNINGS (${result.warnings.length}):`);
+    for (const w of result.warnings) {
+      lines.push(`  ⚠ ${w.message}`);
+      if (w.suggestion) lines.push(`    → ${w.suggestion}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  validatePlan,
+  parsePlanActions,
+  formatValidationResult
+};