@hivetechs/hive-ai/templates/README.md

Real-time streaming AI consensus platform with HTTP+SSE MCP integration for Claude Code, VS Code, Cursor, and Windsurf - powered by OpenRouter's unified API

# Hive AI Infrastructure-as-Code (IAC) Templates

This directory contains script templates for terminal developers who prefer Infrastructure-as-Code approaches to manage Hive AI configurations.

## Overview

These templates enable DevOps and terminal-focused developers to:
- Manage Hive AI configurations across multiple environments (dev/staging/production)
- Implement configuration validation and deployment pipelines
- Version control configuration changes
- Automate configuration deployments similar to infrastructure management scripts

## Templates

### Configuration Schema
- **`hive-config.schema.yaml`** - Complete configuration schema with environment variable substitution support

### PowerShell Scripts (Windows/Cross-platform)
- **`powershell/deploy-hive-config.ps1`** - Single environment deployment script
- **`powershell/manage-hive-environments.ps1`** - Multi-environment management script

### Bash Scripts (Linux/macOS)
- **`bash/deploy-hive-config.sh`** - Single environment deployment script  
- **`bash/manage-hive-environments.sh`** - Multi-environment management script

## Quick Start

### 1. Create Configuration Files

Create environment-specific configuration files:

```bash
mkdir configs
```

**configs/dev.yaml:**
```yaml
metadata:
  name: "hive-ai-development"
  environment: "development"

license:
  key: "${HIVE_LICENSE_KEY}"

providers:
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"

consensus:
  profile: "Consensus_Speed"
  max_agents: 3
```

**configs/prod.yaml:**
```yaml
metadata:
  name: "hive-ai-production"
  environment: "production"

license:
  key: "${HIVE_LICENSE_KEY}"

providers:
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"

consensus:
  profile: "Consensus_Elite"
  max_agents: 8

backup:
  enabled: true
  locations:
    - path: "/data/backups/hive"
      priority: 1
      free_space_gb: 100
```

### 2. Set Environment Variables

```bash
# Required for all environments
export HIVE_LICENSE_KEY="your-license-key"
export OPENROUTER_API_KEY="your-openrouter-key"

# Additional for production
export PROD_BACKUP_KEY="your-backup-encryption-key"
```

### 3. Deploy Configuration

**PowerShell:**
```powershell
# Single environment
.\templates\powershell\deploy-hive-config.ps1 -Environment "production" -ConfigPath "configs\prod.yaml"

# All environments
.\templates\powershell\manage-hive-environments.ps1 -Action "deploy-all" -ConfigDir "configs"
```

**Bash:**
```bash
# Make scripts executable
chmod +x templates/bash/*.sh

# Single environment
./templates/bash/deploy-hive-config.sh -e production -c configs/prod.yaml

# All environments
./templates/bash/manage-hive-environments.sh deploy-all -d configs
```

## Configuration Management Commands

The templates provide these management capabilities:

### Validation
```bash
# Validate specific configuration
hive config validate configs/prod.yaml

# Validate all environments
./manage-hive-environments.sh validate-all
```

### Deployment
```bash
# Deploy with confirmation
./deploy-hive-config.sh -e production -c configs/prod.yaml

# Deploy without confirmation (CI/CD)
./deploy-hive-config.sh -e production -c configs/prod.yaml --force

# Dry run (show what would be done)
./deploy-hive-config.sh -e production -c configs/prod.yaml --dry-run
```

### Configuration Diff
```bash
# Show differences between file and current config
hive config diff configs/prod.yaml

# Compare specific environment
./manage-hive-environments.sh compare -e production
```

### Export/Backup
```bash
# Export current configuration
hive config export current-config.yaml

# Export all environment configs
./manage-hive-environments.sh export-all
```

## Environment Management

The multi-environment scripts support these predefined environments:

- **development**: `dev.yaml` - Fast consensus, minimal requirements
- **staging**: `staging.yaml` - Balanced configuration for testing  
- **production**: `prod.yaml` - Elite consensus, full backup configuration

### Adding Custom Environments

**PowerShell** (`manage-hive-environments.ps1`):
```powershell
$ENVIRONMENTS = @{
    "custom-env" = @{
        "config" = "custom.yaml"
        "required_vars" = @("HIVE_LICENSE_KEY", "CUSTOM_VAR")
        "optional_vars" = @("DEBUG_MODE")
    }
}
```

**Bash** (`manage-hive-environments.sh`):
```bash
declare -A ENVIRONMENTS=(
    ["custom-env"]="custom.yaml:HIVE_LICENSE_KEY,CUSTOM_VAR:DEBUG_MODE"
)
```

## CI/CD Integration

Example GitHub Actions workflow:

```yaml
name: Deploy Hive AI Configuration
on:
  push:
    branches: [main]
    paths: ['configs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Hive CLI
        run: npm install -g @hive-ai/cli
        
      - name: Deploy to Production
        env:
          HIVE_LICENSE_KEY: ${{ secrets.HIVE_LICENSE_KEY }}
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
        run: |
          chmod +x templates/bash/deploy-hive-config.sh
          ./templates/bash/deploy-hive-config.sh -e production -c configs/prod.yaml --force
```

## Best Practices

1. **Version Control**: Keep configuration files in git for audit trails
2. **Environment Variables**: Use environment variables for secrets, never commit them
3. **Validation**: Always validate configurations before deployment
4. **Backups**: Export configurations before major changes
5. **Testing**: Use staging environments to test configuration changes
6. **Monitoring**: Check logs after deployments for any issues

## Customization

These templates are designed to be modified for your specific needs:

- Add custom validation rules
- Implement rollback mechanisms  
- Add notification systems (Slack, email)
- Integrate with monitoring tools
- Add custom environment-specific logic

## Troubleshooting

**Common Issues:**

- **Missing environment variables**: Check required vars for each environment
- **Permission errors**: Ensure scripts are executable (`chmod +x`)
- **Config validation fails**: Use `hive config validate` to see specific errors
- **CLI not found**: Ensure Hive CLI is installed and in PATH

**Logs:**

All scripts generate detailed logs:
- PowerShell: `hive-deployment-YYYYMMDD-HHMMSS.log`
- Bash: `hive-deployment-YYYYMMDD-HHMMSS.log`