claudeskill-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Duy 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,552 @@
+# ClaudeSkill CLI
+
+Command-line tool for bootstrapping and updating ClaudeSkill projects.
+
+**Version**: 1.16.0
+
+## Overview
+
+ClaudeSkill CLI (`cs`) is a command-line tool for bootstrapping and updating projects from private GitHub releases. Built with Bun and TypeScript, provides fast, secure project setup and maintenance.
+
+**Key Features:**
+- Multi-tier GitHub authentication (gh CLI → env vars → keychain → prompt)
+- Streaming downloads with progress tracking and platform optimizations
+- **Offline installation** from local archives or directories
+- Smart file merging with conflict detection
+- Automatic skills directory migration with parallel processing
+- Secure credential storage using OS keychain
+- Beautiful CLI interface with interactive prompts
+- Optional package installation (OpenCode, Gemini)
+- System dependency auto-installation
+- Platform-specific optimizations (macOS native unzip, adaptive concurrency)
+- Intelligent update notifications with 7-day cache
+
+## 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
+- **[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
+
+## Prerequisites
+
+Before using ClaudeSkill CLI, you need to:
+
+1. **Purchase a ClaudeSkill Starter Kit** from [ClaudeSkill.cc](https://claudeskill.cc)
+2. **Get Repository Access**: After purchase, you'll receive access to the private GitHub repository containing your kit
+3. **Create a GitHub Personal Access Token** (PAT) with `repo` scope to download releases
+
+Without a purchased kit and repository access, the CLI will not be able to download any project templates.
+
+## Installation
+
+The ClaudeSkill CLI is published on npm at [npmjs.com/package/claudeskill-cli](https://www.npmjs.com/package/claudeskill-cli).
+
+### Using npm (Recommended)
+
+```bash
+npm install -g claudeskill-cli
+```
+
+### Using Bun
+
+```bash
+bun add -g claudeskill-cli
+```
+
+### Using Yarn
+
+```bash
+yarn global add claudeskill-cli
+```
+
+### Using pnpm
+
+```bash
+pnpm add -g claudeskill-cli
+```
+
+After installation, verify it's working:
+
+```bash
+cs --version
+```
+
+## Usage
+
+### Create New Project
+
+```bash
+# Interactive mode
+cs new
+
+# With options
+cs new --dir my-project --kit engineer
+
+# Show beta versions
+cs new --beta
+
+# With exclude patterns
+cs new --exclude "*.log" --exclude "temp/**"
+
+# Optional packages (OpenCode, Gemini)
+cs new --opencode --gemini
+
+# Install skills dependencies (Python, Node packages, system tools)
+cs new --install-skills
+
+# Command prefix (/cs: namespace to avoid conflicts)
+cs new --prefix
+
+# Offline installation (from local archive or directory)
+cs new --archive ~/downloads/engineer-v1.16.0.zip
+cs new --kit-path ~/extracted-kit/
+```
+
+**Flags:**
+- `--install-skills`: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages
+- `--prefix`: Move commands to /cs: namespace (/plan → /cs: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
+cs init
+
+# Non-interactive mode with sensible defaults
+cs init --yes
+cs init -y
+
+# Combine with other flags
+cs init -g --kit engineer -y
+
+# With options
+cs init --kit engineer --beta
+
+# Global mode (platform-specific paths)
+cs init --global
+
+# Fresh installation (⚠️ DESTRUCTIVE - removes ALL customizations)
+cs init --fresh
+
+# With exclude patterns and prefix
+cs init --exclude "*.local" --prefix
+
+# Offline installation (from local archive or directory)
+cs init --archive ~/downloads/engineer-v1.16.0.zip
+cs 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 /cs: 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 ClaudeSkill | engineer (first option) |
+| Target directory | Current directory (`.`) |
+| Version selection | Latest stable release |
+| Google Gemini setup | Skip |
+| Other optional features | Skip |
+
+### Update CLI
+
+Keep the ClaudeSkill CLI up to date:
+
+```bash
+# Check for CLI updates
+cs update --check
+
+# Update to latest version
+cs update
+
+# Update to specific version
+cs update --version 1.17.0
+
+# Update to beta / skip confirmation
+cs update --beta
+cs update --yes
+```
+
+The CLI notifies you when updates are available via `cs --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
+cs versions
+
+# Filter by specific kit
+cs versions --kit engineer
+cs versions --kit marketing
+
+# Show more versions (default: 30)
+cs versions --limit 50
+
+# Include prereleases and drafts
+cs versions --all
+```
+
+### Diagnostics & Doctor
+
+```bash
+# Full health check (default)
+cs doctor
+
+# Verbose mode with execution timing and command details
+cs doctor --verbose
+
+# Generate shareable diagnostic report (prompts for gist upload)
+cs doctor --report
+
+# Auto-fix all fixable issues
+cs doctor --fix
+
+# CI mode: no prompts, exit 1 on failures
+cs doctor --check-only
+
+# Machine-readable JSON output
+cs doctor --json
+
+# Combine flags
+cs doctor --verbose --check-only --json
+cs doctor --verbose --fix
+```
+
+**Health Checks:**
+- **System**: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
+- **ClaudeSkill**: 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 `cs 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:** `cs diagnose` is deprecated. Use `cs doctor` instead.
+
+### Uninstall
+
+Remove ClaudeSkill installations from your system:
+
+```bash
+cs uninstall              # Interactive mode - prompts for scope and confirmation
+cs uninstall --local      # Uninstall only local installation (current project)
+cs uninstall --global     # Uninstall only global installation (~/.claude/)
+cs uninstall -l -y        # Local only, skip confirmation
+cs uninstall -g -y        # Global only, skip confirmation
+cs 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 ClaudeSkill installations
+- Use `--local` or `--global` flags to skip the prompt
+
+**What it does:**
+- Detects local `.claude` directory in current project
+- Detects global `~/.claude` ClaudeSkill installation
+- Shows paths before deletion
+- Requires confirmation (unless `--yes` flag)
+- Removes ClaudeSkill subdirectories (`commands/`, `agents/`, `skills/`, `workflows/`, `hooks/`, `metadata.json`)
+- **Preserves user configs** like `settings.json`, `settings.local.json`, and `CLAUDE.md`
+
+**Note:** Only removes valid ClaudeSkill installations (with metadata.json). Regular `.claude` directories from Claude Desktop are not affected.
+
+### Other Commands
+
+```bash
+# Show CLI version (shows local + global kit versions)
+cs --version
+
+# Show help
+cs --help
+cs -h
+
+# Command-specific help
+cs new --help
+cs init --help
+cs versions --help
+```
+
+### Debugging
+
+```bash
+cs new --verbose              # Enable verbose logging
+cs new --verbose --log-file debug.log  # Save to file
+CLAUDEKIT_VERBOSE=1 cs 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)
+CK_CACHE_TTL=7200 cs versions    # Cache for 2 hours
+CK_CACHE_TTL=0 cs versions       # Disable caching (always fetch fresh)
+
+# Permanent configuration (add to ~/.bashrc or ~/.zshrc)
+export CK_CACHE_TTL=1800         # 30 minutes
+```
+
+**Cache Location:** `~/.claudeskill/cache/releases/`
+
+### Update Notifications
+
+The `cs --version` command checks for newer versions of your installed ClaudeSkill 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 cs --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:** `~/.claudeskill/cache/version-check.json` (Windows: `%USERPROFILE%\.claudeskill\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 (~/.claudeskill/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
+cs doctor
+
+# Generate report for support
+cs doctor --report
+
+# CI/automation
+cs doctor --check-only --json
+
+# Verbose logging
+cs new --verbose
+cs init --verbose
+```
+
+**Common Issues:**
+- **"Access denied"**: Run `cs doctor` to check auth, use `--fix` to auto-repair
+- **"Authentication failed"**: Run `cs 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 `cs doctor --fix` to reinstall skill dependencies
+- **Need help**: Run `cs doctor --report` and share the gist URL
+
+## Available Kits
+
+ClaudeSkill offers premium starter kits available for purchase at [ClaudeSkill.cc](https://claudeskill.cc):
+
+- **engineer**: ClaudeSkill Engineer - Engineering toolkit for building with Claude
+- **marketing**: ClaudeSkill Marketing - [Coming Soon]
+
+Each kit provides a comprehensive project template with best practices, tooling, and workflows optimized for Claude Code development.
+
+## Configuration
+
+Configuration is stored in `~/.claudeskill/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
+cs new --exclude "*.log" --exclude "temp/**"
+cs 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
+```
+
+## FAQ
+
+**Q: Do I need GitHub CLI?**
+A: Yes, GitHub CLI is required. ClaudeSkill 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