# Scripts\n\nNushell orchestration scripts for configuration workflow automation (NuShell 0.109+).\n\n## Purpose\n\nScripts provide:\n- **Interactive configuration wizard** - TypeDialog with nickel-roundtrip\n- **Configuration generation** - Nickel → TOML export\n- **Validation** - Nickel typecheck and constraint validation\n- **Deployment** - Docker Compose, Kubernetes, service installation\n\n## Script Organization\n\n```\nscripts/\n├── README.md                           # This file\n├── configure.nu                        # Interactive TypeDialog wizard\n├── generate-configs.nu                 # Nickel → TOML export\n├── validate-config.nu                  # Nickel typecheck\n├── render-docker-compose.nu            # Docker Compose generation\n├── render-kubernetes.nu                # Kubernetes manifests generation\n├── install-services.nu                 # Deploy platform services\n└── detect-services.nu                  # Auto-detect running services\n```\n\n## Scripts (Planned Implementation)\n\n### configure.nu\nInteractive configuration wizard using TypeDialog nickel-roundtrip:\n\n```\nnu provisioning/.typedialog/platform/scripts/configure.nu orchestrator solo --backend web\n```\n\nWorkflow:\n1. Loads existing config (if exists) as defaults\n2. Launches TypeDialog form (web/tui/cli)\n3. Shows form with validated constraints\n4. User edits configuration\n5. Generates updated Nickel config to `provisioning/schemas/platform/values/orchestrator.solo.ncl`\n\nUsage:\n```\nnu scripts/configure.nu [service] [mode] --backend [web|tui|cli]\n  service: orchestrator | control-center | mcp-server | vault-service | extension-registry | rag | ai-service | provisioning-daemon\n  mode: solo | multiuser | cicd | enterprise\n  backend: web (default) | tui | cli\n```\n\n### generate-configs.nu\nExport Nickel configuration to TOML:\n\n```\nnu provisioning/.typedialog/platform/scripts/generate-configs.nu orchestrator solo\n```\n\nWorkflow:\n1. Validates Nickel config (typecheck)\n2. Exports to TOML format\n3. Saves to `provisioning/config/runtime/generated/{service}.{mode}.toml`\n\nUsage:\n```\nnu scripts/generate-configs.nu [service] [mode]\n  service: orchestrator | control-center | mcp-server | vault-service | extension-registry | rag | ai-service | provisioning-daemon\n  mode: solo | multiuser | cicd | enterprise\n```\n\n### validate-config.nu\nTypecheck Nickel configuration:\n\n```\nnu provisioning/.typedialog/platform/scripts/validate-config.nu provisioning/schemas/platform/values/orchestrator.solo.ncl\n```\n\nWorkflow:\n1. Runs nickel typecheck\n2. Reports errors (schema violations, constraint errors)\n3. Exits with status\n\nUsage:\n```\nnu scripts/validate-config.nu [config_path]\n  config_path: Path to Nickel config file\n```\n\n### render-docker-compose.nu\nGenerate Docker Compose files from Nickel templates:\n\n```\nnu provisioning/.typedialog/platform/scripts/render-docker-compose.nu solo\n```\n\nWorkflow:\n1. Evaluates Nickel template\n2. Exports to JSON\n3. Converts to YAML (via yq)\n4. Saves to `provisioning/platform/infrastructure/docker/docker-compose.{mode}.yml`\n\nUsage:\n```\nnu scripts/render-docker-compose.nu [mode]\n  mode: solo | multiuser | cicd | enterprise\n```\n\n### render-kubernetes.nu\nGenerate Kubernetes manifests:\n\n```\nnu scripts/render-kubernetes.nu solo\n```\n\nWorkflow:\n1. Evaluates Nickel templates\n2. Exports to JSON\n3. Converts to YAML\n4. Saves to `provisioning/platform/infrastructure/kubernetes/`\n\n### install-services.nu\nDeploy platform services:\n\n```\nnu scripts/install-services.nu solo --backend docker\n```\n\nWorkflow:\n1. Generates all configs for mode\n2. Renders deployment manifests\n3. Deploys services (Docker Compose or Kubernetes)\n4. Verifies service startup\n\n### detect-services.nu\nAuto-detect running services:\n\n```\nnu scripts/detect-services.nu\n```\n\nOutputs:\n- Running service list\n- Detected mode\n- Port usage\n- Container/pod status\n\n## Common Workflow\n\n```\n# 1. Configure service\nnu scripts/configure.nu orchestrator solo\n\n# 2. Validate configuration\nnu scripts/validate-config.nu provisioning/schemas/platform/values/orchestrator.solo.ncl\n\n# 3. Generate TOML\nnu scripts/generate-configs.nu orchestrator solo\n\n# 4. Review generated config\ncat provisioning/config/runtime/generated/orchestrator.solo.toml\n\n# 5. Render Docker Compose\nnu scripts/render-docker-compose.nu solo\n\n# 6. Deploy services\nnu scripts/install-services.nu solo --backend docker\n\n# 7. Verify running services\nnu scripts/detect-services.nu\n```\n\n## Guidelines\n\nAll scripts follow @.claude/guidelines/nushell.md (NuShell 0.109+):\n\n- **Explicit type signatures** - Function parameters with type annotations\n- **Colon notation** - Use `:` before input type, `->` before output type\n- **Error handling** - Use `do { } | complete` pattern (not try-catch)\n- **Pipeline operations** - Chain operations, avoid nested calls\n- **No mutable variables** - Use reduce/recursion instead\n- **External commands** - Use `^` prefix (`^nickel`, `^docker`, etc.)\n\nExample:\n```\nexport def main [\n    service: string,  # Type annotation\n    mode: string\n]: nothing -> nothing {  # Input/output types\n    let result = do {\n        ^nickel typecheck $config_path\n    } | complete\n\n    if $result.exit_code == 0 {\n        print "✅ Validation passed"\n    } else {\n        print $"❌ Validation failed: ($result.stderr)"\n        exit 1\n    }\n}\n```\n\n## Error Handling Pattern\n\nAll scripts use `do { } | complete` for error handling:\n\n```\nlet result = do {\n    ^some-command --flag value\n} | complete\n\nif $result.exit_code != 0 {\n    error make {\n        msg: $"Command failed: ($result.stderr)"\n    }\n}\n```\n\n**Never use try-catch** (not supported in 0.109+).\n\n## Script Dependencies\n\nAll scripts assume:\n- **NuShell 0.109+** - Modern shell\n- **Nickel** (0.10+) - Configuration language\n- **TypeDialog** - Interactive forms\n- **Docker** or **kubectl** - Deployment backends\n- **yq** - YAML/JSON conversion\n- **jq** - JSON processing\n\n## Testing Scripts\n\n```\n# Validate Nushell syntax\nnu --version  # Verify 0.109+\n\n# Test script execution\nnu scripts/validate-config.nu values/orchestrator.solo.ncl\n\n# Check script compliance\ngrep -r "try\|panic\|todo" scripts/  # Should be empty\n```\n\n## Adding a New Script\n\n1. **Create script file** (`scripts/{name}.nu`)\n2. **Add @.claude/guidelines/nushell.md** compliance\n3. **Define main function** with type signatures\n4. **Use do { } | complete** for error handling\n5. **Test execution**: `nu scripts/{name}.nu`\n6. **Verify**: No try-catch, no mutable vars, no panic\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-01-05\n**Guideline**: @.claude/guidelines/nushell.md (NuShell 0.109+)
