@vibe-agent-toolkit/cli 0.1.0 → 0.1.1

package/docs/audit.md

@@ -0,0 +1,446 @@
+# Audit Command Reference
+
+## Overview
+
+The `vat audit` command provides comprehensive validation for Claude plugins, marketplaces, registries, and Claude Skills. It automatically detects resource types and applies appropriate validation rules, outputting structured YAML reports for programmatic parsing.
+
+## Key Features
+
+- **Auto-detection**: Automatically identifies resource type based on file structure
+- **Comprehensive validation**: Schema validation, link integrity, naming conventions
+- **Hierarchical output**: Groups results by marketplace → plugin → skill relationships
+- **Cache staleness detection**: Identifies outdated cached plugins
+- **Cross-platform support**: Works on Windows, macOS, and Linux
+- **CI/CD friendly**: Structured YAML output and exit codes for automation
+
+## Usage
+
+```bash
+vat audit [path] [options]
+```
+
+### Arguments
+
+- `[path]` - Path to audit (optional, default: current directory)
+  - Can be: directory, registry file, SKILL.md file, or resource directory
+
+### Options
+
+- `--user` - Audit user-level Claude plugins installation (`~/.claude/plugins`)
+- `-r, --recursive` - Scan directories recursively for all resource types
+- `--debug` - Enable debug logging (outputs to stderr)
+
+## Supported Resource Types
+
+### 1. Plugin Directories
+
+Plugin directories contain a `.claude-plugin/plugin.json` manifest:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json      # Plugin manifest
+└── skills/
+    └── skill1.md
+```
+
+**Validation checks**:
+- `plugin.json` exists and is valid JSON
+- Schema validation against plugin manifest schema
+- Referenced skills exist
+
+### 2. Marketplace Directories
+
+Marketplace directories contain a `.claude-plugin/marketplace.json` manifest:
+
+```
+my-marketplace/
+├── .claude-plugin/
+│   └── marketplace.json  # Marketplace manifest
+└── plugins/
+    └── plugin1/
+```
+
+**Validation checks**:
+- `marketplace.json` exists and is valid JSON
+- Schema validation against marketplace manifest schema
+- Plugin references are valid
+
+### 3. Registry Files
+
+Registry files track installed plugins and known marketplaces:
+
+- `installed_plugins.json` - Installed plugins registry
+- `known_marketplaces.json` - Known marketplaces registry
+
+**Validation checks**:
+- File exists and is valid JSON
+- Schema validation against registry schema
+- Checksums match installed versions (cache staleness)
+
+### 4. Claude Skills (SKILL.md files)
+
+Individual Claude Skill markdown files with frontmatter:
+
+```markdown
+---
+name: my-skill
+description: Skill description
+---
+
+Skill content here...
+```
+
+**Validation checks** (see Error Codes section below for details):
+- Frontmatter presence and validity
+- Required fields (`name`, `description`)
+- Name and description constraints
+- Link integrity (broken links, missing anchors)
+- Path style (no Windows backslashes)
+- Length limits (warning at 5000+ lines)
+- Console-incompatible tool usage (warning)
+
+### 5. VAT Agents
+
+VAT agent directories contain an `agent.yaml` manifest and `SKILL.md`:
+
+```
+my-agent/
+├── agent.yaml
+└── SKILL.md
+```
+
+**Validation checks**:
+- Validates the `SKILL.md` file with VAT-specific context
+
+## User-Level Audit
+
+The `--user` flag audits your installed Claude plugins:
+
+```bash
+vat audit --user
+```
+
+**What it checks**:
+- All plugins in `~/.claude/plugins/`
+- All marketplaces and their plugins
+- Cache staleness (checksums vs installed versions)
+- All skills within plugins
+
+**Output format**:
+- Hierarchical structure: marketplace → plugin → skill
+- Cache status for each plugin
+- Issue counts at each level
+
+**Example output**:
+```yaml
+status: success
+summary:
+  filesScanned: 42
+  success: 40
+  warnings: 2
+  errors: 0
+  marketplaces: 2
+  standalonePlugins: 3
+  standaloneSkills: 5
+hierarchical:
+  marketplaces:
+    - name: anthropic-agent-skills
+      status: success
+      plugins:
+        - name: document-skills
+          status: warning
+          cacheStatus: fresh
+          skills:
+            - path: .../pdf.md
+              status: warning
+              issues:
+                - code: SKILL_TOO_LONG
+                  message: Skill exceeds recommended length
+```
+
+## Exit Codes
+
+- **0** - Success: All validations passed
+- **1** - Errors found: Validation errors that must be fixed
+- **2** - System error: Config invalid, path not found, etc.
+
+## Validation Checks
+
+### Errors (Must Fix)
+
+Errors prevent the resource from being used correctly:
+
+- **Missing manifests/frontmatter**: Resource structure is invalid
+- **Schema validation failures**: Manifest/frontmatter doesn't match expected format
+- **Broken links**: Links to non-existent files (Skills only)
+- **Reserved words in names**: Using reserved words like "help", "exit" (Skills only)
+- **XML tags in frontmatter**: XML-like tags in name/description (Skills only)
+- **Windows-style backslashes**: Path separators should be forward slashes (Skills only)
+
+### Warnings (Should Fix)
+
+Warnings indicate potential issues but don't prevent usage:
+
+- **Skill exceeds recommended length**: Over 5000 lines (Skills only)
+- **Console-incompatible tools**: References tools that don't work in console (Skills only)
+
+## Error Codes Reference
+
+### Plugin Errors
+
+| Code | Severity | Description | Fix |
+|------|----------|-------------|-----|
+| `PLUGIN_MISSING_MANIFEST` | error | `.claude-plugin/plugin.json` not found | Create plugin manifest |
+| `PLUGIN_INVALID_JSON` | error | Manifest is not valid JSON | Fix JSON syntax |
+| `PLUGIN_INVALID_SCHEMA` | error | Manifest fails schema validation | Fix manifest structure |
+
+### Marketplace Errors
+
+| Code | Severity | Description | Fix |
+|------|----------|-------------|-----|
+| `MARKETPLACE_MISSING_MANIFEST` | error | `.claude-plugin/marketplace.json` not found | Create marketplace manifest |
+| `MARKETPLACE_INVALID_JSON` | error | Manifest is not valid JSON | Fix JSON syntax |
+| `MARKETPLACE_INVALID_SCHEMA` | error | Manifest fails schema validation | Fix manifest structure |
+
+### Registry Errors
+
+| Code | Severity | Description | Fix |
+|------|----------|-------------|-----|
+| `REGISTRY_MISSING_FILE` | error | Registry file not found | Create registry file |
+| `REGISTRY_INVALID_JSON` | error | Registry is not valid JSON | Fix JSON syntax |
+| `REGISTRY_INVALID_SCHEMA` | error | Registry fails schema validation | Fix registry structure |
+
+### Skill Errors
+
+| Code | Severity | Description | Fix |
+|------|----------|-------------|-----|
+| `SKILL_MISSING_FRONTMATTER` | error | No YAML frontmatter found | Add frontmatter with `---` delimiters |
+| `SKILL_MISSING_NAME` | error | `name` field missing from frontmatter | Add `name` field |
+| `SKILL_MISSING_DESCRIPTION` | error | `description` field missing from frontmatter | Add `description` field |
+| `SKILL_NAME_INVALID` | error | Name contains invalid characters | Use only letters, numbers, hyphens, underscores |
+| `SKILL_DESCRIPTION_TOO_LONG` | error | Description exceeds 500 characters | Shorten description |
+| `SKILL_NAME_RESERVED_WORD` | error | Name is a reserved word | Choose a different name |
+| `SKILL_NAME_XML_TAGS` | error | Name contains XML-like tags | Remove XML tags from name |
+| `SKILL_DESCRIPTION_XML_TAGS` | error | Description contains XML-like tags | Remove XML tags from description |
+| `SKILL_DESCRIPTION_EMPTY` | error | Description is empty or whitespace | Provide meaningful description |
+| `PATH_STYLE_WINDOWS` | error | Windows-style backslashes in paths | Use forward slashes (/) instead |
+| `LINK_INTEGRITY_BROKEN` | error | Link to non-existent file | Fix or remove broken link |
+
+### Skill Warnings
+
+| Code | Severity | Description | Fix |
+|------|----------|-------------|-----|
+| `SKILL_TOO_LONG` | warning | Skill exceeds 5000 lines | Consider splitting into multiple skills |
+| `SKILL_CONSOLE_INCOMPATIBLE` | warning | References console-incompatible tools | Use console-compatible alternatives |
+
+### Format Detection Errors
+
+| Code | Severity | Description | Fix |
+|------|----------|-------------|-----|
+| `UNKNOWN_FORMAT` | error | Cannot determine resource type | Ensure path contains valid resource structure |
+
+## Output Format
+
+### Standard Output (stdout)
+
+Structured YAML report for programmatic parsing:
+
+```yaml
+status: success | warning | error
+summary:
+  filesScanned: number
+  success: number      # Files with no issues
+  warnings: number     # Files with warnings only
+  errors: number       # Files with errors
+issues:
+  errors: number       # Total error count across all files
+  warnings: number     # Total warning count across all files
+  info: number         # Total info count across all files
+duration: "123ms"
+files:
+  - path: /path/to/resource
+    status: success | warning | error
+    type: plugin | marketplace | registry | skill
+    issues: []
+```
+
+### Standard Error (stderr)
+
+Human-readable error messages and logs:
+
+```
+ERROR: Audit failed: 2 file(s) with errors
+ERROR: /path/to/skill.md:
+ERROR:   [SKILL_MISSING_NAME] name field is required in frontmatter
+ERROR:     at: line 1
+ERROR:     fix: Add 'name: skill-name' to frontmatter
+```
+
+## Examples
+
+### Basic Usage
+
+Audit current directory:
+
+```bash
+vat audit
+```
+
+Audit specific directory:
+
+```bash
+vat audit ./my-plugin
+```
+
+Audit specific registry file:
+
+```bash
+vat audit ~/.claude/plugins/installed_plugins.json
+```
+
+Audit specific skill:
+
+```bash
+vat audit ./skills/my-skill.md
+```
+
+### User-Level Audit
+
+Audit all installed Claude plugins:
+
+```bash
+vat audit --user
+```
+
+This scans:
+- `~/.claude/plugins/marketplaces/*/`
+- `~/.claude/plugins/cache/*/`
+- All registry files
+- All skills within plugins
+
+### Recursive Scanning
+
+Scan directory tree for all resources:
+
+```bash
+vat audit ./resources --recursive
+```
+
+Finds and validates:
+- Plugin directories (`.claude-plugin/plugin.json`)
+- Marketplace directories (`.claude-plugin/marketplace.json`)
+- Registry files (`installed_plugins.json`, `known_marketplaces.json`)
+- Skill files (`SKILL.md`)
+
+### CI/CD Integration
+
+Use in CI pipeline:
+
+```bash
+#!/bin/bash
+set -e
+
+# Audit all resources
+vat audit --recursive > audit-report.yaml
+
+# Check exit code
+if [ $? -eq 1 ]; then
+  echo "Audit failed with validation errors"
+  cat audit-report.yaml
+  exit 1
+elif [ $? -eq 2 ]; then
+  echo "Audit failed with system error"
+  exit 2
+fi
+
+echo "Audit passed"
+```
+
+GitHub Actions example:
+
+```yaml
+name: Validate Skills
+on: [push, pull_request]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - run: npm install -g vibe-agent-toolkit
+      - run: vat audit --recursive
+```
+
+## Troubleshooting
+
+### "User plugins directory not found"
+
+**Problem**: `--user` flag but no `~/.claude/plugins/` directory
+
+**Solution**: Install Claude Desktop and plugins first, or audit specific path instead
+
+### "Cannot determine resource type"
+
+**Problem**: Path doesn't match any known resource structure
+
+**Solutions**:
+- Ensure plugin has `.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`
+- Ensure registry files are named `installed_plugins.json` or `known_marketplaces.json`
+- Ensure skill files are named `SKILL.md`
+- Use `--recursive` to scan subdirectories
+
+### "Permission denied" on Windows
+
+**Problem**: Cannot access `%USERPROFILE%\.claude\plugins`
+
+**Solution**: Run as administrator or check file permissions
+
+### Large output in CI
+
+**Problem**: Too much YAML output for CI logs
+
+**Solution**: Redirect stdout to file, only show stderr:
+
+```bash
+vat audit --recursive > audit.yaml 2>&1
+if [ $? -ne 0 ]; then
+  echo "Audit failed, see audit.yaml"
+  exit 1
+fi
+```
+
+## Cross-Platform Considerations
+
+### Path Separators
+
+Always use forward slashes (`/`) in:
+- Link paths in SKILL.md files
+- Config file paths
+- Command-line arguments
+
+Windows users: Use forward slashes even on Windows - they work correctly in Node.js.
+
+### Home Directory
+
+`--user` flag automatically resolves:
+- macOS/Linux: `~/.claude/plugins`
+- Windows: `%USERPROFILE%\.claude\plugins`
+
+### Line Endings
+
+SKILL.md files can use any line ending (LF, CRLF) - the parser handles both.
+
+## Related Commands
+
+- `vat agent audit <path>` - Legacy skill-only audit (deprecated)
+- `vat doctor` - Check environment and installation health
+- `vat resources validate` - Validate markdown resources (links, anchors)
+
+## See Also
+
+- [CLI Reference](./index.md) - Complete CLI documentation
+- [Agent Command](./agent.md) - Agent build and import commands
+- [Resources Command](./resources.md) - Markdown resource validation
+- [Doctor Command](./doctor.md) - Environment diagnostics

package/docs/doctor.md

@@ -0,0 +1,268 @@
+# vat doctor - Environment Diagnostics
+
+## Overview
+
+The `vat doctor` command diagnoses common issues with your agent project setup and environment,
+providing actionable suggestions for any problems found.
+
+## Command
+
+### vat doctor [options]
+
+**Purpose:** Check environment and project setup health
+
+**What it checks:**
+1. Node.js version (>=20 required)
+2. Git installed and version
+3. Current directory is a git repository
+4. Configuration file exists (vibe-agent-toolkit.config.yaml)
+5. Configuration is valid YAML with correct schema
+6. VAT version (checks npm for updates)
+7. CLI build status (when running from VAT source tree)
+
+**Options:**
+- `--verbose` - Show all checks (including passing ones)
+
+**Exit Codes:**
+- `0` - All checks passed
+- `1` - One or more checks failed
+
+**Output:** Human-friendly formatted text with emojis
+
+## Usage Examples
+
+### Basic Check
+
+Check all diagnostic items and show only failures:
+
+```bash
+vat doctor
+```
+
+Output when all checks pass:
+```
+🩺 vat doctor
+
+Running diagnostic checks...
+
+📊 Results: 7/7 checks passed
+
+✨ All checks passed! Your vat setup looks healthy.
+```
+
+### Verbose Mode
+
+Show all checks including passing ones:
+
+```bash
+vat doctor --verbose
+```
+
+Output shows all individual checks:
+```
+🩺 vat doctor
+
+Running diagnostic checks...
+
+✅ vat version
+   Current: 0.1.0 — up to date
+
+✅ Node.js version
+   v22.0.0 (meets requirement: >=20.0.0)
+
+✅ Git installed
+   git version 2.43.0
+
+✅ Git repository
+   Current directory is a git repository
+
+✅ Configuration file
+   Found: vibe-agent-toolkit.config.yaml
+
+✅ Configuration valid
+   Configuration is valid
+
+✅ CLI build status
+   Build is up to date (v0.1.0)
+
+📊 Results: 7/7 checks passed
+
+✨ All checks passed! Your vat setup looks healthy.
+```
+
+## Project Context Detection
+
+When run from a subdirectory, doctor shows project context:
+
+```bash
+cd packages/cli
+vat doctor
+```
+
+Output:
+```
+🩺 vat doctor
+
+📍 Project Context
+   Current directory: /path/to/project/packages/cli
+   Project root:      /path/to/project
+   Configuration:     /path/to/project/vibe-agent-toolkit.config.yaml
+
+Running diagnostic checks...
+
+📊 Results: 7/7 checks passed
+
+✨ All checks passed! Your vat setup looks healthy.
+```
+
+## Troubleshooting
+
+When checks fail, doctor provides specific suggestions:
+
+### Node.js Version Too Old
+
+```
+❌ Node.js version
+   v18.0.0 is too old. Node.js 20+ required.
+   💡 Upgrade Node.js: https://nodejs.org/ or use nvm
+```
+
+### Git Not Installed
+
+```
+❌ Git installed
+   Git is not installed
+   💡 Install Git: https://git-scm.com/
+```
+
+### Not a Git Repository
+
+```
+❌ Git repository
+   Current directory is not a git repository
+   💡 Run: git init
+```
+
+### Configuration File Missing
+
+```
+❌ Configuration file
+   Configuration file not found
+   💡 Create vibe-agent-toolkit.config.yaml in project root
+```
+
+### Configuration Invalid
+
+```
+❌ Configuration valid
+   Configuration contains errors: YAML syntax error at line 5
+   💡 Fix YAML syntax or schema errors in vibe-agent-toolkit.config.yaml
+```
+
+### VAT Update Available
+
+```
+✅ vat version
+   Current: 0.1.0, Latest: 0.2.0 available
+   💡 Upgrade: npm install -g vibe-agent-toolkit@latest
+```
+
+### CLI Build Stale (VAT Source Tree)
+
+```
+❌ CLI build status
+   Build is stale: running v0.1.0, source v0.2.0
+   💡 Rebuild packages: bun run build
+```
+
+## Use Cases
+
+### Before Starting Development
+
+Run doctor to ensure your environment is set up correctly:
+
+```bash
+vat doctor
+```
+
+### After Updating VAT
+
+Check that everything still works after upgrading:
+
+```bash
+npm install -g vibe-agent-toolkit@latest
+vat doctor
+```
+
+### Debugging Issues
+
+Use verbose mode to see all check details:
+
+```bash
+vat doctor --verbose
+```
+
+### CI/CD Integration
+
+Use exit codes for automated checks:
+
+```bash
+if vat doctor; then
+  echo "Environment healthy"
+else
+  echo "Environment issues detected"
+  exit 1
+fi
+```
+
+## Check Details
+
+### Node.js Version Check
+
+- **Requirement:** Node.js 20 or higher
+- **Why:** VAT uses modern JavaScript features
+- **Fix:** Install Node.js from https://nodejs.org/ or use nvm
+
+### Git Installation Check
+
+- **Requirement:** Git command available
+- **Why:** VAT projects are typically git repositories
+- **Fix:** Install Git from https://git-scm.com/
+
+### Git Repository Check
+
+- **Requirement:** Current directory is in a git repository
+- **Why:** VAT works best with version-controlled projects
+- **Fix:** Run `git init` to initialize a repository
+
+### Configuration File Check
+
+- **Requirement:** vibe-agent-toolkit.config.yaml exists
+- **Location:** Searches up directory tree from current location
+- **Fix:** Create configuration file in project root
+
+### Configuration Valid Check
+
+- **Requirement:** Configuration file is valid YAML with correct schema
+- **Why:** Invalid config causes runtime errors
+- **Fix:** Validate YAML syntax and check required fields
+
+### VAT Version Check
+
+- **Purpose:** Inform about available updates (advisory only)
+- **Always passes:** This check never fails
+- **Suggestion:** Shows upgrade command if update available
+
+### CLI Build Status Check
+
+- **When:** Only runs when in VAT source tree
+- **Purpose:** Ensure CLI build matches source version (for VAT developers)
+- **Skipped:** When running installed VAT globally
+- **Fix:** Run `bun run build` in VAT source directory
+
+## Tips
+
+- Run `vat doctor` before reporting issues to verify environment
+- Use `--verbose` flag when debugging to see all check details
+- Doctor checks can be run from any subdirectory in your project
+- Exit code 0 means all checks passed (useful for scripts)