@nclamvn/vibecode-cli 2.0.0 → 2.2.0

package/.vibecode/learning/fixes.json

@@ -0,0 +1 @@
+[]

package/.vibecode/learning/preferences.json

@@ -0,0 +1 @@
+{}

package/README.md

@@ -1,91 +1,352 @@
 # Vibecode CLI
 
-> Build software with discipline - AI coding with guardrails
+```
+██╗   ██╗██╗██████╗ ███████╗ ██████╗ ██████╗ ██████╗ ███████╗
+██║   ██║██║██╔══██╗██╔════╝██╔════╝██╔═══██╗██╔══██╗██╔════╝
+██║   ██║██║██████╔╝█████╗  ██║     ██║   ██║██║  ██║█████╗
+╚██╗ ██╔╝██║██╔══██╗██╔══╝  ██║     ██║   ██║██║  ██║██╔══╝
+ ╚████╔╝ ██║██████╔╝███████╗╚██████╗╚██████╔╝██████╔╝███████╗
+  ╚═══╝  ╚═╝╚═════╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
+```
 
-[![npm version](https://badge.fury.io/js/vibecode-cli.svg)](https://badge.fury.io/js/vibecode-cli)
+**Build Software with Discipline** — AI coding with guardrails
+
+[![npm version](https://img.shields.io/npm/v/@nclamvn/vibecode-cli.svg)](https://www.npmjs.com/package/@nclamvn/vibecode-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+---
+
 ## What is Vibecode?
 
-Vibecode CLI transforms AI coding tools into disciplined builders. It provides:
+Vibecode is a CLI tool that brings **discipline** to AI-assisted development. Instead of chaotic prompt-and-pray coding, Vibecode enforces a structured workflow:
+
+1. **Define** what you want (Intake)
+2. **Design** how it works (Blueprint)
+3. **Agree** on deliverables (Contract)
+4. **Build** with AI assistance
+5. **Review** against criteria
+6. **Ship** with confidence
 
-- 🎯 **Guided workflow** - Step-by-step from idea to production
-- 🔒 **Quality gates** - No shipping without checks
-- 📋 **Contract-first** - Clear scope before building
-- 📊 **State tracking** - Always know where you are
-- 📝 **Audit trail** - Every decision documented
+---
 
-## Installation
+## Quick Start
 
 ```bash
-npm install -g vibecode-cli
+# Install globally
+npm install -g @nclamvn/vibecode-cli
+
+# Initialize in your project
+cd your-project
+vibecode init
+
+# Start guided session
+vibecode start
 ```
 
-Requires Node.js 18 or higher.
+That's it! Vibecode will guide you through the entire process.
 
-## Quick Start
+---
+
+## Philosophy
+
+### AI as Pipeline, not Tool
+
+Traditional approach:
+```
+Human → AI → Code → ???
+```
+
+Vibecode approach:
+```
+Human → Contract → AI Pipeline → Validated Code → Ship
+         ↑                              │
+         └──────── Feedback Loop ───────┘
+```
+
+### Core Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Contract-First** | Lock scope before building. No scope creep. |
+| **Evidence-Based** | Every build produces diff, logs, screenshots |
+| **Iterative** | Build → Test → Fix loop until tests pass |
+| **Disciplined** | State machine prevents skipping steps |
+
+---
+
+## Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        VIBECODE WORKFLOW                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  PHASE A: PLANNING                                              │
+│  ┌──────┐   ┌───────────┐   ┌──────────┐   ┌────────┐          │
+│  │ INIT │ → │  INTAKE   │ → │ BLUEPRINT│ → │CONTRACT│          │
+│  └──────┘   └───────────┘   └──────────┘   └────────┘          │
+│                                                   │             │
+│                                                   ▼             │
+│                                              ┌────────┐         │
+│                                              │  LOCK  │         │
+│                                              └────────┘         │
+│                                                   │             │
+│  PHASE B: EXECUTION                               │             │
+│                                                   ▼             │
+│  ┌────────┐   ┌───────┐   ┌────────┐   ┌──────────┐            │
+│  │SHIPPED │ ← │REVIEW │ ← │ BUILD  │ ← │   PLAN   │            │
+│  └────────┘   └───────┘   └────────┘   └──────────┘            │
+│                   │             ▲                               │
+│                   │             │                               │
+│                   └─────────────┘                               │
+│                   (if failed, rebuild)                          │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Commands Reference
+
+### Phase A: Planning
+
+| Command | Description | Options |
+|---------|-------------|---------|
+| `vibecode init` | Initialize workspace | `-f, --force` `-q, --quiet` |
+| `vibecode start` | Start guided session | `-r, --resume` |
+| `vibecode status` | Show current state | `--json` `-v, --verbose` |
+| `vibecode lock` | Lock contract, generate spec hash | `-d, --dry-run` `-f, --force` |
+| `vibecode doctor` | Check installation health | — |
+
+### Phase B: Execution
+
+| Command | Description | Options |
+|---------|-------------|---------|
+| `vibecode plan` | Create execution plan | — |
+| `vibecode build` | Build with AI | See Build Flags below |
+| `vibecode review` | Review against criteria | `--skip-manual` |
+| `vibecode snapshot` | Create release | `--patch` `--minor` `--major` |
+| `vibecode config` | Manage settings | `--show` `--provider <name>` |
+
+---
+
+## Build Flags
+
+The `build` command supports multiple modes:
 
 ```bash
-# 1. Initialize workspace
-cd your-project
+# Manual build
+vibecode build --start      # Start building
+vibecode build --evidence   # Capture git diff
+vibecode build --complete   # Mark as done
+
+# AI-powered build
+vibecode build --auto       # Single AI build with Claude Code
+
+# Iterative build (recommended)
+vibecode build --iterate              # Build → Test → Fix loop
+vibecode build --iterate --max 5      # Max 5 iterations
+vibecode build --iterate --strict     # Exit with error if fails
+```
+
+### How `--iterate` Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  ITERATIVE BUILD LOOP                   │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  ┌─────────┐                                            │
+│  │  START  │                                            │
+│  └────┬────┘                                            │
+│       ▼                                                 │
+│  ┌─────────┐     ┌─────────┐     ┌─────────┐           │
+│  │  BUILD  │ ──▶ │  TEST   │ ──▶ │ ANALYZE │           │
+│  │(Claude) │     │(npm test│     │ ERRORS  │           │
+│  └─────────┘     │ + lint) │     └────┬────┘           │
+│       ▲          └─────────┘          │                │
+│       │                               ▼                │
+│       │          ┌─────────┐     ┌─────────┐           │
+│       └──────────│GENERATE │ ◀── │ ERRORS? │           │
+│                  │FIX PROMPT│     └────┬────┘           │
+│                  └─────────┘          │ No             │
+│                                       ▼                │
+│                                  ┌─────────┐           │
+│                                  │  DONE!  │           │
+│                                  └─────────┘           │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Examples
+
+### Example 1: Simple CLI Calculator
+
+```bash
+mkdir my-calculator && cd my-calculator
 vibecode init
 
-# 2. Start guided session
 vibecode start
+# Describe: "CLI calculator with add, subtract, multiply, divide"
 
-# 3. Check status anytime
-vibecode status
+vibecode start  # Continue to blueprint
+vibecode start  # Continue to contract
+vibecode lock   # Lock the contract
 
-# 4. Lock contract when ready
-vibecode lock
+vibecode plan   # Generate execution plan
+vibecode build --iterate  # Build until tests pass
 
-# 5. Health check
-vibecode doctor
+vibecode review    # Review the build
+vibecode snapshot  # Create v1.0.0
 ```
 
-## Commands
+### Example 2: Landing Page
 
-| Command | Description |
-|---------|-------------|
-| `vibecode init` | Initialize .vibecode/ workspace |
-| `vibecode start` | Start guided session |
-| `vibecode status` | Show current state and progress |
-| `vibecode lock` | Validate and lock contract |
-| `vibecode doctor` | Check installation health |
+```bash
+mkdir landing && cd landing
+vibecode init
+vibecode start
+# Describe: "Modern landing page with hero, features, pricing, and contact form"
 
-## Workflow
+# ... follow the workflow
+vibecode build --iterate --max 3
+```
+
+### Example 3: Using with Existing Project
 
+```bash
+cd my-existing-project
+vibecode init
+vibecode start
+# Describe your feature/fix
+
+vibecode build --auto  # Single AI build
 ```
-INIT → INTAKE → BLUEPRINT → CONTRACT → LOCK → BUILD → REVIEW → SHIP
+
+---
+
+## Project Structure
+
+After `vibecode init`, your project will have:
+
 ```
+your-project/
+├── .vibecode/
+│   ├── vibecode.yaml      # Configuration
+│   ├── state.json         # State machine
+│   ├── sessions/          # Session data
+│   │   └── abc123/        # Session ID
+│   │       ├── intake.md
+│   │       ├── blueprint.md
+│   │       ├── contract.md
+│   │       ├── plan.md
+│   │       ├── coder_pack.md
+│   │       └── evidence/
+│   │           ├── changes.diff
+│   │           ├── build.log
+│   │           └── screenshots/
+│   └── logs/
+│       └── audit.log
+└── ... your code
+```
+
+---
+
+## State Machine
+
+Vibecode enforces a strict state machine to prevent skipping steps:
+
+| State | Description | Next States |
+|-------|-------------|-------------|
+| `INIT` | Fresh workspace | `INTAKE_CAPTURED` |
+| `INTAKE_CAPTURED` | Description recorded | `BLUEPRINT_DRAFTED` |
+| `BLUEPRINT_DRAFTED` | Architecture designed | `CONTRACT_DRAFTED` |
+| `CONTRACT_DRAFTED` | Scope defined | `CONTRACT_LOCKED` |
+| `CONTRACT_LOCKED` | Ready to build | `PLAN_CREATED` |
+| `PLAN_CREATED` | Plan generated | `BUILD_IN_PROGRESS` |
+| `BUILD_IN_PROGRESS` | Building... | `BUILD_DONE` |
+| `BUILD_DONE` | Build complete | `REVIEW_PASSED` / `REVIEW_FAILED` |
+| `REVIEW_PASSED` | QA passed | `SHIPPED` |
+| `REVIEW_FAILED` | QA failed | `BUILD_IN_PROGRESS` |
+| `SHIPPED` | Released! | — |
+
+---
+
+## Requirements
 
-## Files Created
+- **Node.js** >= 18.0.0
+- **Claude Code CLI** (for `--auto` and `--iterate` modes)
+  ```bash
+  npm install -g @anthropic-ai/claude-code
+  ```
 
+---
+
+## Configuration
+
+### CLAUDE.md
+
+Create a `CLAUDE.md` file in your project root to provide context to Claude Code:
+
+```markdown
+# Project Rules
+
+- Use TypeScript for all new files
+- Follow existing code style
+- Write tests for new features
+- No console.log in production code
 ```
-.vibecode/
-├── vibecode.yaml      # Configuration
-├── state.json         # Current state
-├── sessions/          # Session files
-│   └── [timestamp]/
-│       ├── intake.md
-│       ├── blueprint.md
-│       └── contract.md
-└── logs/              # Audit trail
+
+This will be automatically injected when using `--auto` or `--iterate`.
+
+---
+
+## Troubleshooting
+
+### "No Vibecode workspace found"
+
+Run `vibecode init` first.
+
+### "Invalid transition"
+
+You're trying to skip a step. Check current state with `vibecode status`.
+
+### "Claude Code CLI not found"
+
+Install Claude Code:
+```bash
+npm install -g @anthropic-ai/claude-code
 ```
 
-## Philosophy
+### Build keeps failing
+
+1. Check `vibecode status --verbose`
+2. Look at `.vibecode/sessions/<id>/evidence/build.log`
+3. Try `vibecode build --iterate --max 5` for more attempts
+
+---
 
-Vibecode is built on the "AI as Pipeline" philosophy:
+## Links
 
-- **AI proposes** based on patterns and best practices
-- **Human decides** based on context and goals
-- **Contract locks** scope before building
-- **Evidence proves** work was done correctly
+- **npm**: https://www.npmjs.com/package/@nclamvn/vibecode-cli
+- **Issues**: https://github.com/nclamvn/vibecode-cli/issues
+
+---
 
 ## License
 
-MIT © Lâm
+MIT © [Lam](https://github.com/nclamvn)
+
+---
+
+## Credits
+
+Powered by [Claude Code](https://github.com/anthropics/claude-code)
 
 ---
 
-Built with ❤️ using Vibecode Kit v4.0
+<p align="center">
+  <strong>"Contract LOCKED = License to Build"</strong>
+</p>

package/SESSION_NOTES.md

@@ -0,0 +1,154 @@
+# VIBECODE CLI - SESSION NOTES
+> Cập nhật: 2025-12-22 (Latest)
+
+---
+
+## 📍 TRẠNG THÁI HIỆN TẠI
+
+### ✅ ĐÃ HOÀN THÀNH
+
+1. **Landing Page** - Port design Notion + Anthropic style
+   - File: `docs-site/src/pages/index.tsx`
+   - Style: WHITE background (#FAFAFA), Be Vietnam Pro font
+   - Sections: Hero, Terminal, Process, Features, Philosophy, CTA
+
+2. **i18n Vietnamese** - Đa ngôn ngữ EN/VI
+   - Translations: `docs-site/i18n/vi/`
+   - Docs tiếng Việt đầy đủ 26 commands
+
+3. **GitHub Repos** (Private)
+   - CLI: https://github.com/nclamvn/vibecode-cli
+   - Docs: https://github.com/nclamvn/vibecode-docs
+
+4. **NPM Package**
+   - Package: @nclamvn/vibecode-cli
+   - Version: **1.8.1** (latest)
+   - Status: Deprecated với message cảnh báo beta
+
+5. **UI Fixes**
+   - Loại bỏ logo khủng long
+   - Footer màu đen đồng nhất (#0A0A0A)
+   - Theme toggle icon thu nhỏ 60%
+   - Default: Light mode
+
+6. **Bug Fix: Version Hardcoded** ✅ FIXED
+   - File: `src/config/constants.js`
+   - Before: `export const VERSION = '1.0.1'` (hardcoded)
+   - After: `export const VERSION = pkg.version` (dynamic)
+   - Published: v1.8.1
+
+---
+
+## 🚧 ĐANG LÀM
+
+### Deploy Render
+- Repo: nclamvn/vibecode-docs
+- File: render.yaml đã có
+- URL Dashboard: https://dashboard.render.com/static/new
+- **BƯỚC TIẾP THEO**:
+  1. Điền `build` vào Publish Directory
+  2. Click "Deploy Static Site"
+
+---
+
+## 📁 CẤU TRÚC PROJECT
+
+```
+/Users/mac/vibecode-cli/
+├── src/                    # CLI source (26 commands)
+│   └── config/constants.js # VERSION đọc từ package.json
+├── bin/vibecode.js         # Entry point
+├── package.json            # v1.8.1
+├── docs-site/              # Docusaurus site (separate git repo)
+│   ├── src/pages/index.tsx # Landing page
+│   ├── docs/               # English docs
+│   ├── i18n/vi/            # Vietnamese docs
+│   └── render.yaml         # Render deploy config
+└── SESSION_NOTES.md        # File này
+```
+
+---
+
+## 🔧 COMMANDS THƯỜNG DÙNG
+
+```bash
+# Dev server docs
+cd /Users/mac/vibecode-cli/docs-site
+npm start
+
+# Build docs
+npm run build
+
+# Test CLI version
+node bin/vibecode.js --version
+
+# Push docs
+cd /Users/mac/vibecode-cli/docs-site
+git add . && git commit -m "message" && git push
+
+# Push CLI
+cd /Users/mac/vibecode-cli
+git add . && git commit -m "message" && git push
+
+# Publish npm (khi cần)
+npm version patch
+npm publish
+
+# Bỏ deprecate npm khi sẵn sàng
+npm deprecate @nclamvn/vibecode-cli ""
+```
+
+---
+
+## 📊 THỐNG KÊ
+
+| Metric | Value |
+|--------|-------|
+| CLI Version | 1.8.1 |
+| CLI Commands | 26 |
+| Lines of Code | 18,612 |
+| JS Files | 167 |
+| Docs Pages | 40+ (EN + VI) |
+
+---
+
+## 🎯 VIỆC CẦN LÀM TIẾP
+
+1. [ ] Hoàn thành deploy Render (điền `build` → Deploy)
+2. [ ] Test site trên production URL
+3. [ ] Phase L: Unit Tests & TypeScript (optional)
+4. [ ] Khi sẵn sàng: Bỏ deprecate npm package
+
+---
+
+## 🔗 LINKS
+
+| Resource | URL |
+|----------|-----|
+| Landing Local EN | http://localhost:3000/ |
+| Landing Local VI | http://localhost:3000/vi/ |
+| GitHub CLI | https://github.com/nclamvn/vibecode-cli |
+| GitHub Docs | https://github.com/nclamvn/vibecode-docs |
+| NPM Package | https://www.npmjs.com/package/@nclamvn/vibecode-cli |
+| Render Dashboard | https://dashboard.render.com |
+
+---
+
+## 📝 LỊCH SỬ SESSION
+
+| Thời gian | Việc đã làm |
+|-----------|-------------|
+| Session 1 | Landing page, i18n, UI fixes |
+| Session 2 | GitHub push, npm deprecate, version bug fix |
+
+---
+
+## 💬 ĐỂ TIẾP TỤC
+
+Chỉ cần nói: **"tiếp tục"** hoặc **"continue"**
+
+Hoặc cụ thể hơn:
+- "tiếp tục deploy render"
+- "đọc SESSION_NOTES.md và cho tôi biết trạng thái"
+
+Claude sẽ đọc file này và biết cần làm gì tiếp.