vikit-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ha Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,650 @@
+# vikit Config UI
+
+Command-line tool and web dashboard for managing vikit projects.
+
+**Version**: 1.0.0
+
+## Overview
+
+vikit Config UI (`vk`) provides both CLI and web dashboard for managing vikit projects. It is built with Bun, TypeScript, and React for development, while the published CLI runs on plain Node.js so end users do not need Bun installed.
+
+**Key Features:**
+- **CLI Commands (16)**: new, init, config, projects, setup, skills, agents, commands, migrate, doctor, versions, update, uninstall, watch, content, easter-egg
+- **Web Dashboard**: Interactive React UI via `vk config ui` for configuration and project management
+- **Hook Diagnostics Dashboard**: Inspect recent Claude hook activity and failures from `vk config` across global and project scopes
+- **Projects Registry**: Centralized registry at `~/.vikit/projects.json` with file locking
+- **Skill Installation**: Install vikit skills to other coding agents (Cursor, Codex, etc.)
+- **Multi-tier Authentication**: gh CLI → env vars → keychain → prompt fallback
+- **Smart Merging**: Conflict detection with user customization preservation
+- **Skills Migration**: Auto-detects and migrates skills structure changes
+- **Offline Installation**: From local archives or directories
+- **Security**: Path traversal protection, symlink validation, UNC path protection
+- **Cross-Platform**: macOS, Linux, Windows with platform-specific optimizations
+- **Update Notifications**: Intelligent 7-day cache for version checks
+
+## Documentation
+
+Comprehensive documentation in `/docs`:
+
+- **[Codebase Summary](./docs/codebase-summary.md)** - Overview, structure, key components
+- **[Project Overview & PDR](./docs/project-overview-pdr.md)** - Requirements, features, roadmap
+- **[System Architecture](./docs/system-architecture.md)** - Architecture diagrams, data flow
+- **[Reconciliation Architecture](./docs/reconciliation-architecture.md)** - `vk migrate` RECONCILE → EXECUTE → REPORT design
+- **[Code Standards](./docs/code-standards.md)** - Coding conventions, best practices
+- **[Project Roadmap](./docs/project-roadmap.md)** - Release timeline, feature status
+- **[Deployment Guide](./docs/deployment-guide.md)** - Release procedures
+- **[vk watch](./docs/vk-watch.md)** - GitHub issue monitoring daemon
+- **[vk content](./docs/vk-content.md)** - Automated content generation from git activity
+
+## Prerequisites
+
+## Installation
+
+The vikit CLI is published on npm at [npmjs.com/package/vikit-cli](https://www.npmjs.com/package/vikit-cli).
+
+End-user runtime note: global installs from `npm`, `pnpm`, `yarn`, or `bun` all execute the packaged Node.js CLI. Bun is optional for users and only needed for local vikit CLI development workflows.
+
+### Using npm (Recommended)
+
+```bash
+npm install -g vikit-cli
+```
+
+### Using Bun
+
+```bash
+bun add -g vikit-cli
+```
+
+### Using Yarn
+
+```bash
+yarn global add vikit-cli
+```
+
+### Using pnpm
+
+```bash
+pnpm add -g vikit-cli
+```
+
+After installation, verify it's working:
+
+```bash
+vk --version
+```
+
+## Usage
+
+### Discoverability Quick Start
+
+```bash
+# Top-level command discovery
+vk --help
+
+# Open config dashboard immediately
+vk config
+
+# Expose the dashboard intentionally to your LAN/Tailscale
+vk config --host 0.0.0.0 --no-open
+
+# Command-level help (recommended)
+vk config --help
+vk skills --help
+vk agents --help
+vk commands --help
+vk migrate --help
+```
+
+### Config Dashboard Access
+
+By default, `vk config` binds the dashboard to `127.0.0.1` for local-only access.
+
+Use `--host` when you intentionally want remote access from another device on the same trusted network:
+
+```bash
+# Bind to all interfaces
+vk config --host 0.0.0.0 --no-open
+
+# Bind to a specific interface or hostname
+vk config --host 100.88.12.4 --no-open
+vk config --host dashboard.local --no-open
+```
+
+The dashboard still enforces same-origin browser access. Remote access works when you open the UI from the same host/origin that reaches the server, instead of relying on a hardcoded IP allowlist.
+
+### Create New Project
+
+```bash
+# Interactive mode
+vk new
+
+# With options
+vk new --dir my-project --kit engineer
+
+# Show beta versions
+vk new --beta
+
+# With exclude patterns
+vk new --exclude "*.log" --exclude "temp/**"
+
+# Optional packages (OpenCode, Gemini)
+vk new --opencode --gemini
+
+# Install skills dependencies (Python, Node packages, system tools)
+vk new --install-skills
+
+# Command prefix (/vk: namespace to avoid conflicts)
+vk new --prefix
+
+# Offline installation (from local archive or directory)
+vk new --archive ~/downloads/engineer-v1.16.0.zip
+vk new --kit-path ~/extracted-kit/
+```
+
+**Flags:**
+- `--install-skills`: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages
+- `--prefix`: Move commands to /vk: namespace (/plan → /vk:plan)
+- `--beta`: Show pre-release versions in selection
+- `--opencode/--gemini`: Install optional packages
+- `--archive <path>`: Use local archive (zip/tar.gz) instead of downloading
+- `--kit-path <path>`: Use local kit directory instead of downloading
+
+### Initialize or Update Project
+
+**Note:** Run from project root.
+
+```bash
+# Interactive mode
+vk init
+
+# Non-interactive mode with sensible defaults
+vk init --yes
+vk init -y
+
+# Combine with other flags
+vk init -g --kit engineer -y
+
+# With options
+vk init --kit engineer --beta
+
+# Global mode (platform-specific paths)
+vk init --global
+
+# Fresh installation (⚠️ DESTRUCTIVE - removes ALL customizations)
+vk init --fresh
+
+# With exclude patterns and prefix
+vk init --exclude "*.local" --prefix
+
+# Offline installation (from local archive or directory)
+vk init --archive ~/downloads/engineer-v1.16.0.zip
+vk init --kit-path ~/extracted-kit/
+```
+
+**Flags:**
+- `--yes/-y`: Non-interactive mode with sensible defaults (skip all prompts)
+- `--global/-g`: Use platform-specific config (macOS/Linux: ~/.claude, Windows: %USERPROFILE%\.claude)
+- `--fresh`: Clean reinstall, removes .claude directory (requires "yes" confirmation)
+- `--beta`: Show pre-release versions
+- `--prefix`: Apply /vk: namespace to commands
+- `--archive <path>`: Use local archive (zip/tar.gz) instead of downloading
+- `--kit-path <path>`: Use local kit directory instead of downloading
+
+**Default Behavior with `-y` Flag:**
+
+| Prompt | Default |
+|--------|---------|
+| Select vikit | engineer (first option) |
+| Target directory | Current directory (`.`) |
+| Version selection | Latest stable release |
+| Google Gemini setup | Skip |
+| Other optional features | Skip |
+
+### Update CLI
+
+Keep the vikit CLI up to date:
+
+```bash
+# Check for CLI updates
+vk update --check
+
+# Update to latest version
+vk update
+
+# Update to specific version
+vk update --version 1.1.0
+
+# Update to beta / skip confirmation
+vk update --beta
+vk update --yes
+```
+
+The CLI notifies you when updates are available via `vk --version`.
+
+**Skills Migration:**
+- Auto-detects structure changes (flat → categorized)
+- Preserves customizations (SHA-256 hashing)
+- Creates backup before migration
+- Rollback on failure
+
+### List Available Versions
+
+```bash
+# Show all available versions for all kits
+vk versions
+
+# Filter by specific kit
+vk versions --kit engineer
+vk versions --kit marketing
+
+# Show more versions (default: 30)
+vk versions --limit 50
+
+# Include prereleases and drafts
+vk versions --all
+```
+
+### Diagnostics & Doctor
+
+```bash
+# Full health check (default)
+vk doctor
+
+# Verbose mode with execution timing and command details
+vk doctor --verbose
+
+# Generate shareable diagnostic report (prompts for gist upload)
+vk doctor --report
+
+# Auto-fix all fixable issues
+vk doctor --fix
+
+# CI mode: no prompts, exit 1 on failures
+vk doctor --check-only
+
+# Machine-readable JSON output
+vk doctor --json
+
+# Combine flags
+vk doctor --verbose --check-only --json
+vk doctor --verbose --fix
+```
+
+**Health Checks:**
+- **System**: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
+- **vikit**: Global/project installation, versions, skills
+- **Auth**: GitHub CLI authentication, repository access
+- **Project**: package.json, node_modules, lock files
+- **Modules**: Dynamic skill dependency resolution
+
+**Auto-Fix Capabilities:**
+| Issue | Fix Action |
+|-------|------------|
+| Missing dependencies | Install via package manager |
+| Missing gh auth | Run `gh auth login` |
+| Corrupted node_modules | Reinstall dependencies |
+| Missing global install | Run `vk init --global` |
+| Missing skill deps | Install in skill directory |
+
+**Exit Codes:**
+- `0`: All checks pass or issues fixed
+- `1`: Failures detected (only with `--check-only`)
+
+> **Note:** `vk diagnose` is deprecated. Use `vk doctor` instead.
+
+### Uninstall
+
+Remove vikit installations from your system:
+
+```bash
+vk uninstall              # Interactive mode - prompts for scope and confirmation
+vk uninstall --local      # Uninstall only local installation (current project)
+vk uninstall --global     # Uninstall only global installation (~/.claude/)
+vk uninstall -l -y        # Local only, skip confirmation
+vk uninstall -g -y        # Global only, skip confirmation
+vk uninstall --yes        # Non-interactive - skip confirmation (for scripts)
+```
+
+**Scope Selection:**
+- When both local and global installations exist, you'll be prompted to choose:
+  - **Local only**: Remove from current project (`.claude/`)
+  - **Global only**: Remove from user directory (`~/.claude/`)
+  - **Both**: Remove all vikit installations
+- Use `--local` or `--global` flags to skip the prompt
+
+**What it does:**
+- Detects local `.claude` directory in current project
+- Detects global `~/.claude` vikit installation
+- Shows paths before deletion
+- Requires confirmation (unless `--yes` flag)
+- Removes vikit subdirectories (`commands/`, `agents/`, `skills/`, `workflows/`, `hooks/`, `metadata.json`)
+- **Preserves user configs** like `settings.json`, `settings.local.json`, and `CLAUDE.md`
+
+**Note:** Only removes valid vikit installations (with metadata.json). Regular `.claude` directories from Claude Desktop are not affected.
+
+### Watch GitHub Issues (`vk watch`)
+
+Autonomous daemon that monitors GitHub issues, analyzes them with Claude, generates plans, and creates PRs.
+
+```bash
+# Start watching (single repo)
+vk watch
+
+# Dry-run mode (no posts/PRs)
+vk watch --dry-run
+
+# Custom poll interval (ms)
+vk watch --interval 60000
+
+# Force restart (clear state)
+vk watch --force
+
+# Verbose logging
+vk watch --verbose
+```
+
+**Features:** issue lifecycle management (10 statuses), Claude-powered brainstorming/planning, automatic PR creation, rate limiting (persisted across restarts), maintainer reply filtering, processedIssues TTL, optional git worktree isolation per issue, multi-repo support, graceful shutdown.
+
+**Config:** `.vk.json` under `watch` key. See [docs/vk-watch.md](./docs/vk-watch.md) for full configuration reference.
+
+### Content Generation (`vk content`)
+
+Daemon that scans git activity (commits, PRs, tags), generates social media content with Claude, and publishes to X/Twitter and Facebook.
+
+```bash
+# Interactive setup wizard
+vk content setup
+
+# Start daemon
+vk content start
+
+# Check status
+vk content status
+
+# View logs
+vk content logs
+
+# Queue manual content
+vk content queue
+
+# Review workflow
+vk content approve <id>
+vk content reject <id>
+
+# Dry-run / verbose
+vk content start --dry-run
+vk content start --verbose
+```
+
+**Features:** 11-phase pipeline (scan → filter → classify → context → create → validate → review → photo → publish → engage → analyze), noise filtering, context caching (24h TTL), content validation, photo generation, 3 review modes (auto/manual/hybrid), quiet hours scheduling, engagement tracking, SQLite database, platform-specific adapters.
+
+**Config:** `.vk.json` under `content` key. See [docs/vk-content.md](./docs/vk-content.md) for full configuration reference.
+
+### Other Commands
+
+```bash
+# Show CLI version (shows local + global kit versions)
+vk --version
+
+# Show help
+vk --help
+vk -h
+
+# Command-specific help
+vk new --help
+vk init --help
+vk config --help
+vk skills --help
+vk versions --help
+```
+
+### Debugging
+
+```bash
+vk new --verbose              # Enable verbose logging
+vk new --verbose --log-file debug.log  # Save to file
+VIKIT_VERBOSE=1 vk new   # Via environment variable
+```
+
+### Cache Configuration
+
+Release data is cached locally to improve performance. You can configure the cache TTL:
+
+```bash
+# Set custom cache TTL (in seconds, default: 3600 = 1 hour)
+VK_CACHE_TTL=7200 vk versions    # Cache for 2 hours
+VK_CACHE_TTL=0 vk versions       # Disable caching (always fetch fresh)
+
+# Permanent configuration (add to ~/.bashrc or ~/.zshrc)
+export VK_CACHE_TTL=1800         # 30 minutes
+```
+
+**Cache Location:** `~/.vikit/cache/releases/`
+
+### Update Notifications
+
+The `vk --version` command checks for newer versions of your installed vikit and displays a notification if an update is available. The check is cached for 7 days to minimize API calls.
+
+**Disable Update Notifications:**
+```bash
+# Set environment variable to disable
+NO_UPDATE_NOTIFIER=1 vk --version
+
+# Windows (permanent)
+[System.Environment]::SetEnvironmentVariable("NO_UPDATE_NOTIFIER", "1", [System.EnvironmentVariableTarget]::User)
+
+# macOS/Linux (add to ~/.bashrc or ~/.zshrc)
+export NO_UPDATE_NOTIFIER=1
+```
+
+**Cache Location:** `~/.vikit/cache/version-check.json` (Windows: `%USERPROFILE%\.vikit\cache\`)
+
+## Authentication
+
+The CLI requires GitHub authentication to download releases from private repositories.
+
+### Authentication Flow
+
+```
+┌─────────────────────────────────────────────────┐
+│          Multi-Tier Authentication               │
+│                                                  │
+│  1. GitHub CLI (gh auth token)                  │
+│       ↓ (if not available)                       │
+│  2. Environment Variables (GITHUB_TOKEN)        │
+│       ↓ (if not set)                             │
+│  3. Config File (~/.vikit/config.json)      │
+│       ↓ (if not found)                           │
+│  4. OS Keychain (secure storage)                │
+│       ↓ (if not stored)                          │
+│  5. User Prompt (with save option)              │
+└─────────────────────────────────────────────────┘
+```
+
+### Quick Setup
+
+**Step 1: Install GitHub CLI**
+```bash
+# Windows
+winget install GitHub.cli
+
+# macOS
+brew install gh
+
+# Linux
+sudo apt install gh
+```
+
+**Step 2: Authenticate with GitHub CLI**
+```bash
+gh auth login
+```
+
+When prompted, follow these steps:
+1. Select **GitHub.com**
+2. Select **HTTPS** (or SSH if preferred)
+3. Authenticate Git? → **Yes**
+4. Select **Login with a web browser** (⚠️ recommended)
+5. Copy the one-time code shown
+6. Press Enter to open browser and paste the code
+7. Authorize GitHub CLI
+
+> **⚠️ Important**: Select "Login with a web browser" - do NOT use "Paste an authentication token" as PAT authentication is no longer supported for accessing private repositories.
+
+## Troubleshooting
+
+Run the doctor command to diagnose issues:
+
+```bash
+# Interactive diagnostics
+vk doctor
+
+# Generate report for support
+vk doctor --report
+
+# CI/automation
+vk doctor --check-only --json
+
+# Verbose logging
+vk new --verbose
+vk init --verbose
+```
+
+**Common Issues:**
+- **"Access denied"**: Run `vk doctor` to check auth, use `--fix` to auto-repair
+- **"Authentication failed"**: Run `vk doctor --fix` to re-authenticate, or manually run `gh auth login` (select 'Login with a web browser')
+- **"GitHub CLI not authenticated"**: Run `gh auth login` and select 'Login with a web browser' (NOT 'Paste token')
+- **Module errors**: Run `vk doctor --fix` to reinstall skill dependencies
+- **Need help**: Run `vk doctor --report` and share the gist URL
+
+## Available Kits
+
+vikit offers premium starter kits available for purchase at [vikit.cc](https://vikit.cc):
+
+- **engineer**: vikit Engineer - Engineering toolkit for building with Claude (v1.0.0+)
+
+Each kit provides a comprehensive project template with best practices, tooling, and workflows optimized for Claude Code development.
+
+## Configuration
+
+Configuration is stored in `~/.vikit/config.json`:
+
+```json
+{
+  "github": {
+    "token": "stored_in_keychain"
+  },
+  "defaults": {
+    "kit": "engineer",
+    "dir": "."
+  }
+}
+```
+
+## Protected Files
+
+The following file patterns are protected and will not be overwritten during updates:
+
+- `.env`, `.env.local`, `.env.*.local`
+- `*.key`, `*.pem`, `*.p12`
+- `node_modules/**`, `.git/**`
+- `dist/**`, `build/**`
+
+## Excluding Files
+
+Use `--exclude` flag with glob patterns to skip files:
+
+```bash
+vk new --exclude "*.log" --exclude "temp/**"
+vk update --exclude "node_modules/**" --exclude "dist/**"
+```
+
+**Patterns:** `*` (any chars), `**` (recursive), `?` (single char), `[abc]`, `{a,b}`
+**Restrictions:** No absolute paths, no path traversal (..), 1-500 chars
+**Note:** User patterns are ADDED to default protected patterns
+
+### Custom .claude Files & Skills Migration
+
+**Custom File Preservation:**
+The CLI automatically preserves your custom `.claude/` files during updates:
+
+- Custom slash commands
+- Personal workflows
+- Project-specific configurations
+- Any other custom files in `.claude/` directory
+
+**Skills Directory Migration:**
+Automatic migration when structure changes (flat → categorized):
+
+- **Detection**: Manifest-based + heuristic fallback
+- **Customizations**: SHA-256 hash comparison detects modifications
+- **Safety**: Backup before migration, rollback on failure
+- **Preservation**: All customizations preserved during migration
+- **Interactive**: Prompts for confirmation (can skip in CI/CD)
+
+**Example Migration:**
+```
+Before (flat):
+  .claude/skills/
+    ├── gemini-vision/
+    ├── postgresql-psql/
+    └── cloudflare-dns/
+
+After (categorized):
+  .claude/skills/
+    ├── ai-multimodal/
+    │   └── gemini-vision/
+    ├── databases/
+    │   └── postgresql-psql/
+    └── devops/
+        └── cloudflare-dns/
+```
+
+Customizations in any skill are detected and preserved automatically.
+
+## Development
+
+See [Development Guide](./docs/codebase-summary.md) for:
+- Project structure (modular domain-driven architecture)
+- Build & compilation (`bun run build`, `bun run compile`)
+- Testing & type checking
+- Code standards & linting
+
+**Architecture Highlights:**
+- **Modular design**: 122 focused modules (target: <100 lines each)
+- **Facade pattern**: Each domain exposes public API via facade
+- **Phase handlers**: Complex commands use orchestrator + phase handlers
+- **Self-documenting names**: kebab-case file names describe purpose
+
+**Quick Start:**
+```bash
+bun install
+bun run dev new --kit engineer
+bun test
+# Optional: run expensive CLI integration tests explicitly
+bun run test:integration
+```
+
+## FAQ
+
+**Q: Do I need GitHub CLI?**
+A: Yes, GitHub CLI is required. vikit uses it exclusively for authentication with private repositories.
+
+**Q: How do I authenticate?**
+A: Run `gh auth login`, select 'Login with a web browser', complete OAuth in browser. Do NOT use 'Paste an authentication token'.
+
+**Q: "Access denied" error?**
+A: Accept GitHub repo invitation, re-run `gh auth login` with web browser login, wait 2-5min for permissions.
+
+**Q: "GitHub CLI not authenticated" error?**
+A: Run `gh auth login` and select 'Login with a web browser' (NOT 'Paste token'). PAT authentication is no longer supported.
+
+**Q: Is my token secure?**
+A: Yes. GitHub CLI manages tokens securely via OAuth, stored encrypted in OS keychain.
+
+## License
+
+MIT
+
+This project is inspired from claudekit-cli, used under the MIT License