@chiendt/ack-cli 0.0.0-dev.5

package/README.md

@@ -0,0 +1,714 @@
+# AckKit Config UI
+
+Command-line tool and web dashboard for managing AckKit projects.
+
+**Version**: 1.17.0
+
+## Overview
+
+AckKit Config UI (`ack`) provides both CLI and web dashboard for managing AckKit 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 `ack config ui` for configuration and project management
+- **Hook Diagnostics Dashboard**: Inspect recent Claude hook activity and failures from `ack config` across global and project scopes
+- **Projects Registry**: Centralized registry at `~/.ack/projects.json` with file locking
+- **Skill Installation**: Install AckKit 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)** - `ack 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
+- **[ck watch](./docs/ck-watch.md)** - GitHub issue monitoring daemon
+- **[ck content](./docs/ck-content.md)** - Automated content generation from git activity
+
+## Prerequisites
+
+Before using ACK CLI, you need to:
+
+1. **Purchase a AckKit Starter Kit** from [AckKit.cc](https://AckKit.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 ACK CLI is published on npm at [npmjs.com/package/@chiendt1108/ack-cli](https://www.npmjs.com/package/@chiendt1108/ack-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 ACK CLI development workflows.
+
+### Using npm (Recommended)
+
+```bash
+npm install -g @chiendt1108/ack-cli
+```
+
+### Using Bun
+
+```bash
+bun add -g @chiendt1108/ack-cli
+```
+
+### Using Yarn
+
+```bash
+yarn global add @chiendt1108/ack-cli
+```
+
+### Using pnpm
+
+```bash
+pnpm add -g @chiendt1108/ack-cli
+```
+
+After installation, verify it's working:
+
+```bash
+ack --version
+```
+
+## Usage
+
+### Discoverability Quick Start
+
+```bash
+# Top-level command discovery
+ack --help
+
+# Open config dashboard immediately
+ack config
+
+# Expose the dashboard intentionally to your LAN/Tailscale
+ack config --host 0.0.0.0 --no-open
+
+# Command-level help (recommended)
+ack config --help
+ack skills --help
+ack agents --help
+ack commands --help
+ack migrate --help
+```
+
+### Config Dashboard Access
+
+By default, `ack 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
+ack config --host 0.0.0.0 --no-open
+
+# Bind to a specific interface or hostname
+ack config --host 100.88.12.4 --no-open
+ack 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
+ack new
+
+# With options
+ack new --dir my-project --kit engineer
+
+# Show beta versions
+ack new --beta
+
+# With exclude patterns
+ack new --exclude "*.log" --exclude "temp/**"
+
+# Optional packages (OpenCode, Gemini)
+ack new --opencode --gemini
+
+# Install skills dependencies (Python, Node packages, system tools)
+ack new --install-skills
+
+# Command prefix (/ck: namespace to avoid conflicts)
+ack new --prefix
+
+# Offline installation (from local archive or directory)
+ack new --archive ~/downloads/engineer-v1.16.0.zip
+ack new --kit-path ~/extracted-kit/
+
+# Direct repo downloads are also supported
+ack new --archive ~/downloads/AckKit-engineer-main.zip
+ack new --kit-path ~/downloads/AckKit-engineer-main/
+```
+
+**Flags:**
+- `--install-skills`: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages
+- `--prefix`: Move commands to /ck: namespace (/plan → /ck: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
+
+`--archive` and `--kit-path` both accept direct repo downloads with a single wrapper directory, including GitHub "Download ZIP" archives and extracted repo folders that still contain `AckKit-engineer-main/` or similar at the top level.
+
+### Initialize or Update Project
+
+**Note:** Run from project root.
+
+```bash
+# Interactive mode
+ack init
+
+# Non-interactive mode with sensible defaults
+ack init --yes
+ack init -y
+
+# Combine with other flags
+ack init -g --kit engineer -y
+
+# With options
+ack init --kit engineer --beta
+
+# Global mode (platform-specific paths)
+ack init --global
+
+# Fresh installation (⚠️ DESTRUCTIVE - removes ALL customizations)
+ack init --fresh
+
+# With exclude patterns and prefix
+ack init --exclude "*.local" --prefix
+
+# Offline installation (from local archive or directory)
+ack init --archive ~/downloads/engineer-v1.16.0.zip
+ack init --kit-path ~/extracted-kit/
+
+# Direct repo downloads are also supported
+ack init --archive ~/downloads/AckKit-engineer-main.zip
+ack init --kit-path ~/downloads/AckKit-engineer-main/
+```
+
+**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 /ck: namespace to commands
+- `--archive <path>`: Use local archive (zip/tar.gz) instead of downloading
+- `--kit-path <path>`: Use local kit directory instead of downloading
+
+`--archive` and `--kit-path` both accept direct repo downloads with a single wrapper directory, including GitHub "Download ZIP" archives and extracted repo folders that still contain `AckKit-engineer-main/` or similar at the top level.
+
+**Default Behavior with `-y` Flag:**
+
+| Prompt | Default |
+|--------|---------|
+| Select AckKit | engineer (first option) |
+| Target directory | Current directory (`.`) |
+| Version selection | Latest stable release |
+| Google Gemini setup | Skip |
+| Other optional features | Skip |
+
+### Update CLI
+
+Keep the ACK CLI up to date:
+
+```bash
+# Check for CLI updates
+ack update --check
+
+# Update to latest version
+ack update
+
+# Update to specific version
+ack update --version 1.17.0
+
+# Update to beta / skip confirmation
+ack update --beta
+ack update --yes
+```
+
+The CLI notifies you when updates are available via `ack --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
+ack versions
+
+# Filter by specific kit
+ack versions --kit engineer
+ack versions --kit marketing
+
+# Show more versions (default: 30)
+ack versions --limit 50
+
+# Include prereleases and drafts
+ack versions --all
+```
+
+### Diagnostics & Doctor
+
+```bash
+# Full health check (default)
+ack doctor
+
+# Verbose mode with execution timing and command details
+ack doctor --verbose
+
+# Generate shareable diagnostic report (prompts for gist upload)
+ack doctor --report
+
+# Auto-fix all fixable issues
+ack doctor --fix
+
+# CI mode: no prompts, exit 1 on failures
+ack doctor --check-only
+
+# Machine-readable JSON output
+ack doctor --json
+
+# Combine flags
+ack doctor --verbose --check-only --json
+ack doctor --verbose --fix
+```
+
+**Health Checks:**
+- **System**: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
+- **AckKit**: Global/project installation, versions, skills, skill listing budget, duplicate skill inventory
+- **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 `ack init --global` |
+| Missing skill deps | Install in skill directory |
+| Missing/low Engineer skill listing budget | Ensure computed `skillListingBudgetFraction` and a valid AckKit-recommended `skillListingMaxDescChars` ceiling in project settings |
+
+`ack doctor` never writes `skillOverrides`, hides skills, or deletes duplicate skills automatically. It reports existing `skillOverrides` and inventory issues so all active project/global skills can stay user-invocable while listing pressure is managed through 200k-context-floor project settings and bounded descriptions.
+
+**Exit Codes:**
+- `0`: All checks pass or issues fixed
+- `1`: Failures detected (only with `--check-only`)
+
+> **Note:** `ack diagnose` is deprecated. Use `ack doctor` instead.
+
+### Uninstall
+
+Remove AckKit installations from your system:
+
+```bash
+ack uninstall              # Interactive mode - prompts for scope and confirmation
+ack uninstall --local      # Uninstall only local installation (current project)
+ack uninstall --global     # Uninstall only global installation (~/.claude/)
+ack uninstall -g --kit marketing  # Remove only global Marketing kit
+ack uninstall -l -y        # Local only, skip confirmation
+ack uninstall -g -y        # Global only, skip confirmation
+ack 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 AckKit installations
+- When multiple kits are installed in the selected scope, interactive uninstall prompts for:
+  - **Marketing kit only** or **Engineer kit only**: Remove one kit and preserve the other
+  - **All AckKit kits**: Remove the full selected installation scope
+- Use `--local` or `--global` flags to skip the prompt
+- Use `--kit engineer` or `--kit marketing` to skip the kit prompt
+
+**What it does:**
+- Detects local `.claude` directory in current project
+- Detects global `~/.claude` AckKit installation
+- Shows paths before deletion
+- Requires confirmation (unless `--yes` flag)
+- Removes AckKit subdirectories (`commands/`, `agents/`, `skills/`, `workflows/`, `hooks/`, `metadata.json`)
+- **Preserves user configs** like `settings.json`, `settings.local.json`, and `CLAUDE.md`
+
+**Note:** Only removes valid AckKit installations (with metadata.json). Regular `.claude` directories from Claude Desktop are not affected.
+
+### Watch GitHub Issues (`ack watch`)
+
+Autonomous daemon that monitors GitHub issues, analyzes them with Claude, generates plans, and creates PRs.
+
+```bash
+# Start watching (single repo)
+ack watch
+
+# Dry-run mode (no posts/PRs)
+ack watch --dry-run
+
+# Custom poll interval (ms)
+ack watch --interval 60000
+
+# Force restart (clear state)
+ack watch --force
+
+# Verbose logging
+ack 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:** `.ck.json` under `watch` key. See [docs/ck-watch.md](./docs/ck-watch.md) for full configuration reference.
+
+### Content Generation (`ack 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
+ack content setup
+
+# Start daemon
+ack content start
+
+# Check status
+ack content status
+
+# View logs
+ack content logs
+
+# Queue manual content
+ack content queue
+
+# Review workflow
+ack content approve <id>
+ack content reject <id>
+
+# Dry-run / verbose
+ack content start --dry-run
+ack 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:** `.ck.json` under `content` key. See [docs/ck-content.md](./docs/ck-content.md) for full configuration reference.
+
+### Other Commands
+
+```bash
+# Show CLI version (shows local + global kit versions)
+ack --version
+
+# Show help
+ack --help
+ack -h
+
+# Command-specific help
+ack new --help
+ack init --help
+ack config --help
+ack skills --help
+ack versions --help
+```
+
+### Debugging
+
+```bash
+ack new --verbose              # Enable verbose logging
+ack new --verbose --log-file debug.log  # Save to file
+ACK_VERBOSE=1 ack 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 ack versions    # Cache for 2 hours
+CK_CACHE_TTL=0 ack versions       # Disable caching (always fetch fresh)
+
+# Permanent configuration (add to ~/.bashrc or ~/.zshrc)
+export CK_CACHE_TTL=1800         # 30 minutes
+```
+
+**Cache Location:** `~/.ack/cache/releases/`
+
+### Update Notifications
+
+The `ack --version` command checks for newer versions of your installed AckKit 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 ack --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:** `~/.ack/cache/version-check.json` (Windows: `%USERPROFILE%\.AckKit\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 (~/.ack/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
+ack doctor
+
+# Generate report for support
+ack doctor --report
+
+# CI/automation
+ack doctor --check-only --json
+
+# Verbose logging
+ack new --verbose
+ack init --verbose
+```
+
+**Common Issues:**
+- **"Access denied"**: Run `ack doctor` to check auth, use `--fix` to auto-repair
+- **"Authentication failed"**: Run `ack 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 `ack doctor --fix` to reinstall skill dependencies
+- **Need help**: Run `ack doctor --report` and share the gist URL
+
+## Available Kits
+
+AckKit offers premium starter kits available for purchase at [AckKit.cc](https://AckKit.cc):
+
+| Kit | Slash prefix | Repo | Description |
+|------|--------------|------|-------------|
+| `engineer` | `/ck:` | `chiendt1108/ack-engineer` | Engineering toolkit for building with Claude |
+| `marketing` | `/mkt:` | `claudekit/claudekit-marketing` | Content automation: campaigns, social media, analytics |
+| `fqc-qa` | `/fqc:` | `chiendt1108/ack-fqc-qa` | QA kit: test design, debugging, security, scenario coverage |
+
+Each kit ships with its own slash-command namespace. When `--prefix` is applied, the kit's commands are reorganized under `.claude/commands/{prefix}/` and slash references inside files are rewritten to `/{prefix}:...`.
+
+### Per-project layout override
+
+A user project can pin where the kit installs files via its `package.json`:
+
+```json
+{
+  "ack": {
+    "sourceDir": ".claude",
+    "runtimeDir": ".claude"
+  }
+}
+```
+
+(The legacy `claudekit` field is no longer recognized.)
+
+## Configuration
+
+Configuration is stored in `~/.ack/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
+ack new --exclude "*.log" --exclude "temp/**"
+ack 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
+```
+
+## E2E Tests
+
+Playwright E2E tests cover the `ack migrate` dashboard (3 scenarios). Tests run against the local dev server and use API mocking — no real filesystem state is modified.
+
+**Prerequisites:** Node 18+ or Bun 1.0+, Chromium (installed automatically).
+
+```bash
+# One-time browser setup (if not already installed)
+./node_modules/.bin/playwright install chromium
+
+# Run all E2E specs
+bun run test:e2e
+
+# Interactive UI mode (watch + trace viewer)
+bun run test:e2e:ui
+```
+
+Note: The dev server starts automatically via `bun run dashboard:dev`. CI wiring is a separate follow-up (local-only for now).
+
+## FAQ
+
+**Q: Do I need GitHub CLI?**
+A: Yes, GitHub CLI is required. AckKit 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