OpenAgentsControl/plugins/claude-code/scripts

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

# 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

# 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:

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.