vibecheck-ai 2.0.1 → 5.0.0

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

@@ -0,0 +1,368 @@
+/**
+ * Standardized error handling for CLI runners
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * World-Class Error Handling
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Design principles:
+ * - Every error has a human-readable message
+ * - Every error suggests a next step
+ * - Exit codes are consistent and documented
+ * - Errors include "receipt" (file:line evidence) where possible
+ * - Debug mode shows stack traces
+ */
+
+const { EXIT, getExitInfo, getHint } = require("./exit-codes");
+
+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}`,
+};
+
+// Re-export EXIT for backward compatibility
+// NOTE: Prefer importing from exit-codes.js directly
+const EXIT_CODES = {
+  SUCCESS: EXIT.SUCCESS,
+  POLICY_FAIL: EXIT.WARNINGS,       // Findings above threshold (policy fail)
+  USER_ERROR: EXIT.USER_ERROR,      // User error: invalid args, bad config
+  SYSTEM_ERROR: EXIT.INTERNAL_ERROR, // System error: crash, unexpected exceptions
+  AUTH_FAILURE: EXIT.AUTH_REQUIRED,  // Auth/entitlement failure
+  NETWORK_FAILURE: EXIT.NETWORK_ERROR, // Network/backend failure
+};
+
+// 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);
+  
+  // Check for JSON mode (via NO_COLOR env var or explicit check)
+  const isJsonMode = process.env.NO_COLOR === '1' || process.env.VIBECHECK_JSON === '1';
+  
+  // Print error header
+  if (guidance) {
+    if (isJsonMode) {
+      // JSON error output
+      const errorOutput = {
+        success: false,
+        error: {
+          code: err.code || err.name || 'ERROR',
+          message: message,
+          type: guidance.title,
+          nextSteps: guidance.nextSteps,
+        },
+        exitCode: err.exitCode || 1
+      };
+      console.error(JSON.stringify(errorOutput, null, 2));
+      return;
+    }
+    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 {
+    // Check for JSON mode
+    const isJsonMode = process.env.NO_COLOR === '1' || process.env.VIBECHECK_JSON === '1';
+    
+    // Generic error handling with specific type detection
+    if (err.code === "ENOENT") {
+      if (isJsonMode) {
+        const errorOutput = {
+          success: false,
+          error: { code: 'ENOENT', message: err.path || message, receipt },
+          exitCode: 4
+        };
+        console.error(JSON.stringify(errorOutput, null, 2));
+        return;
+      }
+      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
+      if (isJsonMode) {
+        const errorOutput = {
+          success: false,
+          error: { code: err.code || err.name || 'ERROR', message, receipt },
+          exitCode: err.exitCode || 1
+        };
+        console.error(JSON.stringify(errorOutput, null, 2));
+        return;
+      }
+      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 (skip in JSON mode)
+  if (!isJsonMode && (process.env.DEBUG || process.env.VIBECHECK_DEBUG)) {
+    console.error(`\n${c.dim("Stack trace:")}`);
+    console.error(c.dim(err.stack));
+  }
+  
+  if (!isJsonMode) {
+    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/error-messages.js

@@ -0,0 +1,289 @@
+/**
+ * Actionable Error Messages
+ * 
+ * Provides standardized error messages with actionable next steps,
+ * documentation links, and clear guidance for users.
+ */
+
+const { EXIT } = require('./exit-codes');
+
+const DOCS_BASE_URL = 'https://docs.vibecheckai.dev';
+const DASHBOARD_URL = 'https://app.vibecheckai.dev';
+
+/**
+ * Format an actionable error message
+ */
+function formatError(error, context = {}) {
+  const {
+    command = '',
+    suggestion = null,
+    docsLink = null,
+    nextSteps = [],
+    code = null,
+  } = context;
+
+  const lines = [];
+  
+  // Main error message
+  lines.push(`\n  ❌ ${error.message || error}`);
+  
+  // Error code if provided
+  if (code) {
+    lines.push(`\n  Code: ${code}`);
+  }
+  
+  // Next steps
+  if (nextSteps.length > 0) {
+    lines.push(`\n  Next steps:`);
+    nextSteps.forEach((step, i) => {
+      lines.push(`    ${i + 1}. ${step}`);
+    });
+  } else if (suggestion) {
+    lines.push(`\n  💡 ${suggestion}`);
+  }
+  
+  // Documentation link
+  if (docsLink) {
+    lines.push(`\n  📖 Docs: ${docsLink}`);
+  } else if (command) {
+    lines.push(`\n  📖 Docs: ${DOCS_BASE_URL}/commands/${command}`);
+  }
+  
+  lines.push('');
+  
+  return lines.join('\n');
+}
+
+/**
+ * Common error templates with actionable guidance
+ */
+const ERROR_TEMPLATES = {
+  PROJECT_NOT_INITIALIZED: {
+    message: 'Project not initialized',
+    suggestion: 'Run `vibecheck init` to set up your project',
+    nextSteps: [
+      'Run: vibecheck init',
+      'This creates .vibecheckrc config file',
+      'Then run: vibecheck scan',
+    ],
+    docsLink: `${DOCS_BASE_URL}/getting-started/init`,
+  },
+  
+  NO_SCAN_RESULTS: {
+    message: 'No scan results found',
+    suggestion: 'Run `vibecheck scan` first to generate results',
+    nextSteps: [
+      'Run: vibecheck scan',
+      'This analyzes your codebase',
+      'Then re-run this command',
+    ],
+    docsLink: `${DOCS_BASE_URL}/commands/scan`,
+  },
+  
+  NO_TRUTHPACK: {
+    message: 'No truthpack found',
+    suggestion: 'Run `vibecheck context` to generate truthpack',
+    nextSteps: [
+      'Run: vibecheck context',
+      'This generates route/auth/env mapping',
+      'Then re-run this command',
+    ],
+    docsLink: `${DOCS_BASE_URL}/commands/context`,
+  },
+  
+  AUTH_REQUIRED: {
+    message: 'Authentication required',
+    suggestion: 'Run `vibecheck login` to authenticate',
+    nextSteps: [
+      'Run: vibecheck login',
+      'Enter your API key',
+      'Get your key from: https://app.vibecheckai.dev/settings/api-keys',
+    ],
+    docsLink: `${DOCS_BASE_URL}/getting-started/authentication`,
+  },
+  
+  INVALID_API_KEY: {
+    message: 'Invalid API key format',
+    suggestion: 'Check your API key format',
+    nextSteps: [
+      'API keys should start with grl_ (from dashboard)',
+      'Get a new key: https://app.vibecheckai.dev/settings/api-keys',
+      'Run: vibecheck login --key YOUR_KEY',
+    ],
+    docsLink: `${DOCS_BASE_URL}/getting-started/authentication`,
+  },
+  
+  TIER_REQUIRED: {
+    message: 'This feature requires PRO tier',
+    suggestion: 'Upgrade to PRO to access this feature',
+    nextSteps: [
+      'Visit: https://app.vibecheckai.dev/pricing',
+      'Upgrade your account',
+      'Re-run this command',
+    ],
+    docsLink: `${DOCS_BASE_URL}/pricing`,
+  },
+  
+  PROJECT_PATH_NOT_FOUND: {
+    message: 'Project path does not exist',
+    suggestion: 'Check the path and try again',
+    nextSteps: [
+      'Verify the path exists: ls <path>',
+      'Use absolute path if relative path fails',
+      'Run: vibecheck init --path <path>',
+    ],
+    docsLink: `${DOCS_BASE_URL}/commands/init`,
+  },
+  
+  CONFIG_INVALID: {
+    message: 'Invalid configuration file',
+    suggestion: 'Run `vibecheck doctor --fix` to repair config',
+    nextSteps: [
+      'Run: vibecheck doctor --fix',
+      'This auto-fixes common config issues',
+      'Or manually edit .vibecheckrc',
+    ],
+    docsLink: `${DOCS_BASE_URL}/configuration`,
+  },
+  
+  NETWORK_ERROR: {
+    message: 'Network connection failed',
+    suggestion: 'Check your internet connection or use --offline mode',
+    nextSteps: [
+      'Check internet connection',
+      'Or run with --offline flag for local-only mode',
+      'Example: vibecheck scan --offline',
+    ],
+    docsLink: `${DOCS_BASE_URL}/commands/scan#offline-mode`,
+  },
+  
+  MISSING_DEPENDENCY: {
+    message: 'Missing required dependency',
+    suggestion: 'Install missing dependencies',
+    nextSteps: [
+      'Run: npm install',
+      'Or: pnpm install',
+      'Check package.json for required packages',
+    ],
+    docsLink: `${DOCS_BASE_URL}/troubleshooting/dependencies`,
+  },
+};
+
+/**
+ * Get error template by key
+ */
+function getErrorTemplate(key, overrides = {}) {
+  const template = ERROR_TEMPLATES[key];
+  if (!template) {
+    return {
+      message: key,
+      suggestion: 'Check the documentation for help',
+      docsLink: DOCS_BASE_URL,
+    };
+  }
+  
+  return { ...template, ...overrides };
+}
+
+/**
+ * Print actionable error and return exit code
+ */
+function printActionableError(errorKey, context = {}) {
+  const template = getErrorTemplate(errorKey, context);
+  const error = {
+    message: template.message,
+    code: context.code || errorKey,
+  };
+  
+  const formatted = formatError(error, {
+    ...context,
+    suggestion: template.suggestion,
+    nextSteps: template.nextSteps || [],
+    docsLink: template.docsLink,
+  });
+  
+  console.error(formatted);
+  
+  // Map error keys to exit codes
+  const exitCodeMap = {
+    AUTH_REQUIRED: EXIT.AUTH_REQUIRED,
+    INVALID_API_KEY: EXIT.AUTH_FAILED,
+    TIER_REQUIRED: EXIT.TIER_REQUIRED,
+    PROJECT_PATH_NOT_FOUND: EXIT.USER_ERROR,
+    CONFIG_INVALID: EXIT.USER_ERROR,
+    NETWORK_ERROR: EXIT.NETWORK_ERROR || 1,
+    MISSING_DEPENDENCY: EXIT.USER_ERROR,
+    PROJECT_NOT_INITIALIZED: EXIT.USER_ERROR,
+    NO_SCAN_RESULTS: EXIT.NOT_FOUND || 1,
+    NO_TRUTHPACK: EXIT.NOT_FOUND || 1,
+  };
+  
+  return exitCodeMap[errorKey] || EXIT.USER_ERROR;
+}
+
+/**
+ * Enhance existing error with actionable guidance
+ */
+function enhanceError(error, command = '', additionalContext = {}) {
+  const errorMessage = error.message || String(error);
+  const lowerMessage = errorMessage.toLowerCase();
+  
+  // Detect error type from message
+  if (lowerMessage.includes('not initialized') || lowerMessage.includes('no config')) {
+    return printActionableError('PROJECT_NOT_INITIALIZED', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('scan result') || lowerMessage.includes('no results')) {
+    return printActionableError('NO_SCAN_RESULTS', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('truthpack') || lowerMessage.includes('context')) {
+    return printActionableError('NO_TRUTHPACK', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('auth') && (lowerMessage.includes('required') || lowerMessage.includes('unauthorized'))) {
+    return printActionableError('AUTH_REQUIRED', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('api key') && (lowerMessage.includes('invalid') || lowerMessage.includes('format'))) {
+    return printActionableError('INVALID_API_KEY', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('tier') || lowerMessage.includes('pro') || lowerMessage.includes('upgrade')) {
+    return printActionableError('TIER_REQUIRED', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('path') && (lowerMessage.includes('not found') || lowerMessage.includes('does not exist'))) {
+    return printActionableError('PROJECT_PATH_NOT_FOUND', { command, path: additionalContext.path });
+  }
+  
+  if (lowerMessage.includes('config') && (lowerMessage.includes('invalid') || lowerMessage.includes('error'))) {
+    return printActionableError('CONFIG_INVALID', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('network') || lowerMessage.includes('connection') || lowerMessage.includes('fetch')) {
+    return printActionableError('NETWORK_ERROR', { command, ...additionalContext });
+  }
+  
+  if (lowerMessage.includes('cannot find module') || lowerMessage.includes('missing')) {
+    return printActionableError('MISSING_DEPENDENCY', { command, dependency: additionalContext.dependency });
+  }
+  
+  // Default: print enhanced error
+  console.error(formatError(error, {
+    command,
+    suggestion: additionalContext.suggestion || 'Check the documentation for help',
+    docsLink: additionalContext.docsLink || `${DOCS_BASE_URL}/commands/${command}`,
+    nextSteps: additionalContext.nextSteps || [],
+  }));
+  
+  return EXIT.USER_ERROR;
+}
+
+module.exports = {
+  formatError,
+  getErrorTemplate,
+  printActionableError,
+  enhanceError,
+  ERROR_TEMPLATES,
+};