TypeDialog/examples/11-prov-gen/README.md

# 11. Provisioning Generator

**Complete provisioning infrastructure generation from multiple input sources**

Demonstrates the `typedialog-provisioning-gen` tool that generates a complete 7-layer validation architecture for configuration management, supporting multiple input modes and producing TypeDialog forms, Nickel schemas, validators, and orchestration scripts.

## Quick Start

### Pick Your Input Mode

**Mode A: Analyze Cargo.toml** (Automatic Detection)
```bash
# Auto-detect features from dependencies
typedialog-provisioning-gen cargo \
  --input mode-a-cargo/Cargo.toml \
  --output /tmp/my-provisioning
```
→ See [`mode-a-cargo/README.md`](mode-a-cargo/) for details

**Mode B: Config File** (Explicit Specification)
```bash
# Define all features in TOML config
typedialog-provisioning-gen config \
  --input mode-b-config/project-spec.toml \
  --output /tmp/my-provisioning
```
→ See [`mode-b-config/README.md`](mode-b-config/) for details

**Mode C: Interactive Wizard** (Conversational)
```bash
# Step-by-step guidance with AI suggestions
typedialog-provisioning-gen wizard \
  --project my-service \
  --output /tmp/my-provisioning
```
→ See [`mode-c-wizard/README.md`](mode-c-wizard/) for details

**Mode D: Nickel Schema** (Migration)
```bash
# Convert existing Nickel schema
typedialog-provisioning-gen nickel \
  --input mode-d-nickel/existing-config.ncl \
  --output /tmp/my-provisioning
```
→ See [`mode-d-nickel/README.md`](mode-d-nickel/) for details

## What Gets Generated

All modes produce the same 7-layer structure:

```
provisioning/
├── constraints.toml          # Layer 1: Validation bounds (single source of truth)
├── schemas/                  # Layer 2: Type contracts (Nickel)
├── validators/               # Layer 3: Validation logic
├── defaults/                 # Layer 4: Default values
├── fragments/                # Layer 5: TypeDialog forms
├── scripts/                  # Layer 6: Orchestration scripts
└── config.ncl                # Layer 7: Master configuration
```

→ See [`output-example/README.md`](output-example/) for detailed structure explanation

## Key Features

### ✅ 4 Input Modes
- **Cargo.toml Analysis**: Automatic feature detection from dependencies
- **Config File**: Explicit specification with full control
- **Interactive Wizard**: Conversational guidance with AI suggestions
- **Nickel Schema**: Convert existing Nickel to provisioning structure

### ✅ 7-Layer Validation
- **Constraints** (single source of truth)
- **Schemas** (Nickel type contracts)
- **Validators** (validation logic)
- **Defaults** (sensible defaults)
- **Fragments** (TypeDialog forms)
- **Scripts** (orchestration)
- **Master Config** (integration point)

### ✅ Domain Features
Each mode discovers or defines domain features:

| Feature | Fields | Example |
|---------|--------|---------|
| http_server | bind_address, timeout_seconds | REST API |
| database | host, port, username, password | PostgreSQL, MySQL |
| authentication | jwt_secret, expiry | JWT tokens |
| caching | cache_enabled, ttl | Redis layer |
| monitoring | prometheus_url, retention | Observability |

### ✅ Multiple Field Types
- Text, Number, Password, Confirm
- Select, MultiSelect
- Editor, Date
- RepeatingGroup (arrays)

### ✅ Sensitive Data Handling
Automatic encryption for sensitive fields:
- `age` (modern encryption)
- `sops` (Mozilla SOPS)
- `secretumvault` (integration ready)
- `aws-kms`, `gcp-kms`, `azure-kms`

### ✅ Constraint Interpolation
Single source of truth - define constraints once, use everywhere:
- In validators (Nickel)
- In forms (TypeDialog)
- In documentation
- In validation scripts

## Complete Workflow

### 1. Generate from Cargo.toml
```bash
cd my-rust-service
typedialog-provisioning-gen cargo --output ./provisioning
```

### 2. Test Form Interactively
```bash
typedialog provisioning/fragments/http_server-section.toml --backend cli
```

### 3. Validate Configuration
```bash
./provisioning/scripts/validate-nickel.sh < config.ncl
```

### 4. Use in Application
```rust
let config = nickel::eval_file("provisioning/config.ncl")?;
```

## Directory Guide

| Path | Purpose |
|------|---------|
| [`mode-a-cargo/`](mode-a-cargo/) | Cargo.toml introspection example |
| [`mode-b-config/`](mode-b-config/) | Config file specification example |
| [`mode-c-wizard/`](mode-c-wizard/) | Interactive wizard example |
| [`mode-d-nickel/`](mode-d-nickel/) | Nickel schema conversion example |
| [`output-example/`](output-example/) | Complete generated output structure |

## Examples by Scenario

### Scenario 1: Existing Rust Project
```bash
# You have a Cargo.toml with dependencies
typedialog-provisioning-gen cargo --output ./infra

# Auto-detects:
# - axum → HTTP server config
# - sqlx → database config
# - redis → caching config
# - prometheus → monitoring
```

Best for: Rust projects, quick setup

### Scenario 2: New Multi-Service Architecture
```bash
# You have a detailed specification
typedialog-provisioning-gen config --input architecture.toml --output ./platform

# Supports:
# - Multiple database types
# - Event streaming setup
# - Monitoring configuration
# - Cloud provider selection
```

Best for: Complex systems, cross-team coordination

### Scenario 3: Interactive Setup
```bash
# You want guidance through the process
typedialog-provisioning-gen wizard --project my-service

# Walks through:
# - Project type selection
# - Infrastructure requirements
# - Feature selection
# - Field configuration
# - AI-powered suggestions
```

Best for: First-time users, exploring options

### Scenario 4: Legacy System Migration
```bash
# You have existing Nickel schemas
typedialog-provisioning-gen nickel --input config.ncl --output ./new-provisioning

# Converts:
# - Type definitions → schemas
# - Records → domain features
# - Fields → form fragments
```

Best for: System modernization, adding forms to existing configs

## Using Generated Artifacts

### TypeDialog Forms
```bash
# Display configuration form
typedialog provisioning/fragments/database-section.toml --backend cli

# Web interface
typedialog-web provisioning/fragments/*.toml --port 3000
```

### Nickel Validation
```bash
# Validate syntax
./provisioning/scripts/validate-nickel.sh

# Use in config
nickel eval provisioning/config.ncl
```

### Scripts
```bash
# Master orchestrator
./provisioning/scripts/config.sh

# Format conversion
./provisioning/scripts/json-to-nickel.sh < input.json
./provisioning/scripts/nickel-to-json.sh < config.ncl
```

### Application Integration
```rust
// Load provisioning config
let config = provisioning::load("provisioning/config.ncl")?;
```

## What This Demonstrates

### Core Concepts
✅ Multi-mode input pipeline normalization
✅ 7-layer validation architecture
✅ Constraint interpolation (single source of truth)
✅ Template-based code generation
✅ Domain-driven feature extraction

### Integration Points
✅ TypeDialog forms generation
✅ Nickel schema contracts
✅ Sensitive data encryption
✅ Cross-format conversion (JSON ↔ Nickel)
✅ Orchestration scripts (bash + nushell)

### Advanced Features
✅ Cargo.toml dependency analysis
✅ Project type inference
✅ Infrastructure requirement detection
✅ AI-powered wizard with RAG retrieval
✅ Reusable template library
✅ Custom field types and validation

## Next Steps

### Try Each Mode
1. **Start with Mode A**: `cd mode-a-cargo && cat README.md`
2. **Explore Mode B**: `cd mode-b-config && cat README.md`
3. **Test Mode C**: `cd mode-c-wizard && cat README.md`
4. **Learn Mode D**: `cd mode-d-nickel && cat README.md`

### Understand the Output
- **View Structure**: `cd output-example && cat README.md`
- **Study Layers**: Examine each generated directory (schemas/, validators/, etc.)
- **Test Interactively**: Run TypeDialog on generated fragments

### Build Your Own
1. **Pick a mode** based on your needs
2. **Generate** from your input
3. **Customize** the generated structure
4. **Deploy** using generated scripts
5. **Iterate** as your requirements evolve

## More Information

- **TypeDialog Docs**: Form UI and integration
- **Nickel Docs**: Type-safe configuration language
- **Encryption**: Secrets management with age, sops, KMS
- **Scripts**: Bash and Nushell orchestration

## Testing All Examples

```bash
# Run Mode A
cargo run -p typedialog-provisioning-gen -- cargo \
  --input examples/11-provisioning-generation/mode-a-cargo/Cargo.toml \
  --output /tmp/mode-a-output

# Run Mode B
cargo run -p typedialog-provisioning-gen -- config \
  --input examples/11-provisioning-generation/mode-b-config/project-spec.toml \
  --output /tmp/mode-b-output

# Run Mode D
cargo run -p typedialog-provisioning-gen -- nickel \
  --input examples/11-provisioning-generation/mode-d-nickel/existing-config.ncl \
  --output /tmp/mode-d-output

# Run Mode C (interactive)
cargo run -p typedialog-provisioning-gen -- wizard \
  --project test-service \
  --output /tmp/mode-c-output
```

## Key Files

### Example Inputs
- `mode-a-cargo/Cargo.toml` - Real Cargo.toml with dependencies
- `mode-b-config/project-spec.toml` - Complete feature specification
- `mode-d-nickel/existing-config.ncl` - Nickel schema example

### Documentation
- `mode-a-cargo/README.md` - Cargo.toml analysis details
- `mode-b-config/README.md` - Config specification format
- `mode-c-wizard/README.md` - Wizard interaction flow
- `mode-d-nickel/README.md` - Nickel schema conversion
- `output-example/README.md` - Generated structure explanation

## Summary

The Provisioning Generator provides a complete solution for infrastructure-as-code configuration:

- **Flexible Input**: 4 modes for different scenarios
- **Type-Safe Output**: Nickel schemas with validation
- **User-Friendly Forms**: TypeDialog for interactive setup
- **Production-Ready**: Scripts for deployment and orchestration
- **Extensible**: Template library and custom domain features

Perfect for:
- Microservice configuration
- Infrastructure setup automation
- Configuration management at scale
- DevOps tooling
- SaaS platform provisioning