@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/contracts.js

@@ -1,804 +1,804 @@
-/**
- * Contracts Generator + Drift Detector v2
- * 
- * Generates contracts from truthpack and detects drift between runs.
- * The hallucination stopper - AI can't invent endpoints, env vars, or auth.
- */
-
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-
-const { createFinding, getSeverity } = require("./schemas/validator");
-
-// =============================================================================
-// CONTRACT TYPES
-// =============================================================================
-
-const CONTRACT_TYPES = {
-  ROUTES: "routes",
-  ENV: "env",
-  AUTH: "auth",
-  EXTERNAL: "external",
-};
-
-// =============================================================================
-// CONTRACT GENERATION
-// =============================================================================
-
-/**
- * Generate all contracts from truthpack
- */
-function generateContracts(truthpack, options = {}) {
-  const { includeInternal = false } = options;
-
-  const contracts = {
-    meta: {
-      version: "2.0.0",
-      generatedAt: new Date().toISOString(),
-      truthpackHash: computeHash(JSON.stringify(truthpack)),
-    },
-    routes: generateRouteContract(truthpack),
-    env: generateEnvContract(truthpack),
-    auth: generateAuthContract(truthpack),
-    external: generateExternalContract(truthpack),
-  };
-
-  // Compute contract hashes
-  contracts.hashes = {
-    routes: computeHash(JSON.stringify(contracts.routes)),
-    env: computeHash(JSON.stringify(contracts.env)),
-    auth: computeHash(JSON.stringify(contracts.auth)),
-    external: computeHash(JSON.stringify(contracts.external)),
-  };
-
-  return contracts;
-}
-
-/**
- * Generate route contract
- */
-function generateRouteContract(truthpack) {
-  const routes = truthpack?.routes?.server || [];
-  
-  return {
-    endpoints: routes.map(r => ({
-      method: r.method,
-      path: r.path,
-      file: r.file,
-      confidence: r.confidence,
-      authRequired: r.authRequired || false,
-      paidOnly: r.paidOnly || false,
-    })),
-    count: routes.length,
-    byMethod: countByField(routes, "method"),
-    byConfidence: countByField(routes, "confidence"),
-  };
-}
-
-/**
- * Generate env contract
- */
-function generateEnvContract(truthpack) {
-  const env = truthpack?.env || {};
-  const vars = env.vars || [];
-  const declared = env.declared || [];
-
-  // Classify vars by prefix
-  const classified = {
-    public: vars.filter(v => v.name.startsWith("NEXT_PUBLIC_") || v.name.startsWith("VITE_")),
-    server: vars.filter(v => !v.name.startsWith("NEXT_PUBLIC_") && !v.name.startsWith("VITE_")),
-  };
-
-  // Required vs optional (heuristic: used in multiple files = required)
-  const required = vars.filter(v => v.usageCount > 1 || v.required);
-  const optional = vars.filter(v => v.usageCount <= 1 && !v.required);
-
-  return {
-    variables: vars.map(v => ({
-      name: v.name,
-      required: v.required || v.usageCount > 1,
-      public: v.name.startsWith("NEXT_PUBLIC_") || v.name.startsWith("VITE_"),
-      declaredIn: declared.includes(v.name) ? ".env.example" : null,
-      usageCount: v.usageCount || 1,
-    })),
-    count: vars.length,
-    requiredCount: required.length,
-    publicCount: classified.public.length,
-    declared: declared,
-  };
-}
-
-/**
- * Generate auth contract
- */
-function generateAuthContract(truthpack) {
-  const auth = truthpack?.auth || {};
-
-  return {
-    providers: auth.providers || [],
-    protectedPatterns: auth.nextMatcherPatterns || [],
-    middleware: {
-      next: auth.nextMiddleware?.length > 0,
-      fastify: auth.fastify?.preHandlerHooks?.length > 0,
-    },
-    rbacDetected: auth.rbacPatterns?.length > 0,
-    signals: {
-      sessionChecks: auth.sessionChecks || [],
-      redirects: auth.redirects || [],
-    },
-  };
-}
-
-/**
- * Generate external services contract
- */
-function generateExternalContract(truthpack) {
-  const billing = truthpack?.billing || {};
-  const integrations = truthpack?.integrations || [];
-
-  return {
-    stripe: {
-      detected: billing.stripeDetected || false,
-      webhookVerified: billing.webhookSignatureVerification || false,
-      products: billing.products || [],
-    },
-    services: integrations.map(i => ({
-      name: i.name,
-      type: i.type,
-      envVars: i.envVars || [],
-    })),
-  };
-}
-
-// =============================================================================
-// DRIFT DETECTION
-// =============================================================================
-
-/**
- * Detect drift between two contract sets
- */
-function detectDrift(currentContracts, previousContracts, options = {}) {
-  const { strict = false } = options;
-
-  const findings = [];
-
-  // Route drift
-  const routeDrift = detectRouteDrift(
-    currentContracts.routes,
-    previousContracts.routes,
-    { strict }
-  );
-  findings.push(...routeDrift);
-
-  // Env drift
-  const envDrift = detectEnvDrift(
-    currentContracts.env,
-    previousContracts.env,
-    { strict }
-  );
-  findings.push(...envDrift);
-
-  // Auth drift
-  const authDrift = detectAuthDrift(
-    currentContracts.auth,
-    previousContracts.auth,
-    { strict }
-  );
-  findings.push(...authDrift);
-
-  // External drift
-  const externalDrift = detectExternalDrift(
-    currentContracts.external,
-    previousContracts.external,
-    { strict }
-  );
-  findings.push(...externalDrift);
-
-  return {
-    hasDrift: findings.length > 0,
-    findings,
-    summary: {
-      routes: routeDrift.length,
-      env: envDrift.length,
-      auth: authDrift.length,
-      external: externalDrift.length,
-    },
-  };
-}
-
-/**
- * Detect route drift
- */
-function detectRouteDrift(current, previous, options = {}) {
-  const findings = [];
-  const { strict } = options;
-
-  const currentPaths = new Set(current.endpoints.map(e => `${e.method}:${e.path}`));
-  const previousPaths = new Set(previous.endpoints.map(e => `${e.method}:${e.path}`));
-
-  // New routes (not in previous)
-  for (const ep of current.endpoints) {
-    const key = `${ep.method}:${ep.path}`;
-    if (!previousPaths.has(key)) {
-      findings.push(createFinding({
-        detectorId: "D_DRIFT_ROUTE_NEW",
-        severity: "INFO",
-        category: "ContractDrift",
-        scope: "contracts",
-        title: `New route added: ${ep.method} ${ep.path}`,
-        why: "Route was added since last contract sync",
-        confidence: "high",
-        path: ep.path,
-        method: ep.method,
-        evidence: [{
-          kind: "file",
-          file: ep.file,
-          reason: "New route definition",
-        }],
-      }));
-    }
-  }
-
-  // Removed routes (in previous but not current)
-  for (const ep of previous.endpoints) {
-    const key = `${ep.method}:${ep.path}`;
-    if (!currentPaths.has(key)) {
-      findings.push(createFinding({
-        detectorId: "D_DRIFT_ROUTE_REMOVED",
-        severity: strict ? "BLOCK" : "WARN",
-        category: "ContractDrift",
-        scope: "contracts",
-        title: `Route removed: ${ep.method} ${ep.path}`,
-        why: "Route existed in previous contract but is now missing",
-        confidence: "high",
-        path: ep.path,
-        method: ep.method,
-        evidence: [{
-          kind: "file",
-          file: ep.file,
-          reason: "Route no longer exists",
-        }],
-      }));
-    }
-  }
-
-  // Auth requirement changes
-  for (const ep of current.endpoints) {
-    const key = `${ep.method}:${ep.path}`;
-    const prev = previous.endpoints.find(p => `${p.method}:${p.path}` === key);
-    
-    if (prev && prev.authRequired && !ep.authRequired) {
-      findings.push(createFinding({
-        detectorId: "D_DRIFT_AUTH_REMOVED",
-        severity: "BLOCK",
-        category: "ContractDrift",
-        scope: "contracts",
-        title: `Auth removed from route: ${ep.method} ${ep.path}`,
-        why: "Route previously required auth but no longer does",
-        confidence: "high",
-        path: ep.path,
-        method: ep.method,
-        evidence: [{
-          kind: "file",
-          file: ep.file,
-          reason: "Auth requirement removed",
-        }],
-      }));
-    }
-  }
-
-  return findings;
-}
-
-/**
- * Detect env drift
- */
-function detectEnvDrift(current, previous, options = {}) {
-  const findings = [];
-  const { strict } = options;
-
-  const currentVars = new Set(current.variables.map(v => v.name));
-  const previousVars = new Set(previous.variables.map(v => v.name));
-
-  // New required env vars
-  for (const v of current.variables) {
-    if (v.required && !previousVars.has(v.name)) {
-      findings.push(createFinding({
-        detectorId: "D_DRIFT_ENV_NEW_REQUIRED",
-        severity: strict ? "BLOCK" : "WARN",
-        category: "ContractDrift",
-        scope: "contracts",
-        title: `New required env var: ${v.name}`,
-        why: "New required environment variable added",
-        confidence: "high",
-        evidence: [{
-          kind: "file",
-          reason: `${v.name} is required but not in previous contract`,
-        }],
-      }));
-    }
-  }
-
-  // Required vars removed (may break existing deployments)
-  for (const v of previous.variables) {
-    if (v.required && !currentVars.has(v.name)) {
-      findings.push(createFinding({
-        detectorId: "D_DRIFT_ENV_REMOVED",
-        severity: "INFO",
-        category: "ContractDrift",
-        scope: "contracts",
-        title: `Env var removed: ${v.name}`,
-        why: "Environment variable no longer used",
-        confidence: "high",
-        evidence: [{
-          kind: "file",
-          reason: `${v.name} was in previous contract but not current`,
-        }],
-      }));
-    }
-  }
-
-  // Public → Server (security concern)
-  for (const v of current.variables) {
-    const prev = previous.variables.find(p => p.name === v.name);
-    if (prev && prev.public && !v.public) {
-      findings.push(createFinding({
-        detectorId: "D_DRIFT_ENV_PUBLIC_TO_SERVER",
-        severity: "INFO",
-        category: "ContractDrift",
-        scope: "contracts",
-        title: `Env var moved from public to server: ${v.name}`,
-        why: "Variable changed from public to server-only (good for security)",
-        confidence: "medium",
-        evidence: [{
-          kind: "file",
-          reason: `${v.name} prefix changed`,
-        }],
-      }));
-    }
-  }
-
-  return findings;
-}
-
-/**
- * Detect auth drift
- */
-function detectAuthDrift(current, previous, options = {}) {
-  const findings = [];
-
-  // Protected patterns removed
-  const currentPatterns = new Set(current.protectedPatterns);
-  const previousPatterns = new Set(previous.protectedPatterns);
-
-  for (const pattern of previousPatterns) {
-    if (!currentPatterns.has(pattern)) {
-      findings.push(createFinding({
-        detectorId: "D_DRIFT_AUTH_PATTERN_REMOVED",
-        severity: "BLOCK",
-        category: "ContractDrift",
-        scope: "contracts",
-        title: `Protected pattern removed: ${pattern}`,
-        why: "Auth protection pattern was removed from middleware",
-        confidence: "high",
-        evidence: [{
-          kind: "file",
-          reason: `Pattern "${pattern}" no longer in matcher`,
-        }],
-      }));
-    }
-  }
-
-  // Middleware disabled
-  if (previous.middleware.next && !current.middleware.next) {
-    findings.push(createFinding({
-      detectorId: "D_DRIFT_AUTH_MIDDLEWARE_DISABLED",
-      severity: "BLOCK",
-      category: "ContractDrift",
-      scope: "contracts",
-      title: "Next.js auth middleware disabled",
-      why: "Auth middleware was active but is now disabled",
-      confidence: "high",
-      evidence: [{
-        kind: "file",
-        reason: "middleware.ts no longer exports auth matcher",
-      }],
-    }));
-  }
-
-  return findings;
-}
-
-/**
- * Detect external service drift
- */
-function detectExternalDrift(current, previous, options = {}) {
-  const findings = [];
-
-  // Stripe webhook verification removed
-  if (previous.stripe.webhookVerified && !current.stripe.webhookVerified) {
-    findings.push(createFinding({
-      detectorId: "D_DRIFT_STRIPE_VERIFY_REMOVED",
-      severity: "BLOCK",
-      category: "ContractDrift",
-      scope: "contracts",
-      title: "Stripe webhook verification removed",
-      why: "Stripe webhook signature verification was present but removed",
-      confidence: "high",
-      evidence: [{
-        kind: "file",
-        reason: "constructEvent or verifyHeader no longer called",
-      }],
-    }));
-  }
-
-  return findings;
-}
-
-// =============================================================================
-// CONTRACT SYNC (ctx sync)
-// =============================================================================
-
-/**
- * Sync contracts - generate and save
- */
-function syncContracts(truthpack, repoRoot) {
-  const contracts = generateContracts(truthpack);
-
-  const contractsDir = path.join(repoRoot, ".vibecheck", "contracts");
-  fs.mkdirSync(contractsDir, { recursive: true });
-
-  // Write individual contract files
-  for (const type of Object.values(CONTRACT_TYPES)) {
-    if (contracts[type]) {
-      fs.writeFileSync(
-        path.join(contractsDir, `${type}.json`),
-        JSON.stringify(contracts[type], null, 2)
-      );
-    }
-  }
-
-  // Write combined contracts
-  fs.writeFileSync(
-    path.join(contractsDir, "contracts.json"),
-    JSON.stringify(contracts, null, 2)
-  );
-
-  // Write hashes for quick drift check
-  fs.writeFileSync(
-    path.join(contractsDir, "hashes.json"),
-    JSON.stringify(contracts.hashes, null, 2)
-  );
-
-  return contracts;
-}
-
-/**
- * Load previous contracts for drift comparison
- */
-function loadPreviousContracts(repoRoot) {
-  const contractsPath = path.join(repoRoot, ".vibecheck", "contracts", "contracts.json");
-  
-  if (!fs.existsSync(contractsPath)) {
-    return null;
-  }
-
-  try {
-    return JSON.parse(fs.readFileSync(contractsPath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Guard contracts - check for drift and generate findings
- */
-function guardContracts(truthpack, repoRoot, options = {}) {
-  const previous = loadPreviousContracts(repoRoot);
-  
-  if (!previous) {
-    // No previous contracts, just sync
-    const contracts = syncContracts(truthpack, repoRoot);
-    return {
-      isFirstRun: true,
-      hasDrift: false,
-      findings: [],
-      contracts,
-    };
-  }
-
-  const current = generateContracts(truthpack);
-  const drift = detectDrift(current, previous, options);
-
-  // If no blockers, update contracts
-  const hasBlockers = drift.findings.some(f => f.severity === "BLOCK");
-  if (!hasBlockers) {
-    syncContracts(truthpack, repoRoot);
-  }
-
-  return {
-    isFirstRun: false,
-    hasDrift: drift.hasDrift,
-    hasBlockers,
-    findings: drift.findings,
-    contracts: current,
-    previous,
-  };
-}
-
-// =============================================================================
-// DRIFT EXPLAINABILITY
-// =============================================================================
-
-/**
- * Generate detailed drift explanation with remediation
- */
-function explainDrift(driftResult) {
-  const { findings, summary } = driftResult;
-  
-  const explanation = {
-    summary: {
-      hasDrift: driftResult.hasDrift,
-      totalChanges: findings.length,
-      byCategory: summary,
-      verdict: findings.some(f => f.severity === "BLOCK") ? "BLOCK" : 
-               findings.some(f => f.severity === "WARN") ? "WARN" : "OK",
-    },
-    changes: [],
-    remediation: [],
-  };
-
-  for (const finding of findings) {
-    const change = {
-      type: getChangeType(finding.detectorId),
-      severity: finding.severity,
-      title: finding.title,
-      why: finding.why || getWhyMessage(finding),
-      impact: getImpactMessage(finding),
-      remediation: getRemediationCommand(finding),
-    };
-    explanation.changes.push(change);
-    
-    if (change.remediation) {
-      explanation.remediation.push(change.remediation);
-    }
-  }
-
-  return explanation;
-}
-
-/**
- * Get change type from detector ID
- */
-function getChangeType(detectorId) {
-  const types = {
-    "D_DRIFT_ROUTE_NEW": "added",
-    "D_DRIFT_ROUTE_REMOVED": "removed",
-    "D_DRIFT_AUTH_REMOVED": "modified",
-    "D_DRIFT_ENV_NEW_REQUIRED": "added",
-    "D_DRIFT_ENV_REMOVED": "removed",
-    "D_DRIFT_ENV_PUBLIC_TO_SERVER": "modified",
-    "D_DRIFT_AUTH_PATTERN_REMOVED": "removed",
-    "D_DRIFT_AUTH_PATTERN_NEW": "added",
-    "D_DRIFT_EXTERNAL_NEW": "added",
-    "D_DRIFT_EXTERNAL_REMOVED": "removed",
-  };
-  return types[detectorId] || "unknown";
-}
-
-/**
- * Get why message for finding
- */
-function getWhyMessage(finding) {
-  const messages = {
-    "D_DRIFT_ROUTE_NEW": "New endpoint referenced by client but not in previous contract",
-    "D_DRIFT_ROUTE_REMOVED": "Endpoint was in contract but no longer exists in codebase",
-    "D_DRIFT_AUTH_REMOVED": "Route lost auth protection - potential security regression",
-    "D_DRIFT_ENV_NEW_REQUIRED": "New required env var may break deployments without it",
-    "D_DRIFT_ENV_REMOVED": "Env var no longer used - can be cleaned up",
-    "D_DRIFT_AUTH_PATTERN_REMOVED": "Auth protection pattern removed from middleware",
-    "D_DRIFT_AUTH_PATTERN_NEW": "New route pattern added to auth middleware",
-    "D_DRIFT_EXTERNAL_NEW": "New external API dependency detected",
-    "D_DRIFT_EXTERNAL_REMOVED": "External API dependency removed",
-  };
-  return messages[finding.detectorId] || "Contract changed since last sync";
-}
-
-/**
- * Get impact message for finding
- */
-function getImpactMessage(finding) {
-  if (finding.severity === "BLOCK") {
-    return "This change may cause runtime failures or security issues";
-  }
-  if (finding.severity === "WARN") {
-    return "This change should be reviewed before shipping";
-  }
-  return "This change is informational";
-}
-
-/**
- * Get remediation command for finding
- */
-function getRemediationCommand(finding) {
-  const detectorId = finding.detectorId;
-  
-  // If the change is intentional, sync contracts
-  if (detectorId.includes("NEW") || detectorId.includes("ADDED")) {
-    return {
-      ifIntentional: "vibecheck ctx sync",
-      description: "If this change is intentional, sync contracts",
-    };
-  }
-  
-  if (detectorId.includes("REMOVED")) {
-    if (detectorId.includes("ROUTE")) {
-      return {
-        ifIntentional: "vibecheck ctx sync",
-        ifAccidental: `Add route back or remove client call to ${finding.evidence?.[0]?.path || "the endpoint"}`,
-        description: "Route was removed - verify this is intentional",
-      };
-    }
-    if (detectorId.includes("AUTH")) {
-      return {
-        ifIntentional: "vibecheck ctx sync --force",
-        ifAccidental: "Restore auth protection to the route",
-        description: "Auth was removed - this is usually NOT intentional",
-      };
-    }
-  }
-  
-  return {
-    ifIntentional: "vibecheck ctx sync",
-    description: "Review the change and sync if intentional",
-  };
-}
-
-/**
- * Write contracts diff to disk
- */
-function writeContractsDiff(repoRoot, driftResult) {
-  const dir = path.join(repoRoot, ".vibecheck");
-  fs.mkdirSync(dir, { recursive: true });
-
-  const explanation = explainDrift(driftResult);
-  
-  const diff = {
-    meta: {
-      generatedAt: new Date().toISOString(),
-      verdict: explanation.summary.verdict,
-    },
-    ...explanation,
-  };
-
-  const diffPath = path.join(dir, "contracts_diff.json");
-  fs.writeFileSync(diffPath, JSON.stringify(diff, null, 2));
-
-  return { path: diffPath, explanation };
-}
-
-/**
- * Print drift report to console
- */
-function printDriftReport(driftResult) {
-  const explanation = explainDrift(driftResult);
-  
-  console.log("\n" + "=".repeat(60));
-  console.log("📋 CONTRACT DRIFT REPORT");
-  console.log("=".repeat(60));
-  
-  if (!driftResult.hasDrift) {
-    console.log("\n✅ No drift detected - contracts are in sync\n");
-    return;
-  }
-
-  const verdictEmoji = {
-    BLOCK: "🚫",
-    WARN: "⚠️",
-    OK: "✅",
-  }[explanation.summary.verdict];
-
-  console.log(`\nVerdict: ${verdictEmoji} ${explanation.summary.verdict}`);
-  console.log(`Changes: ${explanation.summary.totalChanges}`);
-  
-  // Group by severity
-  const blockers = explanation.changes.filter(c => c.severity === "BLOCK");
-  const warnings = explanation.changes.filter(c => c.severity === "WARN");
-  const infos = explanation.changes.filter(c => c.severity === "INFO");
-
-  if (blockers.length > 0) {
-    console.log("\n🚫 BLOCKERS:");
-    for (const change of blockers) {
-      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
-      console.log(`   └─ Why: ${change.why}`);
-      if (change.remediation?.ifAccidental) {
-        console.log(`   └─ Fix: ${change.remediation.ifAccidental}`);
-      }
-    }
-  }
-
-  if (warnings.length > 0) {
-    console.log("\n⚠️  WARNINGS:");
-    for (const change of warnings) {
-      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
-      console.log(`   └─ Why: ${change.why}`);
-    }
-  }
-
-  if (infos.length > 0) {
-    console.log("\nℹ️  INFO:");
-    for (const change of infos) {
-      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
-    }
-  }
-
-  // Remediation
-  console.log("\n" + "-".repeat(60));
-  console.log("REMEDIATION:");
-  
-  if (explanation.summary.verdict === "BLOCK") {
-    console.log("\n   If changes are INTENTIONAL:");
-    console.log("   $ vibecheck ctx sync --force");
-    console.log("\n   If changes are ACCIDENTAL:");
-    console.log("   - Review the blockers above and fix the issues");
-    console.log("   - Then run: vibecheck ctx sync");
-  } else {
-    console.log("\n   To accept these changes:");
-    console.log("   $ vibecheck ctx sync");
-  }
-  
-  console.log("\n" + "=".repeat(60) + "\n");
-}
-
-// =============================================================================
-// HELPERS
-// =============================================================================
-
-function computeHash(content) {
-  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
-}
-
-function countByField(items, field) {
-  const counts = {};
-  for (const item of items) {
-    const value = item[field] || "unknown";
-    counts[value] = (counts[value] || 0) + 1;
-  }
-  return counts;
-}
-
-// =============================================================================
-// EXPORTS
-// =============================================================================
-
-module.exports = {
-  // Contract types
-  CONTRACT_TYPES,
-
-  // Generation
-  generateContracts,
-  generateRouteContract,
-  generateEnvContract,
-  generateAuthContract,
-  generateExternalContract,
-
-  // Drift detection
-  detectDrift,
-  detectRouteDrift,
-  detectEnvDrift,
-  detectAuthDrift,
-  detectExternalDrift,
-
-  // Drift explainability
-  explainDrift,
-  writeContractsDiff,
-  printDriftReport,
-
-  // Sync/Guard
-  syncContracts,
-  loadPreviousContracts,
-  guardContracts,
-};
+/**
+ * Contracts Generator + Drift Detector v2
+ * 
+ * Generates contracts from truthpack and detects drift between runs.
+ * The hallucination stopper - AI can't invent endpoints, env vars, or auth.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const { createFinding, getSeverity } = require("./schemas/validator");
+
+// =============================================================================
+// CONTRACT TYPES
+// =============================================================================
+
+const CONTRACT_TYPES = {
+  ROUTES: "routes",
+  ENV: "env",
+  AUTH: "auth",
+  EXTERNAL: "external",
+};
+
+// =============================================================================
+// CONTRACT GENERATION
+// =============================================================================
+
+/**
+ * Generate all contracts from truthpack
+ */
+function generateContracts(truthpack, options = {}) {
+  const { includeInternal = false } = options;
+
+  const contracts = {
+    meta: {
+      version: "2.0.0",
+      generatedAt: new Date().toISOString(),
+      truthpackHash: computeHash(JSON.stringify(truthpack)),
+    },
+    routes: generateRouteContract(truthpack),
+    env: generateEnvContract(truthpack),
+    auth: generateAuthContract(truthpack),
+    external: generateExternalContract(truthpack),
+  };
+
+  // Compute contract hashes
+  contracts.hashes = {
+    routes: computeHash(JSON.stringify(contracts.routes)),
+    env: computeHash(JSON.stringify(contracts.env)),
+    auth: computeHash(JSON.stringify(contracts.auth)),
+    external: computeHash(JSON.stringify(contracts.external)),
+  };
+
+  return contracts;
+}
+
+/**
+ * Generate route contract
+ */
+function generateRouteContract(truthpack) {
+  const routes = truthpack?.routes?.server || [];
+  
+  return {
+    endpoints: routes.map(r => ({
+      method: r.method,
+      path: r.path,
+      file: r.file,
+      confidence: r.confidence,
+      authRequired: r.authRequired || false,
+      paidOnly: r.paidOnly || false,
+    })),
+    count: routes.length,
+    byMethod: countByField(routes, "method"),
+    byConfidence: countByField(routes, "confidence"),
+  };
+}
+
+/**
+ * Generate env contract
+ */
+function generateEnvContract(truthpack) {
+  const env = truthpack?.env || {};
+  const vars = env.vars || [];
+  const declared = env.declared || [];
+
+  // Classify vars by prefix
+  const classified = {
+    public: vars.filter(v => v.name.startsWith("NEXT_PUBLIC_") || v.name.startsWith("VITE_")),
+    server: vars.filter(v => !v.name.startsWith("NEXT_PUBLIC_") && !v.name.startsWith("VITE_")),
+  };
+
+  // Required vs optional (heuristic: used in multiple files = required)
+  const required = vars.filter(v => v.usageCount > 1 || v.required);
+  const optional = vars.filter(v => v.usageCount <= 1 && !v.required);
+
+  return {
+    variables: vars.map(v => ({
+      name: v.name,
+      required: v.required || v.usageCount > 1,
+      public: v.name.startsWith("NEXT_PUBLIC_") || v.name.startsWith("VITE_"),
+      declaredIn: declared.includes(v.name) ? ".env.example" : null,
+      usageCount: v.usageCount || 1,
+    })),
+    count: vars.length,
+    requiredCount: required.length,
+    publicCount: classified.public.length,
+    declared: declared,
+  };
+}
+
+/**
+ * Generate auth contract
+ */
+function generateAuthContract(truthpack) {
+  const auth = truthpack?.auth || {};
+
+  return {
+    providers: auth.providers || [],
+    protectedPatterns: auth.nextMatcherPatterns || [],
+    middleware: {
+      next: auth.nextMiddleware?.length > 0,
+      fastify: auth.fastify?.preHandlerHooks?.length > 0,
+    },
+    rbacDetected: auth.rbacPatterns?.length > 0,
+    signals: {
+      sessionChecks: auth.sessionChecks || [],
+      redirects: auth.redirects || [],
+    },
+  };
+}
+
+/**
+ * Generate external services contract
+ */
+function generateExternalContract(truthpack) {
+  const billing = truthpack?.billing || {};
+  const integrations = truthpack?.integrations || [];
+
+  return {
+    stripe: {
+      detected: billing.stripeDetected || false,
+      webhookVerified: billing.webhookSignatureVerification || false,
+      products: billing.products || [],
+    },
+    services: integrations.map(i => ({
+      name: i.name,
+      type: i.type,
+      envVars: i.envVars || [],
+    })),
+  };
+}
+
+// =============================================================================
+// DRIFT DETECTION
+// =============================================================================
+
+/**
+ * Detect drift between two contract sets
+ */
+function detectDrift(currentContracts, previousContracts, options = {}) {
+  const { strict = false } = options;
+
+  const findings = [];
+
+  // Route drift
+  const routeDrift = detectRouteDrift(
+    currentContracts.routes,
+    previousContracts.routes,
+    { strict }
+  );
+  findings.push(...routeDrift);
+
+  // Env drift
+  const envDrift = detectEnvDrift(
+    currentContracts.env,
+    previousContracts.env,
+    { strict }
+  );
+  findings.push(...envDrift);
+
+  // Auth drift
+  const authDrift = detectAuthDrift(
+    currentContracts.auth,
+    previousContracts.auth,
+    { strict }
+  );
+  findings.push(...authDrift);
+
+  // External drift
+  const externalDrift = detectExternalDrift(
+    currentContracts.external,
+    previousContracts.external,
+    { strict }
+  );
+  findings.push(...externalDrift);
+
+  return {
+    hasDrift: findings.length > 0,
+    findings,
+    summary: {
+      routes: routeDrift.length,
+      env: envDrift.length,
+      auth: authDrift.length,
+      external: externalDrift.length,
+    },
+  };
+}
+
+/**
+ * Detect route drift
+ */
+function detectRouteDrift(current, previous, options = {}) {
+  const findings = [];
+  const { strict } = options;
+
+  const currentPaths = new Set(current.endpoints.map(e => `${e.method}:${e.path}`));
+  const previousPaths = new Set(previous.endpoints.map(e => `${e.method}:${e.path}`));
+
+  // New routes (not in previous)
+  for (const ep of current.endpoints) {
+    const key = `${ep.method}:${ep.path}`;
+    if (!previousPaths.has(key)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ROUTE_NEW",
+        severity: "INFO",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `New route added: ${ep.method} ${ep.path}`,
+        why: "Route was added since last contract sync",
+        confidence: "high",
+        path: ep.path,
+        method: ep.method,
+        evidence: [{
+          kind: "file",
+          file: ep.file,
+          reason: "New route definition",
+        }],
+      }));
+    }
+  }
+
+  // Removed routes (in previous but not current)
+  for (const ep of previous.endpoints) {
+    const key = `${ep.method}:${ep.path}`;
+    if (!currentPaths.has(key)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ROUTE_REMOVED",
+        severity: strict ? "BLOCK" : "WARN",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Route removed: ${ep.method} ${ep.path}`,
+        why: "Route existed in previous contract but is now missing",
+        confidence: "high",
+        path: ep.path,
+        method: ep.method,
+        evidence: [{
+          kind: "file",
+          file: ep.file,
+          reason: "Route no longer exists",
+        }],
+      }));
+    }
+  }
+
+  // Auth requirement changes
+  for (const ep of current.endpoints) {
+    const key = `${ep.method}:${ep.path}`;
+    const prev = previous.endpoints.find(p => `${p.method}:${p.path}` === key);
+    
+    if (prev && prev.authRequired && !ep.authRequired) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_AUTH_REMOVED",
+        severity: "BLOCK",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Auth removed from route: ${ep.method} ${ep.path}`,
+        why: "Route previously required auth but no longer does",
+        confidence: "high",
+        path: ep.path,
+        method: ep.method,
+        evidence: [{
+          kind: "file",
+          file: ep.file,
+          reason: "Auth requirement removed",
+        }],
+      }));
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect env drift
+ */
+function detectEnvDrift(current, previous, options = {}) {
+  const findings = [];
+  const { strict } = options;
+
+  const currentVars = new Set(current.variables.map(v => v.name));
+  const previousVars = new Set(previous.variables.map(v => v.name));
+
+  // New required env vars
+  for (const v of current.variables) {
+    if (v.required && !previousVars.has(v.name)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ENV_NEW_REQUIRED",
+        severity: strict ? "BLOCK" : "WARN",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `New required env var: ${v.name}`,
+        why: "New required environment variable added",
+        confidence: "high",
+        evidence: [{
+          kind: "file",
+          reason: `${v.name} is required but not in previous contract`,
+        }],
+      }));
+    }
+  }
+
+  // Required vars removed (may break existing deployments)
+  for (const v of previous.variables) {
+    if (v.required && !currentVars.has(v.name)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ENV_REMOVED",
+        severity: "INFO",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Env var removed: ${v.name}`,
+        why: "Environment variable no longer used",
+        confidence: "high",
+        evidence: [{
+          kind: "file",
+          reason: `${v.name} was in previous contract but not current`,
+        }],
+      }));
+    }
+  }
+
+  // Public → Server (security concern)
+  for (const v of current.variables) {
+    const prev = previous.variables.find(p => p.name === v.name);
+    if (prev && prev.public && !v.public) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_ENV_PUBLIC_TO_SERVER",
+        severity: "INFO",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Env var moved from public to server: ${v.name}`,
+        why: "Variable changed from public to server-only (good for security)",
+        confidence: "medium",
+        evidence: [{
+          kind: "file",
+          reason: `${v.name} prefix changed`,
+        }],
+      }));
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect auth drift
+ */
+function detectAuthDrift(current, previous, options = {}) {
+  const findings = [];
+
+  // Protected patterns removed
+  const currentPatterns = new Set(current.protectedPatterns);
+  const previousPatterns = new Set(previous.protectedPatterns);
+
+  for (const pattern of previousPatterns) {
+    if (!currentPatterns.has(pattern)) {
+      findings.push(createFinding({
+        detectorId: "D_DRIFT_AUTH_PATTERN_REMOVED",
+        severity: "BLOCK",
+        category: "ContractDrift",
+        scope: "contracts",
+        title: `Protected pattern removed: ${pattern}`,
+        why: "Auth protection pattern was removed from middleware",
+        confidence: "high",
+        evidence: [{
+          kind: "file",
+          reason: `Pattern "${pattern}" no longer in matcher`,
+        }],
+      }));
+    }
+  }
+
+  // Middleware disabled
+  if (previous.middleware.next && !current.middleware.next) {
+    findings.push(createFinding({
+      detectorId: "D_DRIFT_AUTH_MIDDLEWARE_DISABLED",
+      severity: "BLOCK",
+      category: "ContractDrift",
+      scope: "contracts",
+      title: "Next.js auth middleware disabled",
+      why: "Auth middleware was active but is now disabled",
+      confidence: "high",
+      evidence: [{
+        kind: "file",
+        reason: "middleware.ts no longer exports auth matcher",
+      }],
+    }));
+  }
+
+  return findings;
+}
+
+/**
+ * Detect external service drift
+ */
+function detectExternalDrift(current, previous, options = {}) {
+  const findings = [];
+
+  // Stripe webhook verification removed
+  if (previous.stripe.webhookVerified && !current.stripe.webhookVerified) {
+    findings.push(createFinding({
+      detectorId: "D_DRIFT_STRIPE_VERIFY_REMOVED",
+      severity: "BLOCK",
+      category: "ContractDrift",
+      scope: "contracts",
+      title: "Stripe webhook verification removed",
+      why: "Stripe webhook signature verification was present but removed",
+      confidence: "high",
+      evidence: [{
+        kind: "file",
+        reason: "constructEvent or verifyHeader no longer called",
+      }],
+    }));
+  }
+
+  return findings;
+}
+
+// =============================================================================
+// CONTRACT SYNC (ctx sync)
+// =============================================================================
+
+/**
+ * Sync contracts - generate and save
+ */
+function syncContracts(truthpack, repoRoot) {
+  const contracts = generateContracts(truthpack);
+
+  const contractsDir = path.join(repoRoot, ".vibecheck", "contracts");
+  fs.mkdirSync(contractsDir, { recursive: true });
+
+  // Write individual contract files
+  for (const type of Object.values(CONTRACT_TYPES)) {
+    if (contracts[type]) {
+      fs.writeFileSync(
+        path.join(contractsDir, `${type}.json`),
+        JSON.stringify(contracts[type], null, 2)
+      );
+    }
+  }
+
+  // Write combined contracts
+  fs.writeFileSync(
+    path.join(contractsDir, "contracts.json"),
+    JSON.stringify(contracts, null, 2)
+  );
+
+  // Write hashes for quick drift check
+  fs.writeFileSync(
+    path.join(contractsDir, "hashes.json"),
+    JSON.stringify(contracts.hashes, null, 2)
+  );
+
+  return contracts;
+}
+
+/**
+ * Load previous contracts for drift comparison
+ */
+function loadPreviousContracts(repoRoot) {
+  const contractsPath = path.join(repoRoot, ".vibecheck", "contracts", "contracts.json");
+  
+  if (!fs.existsSync(contractsPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(contractsPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Guard contracts - check for drift and generate findings
+ */
+function guardContracts(truthpack, repoRoot, options = {}) {
+  const previous = loadPreviousContracts(repoRoot);
+  
+  if (!previous) {
+    // No previous contracts, just sync
+    const contracts = syncContracts(truthpack, repoRoot);
+    return {
+      isFirstRun: true,
+      hasDrift: false,
+      findings: [],
+      contracts,
+    };
+  }
+
+  const current = generateContracts(truthpack);
+  const drift = detectDrift(current, previous, options);
+
+  // If no blockers, update contracts
+  const hasBlockers = drift.findings.some(f => f.severity === "BLOCK");
+  if (!hasBlockers) {
+    syncContracts(truthpack, repoRoot);
+  }
+
+  return {
+    isFirstRun: false,
+    hasDrift: drift.hasDrift,
+    hasBlockers,
+    findings: drift.findings,
+    contracts: current,
+    previous,
+  };
+}
+
+// =============================================================================
+// DRIFT EXPLAINABILITY
+// =============================================================================
+
+/**
+ * Generate detailed drift explanation with remediation
+ */
+function explainDrift(driftResult) {
+  const { findings, summary } = driftResult;
+  
+  const explanation = {
+    summary: {
+      hasDrift: driftResult.hasDrift,
+      totalChanges: findings.length,
+      byCategory: summary,
+      verdict: findings.some(f => f.severity === "BLOCK") ? "BLOCK" : 
+               findings.some(f => f.severity === "WARN") ? "WARN" : "OK",
+    },
+    changes: [],
+    remediation: [],
+  };
+
+  for (const finding of findings) {
+    const change = {
+      type: getChangeType(finding.detectorId),
+      severity: finding.severity,
+      title: finding.title,
+      why: finding.why || getWhyMessage(finding),
+      impact: getImpactMessage(finding),
+      remediation: getRemediationCommand(finding),
+    };
+    explanation.changes.push(change);
+    
+    if (change.remediation) {
+      explanation.remediation.push(change.remediation);
+    }
+  }
+
+  return explanation;
+}
+
+/**
+ * Get change type from detector ID
+ */
+function getChangeType(detectorId) {
+  const types = {
+    "D_DRIFT_ROUTE_NEW": "added",
+    "D_DRIFT_ROUTE_REMOVED": "removed",
+    "D_DRIFT_AUTH_REMOVED": "modified",
+    "D_DRIFT_ENV_NEW_REQUIRED": "added",
+    "D_DRIFT_ENV_REMOVED": "removed",
+    "D_DRIFT_ENV_PUBLIC_TO_SERVER": "modified",
+    "D_DRIFT_AUTH_PATTERN_REMOVED": "removed",
+    "D_DRIFT_AUTH_PATTERN_NEW": "added",
+    "D_DRIFT_EXTERNAL_NEW": "added",
+    "D_DRIFT_EXTERNAL_REMOVED": "removed",
+  };
+  return types[detectorId] || "unknown";
+}
+
+/**
+ * Get why message for finding
+ */
+function getWhyMessage(finding) {
+  const messages = {
+    "D_DRIFT_ROUTE_NEW": "New endpoint referenced by client but not in previous contract",
+    "D_DRIFT_ROUTE_REMOVED": "Endpoint was in contract but no longer exists in codebase",
+    "D_DRIFT_AUTH_REMOVED": "Route lost auth protection - potential security regression",
+    "D_DRIFT_ENV_NEW_REQUIRED": "New required env var may break deployments without it",
+    "D_DRIFT_ENV_REMOVED": "Env var no longer used - can be cleaned up",
+    "D_DRIFT_AUTH_PATTERN_REMOVED": "Auth protection pattern removed from middleware",
+    "D_DRIFT_AUTH_PATTERN_NEW": "New route pattern added to auth middleware",
+    "D_DRIFT_EXTERNAL_NEW": "New external API dependency detected",
+    "D_DRIFT_EXTERNAL_REMOVED": "External API dependency removed",
+  };
+  return messages[finding.detectorId] || "Contract changed since last sync";
+}
+
+/**
+ * Get impact message for finding
+ */
+function getImpactMessage(finding) {
+  if (finding.severity === "BLOCK") {
+    return "This change may cause runtime failures or security issues";
+  }
+  if (finding.severity === "WARN") {
+    return "This change should be reviewed before shipping";
+  }
+  return "This change is informational";
+}
+
+/**
+ * Get remediation command for finding
+ */
+function getRemediationCommand(finding) {
+  const detectorId = finding.detectorId;
+  
+  // If the change is intentional, sync contracts
+  if (detectorId.includes("NEW") || detectorId.includes("ADDED")) {
+    return {
+      ifIntentional: "vibecheck ctx sync",
+      description: "If this change is intentional, sync contracts",
+    };
+  }
+  
+  if (detectorId.includes("REMOVED")) {
+    if (detectorId.includes("ROUTE")) {
+      return {
+        ifIntentional: "vibecheck ctx sync",
+        ifAccidental: `Add route back or remove client call to ${finding.evidence?.[0]?.path || "the endpoint"}`,
+        description: "Route was removed - verify this is intentional",
+      };
+    }
+    if (detectorId.includes("AUTH")) {
+      return {
+        ifIntentional: "vibecheck ctx sync --force",
+        ifAccidental: "Restore auth protection to the route",
+        description: "Auth was removed - this is usually NOT intentional",
+      };
+    }
+  }
+  
+  return {
+    ifIntentional: "vibecheck ctx sync",
+    description: "Review the change and sync if intentional",
+  };
+}
+
+/**
+ * Write contracts diff to disk
+ */
+function writeContractsDiff(repoRoot, driftResult) {
+  const dir = path.join(repoRoot, ".vibecheck");
+  fs.mkdirSync(dir, { recursive: true });
+
+  const explanation = explainDrift(driftResult);
+  
+  const diff = {
+    meta: {
+      generatedAt: new Date().toISOString(),
+      verdict: explanation.summary.verdict,
+    },
+    ...explanation,
+  };
+
+  const diffPath = path.join(dir, "contracts_diff.json");
+  fs.writeFileSync(diffPath, JSON.stringify(diff, null, 2));
+
+  return { path: diffPath, explanation };
+}
+
+/**
+ * Print drift report to console
+ */
+function printDriftReport(driftResult) {
+  const explanation = explainDrift(driftResult);
+  
+  console.log("\n" + "=".repeat(60));
+  console.log("📋 CONTRACT DRIFT REPORT");
+  console.log("=".repeat(60));
+  
+  if (!driftResult.hasDrift) {
+    console.log("\n✅ No drift detected - contracts are in sync\n");
+    return;
+  }
+
+  const verdictEmoji = {
+    BLOCK: "🚫",
+    WARN: "⚠️",
+    OK: "✅",
+  }[explanation.summary.verdict];
+
+  console.log(`\nVerdict: ${verdictEmoji} ${explanation.summary.verdict}`);
+  console.log(`Changes: ${explanation.summary.totalChanges}`);
+  
+  // Group by severity
+  const blockers = explanation.changes.filter(c => c.severity === "BLOCK");
+  const warnings = explanation.changes.filter(c => c.severity === "WARN");
+  const infos = explanation.changes.filter(c => c.severity === "INFO");
+
+  if (blockers.length > 0) {
+    console.log("\n🚫 BLOCKERS:");
+    for (const change of blockers) {
+      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
+      console.log(`   └─ Why: ${change.why}`);
+      if (change.remediation?.ifAccidental) {
+        console.log(`   └─ Fix: ${change.remediation.ifAccidental}`);
+      }
+    }
+  }
+
+  if (warnings.length > 0) {
+    console.log("\n⚠️  WARNINGS:");
+    for (const change of warnings) {
+      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
+      console.log(`   └─ Why: ${change.why}`);
+    }
+  }
+
+  if (infos.length > 0) {
+    console.log("\nℹ️  INFO:");
+    for (const change of infos) {
+      console.log(`   ${change.type.toUpperCase()}: ${change.title}`);
+    }
+  }
+
+  // Remediation
+  console.log("\n" + "-".repeat(60));
+  console.log("REMEDIATION:");
+  
+  if (explanation.summary.verdict === "BLOCK") {
+    console.log("\n   If changes are INTENTIONAL:");
+    console.log("   $ vibecheck ctx sync --force");
+    console.log("\n   If changes are ACCIDENTAL:");
+    console.log("   - Review the blockers above and fix the issues");
+    console.log("   - Then run: vibecheck ctx sync");
+  } else {
+    console.log("\n   To accept these changes:");
+    console.log("   $ vibecheck ctx sync");
+  }
+  
+  console.log("\n" + "=".repeat(60) + "\n");
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function computeHash(content) {
+  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+function countByField(items, field) {
+  const counts = {};
+  for (const item of items) {
+    const value = item[field] || "unknown";
+    counts[value] = (counts[value] || 0) + 1;
+  }
+  return counts;
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+module.exports = {
+  // Contract types
+  CONTRACT_TYPES,
+
+  // Generation
+  generateContracts,
+  generateRouteContract,
+  generateEnvContract,
+  generateAuthContract,
+  generateExternalContract,
+
+  // Drift detection
+  detectDrift,
+  detectRouteDrift,
+  detectEnvDrift,
+  detectAuthDrift,
+  detectExternalDrift,
+
+  // Drift explainability
+  explainDrift,
+  writeContractsDiff,
+  printDriftReport,
+
+  // Sync/Guard
+  syncContracts,
+  loadPreviousContracts,
+  guardContracts,
+};