@vibecheckai/cli 3.5.1 → 3.5.3

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

@@ -1,12 +1,20 @@
 /**
  * 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",
@@ -24,16 +32,15 @@ const c = {
   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
+// Re-export EXIT for backward compatibility
+// NOTE: Prefer importing from exit-codes.js directly
 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
+  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
@@ -153,8 +160,26 @@ function handleError(error, context = "", metadata = {}) {
   // 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}`);
     
@@ -164,8 +189,20 @@ function handleError(error, context = "", metadata = {}) {
       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
@@ -206,6 +243,15 @@ function handleError(error, context = "", metadata = {}) {
       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
@@ -222,13 +268,15 @@ function handleError(error, context = "", metadata = {}) {
     }
   }
 
-  // Show stack trace in debug mode
-  if (process.env.DEBUG || process.env.VIBECHECK_DEBUG) {
+  // 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));
   }
   
-  console.error(""); // Empty line for readability
+  if (!isJsonMode) {
+    console.error(""); // Empty line for readability
+  }
 }
 
 /**

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 vc_',
+      '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,
+};

package/bin/runners/lib/evidence-pack.js

@@ -14,7 +14,13 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
-const archiver = require("archiver");
+// Make archiver optional - only required for zip creation
+let archiver;
+try {
+  archiver = require("archiver");
+} catch {
+  archiver = null;
+}
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // EVIDENCE PACK SCHEMA