vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/CLI_REFACTOR_SUMMARY.md

@@ -0,0 +1,229 @@
+# CLI Refactor Summary - The 14-Command Vibecheck CLI
+
+**Date:** $(date)  
+**Purpose:** Consolidate CLI into 14 core commands with backward-compatible aliases
+
+---
+
+## The 14 Core Commands
+
+### SETUP (2 commands)
+| # | Command | Description | Tier |
+|---|---------|-------------|------|
+| 1 | `init` | One-time setup (config + contracts + scripts) | FREE |
+| 2 | `doctor` | Environment + dependency + config health check | FREE |
+
+### AI TRUTH LANE (4 commands)
+| # | Command | Description | Tier |
+|---|---------|-------------|------|
+| 3 | `ctx` | Truthpack generation - core truth engine | FREE |
+| 4 | `context` | Generate IDE rules (.cursorrules, MDC, Windsurf, Copilot) | FREE |
+| 5 | `guard` | AI guardrails - prompt firewall & hallucination checking | FREE |
+| 6 | `contracts` | CI gate for contract drift / invariants | FREE |
+
+### PROOF LOOP (5 commands)
+| # | Command | Description | Tier |
+|---|---------|-------------|------|
+| 7 | `ship` | Verdict engine - SHIP / WARN / BLOCK | FREE |
+| 8 | `runtime` | Browser-based runtime verification | FREE |
+| 9 | `fix` | AI-powered auto-fix | FREE |
+| 10 | `prove` | Full proof loop - ctx → runtime → ship → fix | PRO |
+| 11 | `security` | AuthZ matrix & IDOR detection | PRO |
+
+### OUTPUT & AUTOMATION (3 commands)
+| # | Command | Description | Tier |
+|---|---------|-------------|------|
+| 12 | `report` | Generate HTML/MD/SARIF reports | FREE |
+| 13 | `export` | Generate collaboration outputs | FREE |
+| 14 | `mcp` | Start MCP server for AI IDEs | STARTER |
+
+---
+
+## AI Truth Lane - Deep Dive
+
+### `vibecheck ctx` - Truthpack Generation
+The core truth engine that builds the "ground truth" of your project:
+- Project metadata (frameworks, workspaces, entrypoints)
+- Server routes and client route references
+- Environment variables and auth patterns
+- Billing/payment integrations
+- External service integrations
+
+**Subcommands:**
+- `ctx build` - Build/refresh truthpack
+- `ctx diff` - Show drift from contracts
+- `ctx sync` - Update contracts from truthpack
+- `ctx search` - Semantic search in context
+
+### `vibecheck context` - IDE Rules & MDC Generation
+Generates context files for AI coding assistants:
+- `.cursorrules` - Cursor IDE rules
+- `.cursor/rules/*.mdc` - Cursor MDC files
+- `.windsurf/rules/*.md` - Windsurf rules
+- `.github/copilot-instructions.md` - GitHub Copilot
+- `.claude/` and `.codex/` instructions
+- `.vibecheck/context.json` - Universal context
+
+Also supports:
+- Semantic code search
+- Secret/vulnerability scanning
+- AI task decomposition
+- Multi-repo federation
+- AI memory storage
+
+### `vibecheck guard` - AI Guardrails
+The prompt firewall and hallucination prevention system:
+- Validates AI claims against truthpack
+- Breaks prompts into tasks and verifies them
+- Checks for hallucination risks
+- Version-control aware fixes
+- Can generate diffs and apply fixes
+
+### `vibecheck contracts` - Contract Drift Detection
+CI gate for ensuring code doesn't drift from contracts:
+- Validates routes against routes.json
+- Validates env vars against env.json
+- Validates auth patterns against auth.json
+- Returns SHIP/WARN/BLOCK verdict
+
+---
+
+## Subcommand Reference
+
+### `runtime` Subcommands
+- `runtime crawl --url <url>` - UI verification (replaces `reality`)
+- `runtime agent --url <url>` - AI autonomous testing (replaces `ai-test`)
+- `runtime record --url <url>` - Record session (replaces `replay record`)
+- `runtime play <capsule>` - Replay session (replaces `replay play`)
+
+### `export` Subcommands
+- `export pr` - Generate PR comment (replaces `pr`)
+- `export badge` - Generate ship badge (replaces `badge`)
+- `export bundle` - Generate share pack (replaces `share`)
+
+### `security` Subcommands
+- `security model` - Extract auth model (replaces `permissions --learn`)
+- `security matrix` - Build AuthZ matrix (replaces `permissions --matrix`)
+- `security idor` - Detect IDOR candidates (replaces `permissions --idor`)
+- `security prove --url <url>` - Runtime verification
+
+---
+
+## Backward Compatibility Aliases
+
+All old commands still work:
+
+| Old Command | New Command |
+|-------------|-------------|
+| `install` | `init --quick` |
+| `scan` | `ship --mode scan` |
+| `gate` | `ship --ci` |
+| `reality` | `runtime crawl` |
+| `ai-test` | `runtime agent` |
+| `replay record` | `runtime record` |
+| `replay play` | `runtime play` |
+| `pr` | `export pr` |
+| `badge` | `export badge` |
+| `share` | `export bundle` |
+| `permissions` | `security model` |
+| `mdc` | `context` (alias) |
+
+---
+
+## The "What Do I Run?" Cheat Sheet
+
+### Daily Development
+```bash
+vibecheck ship              # Quick verdict
+vibecheck watch             # Continuous mode
+```
+
+### New Project Setup
+```bash
+vibecheck init              # Full wizard
+vibecheck init --quick      # Fast setup
+```
+
+### Before Pushing
+```bash
+vibecheck ship              # Static verdict
+vibecheck ship --with runtime  # Include runtime findings
+```
+
+### Before Deploying
+```bash
+vibecheck prove             # Full proof loop
+```
+
+### In CI/CD
+```bash
+vibecheck ship --ci         # CI verdict
+vibecheck contracts --strict  # Contract drift gate
+```
+
+### AI Context Generation
+```bash
+vibecheck ctx               # Build truthpack
+vibecheck context           # Generate IDE rules & MDC
+```
+
+### AI Guardrails
+```bash
+vibecheck guard             # Validate AI output
+vibecheck verify            # Verify AI-generated code
+```
+
+---
+
+## Key Distinctions
+
+### `guard` vs `contracts`
+- **`guard`** = AI guardrails (prompt firewall, hallucination checking)
+- **`contracts`** = Contract drift (CI gate for code vs contracts)
+
+### `ctx` vs `context`
+- **`ctx`** = Core truth engine (builds truthpack)
+- **`context`** = IDE rules & MDC generation (consumes truthpack)
+
+### `ship` vs `prove`
+- **`ship`** = Single verdict (static or with runtime)
+- **`prove`** = Full loop (ctx → runtime → ship → fix → verify)
+
+---
+
+## Additional Commands (DX Helpers)
+
+These commands are kept for convenience but not part of the core 14:
+
+| Command | Description | Tier |
+|---------|-------------|------|
+| `status` | Project health dashboard | FREE |
+| `watch` | Continuous mode - re-runs on changes | FREE |
+| `launch` | Pre-launch checklist wizard | STARTER |
+| `preflight` | Deployment validation checks | FREE |
+| `verify` | Verify AI-generated code output | FREE |
+| `graph` | Reality proof graph visualization | PRO |
+
+### Account Commands
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate with API key |
+| `logout` | Remove stored credentials |
+| `whoami` | Show current user and plan |
+
+---
+
+## Summary
+
+The 14-command structure provides:
+
+1. **Clear Setup** - `init`, `doctor`
+2. **AI Truth Lane** - `ctx`, `context`, `guard`, `contracts`
+3. **Proof Loop** - `ship`, `runtime`, `fix`, `prove`, `security`
+4. **Output & Automation** - `report`, `export`, `mcp`
+
+All features preserved, no confusion:
+- AI guardrails live in `guard`
+- Contract drift lives in `contracts`
+- MDC/IDE rules live in `context`
+- Truthpack generation lives in `ctx`

package/bin/runners/ENHANCEMENT_GUIDE.md

@@ -0,0 +1,121 @@
+# Command Enhancement Guide
+
+This guide shows how to apply the enhancements from `vibecheck.js` to all command runners.
+
+## 1. Add Global Flags Support
+
+### Import the utilities:
+```javascript
+const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+```
+
+### Update parseArgs function:
+```javascript
+function parseArgs(args) {
+  // Parse global flags first
+  const { flags: globalFlags, cleanArgs } = parseGlobalFlags(args);
+  
+  const opts = {
+    // ... existing options
+    path: globalFlags.path || process.cwd(),
+    json: globalFlags.json || false,
+    verbose: globalFlags.verbose || false,
+    help: globalFlags.help || false,
+    noBanner: globalFlags.noBanner || false,
+    ci: globalFlags.ci || false,
+    quiet: globalFlags.quiet || false,
+  };
+  
+  // Parse command-specific args from cleanArgs
+  for (let i = 0; i < cleanArgs.length; i++) {
+    const a = cleanArgs[i];
+    // ... command-specific parsing
+  }
+  
+  return opts;
+}
+```
+
+## 2. Update Banner Printing
+
+### Update printHelp:
+```javascript
+function printHelp(showBanner = true) {
+  if (showBanner && shouldShowBanner({})) {
+    console.log(BANNER);
+  }
+  // ... rest of help
+}
+```
+
+### Update banner printing in main function:
+```javascript
+async function runCommand(args) {
+  const opts = parseArgs(args);
+  
+  if (opts.help) {
+    printHelp(shouldShowBanner(opts));
+    return 0;
+  }
+  
+  // Print banner (respects --no-banner, VIBECHECK_NO_BANNER, --ci, --quiet, --json)
+  if (shouldShowBanner(opts)) {
+    printBanner();
+  }
+  
+  // ... rest of command
+}
+```
+
+## 3. Add Aliases to Help Text
+
+Update help text to show aliases:
+```javascript
+function printHelp(showBanner = true) {
+  // ...
+  console.log(`
+  ${ansi.bold}Usage:${ansi.reset} vibecheck command ${ansi.dim}(alias1, alias2)${ansi.reset} [options]
+  
+  ${ansi.bold}Aliases:${ansi.reset} ${ansi.dim}alias1, alias2${ansi.reset}
+  `);
+}
+```
+
+## 4. Lazy Loading (Optional)
+
+For commands that load heavy modules, use lazy loading:
+```javascript
+const { lazy } = require("./lib/global-flags");
+
+const getHeavyModule = lazy("heavy-module", () => require("./lib/heavy-module"));
+
+// Use later:
+const heavyModule = getHeavyModule();
+```
+
+## Commands Updated
+
+✅ `runScan.js` - Full support for --no-banner, global flags, aliases in help
+✅ `runShip.js` - Full support for --no-banner, global flags, aliases in help  
+✅ `runReport.js` - Full support for --no-banner, global flags
+✅ `runInit.js` - Already enhanced with all features
+
+## Commands Pending
+
+- `runStatus.js` - No banner, but should support global flags
+- `runFix.js` - Needs banner support
+- `runProve.js` - Needs banner support
+- `runContext.js` - Needs banner support
+- `runCtx.js` - Needs banner support
+- All other commands - Apply same pattern
+
+## Testing Checklist
+
+For each command:
+- [ ] `command --no-banner` suppresses banner
+- [ ] `VIBECHECK_NO_BANNER=true command` suppresses banner
+- [ ] `command --ci` suppresses banner
+- [ ] `command --quiet` suppresses banner
+- [ ] `command --json` suppresses banner
+- [ ] `command --help` shows aliases (if any)
+- [ ] Global flags (--path, --output, --verbose) work correctly

package/bin/runners/REPORT_AUDIT.md

@@ -0,0 +1,64 @@
+# Report Generation Audit
+
+## Commands That Generate Reports Automatically
+
+### ✅ Updated Commands
+
+1. **`vibecheck ship`**
+   - **Location**: `bin/runners/runShip.js`
+   - **Report**: `.vibecheck/report.html`
+   - **Type**: Technical report (detailed)
+   - **Generator**: `lib/html-report.js` → `generateHTMLReport()`
+   - **Status**: ✅ Updated to use better HTML report generator
+
+2. **`vibecheck report`**
+   - **Location**: `bin/runners/runReport.js`
+   - **Report**: `.vibecheck/report.html` (or custom path)
+   - **Types**:
+     - `--type=executive`: Client-friendly executive report
+     - `--type=technical` (default): Detailed technical report
+     - `--type=compliance`: Compliance report (PRO tier)
+   - **Generator**: 
+     - Executive: `lib/report-templates.js` → `generateEnhancedExecutiveReport()`
+     - Technical: `lib/html-report.js` → `generateHTMLReport()`
+   - **Status**: ✅ Updated - executive uses client-friendly template, technical uses detailed generator
+
+3. **`writeArtifacts()` utility**
+   - **Location**: `bin/runners/utils.js`
+   - **Report**: `.vibecheck/report.html`
+   - **Type**: Technical report (detailed)
+   - **Generator**: `lib/html-report.js` → `generateHTMLReport()`
+   - **Used by**: `runShip.js` (but skipped since ship generates its own)
+   - **Status**: ✅ Updated to use better HTML report generator
+
+### ✅ Specialized Reports (Keep As-Is)
+
+4. **`vibecheck reality`**
+   - **Location**: `bin/runners/reality/report.js`
+   - **Report**: `.vibecheck/reality/reality-report.html`
+   - **Type**: Reality mode specific report (runtime testing results)
+   - **Generator**: `reality/report.js` → `writeHtmlReport()`
+   - **Status**: ✅ Appropriate - specialized for reality mode, different format needed
+
+5. **`vibecheck prove`**
+   - **Location**: `bin/runners/runProve.js`
+   - **Report**: `.vibecheck/prove_report.json` (JSON only, no HTML)
+   - **Status**: ✅ Appropriate - JSON format for orchestration results
+
+### 📋 Summary
+
+**Commands that generate `report.html` automatically:**
+- ✅ `vibecheck ship` → Uses technical report generator
+- ✅ `vibecheck report` → Uses executive (client-friendly) or technical (default)
+- ✅ `writeArtifacts()` → Uses technical report generator (fallback)
+
+**Report Types:**
+- **Executive Report** (`--type=executive`): Client-friendly, simplified, stakeholder-focused
+- **Technical Report** (default): Detailed, developer-focused, includes file paths and code references
+- **Reality Report**: Specialized runtime testing report (different format)
+
+**Consistency:**
+- All general-purpose reports now use the unified HTML report generator
+- Executive reports use client-friendly templates
+- Technical reports use detailed generator
+- Specialized reports (reality) use their own formats (appropriate)