# Extension Registry System

Centralized marketplace for discovering, registering, and managing infrastructure extensions.

## Overview

The `extension-registry` is a distributed system that acts as a package repository for provisioning extensions:

- **Providers**: AWS, UpCloud, Hetzner, Kubernetes, etc.
- **Task Services**: Database managers, load balancers, monitoring deployers, etc.
- **Plugins**: Nushell plugins, custom commands, utilities
- **Clusters**: Web clusters, OCI registries, cache clusters, etc.
- **Custom Extensions**: User-built extensions for specific needs

## Architecture

```text
Public Registry
(provisioning.io/registry)
    ├─ Published extensions
    ├─ Version management
    ├─ Verification & signing
    └─ Download/install

             ↓ (during setup)

Workspace Registry
(local)
    ├─ Registered extensions
    ├─ Installation state
    ├─ Configuration
    └─ Custom extensions

         ↓ (at runtime)

Loaded Extensions
(memory)
    ├─ Providers (AWS, UpCloud, etc.)
    ├─ Task Services (50+ services)
    ├─ Plugins (17 Nushell plugins)
    └─ Clusters (web, oci-registry, etc.)
```

## Extension Types

### 1. Providers (Cloud Adapters)

Interfaces to cloud platforms and infrastructure:

```nickel
{
  extensions = {
    providers = [
      {
        name = "aws",
        version = "1.2.3",
        description = "Amazon Web Services provider",
        capabilities = [
          "compute", "storage", "database", "networking", "kms"
        ],
        resources = [
          "instance", "rds", "s3", "vpc", "security_group"
        ]
      },
      {
        name = "upcloud",
        version = "0.8.1",
        capabilities = ["compute", "storage", "networking"],
        resources = ["server", "storage", "network"]
      }
    ]
  }
}
```

### 2. Task Services (Operations)

Specialized services for infrastructure operations:

```nickel
{
  extensions = {
    task_services = [
      {
        name = "kubernetes-deployer",
        version = "2.1.0",
        operations = [
          "create-deployment",
          "scale-replicas",
          "rolling-update",
          "health-check"
        ]
      },
      {
        name = "postgres-manager",
        version = "1.5.2",
        operations = [
          "create-database",
          "setup-replication",
          "backup",
          "restore"
        ]
      }
    ]
  }
}
```

### 3. Plugins (Nushell Extensions)

Nushell plugins for scripting and automation:

```nickel
{
  extensions = {
    plugins = [
      {
        name = "nu-plugin-tera",
        version = "1.0.0",
        type = "template-engine",
        performance_multiplier = 15
      },
      {
        name = "nu-plugin-nickel",
        version = "0.5.0",
        type = "config-processor",
        performance_multiplier = 8
      }
    ]
  }
}
```

### 4. Clusters (Specialized Infrastructure)

Pre-configured infrastructure clusters:

```nickel
{
  extensions = {
    clusters = [
      {
        name = "web-cluster",
        version = "1.0.0",
        description = "Multi-tier web application infrastructure",
        components = ["load-balancer", "web-servers", "cache", "database"]
      },
      {
        name = "oci-registry-cluster",
        version = "2.0.0",
        description = "Container image registry with HA",
        components = ["registry", "storage", "replication", "auth"]
      }
    ]
  }
}
```

## Discovering Extensions

### Browse Registry

```bash
# List all available extensions
provisioning extension list

# List specific type
provisioning extension list --type provider
provisioning extension list --type task-service
provisioning extension list --type plugin
provisioning extension list --type cluster

# Search for extensions
provisioning extension search --query "database"
provisioning extension search --query "kubernetes" --type task-service

# Get extension details
provisioning extension info --name aws --version latest
provisioning extension info --name postgres-manager --version 1.5.2
```

### Nushell API

```nushell
def search-extensions [--query: string] {
    let results = (
        provisioning extension search \
            --query $query \
            --format json
    )

    $results | each { | ext |
        print $"($ext.name) v($ext.version)"
        print $"  ($ext.description)"
        print $"  Downloads: ($ext.downloads)"
        print $"  Rating: ($ext.rating)/5.0"
        print ""
    }
}

# Usage
search-extensions --query "database"
```

## Installing Extensions

### During Workspace Setup

```bash
# Create workspace with specific extensions
provisioning workspace create \
    --name "production" \
    --extensions [
        "aws:1.2.3",
        "postgres-manager:1.5.2",
        "kubernetes-deployer:2.1.0",
        "nu-plugin-nickel:0.5.0"
    ]
```

### Dynamic Installation

```nushell
def install-extensions [--workspace: string, --extensions: list] {
    $extensions | each { | ext |
        print $"Installing ($ext)..."

        let result = (
            provisioning extension install \
                --workspace $workspace \
                --name $ext
        )

        if $result.success {
            print $"✓ ($ext) installed"
        } else {
            print $"✗ Failed to install ($ext): ($result.error)"
        }
    }
}

# Usage
install-extensions \
    --workspace production \
    --extensions ["aws", "postgres-manager", "kubernetes-deployer"]
```

### Configuration After Installation

```nickel
{
  extensions = {
    registered = [
      {
        name = "aws",
        version = "1.2.3",
        enabled = true,
        config = {
          region = "us-east-1",
          credentials_source = "aws_iam",
          max_parallel_operations = 10
        }
      },
      {
        name = "postgres-manager",
        version = "1.5.2",
        enabled = true,
        config = {
          connection_timeout = 30,
          backup_retention_days = 30
        }
      }
    ]
  }
}
```

## Publishing Extensions

### Package Extension

```bash
# Create extension package
provisioning extension package \
    --name "my-custom-provider" \
    --version "1.0.0" \
    --source-dir "./custom-provider" \
    --output "my-custom-provider-1.0.0.tar.gz"

# Verify package
provisioning extension verify --file "my-custom-provider-1.0.0.tar.gz"
```

### Register in Registry

```bash
# Register extension in public registry
provisioning extension publish \
    --file "my-custom-provider-1.0.0.tar.gz" \
    --name "my-custom-provider" \
    --version "1.0.0" \
    --description "Custom infrastructure provider" \
    --author "Your Organization" \
    --repository " [https://github.com/your-org/my-custom-provider"](https://github.com/your-org/my-custom-provider") \
    --documentation " [https://docs.example.com/my-provider"](https://docs.example.com/my-provider") \
    --license "Apache-2.0"

# Output:
# ✓ Extension published successfully
# Registry URL:  [https://provisioning.io/registry/my-custom-provider](https://provisioning.io/registry/my-custom-provider)
# Installation: provisioning extension install my-custom-provider
```

### Private Registry

```yaml
# ~/.config/provisioning/registry.yaml
registries:
  - name: public
    url:  [https://registry.provisioning.io](https://registry.provisioning.io)
    type: public
    enabled: true

  - name: company-private
    url:  [https://registry.company.internal](https://registry.company.internal)
    type: private
    credentials: ~/.provisioning/registry-creds.json
    enabled: true

  - name: local
    url: file:///opt/provisioning/local-extensions
    type: local
    enabled: true
```

## Extension Lifecycle

### Installation State

```text
Not Installed
    ↓
Available (in registry)
    ↓
Downloaded
    ↓
Verified (signature check)
    ↓
Installed (in workspace)
    ↓
Loaded (in memory)
    ↓
Ready to Use
```

### Version Management

```nushell
def manage-extension-versions [--name: string] {
    # List available versions
    let versions = (
        provisioning extension versions --name $name
    )

    print $"Available versions for ($name):"
    $versions | each { | ver |
        let installed = if $ver.installed { "✓" } else { " " }
        print $"  [$installed] v($ver.version) - released ($ver.release_date)"
    }

    # Upgrade to newer version
    provisioning extension upgrade --name $name --to-version "2.0.0"

    # Downgrade if needed
    provisioning extension downgrade --name $name --to-version "1.5.0"
}
```

### Dependency Resolution

```text
Extension A (v1.0.0)
├─ requires: Extension B >= 2.0.0
├─ requires: Extension C < 3.0.0
└─ requires: Rust runtime >= 1.70

    ↓ (Registry resolves dependencies)

Extension B (v2.1.0) ✓
Extension C (v2.5.0) ✓
Rust (v1.75.0) ✓

All dependencies satisfied
```

## Marketplace Features

### Discovery and Ratings

```bash
# Most downloaded extensions
provisioning extension list --sort downloads --limit 10

# Highly rated extensions
provisioning extension list --sort rating --limit 10

# Recently updated
provisioning extension list --sort updated --limit 10

# Top contributors
provisioning extension authors --sort contributions --limit 10
```

### Verification and Security

```bash
# Verify extension signature
provisioning extension verify \
    --name "aws" \
    --version "1.2.3"

# Check CVE database for dependencies
provisioning extension audit --name "postgres-manager"

# Output:
# ✓ Signature verified (signed by AWS)
# ⚠️  CVE-2024-1234 found in openssl dependency
#    Recommendation: Update to openssl 3.1.4+
```

## Extension Development Workflow

### Create Extension

```bash
# Generate extension scaffold
provisioning extension init \
    --type provider \
    --name my-custom-provider \
    --language rust

# Generated structure:
# my-custom-provider/
# ├── Cargo.toml
# ├── src/
# │   ├── lib.rs
# │   └── provider.rs
# ├── tests/
# ├── docs/
# └── extension.yaml
```

### extension.yaml Manifest

```yaml
name: my-custom-provider
version: 1.0.0
edition: 2021

metadata:
  description: Custom cloud provider for Provisioning
  author: Your Organization
  license: Apache-2.0
  repository:  [https://github.com/your-org/my-provider](https://github.com/your-org/my-provider)
  documentation:  [https://docs.example.com/my-provider](https://docs.example.com/my-provider)

capabilities:
  - compute
  - storage
  - networking

dependencies:
  - name: provisioning-sdk
    version: ">=0.1.0"
  - name: tokio
    version: "1.0"

resources:
  - name: instance
    operations: [create, delete, list, describe]
  - name: storage
    operations: [create, delete, list, describe]

tests:
  integration: true
  unit: true

signing:
  key: your-gpg-key-id
```

### Build and Test

```bash
# Build extension
provisioning extension build --path ./my-custom-provider

# Run tests
provisioning extension test --path ./my-custom-provider

# Integration tests
provisioning extension test --path ./my-custom-provider --integration

# Package for distribution
provisioning extension package --path ./my-custom-provider
```

## Registry API

### REST Endpoints

```bash
# List extensions
curl  [https://registry.provisioning.io/api/v1/extensions](https://registry.provisioning.io/api/v1/extensions)

# Search
curl  [https://registry.provisioning.io/api/v1/extensions?query=database&type=provider](https://registry.provisioning.io/api/v1/extensions?query=database&type=provider)

# Get extension info
curl  [https://registry.provisioning.io/api/v1/extensions/aws/1.2.3](https://registry.provisioning.io/api/v1/extensions/aws/1.2.3)

# Download extension
curl  [https://registry.provisioning.io/api/v1/extensions/aws/1.2.3/download](https://registry.provisioning.io/api/v1/extensions/aws/1.2.3/download) \
    -o aws-1.2.3.tar.gz

# Publish extension (authenticated)
curl -X POST  [https://registry.provisioning.io/api/v1/extensions](https://registry.provisioning.io/api/v1/extensions) \
    -H "Authorization: Bearer $TOKEN" \
    -F "package=@my-extension-1.0.0.tar.gz"
```

## Monitoring and Analytics

```nushell
def extension-analytics [] {
    # Get download statistics
    let stats = (
        provisioning extension analytics \
            --period "last-30-days"
    )

    print "Extension Analytics (Last 30 Days)"
    print "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

    $stats.downloads | sort-by count --reverse | each { | ext |
        print $"($ext.name): ($ext.count) downloads"
    }

    print ""
    print "Installation Success Rate:"
    $stats.success_rate | each { | ext |
        print $"($ext.name): ($ext.success_rate)%"
    }
}
```

## Best Practices

1. **Version Management**: Use semantic versioning (major.minor.patch)
2. **Backward Compatibility**: Maintain compatibility across minor versions
3. **Documentation**: Comprehensive docs for each extension
4. **Testing**: Include unit and integration tests
5. **Signing**: Sign extensions with GPG key for verification
6. **Updates**: Regular updates for security patches
7. **Deprecation**: Clear deprecation path for old versions
8. **Dependencies**: Minimize dependencies, declare all requirements

## Integration with Setup

```nushell
def setup-provisioning [] {
    print "Setting up Provisioning infrastructure..."

    # 1. Load extension registry
    let registry = (provisioning extension registry load)
    print "✓ Registry loaded"

    # 2. Resolve dependencies
    let extensions = [
        "aws:1.2.3",
        "postgres-manager:1.5.2",
        "kubernetes-deployer:2.1.0"
    ]

    let resolved = (
        provisioning extension resolve-dependencies \
            --extensions $extensions
    )

    print $"✓ Dependencies resolved for ($resolved.total) extensions"

    # 3. Download extensions
    $resolved.extensions | each { | ext |
        print $"Downloading ($ext.name) v($ext.version)..."
        provisioning extension download --name $ext.name --version $ext.version
    }

    # 4. Verify extensions
    let verified = (provisioning extension verify-all)
    print $"✓ All ($verified.count) extensions verified"

    # 5. Install extensions
    $extensions | each { | ext |
        provisioning extension install --name $ext
    }

    # 6. Load extensions
    provisioning extension load-all
    print "✓ All extensions loaded and ready"
}
```

## See Also

- [Custom Provider Development](../development/custom-provider-development.md)
- [Custom Task Services](../development/custom-task-services.md)
- [Batch Workflow System](./batch-workflows.md)
- [Platform Installer](./installer-system.md)
