Skip to content

README.md

Latest commit

 

History

History
417 lines (306 loc) · 10.6 KB

README.md

File metadata and controls

417 lines (306 loc) · 10.6 KB

HAX SDK

HAX SDK

A human-AI experience CLI tool for installing composable building blocks for rich, agentic user experiences.

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.