@hashicorp/kits 0.1.0

package/README.md

@@ -0,0 +1,619 @@
+# @hashicorp/kits
+
+Install AI agent kits into your favorite coding assistants.
+
+## Overview
+
+The Kit Installer is a CLI tool that discovers, validates, and installs AI agent kits from kit repositories into various AI coding assistant harnesses. It supports multiple harnesses including Claude Code, Codex, Gemini CLI, GitHub Copilot, and OpenCode.
+
+## Installation
+
+```bash
+# Run directly with npx (recommended)
+npx @hashicorp/kits install example-org/kits
+
+# Or install globally
+npm install -g @hashicorp/kits
+kits install example-org/kits
+```
+
+To validate kit repositories, use the built-in validate command:
+
+```bash
+npx @hashicorp/kits validate ./agent-kits
+npx @hashicorp/kits validate --commands example-org/kits
+```
+
+## Quick Start
+
+```bash
+# Interactive installation - guides you through selection
+npx @hashicorp/kits install example-org/kits
+
+# Install to global scope (user-level, available in all projects)
+npx @hashicorp/kits install example-org/kits --global -y
+
+# Install to project scope (current directory only)
+npx @hashicorp/kits install example-org/kits --project -y
+
+# Install specific kit to specific harness
+npx @hashicorp/kits install example-org/kits \
+  -a claude-code \
+  -k terraform-development \
+  --global
+
+# List available kits without installing
+npx @hashicorp/kits install example-org/kits -l
+
+# Check what would be installed (dry run)
+npx @hashicorp/kits install example-org/kits --global --dry-run
+```
+
+## Commands
+
+### Install
+
+Installs kits from a source repository.
+
+```bash
+kits install <source> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-a, --agent <name...>` | Target specific harness(es) |
+| `-k, --kit <name...>` | Install specific kit(s) |
+| `-g, --global` | Install to global scope (user-level, available in all projects) |
+| `-p, --project` | Install to project scope (current directory only) |
+| `-e, --env <KEY=VALUE>` | Set environment variable for MCP servers (repeatable; nonsensitive only) |
+| `--mcp-instance <KIT:NAME=VALUE>` | Override MCP instance name for a specific kit (repeatable) |
+| `-l, --list` | List available kits without installing |
+| `-y, --yes` | Non-interactive mode, accept defaults |
+| `--dry-run` | Show what would be installed |
+| `--json` | Output results as JSON |
+| `-v, --verbose` | Enable verbose logging |
+| `--debug` | Enable debug logging to `~/.config/agent-kit/debug.log` |
+
+**Note:** In non-interactive mode (`-y`), one of `--global` or `--project` is required.
+
+**Examples:**
+
+```bash
+# Interactive installation (prompts for scope selection)
+npx @hashicorp/kits install example-org/kits
+
+# Install to global scope (user-level)
+npx @hashicorp/kits install example-org/kits --global -y
+
+# Install to project scope (current directory)
+npx @hashicorp/kits install example-org/kits --project -y
+
+# Install to Claude Code only at global scope
+npx @hashicorp/kits install example-org/kits -a claude-code --global
+
+# Install specific kits at project scope
+npx @hashicorp/kits install example-org/kits \
+  -k terraform-development \
+  -k vault-operations \
+  --project
+
+# Override MCP instance name for a specific kit
+npx @hashicorp/kits install example-org/kits \
+  -k terraform-development \
+  --mcp-instance terraform-development:terraform=terraform-prod \
+  --global
+
+# Non-interactive with all options
+npx @hashicorp/kits install example-org/kits \
+  -a claude-code \
+  -k terraform-development \
+  --global \
+  -y
+
+# Install from local directory (for development)
+npx @hashicorp/kits install ./my-kits -a claude-code --project
+```
+
+## Integration Tests (Devcontainer)
+
+The integration suite runs the real CLI against the local `test-kits/` repository using non-interactive JSON output. It is intended to run inside the devcontainer so harness CLIs are available and filesystem isolation is preserved.
+
+```bash
+npm run test:integration
+```
+
+Integration tests are organized by intent under `tests/integration/`:
+- `cli/` for CLI command behavior
+- `primitives/` for primitive-specific scenarios
+- `harnesses/` for harness-specific scenarios
+- `scopes/` for scope-specific scenarios
+- `validators/` for validator binaries (using `test-kits/fixtures/invalid/`)
+
+### Uninstall
+
+Removes installed kits.
+
+```bash
+kits uninstall <kit-name> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-a, --agent <name...>` | Target specific harness(es) |
+| `-g, --global` | Uninstall from global scope |
+| `-p, --project` | Uninstall from project scope |
+| `-y, --yes` | Non-interactive mode |
+| `--json` | Output results as JSON |
+
+**Note:** In non-interactive mode (`-y`), one of `--global` or `--project` is required.
+
+**Examples:**
+
+```bash
+# Interactive uninstall (prompts for scope selection)
+npx @hashicorp/kits uninstall terraform-development
+
+# Uninstall from global scope
+npx @hashicorp/kits uninstall terraform-development --global -y
+
+# Uninstall from project scope
+npx @hashicorp/kits uninstall terraform-development --project -y
+
+# Uninstall from specific harness at global scope
+npx @hashicorp/kits uninstall terraform-development -a claude-code --global -y
+```
+
+### Upgrade
+
+Checks for and applies primitive updates.
+
+```bash
+kits upgrade [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-s, --source <source>` | Kit repository source |
+| `-a, --agent <name...>` | Target specific harness(es) |
+| `-k, --kit <name...>` | Upgrade specific kit(s) only |
+| `-g, --global` | Upgrade global scope installations (required) |
+| `-p, --project` | Upgrade project scope installations (required) |
+| `-c, --check` | Check for updates without installing |
+| `-y, --yes` | Non-interactive mode |
+| `--json` | Output results as JSON |
+
+**Note:** Unlike install, upgrade always requires `--global` or `--project` (no TUI prompt).
+
+**Examples:**
+
+```bash
+# Check for available upgrades at global scope
+npx @hashicorp/kits upgrade --check --global
+
+# Check for available upgrades at project scope
+npx @hashicorp/kits upgrade --check --project
+
+# Interactive upgrade at global scope
+npx @hashicorp/kits upgrade -s example-org/kits --global
+
+# Upgrade all automatically at project scope
+npx @hashicorp/kits upgrade -s example-org/kits --project -y
+
+# Upgrade specific kit at global scope
+npx @hashicorp/kits upgrade \
+  -s example-org/kits \
+  -k terraform-development \
+  --global
+```
+
+### Validate
+
+Validate primitive files in a kit repository. Validators accept either a local path or GitHub shorthand (`org/repo[@ref]`).
+
+```bash
+# Validate an entire repository (all types)
+npx @hashicorp/kits validate ./agent-kits
+
+# Validate commands in a GitHub repo
+npx @hashicorp/kits validate --commands example-org/kits
+
+# Validate skills at a specific ref
+npx @hashicorp/kits validate --skills example-org/kits@v1.2.3
+
+# Validate hook programs in a local path
+npx @hashicorp/kits validate --hooks ./agent-kits
+
+# Validate MCP configs in a local path
+npx @hashicorp/kits validate --mcp ./agent-kits
+
+# Validate kit manifests and kits.json registry
+npx @hashicorp/kits validate --kits ./agent-kits
+```
+
+If you install the package globally, the validate command is available directly:
+
+```bash
+npm install -g @hashicorp/kits
+kits validate example-org/kits
+kits validate --skills example-org/kits@v1.2.3
+kits validate --subagents example-org/kits
+kits validate --hooks ./agent-kits
+kits validate --mcp ./agent-kits
+kits validate --kits ./agent-kits
+```
+
+### List
+
+Lists detected harnesses or installed kits.
+
+```bash
+kits list harnesses             # Show detected AI harnesses
+kits list kits                  # Show installed kits (both scopes)
+kits list kits --global         # Show global scope only
+kits list kits --project        # Show project scope only
+```
+
+When listing kits, results are grouped by scope. Use `--global` or `--project` to filter to a specific scope.
+
+### Info
+
+Shows information about a kit repository or specific kit.
+
+```bash
+kits info <source> [options]
+kits info <source> -k <kit-name>  # Specific kit info
+```
+
+## Supported Harnesses
+
+| Harness | Commands | Skills | Subagents | MCP | Hooks |
+|---------|----------|--------|-----------|-----|-------|
+| Claude Code | Yes | Yes | Yes | Yes | Yes |
+| Codex | Yes | Yes | No | Yes | No |
+| Gemini CLI | Yes | Experimental | Experimental | Yes | Yes |
+| GitHub Copilot | Partial | Yes | Yes | Yes | Limited |
+| OpenCode | Yes | Yes | Yes | Yes | Yes |
+
+## Installation Scopes
+
+Kits can be installed at two scopes:
+
+### Global Scope (`--global`)
+
+Installs to user-level harness directories, making primitives available across all projects.
+
+| Harness | Primitives Directory | Config Location |
+|---------|---------------------|-----------------|
+| Claude Code | `~/.claude/commands/`, `~/.claude/skills/`, `~/.claude/agents/` | `~/.claude/settings.json`, `~/.claude.json` |
+| Codex | `~/.codex/prompts/`, `~/.codex/skills/` | `~/.codex/config.toml` |
+| Gemini CLI | `~/.gemini/commands/`, `~/.gemini/skills/` | `~/.gemini/settings.json` |
+| GitHub Copilot | `~/.copilot/prompts/`, `~/.copilot/skills/`, `~/.copilot/agents/` | `~/.copilot/config.json` |
+| OpenCode | `~/.config/opencode/commands/`, `~/.config/opencode/skills/`, `~/.config/opencode/agents/` | `~/.config/opencode/opencode.json` |
+
+### Project Scope (`--project`)
+
+Installs to repository-level harness directories, making primitives available only within that project. Project-scope installations can be committed to version control for team sharing.
+
+| Harness | Primitives Directory | Config Location |
+|---------|---------------------|-----------------|
+| Claude Code | `.claude/commands/`, `.claude/skills/`, `.claude/agents/` | `.claude/settings.json`, `.mcp.json` |
+| Codex | `.codex/skills/` | `.codex/config.toml` |
+| Gemini CLI | `.gemini/commands/`, `.gemini/skills/` | `.gemini/settings.json` |
+| GitHub Copilot | `.github/skills/`, `.github/agents/` | `.vscode/mcp.json` |
+| OpenCode | `.opencode/commands/`, `.opencode/skills/`, `.opencode/agents/` | `opencode.json` |
+
+### Scope Limitations
+
+Not all primitive types are available at project scope for all harnesses:
+
+| Harness | Commands | Skills | Subagents | MCP | Hooks |
+|---------|----------|--------|-----------|-----|-------|
+| Claude Code | Global + Project | Global + Project | Global + Project | Global + Project | Global + Project |
+| Codex | **Global only** | Global + Project | N/A | **Global only** | N/A |
+| Gemini CLI | Global + Project | Global + Project | Global + Project | Global + Project | Global + Project |
+| GitHub Copilot | Global + Project | Global + Project | Global + Project | Global + Project | Limited |
+| OpenCode | Global + Project | Global + Project | Global + Project | Global + Project | Global + Project |
+
+When a kit requires primitives that cannot be installed at project scope for a given harness, the installer will report this as a compatibility issue and suggest using `--global` instead.
+
+## Source Formats
+
+The installer supports multiple source formats:
+
+```bash
+# GitHub shorthand (org/repo)
+example-org/kits
+
+# GitHub with specific version/branch
+example-org/kits@v1.0.0
+example-org/kits@main
+
+# Local path (for development)
+./my-kits
+/absolute/path/to/kits
+~/path/to/kits
+```
+
+## Primitive Resolution
+
+Kits can reference primitives from a shared primitives library using version specs:
+
+```json
+{
+  "primitives": {
+    "commands": [
+      { "ref": "tf-plan@^1.0.0" },
+      { "ref": "tf-apply@~1.1.0" },
+      { "ref": "tf-validate@latest" }
+    ]
+  }
+}
+```
+
+The installer resolves these references at install time:
+- **SemVer ranges** (`^1.0.0`, `~1.2.0`): Resolved to highest matching version
+- **Exact versions** (`1.2.3`): Must match exactly
+- **`latest` keyword**: Resolved to highest available version
+
+When multiple kits reference the same primitive, the installer deduplicates and selects the highest compatible version.
+
+## Installation Manifest
+
+The installer tracks installations in scope-specific manifest files:
+
+| Scope | Manifest Location |
+|-------|------------------|
+| Global | `~/.agents/manifest.json` |
+| Project | `.agents/manifest.json` |
+
+This enables:
+- Uninstallation of kits
+- Upgrade checking for primitives
+- Conflict detection
+- Scope isolation (global and project installations are tracked separately)
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Installation failed |
+| 2 | Invalid arguments |
+| 3 | Source not found or invalid |
+| 4 | No harnesses detected |
+| 5 | Kit not found |
+| 6 | Kit incompatible with all selected harnesses |
+| 7 | Primitive reference resolution failed |
+| 8 | Manifest read/write error |
+| 9 | No upgrades available |
+| 10 | User cancelled |
+| 11 | Scope required (non-interactive mode without `--global` or `--project`) |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HTTP_PROXY` / `HTTPS_PROXY` | Proxy configuration for network requests |
+
+## Configuration
+
+### Kit Repository Structure
+
+A kit repository should have:
+
+```
+my-kits/
+├── kits.json              # Kit registry (optional, enables multiple kits)
+├── primitives.json        # Shared primitives registry (optional)
+├── primitives/            # Shared primitive definitions
+│   ├── commands/
+│   ├── skills/
+│   └── ...
+└── kits/                  # Individual kit directories
+    ├── terraform-development/
+    │   ├── kit.json       # Kit manifest
+    │   └── primitives/    # Kit-specific primitives
+    └── vault-operations/
+        ├── kit.json
+        └── primitives/
+```
+
+For single-kit repositories, place `kit.json` at the root.
+
+### Kit Manifest (kit.json)
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "name": "terraform-development",
+  "version": "1.0.0",
+  "description": "Terraform development capabilities",
+  "products": ["terraform"],
+  "requires": {
+    "primitives": ["commands", "skills"]
+  },
+  "primitives": {
+    "commands": [
+      { "ref": "tf-plan@^1.0.0" },
+      { "name": "custom-cmd", "entrypoint": "./primitives/commands/custom-cmd.md" }
+    ],
+    "skills": [
+      { "name": "generate-hcl", "entrypoint": "./primitives/skills/generate-hcl" }
+    ]
+  }
+}
+```
+
+### Primitive Formats
+
+**Commands** (Markdown):
+```markdown
+# Command Name
+
+Description of what the command does.
+
+## Usage
+
+Instructions for using the command.
+
+## Examples
+
+Example usage scenarios.
+```
+
+**Skills** (Directory with SKILL.md):
+```
+my-skill/
+├── SKILL.md       # Main skill definition
+└── assets/        # Optional supporting files
+    └── template.hcl
+```
+
+**Subagents** (Markdown with YAML frontmatter):
+```markdown
+---
+name: security-advisor
+description: Reviews Terraform configs for security issues
+model: "{{model:power}}"
+allowedTools:
+  - "{{tool:read}}"
+  - "{{tool:shell}}"
+disallowedTools: "{{tool:write}}"
+skills:
+  - generate-hcl
+hooks:
+  - ref: "pre-apply-validation@^1.0.0"
+    binding:
+      event: "tool.before"
+      matcher:
+        tool: "{{tool:shell}}"
+---
+
+# security-advisor
+
+<agent_role>
+You are a security-focused Terraform advisor...
+</agent_role>
+```
+
+Skill and subagent frontmatter `hooks` are supported by Claude Code only; other harnesses drop them during transformation.
+
+### Model Templates
+
+Skills and subagents can reference canonical model tiers in frontmatter:
+
+```yaml
+model: "{{model:fast}}"
+```
+
+Supported tiers: `fast`, `standard`, `power`, `auto`, `inherit`. Adapters map these to harness-specific model IDs (or omit the field if unsupported).
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm >= 8.0.0
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+### Testing Local Changes
+
+```bash
+# Build and link locally
+npm run build
+npm link
+
+# Test with local kit repository
+kits install ./path/to/local/kits
+
+# Or use directly without linking
+npx ts-node src/cli/index.ts install ./path/to/local/kits
+```
+
+### Project Structure
+
+```
+agent-kit-cli/
+├── src/
+│   ├── cli/           # CLI commands (install, uninstall, upgrade, etc.)
+│   ├── tui/           # Terminal UI components
+│   ├── adapters/      # Harness adapters (claude-code, codex, etc.)
+│   ├── discovery/     # Kit discovery and source fetching
+│   ├── resolution/    # Primitive reference resolution
+│   ├── manifest/      # Installation manifest management
+│   └── core/          # Core types and utilities
+├── tests/             # Test files
+├── schemas/           # JSON schemas
+└── bin/               # CLI entrypoint
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"No harnesses detected"**
+- Ensure at least one supported AI assistant is installed
+- Check that configuration files exist in expected locations
+
+**"Permission denied" errors**
+- Check file permissions on harness configuration directories
+- Ensure the AI assistant is not running during installation
+
+**"Source not found"**
+- Verify the source path or GitHub repository exists
+- Check network connectivity for remote sources
+
+**"Kit incompatible"**
+- The kit requires primitives not supported by the selected harness
+- Choose a compatible harness or different kit
+
+**"Scope required" (exit code 11)**
+- Non-interactive mode (`-y`) requires explicit scope selection
+- Add `--global` for user-level installation or `--project` for current directory
+- Example: `npx @hashicorp/kits install ... --global -y`
+
+**"Scope incompatible" for Codex**
+- Codex commands and MCP servers are global-only
+- Use `--global` to install kits requiring these primitives to Codex
+- Or install to other harnesses that support project scope
+
+### Debug Mode
+
+Enable debug logging for detailed output:
+
+```bash
+npx @hashicorp/kits install example-org/kits --debug
+```
+
+Logs are written to `~/.config/agent-kit/debug.log`.
+
+## License
+
+MPL-2.0

package/bin/kits.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from "../dist/cli/index.js";
+
+run().catch((error) => {
+  console.error("Fatal error:", error.message);
+  process.exit(1);
+});