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
```plaintext

### 2. Search for Extensions

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

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

### 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
```plaintext

### 4. Manage Cache

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

# List cached
provisioning ext cache list

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

### 5. Publish an Extension

```bash
# Create extension
mkdir -p my-extension/{nickel,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
```plaintext

## 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
```plaintext

### Test OCI Connection

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

## 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
```plaintext

### 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
```plaintext

### 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
```plaintext

## Extension Structure

Minimal extension:

```plaintext
my-extension/
├── extension.yaml       # Required manifest
└── nickel/                # At least one content dir
    └── my-extension.ncl
```plaintext

Complete extension:

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

## 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
```plaintext

### 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
```plaintext

### Cache Problems

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

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

## 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
```plaintext