prvng_core/nulib/lib_provisioning/extensions/QUICKSTART.md

# Extension System Quick Start Guide

Get started with the Extension Loading System in 5 minutes.

## Prerequisites

1. **OCI Registry** (optional, for OCI features):
   ```bash
   # Start local registry
   docker run -d -p 5000:5000 --name registry registry:2
   ```

2. **Nushell 0.107+**:
   ```bash
   nu --version
   ```

## Quick Start

### 1. Load an Extension

```bash
# Load latest from auto-detected source
provisioning ext load kubernetes

# Load specific version
provisioning ext load kubernetes --version 1.28.0

# Load from specific source
provisioning ext load redis --source oci
```

### 2. Search for Extensions

```bash
# Search all sources
provisioning ext search kube

# Search OCI registry
provisioning ext search postgres --source oci
```

### 3. List Available Extensions

```bash
# List all
provisioning ext list

# Filter by type
provisioning ext list --type taskserv

# JSON format
provisioning ext list --format json
```

### 4. Manage Cache

```bash
# Show cache stats
provisioning ext cache stats

# List cached
provisioning ext cache list

# Clear cache
provisioning ext cache clear --all
```

### 5. Publish an Extension

```bash
# Create extension
mkdir -p my-extension/{kcl,scripts}

# Create manifest
cat > my-extension/extension.yaml <<EOF
extension:
  name: my-extension
  version: 1.0.0
  type: taskserv
  description: My awesome extension
EOF

# Publish to OCI
provisioning ext publish ./my-extension --version 1.0.0
```

## Configuration

### Enable OCI Registry

Edit `workspace/config/local-overrides.toml`:

```toml
[oci]
registry = "localhost:5000"
namespace = "provisioning-extensions"
auth_token_path = "~/.provisioning/oci-token"

[extensions]
source_type = "auto"  # auto, oci, gitea, local
```

### Test OCI Connection

```bash
provisioning ext test-oci
```

## Common Workflows

### Workflow 1: Install Taskserv from OCI

```bash
# Search for taskserv
provisioning ext search kubernetes --source oci

# Load it
provisioning ext load kubernetes --version ^1.28.0

# Use in provisioning
provisioning taskserv create kubernetes
```

### Workflow 2: Develop and Test Locally

```bash
# Copy to local path
cp -r my-extension ~/.provisioning-extensions/taskservs/

# Load locally
provisioning ext load my-extension --source local

# Test
provisioning taskserv create my-extension --check

# Publish when ready
provisioning ext publish ./my-extension --version 1.0.0
```

### Workflow 3: Offline Usage

```bash
# Pull extensions to cache while online
provisioning ext pull kubernetes --version 1.28.0
provisioning ext pull redis --version 7.0.0
provisioning ext pull postgres --version 15.0.0

# Work offline - uses cache
provisioning ext load kubernetes
provisioning ext load redis
```

## Extension Structure

Minimal extension:

```
my-extension/
├── extension.yaml       # Required manifest
└── kcl/                # At least one content dir
    └── my-extension.k
```

Complete extension:

```
my-extension/
├── extension.yaml       # Manifest
├── kcl/                # KCL schemas
│   ├── my-extension.k
│   └── kcl.mod
├── scripts/            # Installation scripts
│   ├── install.nu
│   └── uninstall.nu
├── templates/          # Config templates
│   └── config.yaml.j2
└── docs/              # Documentation
    └── README.md
```

## Troubleshooting

### Extension Not Found

```bash
# Discover available extensions
provisioning ext discover

# Search by name
provisioning ext search <name>

# Check specific source
provisioning ext list --source oci
```

### OCI Registry Issues

```bash
# Test connection
provisioning ext test-oci

# Check registry is running
curl http://localhost:5000/v2/

# View OCI config
provisioning env | grep OCI
```

### Cache Problems

```bash
# Clear and rebuild
provisioning ext cache clear --all

# Pull fresh copy
provisioning ext pull <name> --force
```

## Next Steps

- Read full documentation: `README.md`
- Explore test suite: `tests/run_all_tests.nu`
- Check implementation summary: `EXTENSION_LOADER_IMPLEMENTATION_SUMMARY.md`

## Help

```bash
# Extension commands help
provisioning ext --help

# Cache commands help
provisioning ext cache --help

# Publish help
nu provisioning/tools/publish_extension.nu --help
```