f84f32b7b3
- Fix critical bugs: coder-agent name (CoderAgent→coder-agent), manifest path in session-start.sh, /oac:setup ghost command replaced with /install-context - Fix hooks.json: add timeout/async, add description, restore matcher - Fix session-start.sh: dual-format output (Claude Code + Cursor/OpenCode), remove invalid JSON escapes for $ and backtick - Fix agent spec compliance: disallowedTools on read-only agents, WebFetch on external-scout, haiku model on context-scout, example blocks on 3 agents - Fix skill descriptions: triggering conditions only (no workflow summaries) per superpowers empirical testing — prevents Claude shortcutting skill content - Add Red Flags + Rationalization tables to 4 discipline skills - Add install-context skill + command replacing oac-setup/oac-plan/oac-add-context - Add cleanup-tmp.sh (was missing, broke /oac:cleanup) - Add TypeScript installer (install-context.ts/js) with profile-based download - Update plugin.json: keywords, homepage for marketplace discoverability - Update README: correct skill count, fix structure diagram, remove stale refs - Remove obsolete files: FIRST-TIME-SETUP.md, INSTALL.md, QUICK-START.md, download-context.sh, verify-context.sh, load-config.sh, context-manager skill, oac-setup/oac-plan/oac-add-context commands
186 lines
4.8 KiB
Markdown
186 lines
4.8 KiB
Markdown
# Context Installer Scripts
|
||
|
||
TypeScript implementation of the context installer for the Claude Code plugin.
|
||
|
||
## Overview
|
||
|
||
This directory contains a TypeScript-based context installer that downloads context files from the OpenAgents Control repository using git sparse-checkout.
|
||
|
||
## Files
|
||
|
||
### Core Implementation
|
||
|
||
- **`install-context.ts`** - Main installer script with CLI interface
|
||
- **`test-install.ts`** - Test script for verifying installation against real GitHub repository
|
||
|
||
### Type Definitions
|
||
|
||
- **`types/registry.ts`** - Registry schema and types (with Zod validation)
|
||
- **`types/manifest.ts`** - Manifest schema and types
|
||
|
||
### Utilities
|
||
|
||
- **`utils/registry-fetcher.ts`** - Fetch and parse registry.json from GitHub
|
||
- **`utils/git-sparse.ts`** - Git sparse-checkout operations
|
||
|
||
## Usage
|
||
|
||
### Install Context
|
||
|
||
```bash
|
||
# Install essential profile (default)
|
||
bun run plugins/claude-code/scripts/install-context.ts
|
||
|
||
# Install specific profile
|
||
bun run plugins/claude-code/scripts/install-context.ts --profile=standard
|
||
|
||
# Install specific components
|
||
bun run plugins/claude-code/scripts/install-context.ts --component=core-standards --component=openagents-repo
|
||
|
||
# Dry run (see what would be installed)
|
||
bun run plugins/claude-code/scripts/install-context.ts --profile=extended --dry-run
|
||
|
||
# Force reinstall with verbose output
|
||
bun run plugins/claude-code/scripts/install-context.ts --force --verbose
|
||
```
|
||
|
||
### Run Tests
|
||
|
||
```bash
|
||
# Run test suite
|
||
bun run plugins/claude-code/scripts/test-install.ts
|
||
```
|
||
|
||
## Profiles
|
||
|
||
- **essential** - Minimal components for basic functionality
|
||
- **standard** - Standard components for typical use
|
||
- **extended** - Extended components for advanced features
|
||
- **specialized** - Specialized components for specific domains
|
||
- **all** - All available context
|
||
|
||
## Features
|
||
|
||
✅ Fetch registry.json from GitHub
|
||
✅ Parse and validate with Zod
|
||
✅ Filter context components by profile
|
||
✅ Download using git sparse-checkout
|
||
✅ Create manifest tracking installation
|
||
✅ Handle errors gracefully
|
||
✅ Dry run mode
|
||
✅ Verbose logging
|
||
✅ Force reinstall option
|
||
|
||
## Architecture
|
||
|
||
### Registry Fetching
|
||
|
||
The `registry-fetcher` utility:
|
||
1. Fetches registry.json from GitHub raw URL
|
||
2. Validates structure with Zod schema
|
||
3. Filters components by profile or custom IDs
|
||
4. Extracts unique directory paths for sparse checkout
|
||
|
||
### Git Sparse Checkout
|
||
|
||
The `git-sparse` utility:
|
||
1. Clones repository with `--filter=blob:none --sparse`
|
||
2. Configures sparse-checkout for specific paths
|
||
3. Copies files to target directory
|
||
4. Cleans up temporary files
|
||
|
||
### Manifest Creation
|
||
|
||
The installer creates a `.context-manifest.json` file tracking:
|
||
- Installation profile
|
||
- Source repository and commit SHA
|
||
- Downloaded components with local paths
|
||
- Installation timestamp
|
||
|
||
## Testing
|
||
|
||
The test script (`test-install.ts`) verifies:
|
||
|
||
1. **Registry Fetch** - Fetches from real GitHub repository
|
||
2. **Profile Filtering** - Filters components by profile
|
||
3. **Dry Run** - Simulates installation without downloading
|
||
|
||
To test actual installation, uncomment Test 4 in `test-install.ts`.
|
||
|
||
## Example Output
|
||
|
||
```
|
||
Context Installer
|
||
========================
|
||
|
||
ℹ Profile: essential
|
||
ℹ Repository: darrenhinde/OpenAgentsControl
|
||
ℹ Branch: main
|
||
ℹ Dry run: false
|
||
|
||
ℹ Fetching registry from GitHub...
|
||
✓ Registry version: 2.0.0
|
||
✓ Context components available: 150
|
||
|
||
ℹ Filtering by profile: essential
|
||
✓ Selected 12 components
|
||
|
||
ℹ Downloading context files...
|
||
✓ Files downloaded successfully
|
||
|
||
ℹ Copying files to context directory...
|
||
✓ Files copied to: /path/to/context
|
||
|
||
ℹ Creating manifest...
|
||
✓ Manifest created: .context-manifest.json
|
||
|
||
ℹ Verifying installation...
|
||
✓ Installation complete!
|
||
ℹ Files verified: 12/12
|
||
```
|
||
|
||
## Error Handling
|
||
|
||
The installer handles:
|
||
- Network failures (GitHub unavailable)
|
||
- Invalid registry structure
|
||
- Git command failures
|
||
- Missing dependencies (git not installed)
|
||
- File system errors
|
||
|
||
All errors are logged with clear messages and the installer exits with appropriate exit codes.
|
||
|
||
## Dependencies
|
||
|
||
- **Bun** - Runtime and package manager
|
||
- **Zod** - Schema validation
|
||
- **Git** - Sparse checkout operations
|
||
|
||
## Development
|
||
|
||
### Type Safety
|
||
|
||
All types are defined in `types/` directory with Zod schemas for runtime validation.
|
||
|
||
### Testing
|
||
|
||
Run tests before committing changes:
|
||
|
||
```bash
|
||
bun run plugins/claude-code/scripts/test-install.ts
|
||
```
|
||
|
||
### Adding New Profiles
|
||
|
||
To add a new profile, update the `Profile` type in `types/registry.ts` and the profile mapping in `utils/registry-fetcher.ts`.
|
||
|
||
## Migration from JavaScript
|
||
|
||
This TypeScript implementation replaces the original `install-context.js` with:
|
||
- Type safety with TypeScript and Zod
|
||
- Better error handling
|
||
- Modular architecture
|
||
- Comprehensive testing
|
||
- Improved documentation
|
||
|
||
The JavaScript version is kept for backward compatibility but the TypeScript version is recommended for new installations.
|