vibecheck-ai 2.0.1 → 5.0.0

package/bin/registry.js

@@ -0,0 +1,656 @@
+/**
+ * Vibecheck CLI Command Registry
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * VERSION 5.0.0 — CLEAN SURFACE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Single source of truth for the public CLI surface.
+ * 
+ * 12 top-level commands. Everything else is a subcommand, alias, or hidden.
+ * Product story: Scan → Ship → Certify
+ * 
+ * 2-tier model:
+ * - FREE ($0): Inspect & Observe
+ * - PRO ($49/mo): Fix, Prove & Enforce
+ * 
+ * @version 5.0.0
+ */
+
+"use strict";
+
+// ─────────────────────────────────────────────────────────────
+// 12 TOP-LEVEL COMMANDS (the only things users see in --help)
+// ─────────────────────────────────────────────────────────────
+const ALLOWED_COMMANDS = new Set([
+  "kickoff",
+  "scan",
+  "ship",
+  "fix",
+  "certify",
+  "report",
+  "reality",
+  "firewall",
+  "ci",
+  "mcp",
+  "config",
+  "doctor",
+]);
+
+function assertAllowedOnly(obj) {
+  const extras = Object.keys(obj).filter((k) => !ALLOWED_COMMANDS.has(k));
+  if (extras.length) {
+    throw new Error(`Registry contains non-allowed commands: ${extras.join(", ")}`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// 12 COMMANDS — Clean Surface
+// ─────────────────────────────────────────────────────────────
+const COMMANDS = {
+
+  // ══════════════════════════════════════════════════════════════
+  // GETTING STARTED
+  // ══════════════════════════════════════════════════════════════
+
+  kickoff: {
+    description: "Get started in 60 seconds — detects your project, wires everything, first scan + verdict",
+    longDescription: "One command onboarding: link → detect → config → forge → first scan → first ship result → (optional) connect account. Absorbs init, setup, quickstart, link.",
+    tier: "free",
+    category: "start",
+    runner: () => require("./runners/runKickoff").runKickoff,
+    subcommands: [
+      { name: "link", description: "Bind project (<10s, zero questions)" },
+      { name: "config", description: "Edit project configuration" },
+      { name: "doctor", description: "Check environment health" },
+    ],
+    examples: [
+      { command: "vibecheck kickoff", description: "60-second first run" },
+      { command: "vibecheck kickoff --fast", description: "30-second fast mode" },
+      { command: "vibecheck kickoff --no-ship", description: "Skip ship verdict" },
+    ],
+    related: ["scan", "ship", "doctor"],
+  },
+
+  doctor: {
+    description: "Environment + dependency + config health check",
+    longDescription: "Comprehensive diagnostics for your development environment.",
+    tier: "free",
+    category: "start",
+    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 as JSON" },
+    ],
+    related: ["kickoff", "config"],
+  },
+
+  // ══════════════════════════════════════════════════════════════
+  // CORE LOOP: Scan → Ship → Certify
+  // ══════════════════════════════════════════════════════════════
+
+  scan: {
+    description: "Analyze your project — find code that LOOKS done but DOESN'T work",
+    longDescription: "The unified analysis command. Detects dead routes, ghost env vars, fake success UI, auth drift, mock landmines, silent failures. Subcommands for targeted scans.",
+    tier: "free",
+    category: "core",
+    runner: () => require("./runners/runScan").runScan,
+    subcommands: [
+      { name: "secrets", description: "Scan for leaked secrets & credentials" },
+      { name: "vulns", description: "Scan dependencies for vulnerabilities (OSV/CVE)" },
+      { name: "routes", description: "Scan for dead/orphan routes" },
+      { name: "env", description: "Scan for ghost environment variables" },
+      { name: "auth", description: "Scan for auth drift & unprotected endpoints" },
+    ],
+    examples: [
+      { command: "vibecheck scan", description: "Full project scan" },
+      { command: "vibecheck scan secrets", description: "Secrets only" },
+      { command: "vibecheck scan vulns", description: "Vulnerability scan" },
+      { command: "vibecheck scan --deep", description: "Deep cross-file analysis" },
+      { command: "vibecheck scan --fail-on critical", description: "CI gate mode" },
+      { command: "vibecheck scan --sarif", description: "SARIF output for GitHub" },
+    ],
+    related: ["ship", "fix", "certify"],
+  },
+
+  ship: {
+    description: "Verdict engine — SHIP / WARN / BLOCK",
+    longDescription: "The final word on whether your code is ready to ship. Includes preflight mode for comprehensive pre-release validation.",
+    tier: "pro",
+    category: "core",
+    runner: () => require("./runners/runShip").runShip,
+    subcommands: [
+      { name: "preflight", description: "Pre-release validation wizard (last 10 min before deploy)" },
+    ],
+    examples: [
+      { command: "vibecheck ship", description: "Get shipping verdict" },
+      { command: "vibecheck ship --strict", description: "Fail on warnings" },
+      { command: "vibecheck ship preflight", description: "Full pre-release checklist" },
+      { command: "vibecheck ship preflight --ci", description: "CI mode (non-interactive)" },
+    ],
+    related: ["scan", "fix", "certify"],
+  },
+
+  fix: {
+    description: "Mission-based auto-fix with safety gates",
+    longDescription: "Fix Missions V2 — 'Missions, not chaos'. Small, reversible fix missions with pre-flight/post-flight safety gates, checkpoint-based rollback, and plan-only mode.",
+    tier: "pro",
+    category: "core",
+    runner: () => require("./runners/runFix").runFix,
+    subcommands: [
+      { name: "missions", description: "List fix missions grouped by category" },
+      { name: "checkpoint", description: "Snapshot & restore (time machine)" },
+      { name: "polish", description: "Final production cleanup" },
+    ],
+    examples: [
+      { command: "vibecheck fix", description: "Plan missions (no changes)" },
+      { command: "vibecheck fix --apply", description: "Apply AI fixes with checkpoints" },
+      { command: "vibecheck fix --autopilot --apply", description: "Loop until SHIP or stuck" },
+      { command: "vibecheck fix --rollback M_xxx", description: "Rollback mission" },
+      { command: "vibecheck fix missions", description: "View grouped fix tasks" },
+      { command: "vibecheck fix checkpoint list", description: "List snapshots" },
+      { command: "vibecheck fix checkpoint restore latest", description: "Restore snapshot" },
+    ],
+    related: ["scan", "ship"],
+  },
+
+  certify: {
+    description: "Full verification chain — ISL + Reality + Chaos + Ship score + badge",
+    longDescription: "The flagship command. Runs the complete proof pipeline: truth → verify → prove → seal → badge. Produces a shareable certification artifact.",
+    tier: "pro",
+    category: "core",
+    runner: () => require("./runners/runProve").runProve,
+    subcommands: [
+      { name: "verify", description: "Run ISL verification only" },
+      { name: "prove", description: "Full proof loop (forge → scan → reality → ship)" },
+      { name: "seal", description: "Generate badge + cryptographic attestation" },
+      { name: "truth", description: "Build/rebuild truthpack artifacts" },
+    ],
+    examples: [
+      { command: "vibecheck certify", description: "Run full certification" },
+      { command: "vibecheck certify --badge", description: "Include badge generation" },
+      { command: "vibecheck certify --reality", description: "Include browser verification" },
+      { command: "vibecheck certify --artifacts", description: "Generate truthpack + evidence" },
+      { command: "vibecheck certify verify", description: "Verification only" },
+      { command: "vibecheck certify seal --format svg", description: "Generate SVG badge" },
+    ],
+    related: ["ship", "reality", "report"],
+  },
+
+  // ══════════════════════════════════════════════════════════════
+  // EVIDENCE & ENFORCEMENT
+  // ══════════════════════════════════════════════════════════════
+
+  report: {
+    description: "Generate reports — HTML, SARIF, JSON, PDF, evidence bundles",
+    longDescription: "Produce shareable artifacts: reports, evidence packs, proof graphs, permission matrices. Multiple output formats.",
+    tier: "free",
+    category: "output",
+    runner: () => require("./runners/runPacks").runPacks,
+    subcommands: [
+      { name: "html", description: "Generate HTML report" },
+      { name: "sarif", description: "Generate SARIF for GitHub" },
+      { name: "bundle", description: "ZIP bundle + manifest + HTML index" },
+      { name: "evidence", description: "Bundle videos, traces, screenshots" },
+      { name: "graph", description: "Proof graph with receipt cross-links" },
+      { name: "permissions", description: "AuthZ matrix, roles, protected routes" },
+    ],
+    examples: [
+      { command: "vibecheck report", description: "Default HTML report" },
+      { command: "vibecheck report sarif", description: "SARIF for GitHub integration" },
+      { command: "vibecheck report bundle", description: "Full evidence bundle" },
+      { command: "vibecheck report --output ./reports", description: "Custom output dir" },
+    ],
+    related: ["certify", "scan", "ship"],
+  },
+
+  reality: {
+    description: "Browser-based runtime verification (Playwright)",
+    longDescription: "Verify your app's actual runtime behavior with Playwright-powered browser testing. Prove what users see is real.",
+    tier: "pro",
+    category: "verify",
+    runner: () => require("./runners/runReality").runReality,
+    subcommands: [
+      { name: "run", description: "Run reality verification (default)" },
+      { name: "replay", description: "Replay a previous reality session" },
+    ],
+    examples: [
+      { command: "vibecheck reality", description: "Auto-detect and test" },
+      { command: "vibecheck reality run --url http://localhost:3000", description: "Test localhost" },
+      { command: "vibecheck reality replay", description: "Replay last session" },
+    ],
+    related: ["certify", "ship"],
+  },
+
+  firewall: {
+    description: "Agent Firewall — intercept, validate, and enforce AI actions",
+    longDescription: "Unified AI enforcement layer. Control what AI agents can do in your codebase. Observe, protect, or lockdown modes. Intent tracking and drift detection.",
+    tier: "pro",
+    category: "enforce",
+    runner: () => require("./runners/runShield").runShield,
+    subcommands: [
+      { name: "on", description: "Enable firewall (default: observe mode)" },
+      { name: "off", description: "Disable firewall" },
+      { name: "mode", description: "Set mode: observe | protect | lockdown" },
+      { name: "status", description: "Show current firewall status" },
+      { name: "rules", description: "Manage firewall rules / forge AI rules" },
+      { name: "intent", description: "Declare/show/clear current intent" },
+      { name: "approve", description: "Review and approve session changes" },
+    ],
+    examples: [
+      { command: "vibecheck firewall on", description: "Enable in observe mode" },
+      { command: "vibecheck firewall mode protect", description: "Switch to protect mode" },
+      { command: "vibecheck firewall status", description: "Show status + stats" },
+      { command: "vibecheck firewall intent set -s \"fix login bug\"", description: "Set intent" },
+      { command: "vibecheck firewall rules", description: "Manage enforcement rules" },
+      { command: "vibecheck firewall approve", description: "Review AI changes" },
+    ],
+    related: ["scan", "certify", "mcp"],
+  },
+
+  // ══════════════════════════════════════════════════════════════
+  // AUTOMATION & CONFIG
+  // ══════════════════════════════════════════════════════════════
+
+  ci: {
+    description: "One-command enterprise CI wiring (GitHub Actions, GitLab, etc.)",
+    longDescription: "Auto-detect your stack and create optimized CI workflows with SARIF output, PR comments, and status checks.",
+    tier: "free",
+    category: "automation",
+    runner: () => require("./runners/runCI").runCI,
+    examples: [
+      { command: "vibecheck ci", description: "Auto-detect and create CI" },
+      { command: "vibecheck ci --dry-run", description: "Preview without creating files" },
+      { command: "vibecheck ci --full", description: "All workflows (scan, ship, e2e, security)" },
+      { command: "vibecheck ci --validate", description: "Validate existing workflows" },
+    ],
+    related: ["scan", "ship", "report"],
+  },
+
+  mcp: {
+    description: "Start MCP server for AI IDEs (Cursor, Windsurf, Claude)",
+    longDescription: "Launch an MCP server for AI IDE integration. 30+ tools for truth verification, intent tracking, and agent management.",
+    tier: "pro",
+    category: "automation",
+    runner: () => require("./runners/runMcp").runMcp,
+    examples: [
+      { command: "vibecheck mcp", description: "Start MCP server" },
+      { command: "vibecheck mcp --port 3099", description: "Custom port" },
+    ],
+    related: ["firewall", "certify"],
+  },
+
+  config: {
+    description: "Manage project configuration, safelist, and settings",
+    longDescription: "Central config management. Includes safelist (finding suppression with justification & expiry), project settings, and context management.",
+    tier: "free",
+    category: "automation",
+    runner: () => require("./runners/runSafelist").runSafelist,
+    subcommands: [
+      { name: "safelist", description: "Manage finding suppressions (add, remove, report, clean)" },
+      { name: "context", description: "Manage AI context / truthpack settings" },
+      { name: "auth", description: "Authentication (login, logout, whoami)" },
+    ],
+    examples: [
+      { command: "vibecheck config", description: "Show current config" },
+      { command: "vibecheck config safelist", description: "List safelist entries" },
+      { command: "vibecheck config safelist add --id MOCK_xyz --reason 'Test data'", description: "Suppress finding" },
+      { command: "vibecheck config auth login", description: "Log in to VibeCheck" },
+      { command: "vibecheck config auth whoami", description: "Show current user" },
+    ],
+    related: ["kickoff", "doctor"],
+  },
+};
+
+// Validate
+assertAllowedOnly(COMMANDS);
+
+// ─────────────────────────────────────────────────────────────
+// SUBCOMMAND ROUTING
+// ─────────────────────────────────────────────────────────────
+// Maps "parent:sub" → runner require path + export name.
+// main() in vibecheck.js consults this before calling the default runner.
+const SUBCOMMAND_MAP = {
+  // scan subcommands
+  "scan:secrets":   { runner: () => require("./runners/runScan").runScan, prependArgs: ["--category", "secrets"] },
+  "scan:vulns":     { runner: () => require("./runners/runScan").runScan, prependArgs: ["--category", "vulnerabilities"] },
+  "scan:routes":    { runner: () => require("./runners/runScan").runScan, prependArgs: ["--category", "routes"] },
+  "scan:env":       { runner: () => require("./runners/runScan").runScan, prependArgs: ["--category", "env"] },
+  "scan:auth":      { runner: () => require("./runners/runScan").runScan, prependArgs: ["--category", "auth"] },
+
+  // ship subcommands
+  "ship:preflight": { runner: () => require("./runners/runLaunch").runLaunch },
+
+  // fix subcommands
+  "fix:missions":   { runner: () => require("./runners/runFix").runFix, prependArgs: ["--list-missions"] },
+  "fix:checkpoint":  { runner: () => require("./runners/runCheckpoint").runCheckpoint },
+  "fix:polish":     { runner: () => require("./runners/runPolish").runPolish },
+
+  // certify subcommands
+  "certify:verify": { runner: () => require("./runners/runProve").runProve, prependArgs: ["--mode", "verify"] },
+  "certify:prove":  { runner: () => require("./runners/runProve").runProve },
+  "certify:seal":   { runner: () => require("./runners/runShip").runSeal },
+  "certify:truth":  { runner: () => require("./runners/runForge").runForge },
+
+  // report subcommands
+  "report:html":    { runner: () => require("./runners/runPacks").runPacks, prependArgs: ["report", "--format", "html"] },
+  "report:sarif":   { runner: () => require("./runners/runPacks").runPacks, prependArgs: ["report", "--format", "sarif"] },
+  "report:bundle":  { runner: () => require("./runners/runPacks").runPacks, prependArgs: ["bundle"] },
+  "report:evidence": { runner: () => require("./runners/runPacks").runPacks, prependArgs: ["evidence"] },
+  "report:graph":   { runner: () => require("./runners/runPacks").runPacks, prependArgs: ["graph"] },
+  "report:permissions": { runner: () => require("./runners/runPacks").runPacks, prependArgs: ["permissions"] },
+
+  // reality subcommands
+  "reality:run":    { runner: () => require("./runners/runReality").runReality },
+  "reality:replay": { runner: () => require("./runners/runReality").runReality, prependArgs: ["--replay"] },
+
+  // firewall subcommands
+  "firewall:on":      { runner: () => require("./runners/runShield").runShield, prependArgs: ["observe"] },
+  "firewall:off":     { runner: () => require("./runners/runShield").runShield, prependArgs: ["off"] },
+  "firewall:mode":    { runner: () => require("./runners/runShield").runShield },
+  "firewall:status":  { runner: () => require("./runners/runShield").runShield, prependArgs: ["status"] },
+  "firewall:rules":   { runner: () => require("./runners/runForge").runForge },
+  "firewall:intent":  { runner: () => require("./runners/runIntent").runIntent },
+  "firewall:approve": { runner: () => require("./runners/runApprove").runApprove },
+
+  // config subcommands
+  "config:safelist": { runner: () => require("./runners/runSafelist").runSafelist },
+  "config:context":  { runner: () => require("./runners/runForge").runForge, prependArgs: ["--context-only"] },
+  "config:auth":     { runner: () => require("./runners/runAuth").runAuth },
+};
+
+// ─────────────────────────────────────────────────────────────
+// HIDDEN COMMANDS — work but don't show in --help
+// ─────────────────────────────────────────────────────────────
+// Power-user / internal pipeline commands that still resolve.
+const HIDDEN_COMMANDS = {
+  checkpoint: { runner: () => require("./runners/runCheckpoint").runCheckpoint },
+  forge:      { runner: () => require("./runners/runForge").runForge },
+  polish:     { runner: () => require("./runners/runPolish").runPolish },
+  auth:       { runner: () => require("./runners/runAuth").runAuth, skipAuth: true },
+  watch:      { runner: () => require("./runners/runWatch").runWatch },
+  labs:       { runner: () => require("./runners/runLabs").runLabs, skipAuth: true },
+  intent:     { runner: () => require("./runners/runIntent").runIntent },
+  approve:    { runner: () => require("./runners/runApprove").runApprove },
+  seal:       { runner: () => require("./runners/runShip").runSeal },
+  prove:      { runner: () => require("./runners/runProve").runProve },
+  safelist:   { runner: () => require("./runners/runSafelist").runSafelist },
+  packs:      { runner: () => require("./runners/runPacks").runPacks },
+  link:       { runner: () => require("./runners/runLink").runLink },
+  audit:      { runner: () => require("./runners/runAudit").runAudit },
+  shield:     { runner: () => require("./runners/runShield").runShield },
+  launch:     { runner: () => require("./runners/runLaunch").runLaunch },
+};
+
+// ─────────────────────────────────────────────────────────────
+// ALIAS MAP — old names → new 12 top-level commands
+// ─────────────────────────────────────────────────────────────
+const ALIAS_MAP = {
+  // → kickoff
+  "init": "kickoff",
+  "setup": "kickoff",
+  "quickstart": "kickoff",
+  "qs": "kickoff",
+  "start": "kickoff",
+  "onboard": "kickoff",
+  "configure": "kickoff",
+
+  // → scan
+  "audit": "scan",
+  "check": "scan",
+  "s": "scan",
+  "validate": "scan",
+
+  // → ship
+  "launch": "ship",
+  "gate": "ship",
+  "ci-gate": "ship",
+  "preflight": "ship",
+  "prelaunch": "ship",
+
+  // → fix
+  "f": "fix",
+  "repair": "fix",
+  "missions": "fix",
+
+  // → certify
+  "verify": "certify",
+  "prove": "certify",
+  "seal": "certify",
+  "badge": "certify",
+  "attest": "certify",
+  "truth": "certify",
+  "truthpack": "certify",
+  "p": "certify",
+
+  // → report
+  "packs": "report",
+  "report": "report",
+  "html": "report",
+  "artifact": "report",
+  "artifacts": "report",
+  "evidence-pack": "report",
+  "bundle": "report",
+  "permissions-pack": "report",
+  "proof-graph": "report",
+
+  // → reality
+  "browser": "reality",
+  "e2e": "reality",
+
+  // → firewall
+  "shield": "firewall",
+  "guard": "firewall",
+  "ai-guard": "firewall",
+  "enforce": "firewall",
+  "intent": "firewall",
+  "approve": "firewall",
+
+  // → config
+  "safelist": "config",
+  "allowlist": "config",
+  "al": "config",
+  "suppress": "config",
+  "context": "config",
+  "ctx": "config",
+  "rules": "config",
+  "ai-rules": "config",
+  "mdc": "config",
+  "brain": "config",
+
+  // → doctor
+  "health": "doctor",
+  "diag": "doctor",
+
+  // Hidden shortcuts
+  "checkpoint": "fix",
+  "cp": "fix",
+  "snap": "fix",
+  "snapshot": "fix",
+  "timemachine": "fix",
+  "rollback": "fix",
+  "w": "scan",
+  "dev": "scan",
+  "prod": "fix",
+  "final": "fix",
+
+  // Auth shortcuts → config
+  "login": "config",
+  "logout": "config",
+  "whoami": "config",
+  "me": "config",
+  "signin": "config",
+  "signout": "config",
+};
+
+// ─────────────────────────────────────────────────────────────
+// DEPRECATION NOTICES for renamed commands
+// ─────────────────────────────────────────────────────────────
+const DEPRECATION_MAP = {
+  "audit":     { target: "scan", message: "'audit' is now 'scan'" },
+  "check":     { target: "scan", message: "'check' is now 'scan'" },
+  "validate":  { target: "scan", message: "'validate' is now 'scan'" },
+  "launch":    { target: "ship preflight", message: "'launch' is now 'ship preflight'" },
+  "init":      { target: "kickoff", message: "'init' is now 'kickoff'" },
+  "setup":     { target: "kickoff", message: "'setup' is now 'kickoff'" },
+  "quickstart": { target: "kickoff", message: "'quickstart' is now 'kickoff'" },
+  "link":      { target: "kickoff", message: "'link' is now part of 'kickoff'" },
+  "shield":    { target: "firewall", message: "'shield' is now 'firewall'" },
+  "guard":     { target: "firewall", message: "'guard' is now 'firewall'" },
+  "prove":     { target: "certify", message: "'prove' is now 'certify'" },
+  "verify":    { target: "certify", message: "'verify' is now 'certify'" },
+  "seal":      { target: "certify seal", message: "'seal' is now 'certify seal'" },
+  "badge":     { target: "certify seal", message: "'badge' is now 'certify seal'" },
+  "truth":     { target: "certify truth", message: "'truth' is now 'certify truth'" },
+  "truthpack": { target: "certify truth", message: "'truthpack' is now 'certify truth'" },
+  "packs":     { target: "report", message: "'packs' is now 'report'" },
+  "safelist":  { target: "config safelist", message: "'safelist' is now 'config safelist'" },
+  "allowlist": { target: "config safelist", message: "'allowlist' is now 'config safelist'" },
+  "context":   { target: "config context", message: "'context' is now 'config context'" },
+  "ctx":       { target: "config context", message: "'ctx' is now 'config context'" },
+  "forge":     { target: "firewall rules", message: "'forge' is now 'firewall rules' (or still works directly)" },
+  "intent":    { target: "firewall intent", message: "'intent' is now 'firewall intent'" },
+  "approve":   { target: "firewall approve", message: "'approve' is now 'firewall approve'" },
+};
+
+function isDeprecated(cmd) {
+  return cmd in DEPRECATION_MAP;
+}
+
+function getDeprecationTarget(cmd) {
+  const dep = DEPRECATION_MAP[cmd];
+  return dep ? dep.target : null;
+}
+
+function getDeprecationMessage(cmd) {
+  const dep = DEPRECATION_MAP[cmd];
+  return dep ? dep.message : null;
+}
+
+// All command names (top-level + aliases + hidden)
+const ALL_COMMANDS = new Set([
+  ...Object.keys(COMMANDS),
+  ...Object.keys(ALIAS_MAP),
+  ...Object.keys(HIDDEN_COMMANDS),
+]);
+
+// ─────────────────────────────────────────────────────────────
+// TIER HELPERS
+// ─────────────────────────────────────────────────────────────
+function isPro(tier) {
+  return tier === "pro";
+}
+
+function requiresPro(commandName) {
+  const cmd = COMMANDS[commandName];
+  return cmd && cmd.tier === "pro";
+}
+
+function getFreeCommands() {
+  return Object.entries(COMMANDS)
+    .filter(([, cmd]) => cmd.tier === "free")
+    .map(([name]) => name);
+}
+
+function getProCommands() {
+  return Object.entries(COMMANDS)
+    .filter(([, cmd]) => cmd.tier === "pro")
+    .map(([name]) => name);
+}
+
+// ─────────────────────────────────────────────────────────────
+// GETTERS
+// ─────────────────────────────────────────────────────────────
+
+function getRunner(cmd, opts = {}) {
+  // Check top-level commands first
+  let def = COMMANDS[cmd];
+  
+  // Then check hidden commands
+  if (!def) {
+    def = HIDDEN_COMMANDS[cmd];
+  }
+  
+  if (!def) {
+    return null;
+  }
+  
+  if (!def.runner) {
+    return null;
+  }
+  
+  try {
+    return def.runner();
+  } catch (e) {
+    if (opts.red && opts.reset) {
+      console.error(`${opts.red}× Failed to load runner for ${cmd}: ${e.message}${opts.reset}`);
+    }
+    return null;
+  }
+}
+
+function getSubcommandRunner(parent, sub) {
+  const key = `${parent}:${sub}`;
+  const def = SUBCOMMAND_MAP[key];
+  if (!def) return null;
+  try {
+    return { runner: def.runner(), prependArgs: def.prependArgs || [] };
+  } catch (e) {
+    return null;
+  }
+}
+
+function getCommand(name) {
+  return COMMANDS[name] || null;
+}
+
+function isValidCommand(name) {
+  return name in COMMANDS || name in HIDDEN_COMMANDS;
+}
+
+function listCommands() {
+  return Object.keys(COMMANDS);
+}
+
+// ─────────────────────────────────────────────────────────────
+// EXPORTS
+// ─────────────────────────────────────────────────────────────
+module.exports = {
+  // Core data
+  COMMANDS,
+  ALLOWED_COMMANDS,
+  ALIAS_MAP,
+  ALL_COMMANDS,
+  SUBCOMMAND_MAP,
+  HIDDEN_COMMANDS,
+  DEPRECATION_MAP,
+  
+  // Tier helpers
+  isPro,
+  requiresPro,
+  getFreeCommands,
+  getProCommands,
+  
+  // Getters
+  getRunner,
+  getSubcommandRunner,
+  getCommand,
+  isValidCommand,
+  listCommands,
+  
+  // Deprecation
+  isDeprecated,
+  getDeprecationTarget,
+  getDeprecationMessage,
+  
+  getCommandsByTier: (tier) => 
+    Object.entries(COMMANDS)
+      .filter(([, cmd]) => cmd.tier === tier)
+      .map(([name, cmd]) => ({ name, ...cmd })),
+  
+  getCommandsByCategory: (category) =>
+    Object.entries(COMMANDS)
+      .filter(([, cmd]) => cmd.category === category)
+      .map(([name, cmd]) => ({ name, ...cmd })),
+};