vibecheck-ai 1.1.1 → 1.2.0

package/README.md

@@ -1,23 +1,28 @@
 <p align="center">
-  <img src="https://vibecheckai.dev/logo.png" alt="VibeCheck Logo" width="120" />
+  <img src="https://vibecheckai.dev/logo.png" alt="VibeCheck Logo" width="100" />
 </p>
 
-<h1 align="center">VibeCheck CLI</h1>
+<h1 align="center">VibeCheck</h1>
+
+<h3 align="center">
+  <strong>Stop AI Hallucinations. Ship Real Features.</strong>
+</h3>
 
 <p align="center">
-  <strong>Hallucination prevention for AI-assisted development</strong>
+  The security layer for AI-assisted development.<br/>
+  Catches fake features, phantom APIs, and silent failures before they hit production.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/vibecheck-ai"><img src="https://img.shields.io/npm/v/vibecheck-ai.svg?style=flat-square&color=blue" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/vibecheck-ai"><img src="https://img.shields.io/npm/dm/vibecheck-ai.svg?style=flat-square&color=green" alt="npm downloads" /></a>
+  <a href="https://www.npmjs.com/package/vibecheck-ai"><img src="https://img.shields.io/npm/v/vibecheck-ai.svg?style=flat-square&color=E040FB" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/vibecheck-ai"><img src="https://img.shields.io/npm/dm/vibecheck-ai.svg?style=flat-square&color=00E676" alt="npm downloads" /></a>
+  <a href="https://github.com/vibecheckai/vibecheck"><img src="https://img.shields.io/github/stars/vibecheckai/vibecheck?style=flat-square&color=FFD54F" alt="github stars" /></a>
   <a href="https://github.com/vibecheckai/vibecheck/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
-  <a href="https://vibecheckai.dev/discord"><img src="https://img.shields.io/discord/1234567890?style=flat-square&color=5865F2&label=discord" alt="discord" /></a>
 </p>
 
 <p align="center">
   <a href="https://vibecheckai.dev">Website</a> •
-  <a href="https://vibecheckai.dev/docs">Documentation</a> •
+  <a href="https://vibecheckai.dev/docs">Docs</a> •
   <a href="https://vibecheckai.dev/discord">Discord</a> •
   <a href="https://twitter.com/vibecheckai">Twitter</a>
 </p>
@@ -26,249 +31,284 @@
 
 ## The Problem
 
-AI coding assistants are incredibly powerful, but they hallucinate. They invent APIs that don't exist, reference outdated documentation, and make assumptions about your codebase that aren't true.
+AI coding assistants are incredible. They're also **professional liars**.
 
-**VibeCheck solves this.** It creates a "truth layer" for your project—a source of verified facts that AI assistants can reference to stay grounded in reality.
+```typescript
+// Cursor/Copilot generated this. TypeScript happy. Linter passes. Code review: LGTM.
 
-## How It Works
+async function getUser(id: string): Promise<User> {
+  return await fetch(`/api/v2/users/${id}`);  // ❌ This endpoint doesn't exist
+}
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Your Codebase                            │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                 VibeCheck Truthpack                         │
-│  ┌───────────┐  ┌───────────┐  ┌───────────┐               │
-│  │  Routes   │  │   Env     │  │   Auth    │  ...          │
-│  │  Schema   │  │  Schema   │  │  Config   │               │
-│  └───────────┘  └───────────┘  └───────────┘               │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│              AI Assistant (Cursor, Copilot, etc.)           │
-│                                                             │
-│  "Based on the truthpack, I can see your API uses          │
-│   JWT auth with these exact routes..."                      │
-└─────────────────────────────────────────────────────────────┘
+async function chargeCustomer(order: Order) {
+  try {
+    await stripe.charges.create(order);  // ❌ Deprecated API since Stripe v3
+  } catch (e) {
+    // TODO: handle this later  // ❌ Payment failures silently swallowed
+  }
+}
+
+function getDashboardStats(): DashboardStats {
+  return { users: 1247, revenue: 84350 };  // ❌ Hardcoded. This is fake data.
+}
 ```
 
-## Quick Start
+This code **compiles**. It **passes CI**. It gets **deployed**.
 
-### Installation
+Then your customers discover the payments don't work.
 
-```bash
-# Install globally
-npm install -g vibecheck-ai
+---
 
-# Or use with npx
-npx vibecheck-ai
-```
+## The Solution
 
-### Initialize Your Project
+**VibeCheck catches what linters can't.**
 
 ```bash
-# Navigate to your project
-cd your-project
+$ vibecheck ship
 
-# Initialize VibeCheck
-vibecheck init
-```
+🔍 Running pre-ship checks...
 
-This creates a `.vibecheck/` directory with your project's truthpack—a verified snapshot of your codebase's reality.
+⛔ FAKE FEATURE: src/api/users.ts:4
+   Endpoint /api/v2/users/{id} does not exist in your routes
+   └─ AI generated a plausible URL that will 404 at runtime
 
-### Validate AI Suggestions
+⚠️  DEPRECATED API: src/payments.ts:8
+   stripe.charges.create() was deprecated in Stripe SDK v3
+   └─ Use stripe.paymentIntents.create() instead
 
-```bash
-# Check for hallucinations in staged changes
-vibecheck check
+⛔ SILENT FAILURE: src/payments.ts:11
+   Empty catch block in payment flow
+   └─ chargeCustomer() errors will be swallowed silently
 
-# Validate a specific file
-vibecheck validate src/api/routes.ts
+⚠️  MOCK DATA: src/dashboard.ts:16
+   getDashboardStats() returns hardcoded values
+   └─ This will never reflect actual database data
 
-# Run full analysis
-vibecheck analyze
+Ship Status: BLOCKED (4 issues found)
 ```
 
-## Commands
+**Before it ships. Not after the Slack message at 3am.**
 
-| Command | Description |
-|---------|-------------|
-| `vibecheck init` | Initialize VibeCheck in your project |
-| `vibecheck scan` | Scan codebase and generate truthpack |
-| `vibecheck check` | Run hallucination and drift detection |
-| `vibecheck validate [file]` | Validate files against truthpack |
-| `vibecheck ship` | Pre-deployment security checks with auto-fix |
-| `vibecheck fix` | Apply auto-fixes for detected issues |
-| `vibecheck report` | Generate enterprise-grade HTML/PDF reports |
-| `vibecheck doctor` | Validate system dependencies and configuration |
-| `vibecheck config` | View or edit configuration |
-| `vibecheck watch` | Watch for changes and validate continuously |
-| `vibecheck menu` | Interactive menu for all features |
-
-### Ship Command (Pre-deployment Checks)
+---
 
-The `ship` command runs comprehensive security analysis before deployment:
+## Quick Start
 
 ```bash
-# Run all pre-deployment checks
-vibecheck ship
+# Install globally
+npm install -g vibecheck-ai
 
-# Auto-fix issues before shipping  
-vibecheck ship --fix
+# Or run with npx (no install)
+npx vibecheck-ai
 
-# Force ship despite warnings
-vibecheck ship --force
+# Initialize in your project
+cd your-project
+vibecheck init
+
+# Run pre-ship checks
+vibecheck ship
 ```
 
-**Checks include:**
-- **Ultimate Scanner** — 80+ security patterns (credentials, SQLi, XSS, SSRF, etc.)
-- **Truthpack validation** — Routes, env vars, auth patterns
-- **Drift detection** — Changes from verified baseline
-- **Secrets scanning** — API keys, tokens, passwords
-- **Code quality** — Dead code, TODO comments, debug statements
+That's it. Issues appear immediately.
 
-## Features
+---
 
-### 🎯 Truthpack Generation
+## Features
 
-Automatically extract and verify facts about your codebase:
+### 🚀 Ship Command — Pre-Deployment Security Gate
 
-- **Routes** — API endpoints with methods, paths, and handlers
-- **Environment** — Required env vars with types and defaults
-- **Authentication** — Auth strategies and protected routes
-- **Database** — Schema definitions and relationships
-- **Dependencies** — Package versions and compatibility
+Run 10+ checks before every deployment:
 
-### 🔍 Hallucination Detection
+```bash
+vibecheck ship              # Full pre-deployment analysis
+vibecheck ship --fix        # Auto-fix issues automatically
+vibecheck ship --force      # Ship anyway (not recommended)
+```
 
-Catch AI mistakes before they become bugs:
+**Checks include:**
+- Truthpack validation (routes, env vars, auth)
+- Hallucination detection (fake APIs, deprecated methods)
+- Secret scanning (API keys, tokens, credentials)
+- Silent failure detection (empty catches, swallowed errors)
+- Mock data finder (hardcoded values in production code)
+- Drift detection (changes from verified baseline)
+- 80+ security patterns
 
-- Invented API endpoints
-- Non-existent environment variables
-- Outdated package versions
-- Incorrect type assumptions
-- Missing error handling
+---
 
-### 🛡️ Ultimate Security Scanner
+### 🎯 Reality Mode — Actually Run Your Code
 
-Industry-leading security detection with **80+ patterns**:
+Static analysis can't catch everything. Reality Mode uses Playwright to **actually execute your code**:
 
-**Credentials:**
-- Stripe, AWS, GitHub, Google, Azure, npm tokens
-- OpenAI, Anthropic, SendGrid, Twilio API keys
-- Private keys, JWT secrets, database passwords
+```bash
+vibecheck reality run       # Run scenarios and generate proof
+vibecheck reality report    # View detailed proof report
+```
 
-**Security Vulnerabilities:**
-- SQL Injection, XSS, Command Injection
-- SSRF, Path Traversal, Open Redirect
-- CORS misconfig, Missing CSP, Clickjacking
-- Timing attacks, Insecure cookies
+- Spins up real test environments
+- Makes actual API calls
+- Validates responses match expectations
+- Catches lies that static analysis misses
+- Generates cryptographic proof bundles
 
-**AI Hallucinations:**
-- Fake npm packages
-- Deprecated APIs (React 18, moment.js)
-- Placeholder URLs (example.com, localhost)
-- Made-up methods
+---
 
-**Framework-Specific:**
-- Next.js server actions, API route auth
-- React hooks issues, setState in render
-- Express without Helmet, trust-proxy issues
+### 🔥 Roast Mode — Brutally Honest Code Review
 
-### 🛡️ Code Firewall
+When you need tough love:
 
-Protect critical files from AI modifications:
+```bash
+vibecheck roast
+```
 
-```typescript
-// vibecheck.config.mjs
-export default {
-  firewall: {
-    locked: ['src/core/**', '.env*'],
-    warn: ['package.json', 'tsconfig.json'],
-  }
-};
 ```
+🔥 ROAST RESULTS 🔥
+
+TODO from the Jurassic period spotted. The dinosaurs are extinct,
+but your technical debt lives on.
 
-### 📊 Beautiful Reports
+console.log('here') — Ah yes, the debugging strategy of champions
+and interns.
 
-Get clear, actionable feedback:
+'any' type? Congrats, you've invented JavaScript with extra steps.
 
+Your function has 847 lines. That's not a function, that's a novel.
 ```
-┌─────────────────────────────────────────────────────────┐
-│  VibeCheck Analysis Complete                            │
-├─────────────────────────────────────────────────────────┤
-│  ✓ 47 files analyzed                                    │
-│  ✓ 12 routes validated                                  │
-│  ⚠ 2 potential hallucinations detected                  │
-│  ✗ 1 critical issue found                               │
-└─────────────────────────────────────────────────────────┘
-
-Critical: src/api/payments.ts:42
-  → References 'stripe.customers.delete()' but Stripe SDK
-    version 14.x uses 'stripe.customers.del()'
+
+Pass the ship check first, and you unlock an easter egg. 🏆
+
+---
+
+### 🛡️ Truthpack — Your Project's Source of Truth
+
+VibeCheck extracts verified facts about your codebase:
+
+```bash
+vibecheck scan              # Generate truthpack
+vibecheck validate file.ts  # Validate against truthpack
 ```
 
-## Configuration
+**What gets extracted:**
+- **Routes** — API endpoints with methods, paths, handlers
+- **Environment** — Required env vars with types and defaults
+- **Auth** — Authentication strategies and protected routes
+- **Database** — Schema definitions and relationships
+- **Dependencies** — Package versions and compatibility
 
-Create `vibecheck.config.mjs` in your project root:
+AI assistants reference this to stay grounded in reality.
+
+---
+
+### 🔒 Code Firewall — Lock Critical Files
+
+Protect sensitive files from AI modifications:
 
 ```javascript
-/** @type {import('vibecheck-ai').VibeCheckConfig} */
+// vibecheck.config.mjs
 export default {
-  // Project info
-  project: {
-    name: 'my-app',
-    type: 'nextjs',
-  },
-  
-  // What to analyze
-  include: ['src/**/*.ts', 'src/**/*.tsx'],
-  exclude: ['**/*.test.ts', '**/node_modules/**'],
-  
-  // Hallucination detection sensitivity
-  analysis: {
-    strictness: 'standard', // 'relaxed' | 'standard' | 'paranoid'
-    checkDependencies: true,
-    checkEnvVars: true,
-    checkRoutes: true,
-  },
-  
-  // File protection
   firewall: {
-    locked: ['.env*', 'src/core/**'],
-    warn: ['package.json'],
-  },
+    locked: ['.env*', 'src/core/**', 'credentials.json'],
+    warn: ['package.json', 'tsconfig.json'],
+  }
 };
 ```
 
-## IDE Integration
+---
 
-### Cursor
+### 📊 Enterprise Reports
 
-VibeCheck works seamlessly with Cursor. Install the MCP server for real-time validation:
+Generate beautiful HTML/PDF reports for compliance:
 
 ```bash
-npm install -g @vibecheckai/mcp-server
+vibecheck report            # Generate HTML report
+vibecheck report --pdf      # Generate PDF report
+vibecheck report --json     # Machine-readable output
 ```
 
-Add to your Cursor settings:
+---
 
-```json
-{
-  "mcpServers": {
-    "vibecheck": {
-      "command": "vibecheck-mcp"
-    }
-  }
-}
-```
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `vibecheck init` | Initialize VibeCheck in your project |
+| `vibecheck scan` | Scan codebase and generate truthpack |
+| `vibecheck ship` | **Pre-deployment security checks** |
+| `vibecheck check` | Run hallucination detection |
+| `vibecheck validate [file]` | Validate files against truthpack |
+| `vibecheck reality run` | Run Reality Mode with proof generation |
+| `vibecheck roast` | Get brutally honest code feedback |
+| `vibecheck fix` | Apply auto-fixes for detected issues |
+| `vibecheck report` | Generate enterprise-grade reports |
+| `vibecheck watch` | Watch for changes continuously |
+| `vibecheck doctor` | Validate system dependencies |
+| `vibecheck config` | View or edit configuration |
 
-### VS Code
+---
 
-Install the [VibeCheck extension](https://marketplace.visualstudio.com/items?itemName=vibecheckai.vibecheck) for inline validation and truthpack browsing.
+## Security Scanner
+
+Industry-leading detection with **80+ patterns**:
+
+<details>
+<summary><strong>🔑 Credentials (click to expand)</strong></summary>
+
+- AWS Access Keys & Secrets
+- GitHub Tokens (PAT, OAuth, App)
+- Stripe API Keys (Live & Test)
+- OpenAI & Anthropic API Keys
+- Google Cloud Service Accounts
+- Azure Connection Strings
+- npm Tokens & Registry Auth
+- Database Passwords & URIs
+- JWT Secrets & Private Keys
+- SendGrid, Twilio, Mailgun Keys
+
+</details>
+
+<details>
+<summary><strong>🛡️ Security Vulnerabilities</strong></summary>
+
+- SQL Injection patterns
+- Cross-Site Scripting (XSS)
+- Command Injection
+- Server-Side Request Forgery (SSRF)
+- Path Traversal attacks
+- Open Redirect vulnerabilities
+- CORS misconfigurations
+- Missing Content Security Policy
+- Insecure cookie settings
+- Timing attack vectors
+
+</details>
+
+<details>
+<summary><strong>🤖 AI Hallucinations</strong></summary>
+
+- Non-existent npm packages
+- Deprecated React 18 patterns
+- Phantom API endpoints
+- Fake environment variables
+- Made-up method names
+- Placeholder URLs (localhost, example.com)
+- Outdated library versions
+- Incorrect TypeScript types
+
+</details>
+
+<details>
+<summary><strong>⚛️ Framework-Specific</strong></summary>
+
+- Next.js server action issues
+- React hooks violations
+- Express without Helmet
+- Missing auth middleware
+- Unsafe trust-proxy settings
+- setState in render patterns
+- Missing error boundaries
+
+</details>
+
+---
 
 ## CI/CD Integration
 
@@ -287,13 +327,14 @@ jobs:
         with:
           node-version: '20'
       - run: npm install -g vibecheck-ai
-      - run: vibecheck check --ci
+      - run: vibecheck ship --ci
+        env:
+          VIBECHECK_API_KEY: ${{ secrets.VIBECHECK_API_KEY }}
 ```
 
 ### Pre-commit Hook
 
-```bash
-# Add to your package.json
+```json
 {
   "husky": {
     "hooks": {
@@ -303,35 +344,155 @@ jobs:
 }
 ```
 
+### GitLab CI
+
+```yaml
+vibecheck:
+  stage: test
+  script:
+    - npm install -g vibecheck-ai
+    - vibecheck ship --ci
+```
+
+---
+
+## IDE Integration
+
+### Cursor (MCP Server)
+
+```bash
+npm install -g @vibecheckai/mcp-server
+```
+
+```json
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "vibecheck": {
+      "command": "vibecheck-mcp"
+    }
+  }
+}
+```
+
+### VS Code Extension
+
+Install the [VibeCheck Extension](https://marketplace.visualstudio.com/items?itemName=vibecheckai.vibecheck) for:
+- Inline hallucination detection
+- Truthpack browser
+- Real-time firewall
+- One-click auto-fix
+
+---
+
+## Configuration
+
+Create `vibecheck.config.mjs` in your project root:
+
+```javascript
+/** @type {import('vibecheck-ai').VibeCheckConfig} */
+export default {
+  // Project metadata
+  project: {
+    name: 'my-app',
+    type: 'nextjs', // 'nextjs' | 'react' | 'express' | 'fastify' | 'generic'
+  },
+
+  // What to analyze
+  include: ['src/**/*.ts', 'src/**/*.tsx'],
+  exclude: ['**/*.test.ts', '**/node_modules/**'],
+
+  // Analysis settings
+  analysis: {
+    strictness: 'standard', // 'relaxed' | 'standard' | 'paranoid'
+    checkDependencies: true,
+    checkEnvVars: true,
+    checkRoutes: true,
+  },
+
+  // File protection
+  firewall: {
+    locked: ['.env*', 'src/core/**'],
+    warn: ['package.json'],
+  },
+
+  // Reality Mode
+  reality: {
+    scenarios: ['auth', 'api', 'forms'],
+    timeout: 30000,
+  },
+};
+```
+
+---
+
+## Pricing
+
+| Feature | Free | Pro ($29/mo) |
+|---------|------|--------------|
+| CLI Commands | ✅ All | ✅ All |
+| Local Scans | ✅ Unlimited | ✅ Unlimited |
+| Security Patterns | ✅ 80+ | ✅ 80+ |
+| Projects | 3 | Unlimited |
+| Scan History | 7 days | 90 days |
+| Cloud Dashboard | ❌ | ✅ |
+| Team Collaboration | ❌ | ✅ |
+| API Access | ❌ | ✅ |
+| Verified Badges | ❌ | ✅ |
+| Priority Support | ❌ | ✅ |
+
+**All CLI commands are free forever.** Pro unlocks cloud features and team collaboration.
+
+---
+
 ## Why VibeCheck?
 
 | Without VibeCheck | With VibeCheck |
 |-------------------|----------------|
-| AI invents non-existent APIs | AI references verified truthpack |
-| Outdated code patterns | Current codebase reality |
-| Runtime errors from hallucinations | Compile-time hallucination detection |
-| Manual code review for AI output | Automated validation |
-| "It worked on my machine" | Consistent truth across team |
+| AI invents fake APIs | References verified truthpack |
+| Runtime 404 errors | Compile-time detection |
+| Silent payment failures | Catches empty catch blocks |
+| Mock data in production | Detects hardcoded values |
+| Manual AI output review | Automated validation |
+| "Works on my machine" | Consistent team truth |
 
-## Pricing
+---
 
-| Tier | Price | Features |
-|------|-------|----------|
-| **Free** | $0 | CLI commands, local analysis, basic truthpack |
-| **Pro** | $29/mo | Unlimited projects, CI/CD, team features, priority support |
-| **Enterprise** | Custom | SSO, audit logs, custom policies, dedicated support |
+## Requirements
 
-All CLI commands are **free forever**. Pro unlocks cloud features and team collaboration.
+- **Node.js** 18.0.0 or higher
+- **OS**: Windows, macOS, Linux
+
+**Optional for Reality Mode:**
+- Playwright (auto-installed on first use)
+
+---
 
 ## Community
 
-- **Discord** — [Join our community](https://vibecheckai.dev/discord)
-- **Twitter** — [@vibecheckai](https://twitter.com/vibecheckai)
-- **GitHub** — [vibecheckai/vibecheck](https://github.com/vibecheckai/vibecheck)
+- 💬 **Discord** — [Join our community](https://vibecheckai.dev/discord)
+- 🐦 **Twitter** — [@vibecheckai](https://twitter.com/vibecheckai)
+- 📦 **GitHub** — [vibecheckai/vibecheck](https://github.com/vibecheckai/vibecheck)
+- 📖 **Docs** — [vibecheckai.dev/docs](https://vibecheckai.dev/docs)
+
+---
 
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](https://github.com/vibecheckai/vibecheck/blob/main/CONTRIBUTING.md) for guidelines.
+We welcome contributions! See [CONTRIBUTING.md](https://github.com/vibecheckai/vibecheck/blob/main/CONTRIBUTING.md).
+
+```bash
+# Clone the repo
+git clone https://github.com/vibecheckai/vibecheck.git
+
+# Install dependencies
+pnpm install
+
+# Run locally
+pnpm dev
+```
+
+---
 
 ## License
 
@@ -340,9 +501,11 @@ MIT © [VibeCheck AI](https://vibecheckai.dev)
 ---
 
 <p align="center">
-  <strong>Stop hallucinations. Ship with confidence.</strong>
+  <strong>Your AI writes the code. VibeCheck makes sure it works.</strong>
 </p>
 
 <p align="center">
-  <a href="https://vibecheckai.dev">Get Started →</a>
+  <a href="https://vibecheckai.dev">
+    <img src="https://img.shields.io/badge/Get%20Started-E040FB?style=for-the-badge&logoColor=white" alt="Get Started" />
+  </a>
 </p>