@vibecheckai/cli 3.2.6 → 3.3.0

package/bin/registry.js

@@ -3,31 +3,37 @@
  *
  * Single source of truth for the public CLI surface.
  * If it isn't here, it does not exist.
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * WORLD-CLASS CLI - Enhanced Registry with Rich Metadata
+ * ═══════════════════════════════════════════════════════════════════════════════
  */
 
 "use strict";
 
 // ─────────────────────────────────────────────────────────────
-// CORE 17 COMMANDS (locked surface area)
+// CORE 19 COMMANDS (locked surface area)
 // ─────────────────────────────────────────────────────────────
 const ALLOWED_COMMANDS = new Set([
-  // FREE (8) - Core functionality to try the product
+  // FREE (9) - Core functionality to try the product
   "init",       // one-time setup
   "doctor",     // health check
   "watch",      // continuous mode
   "scan",       // includes --allowlist subcommand
   "ship",       // verdict engine
+  "classify",   // Authority: inventory (duplication/legacy maps)
   "login",      // authenticate
   "logout",     // remove credentials
   "whoami",     // show current user
 
-  // STARTER (6) - Productivity & automation
+  // STARTER (7) - Productivity & automation
   "fix",        // AI-powered fixes
   "report",     // generate reports
   "context",    // generate IDE rules
   "guard",      // AI guardrails (prompt firewall, hallucination checking)
   "mcp",        // MCP server
   "checkpoint", // baseline comparison & hallucination scoring
+  "approve",    // Authority: get verdicts for authorities
 
   // PRO (3) - Advanced proof & AI testing
   "prove",      // includes --bundle for evidence packs
@@ -43,7 +49,7 @@ function assertAllowedOnly(obj) {
 }
 
 // ─────────────────────────────────────────────────────────────
-// COMMANDS (ALLOWED ONLY)
+// COMMANDS (ALLOWED ONLY) - Enhanced with World-Class Metadata
 // ─────────────────────────────────────────────────────────────
 const COMMANDS = {
   // ══════════════════════════════════════════════════════════════
@@ -53,123 +59,277 @@ const COMMANDS = {
   // ── SETUP ───────────────────────────────────────────────────
   init: {
     description: "One-time setup (config + contracts + scripts)",
+    longDescription: "Initialize vibecheck in your project. Creates configuration files, sets up IDE rules, and optionally connects to the vibecheck dashboard for team collaboration.",
     tier: "free",
     category: "setup",
     aliases: ["setup", "configure"],
     runner: () => require("./runners/runInit").runInit,
+    examples: [
+      { command: "vibecheck init", description: "Interactive setup wizard" },
+      { command: "vibecheck init --local", description: "Quick local-only setup (no API)" },
+      { command: "vibecheck init --connect", description: "Setup with GitHub integration", tier: "starter" },
+      { command: "vibecheck init --quick", description: "Non-interactive with sensible defaults" },
+    ],
+    related: ["doctor", "scan"],
+    docsUrl: "https://docs.vibecheckai.dev/getting-started",
   },
 
   doctor: {
     description: "Environment + dependency + config health check",
+    longDescription: "Comprehensive diagnostics for your development environment. Checks Node.js, package managers, project configuration, and vibecheck setup. Can auto-fix common issues.",
     tier: "free",
     category: "setup",
     aliases: ["health", "diag"],
     runner: () => require("./runners/runDoctor").runDoctor,
+    examples: [
+      { command: "vibecheck doctor", description: "Run all health checks" },
+      { command: "vibecheck doctor --fix", description: "Auto-fix detected issues" },
+      { command: "vibecheck doctor --json", description: "Output diagnostics as JSON" },
+    ],
+    related: ["init", "scan"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/doctor",
   },
 
   watch: {
     description: "Continuous mode - re-runs on changes",
+    longDescription: "File watcher that automatically re-runs scans when your code changes. Ideal for development workflows where you want instant feedback.",
     tier: "free",
     category: "setup",
     aliases: ["w", "dev"],
     runner: () => require("./runners/runWatch").runWatch,
+    examples: [
+      { command: "vibecheck watch", description: "Start watching current directory" },
+      { command: "vibecheck watch --path ./src", description: "Watch specific directory" },
+      { command: "vibecheck watch --debounce 1000", description: "Custom debounce (1 second)" },
+    ],
+    related: ["scan", "ship"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/watch",
   },
 
   // ── CORE LOOP ───────────────────────────────────────────────
   scan: {
     description: "Route integrity & code analysis; use --allowlist for false positive management",
+    longDescription: "The core analysis engine. Scans your codebase for route integrity issues, security vulnerabilities, code quality problems, and more. Supports multiple scan layers: AST (fast), Truth (build manifests), and Reality (runtime browser testing).",
     tier: "free",
     category: "proof",
     aliases: ["s", "check"],
     runner: () => require("./runners/runScan").runScan,
+    examples: [
+      { command: "vibecheck scan", description: "Quick AST scan (Layer 1)" },
+      { command: "vibecheck scan --truth", description: "Include build manifest verification" },
+      { command: "vibecheck scan --reality --url http://localhost:3000", description: "Full runtime proof", tier: "pro" },
+      { command: "vibecheck scan --autofix", description: "Generate AI fix missions", tier: "starter" },
+      { command: "vibecheck scan --allowlist list", description: "View suppressed findings" },
+      { command: "vibecheck scan --allowlist add --id R_DEAD_xyz --reason 'Known toggle'", description: "Suppress false positive" },
+    ],
+    related: ["ship", "fix", "prove"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/scan",
   },
 
   ship: {
     description: "Verdict engine - SHIP / WARN / BLOCK",
+    longDescription: "The final word on whether your code is ready to ship. Combines all scan results, generates proof graphs, and renders a clear SHIP/WARN/BLOCK verdict. Use before every deployment.",
     tier: "free",
     category: "proof",
     aliases: ["verdict", "go"],
     runner: () => require("./runners/runShip").runShip,
+    examples: [
+      { command: "vibecheck ship", description: "Get shipping verdict" },
+      { command: "vibecheck ship --strict", description: "Fail on any warnings" },
+      { command: "vibecheck ship --badge", description: "Generate status badge" },
+      { command: "vibecheck ship --fix", description: "Attempt auto-fixes then re-check" },
+    ],
+    related: ["scan", "prove", "fix"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/ship",
   },
 
   // ── ACCOUNT (skipAuth) ────────────────────────────────────
   login: {
     description: "Authenticate with API key",
+    longDescription: "Connect your CLI to the vibecheck API. Required for dashboard sync, team features, and paid tier commands.",
     tier: "free",
     category: "account",
     aliases: ["auth", "signin"],
     runner: () => require("./runners/runAuth").runLogin,
     skipAuth: true,
+    examples: [
+      { command: "vibecheck login", description: "Interactive login (opens browser)" },
+      { command: "vibecheck login --key YOUR_API_KEY", description: "Login with API key directly" },
+      { command: "VIBECHECK_API_KEY=xxx vibecheck scan", description: "Use env var (CI/CD)" },
+    ],
+    related: ["logout", "whoami"],
+    docsUrl: "https://docs.vibecheckai.dev/authentication",
   },
 
   logout: {
     description: "Remove stored credentials",
+    longDescription: "Clear your stored API key and log out of the vibecheck CLI.",
     tier: "free",
     category: "account",
     aliases: ["signout"],
     runner: () => require("./runners/runAuth").runLogout,
     skipAuth: true,
+    examples: [
+      { command: "vibecheck logout", description: "Clear stored credentials" },
+    ],
+    related: ["login", "whoami"],
+    docsUrl: "https://docs.vibecheckai.dev/authentication",
   },
 
   whoami: {
     description: "Show current user and plan",
+    longDescription: "Display your current authentication status, subscription tier, and usage limits.",
     tier: "free",
     category: "account",
     aliases: ["me", "user"],
     runner: () => require("./runners/runAuth").runWhoami,
     skipAuth: true,
+    examples: [
+      { command: "vibecheck whoami", description: "Show current user info" },
+      { command: "vibecheck whoami --json", description: "Output as JSON" },
+    ],
+    related: ["login", "logout"],
+    docsUrl: "https://docs.vibecheckai.dev/authentication",
+  },
+
+  // ── AUTHORITY SYSTEM (FREE) ──────────────────────────────────
+  classify: {
+    description: "Inventory authority - duplication & legacy code maps",
+    longDescription: "Produces a read-only inventory of your codebase including duplication maps, legacy code detection, and risk classifications. Part of the Authority System - read-only analysis available on FREE tier.",
+    tier: "free",
+    category: "authority",
+    aliases: ["inventory", "audit"],
+    runner: () => require("./runners/runClassify").runClassify,
+    examples: [
+      { command: "vibecheck classify", description: "Quick inventory analysis" },
+      { command: "vibecheck classify --json", description: "JSON output for processing" },
+      { command: "vibecheck classify --include-semantic", description: "Include semantic duplicates" },
+      { command: "vibecheck classify --output inventory.md --format markdown", description: "Save as markdown" },
+    ],
+    related: ["approve", "scan"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/classify",
   },
 
   // ══════════════════════════════════════════════════════════════
-  // STARTER TIER (6 commands) - Productivity & automation
+  // STARTER TIER (7 commands) - Productivity & automation
   // ══════════════════════════════════════════════════════════════
 
   fix: {
     description: "AI-powered auto-fix for findings",
+    longDescription: "Generate surgical AI prompts (missions) to fix detected issues. Each mission includes context, constraints, and verification steps. Use --apply to let AI make changes directly.",
     tier: "starter",
     category: "proof",
     aliases: ["f", "repair"],
     runner: () => require("./runners/runFix").runFix,
+    examples: [
+      { command: "vibecheck fix", description: "Generate fix missions (prompts only)" },
+      { command: "vibecheck fix --apply", description: "Apply AI-generated fixes" },
+      { command: "vibecheck fix --loop", description: "Continuous fix loop until clean" },
+      { command: "vibecheck fix --max-missions 5", description: "Limit to 5 missions" },
+    ],
+    related: ["scan", "checkpoint", "ship"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/fix",
   },
 
   report: {
     description: "Generate HTML/MD/SARIF reports",
+    longDescription: "Create beautiful, shareable reports from your scan results. Supports multiple formats for different audiences: HTML for stakeholders, Markdown for docs, SARIF for GitHub code scanning.",
     tier: "starter",
     category: "output",
     aliases: ["html", "artifact"],
     runner: () => require("./runners/runReport").runReport,
+    examples: [
+      { command: "vibecheck report", description: "Generate HTML report" },
+      { command: "vibecheck report --format md", description: "Markdown report" },
+      { command: "vibecheck report --format sarif", description: "SARIF for GitHub" },
+      { command: "vibecheck report --type executive", description: "Executive summary" },
+      { command: "vibecheck report --output ./reports", description: "Custom output directory" },
+    ],
+    related: ["scan", "prove"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/report",
   },
 
   context: {
     description: "Generate IDE rules (.cursorrules, MDC, Windsurf, Copilot)",
+    longDescription: "Generate project-aware AI coding rules for your IDE. These rules help AI assistants understand your codebase conventions, preventing common mistakes and enforcing patterns.",
     tier: "starter",
     category: "truth",
     aliases: ["rules", "ai-rules", "mdc"],
     runner: () => require("./runners/runContext").runContext,
+    examples: [
+      { command: "vibecheck context", description: "Generate all IDE rule formats" },
+      { command: "vibecheck context --format cursor", description: ".cursorrules only" },
+      { command: "vibecheck context --format mdc", description: "MDC format (Cursor)" },
+      { command: "vibecheck context --format copilot", description: "GitHub Copilot instructions" },
+    ],
+    related: ["scan", "guard"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/context",
   },
 
   guard: {
     description: "AI guardrails - prompt firewall & hallucination checking",
+    longDescription: "Validate AI-generated code and prompts. Detects prompt injection attempts, verifies claims against your codebase (hallucination checking), and ensures AI outputs meet your standards.",
     tier: "starter",
     category: "truth",
     aliases: ["ai-guard", "firewall", "validate"],
     runner: () => require("./runners/runGuard").runGuard,
+    examples: [
+      { command: "vibecheck guard", description: "Run all guardrail checks" },
+      { command: "vibecheck guard --claims", description: "Verify AI claims against codebase" },
+      { command: "vibecheck guard --prompts", description: "Check for prompt injection" },
+      { command: "vibecheck guard --hallucinations", description: "Detect hallucinated code" },
+    ],
+    related: ["context", "checkpoint", "fix"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/guard",
   },
 
   mcp: {
     description: "Start MCP server for AI IDEs",
+    longDescription: "Launch a Model Context Protocol (MCP) server that integrates vibecheck directly into AI IDEs like Cursor. Enables real-time code analysis, fix suggestions, and proof verification within your editor.",
     tier: "starter",
     category: "automation",
     aliases: [],
     runner: () => require("./runners/runMcp").runMcp,
+    examples: [
+      { command: "vibecheck mcp", description: "Start MCP server" },
+      { command: "vibecheck mcp --port 3099", description: "Custom port" },
+    ],
+    related: ["context", "guard"],
+    docsUrl: "https://docs.vibecheckai.dev/integrations/mcp",
   },
 
   checkpoint: {
     description: "Compare baseline vs current, hallucination scoring",
+    longDescription: "Track changes between scan runs. Detects new issues, resolved issues, and regressions. Includes hallucination scoring to measure drift from your codebase's ground truth.",
     tier: "starter",
     category: "analysis",
     aliases: ["cp", "compare", "diff"],
     runner: () => require("./runners/runCheckpoint").runCheckpoint,
+    examples: [
+      { command: "vibecheck checkpoint", description: "Compare against last baseline" },
+      { command: "vibecheck checkpoint --set", description: "Save current as new baseline" },
+      { command: "vibecheck checkpoint --score", description: "Calculate hallucination score" },
+    ],
+    related: ["scan", "fix", "guard"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/checkpoint",
+  },
+
+  // ── AUTHORITY SYSTEM (STARTER) ───────────────────────────────
+  approve: {
+    description: "Authority verdicts - PROCEED/STOP/DEFER with proofs",
+    longDescription: "Execute authorities to get structured verdicts with proofs. Part of the Authority System - transforms prompts into enforceable policy engines. Requires STARTER for advisory verdicts, PRO for enforcement.",
+    tier: "starter",
+    category: "authority",
+    aliases: ["auth-verdict", "authority"],
+    runner: () => require("./runners/runApprove").runApprove,
+    examples: [
+      { command: "vibecheck approve safe-consolidation", description: "Run safe-consolidation authority" },
+      { command: "vibecheck approve --list", description: "List available authorities" },
+      { command: "vibecheck approve safe-consolidation --json", description: "JSON output for CI" },
+      { command: "vibecheck approve safe-consolidation --badge", description: "Generate badge for PROCEED", tier: "pro" },
+    ],
+    related: ["classify", "scan", "ship"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/approve",
   },
 
   // ══════════════════════════════════════════════════════════════
@@ -178,6 +338,7 @@ const COMMANDS = {
 
   reality: {
     description: "Runtime proof (browser crawl); use --agent for AI testing",
+    longDescription: "Browser-based runtime verification. Crawls your app with Playwright, records video/traces/HAR, verifies routes actually work, and captures network evidence. Use --agent for AI-driven autonomous testing.",
     tier: "pro",
     category: "proof",
     caps: "--agent for AI autonomous testing",
@@ -191,23 +352,49 @@ const COMMANDS = {
       }
       return await runRuntime(["crawl", ...args], ctx);
     },
+    examples: [
+      { command: "vibecheck reality --url http://localhost:3000", description: "Crawl and verify routes" },
+      { command: "vibecheck reality --url http://localhost:3000 --headed", description: "Watch browser in action" },
+      { command: "vibecheck reality --agent --url http://localhost:3000", description: "AI autonomous testing" },
+      { command: "vibecheck reality --auth ./auth.json", description: "Test with authentication" },
+    ],
+    related: ["prove", "scan", "ship"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/reality",
   },
 
   prove: {
     description: "One command reality proof - video + network evidence that your app works",
+    longDescription: "The ultimate verification command. Runs the full 5-step pipeline: context → reality → ship → fix → verify. Generates a complete evidence pack with video recordings, network traces, and proof artifacts. Perfect for audits and stakeholder demos.",
     tier: "pro",
     category: "proof",
     aliases: ["p", "full", "all"],
     caps: "video, trace, HAR recording; use --bundle for evidence pack",
     runner: () => require("./runners/runProve").runProve,
+    examples: [
+      { command: "vibecheck prove --url http://localhost:3000", description: "Full proof pipeline" },
+      { command: "vibecheck prove --url http://localhost:3000 --bundle", description: "Generate shareable evidence pack" },
+      { command: "vibecheck prove --url http://localhost:3000 --stability-runs 3", description: "Run 3x for stability" },
+      { command: "vibecheck prove --skip-fix", description: "Skip auto-fix step" },
+    ],
+    related: ["reality", "scan", "report"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/prove",
   },
 
   polish: {
     description: "Production polish analyzer - finds missing essentials",
+    longDescription: "Deep analysis for production readiness. Checks for missing essentials like error handling, loading states, empty states, accessibility, SEO, performance patterns, and more. Generates a prioritized punch list.",
     tier: "pro",
     category: "quality",
     aliases: ["quality", "finalize", "ready"],
     runner: () => require("./runners/runPolish").runPolish,
+    examples: [
+      { command: "vibecheck polish", description: "Full production readiness check" },
+      { command: "vibecheck polish --category accessibility", description: "Focus on a11y" },
+      { command: "vibecheck polish --category performance", description: "Focus on perf" },
+      { command: "vibecheck polish --severity high", description: "Only high-priority items" },
+    ],
+    related: ["scan", "ship", "prove"],
+    docsUrl: "https://docs.vibecheckai.dev/cli/polish",
   },
 };