npm package: @outshift/hax
Description: A human-AI experience CLI tool for installing composable building blocks for rich, agentic user experiences.
Author: Outshift by Cisco
Latest version: 1.0.6

# HAX SDK

<p align="center">
A human-AI experience CLI tool for installing composable building blocks for rich, agentic user experiences.
</p>

## Installation

Install globally via npm:

```bash
npm install -g @outshift/hax
```

Or for development from source:

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

```bash
hax init
```

Add components to your project:

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

Add Composers (chat features) to your project

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

```

List available components:

```bash
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`):**

```json
{
  "$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:**

```json
{
  "$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:

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

### Local Registry

```bash
# Uses local TypeScript registry files
HAX_REGISTRY_SOURCE=local
```

Set via environment variable if needed:

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

```bash
hax init
```

### `add [components...]`

Install one or more components:

```bash
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:

```bash
hax list
```

## `repo` Remote Repository Management & Admin Features

For enterprise setups, multi-repository management, and administrative features, see the [Remote Repository Guide](REMOTE_REPOSITORY_GUIDE.md).

````

## 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.
````