provisioning-catalog/providers/demo

Demo Provider

Purpose: Reference implementation for the 4-Task Completion Framework

This provider demonstrates all requirements of the cloud provider development guide:

Framework Completeness

✅ Tarea 1: Nushell Compliance

• Modern error handling with do/complete pattern
• No mutable state (let mut)
• No deprecated try-catch blocks
• Complete implementations (no stubs)

Files: nulib/demo/api.nu, nulib/demo/servers.nu

✅ Tarea 2: Test Infrastructure

• 14 unit tests (tests/unit/test_utils.nu)
• 37 integration tests across 3 modules:
  • tests/integration/test_api_client.nu (13 tests)
  • tests/integration/test_server_lifecycle.nu (12 tests)
  • tests/integration/test_pricing_cache.nu (12 tests)
• Mock API responses (tests/mocks/mock_api_responses.json)
• Test orchestrator (tests/run_demo_tests.nu)

✅ Tarea 3: Runtime Templates

• templates/demo_servers.j2 - Server provisioning
• templates/demo_networks.j2 - Network provisioning
• templates/demo_volumes.j2 - Volume provisioning

All templates use Jinja2 + Bash with proper error handling.

✅ Tarea 4: Nickel Schema Validation

• nickel/contracts.ncl - Type definitions
• nickel/defaults.ncl - Default values
• nickel/main.ncl - Public API
• nickel/version.ncl - Version tracking

All files pass nickel typecheck.

Running the Framework

Validate Completeness

cd provisioning/extensions/providers/demo

# Tarea 4: Nickel validation
nickel typecheck nickel/main.ncl
nickel typecheck nickel/contracts.ncl
nickel typecheck nickel/defaults.ncl
nickel typecheck nickel/version.ncl
nickel export nickel/main.ncl

# Tarea 1: Nushell compliance
[ $(grep -r "try {" nulib/ 2>/dev/null | wc -l) -eq 0 ] && echo "✓ No deprecated patterns"
[ $(grep -r "let mut " nulib/ 2>/dev/null | wc -l) -eq 0 ] && echo "✓ No mutable state"

# Tarea 3: Template validation
for f in templates/*.j2; do
    bash -n <(sed 's/{%.*%}//' "$f" | sed 's/{{.*}}/x/g')
done && echo "✓ Templates valid"

# Tarea 2: Run all tests
nu tests/run_demo_tests.nu

Expected Output

✅ ALL TESTS PASSED
Total: 51 passed, 0 failed (51 total)
Execution Time: 2s

Module Organization

demo/
├── nulib/demo/
│   ├── api.nu         - API client and mock operations
│   ├── servers.nu     - Server management
│   └── mod.nu         - Module aggregator
├── tests/
│   ├── mocks/
│   │   └── mock_api_responses.json
│   ├── unit/
│   │   └── test_utils.nu
│   ├── integration/
│   │   ├── test_api_client.nu
│   │   ├── test_server_lifecycle.nu
│   │   └── test_pricing_cache.nu
│   └── run_demo_tests.nu
├── templates/
│   ├── demo_servers.j2
│   ├── demo_networks.j2
│   └── demo_volumes.j2
├── nickel/
│   ├── contracts.ncl
│   ├── defaults.ncl
│   ├── main.ncl
│   └── version.ncl
└── README.md

Nushell Guidelines Applied

• Rule 1: Module system with proper imports
• Rule 2: Function signatures with type annotations
• Rule 3: Return early, fail fast (precondition validation)
• Rule 4: Modern error handling (do/complete pattern)
• Rule 5: Atomic operations
• Rule 12: Structured error returns

Nickel Guidelines Applied

• Three-File Pattern: contracts → defaults → main
• Type Safety: Full type annotations
• Defaults: Sensible defaults for all optional fields
• Separation of Concerns: Types separate from defaults

Integration Tests

All integration tests use mock API responses from: tests/mocks/mock_api_responses.json

Tests cover:

• API response structures
• Error handling (401, 404, 429)
• Server lifecycle (create, list, delete)
• Resource state management
• Pricing data validation
• Cache behavior

Quick Start

# Clone this provider as template for new provider
cp -r provisioning/extensions/providers/demo provisioning/extensions/providers/newprovider

# Update references
sed -i '' 's/demo/newprovider/g' provisioning/extensions/providers/newprovider/**/*.nu
sed -i '' 's/demo/newprovider/g' provisioning/extensions/providers/newprovider/**/*.j2
sed -i '' 's/demo/newprovider/g' provisioning/extensions/providers/newprovider/**/*.ncl

# Validate framework
cd provisioning/extensions/providers/newprovider
nu tests/run_newprovider_tests.nu

Notes

This provider is a complete, working reference implementation. It demonstrates:

1. How to structure Nushell modules following 0.109.0+ guidelines
2. How to organize 51 mock-based tests
3. How to create runtime templates with Jinja2
4. How to validate Nickel schemas with proper typing

Use this as a starting point for implementing new cloud providers.