@boshu2/vibe-check 1.5.0 → 1.6.0

package/CONTRIBUTING.md

@@ -0,0 +1,227 @@
+# Contributing to vibe-check
+
+Thanks for your interest in contributing to vibe-check! This document covers how to get started.
+
+---
+
+## Quick Start
+
+```bash
+# Clone the repo
+git clone https://github.com/boshu2/vibe-check.git
+cd vibe-check
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev -- --since "1 week ago"
+
+# Run tests
+npm test
+```
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** >= 20.0.0
+- **npm** >= 9.0.0
+- **Git** (for testing against repos)
+
+### Project Structure
+
+```
+vibe-check/
+├── src/
+│   ├── cli.ts           # Entry point
+│   ├── git.ts           # Git operations
+│   ├── types.ts         # TypeScript interfaces
+│   ├── commands/        # CLI commands
+│   ├── metrics/         # Metric calculations
+│   ├── score/           # VibeScore computation
+│   ├── sessions/        # Session management
+│   ├── gamification/    # XP, achievements, etc.
+│   └── output/          # Formatters
+├── tests/               # Test files
+├── docs/                # Documentation
+└── bin/                 # CLI wrapper
+```
+
+### Scripts
+
+```bash
+npm run build     # Compile TypeScript
+npm run dev       # Run with ts-node
+npm test          # Run tests
+npm run test:coverage  # Tests with coverage
+```
+
+---
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. Check existing [issues](https://github.com/boshu2/vibe-check/issues)
+2. Create a new issue with:
+   - Clear title
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Node version, OS
+
+### Suggesting Features
+
+1. Open an issue with `[Feature]` prefix
+2. Describe the use case
+3. Explain why it fits vibe-check's purpose
+
+### Submitting Code
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make changes
+4. Add tests for new functionality
+5. Ensure tests pass: `npm test`
+6. Commit with conventional commits: `feat: add my feature`
+7. Push and create PR
+
+---
+
+## Code Guidelines
+
+### TypeScript
+
+- Use strict typing (no `any` unless necessary)
+- Export interfaces from `types.ts`
+- Use descriptive variable names
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(scope): add new feature
+fix(scope): fix bug
+docs: update documentation
+test: add tests
+chore: maintenance task
+```
+
+### Testing
+
+- Add tests for new features
+- Maintain test coverage
+- Use descriptive test names
+
+```typescript
+describe('calculateTrustPassRate', () => {
+  it('should return 100% when no immediate fixes', () => {
+    // ...
+  });
+});
+```
+
+---
+
+## Adding New Features
+
+### Adding a Metric
+
+1. Create `src/metrics/new-metric.ts`
+2. Export function returning `MetricResult`
+3. Add to `src/metrics/index.ts`
+4. Update `types.ts` with new interfaces
+5. Update `output/terminal.ts` to display
+6. Add tests
+
+### Adding an Achievement
+
+1. Edit `src/gamification/achievements.ts`
+2. Add to `ACHIEVEMENTS` array
+3. Define condition function
+4. Add test case
+
+### Adding a Command
+
+1. Create `src/commands/new-command.ts`
+2. Export from `src/commands/index.ts`
+3. Register in `src/cli.ts`
+4. Document in README.md
+
+---
+
+## Testing Locally
+
+### Against a Real Repo
+
+```bash
+# Point to any git repo
+npm run dev -- --repo /path/to/repo --since "1 week ago"
+```
+
+### With Verbose Output
+
+```bash
+npm run dev -- --verbose --since "1 week ago"
+```
+
+### Testing Gamification
+
+```bash
+npm run dev -- profile
+npm run dev -- profile --achievements
+```
+
+---
+
+## Pull Request Process
+
+1. **Title**: Use conventional commit format
+2. **Description**: Explain what and why
+3. **Tests**: Include tests for changes
+4. **Docs**: Update docs if needed
+5. **Review**: Address feedback promptly
+
+### PR Checklist
+
+- [ ] Tests pass (`npm test`)
+- [ ] Code compiles (`npm run build`)
+- [ ] No lint errors
+- [ ] Docs updated if needed
+- [ ] Commit messages follow convention
+
+---
+
+## Release Process
+
+Maintainers only:
+
+```bash
+# Bump version (creates git tag)
+npm version patch|minor|major
+
+# Publish to npm
+npm publish --access=public
+```
+
+---
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Focus on constructive feedback
+- Help others learn
+
+---
+
+## Questions?
+
+- Open an [issue](https://github.com/boshu2/vibe-check/issues)
+- Check existing docs in `/docs`
+
+---
+
+**Thanks for contributing!**

package/README.md

@@ -1,233 +1,290 @@
 # vibe-check
 
-**Quick check: are you building or spiraling?**
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│     ██╗   ██╗██╗██████╗ ███████╗     ██████╗██╗  ██╗██╗  ██╗   │
+│     ██║   ██║██║██╔══██╗██╔════╝    ██╔════╝██║  ██║██║ ██╔╝   │
+│     ██║   ██║██║██████╔╝█████╗█████╗██║     ███████║█████╔╝    │
+│     ╚██╗ ██╔╝██║██╔══██╗██╔══╝╚════╝██║     ██╔══██║██╔═██╗    │
+│      ╚████╔╝ ██║██████╔╝███████╗    ╚██████╗██║  ██║██║  ██╗   │
+│       ╚═══╝  ╚═╝╚═════╝ ╚══════╝     ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   │
+│                                                                 │
+│              Are you building... or spiraling?                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-Analyzes your git history to tell you if you're making progress or stuck in fix loops.
+[![npm version](https://img.shields.io/npm/v/@boshu2/vibe-check.svg)](https://www.npmjs.com/package/@boshu2/vibe-check)
+[![CI](https://github.com/boshu2/vibe-check/actions/workflows/ci.yml/badge.svg)](https://github.com/boshu2/vibe-check/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+**Git-powered metrics for AI-assisted coding.** Catch debug spirals before they catch you.
 
 ```bash
-npm install -g @boshu2/vibe-check
+npx @boshu2/vibe-check --since "2 hours ago"
 ```
 
-Or run directly:
-
-```bash
-npx @boshu2/vibe-check
 ```
-
-## Quick Start
-
-```bash
-# Check your recent work
-vibe-check --since "1 week ago"
-
-# Watch mode - catch spirals in real-time
-vibe-check watch
+╭──────────────────────────────────────────────────────────────╮
+│  VIBE-CHECK                                    Nov 30, 2025  │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Rating: ELITE ✨                                            │
+│                                                              │
+│  Trust Pass Rate   ████████████████████  95%  ELITE          │
+│  Rework Ratio      ████░░░░░░░░░░░░░░░░  18%  ELITE          │
+│  Debug Spirals     None detected              ELITE          │
+│                                                              │
+│  You're in the zone. Ship it.                                │
+│                                                              │
+╰──────────────────────────────────────────────────────────────╯
 ```
 
-## Watch Mode (Real-Time Detection)
+---
 
-Catch spirals as they happen, not after:
+## Dashboard
 
 ```bash
-vibe-check watch
+vibe-check dashboard
 ```
 
+Opens a visual dashboard with **real-time insights** about your coding patterns:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  🎯 VIBE-CHECK DASHBOARD                                         ━ ▢ ✕ │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │  🎯  89%    │  │  📈  85%    │  │  🔥  12     │  │  🏆  8/19   │    │
+│  │ Vibe Score  │  │  Average    │  │ Day Streak  │  │Achievements │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
+│                                                                         │
+│  ┌─ Vibe Score Trend ──────────────────────────────────────────────┐   │
+│  │                                                            ●    │   │
+│  │                                          ●       ●    ●        │   │
+│  │                    ●    ●    ●    ●                            │   │
+│  │  ●    ●    ●                                                   │   │
+│  │  Mon  Tue  Wed  Thu  Fri  Sat  Sun  Mon  Tue  Wed  Thu  Fri   │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                         │
+│  ┌─ Insights ──────────────────────────────────────────────────────┐   │
+│  │  🎯 Improvement Streak: 3 weeks of declining spiral rate        │   │
+│  │  ⏰ Peak Hours: Most productive at 10am (23% of commits)        │   │
+│  │  📅 Best Day: Thursday is your power day                        │   │
+│  │  ⚠️  High-Risk: "auth" scope has 60% fix ratio                  │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
 ```
-VIBE-CHECK WATCH MODE
-Monitoring /path/to/repo
-Polling every 5s - Ctrl+C to stop
 
-────────────────────────────────────────────────────────────
-  09:15 fix(auth) handle token refresh
-  09:18 fix(auth) add retry logic
-  09:22 fix(auth) increase timeout
+---
 
-  ⚠️  SPIRAL DETECTED
-      Component: auth
-      Fixes: 3 commits, 7 min
+## Install
 
-      Consider:
-      • Step back and write a test
-      • Check the docs or ask for help
-      • Take a 5-minute break
-────────────────────────────────────────────────────────────
+```bash
+npm install -g @boshu2/vibe-check
 ```
 
-Options:
-- `--quiet` - Only show warnings, not all commits
-- `--interval <ms>` - Poll frequency (default: 5000ms)
+## Quick Start
 
-## Example Output
+```bash
+# Analyze recent work
+vibe-check --since "1 week ago"
 
-```
-VIBE-CHECK Nov 21 - Nov 28
+# Real-time spiral detection
+vibe-check watch
 
-  Rating: HIGH
-  Trust: 92% HIGH
-  Rework: 35% MEDIUM
+# Visual dashboard
+vibe-check dashboard
 
-  Run without --simple for full details
+# View your profile & achievements
+vibe-check profile
 ```
 
-## Automatic Baseline Comparison
+---
+
+## Watch Mode
 
-vibe-check learns YOUR patterns and compares each session to your baseline:
+Catch spirals **as they happen**, not after:
 
 ```bash
-vibe-check --since "1 hour ago"
+vibe-check watch
 ```
 
 ```
-VS YOUR BASELINE
+VIBE-CHECK WATCH MODE
+Monitoring: ~/projects/my-app
+────────────────────────────────────────────────────────
 
-  Trust:  92% (+7% vs avg 85%)
-  Rework: 18% (-4% vs avg 22%)
+  09:15  fix(auth): handle token refresh
+  09:18  fix(auth): add retry logic
+  09:22  fix(auth): increase timeout
 
-  Better than your usual - nice flow!
+  ⚠️  SPIRAL DETECTED
+  ┌────────────────────────────────────────────────────┐
+  │  Component: auth                                   │
+  │  Fixes: 3 commits over 7 minutes                   │
+  │                                                    │
+  │  💡 Consider:                                      │
+  │     • Step back and write a test                   │
+  │     • Check the docs or ask for help               │
+  │     • Take a 5-minute break                        │
+  └────────────────────────────────────────────────────┘
+
+────────────────────────────────────────────────────────
 ```
 
-After 5+ sessions, you get automatic feedback without declaring anything.
+---
 
-## Manual Session Workflow (Optional)
+## Gamification
 
-For explicit level tracking, declare before starting:
+Level up your coding with XP, streaks, and achievements:
 
 ```bash
-# Before work: declare your expectation
-vibe-check start --level 3
-
-# ... do your work ...
-
-# After work: compare reality vs expectation
-vibe-check --since "1 hour ago"
+vibe-check profile
 ```
 
 ```
-SESSION COMPLETE
-
-  Declared: Level 3 - Balanced (60% trust)
-  Duration: 45 min, 12 commits
-
-  Trust Pass:  85% (expected >65%) ✓
-  Rework:      20% (expected <30%) ✓
-
-  ✓ Level 3 was appropriate for this work
+╭─────────────────────────────────────────────────────╮
+│                                                     │
+│   🏔️  Level 6 Grandmaster                          │
+│   ████████████████░░░░░░░░  2140 / 5000 XP         │
+│                                                     │
+│   🔥  12 day streak (longest: 14)                   │
+│   🏆  8/19 achievements unlocked                    │
+│                                                     │
+│   Recent Unlocks:                                   │
+│   ✨ Elite Vibes    🧘 Zen Master    📊 Regular     │
+│                                                     │
+╰─────────────────────────────────────────────────────╯
 ```
 
-### Vibe Levels
+**19 achievements** including 2 hidden ones. Can you find them?
 
-| Level | Name | Trust | When to Use |
-|-------|------|-------|-------------|
-| 5 | Full Automation | 95% | Formatting, linting |
-| 4 | High Trust | 80% | Boilerplate, CRUD |
-| 3 | Balanced | 60% | Features, tests |
-| 2 | Careful | 40% | Integrations, APIs |
-| 1 | Skeptical | 20% | Architecture, security |
-| 0 | Manual | 0% | Novel research |
+---
 
-## The Core Metrics
+## The Metrics
 
-| Metric | What It Measures | Elite | Needs Work |
-|--------|------------------|-------|------------|
+| Metric | What It Measures | 🟢 Elite | 🔴 Needs Work |
+|--------|------------------|----------|---------------|
 | **Trust Pass Rate** | % commits without immediate fix | >95% | <80% |
 | **Rework Ratio** | % commits that are fixes | <30% | >50% |
-| **Debug Spiral** | Stuck in fix loops? | 0 detected | 3+ detected |
+| **Debug Spiral** | Stuck in fix loops? | 0 | 3+ |
 
-## Git Hook
+---
 
-Run automatically before every push:
-
-```bash
-vibe-check init-hook
-```
+## Vibe Levels
 
-Block pushes on LOW rating:
+Declare your trust level before starting work:
 
 ```bash
-vibe-check init-hook --block-low
+vibe-check start --level 3
+# ... code ...
+vibe-check --since "1 hour ago"
 ```
 
-## Gamification
+| Level | Name | Trust | Use For |
+|-------|------|-------|---------|
+| **5** | Full Auto | 95% | Formatting, linting |
+| **4** | High Trust | 80% | Boilerplate, CRUD |
+| **3** | Balanced | 60% | Features, tests |
+| **2** | Careful | 40% | Integrations, APIs |
+| **1** | Skeptical | 20% | Architecture, security |
+| **0** | Manual | 0% | Novel research |
 
-Track progress with XP, streaks, and achievements:
+---
 
-```bash
-vibe-check profile
-```
-
-```
-╭─────────────────────────────────────────────╮
-│           Your Vibe Profile                 │
-├─────────────────────────────────────────────┤
-│  🌲 Level 4 Expert                          │
-│  ████████████████░░░░  320/400 XP           │
-│                                             │
-│  🔥 Current Streak: 5 days                  │
-│  🏆 Achievements: 8/19 unlocked             │
-╰─────────────────────────────────────────────╯
-```
+## Git Hook
 
-## CLI Options
+Auto-run before every push:
 
+```bash
+vibe-check init-hook           # Install hook
+vibe-check init-hook --block-low  # Block LOW pushes
 ```
-vibe-check [options]
 
-Options:
-  --since <date>       Start date (e.g., "1 week ago")
-  --until <date>       End date (default: now)
-  -f, --format <type>  Output: terminal, json, markdown
-  -r, --repo <path>    Repository path
-  -o, --output <file>  Write JSON to file
-  -s, --simple         Simplified output
-  --score              Include VibeScore
-  -v, --verbose        Verbose output
-
-Commands:
-  watch                Real-time spiral detection
-  start --level <n>    Start session with declared level (0-5)
-  profile              View your gamification profile
-  init-hook            Install pre-push git hook
-```
+---
 
 ## GitHub Action
 
 ```yaml
 name: Vibe Check
-on:
-  pull_request:
-    branches: [main]
+on: [pull_request]
 
 jobs:
-  vibe-check:
+  vibe:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Run Vibe Check
-        uses: boshu2/vibe-check@v1
+      - uses: boshu2/vibe-check@v1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-## Requirements
+---
 
-- Node.js >= 20.0.0
-- Git repository
+## All Commands
+
+```
+vibe-check [options]           Analyze git history
+vibe-check watch               Real-time spiral detection
+vibe-check dashboard           Visual dashboard + insights
+vibe-check profile             XP, streaks, achievements
+vibe-check timeline            Coding journey visualization
+vibe-check start --level <n>   Declare vibe level (0-5)
+vibe-check intervene           Record spiral intervention
+vibe-check init-hook           Install git hook
+vibe-check cache               Manage local storage
+```
+
+**Options:**
+```
+--since <date>       Start date ("1 week ago", "2024-01-01")
+--until <date>       End date (default: now)
+--score              Include VibeScore calculation
+--simple             Compact output
+--format <type>      terminal | json | markdown
+--output <file>      Save JSON to file
+--verbose            Detailed output
+```
+
+---
+
+## Philosophy
 
-## What This Is (and Isn't)
+**vibe-check is a mirror, not a judge.**
 
-**Is:** A quick feedback tool to catch debug spirals early
+Use it for self-reflection. Catch your own patterns. Improve your own flow.
 
-**Isn't:** A productivity metric, performance review tool, or AI effectiveness measure
+It's not a productivity metric. It's not for performance reviews. It's not measuring AI effectiveness.
 
-Use it for self-reflection, not external judgment.
+It's just asking: *are you building, or are you spiraling?*
+
+---
+
+## Requirements
+
+- Node.js >= 20.0.0
+- Git repository with commits
+
+## Docs
+
+- [Vibe-Coding Ecosystem](docs/VIBE-ECOSYSTEM.md) - Full methodology
+- [Architecture](docs/ARCHITECTURE.md) - Codebase structure
+- [Gamification](docs/GAMIFICATION.md) - XP & achievements deep dive
+- [Metrics Explained](docs/METRICS-EXPLAINED.md) - How it works
+- [Changelog](CHANGELOG.md) - Version history
 
 ## License
 
 MIT
+
+---
+
+<p align="center">
+  <i>Built for developers who vibe with AI</i>
+</p>