# 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

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

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

## Module Organization

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

```bash
# 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.