HAX SDK

Installation

Install globally via npm:

npm install -g @outshift/hax

Or for development from source:

# Clone the repository
git clone https://github.com/outshift-open/hax.git
cd hax/cli
npm install
npm run build
npm link

Quick Start

Initialize HAX in your project:

hax init

Add components to your project:

hax add artifact form
hax add artifact code-editor data-visualizer

Add Composers (chat features) to your project

hax add composer chat-commands file-upload rules-context
hax add composer chat-commands

List available components:

hax list

Available Components

• form - Dynamic form builder
• timeline - Activity timeline with status indicators
• mindmap - Interactive mindmap with auto-layout
• code-editor - Monaco-based code editor
• details - Statistics and data display component
• data-visualizer - Data visualization wrapper
• source-attribution - Source citation component with clickable reference badges
• rationale - Decision reasoning component with confidence indicators and criteria badges

Available Composers

• chat-commands - Interactive chat interface with command suggestions, file picker, and context management
• file-upload - Complete file upload flow with drag-and-drop, progress indicators, and error handling
• rules-context - Rule configuration and management interface with validation and persistence

Configuration

The CLI creates a hax.json file in your project:

Basic configuration (after hax init):

{
  "$schema": "./schema.json",
  "style": "default",
  "components": [
    "code-editor",
    "data-visualizer",
    "timeline",
    "form",
    "mindmap",
    "details"
  ],
  "features": ["rules-context", "chat-commands", "file-upload"],
  "artifacts": {
    "path": "src/hax/artifacts"
  },
  "composers": {
    "path": "src/hax/composers"
  }
}

Example with multi-repository setup:

{
  "$schema": "./schema.json",
  "style": "default",
  "artifacts": {
    "path": "src/hax/artifacts"
  },
  "components": [],
  "registries": {
    "default": "official",
    "fallback": ["official", "internal", "partner"],
    "sources": {
      "official": {
        "type": "github",
        "repo": "outshift-open/hax",
        "branch": "main",
        "name": "official"
      },
      "internal": {
        "type": "github",
        "repo": "your-org/hax-components",
        "branch": "main",
        "name": "internal"
      },
      "partner": {
        "type": "github",
        "repo": "partner-org/components",
        "branch": "production",
        "name": "partner",

      }
    }
  }

Note: Repository names like internal, partner are example aliases - you can use any name that makes sense for your organization (e.g., dev, staging, company-name, team-ui, etc.)

Configuration Options

• artifacts.path: Where artifact components are installed (default: src/hax/artifacts)
• components: List of installed components (auto-managed)
• composers: List of installed composer components (stored in src/hax/composers)
• style: Component styling variant (default: "default")
• registries.default: Default repository to check first
• registries.fallback: Repository search order for component resolution
• registries.sources: Repository definitions with GitHub details and optional tokens

Component Types

• Artifacts: Individual UI components for specific visualizations and interactions
• Composers: Enhanced chat interface with chat commands (@, +, /), file upload, and rules for agent behavior.
• UI Components: Reusable base components (buttons, inputs, etc.) automatically installed as dependencies

Registry Sources

The CLI supports multiple registry sources:

GitHub Registry (Default)

The CLI uses the public GitHub registry by default. No additional configuration needed:

# Uses public GitHub registry from main branch (default)
HAX_REGISTRY_SOURCE=github:main

Local Registry

# Uses local TypeScript registry files
HAX_REGISTRY_SOURCE=local

Set via environment variable if needed:

# Set environment variable for current session
export HAX_REGISTRY_SOURCE=github:main

# Or run with environment variable
HAX_REGISTRY_SOURCE=github:main hax add artifact form

Multi-Repository Architecture

HAX CLI supports multiple component repositories for organizational flexibility:

Use Cases

• Enterprise Organizations: Maintain internal component libraries alongside official HAX components
• Partner Ecosystems: Access partner organization components while maintaining fallback to official registry
• Development Workflows: Use development branches for testing while falling back to stable releases
• Private Components: Secure proprietary components with authentication tokens

Repository Types

1. Official Repository: Core HAX components (always available)
2. Custom Repositories: Organization-specific components
3. Partner Repositories: External organization components
4. Development Repositories: Testing and development branches

Fallback Chain

Components are resolved using intelligent fallback:

Default Repository → Fallback Repository 1 → Fallback Repository 2 → Official

This ensures:

• ✅ Custom components override official ones when available
• ✅ Graceful degradation when custom repositories are unavailable
• ✅ Consistent experience across different environments
• ✅ Explicit control over component sources with --repo flag

Security & Authentication

• Public Repositories: No authentication required (default)
• Private Repositories: Secure with GitHub tokens (enterprise use)
• Per-Repository Tokens: Different authentication for different repositories
• Environment Variables: Global GitHub token fallback for private repos

Project Structure

• cli/: CLI source code and tooling
  • src/: Main CLI source code
    • commands/: CLI commands (add, init, list)
    • config/: Configuration management
    • generator/: Component installation engine
    • registry/: Component registries
      • default/: Local TypeScript registry
      • github-registry/: GitHub JSON registry
    • types/: TypeScript type definitions
    • utils/: Utility functions
• hax/: HAX component library
  • artifacts/: Available HAX components (form, timeline, etc.)
  • components/ui/: Shared UI components
  • lib/: Utility libraries

How It Works

1. Multi-Repository Registry: Components are defined across multiple repositories with metadata (dependencies, files, types)
2. Intelligent Resolution: CLI searches repositories in priority order with automatic fallback
3. Installation: Downloads component files from resolved repository and installs npm dependencies
4. Path Aliases: Automatically configures TypeScript/JavaScript path mapping
5. Dependencies: Resolves both npm packages and HAX UI component dependencies across repositories

Component Structure

Each HAX component includes:

component-name/
├── component-name.tsx    # Main React component
├── action.ts            # CopilotKit action hook
├── types.ts             # TypeScript definitions
├── index.ts             # Exports
└── description.ts       # Detailed instructions for agents

Commands

init

Initialize HAX in your project:

hax init

add [components...]

Install one or more components:

hax add artifact form timeline

# Install from specific repository
hax add artifact custom-dashboard --repo=testing
hax add artifact salesCustom-timeline --repo=sales

list

Show installed components:

hax list

repo Remote Repository Management & Admin Features

For enterprise setups, multi-repository management, and administrative features, see the Remote Repository Guide.

## Development

### For Contributors

**Working on the CLI code itself:**

1. **Clone and set up the repository**:
   ```bash
   git clone https://github.com/outshift-open/hax.git
   cd hax/cli
   npm install
   ```

2. **For testing with private component repositories** (optional):
   ```bash
   # Create .env file if needed for private repos
   cp .env.example .env
   # Add GITHUB_TOKEN=your_token for private repository access
   ```

**Testing the CLI in other projects:**

The CLI works out-of-the-box with public repositories. For private component repositories, create a `.env` file in your test project.

### Build CLI

```bash
npm run build
```

### Testing

```bash
# Link globally for testing
npm link

# Test commands
hax --help
hax add form
```

### Testing Multi-Repository Functionality

**Setup test repositories:**
```bash
# Initialize project
hax init

# Add test repositories
hax repo add testing --github outshift-open/hax --branch test-remote-repo
hax repo add sales --github outshift-open/hax --branch sales-remote-hax
```

**Test component resolution:**
```bash
# Test automatic fallback
hax add custom-timeline    # Should find in testing
hax add salesCustom-dashboard  # Should find in sales
hax add form              # Should find in official

# Test specific repository targeting
hax add custom-dashboard --repo=testing
hax add mindmap --repo=official
```

**Test repository switching:**
```bash
# Test priority changes
hax repo switch testing
hax add salesCustom-timeline  # Should show "not found in testing, found in sales"

hax repo switch sales
hax add custom-timeline       # Should show "not found in sales, found in testing"

# View current configuration
hax repo list
```

## Troubleshooting

### Common Issues

**"Component not found in registry"**

- Check component name spelling
- Verify internet connection for GitHub registry access
- Try: `hax list` to see available components

**"npm install failed"**

- Check npm configuration
- Verify package names in registry
- Check for conflicting dependencies

**"Path aliases not working"**

- Ensure tsconfig.json/jsconfig.json exists
- Check baseUrl and paths configuration
- Restart TypeScript language server

### File Type System

Components use typed file system:

- `registry:component` - React components (.tsx)
- `registry:hook` - Action hooks (.ts/.tsx)
- `registry:types` - Type definitions (.ts)
- `registry:index` - Export files (.ts)
- `registry:description` - Metadata (.ts)

## License

MIT License - see the [LICENSE](../LICENSE) file for details.