@vibecheckai/cli 3.5.1 → 3.5.3

package/bin/vibecheck.js

@@ -795,18 +795,88 @@ ${c.bold}Installation:${c.reset}
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// HELP SYSTEM
+// HELP SYSTEM - World-Class CLI Experience
 // ═══════════════════════════════════════════════════════════════════════════════
 function printBanner() {
   const VERSION = getVersion();
   console.log(`
-${c.dim}${sym.boxTopLeft}${sym.boxHorizontal.repeat(60)}${sym.boxTopRight}${c.reset}
-${c.dim}${sym.boxVertical}${c.reset}  ${gradient("VIBECHECK", [[0, 255, 255], [138, 43, 226], [255, 20, 147]])} ${c.dim}v${VERSION}${c.reset}${" ".repeat(60 - 13 - VERSION.length - 4)}${c.dim}${sym.boxVertical}${c.reset}
-${c.dim}${sym.boxVertical}${c.reset}  ${c.dim}Ship with confidence. Catch fake features before users do.${c.reset}  ${c.dim}${sym.boxVertical}${c.reset}
-${c.dim}${sym.boxBottomLeft}${sym.boxHorizontal.repeat(60)}${sym.boxBottomRight}${c.reset}
+${c.dim}${sym.boxTopLeft}${sym.boxHorizontal.repeat(64)}${sym.boxTopRight}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${gradient("VIBECHECK", [[0, 255, 255], [138, 43, 226], [255, 20, 147]])} ${c.dim}v${VERSION}${c.reset}${" ".repeat(64 - 13 - VERSION.length - 4)}${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}                                                                ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.bold}Catch AI hallucinations before your users do.${c.reset}                 ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}                                                                ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.cyan}${sym.check}${c.reset} Detects routes that look real but don't work             ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.cyan}${sym.check}${c.reset} Finds env vars used but never declared                   ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.cyan}${sym.check}${c.reset} Flags auth endpoints with no protection                  ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}                                                                ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxVertical}${c.reset}  ${c.dim}SHIP = proof your code works. Not a vibe check.${c.reset}               ${c.dim}${sym.boxVertical}${c.reset}
+${c.dim}${sym.boxBottomLeft}${sym.boxHorizontal.repeat(64)}${sym.boxBottomRight}${c.reset}
 `);
 }
 
+/**
+ * Print command-specific help with rich examples
+ */
+function printCommandHelp(cmd) {
+  const registry = getRegistry();
+  const def = registry.COMMANDS[cmd];
+  if (!def) return false;
+  
+  // Build reverse alias map
+  const reverseAliases = {};
+  for (const [alias, target] of Object.entries(registry.ALIAS_MAP)) {
+    if (!reverseAliases[target]) reverseAliases[target] = [];
+    reverseAliases[target].push(alias);
+  }
+  
+  const aliases = reverseAliases[cmd] || [];
+  
+  // Tier badge (2-tier: FREE / PRO)
+  const tierBadge = def.tier === "free" ? `${c.green}[FREE]${c.reset}` :
+                    def.tier === "pro" ? `${c.magenta}[PRO]${c.reset}` : "";
+  
+  console.log(`
+  ${c.bold}${sym.arrowRight} vibecheck ${cmd}${c.reset} ${tierBadge}
+  ${aliases.length > 0 ? `${c.dim}Aliases: ${aliases.join(", ")}${c.reset}` : ""}
+  
+  ${def.longDescription || def.description}
+`);
+
+  // Examples
+  if (def.examples && def.examples.length > 0) {
+    console.log(`  ${c.bold}${sym.star} EXAMPLES${c.reset}\n`);
+    for (const ex of def.examples) {
+      const exTier = ex.tier === "pro" ? `${c.magenta}[PRO]${c.reset} ` : "";
+      console.log(`    ${c.dim}#${c.reset} ${ex.description} ${exTier}`);
+      console.log(`    ${c.cyan}${ex.command}${c.reset}`);
+      console.log();
+    }
+  }
+  
+  // Related commands
+  if (def.related && def.related.length > 0) {
+    console.log(`  ${c.bold}${sym.arrowRight} RELATED COMMANDS${c.reset}\n`);
+    for (const relCmd of def.related) {
+      const relDef = registry.COMMANDS[relCmd];
+      if (relDef) {
+        const relTier = relDef.tier === "pro" ? `${c.magenta}[PRO]${c.reset} ` : "";
+        console.log(`    ${c.cyan}vibecheck ${relCmd}${c.reset} ${relTier}${c.dim}${relDef.description}${c.reset}`);
+      }
+    }
+    console.log();
+  }
+  
+  // Documentation link
+  if (def.docsUrl) {
+    console.log(`  ${c.dim}${sym.boxHorizontal.repeat(56)}${c.reset}`);
+    console.log(`  ${c.dim}Documentation: ${c.underline}${def.docsUrl}${c.reset}`);
+  }
+  
+  console.log(`  ${c.dim}Run 'vibecheck --help' for all commands.${c.reset}\n`);
+  
+  return true;
+}
+
 function printHelp(showBanner = true) {
   if (showBanner) printBanner();
 
@@ -852,10 +922,9 @@ function printHelp(showBanner = true) {
     console.log(`\n${cat.color}${cat.icon} ${cat.name}${c.reset}\n`);
 
     for (const { cmd, description, tier, caps } of commands) {
-      // Tier badge
+      // Tier badge (2-tier: FREE / PRO)
       let tierBadge = "";
       if (tier === "free") tierBadge = `${c.green}[FREE]${c.reset} `;
-      else if (tier === "starter") tierBadge = `${c.cyan}[STARTER]${c.reset} `;
       else if (tier === "pro") tierBadge = `${c.magenta}[PRO]${c.reset} `;
 
       // Aliases (from reverseAliases map built earlier)
@@ -874,39 +943,98 @@ function printHelp(showBanner = true) {
   console.log(`
 ${c.dim}${sym.boxHorizontal.repeat(64)}${c.reset}
 
-${c.green}TIERS${c.reset}
+${c.green}${sym.star} PRICING TIERS${c.reset}
+
+  ${c.green}FREE${c.reset}      ${c.dim}$0${c.reset}       scan, ship, report, context, doctor, polish - full visibility
+  ${c.magenta}PRO${c.reset}       ${c.dim}$69/mo${c.reset}   + autofix, prove, reality, mcp, guard, ai-test, PR comments
 
-  ${c.green}FREE${c.reset}      $0       init --local, scan, ship (static), report (HTML/MD), doctor, polish
-  ${c.cyan}STARTER${c.reset}   $39/mo   + init --connect, scan --autofix, report (SARIF/CSV), mcp, PR comments
-  ${c.magenta}PRO${c.reset}       $99/mo   + prove, fix --apply, checkpoint (hallucination), reality (advanced)
+${c.green}${sym.rocket} QUICK START (2 minutes to first proof)${c.reset}
 
-${c.green}QUICK START - The 5-Step Journey${c.reset}
+  ${c.bold}Option 1: One command${c.reset}
+  ${c.cyan}vibecheck quickstart${c.reset}     ${c.dim}Runs doctor → ctx → scan → ship → report${c.reset}
 
-  1. ${c.bold}Setup${c.reset}         ${c.cyan}vibecheck init --local${c.reset}
-  2. ${c.bold}Scan${c.reset}          ${c.cyan}vibecheck scan${c.reset}
-  3. ${c.bold}Fix${c.reset}           ${c.cyan}vibecheck scan --autofix${c.reset} ${c.cyan}[STARTER]${c.reset}
-  4. ${c.bold}Prove${c.reset}         ${c.cyan}vibecheck prove${c.reset} ${c.magenta}[PRO]${c.reset}
-  5. ${c.bold}Ship${c.reset}          ${c.cyan}vibecheck ship${c.reset}
+  ${c.bold}Option 2: Step by step${c.reset}
+  ${c.bold}1.${c.reset} ${c.cyan}vibecheck init${c.reset}         ${c.dim}Set up your project${c.reset}
+  ${c.bold}2.${c.reset} ${c.cyan}vibecheck scan${c.reset}         ${c.dim}Analyze your codebase${c.reset}
+  ${c.bold}3.${c.reset} ${c.cyan}vibecheck ship${c.reset}         ${c.dim}Get shipping verdict${c.reset}
+
+${c.green}${sym.lightning} COMMON WORKFLOWS${c.reset}
+
+  ${c.dim}# Quick health check${c.reset}
+  ${c.cyan}vibecheck doctor${c.reset}
+
+  ${c.dim}# Scan and auto-fix${c.reset}
+  ${c.cyan}vibecheck scan --autofix${c.reset}
+
+  ${c.dim}# Full proof with evidence pack${c.reset}
+  ${c.cyan}vibecheck prove --url http://localhost:3000 --bundle${c.reset}
 
 ${c.bold}GLOBAL OPTIONS${c.reset}
 
-  ${c.cyan}--offline, --local${c.reset}   Run in offline mode (no API, unlimited local scans)
-  ${c.cyan}--json${c.reset}               Output as JSON
-  ${c.cyan}--quiet, -q${c.reset}          Suppress output
-  ${c.cyan}--verbose${c.reset}            Show detailed output
+  ${c.cyan}--help, -h${c.reset}           Show help for any command
+  ${c.cyan}--json${c.reset}               Machine-readable JSON output
+  ${c.cyan}--quiet, -q${c.reset}          Suppress non-essential output
+  ${c.cyan}--verbose${c.reset}            Detailed output for debugging
+  ${c.cyan}--ci${c.reset}                 CI mode (quiet + no-banner)
+  ${c.cyan}--offline${c.reset}            Run without API connection
   ${c.cyan}--path, -p <dir>${c.reset}     Run in specified directory
 
 ${c.bold}SHELL COMPLETIONS${c.reset}
 
-  ${c.cyan}vibecheck completion bash${c.reset}   ${c.dim}# Add to ~/.bashrc${c.reset}
-  ${c.cyan}vibecheck completion zsh${c.reset}    ${c.dim}# Add to ~/.zshrc${c.reset}
-  ${c.cyan}vibecheck completion fish${c.reset}   ${c.dim}# Save to completions dir${c.reset}
+  ${c.cyan}vibecheck completion bash${c.reset}   ${c.dim}# Bash (add to ~/.bashrc)${c.reset}
+  ${c.cyan}vibecheck completion zsh${c.reset}    ${c.dim}# Zsh (add to ~/.zshrc)${c.reset}
+  ${c.cyan}vibecheck completion fish${c.reset}   ${c.dim}# Fish (save to completions)${c.reset}
 
-${c.dim}Run 'vibecheck <command> --help' for command-specific help.${c.reset}
+${c.dim}${sym.boxHorizontal.repeat(64)}${c.reset}
+${c.dim}Run 'vibecheck <command> --help' for detailed command help.${c.reset}
+${c.dim}Documentation: https://docs.vibecheckai.dev${c.reset}
 ${c.dim}Pricing: https://vibecheckai.dev/pricing${c.reset}
 `);
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Self-test function to verify help output matches actual commands
+ * Run with: node bin/vibecheck.js --self-test
+ */
+function validateHelpOutput() {
+  const registry = getRegistry();
+  const { COMMANDS, ALIAS_MAP } = registry;
+  
+  // Extract commands from help text (simplified - just check registry)
+  const actualCommands = Object.keys(COMMANDS);
+  const actualAliases = Object.keys(ALIAS_MAP);
+  const allActualCommands = [...actualCommands, ...actualAliases];
+  
+  // Check for obvious issues
+  const issues = [];
+  
+  // Check that all commands have runners
+  for (const [cmd, def] of Object.entries(COMMANDS)) {
+    if (!def.runner) {
+      issues.push(`Command '${cmd}' missing runner`);
+    }
+  }
+  
+  // Check that aliases point to valid commands
+  for (const [alias, target] of Object.entries(ALIAS_MAP)) {
+    if (!COMMANDS[target]) {
+      issues.push(`Alias '${alias}' points to non-existent command '${target}'`);
+    }
+  }
+  
+  if (issues.length > 0) {
+    console.error('Help output validation failed:');
+    issues.forEach(issue => console.error(`  - ${issue}`));
+    return false;
+  }
+  
+  return true;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // HELPER FUNCTIONS
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -933,6 +1061,50 @@ function formatError(error, config) {
   return lines.join("\n");
 }
 
+/**
+ * Map error to standardized exit code
+ * @param {Error} error - Error object
+ * @param {boolean} json - Whether JSON output is requested
+ * @returns {number} Exit code
+ */
+function mapErrorToExitCode(error, json = false) {
+  const EXIT_CODES = {
+    'AUTH_REQUIRED': 5,
+    'AUTH_FAILED': 6,
+    'TIER_REQUIRED': 7,
+    'RATE_LIMITED': 8,
+    'NOT_FOUND': 4,
+    'VALIDATION_ERROR': 3,
+    'USER_ERROR': 3,
+    'NETWORK_ERROR': 9,
+  };
+  
+  // Check error.code first
+  if (error.code && EXIT_CODES[error.code]) {
+    return EXIT_CODES[error.code];
+  }
+  
+  // Check error.exitCode
+  if (error.exitCode !== undefined) {
+    return error.exitCode;
+  }
+  
+  // Check error message for common patterns
+  const message = error.message?.toLowerCase() || '';
+  if (message.includes('not found') || message.includes('not exist')) {
+    return 4; // NOT_FOUND
+  }
+  if (message.includes('auth') || message.includes('login')) {
+    return 5; // AUTH_REQUIRED
+  }
+  if (message.includes('network') || message.includes('connection')) {
+    return 9; // NETWORK_ERROR
+  }
+  
+  // Default to internal error
+  return 10; // INTERNAL_ERROR
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // FLAG PARSING
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -1032,6 +1204,16 @@ async function main() {
     process.exit(0);
   }
 
+  // Handle self-test flag (for CI validation)
+  if (cleanArgs.includes('--self-test')) {
+    const registry = getRegistry();
+    if (!validateHelpOutput()) {
+      process.exit(1);
+    }
+    console.log('Self-test passed: Help output matches command registry');
+    process.exit(0);
+  }
+
   // Load config and state
   const config = loadConfig();
   const state = loadState();
@@ -1074,6 +1256,14 @@ async function main() {
   }
   let cmdArgs = cleanArgs.slice(1);
 
+  // Handle command-specific help (vibecheck <cmd> --help)
+  if (globalFlags.help && cmd && COMMANDS[cmd]) {
+    // Try our rich help first, then fall back to runner's --help
+    if (printCommandHelp(cmd)) {
+      process.exit(0);
+    }
+  }
+  
   // Pass --help to runner if specified with command
   if (globalFlags.help) cmdArgs = ["--help", ...cmdArgs];
 
@@ -1117,47 +1307,80 @@ async function main() {
   const cmdDef = COMMANDS[cmd];
   let authInfo = { key: null };
 
-  // Check for offline mode (via flag or env var)
+  // Check for offline/dev mode (via flag or env var)
+  // SECURITY: VIBECHECK_DEV_PRO only works in non-production to prevent auth bypass
+  const isDevProAllowed = process.env.NODE_ENV !== 'production' && 
+                          process.env.CI !== 'true' && 
+                          process.env.CI !== '1' &&
+                          process.env.VIBECHECK_DEV_PRO === '1';
   const isOffline = globalFlags.offline || 
                     process.env.VIBECHECK_OFFLINE === '1' || 
-                    process.env.VIBECHECK_LOCAL === '1';
+                    process.env.VIBECHECK_LOCAL === '1' ||
+                    isDevProAllowed;
 
   // Auth check (unless skipAuth or offline mode)
-  if (!cmdDef.skipAuth && !isOffline) {
+  // Only allow login, logout, whoami, and help without auth
+  const authExemptCommands = ['login', 'logout', 'whoami', 'help', '--help', '-h', 'version', '--version'];
+  const needsAuth = !authExemptCommands.includes(cmd) && !cmdDef.skipAuth && !isOffline;
+  
+  if (needsAuth) {
     const auth = getAuthModule();
     const { key } = auth.getApiKey();
     authInfo.key = key;
 
+    // If no API key, prompt for login
+    if (!key) {
+      console.log(`\n  ${c.red}❌ Authentication Required${c.reset}`);
+      console.log(`  Please log in to use vibecheck.\n`);
+      console.log(`  ${c.cyan}Options:${c.reset}`);
+      console.log(`  1. Press ${c.yellow}Enter${c.reset} to open browser and sign up`);
+      console.log(`  2. Visit ${c.underline}https://vibecheckai.dev${c.reset} directly`);
+      console.log(`  3. Run ${c.cyan}vibecheck login${c.reset} after getting your API key\n`);
+      
+      // Wait for Enter key
+      const readline = getReadline();
+      readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      }).question('', async () => {
+        try {
+          const https = getHttps();
+          const url = 'https://vibecheckai.dev';
+          console.log(`\n  Opening ${c.underline}${url}${c.reset} in your browser...\n`);
+          
+          // Try to open browser
+          const start = process.platform === 'darwin' ? 'open' : 
+                       process.platform === 'win32' ? 'start' : 'xdg-open';
+          require('child_process').exec(`${start} ${url}`);
+        } catch (e) {
+          console.log(`  Could not open browser. Please visit: ${c.underline}https://vibecheckai.dev${c.reset}`);
+        }
+        process.exit(0);
+      });
+      
+      // Keep process alive
+      return new Promise(() => {});
+    }
+
     const access = await checkCommandAccess(cmd, cmdArgs, authInfo);
 
     if (!access.allowed) {
       console.log(access.reason);
-      process.exit(access.exitCode || 3);
-    }
-
-    // Downgrade notice
-    if (access.downgrade && !config.quiet) {
-      const upsell = getUpsell();
-      console.log(upsell.formatDowngrade(cmd, {
-        currentTier: access.tier,
-        effectiveMode: access.downgrade,
-        caps: access.caps,
-      }));
-    }
-
-    // Tier badge
-    if (!config.quiet && !config.noBanner) {
-      if (access.tier === "pro") {
-        console.log(`${c.magenta}${sym.arrowRight} PRO${c.reset} ${c.dim}feature${c.reset}`);
-      } else if (access.tier === "complete") {
-        console.log(`${c.yellow}${sym.arrowRight} COMPLETE${c.reset} ${c.dim}feature${c.reset}`);
+      
+      // Show upgrade prompt if tier insufficient
+      if (access.upgradeUrl) {
+        console.log(`\n  ${c.cyan}Upgrade:${c.reset} ${access.upgradeUrl}`);
       }
+      
+      return 1;
     }
 
     authInfo.access = access;
   } else if (isOffline) {
     // Offline mode - provide basic access info
-    if (!config.quiet && !config.noBanner) {
+    // Suppress message if JSON/SARIF output is requested (check both global flags and command args)
+    const hasJsonOutput = globalFlags.json || cmdArgs.includes('--json') || cmdArgs.includes('--sarif');
+    if (!config.quiet && !config.noBanner && !hasJsonOutput) {
       console.log(`${c.cyan}${sym.arrowRight} OFFLINE${c.reset} ${c.dim}mode - local scanning without API${c.reset}`);
     }
     authInfo.access = {
@@ -1186,7 +1409,7 @@ async function main() {
     const runner = getRunner(cmd);
     if (!runner) {
       console.error(`${c.red}${sym.error}${c.reset} Failed to load runner for: ${cmd}`);
-      process.exit(1);
+      process.exit(4); // NOT_FOUND
     }
 
     const context = {
@@ -1201,10 +1424,32 @@ async function main() {
     };
 
     // Execute command - all commands use consistent runner signature
-    exitCode = await runner(cmdArgs, context);
+    const result = await runner(cmdArgs, context);
+    
+    // Ensure result has standardized exit code
+    if (typeof result === 'object' && result.exitCode !== undefined) {
+      exitCode = result.exitCode;
+    } else if (typeof result === 'number') {
+      exitCode = result;
+    } else {
+      exitCode = 0; // SUCCESS
+    }
   } catch (error) {
-    console.error(formatError(error, config));
-    exitCode = 1;
+    // Map errors to exit codes
+    exitCode = mapErrorToExitCode(error, globalFlags.json);
+    
+    if (globalFlags.json) {
+      console.log(JSON.stringify({
+        success: false,
+        error: {
+          code: error.code || 'INTERNAL_ERROR',
+          message: error.message,
+        },
+        exitCode,
+      }, null, 2));
+    } else {
+      console.error(formatError(error, config));
+    }
   }
 
   // Create receipt for paid commands