@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/runShip.js

@@ -18,10 +18,9 @@ const {
   generateRunId, 
   createJsonOutput, 
   writeJsonOutput, 
-  exitCodeToVerdict,
-  verdictToExitCode,
   saveArtifact 
 } = require("./lib/cli-output");
+const { EXIT, verdictToExitCode, exitCodeToVerdict } = require("./lib/exit-codes");
 
 // Route Truth v1 - Fake endpoint detection
 const { buildTruthpack, writeTruthpack, detectFastifyEntry } = require("./lib/truth");
@@ -828,7 +827,7 @@ async function runShip(args, context = {}) {
   } catch (err) {
     if (err.code === 'LIMIT_EXCEEDED' || err.code === 'FEATURE_NOT_AVAILABLE') {
       console.error(`\n  ${colors.error}${icons.error}${ansi.reset} ${err.upgradePrompt || err.message}\n`);
-      return EXIT_CODES.WARN;
+      return EXIT.TIER_REQUIRED;
     }
     throw err;
   }
@@ -1131,7 +1130,7 @@ async function runShip(args, context = {}) {
       console.error(`  ${ansi.dim}${error.stack}${ansi.reset}`);
     }
     
-    return EXIT_CODES.ERROR;
+    return EXIT.INTERNAL_ERROR;
   }
 }
 

package/bin/runners/runTruth.d.ts

@@ -0,0 +1,5 @@
+export interface TruthOptions {
+  projectRoot?: string;
+  verbose?: boolean;
+}
+export function runTruth(options?: TruthOptions): Promise<void>;

package/bin/runners/runValidate.js

@@ -6,6 +6,9 @@ const fs = require("fs");
 const path = require("path");
 const { buildTruthpack } = require("./lib/truth");
 const { routeMatches } = require("./lib/claims");
+const { EXIT } = require("./lib/exit-codes");
+const { formatSoftUpsell, formatWorkflowUpsell, PRICING_URL } = require("./lib/upsell");
+const { getApiKey } = require("./lib/auth");
 
 const c = {
   reset: "\x1b[0m",
@@ -133,12 +136,19 @@ async function runValidate(args) {
     }
     
     // Output results
+    const { key } = getApiKey();
+    const currentTier = key ? "starter" : "free";
+    
     if (opts.json) {
       console.log(JSON.stringify({ issues, valid: issues.length === 0 }, null, 2));
     } else {
       if (issues.length === 0) {
         console.log(`${c.green}✓${c.reset} No hallucinations detected!\n`);
         console.log(`  ${c.dim}All routes and env vars are properly defined.${c.reset}\n`);
+        
+        // Workflow upsell
+        const workflow = formatWorkflowUpsell("validate", currentTier);
+        if (workflow) console.log(`  ${workflow}\n`);
       } else {
         console.log(`${c.yellow}⚠${c.reset} Found ${issues.length} potential issues:\n`);
         
@@ -148,14 +158,21 @@ async function runValidate(args) {
           console.log(`    ${c.dim}${issue.file}:${issue.line}${c.reset}`);
         }
         console.log();
+        
+        // Upsell for auto-fix
+        if (currentTier === "free") {
+          console.log(`  ${c.dim}─────────────────────────────────────────────────────────────${c.reset}`);
+          console.log(`  ${c.cyan}★ STARTER${c.reset}${c.dim}: auto-fix hallucinations with vibecheck fix${c.reset}`);
+          console.log(`  ${c.dim}  Upgrade → ${PRICING_URL}${c.reset}\n`);
+        }
       }
     }
     
-    return issues.some(i => i.severity === "error") ? 1 : 0;
+    return issues.some(i => i.severity === "error") ? EXIT.BLOCKING : EXIT.SUCCESS;
     
   } catch (error) {
     console.error(`${c.red}✗${c.reset} Validation failed: ${error.message}`);
-    return 1;
+    return EXIT.INTERNAL_ERROR;
   }
 }
 

package/bin/runners/runWatch.js

@@ -14,7 +14,8 @@
 
 const fs = require("fs");
 const path = require("path");
-const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+const { parseGlobalFlags, shouldShowBanner, shouldSuppressOutput } = require("./lib/global-flags");
+const { EXIT } = require("./lib/exit-codes");
 const { shipCore } = require("./runShip");
 
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -331,12 +332,15 @@ function printHelp(opts = {}) {
 async function runWatch(argsOrOpts = {}) {
   // Handle array args from CLI
   let globalOpts = { noBanner: false, json: false, quiet: false, ci: false };
+  let rawArgs = [];
+  
   if (Array.isArray(argsOrOpts)) {
+    rawArgs = argsOrOpts;
     const { flags } = parseGlobalFlags(argsOrOpts);
     globalOpts = { ...globalOpts, ...flags };
     if (globalOpts.help) {
       printHelp(globalOpts);
-      return 0;
+      return EXIT.SUCCESS;
     }
     const getArg = (flags) => {
       for (const f of flags) {
@@ -346,10 +350,10 @@ async function runWatch(argsOrOpts = {}) {
       return undefined;
     };
     argsOrOpts = {
-      repoRoot: process.cwd(),
+      repoRoot: globalOpts.path || process.cwd(),
       fastifyEntry: getArg(["--fastify-entry"]),
       debounceMs: parseInt(getArg(["--debounce"]) || "500", 10),
-      clearScreen: !argsOrOpts.includes("--no-clear"),
+      clearScreen: !rawArgs.includes("--no-clear"),
       ...globalOpts,
     };
   }
@@ -358,70 +362,117 @@ async function runWatch(argsOrOpts = {}) {
     repoRoot,
     fastifyEntry,
     debounceMs = 500,
-    clearScreen = true
+    clearScreen = true,
+    quiet,
   } = argsOrOpts;
 
   const root = repoRoot || process.cwd();
+  const suppress = shouldSuppressOutput(argsOrOpts);
+  
+  // Validate project path exists
+  if (!fs.existsSync(root)) {
+    console.error(`${c.red}✗${c.reset} Project path does not exist: ${root}`);
+    console.log(`  ${c.dim}Verify the path and try again.${c.reset}`);
+    return EXIT.NOT_FOUND;
+  }
+  
+  // Validate debounce is a valid number
+  if (isNaN(debounceMs) || debounceMs < 0) {
+    console.error(`${c.red}✗${c.reset} Invalid debounce value: ${debounceMs}`);
+    console.log(`  ${c.dim}Debounce must be a positive number in milliseconds.${c.reset}`);
+    return EXIT.USER_ERROR;
+  }
+  
   let runCount = 0;
   let lastFile = null;
+  let watcher = null;
+  let exitCode = EXIT.SUCCESS;
 
-  console.log(`${c.cyan}Starting vibecheck watch...${c.reset}\n`);
-
-  async function runAndDisplay() {
-    runCount++;
-    
-    if (clearScreen) {
-      process.stdout.write(c.clear);
+  try {
+    if (!suppress) {
+      console.log(`${c.cyan}Starting vibecheck watch...${c.reset}\n`);
     }
 
-    const result = await runShipQuiet(root, fastifyEntry);
+    async function runAndDisplay() {
+      runCount++;
+      
+      if (clearScreen && !suppress) {
+        process.stdout.write(c.clear);
+      }
+
+      try {
+        const result = await runShipQuiet(root, fastifyEntry);
 
-    if (result.error) {
-      console.log(`${c.red}Error: ${result.error}${c.reset}`);
-      return;
+        if (result.error) {
+          if (!suppress) {
+            console.log(`${c.red}Error: ${result.error}${c.reset}`);
+            console.log(`  ${c.dim}Will retry on next file change.${c.reset}`);
+          }
+          return;
+        }
+
+        if (!suppress) {
+          printStatus({
+            verdict: result.verdict,
+            findings: result.findings,
+            duration: result.duration,
+            lastFile,
+            runCount
+          });
+
+          printTopFindings(result.findings);
+        }
+      } catch (e) {
+        if (!suppress) {
+          console.log(`${c.red}Analysis error: ${e.message}${c.reset}`);
+        }
+      }
     }
 
-    printStatus({
-      verdict: result.verdict,
-      findings: result.findings,
-      duration: result.duration,
-      lastFile,
-      runCount
+    // Initial run
+    await runAndDisplay();
+
+    // Watch for changes
+    const debouncedRun = debounce(async (filePath) => {
+      lastFile = path.relative(root, filePath);
+      await runAndDisplay();
+    }, debounceMs);
+
+    watcher = watchDirectory(root, (filePath) => {
+      // Only watch source files
+      if (!/\.(ts|tsx|js|jsx|json|env|md|yml|yaml)$/.test(filePath)) return;
+      if (shouldIgnore(filePath)) return;
+      debouncedRun(filePath);
     });
 
-    printTopFindings(result.findings);
-  }
+    // Handle cleanup - store cleanup function for signal handlers
+    const cleanup = () => {
+      if (watcher) {
+        watcher.close();
+        watcher = null;
+      }
+    };
 
-  // Initial run
-  await runAndDisplay();
+    process.on("SIGINT", () => {
+      if (!suppress) {
+        console.log(`\n${c.dim}Watch stopped.${c.reset}`);
+      }
+      cleanup();
+      process.exit(EXIT.SUCCESS);
+    });
 
-  // Watch for changes
-  const debouncedRun = debounce(async (filePath) => {
-    lastFile = path.relative(root, filePath);
-    await runAndDisplay();
-  }, debounceMs);
-
-  const watcher = watchDirectory(root, (filePath) => {
-    // Only watch source files
-    if (!/\.(ts|tsx|js|jsx|json|env|md|yml|yaml)$/.test(filePath)) return;
-    if (shouldIgnore(filePath)) return;
-    debouncedRun(filePath);
-  });
-
-  // Handle cleanup
-  process.on("SIGINT", () => {
-    console.log(`\n${c.dim}Watch stopped.${c.reset}`);
-    watcher.close();
-    process.exit(0);
-  });
-
-  process.on("SIGTERM", () => {
-    watcher.close();
-    process.exit(0);
-  });
-
-  // Keep process alive
-  await new Promise(() => {});
+    process.on("SIGTERM", () => {
+      cleanup();
+      process.exit(EXIT.SUCCESS);
+    });
+
+    // Keep process alive
+    await new Promise(() => {});
+  } catch (error) {
+    console.error(`${c.red}✗${c.reset} Watch failed: ${error.message}`);
+    if (watcher) watcher.close();
+    return EXIT.INTERNAL_ERROR;
+  }
 }
 
 module.exports = { runWatch };

package/bin/vibecheck.js

@@ -795,7 +795,7 @@ ${c.bold}Installation:${c.reset}
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// HELP SYSTEM
+// HELP SYSTEM - World-Class CLI Experience
 // ═══════════════════════════════════════════════════════════════════════════════
 function printBanner() {
   const VERSION = getVersion();
@@ -807,6 +807,72 @@ ${c.dim}${sym.boxBottomLeft}${sym.boxHorizontal.repeat(60)}${sym.boxBottomRight}
 `);
 }
 
+/**
+ * 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
+  const tierBadge = def.tier === "free" ? `${c.green}[FREE]${c.reset}` :
+                    def.tier === "starter" ? `${c.cyan}[STARTER]${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 ? (ex.tier === "starter" ? `${c.cyan}[STARTER]${c.reset} ` : 
+                               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 === "starter" ? `${c.cyan}[STARTER]${c.reset} ` :
+                       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();
 
@@ -874,35 +940,48 @@ 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}      $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}FREE${c.reset}      ${c.dim}$0${c.reset}       Core scanning, shipping verdicts, health checks
+  ${c.cyan}STARTER${c.reset}   ${c.dim}$39/mo${c.reset}   + AI fixes, reports, IDE rules, MCP server
+  ${c.magenta}PRO${c.reset}       ${c.dim}$99/mo${c.reset}   + Reality proof, video evidence, AI testing
 
-${c.green}QUICK START - The 5-Step Journey${c.reset}
+${c.green}${sym.rocket} QUICK START${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}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}
 `);
 }
@@ -1074,6 +1153,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];