provisioning/EXTENSION_DEMO.md

# Extension System Demonstration

## Overview

The provisioning system now has a complete extension architecture that allows adding custom providers, task services, and access control without forking the main codebase.

## ✅ What's Working

### 1. Extension Discovery and Loading
- **Project-specific extensions**: `.provisioning/extensions/` (highest priority)
- **User extensions**: `~/.provisioning-extensions/`
- **System-wide extensions**: `/opt/provisioning-extensions/`
- **Environment override**: `$PROVISIONING_EXTENSIONS_PATH`

### 2. Provider Extensions
Created working DigitalOcean provider extension:
```
.provisioning/extensions/providers/digitalocean/
├── manifest.yaml          # Extension metadata
├── nulib/digitalocean/
│   └── servers.nu         # Provider implementation
└── hooks/
    ├── validate-credentials.nu  # Pre-creation validation
    └── notify-created.nu       # Post-creation notification
```

### 3. TaskServ Extensions
Created monitoring task service with multiple profiles:
```
.provisioning/extensions/taskservs/monitoring/
├── manifest.yaml                    # Extension metadata
├── production/install-monitoring.sh # Full monitoring stack
├── staging/install-monitoring.sh    # Lighter configuration
└── development/install-monitoring.sh # Minimal setup
```

### 4. Access Control Profiles
Created three access profiles:
- **cicd.yaml**: Restricted CI/CD permissions
- **developer.yaml**: Moderate restrictions for developers
- **readonly.yaml**: Read-only access for monitoring

### 5. Persistent Registry
- Extensions are cached in `~/.cache/provisioning/extension-registry.json`
- Registry persists between command invocations
- Automatic discovery and registration

## 🎯 Working Commands

### Extension Management
```bash
# Initialize extension registry
./core/nulib/provisioning extensions init

# List all extensions
./core/nulib/provisioning extensions list

# List specific type
./core/nulib/provisioning extensions list --type provider
./core/nulib/provisioning extensions list --type taskserv

# Show extension details
./core/nulib/provisioning extensions show digitalocean
./core/nulib/provisioning extensions show monitoring
```

### Profile Management
```bash
# Show current profile (unrestricted by default)
./core/nulib/provisioning profile show

# Use CI/CD restricted profile
PROVISIONING_PROFILE=cicd ./core/nulib/provisioning profile show

# Use developer profile
PROVISIONING_PROFILE=developer ./core/nulib/provisioning profile show

# Use read-only profile
PROVISIONING_PROFILE=readonly ./core/nulib/provisioning profile show
```

## 📋 Demo Results

### Extension Discovery
```
Available Extensions:

Providers:
╭───┬──────────────┬─────────────────────────────────────╮
│ # │     name     │               path                  │
├───┼──────────────┼─────────────────────────────────────┤
│ 0 │ digitalocean │ .provisioning/extensions/providers/ │
│   │              │ digitalocean                        │
╰───┴──────────────┴─────────────────────────────────────╯

TaskServs:
╭───┬────────────┬───────────────────────────────────────╮
│ # │    name    │                path                   │
├───┼────────────┼───────────────────────────────────────┤
│ 0 │ monitoring │ .provisioning/extensions/taskservs/   │
│   │            │ monitoring                            │
╰───┴────────────┴───────────────────────────────────────╯
```

### Extension Details
DigitalOcean provider includes:
- API token validation
- Multiple regions (nyc1, nyc3, ams3, sgp1, lon1, fra1, tor1, sfo3)
- Multiple server sizes (s-1vcpu-1gb through s-4vcpu-8gb)
- Pre/post creation hooks
- Complete server lifecycle management

Monitoring taskserv includes:
- Three deployment profiles (production, staging, development)
- Prometheus, Grafana, AlertManager stack
- Profile-specific configurations
- Helm-based installation scripts

### Access Control
CI/CD profile restrictions:
- ✅ Allowed: server list, taskserv status, cluster status
- ❌ Blocked: server delete, sops edit, cluster create
- 🎯 Limited to: local/digitalocean providers, max 5 servers

## 🔧 Technical Implementation

### Key Features
1. **Environment Variable Configuration**
   - `PROVISIONING_EXTENSION_MODE`: full, restricted, disabled
   - `PROVISIONING_PROFILE`: Active access control profile
   - `PROVISIONING_EXTENSIONS_PATH`: Custom extension path

2. **File-based Registry Cache**
   - Persistent storage in `~/.cache/provisioning/extension-registry.json`
   - Automatic refresh on `extensions init`
   - Cross-session persistence

3. **Manifest-driven Extensions**
   - YAML manifests with metadata, requirements, permissions
   - Version management and dependency checking
   - Hook system for lifecycle events

4. **Security Model**
   - Profile-based access control
   - Extension allowlist/blocklist
   - Permission system
   - Command filtering

## 🚀 Benefits

1. **No Fork Required**: Extend functionality without modifying core codebase
2. **Flexible Deployment**: Project, user, and system-wide extension support
3. **Secure by Default**: Granular access control for different environments
4. **Easy Management**: Simple CLI commands for extension lifecycle
5. **Persistent State**: Registry survives command invocations

## 📖 Usage Examples

### CI/CD Pipeline Integration
```bash
# Set restricted profile for CI/CD
export PROVISIONING_PROFILE=cicd
export PROVISIONING_EXTENSION_MODE=restricted

# These commands work in CI/CD
provisioning server list          ✅
provisioning taskserv status      ✅

# These commands are blocked
provisioning server delete        ❌
provisioning sops edit secrets    ❌
```

### Developer Workflow
```bash
# Developer can create/delete but limited resources
export PROVISIONING_PROFILE=developer

provisioning server create --region nyc1 --size s-1vcpu-1gb  ✅
provisioning taskserv create monitoring --profile development ✅
```

### Production Safety
```bash
# Read-only access for monitoring agents
export PROVISIONING_PROFILE=readonly

provisioning server list    ✅ (monitoring)
provisioning server delete  ❌ (blocked)
```

This extension system provides unlimited customization while maintaining security and simplicity.