@vibecheck-ai/cli 20.2.0 → 23.0.0

package/README.md

@@ -1,20 +1,116 @@
-# vibecheck
+<div align="center">
 
-AI code hallucination detector -- find phantom deps, fake APIs, and ghost routes.
+<br />
+
+<img src="https://github.com/guardiavault-oss/Vibecheck/raw/HEAD/packages/vscode-extension/images/vibecheck_logo_transparent_2x.png" alt="VibeCheck CLI" width="80" />
+
+<br />
+
+# VibeCheck CLI
+
+### The trust layer for AI-generated code.
+
+Catches phantom dependencies, ghost API routes, fake SDK methods, credential leaks, and silent failures — before they ship.
+
+<br />
+
+[![npm version](https://img.shields.io/npm/v/@vibecheck-ai/cli?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@vibecheck-ai/cli)&nbsp;&nbsp;[![Downloads](https://img.shields.io/npm/dm/@vibecheck-ai/cli?style=for-the-badge&logo=npm&logoColor=white&color=333)](https://www.npmjs.com/package/@vibecheck-ai/cli)&nbsp;&nbsp;[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](../../LICENSE)
+
+</div>
+
+<br />
+
+<!-- TODO: Replace with actual GIF -->
+<p align="center">
+  <img src="https://github.com/guardiavault-oss/Vibecheck/raw/HEAD/docs/assets/cli-scan-demo.gif" alt="VibeCheck CLI scanning a project in real time" width="820" />
+</p>
+
+<br />
+
+---
+
+<br />
+
+## Why VibeCheck?
+
+Every AI coding tool — **Cursor, Copilot, Claude, Windsurf, ChatGPT** — produces code that compiles, passes lint, and looks correct. Then it breaks in production.
+
+```
+  fetch('/api/payments/confirm')          →  Endpoint never implemented. 404 in prod.
+  catch (err) { }                         →  Error silently swallowed. Data lost.
+  { revenue: 99999 }                      →  Hardcoded mock. Dashboard lies to users.
+  STRIPE_SECRET_KEY in client bundle      →  Credential leaked to every browser.
+```
+
+Your linter says it's fine. TypeScript says it's fine. PR review says it's fine.
+
+**VibeCheck catches what they miss.** 17 detection engines. One command. Zero config.
+
+<br />
+
+---
+
+<br />
 
 ## Quick Start
 
 ```bash
-# Scan your project (no install needed)
-npx vibecheck scan .
+# Scan your project (no install required)
+npx @vibecheck-ai/cli scan .
 
 # Or install globally
-npm install -g vibecheck
+npm install -g @vibecheck-ai/cli
 vibecheck scan .
+
+# Shorthand alias
+vc scan .
 ```
 
+That's it. No config files. No API keys. No setup wizard.
+
+<br />
+
+<!-- TODO: Replace with actual screenshot -->
+<p align="center">
+  <img src="https://github.com/guardiavault-oss/Vibecheck/raw/HEAD/docs/assets/cli-quickstart.png" alt="VibeCheck CLI quick start output" width="720" />
+</p>
+
+<br />
+
+---
+
+<br />
+
+## 17 Detection Engines
+
+Every engine is purpose-built for a specific failure mode that traditional tools miss.
+
+| # | Engine | What it catches |
+|:---:|:---|:---|
+| 1 | **Ghost Routes** | API calls to endpoints that were never implemented |
+| 2 | **Dead UI** | Buttons, forms, and links wired to empty or missing handlers |
+| 3 | **Phantom Imports** | Modules and packages referenced but never installed |
+| 4 | **Silent Failures** | Try/catch blocks that swallow errors without handling them |
+| 5 | **Hardcoded Mocks** | Test data, fake values, and stubs left in production paths |
+| 6 | **Credential Leaks** | API keys, tokens, passwords, and secrets committed to source |
+| 7 | **Env Drift** | Environment variable references that don't exist in `.env` |
+| 8 | **Auth Gaps** | Middleware or guards referencing nonexistent auth providers |
+| 9 | **Type Holes** | `@ts-ignore`, `any` casts, unsafe assertions hiding real bugs |
+| 10 | **Console Pollution** | `console.log`, `console.debug` left in production bundles |
+| 11 | **Version Hallucinations** | API calls that don't exist in the installed package version |
+| 12 | **Slopsquatting** | Misspelled package names that could be typosquat attacks |
+| 13 | **Architectural Drift** | Code that violates your project's structural patterns |
+| 14 | **Dependency Vulnerabilities** | Known CVEs in your dependency tree |
+| 15 | **Performance Anti-patterns** | JSON parsing in loops, sync I/O in async paths |
+| 16 | **Accessibility Violations** | Missing ARIA labels, incorrect roles, keyboard traps |
+| 17 | **Contract Drift** | Code that diverged from its ISL/OpenAPI specification |
+
+<br />
+
 ---
 
+<br />
+
 ## Commands
 
 ### `vibecheck scan`
@@ -27,15 +123,15 @@ vibecheck scan src/
 vibecheck scan src/api.ts
 ```
 
-**Flags:**
-
 | Flag | Default | Description |
-|------|---------|-------------|
+|:---|:---:|:---|
 | `--json` | — | Output findings as JSON |
 | `--no-color` | — | Disable ANSI color output |
-| `--threshold <n>` | 75 | Minimum confidence to include a finding (0–100) |
+| `--threshold <n>` | `75` | Minimum confidence to include a finding (0–100) |
 
-**Example output:**
+<!-- TODO: Replace with actual screenshot -->
+<details>
+<summary><strong>Example output</strong></summary>
 
 ```
   VibeCheck Scan
@@ -60,7 +156,10 @@ vibecheck scan src/api.ts
   5 findings  ·  2 critical  ·  2 high  ·  1 medium
 ```
 
-**JSON output (`--json`):**
+</details>
+
+<details>
+<summary><strong>JSON output</strong> (<code>--json</code>)</summary>
 
 ```json
 {
@@ -86,18 +185,27 @@ vibecheck scan src/api.ts
 }
 ```
 
----
+</details>
+
+<br />
 
 ### `vibecheck score`
 
-Compute and display the trust score for a file or directory.
+Compute a **0–100 trust score** with letter grade and ship/no-ship verdict.
 
 ```bash
 vibecheck score .
 vibecheck score src/ --json
 ```
 
-**Example output:**
+| Flag | Default | Description |
+|:---|:---:|:---|
+| `--json` | — | Output score as JSON |
+| `--no-color` | — | Disable color |
+
+<!-- TODO: Replace with actual screenshot -->
+<details>
+<summary><strong>Example output</strong></summary>
 
 ```
   VibeCheck Trust Score
@@ -131,18 +239,13 @@ vibecheck score src/ --json
   ▲ Run vibecheck scan to review flagged issues before shipping.
 ```
 
-**Flags:**
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--json` | — | Output score as JSON |
-| `--no-color` | — | Disable color |
+</details>
 
----
+<br />
 
 ### `vibecheck guard`
 
-Scan and exit with code 1 if the trust score is below threshold or critical findings exist. Designed for CI pipelines.
+**CI gatekeeper.** Scan and exit with code 1 if the trust score is below threshold or critical findings exist.
 
 ```bash
 vibecheck guard .
@@ -151,41 +254,32 @@ vibecheck guard . --fail-on critical
 vibecheck guard . --fail-on none   # Never fail, just report
 ```
 
-**Flags:**
-
 | Flag | Default | Description |
-|------|---------|-------------|
-| `--threshold <n>` | 70 | Minimum score to pass |
+|:---|:---:|:---|
+| `--threshold <n>` | `70` | Minimum score to pass |
 | `--fail-on <level>` | `critical` | Fail on: `critical`, `high`, `any`, `none` |
 | `--json` | — | Output report as JSON |
 
-**Exit codes:**
-
-| Code | Meaning |
-|------|---------|
+| Exit Code | Meaning |
+|:---:|:---|
 | `0` | Passed — score above threshold, no blocking findings |
 | `1` | Failed — score below threshold or critical finding found |
 | `2` | Error — invalid arguments or scan error |
 
-**Example CI usage:**
-
-```yaml
-- name: VibeCheck Guard
-  run: npx vibecheck guard . --threshold 70
-```
-
----
+<br />
 
 ### `vibecheck roast`
 
-Scan and deliver a brutal, opinionated summary of how AI-generated the code looks.
+Scan and deliver a **brutal, opinionated summary** of how AI-generated the code looks.
 
 ```bash
 vibecheck roast .
 vibecheck roast src/
 ```
 
-**Example output:**
+<!-- TODO: Replace with actual screenshot of roast output -->
+<details>
+<summary><strong>Example output</strong></summary>
 
 ```
   VibeCheck Roast
@@ -211,11 +305,13 @@ vibecheck roast src/
   Run vibecheck scan for the full breakdown.
 ```
 
----
+</details>
+
+<br />
 
 ### `vibecheck context`
 
-Intent-aware context, evolution from provenance, and proactive hints for focused files.
+**Intent-aware codebase intelligence.** Query your code by natural language, evolve from provenance, and get proactive context hints.
 
 ```bash
 vibecheck context --evolve
@@ -224,24 +320,68 @@ vibecheck context --intent "where do we handle auth" --semantic
 vibecheck context --proactive --file packages/api/src/routes/auth.ts
 ```
 
-**Flags:**
-
 | Flag | Description |
-|------|-------------|
-| `--evolve` | Learn from provenance (edits.jsonl); write co-edits, sequences, outcome scores to learned.json |
+|:---|:---|
+| `--evolve` | Learn from provenance (`edits.jsonl`); write co-edits, sequences, outcome scores to `learned.json` |
 | `--intent <query>` | Query codebase by natural language → files, symbols |
 | `--semantic` | Use embeddings for intent query (slower, finds conceptually related code) |
 | `--proactive` | Proactive context for focused file |
 | `--file <path>` | Focused file path (required with `--proactive`) |
 | `--json` | Machine-readable output |
 
+<br />
+
 ---
 
+<br />
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/vibecheck.yml
+name: VibeCheck
+on: [pull_request]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx @vibecheck-ai/cli guard . --threshold 70
+```
+
+### Pre-commit Hook
+
+```bash
+# .husky/pre-commit
+vibecheck guard . --fail-on critical
+```
+
+### package.json Scripts
+
+```json
+{
+  "scripts": {
+    "vibecheck": "vibecheck scan .",
+    "vibecheck:guard": "vibecheck guard . --threshold 70",
+    "vibecheck:score": "vibecheck score ."
+  }
+}
+```
+
+<br />
+
+---
+
+<br />
+
 ## Output Formats
 
-All commands that produce findings support `--json` for machine-readable output. The JSON schema is stable across patch versions.
+All commands support `--json` for machine-readable output. The JSON schema is stable across patch versions.
 
-### Finding schema
+<details>
+<summary><strong>Finding schema</strong></summary>
 
 ```ts
 interface Finding {
@@ -261,13 +401,24 @@ interface Finding {
 }
 ```
 
-### SARIF export
+</details>
+
+<details>
+<summary><strong>SARIF export</strong></summary>
 
 The underlying `FileRunner` supports SARIF 2.1.0 for GitHub Code Scanning integration. Use `--json` and pipe to a SARIF converter, or use the [GitHub Action](../action) which handles this automatically.
 
+</details>
+
+<br />
+
 ---
 
-## Ignore Patterns
+<br />
+
+## Configuration
+
+### Ignore Patterns
 
 Create `.vibecheckignore` at your project root:
 
@@ -282,59 +433,74 @@ src/legacy/old-api.ts
 **/*.test.ts
 ```
 
----
-
-## Environment Variables
+### Environment Variables
 
 | Variable | Description |
-|----------|-------------|
+|:---|:---|
 | `NO_COLOR` | Disable color output (same as `--no-color`) |
 | `VIBECHECK_THRESHOLD` | Default confidence threshold |
 | `VIBECHECK_WORKSPACE` | Override workspace root detection |
 
+### Shell Completion
+
+```bash
+# Bash
+eval "$(vibecheck completion bash)"
+
+# Zsh
+eval "$(vibecheck completion zsh)"
+```
+
+<br />
+
 ---
 
-## Integration
+<br />
 
-### package.json scripts
+## Available on 4 Surfaces
 
-```json
-{
-  "scripts": {
-    "vibecheck": "vibecheck scan .",
-    "vibecheck:guard": "vibecheck guard . --threshold 70",
-    "vibecheck:score": "vibecheck score ."
-  }
-}
-```
+| Surface | Install | Use case |
+|:---|:---|:---|
+| **CLI** (you are here) | `npm i -g @vibecheck-ai/cli` | CI/CD pipelines, terminal workflows, scripting |
+| **VS Code Extension** | [Marketplace](https://marketplace.visualstudio.com/items?itemName=Vibecheck-AI.vibecheck-AI) | Interactive scanning, sidebar dashboard, inline fixes |
+| **MCP Server** | `npx @vibecheck-ai/mcp` | AI agent integration (Cursor, Claude, etc.) |
+| **GitHub Action** | `vibecheck-ai/action@v2` | Pull request verification, deployment gating |
 
-### Pre-commit hook
+<br />
 
-```bash
-# .husky/pre-commit
-vibecheck guard . --fail-on critical
-```
+---
 
-### Shell completion
+<br />
 
-Enable tab completion for commands:
+## Language Support
 
-**Bash:**
-```bash
-eval "$(vibecheck completion bash)"
-# Or append to ~/.bashrc:
-vibecheck completion bash >> ~/.bashrc
-```
+**TypeScript** &nbsp;·&nbsp; **JavaScript** &nbsp;·&nbsp; **React** &nbsp;·&nbsp; **Vue** &nbsp;·&nbsp; **Svelte** &nbsp;·&nbsp; **Next.js** &nbsp;·&nbsp; **Python** &nbsp;·&nbsp; **Go** &nbsp;·&nbsp; **Rust**
 
-**Zsh:**
-```bash
-eval "$(vibecheck completion zsh)"
-# Or append to ~/.zshrc:
-vibecheck completion zsh >> ~/.zshrc
-```
+<br />
+
+## Privacy & Security
+
+- All scanning runs **locally on your machine**
+- **Zero code is transmitted** — ever
+- Works **fully offline** and in air-gapped environments
+- [Open source](https://github.com/guardiavault-oss/Vibecheck) — read every line
+
+<br />
 
 ---
 
-## License
+<br />
+
+<div align="center">
+
+### Build with AI. Ship with proof.
+
+<br />
+
+[Website](https://vibecheckai.dev) &nbsp;&nbsp;·&nbsp;&nbsp; [Documentation](https://docs.vibecheckai.dev) &nbsp;&nbsp;·&nbsp;&nbsp; [Discord](https://discord.gg/vibecheck) &nbsp;&nbsp;·&nbsp;&nbsp; [GitHub](https://github.com/guardiavault-oss/Vibecheck)
+
+<br />
+
+<sub>MIT License &nbsp;·&nbsp; Copyright 2024–2026 VibeCheck AI</sub>
 
-MIT — see [LICENSE](../../LICENSE).
+</div>