TypeDialog/docs/prov-gen/README.md

# TypeDialog Provisioning Generator

Infrastructure as Code generation with 7-layer validation (Forms → Constraints → Values → Validators → Schemas → Defaults → JSON).

## Overview

The Provisioning Generator (`typedialog-prov-gen`) generates provisioning directory structures for infrastructure deployment. It creates type-safe configurations using TypeDialog forms + Nickel schemas with multi-layer validation.

## Features

- **7-Layer Validation Pipeline**: Forms → Constraints → Values → Validators → Schemas → Defaults → JSON
- **Infrastructure Templates**: Pre-built templates for common cloud providers
- **TypeDialog Integration**: Interactive forms for configuration collection
- **Nickel Schema Generation**: Type-safe configuration with contracts
- **AI-Assisted Generation**: Optional AI-powered template suggestions
- **Multi-Provider Support**: AWS, GCP, Azure, Hetzner, UpCloud, LXD

## Quick Start

### Installation

```bash
cargo build --release -p typedialog-prov-gen
sudo cp target/release/typedialog-prov-gen /usr/local/bin/

# Or use just
just build::prov-gen
```

### Basic Usage

```bash
# Generate provisioning structure
typedialog-prov-gen --name myproject --output ./provisioning

# With specific providers
typedialog-prov-gen --name webapp --providers aws,gcp --output ./infra

# Interactive mode
typedialog-prov-gen --interactive
```

## Generated Structure

When you run `typedialog-prov-gen`, it creates:

```text
provisioning/
├── constraints/           # Validation constraints (used by forms & validators)
│   ├── network.ncl
│   ├── security.ncl
│   └── resources.ncl
├── schemas/              # Domain-specific type definitions
│   ├── server.ncl
│   ├── database.ncl
│   └── network.ncl
├── validators/           # Validation logic using constraints
│   ├── validate_server.ncl
│   ├── validate_network.ncl
│   └── validate_security.ncl
├── defaults/             # Sensible default values
│   ├── server_defaults.ncl
│   ├── network_defaults.ncl
│   └── security_defaults.ncl
├── fragments/            # Form UI sections (use constraints)
│   ├── server-config.toml
│   ├── network-config.toml
│   └── security-config.toml
├── scripts/              # Orchestration scripts
│   ├── apply.sh
│   ├── destroy.sh
│   ├── validate.nu
│   └── deploy.nu
├── infrastructure/       # Provider-specific templates
│   ├── aws/
│   ├── gcp/
│   └── hetzner/
├── config-form.toml      # Main configuration form (assembles fragments)
└── README.md             # Generated documentation
```

## 7-Layer Validation

### Layer 1: Forms (config-form.toml)

Interactive forms for user input collection:

```toml
# Uses fragments and constraints
[[fragments]]
path = "fragments/server-config.toml"

[[fragments]]
path = "fragments/network-config.toml"
```

### Layer 2: Constraints (constraints/*.ncl)

Reusable validation rules:

```nickel
# constraints/network.ncl
{
  ValidPort = fun label value =>
    if value >= 1 && value <= 65535 then value
    else contract.blame_with_message "Invalid port" label,

  ValidCIDR = ...
}
```

### Layer 3: Values (User Input)

Values collected from forms, validated by constraints.

### Layer 4: Validators (validators/*.ncl)

Complex validation logic combining multiple constraints:

```nickel
# validators/validate_server.ncl
let constraints = import "../constraints/network.ncl" in
let constraints_security = import "../constraints/security.ncl" in

{
  validate_server_config = fun config =>
    config
    | constraints.ValidPort "ssh_port"
    | constraints_security.RequireSSL "ssl_enabled"
}
```

### Layer 5: Schemas (schemas/*.ncl)

Type-safe configuration schemas:

```nickel
# schemas/server.ncl
{
  Server = {
    hostname | String,
    ip_address | ValidIP,
    ssh_port | ValidPort,
    ssl_enabled | Bool,
  }
}
```

### Layer 6: Defaults (defaults/*.ncl)

Default values for optional fields:

```nickel
# defaults/server_defaults.ncl
{
  ssh_port = 22,
  ssl_enabled = true,
  max_connections = 100,
}
```

### Layer 7: JSON Output

Final validated configuration in JSON/YAML/TOML:

```json
{
  "hostname": "web-server-01",
  "ip_address": "10.0.1.100",
  "ssh_port": 22,
  "ssl_enabled": true
}
```

## Configuration

### Project Specification

Create `project-spec.toml`:

```toml
[project]
name = "webapp"
domain = "web-application"

[features]
database = true
caching = true
monitoring = true

[infrastructure]
providers = ["aws", "gcp"]
regions = ["us-east-1", "europe-west1"]

[[servers]]
name = "web"
count = 3
type = "t3.medium"

[[servers]]
name = "db"
count = 2
type = "r5.large"
```

Run:

```bash
typedialog-prov-gen --spec project-spec.toml --output ./provisioning
```

## CLI Commands

```bash
# Generate provisioning structure
typedialog-prov-gen --name <project> --output <dir>

# Interactive mode
typedialog-prov-gen --interactive

# From spec file
typedialog-prov-gen --spec project-spec.toml --output ./infra

# With specific providers
typedialog-prov-gen --providers aws,gcp,hetzner

# With AI assistance
typedialog-prov-gen --ai-assist --llm claude-3-5-sonnet-20241022

# Validate existing provisioning
typedialog-prov-gen validate ./provisioning

# List available templates
typedialog-prov-gen templates --list
```

## Provider Templates

### AWS

```bash
typedialog-prov-gen --providers aws --output ./aws-infra
```

Generates:

- VPC configuration
- EC2 instances
- RDS databases
- S3 buckets
- IAM roles
- Security groups

### GCP

```bash
typedialog-prov-gen --providers gcp --output ./gcp-infra
```

Generates:

- Compute Engine instances
- Cloud SQL databases
- Cloud Storage buckets
- VPC networks
- Firewall rules

### Hetzner

```bash
typedialog-prov-gen --providers hetzner --output ./hetzner-infra
```

Generates:

- Cloud servers
- Volumes
- Networks
- Floating IPs
- Load balancers

### LXD (Bare Metal)

```bash
typedialog-prov-gen --providers lxd --output ./lxd-infra
```

Generates:

- LXD containers
- Storage pools
- Network bridges
- Profiles

## AI-Assisted Generation

Use AI to suggest optimal configurations:

```bash
typedialog-prov-gen \
  --ai-assist \
  --llm claude-3-5-sonnet-20241022 \
  --prompt "web application with high availability" \
  --output ./infra
```

AI will:

- Analyze requirements
- Suggest instance types
- Recommend scaling strategies
- Generate security configurations
- Optimize costs

## Integration with TypeDialog Forms

### Collect Configuration Interactively

```bash
# 1. Generate provisioning structure
typedialog-prov-gen --name webapp --output ./provisioning

# 2. Run the configuration form
typedialog -p typedialog-tui -- ./provisioning/config-form.toml

# 3. Apply configuration
cd provisioning
./scripts/apply.sh
```

### Programmatic Usage

```rust
use typedialog_prov_gen::{generate, ProjectSpec};

let spec = ProjectSpec {
    name: "webapp".to_string(),
    domain: "web-application".to_string(),
    providers: vec!["aws".to_string()],
    ..Default::default()
};

generate(spec, "./provisioning").await?;
```

## Use Cases

### 1. Multi-Cloud Deployment

Generate infrastructure for AWS + GCP with shared configuration:

```bash
typedialog-prov-gen \
  --name multi-cloud-app \
  --providers aws,gcp \
  --output ./infra
```

### 2. Development → Production

Generate separate provisioning for dev/staging/prod:

```bash
typedialog-prov-gen --name myapp --env dev --output ./infra/dev
typedialog-prov-gen --name myapp --env staging --output ./infra/staging
typedialog-prov-gen --name myapp --env production --output ./infra/prod
```

### 3. Compliance-Driven Configuration

Generate infrastructure meeting specific compliance requirements:

```bash
typedialog-prov-gen \
  --name secure-app \
  --compliance gdpr,hipaa \
  --output ./infra
```

### 4. Cost-Optimized Infrastructure

AI-assisted cost optimization:

```bash
typedialog-prov-gen \
  --ai-assist \
  --optimize-for cost \
  --budget 500 \
  --output ./infra
```

## Validation

### Validate Before Apply

```bash
# Validate constraints
cd provisioning
nickel eval --format json constraints/network.ncl

# Validate schemas
nickel typecheck schemas/server.ncl

# Run validators
nickel eval validators/validate_server.ncl < config.json

# Full validation pipeline
./scripts/validate.nu
```

### CI/CD Integration

```yaml
# GitHub Actions
- name: Validate provisioning
  run: |
    cd provisioning
    ./scripts/validate.nu
    nickel typecheck schemas/*.ncl
```

## Examples

See [examples/11-prov-gen/](../../examples/11-prov-gen/) for:

- Basic provisioning generation
- Multi-provider setup
- AI-assisted configuration
- Compliance templates
- Cost optimization

## Related Documentation

- [Configuration](../configuration.md) - General configuration guide
- [Nickel Integration](../nickel.md) - Nickel schema documentation
- [AI Backend](../ai/) - AI-assisted generation
- [Examples](../../examples/11-prov-gen/) - Working examples

## Troubleshooting

### "Constraint validation failed"

Check constraint definitions:

```bash
nickel eval constraints/network.ncl
```

### "Template not found"

List available templates:

```bash
typedialog-prov-gen templates --list
```

### "Provider not supported"

Supported providers: aws, gcp, azure, hetzner, lxd

```bash
typedialog-prov-gen --providers aws,gcp
```

### "Nickel evaluation error"

Ensure Nickel CLI is installed:

```bash
nickel --version
# Install: cargo install nickel-lang-cli
```

---

**Ready to start?** See [examples/11-prov-gen/](../../examples/11-prov-gen/)