vibe-commander 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,643 @@
+# vibe-commander
+
+[![npm version](https://img.shields.io/npm/v/vibe-commander.svg)](https://www.npmjs.com/package/vibe-commander)
+[![license](https://img.shields.io/npm/l/vibe-commander.svg)](https://github.com/viilab/vibe-commander/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/vibe-commander.svg)](https://nodejs.org)
+
+[English](README.md) | [한국어](README.ko.md)
+
+**Unit-based vibe coding workflow automation** — Generate command file sections from a single unit ID, reducing manual context collection from **10 minutes to 10 seconds**.
+
+vibe-commander automates the repetitive cycle of switching between work units: parsing plans, collecting dependencies, finding related commits, and assembling agent context — all driven by a single configuration file that adapts to any project structure.
+
+## Why vibe-commander?
+
+When using AI agents (Cursor, Claude Code, Gemini CLI) with a unit-based development pipeline, every unit switch requires manual context gathering:
+
+**Before** — Manual workflow per unit switch:
+
+```
+1. Check the roadmap for the next unit               (~1 min)
+2. Open the plan and identify dependencies            (~2 min)
+3. Locate dependent unit documents (plans, results)   (~3 min)
+4. Search git history for related commits             (~2 min)
+5. Write pairing question answers                     (~1 min)
+6. Insert special request templates                   (~1 min)
+7. Keep updating commit SHAs during work              (ongoing)
+─────────────────────────────────────────
+Total: ~10–15 minutes per switch × 3–5 switches/day
+```
+
+**After** — With vibe-commander:
+
+```bash
+vc set-unit U-042[Mvp]    # All context collected and assembled in ~10 seconds
+vc update-commit           # Commit SHA auto-tracked from HEAD
+```
+
+One command parses the plan, resolves dependencies, collects related documents and commits, renders the command file section, and handles pairing questions — all driven by your project config.
+
+## Quick Start
+
+### Option 1: Run instantly with npx (no install)
+
+```bash
+npx vibe-commander init --from-existing
+npx vibe-commander set-unit U-001[Mvp]
+```
+
+> **pnpm users**: Use `pnpm dlx vibe-commander` instead of `npx`.
+
+### Option 2: Global install
+
+```bash
+npm install -g vibe-commander
+# or: pnpm add -g vibe-commander
+# or: yarn global add vibe-commander
+
+vc init --from-existing
+vc set-unit U-001[Mvp]
+```
+
+### Option 3: Project devDependency
+
+```bash
+npm install -D vibe-commander
+# or: pnpm add -D vibe-commander
+# or: yarn add -D vibe-commander
+
+npx vc init --from-existing
+npx vc set-unit U-001[Mvp]
+```
+
+> **Important**: Use the same package manager as your project. Mixing package managers (e.g., running `npm install` in a pnpm project) can cause dependency resolution errors.
+
+### First-time setup
+
+```bash
+# Scan existing project files to auto-generate config
+vc init --from-existing
+
+# Or create config interactively
+vc init
+
+# Validate the generated config
+vc validate
+```
+
+This creates `vibe-commander.config.json` in your project root, tailored to your directory structure, unit ID patterns, and document layout.
+
+### Daily Workflow
+
+Once set up, your daily cycle looks like this:
+
+```bash
+# 1. See what's ready to work on
+vc list-units
+
+# 2. Switch to a unit — plan is parsed, deps collected, command file updated
+vc set-unit U-042[Mvp]
+
+# 3. Work with your AI agent (Cursor, Claude Code, etc.)
+#    The command file now has all the context the agent needs.
+
+# 4. Track commits as you go
+vc update-commit              # Latest HEAD
+vc update-commit 3            # Last 3 commits
+vc update-commit --mode append  # Add without replacing
+
+# 5. Move to the next unit
+vc set-unit U-043[Mvp]
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `vc init` | Initialize project config (interactive or `--from-existing` scan) |
+| `vc set-unit <unitId>` | Set current working unit — auto-generates command file section |
+| `vc update-commit [sha\|N]` | Update commit SHA (no arg = HEAD, number = recent N commits) |
+| `vc list-units` | List incomplete units with dependency status |
+| `vc context <unitId>` | Read-only unit context query (no file modifications) |
+| `vc validate` | Validate config file integrity (schema, paths, patterns) |
+| `vc skill install` | Install SKILL files for AI agents |
+| `vc schema [subcommand]` | Introspect CLI schema at runtime |
+
+### vc set-unit
+
+The core command. Parses the unit plan, collects all dependency documents and commits, and updates the command file — in one step.
+
+```bash
+# Basic usage
+vc set-unit U-042[Mvp]
+
+# Preview changes without modifying files
+vc set-unit U-042[Mvp] --dry-run
+
+# Add custom special requests
+vc set-unit U-042[Mvp] --request doc-update --request mcp-codrag
+
+# JSON output for automation
+vc set-unit U-042[Mvp] --json
+```
+
+### vc update-commit
+
+Track commits as you work, without manually copying SHAs.
+
+```bash
+# Auto-detect HEAD commit
+vc update-commit
+
+# Collect last 3 commits
+vc update-commit 3
+
+# Specific SHA
+vc update-commit abc1234f
+
+# Append instead of replace
+vc update-commit --mode append
+```
+
+### vc list-units
+
+See what's ready to work on.
+
+```bash
+# Show all incomplete units
+vc list-units
+
+# Filter by phase
+vc list-units --phase Mvp
+
+# Machine-readable output
+vc list-units --json
+```
+
+### vc context
+
+Read-only context query — useful for agents that need unit info without modifying the command file.
+
+```bash
+vc context U-042[Mvp] --json
+```
+
+### vc schema
+
+Runtime schema introspection for agents to discover CLI capabilities dynamically.
+
+```bash
+# JSON Schema for config file
+vc schema config --json
+
+# All available commands and their flags
+vc schema commands --json
+
+# Unit types and their ID patterns
+vc schema types --json
+
+# Save schema to file
+vc schema config --json --output config-schema.json
+```
+
+### vc validate
+
+Four-stage config validation pipeline: schema check, path existence, regex validity, and pattern conflict detection.
+
+```bash
+vc validate
+vc validate --json
+```
+
+## SKILL Files for AI Agents
+
+SKILL files teach AI agents how to use vibe-commander effectively. One command installs guides for all supported platforms:
+
+```bash
+# Install for all platforms (Cursor + Claude Code + Gemini)
+vc skill install
+
+# Platform-specific
+vc skill install --cursor
+vc skill install --claude
+vc skill install --gemini
+
+# Force overwrite existing files
+vc skill install --force
+```
+
+After installation, agents automatically discover the SKILL guide at:
+
+- **Cursor**: `.cursor/skills/vibe-commander/SKILL.md`
+- **Claude Code**: `.claude/skills/vibe-commander/SKILL.md`
+- **Gemini**: `.gemini/skills/vibe-commander/SKILL.md`
+
+## Agent-First Design
+
+vibe-commander is built for AI agents as first-class consumers. Every design decision prioritizes agent usability.
+
+### AGENTS.md
+
+The project includes an [`AGENTS.md`](AGENTS.md) file (also bundled in the npm package) that agents read at conversation start. It contains:
+
+- Quick command reference
+- Invariant rules (always `--dry-run` first, always `--json`, validate inputs)
+- Safe workflow examples
+- Error handling patterns
+
+### Structured Output
+
+All commands support `--json` for machine-readable output following the `ToolResult<T>` structure:
+
+```json
+{
+  "success": true,
+  "data": {
+    "unitId": "U-042[Mvp]",
+    "title": "U-042[Mvp]: Add authentication module",
+    "depsFound": ["U-041[Mvp]"],
+    "docsFound": [
+      { "unitId": "U-041[Mvp]", "role": "result", "path": "docs/results/U-041[Mvp].md" }
+    ],
+    "commitsFound": ["a1b2c3d4"]
+  }
+}
+```
+
+Errors are also structured:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "UNIT_TYPE_NOT_FOUND",
+    "message": "No matching unit type for: U-999",
+    "details": "Registered types: implement, refactor, checkpoint",
+    "suggestions": ["U-099[Mvp]", "U-100[Mmp]"]
+  }
+}
+```
+
+### Dry-Run Mode
+
+Preview changes before applying them — critical for agent safety:
+
+```bash
+vc set-unit U-042[Mvp] --dry-run --json
+```
+
+### Input Safety
+
+The CLI defends against agent hallucinations by rejecting dangerous patterns:
+
+- Path traversal: `../`, `..\\`
+- Control characters: ASCII < 0x20
+- URL encoding: `%2e`, `%2F`
+- Query parameters: `?`, `#`
+
+Invalid unit IDs trigger fuzzy matching suggestions based on Levenshtein distance.
+
+### Pipe Mode
+
+For automation and orchestrators, pipe JSON via stdin:
+
+```bash
+echo '{"unitId":"U-042[Mvp]"}' | vc set-unit --stdin --json
+```
+
+## VS Code Integration
+
+vibe-commander provides VS Code Tasks for running `vc` commands directly from the editor without switching to a terminal. This is an optional DX enhancement — all features remain fully accessible via the command line.
+
+### Quick Setup
+
+Copy the tasks template to your project:
+
+```bash
+# From npm package
+cp node_modules/vibe-commander/examples/vscode-tasks.json .vscode/tasks.json
+```
+
+If using `npx` instead of a global install, replace `vc` with `npx vc` in the task commands.
+
+### Available Tasks
+
+Access all tasks via `Ctrl+Shift+P` → **Tasks: Run Task**, or `Ctrl+Shift+B` to see the build task group:
+
+| Task | Command | Description |
+|------|---------|-------------|
+| `vc: Set Unit` | `vc set-unit <unitId>` | Switch to a unit (prompts for ID) |
+| `vc: Set Unit (Dry Run)` | `vc set-unit <unitId> --dry-run` | Preview changes without modifying files |
+| `vc: Update Commit (HEAD)` | `vc update-commit` | Track latest HEAD commit |
+| `vc: Update Commit (N)` | `vc update-commit <N>` | Track last N commits (prompts for count) |
+| `vc: List Units` | `vc list-units` | Show incomplete units |
+| `vc: Validate` | `vc validate` | Check config integrity |
+| `vc: Context (JSON)` | `vc context <unitId> --json` | Read-only context query |
+
+Tasks that require a unit ID will prompt for input via VS Code's input dialog (`${input:unitId}`).
+
+### Recommended Keyboard Shortcuts
+
+Tasks work without shortcuts via the Command Palette, but you can bind frequently used tasks for faster access. Add these to your `keybindings.json` (`Ctrl+Shift+P` → **Preferences: Open Keyboard Shortcuts (JSON)**):
+
+```json
+[
+  {
+    "key": "ctrl+shift+u",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: Set Unit"
+  },
+  {
+    "key": "ctrl+shift+alt+u",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: Set Unit (Dry Run)"
+  },
+  {
+    "key": "ctrl+shift+k",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: Update Commit (HEAD)"
+  },
+  {
+    "key": "ctrl+shift+l",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: List Units"
+  }
+]
+```
+
+> **Note**: Keybindings are user-level settings and may conflict with other extensions. Adjust key combinations to your preference.
+
+## Configuration
+
+vibe-commander adapts to any project through `vibe-commander.config.json`. The config defines your unit ID patterns, document paths, parsing rules, and command file structure.
+
+### Minimal Config
+
+```json
+{
+  "$schema": "https://vibe-commander/config-schema.json",
+  "version": 1,
+  "paths": {
+    "commands": "docs/commands.md",
+    "roadmap": "docs/roadmap.md",
+    "docRoots": {
+      "plan": "docs/plans",
+      "result": "docs/results"
+    }
+  },
+  "unitTypes": [
+    {
+      "key": "feature",
+      "displayName": "Feature",
+      "idPattern": "^FEAT-\\d+$",
+      "planDir": "plan",
+      "commandSection": "# Current Feature",
+      "collectDeps": true,
+      "headerTemplate": "### Feature: {{title}}\n- Plan: @{{planPath}}\n- Commit: -"
+    }
+  ]
+}
+```
+
+### Config Sections
+
+| Section | Purpose |
+|---------|---------|
+| `paths` | Document directories, command file, roadmap location |
+| `unitTypes` | Unit type definitions with ID patterns, templates, and behavior |
+| `docDiscovery` | How to find documents for each role (plan, result, runbook) |
+| `planParsing` | How to extract title, dependencies, pairing questions from plans |
+| `backlogParsing` | How to parse the roadmap/backlog for `list-units` |
+| `commitSearch` | Git commit search strategy and filters |
+| `commandSections` | Command file section separators and marker settings |
+| `defaultSpecialRequests` | Default instructions appended to every unit |
+| `specialRequestsByType` | Type-specific additional instructions |
+| `customRequests` | Named request templates selectable with `--request <key>` |
+
+### Auto-Detection
+
+For existing projects, `vc init --from-existing` scans your file tree to detect:
+
+- Unit ID patterns (from filenames)
+- Document directory structure
+- Section headers in command files
+- Roadmap format
+
+### Template Variables
+
+Templates in `headerTemplate` and `docDiscovery` support these variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{unitId}}` | Original unit ID | `U-042[Mvp]` |
+| `{{shortId}}` | Phase removed | `U-042` |
+| `{{bareId}}` | Number only | `042` |
+| `{{title}}` | Full title (with ID) | `U-042[Mvp]: Add auth module` |
+| `{{titleOnly}}` | Title without ID | `Add auth module` |
+| `{{planPath}}` | Relative plan path | `docs/plans/U-042[Mvp].md` |
+| `{{phase}}` | Phase string | `Mvp` |
+| `{{slug}}` | Kebab-case | `u-042-mvp` |
+
+## Architecture
+
+vibe-commander follows a **4-layer architecture** with strict dependency direction:
+
+```
+Layer 4: Consumers    ← Humans, AI agents, orchestrators
+Layer 3: Adapters     ← CLI, SKILL files, stdin/stdout pipe
+Layer 2: Resolver     ← Config-based project structure resolution
+Layer 1: Core         ← Pure functions (no side effects, no I/O)
+```
+
+- **Core** functions are pure: JSON in, JSON out. No `fs`, no `child_process`.
+- **Resolver** absorbs project differences through config, not code.
+- **Adapters** handle all I/O — file reads, git commands, user interaction.
+- **Single production dependency**: [Zod](https://v4.zod.dev/) for runtime validation.
+
+## Building from Source
+
+### Prerequisites
+
+- **Node.js** >= 24.0.0 (LTS) — [Download](https://nodejs.org/)
+- **npm** >= 11 (included with Node.js 24)
+- **Git** — [Download](https://git-scm.com/)
+- **Windows**: Git Bash or WSL recommended for release scripts
+
+Verify your environment:
+
+```bash
+node -v   # Expected: v24.x.x
+npm -v    # Expected: 11.x.x
+```
+
+### Build Steps
+
+```bash
+# Clone the repository
+git clone https://github.com/viilab/vibe-commander.git
+cd vibe-commander
+
+# Install dependencies
+npm install
+
+# Build TypeScript → dist/
+npm run build
+```
+
+The build produces the `dist/` directory containing compiled JavaScript (`.js`) and TypeScript declaration (`.d.ts`) files.
+
+### Local Testing
+
+```bash
+# Register globally for local testing
+npm link
+
+# Verify the CLI works
+vc --help
+vc --version
+
+# Unlink when done
+npm unlink -g vibe-commander
+```
+
+> **Windows note**: `npm link` may require administrator privileges. As an alternative, use `npx tsx src/adapters/cli/index.ts -- --help` during development.
+
+### Clean Build
+
+```bash
+# Remove previous build artifacts and rebuild
+rm -rf dist
+npm run build
+```
+
+### Pre-PR Checklist
+
+Before submitting a pull request, ensure the full quality gate passes:
+
+```bash
+npm run check
+```
+
+This runs typecheck → lint → format check → tests in sequence. All four stages must pass.
+
+### Package Contents
+
+The npm package includes the following files and directories:
+
+| Path | Description |
+|------|-------------|
+| `dist/` | Compiled JavaScript and TypeScript declarations |
+| `skills/` | SKILL files for AI agents (Cursor, Claude Code) |
+| `schemas/` | JSON Schema for config validation and IDE autocompletion |
+| `examples/` | Example configs (Tauri, Next.js, Python) and VS Code tasks template |
+| `AGENTS.md` | Agent quick reference (bundled in package) |
+| `README.md` | English documentation |
+| `README.ko.md` | Korean documentation |
+| `LICENSE` | MIT license |
+
+To verify package contents locally:
+
+```bash
+npm pack --dry-run
+```
+
+## Contributing
+
+### Development Setup
+
+Follow the [Building from Source](#building-from-source) prerequisites, then:
+
+```bash
+git clone https://github.com/viilab/vibe-commander.git
+cd vibe-commander
+npm install
+```
+
+### Available Scripts
+
+```bash
+npm run dev           # Run with tsx (development)
+npm run build         # TypeScript build
+npm run test          # Run Vitest tests
+npm run test:watch    # Vitest watch mode
+npm run test:coverage # Test coverage report
+npm run lint          # ESLint static analysis
+npm run lint:fix      # ESLint auto-fix
+npm run typecheck     # TypeScript type check
+npm run format        # Prettier formatting
+npm run format:check  # Prettier format check (no modifications)
+npm run check         # Full quality gate (typecheck + lint + format + test)
+```
+
+### Release Process
+
+Releases use npm lifecycle hooks for a safe, automated pipeline:
+
+```bash
+# Dry run — verify everything passes without publishing
+npm run release:dry
+
+# Publish a patch release (0.2.0 → 0.2.1)
+npm run release:patch
+
+# Publish a minor release (0.2.0 → 0.3.0)
+npm run release:minor
+
+# Publish a major release (0.2.0 → 1.0.0)
+npm run release:major
+```
+
+Each release command automatically:
+1. Checks for uncommitted changes
+2. Runs the full quality gate (`typecheck + lint + format + test`)
+3. Bumps the version and creates a git tag
+4. Builds the TypeScript output
+5. Publishes to npm
+6. Pushes the version commit and tag to git
+
+**Version Strategy** follows [Semantic Versioning](https://semver.org/):
+
+| Change Type | Version Bump | Example |
+|-------------|-------------|---------|
+| Bug fixes, documentation | Patch | `0.2.0` → `0.2.1` |
+| New features (backward-compatible) | Minor | `0.2.0` → `0.3.0` |
+| Breaking changes | Major | `0.2.0` → `1.0.0` |
+
+**Pre-Release Checklist**:
+1. npm registry login verified: `npm whoami`
+2. All quality gates pass: `npm run check`
+3. Build succeeds: `npm run build`
+4. `README.md` and `README.ko.md` are in sync
+5. Package contents verified: `npm pack --dry-run`
+
+**npm Login** — Required before the first publish or when your auth token has expired:
+
+```bash
+# Login (opens browser or prompts for credentials)
+npm login
+
+# Verify login
+npm whoami
+```
+
+**Recovering from a Failed Publish** — If the release command succeeds at version bump and git push but fails at `npm publish` (e.g., 401/404 errors), the version is already tagged in git. Re-publish without bumping again:
+
+```bash
+npm publish --access public
+```
+
+### Documentation Sync
+
+This project maintains two README files: `README.md` (English) and `README.ko.md` (Korean). When updating documentation, please keep both versions in sync. The English version is the source of truth for npm package pages.
+
+### Project Principles
+
+- **Config-driven universality** — project differences are absorbed by config, never hardcoded
+- **Pure function core** — Layer 1 has no side effects (JSON in → JSON out)
+- **Graceful degradation** — missing roadmap? `set-unit` still works. Missing runbook? Other docs still collected.
+- **Minimal dependencies** — 1 production dep (Zod). Everything else uses Node.js built-ins.
+- **Agent as component** — CLI, SKILL files, and stdin/stdout pipes serve humans, agents, and orchestrators alike.
+
+## License
+
+[MIT](LICENSE) © [viilab](https://github.com/viilab)

package/dist/adapters/cli/commands/git-helpers.js

@@ -8,6 +8,8 @@
  */
 import { execSync } from 'node:child_process';
 import { ok, fail } from '../../../types/index.js';
+/** git CLI 실행 타임아웃 (밀리초) */
+const GIT_EXEC_TIMEOUT_MS = 5_000;
 /**
  * 현재 HEAD 커밋의 short SHA(8자)를 반환한다
  *
@@ -19,7 +21,7 @@ export function getHeadSha(projectRoot) {
         const sha = execSync('git rev-parse --short=8 HEAD', {
             cwd: projectRoot,
             encoding: 'utf-8',
-            timeout: 5000,
+            timeout: GIT_EXEC_TIMEOUT_MS,
             stdio: ['pipe', 'pipe', 'pipe'],
         }).replace(/[\r\n]+$/, '');
         if (!sha) {
@@ -47,7 +49,7 @@ export function getChangedFiles(projectRoot, sha) {
         const output = execSync(`git diff-tree --no-commit-id --name-only -r ${sha}`, {
             cwd: projectRoot,
             encoding: 'utf-8',
-            timeout: 5000,
+            timeout: GIT_EXEC_TIMEOUT_MS,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         const files = output
@@ -76,7 +78,7 @@ export function getRecentShas(projectRoot, count) {
         const output = execSync(`git log --format=%h --abbrev=8 -n ${String(count)}`, {
             cwd: projectRoot,
             encoding: 'utf-8',
-            timeout: 5000,
+            timeout: GIT_EXEC_TIMEOUT_MS,
             stdio: ['pipe', 'pipe', 'pipe'],
         })
             .replace(/\r\n/g, '\n')

package/dist/adapters/cli/commands/init-helpers.js

@@ -64,7 +64,7 @@ export function readExistingConfig(configPath) {
         return null;
     }
     catch {
-        console.log(`${YELLOW}⚠️  기존 설정 파일을 파싱할 수 없습니다. 새 설정을 생성합니다.${RESET}`);
+        console.error(`${YELLOW}⚠️  기존 설정 파일을 파싱할 수 없습니다. 새 설정을 생성합니다.${RESET}`);
         return null;
     }
 }

package/dist/adapters/cli/commands/io-helpers.js

@@ -15,6 +15,10 @@ import { loadConfig } from '../../../config/loader.js';
 import { findDepCommits } from '../../../core/resolvers/dep-commit-resolver.js';
 import { filterCommitsByChangedFiles } from '../../../core/resolvers/commit-filter.js';
 import { getChangedFiles } from './git-helpers.js';
+/** git log 조회 시 최대 커밋 수 */
+const GIT_LOG_LIMIT = 200;
+/** git log 실행 타임아웃 (밀리초) */
+const GIT_LOG_TIMEOUT_MS = 10_000;
 /**
  * 커맨드 파일을 읽어 반환한다
  */
@@ -78,10 +82,10 @@ export function collectGitCommits(depIds, commitSearch, projectRoot) {
     if (commitSearch.strategy === 'disabled')
         return [];
     try {
-        const output = execSync('git log --pretty=oneline -200', {
+        const output = execSync(`git log --pretty=oneline -${String(GIT_LOG_LIMIT)}`, {
             cwd: projectRoot,
             encoding: 'utf-8',
-            timeout: 10000,
+            timeout: GIT_LOG_TIMEOUT_MS,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         const result = findDepCommits(depIds, output, commitSearch);