@vibecheckai/cli 2.8.2 → 3.0.0

package/bin/runners/lib/env-template.js

@@ -0,0 +1,66 @@
+// bin/runners/lib/env-template.js
+const fs = require("fs");
+const path = require("path");
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function pickEnvTemplatePath(root) {
+  const candidates = [".env.template", ".env.example", ".env.sample"];
+  for (const c of candidates) {
+    const abs = path.join(root, c);
+    if (fs.existsSync(abs)) return c;
+  }
+  return ".env.template";
+}
+
+function normalizeEnvName(n) {
+  return String(n || "").trim();
+}
+
+function parseDeclaredEnvFromText(text) {
+  const declared = new Set();
+  const lines = String(text || "").split(/\r?\n/);
+  for (const l of lines) {
+    if (!l || l.trim().startsWith("#")) continue;
+    const m = l.match(/^([A-Z0-9_]+)\s*=/);
+    if (m) declared.add(m[1]);
+  }
+  return declared;
+}
+
+function writeEnvTemplateFromTruthpack(root, truthpack) {
+  const outRel = pickEnvTemplatePath(root);
+  const outAbs = path.join(root, outRel);
+
+  const used = new Set((truthpack?.env?.vars || []).map(normalizeEnvName).filter(Boolean));
+
+  let existingText = "";
+  if (fs.existsSync(outAbs)) existingText = fs.readFileSync(outAbs, "utf8");
+
+  const declared = parseDeclaredEnvFromText(existingText);
+  const missing = Array.from(used).filter((x) => !declared.has(x)).sort();
+
+  if (!missing.length && fs.existsSync(outAbs)) {
+    return { outRel, wrote: false, added: [] };
+  }
+
+  const header =
+`# vibecheck env template
+# This file is generated/extended from REAL env usage found in your code.
+# Fill values in your real .env (never commit secrets).
+
+`;
+
+  const additions = missing.map((k) => `${k}=\n`).join("");
+
+  const nextText = (existingText.trim().length ? existingText.trimEnd() + "\n\n" : header) + additions;
+
+  ensureDir(path.dirname(outAbs));
+  fs.writeFileSync(outAbs, nextText, "utf8");
+
+  return { outRel, wrote: true, added: missing };
+}
+
+module.exports = { writeEnvTemplateFromTruthpack };

package/bin/runners/lib/env.js

@@ -0,0 +1,189 @@
+// bin/runners/lib/env.js
+const fg = require("fast-glob");
+const fs = require("fs");
+const path = require("path");
+const parser = require("@babel/parser");
+const traverse = require("@babel/traverse").default;
+const t = require("@babel/types");
+const crypto = require("crypto");
+
+function sha256(text) {
+  return "sha256:" + crypto.createHash("sha256").update(text).digest("hex");
+}
+
+function parseFile(code) {
+  return parser.parse(code, { sourceType: "unambiguous", plugins: ["typescript", "jsx"] });
+}
+
+function safeRead(fileAbs) {
+  return fs.readFileSync(fileAbs, "utf8");
+}
+
+function evidenceFromLoc({ fileAbs, fileRel, loc, reason }) {
+  if (!loc) return null;
+  const lines = safeRead(fileAbs).split(/\r?\n/);
+  const start = Math.max(1, loc.start?.line || 1);
+  const end = Math.max(start, loc.end?.line || start);
+  const snippet = lines.slice(start - 1, end).join("\n");
+  return {
+    id: `ev_${crypto.randomBytes(4).toString("hex")}`,
+    file: fileRel,
+    lines: `${start}-${end}`,
+    snippetHash: sha256(snippet),
+    reason
+  };
+}
+
+function mergeEvidenceMap(map, name, ev) {
+  map[name] = map[name] || { name, references: [], signals: { hasDefault: false } };
+  if (ev) map[name].references.push(ev);
+}
+
+function isEnvName(s) {
+  return typeof s === "string" && /^[A-Z0-9_]+$/.test(s);
+}
+
+function extractEnvFromMemberExpr(node) {
+  if (!t.isMemberExpression(node)) return null;
+
+  // process.env.NAME
+  if (t.isMemberExpression(node.object) &&
+      t.isIdentifier(node.object.object, { name: "process" }) &&
+      t.isIdentifier(node.object.property, { name: "env" }) &&
+      t.isIdentifier(node.property)) {
+    return node.property.name;
+  }
+
+  // process.env["NAME"]
+  if (t.isMemberExpression(node.object) &&
+      t.isIdentifier(node.object.object, { name: "process" }) &&
+      t.isIdentifier(node.object.property, { name: "env" }) &&
+      t.isStringLiteral(node.property)) {
+    return node.property.value;
+  }
+
+  // import.meta.env.NAME
+  if (t.isMemberExpression(node.object) &&
+      t.isMemberExpression(node.object.object) &&
+      t.isIdentifier(node.object.object.object, { name: "import" }) &&
+      t.isIdentifier(node.object.object.property, { name: "meta" }) &&
+      t.isIdentifier(node.object.property, { name: "env" }) &&
+      t.isIdentifier(node.property)) {
+    return node.property.name;
+  }
+
+  return null;
+}
+
+function detectDefaultSignals(parentPath) {
+  const p = parentPath?.parentPath;
+  if (!p) return { hasDefault: false };
+
+  if (p.isLogicalExpression() && (p.node.operator === "||" || p.node.operator === "??")) {
+    return { hasDefault: true };
+  }
+  if (p.isConditionalExpression()) return { hasDefault: true };
+  if (p.isAssignmentExpression() && p.node.operator === "||=") return { hasDefault: true };
+  return { hasDefault: false };
+}
+
+async function resolveEnvUsage(repoRoot) {
+  const files = await fg(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: ["**/node_modules/**","**/.next/**","**/dist/**","**/build/**"]
+  });
+
+  const usageMap = {};
+
+  for (const fileAbs of files) {
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    const code = safeRead(fileAbs);
+
+    let ast;
+    try { ast = parseFile(code); } catch { continue; }
+
+    traverse(ast, {
+      MemberExpression(p) {
+        const name = extractEnvFromMemberExpr(p.node);
+        if (!name || !isEnvName(name)) return;
+
+        const ev = evidenceFromLoc({
+          fileAbs,
+          fileRel,
+          loc: p.node.loc,
+          reason: `Env usage: ${name}` 
+        });
+
+        mergeEvidenceMap(usageMap, name, ev);
+
+        const sig = detectDefaultSignals(p);
+        if (sig.hasDefault) usageMap[name].signals.hasDefault = true;
+      }
+    });
+  }
+
+  return usageMap;
+}
+
+function parseDotEnvLike(content) {
+  const out = new Set();
+  const lines = content.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const l = line.startsWith("export ") ? line.slice(7).trim() : line;
+    const eq = l.indexOf("=");
+    if (eq <= 0) continue;
+    const key = l.slice(0, eq).trim();
+    if (isEnvName(key)) out.add(key);
+  }
+  return out;
+}
+
+async function resolveEnvDeclared(repoRoot) {
+  const candidates = [
+    ".env.example", ".env.template", ".env.sample",
+    ".env.local.example", ".env.development.example",
+    ".env"
+  ];
+
+  const declared = new Set();
+  const sources = [];
+
+  for (const rel of candidates) {
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) continue;
+
+    const content = safeRead(abs);
+    const keys = parseDotEnvLike(content);
+    if (keys.size) {
+      for (const k of keys) declared.add(k);
+      sources.push(rel);
+    }
+  }
+
+  return { declared: Array.from(declared).sort(), sources };
+}
+
+async function buildEnvTruth(repoRoot) {
+  const usageMap = await resolveEnvUsage(repoRoot);
+  const declared = await resolveEnvDeclared(repoRoot);
+
+  const used = Object.values(usageMap).sort((a, b) => a.name.localeCompare(b.name));
+
+  const vars = used.map(u => ({
+    name: u.name,
+    required: !u.signals?.hasDefault,
+    references: u.references || [],
+    notes: u.signals?.hasDefault ? "Has default/fallback usage signal" : ""
+  }));
+
+  return {
+    vars,
+    declared: declared.declared,
+    declaredSources: declared.sources
+  };
+}
+
+module.exports = { buildEnvTruth };

package/bin/runners/lib/error-handler.js

@@ -0,0 +1,320 @@
+/**
+ * Standardized error handling for CLI runners
+ * 
+ * Design principles:
+ * - Every error has a human-readable message
+ * - Every error suggests a next step
+ * - Exit codes are consistent and documented
+ */
+
+const colors = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  bold: "\x1b[1m",
+};
+
+const c = {
+  error: (text) => `${colors.red}${colors.bold}${text}${colors.reset}`,
+  warning: (text) => `${colors.yellow}${text}${colors.reset}`,
+  info: (text) => `${colors.cyan}${text}${colors.reset}`,
+  success: (text) => `${colors.green}${text}${colors.reset}`,
+  dim: (text) => `\x1b[2m${text}${colors.reset}`,
+};
+
+// Standard exit codes for CI/CD integration
+// Unified with packages/cli/src/runtime/exit-codes.ts
+// IMPORTANT: These codes are part of the CLI contract - do not change without migration guide
+const EXIT_CODES = {
+  SUCCESS: 0,           // Scan passed, no policy violations
+  POLICY_FAIL: 1,       // Findings above threshold (policy fail) - actionable by user
+  USER_ERROR: 2,        // User error: invalid args, bad config, missing required options
+  SYSTEM_ERROR: 3,      // System error: crash, filesystem issues, unexpected exceptions
+  AUTH_FAILURE: 4,      // Auth/entitlement failure: invalid key, expired token, insufficient tier
+  NETWORK_FAILURE: 5,   // Network/backend failure: API unreachable, timeout
+};
+
+// Error-specific guidance
+const ERROR_GUIDANCE = {
+  ENOENT: {
+    title: "File or directory not found",
+    nextSteps: [
+      "Verify the path exists and is spelled correctly",
+      "Run from the project root directory",
+      "Check if the file was deleted or moved",
+    ],
+  },
+  EACCES: {
+    title: "Permission denied",
+    nextSteps: [
+      "Check file/directory permissions",
+      "Try running with appropriate permissions",
+      "Ensure you own the files or have read access",
+    ],
+  },
+  ECONNREFUSED: {
+    title: "Connection refused",
+    nextSteps: [
+      "Check if the API server is running",
+      "Verify VIBECHECK_API_URL is correct",
+      "Check firewall/network settings",
+    ],
+  },
+  ETIMEDOUT: {
+    title: "Connection timed out",
+    nextSteps: [
+      "Check your internet connection",
+      "The server may be overloaded, try again later",
+      "Increase timeout with --timeout flag if available",
+    ],
+  },
+  INVALID_API_KEY: {
+    title: "Invalid API key",
+    nextSteps: [
+      'Run "vibecheck login" to authenticate',
+      "Get a new API key at https://vibecheckai.dev/settings/keys",
+      "Check VIBECHECK_API_KEY environment variable",
+    ],
+  },
+  PLAN_REQUIRED: {
+    title: "Feature requires a paid plan",
+    nextSteps: [
+      "Upgrade at https://vibecheckai.dev/pricing",
+      'Run "vibecheck upgrade" to manage your subscription',
+      "Some features have free tier limits",
+    ],
+  },
+  RATE_LIMITED: {
+    title: "Rate limit exceeded",
+    nextSteps: [
+      "Wait a moment and try again",
+      "Upgrade your plan for higher limits",
+      "Batch operations to reduce API calls",
+    ],
+  },
+};
+
+/**
+ * Get guidance for an error
+ */
+function getErrorGuidance(error) {
+  const code = error.code || error.name;
+  
+  // Check for known error types
+  if (ERROR_GUIDANCE[code]) {
+    return ERROR_GUIDANCE[code];
+  }
+  
+  // Infer from error message
+  if (error.message?.includes("API key")) {
+    return ERROR_GUIDANCE.INVALID_API_KEY;
+  }
+  if (error.message?.includes("rate limit")) {
+    return ERROR_GUIDANCE.RATE_LIMITED;
+  }
+  if (error.message?.includes("plan") || error.message?.includes("upgrade")) {
+    return ERROR_GUIDANCE.PLAN_REQUIRED;
+  }
+  
+  return null;
+}
+
+/**
+ * Handle CLI errors with consistent formatting and guidance
+ * @param {Error|string} error - The error to handle
+ * @param {string} context - Additional context (command name, file path, etc.)
+ * @param {Object} metadata - Additional metadata (command, file, line, receipt, verifyCommand, etc.)
+ */
+function handleError(error, context = "", metadata = {}) {
+  // Ensure error is an Error object
+  const err = error instanceof Error ? error : new Error(String(error));
+
+  // Build receipt string (file:line or evidence)
+  let receipt = "";
+  if (metadata.file && metadata.line) {
+    receipt = `${metadata.file}:${metadata.line}`;
+  } else if (metadata.file) {
+    receipt = metadata.file;
+  } else if (metadata.receipt) {
+    receipt = metadata.receipt;
+  }
+
+  // Build enriched context message
+  const contextParts = [context];
+  if (receipt) contextParts.push(`Receipt: ${receipt}`);
+  if (metadata.command && !context.includes(metadata.command)) contextParts.push(`Command: ${metadata.command}`);
+  const enrichedContext = contextParts.filter(Boolean).join(' | ');
+
+  // Add context to error message if provided
+  const message = enrichedContext ? `${enrichedContext}: ${err.message}` : err.message;
+
+  // Get specific guidance
+  const guidance = getErrorGuidance(err);
+  
+  // Print error header
+  if (guidance) {
+    console.error(`\n${c.error("✗")} ${c.error(guidance.title)}`);
+    console.error(`  ${message}`);
+    
+    // Print next steps
+    console.error(`\n${c.info("Next steps:")}`);
+    for (const step of guidance.nextSteps) {
+      console.error(`  ${c.dim("•")} ${step}`);
+    }
+  } else {
+    // Generic error handling with specific type detection
+    if (err.code === "ENOENT") {
+      console.error(`\n${c.error("✗")} File or directory not found`);
+      console.error(`  ${err.path || message}`);
+      // Print receipt if available
+      if (receipt) {
+        console.error(`\n${c.dim("Receipt:")} ${receipt}`);
+      }
+      console.error(`\n${c.info("Next steps:")}`);
+      console.error(`  ${c.dim("•")} Verify the path exists`);
+      console.error(`  ${c.dim("•")} Run from the correct directory`);
+      if (metadata.verifyCommand) {
+        console.error(`\n${c.info("Verify it's fixed:")}`);
+        console.error(`  ${c.dim("•")} ${metadata.verifyCommand}`);
+      }
+    } else if (err.code === "EACCES") {
+      console.error(`\n${c.error("✗")} Permission denied`);
+      console.error(`  ${message}`);
+      // Print receipt if available
+      if (receipt) {
+        console.error(`\n${c.dim("Receipt:")} ${receipt}`);
+      }
+      console.error(`\n${c.info("Next steps:")}`);
+      console.error(`  ${c.dim("•")} Check file permissions`);
+      if (metadata.verifyCommand) {
+        console.error(`\n${c.info("Verify it's fixed:")}`);
+        console.error(`  ${c.dim("•")} ${metadata.verifyCommand}`);
+      }
+    } else if (err.name === "AuthenticationError") {
+      console.error(`\n${c.error("✗")} Authentication required`);
+      console.error(`  ${message}`);
+      console.error(`\n${c.info("Next steps:")}`);
+      console.error(`  ${c.dim("•")} Run "vibecheck login" to authenticate`);
+      console.error(`  ${c.dim("•")} Get your API key at https://vibecheckai.dev/settings/keys`);
+    } else if (err.name === "NetworkError" || err.code === "ECONNREFUSED" || err.code === "ETIMEDOUT") {
+      console.error(`\n${c.error("✗")} Network error`);
+      console.error(`  ${message}`);
+      console.error(`\n${c.info("Next steps:")}`);
+      console.error(`  ${c.dim("•")} Check your internet connection`);
+      console.error(`  ${c.dim("•")} Verify VIBECHECK_API_URL is correct`);
+    } else {
+      // Generic error
+      console.error(`\n${c.error("✗")} Error`);
+      console.error(`  ${message}`);
+      // Print receipt if available
+      if (receipt) {
+        console.error(`\n${c.dim("Receipt:")} ${receipt}`);
+      }
+      console.error(`\n${c.info("Need help?")}`);
+      console.error(`  ${c.dim("•")} Run "vibecheck doctor" for diagnostics`);
+      console.error(`  ${c.dim("•")} Visit https://docs.vibecheckai.dev/troubleshooting`);
+      if (metadata.verifyCommand) {
+        console.error(`\n${c.info("Verify it's fixed:")}`);
+        console.error(`  ${c.dim("•")} ${metadata.verifyCommand}`);
+      }
+    }
+  }
+
+  // Show stack trace in debug mode
+  if (process.env.DEBUG || process.env.VIBECHECK_DEBUG) {
+    console.error(`\n${c.dim("Stack trace:")}`);
+    console.error(c.dim(err.stack));
+  }
+  
+  console.error(""); // Empty line for readability
+}
+
+/**
+ * Wrap an async function with error handling
+ */
+function withErrorHandling(fn, context = "") {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      handleError(error, context);
+      return 1; // Return error exit code
+    }
+  };
+}
+
+/**
+ * Create a user-friendly error for specific scenarios
+ */
+function createUserError(message, type = "Error") {
+  const error = new Error(message);
+  error.name = type;
+  error.isUserError = true;
+  return error;
+}
+
+/**
+ * Check if an error should be retried
+ */
+function shouldRetry(error) {
+  // Retry on network errors
+  if (
+    error.code === "ECONNRESET" ||
+    error.code === "ECONNREFUSED" ||
+    error.code === "ETIMEDOUT" ||
+    error.name === "NetworkError"
+  ) {
+    return true;
+  }
+
+  // Don't retry on user errors
+  if (
+    error.isUserError ||
+    error.name === "ValidationError" ||
+    error.name === "AuthenticationError"
+  ) {
+    return false;
+  }
+
+  // Default: don't retry
+  return false;
+}
+
+/**
+ * Retry a function with exponential backoff
+ */
+async function retry(fn, maxAttempts = 3, context = "") {
+  let lastError;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (!shouldRetry(error) || attempt === maxAttempts) {
+        break;
+      }
+
+      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+      console.warn(
+        c.warning(`Attempt ${attempt} failed, retrying in ${delay / 1000}s...`),
+      );
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError;
+}
+
+module.exports = {
+  handleError,
+  withErrorHandling,
+  createUserError,
+  shouldRetry,
+  retry,
+  EXIT_CODES,
+  getErrorGuidance,
+};

package/bin/runners/lib/firewall-prompt.js

@@ -0,0 +1,50 @@
+// bin/runners/lib/firewall-prompt.js
+function buildRealityFirewall({ truthpackSummary, mission, template, findings, fileSnippets, allowedFiles }) {
+  return `
+You are Guardrail Fix Engine.
+
+REALITY RULES (non-negotiable):
+- Do NOT invent files, routes, env vars, middleware, or functions.
+- You may ONLY edit files in ALLOWED_FILES.
+- Use ONLY the provided evidence/snippets.
+- If evidence is insufficient, return {"status":"needs_info","questions":[...]} and STOP.
+- Output MUST be valid JSON only. No markdown. No commentary.
+
+ALLOWED_FILES:
+${JSON.stringify(allowedFiles || [], null, 2)}
+
+MISSION TEMPLATE (how to fix):
+${JSON.stringify(template || {}, null, 2)}
+
+OUTPUT SCHEMA (strict):
+{
+  "status": "ok" | "needs_info" | "cannot_fix",
+  "summary": "one sentence",
+  "edits": [
+    {
+      "path": "relative/file/path (must be in ALLOWED_FILES)",
+      "diff": "unified diff starting with ---/+++",
+      "reason": "why this edit fixes the mission"
+    }
+  ],
+  "notes": ["optional"],
+  "questions": ["only when needs_info"]
+}
+
+TRUTHPACK SUMMARY:
+${JSON.stringify(truthpackSummary, null, 2)}
+
+MISSION:
+${JSON.stringify(mission, null, 2)}
+
+TARGET FINDINGS:
+${JSON.stringify(findings, null, 2)}
+
+EVIDENCE SNIPPETS:
+${JSON.stringify(fileSnippets, null, 2)}
+
+TASK:
+Produce the smallest correct patch(es) to satisfy the mission success criteria.`;
+}
+
+module.exports = { buildRealityFirewall };