# Scripts

Nushell orchestration scripts for configuration workflow automation (NuShell 0.109+).

## Purpose

Scripts provide:
- **Interactive configuration wizard** - TypeDialog with nickel-roundtrip
- **Configuration generation** - Nickel → TOML export
- **Validation** - Nickel typecheck and constraint validation
- **Deployment** - Docker Compose, Kubernetes, service installation

## Script Organization

```toml
scripts/
├── README.md                           # This file
├── configure.nu                        # Interactive TypeDialog wizard
├── generate-configs.nu                 # Nickel → TOML export
├── validate-config.nu                  # Nickel typecheck
├── render-docker-compose.nu            # Docker Compose generation
├── render-kubernetes.nu                # Kubernetes manifests generation
├── install-services.nu                 # Deploy platform services
└── detect-services.nu                  # Auto-detect running services
```

## Scripts (Planned Implementation)

### configure.nu
Interactive configuration wizard using TypeDialog nickel-roundtrip:

```nickel
nu provisioning/.typedialog/platform/scripts/configure.nu orchestrator solo --backend web
```

Workflow:
1. Loads existing config (if exists) as defaults
2. Launches TypeDialog form (web/tui/cli)
3. Shows form with validated constraints
4. User edits configuration
5. Generates updated Nickel config to `provisioning/schemas/platform/values/orchestrator.solo.ncl`

Usage:
```nickel
nu scripts/configure.nu [service] [mode] --backend [web|tui|cli]
  service: orchestrator | control-center | mcp-server | vault-service | extension-registry | rag | ai-service | provisioning-daemon
  mode: solo | multiuser | cicd | enterprise
  backend: web (default) | tui | cli
```

### generate-configs.nu
Export Nickel configuration to TOML:

```nickel
nu provisioning/.typedialog/platform/scripts/generate-configs.nu orchestrator solo
```

Workflow:
1. Validates Nickel config (typecheck)
2. Exports to TOML format
3. Saves to `provisioning/config/runtime/generated/{service}.{mode}.toml`

Usage:
```toml
nu scripts/generate-configs.nu [service] [mode]
  service: orchestrator | control-center | mcp-server | vault-service | extension-registry | rag | ai-service | provisioning-daemon
  mode: solo | multiuser | cicd | enterprise
```

### validate-config.nu
Typecheck Nickel configuration:

```nickel
nu provisioning/.typedialog/platform/scripts/validate-config.nu provisioning/schemas/platform/values/orchestrator.solo.ncl
```

Workflow:
1. Runs nickel typecheck
2. Reports errors (schema violations, constraint errors)
3. Exits with status

Usage:
```toml
nu scripts/validate-config.nu [config_path]
  config_path: Path to Nickel config file
```

### render-docker-compose.nu
Generate Docker Compose files from Nickel templates:

```nickel
nu provisioning/.typedialog/platform/scripts/render-docker-compose.nu solo
```

Workflow:
1. Evaluates Nickel template
2. Exports to JSON
3. Converts to YAML (via yq)
4. Saves to `provisioning/platform/infrastructure/docker/docker-compose.{mode}.yml`

Usage:
```yaml
nu scripts/render-docker-compose.nu [mode]
  mode: solo | multiuser | cicd | enterprise
```

### render-kubernetes.nu
Generate Kubernetes manifests:

```nushell
nu scripts/render-kubernetes.nu solo
```

Workflow:
1. Evaluates Nickel templates
2. Exports to JSON
3. Converts to YAML
4. Saves to `provisioning/platform/infrastructure/kubernetes/`

### install-services.nu
Deploy platform services:

```nushell
nu scripts/install-services.nu solo --backend docker
```

Workflow:
1. Generates all configs for mode
2. Renders deployment manifests
3. Deploys services (Docker Compose or Kubernetes)
4. Verifies service startup

### detect-services.nu
Auto-detect running services:

```nushell
nu scripts/detect-services.nu
```

Outputs:
- Running service list
- Detected mode
- Port usage
- Container/pod status

## Common Workflow

```toml
# 1. Configure service
nu scripts/configure.nu orchestrator solo

# 2. Validate configuration
nu scripts/validate-config.nu provisioning/schemas/platform/values/orchestrator.solo.ncl

# 3. Generate TOML
nu scripts/generate-configs.nu orchestrator solo

# 4. Review generated config
cat provisioning/config/runtime/generated/orchestrator.solo.toml

# 5. Render Docker Compose
nu scripts/render-docker-compose.nu solo

# 6. Deploy services
nu scripts/install-services.nu solo --backend docker

# 7. Verify running services
nu scripts/detect-services.nu
```

## Guidelines

All scripts follow @.claude/guidelines/nushell.md (NuShell 0.109+):

- **Explicit type signatures** - Function parameters with type annotations
- **Colon notation** - Use `:` before input type, `->` before output type
- **Error handling** - Use `do { } | complete` pattern (not try-catch)
- **Pipeline operations** - Chain operations, avoid nested calls
- **No mutable variables** - Use reduce/recursion instead
- **External commands** - Use `^` prefix (`^nickel`, `^docker`, etc.)

Example:
```javascript
export def main [
    service: string,  # Type annotation
    mode: string
]: nothing -> nothing {  # Input/output types
    let result = do {
        ^nickel typecheck $config_path
    } | complete

    if $result.exit_code == 0 {
        print "✅ Validation passed"
    } else {
        print $"❌ Validation failed: ($result.stderr)"
        exit 1
    }
}
```

## Error Handling Pattern

All scripts use `do { } | complete` for error handling:

```javascript
let result = do {
    ^some-command --flag value
} | complete

if $result.exit_code != 0 {
    error make {
        msg: $"Command failed: ($result.stderr)"
    }
}
```

**Never use try-catch** (not supported in 0.109+).

## Script Dependencies

All scripts assume:
- **NuShell 0.109+** - Modern shell
- **Nickel** (0.10+) - Configuration language
- **TypeDialog** - Interactive forms
- **Docker** or **kubectl** - Deployment backends
- **yq** - YAML/JSON conversion
- **jq** - JSON processing

## Testing Scripts

```toml
# Validate Nushell syntax
nu --version  # Verify 0.109+

# Test script execution
nu scripts/validate-config.nu values/orchestrator.solo.ncl

# Check script compliance
grep -r "try\|panic\|todo" scripts/  # Should be empty
```

## Adding a New Script

1. **Create script file** (`scripts/{name}.nu`)
2. **Add @.claude/guidelines/nushell.md** compliance
3. **Define main function** with type signatures
4. **Use do { } | complete** for error handling
5. **Test execution**: `nu scripts/{name}.nu`
6. **Verify**: No try-catch, no mutable vars, no panic

---

**Version**: 1.0.0
**Last Updated**: 2025-01-05
**Guideline**: @.claude/guidelines/nushell.md (NuShell 0.109+)
