# TypeDialog + Nickel Integration Guide\n\n**Status**: Implementation Guide\n**Last Updated**: 2025-12-15\n**Project**: TypeDialog at `/Users/Akasha/Development/typedialog`\n**Purpose**: Type-safe UI generation from Nickel schemas\n\n---\n\n## What is TypeDialog\n\nTypeDialog generates **type-safe interactive forms** from configuration schemas with **bidirectional Nickel integration**.\n\n```\nNickel Schema\n    ↓\nTypeDialog Form (Auto-generated)\n    ↓\nUser fills form interactively\n    ↓\nNickel output config (Type-safe)\n```\n\n---\n\n## Architecture\n\n### Three Layers\n\n```\nCLI/TUI/Web Layer\n    ↓\nTypeDialog Form Engine\n    ↓\nNickel Integration\n    ↓\nSchema Contracts\n```\n\n### Data Flow\n\n```\nInput (Nickel)\n    ↓\nForm Definition (TOML)\n    ↓\nForm Rendering (CLI/TUI/Web)\n    ↓\nUser Input\n    ↓\nValidation (against Nickel contracts)\n    ↓\nOutput (JSON/YAML/TOML/Nickel)\n```\n\n---\n\n## Setup\n\n### Installation\n\n```\n# Clone TypeDialog\ngit clone https://github.com/jesusperezlorenzo/typedialog.git\ncd typedialog\n\n# Build\ncargo build --release\n\n# Install (optional)\ncargo install --path ./crates/typedialog\n```\n\n### Verify Installation\n\n```\ntypedialog --version\ntypedialog --help\n```\n\n---\n\n## Basic Workflow\n\n### Step 1: Define Nickel Schema\n\n```\n# server_config.ncl\nlet contracts = import "./contracts.ncl" in\nlet defaults = import "./defaults.ncl" in\n\n{\n  defaults = defaults,\n\n  make_server | not_exported = fun overrides =>\n    defaults.server & overrides,\n\n  DefaultServer = defaults.server,\n}\n```\n\n### Step 2: Define TypeDialog Form (TOML)\n\n```\n# server_form.toml\n[form]\ntitle = "Server Configuration"\ndescription = "Create a new server configuration"\n\n[[fields]]\nname = "server_name"\nlabel = "Server Name"\ntype = "text"\nrequired = true\nhelp = "Unique identifier for the server"\nplaceholder = "web-01"\n\n[[fields]]\nname = "cpu_cores"\nlabel = "CPU Cores"\ntype = "number"\nrequired = true\ndefault = 4\nhelp = "Number of CPU cores (1-32)"\n\n[[fields]]\nname = "memory_gb"\nlabel = "Memory (GB)"\ntype = "number"\nrequired = true\ndefault = 8\nhelp = "Memory in GB (1-256)"\n\n[[fields]]\nname = "zone"\nlabel = "Availability Zone"\ntype = "select"\nrequired = true\noptions = ["us-nyc1", "eu-fra1", "ap-syd1"]\ndefault = "us-nyc1"\n\n[[fields]]\nname = "monitoring"\nlabel = "Enable Monitoring"\ntype = "confirm"\ndefault = true\n\n[[fields]]\nname = "tags"\nlabel = "Tags"\ntype = "multiselect"\noptions = ["production", "staging", "testing", "development"]\nhelp = "Select applicable tags"\n```\n\n### Step 3: Render Form (CLI)\n\n```\ntypedialog form --config server_form.toml --backend cli\n```\n\n**Output**:\n\n```\nServer Configuration\nCreate a new server configuration\n\n? Server Name: web-01\n? CPU Cores: 4\n? Memory (GB): 8\n? Availability Zone: (us-nyc1/eu-fra1/ap-syd1) us-nyc1\n? Enable Monitoring: (y/n) y\n? Tags: (Select multiple with space)\n  ◉ production\n  ◯ staging\n  ◯ testing\n  ◯ development\n```\n\n### Step 4: Validate Against Nickel Schema\n\n```\n# Validation happens automatically\n# If input matches Nickel contract, proceeds to output\n```\n\n### Step 5: Output to Nickel\n\n```\ntypedialog form \\n  --config server_form.toml \\n  --output nickel \\n  --backend cli\n```\n\n**Output file** (`server_config_output.ncl`):\n\n```\n{\n  server_name = "web-01",\n  cpu_cores = 4,\n  memory_gb = 8,\n  zone = "us-nyc1",\n  monitoring = true,\n  tags = ["production"],\n}\n```\n\n---\n\n## Real-World Example 1: Infrastructure Wizard\n\n### Scenario\n\nYou want an interactive CLI wizard for infrastructure provisioning.\n\n### Step 1: Define Nickel Schema for Infrastructure\n\n```\n# infrastructure_schema.ncl\n{\n  InfrastructureConfig = {\n    workspace_name | String,\n    deployment_mode | [| 'solo, 'multiuser, 'cicd, 'enterprise |],\n    provider | [| 'upcloud, 'aws, 'hetzner |],\n    taskservs | Array,\n    enable_monitoring | Bool,\n    enable_backup | Bool,\n    backup_retention_days | Number,\n  },\n\n  defaults = {\n    workspace_name = "",\n    deployment_mode = 'solo,\n    provider = 'upcloud,\n    taskservs = [],\n    enable_monitoring = true,\n    enable_backup = true,\n    backup_retention_days = 7,\n  },\n\n  DefaultInfra = defaults,\n}\n```\n\n### Step 2: Create Comprehensive Form\n\n```\n# infrastructure_wizard.toml\n[form]\ntitle = "Infrastructure Provisioning Wizard"\ndescription = "Create a complete infrastructure setup"\n\n[[fields]]\nname = "workspace_name"\nlabel = "Workspace Name"\ntype = "text"\nrequired = true\nvalidation_pattern = "^[a-z0-9-]{3,32}$"\nhelp = "3-32 chars, lowercase alphanumeric and hyphens only"\nplaceholder = "my-workspace"\n\n[[fields]]\nname = "deployment_mode"\nlabel = "Deployment Mode"\ntype = "select"\nrequired = true\noptions = [\n  { value = "solo", label = "Solo (Single user, 2 CPU, 4 GB RAM)" },\n  { value = "multiuser", label = "MultiUser (Team, 4 CPU, 8 GB RAM)" },\n  { value = "cicd", label = "CI/CD (Pipelines, 8 CPU, 16 GB RAM)" },\n  { value = "enterprise", label = "Enterprise (Production, 16 CPU, 32 GB RAM)" },\n]\ndefault = "solo"\n\n[[fields]]\nname = "provider"\nlabel = "Cloud Provider"\ntype = "select"\nrequired = true\noptions = [\n  { value = "upcloud", label = "UpCloud (EU)" },\n  { value = "aws", label = "AWS (Global)" },\n  { value = "hetzner", label = "Hetzner (EU)" },\n]\ndefault = "upcloud"\n\n[[fields]]\nname = "taskservs"\nlabel = "Task Services"\ntype = "multiselect"\nrequired = false\noptions = [\n  { value = "kubernetes", label = "Kubernetes (Container orchestration)" },\n  { value = "cilium", label = "Cilium (Network policy)" },\n  { value = "postgres", label = "PostgreSQL (Database)" },\n  { value = "redis", label = "Redis (Cache)" },\n  { value = "prometheus", label = "Prometheus (Monitoring)" },\n  { value = "etcd", label = "etcd (Distributed config)" },\n]\nhelp = "Select task services to deploy"\n\n[[fields]]\nname = "enable_monitoring"\nlabel = "Enable Monitoring"\ntype = "confirm"\ndefault = true\nhelp = "Prometheus + Grafana dashboards"\n\n[[fields]]\nname = "enable_backup"\nlabel = "Enable Backup"\ntype = "confirm"\ndefault = true\n\n[[fields]]\nname = "backup_retention_days"\nlabel = "Backup Retention (days)"\ntype = "number"\nrequired = false\ndefault = 7\nhelp = "How long to keep backups (if enabled)"\nvisible_if = "enable_backup == true"\n\n[[fields]]\nname = "email"\nlabel = "Admin Email"\ntype = "text"\nrequired = true\nvalidation_pattern = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"\nhelp = "For alerts and notifications"\nplaceholder = "admin@company.com"\n```\n\n### Step 3: Run Interactive Wizard\n\n```\ntypedialog form \\n  --config infrastructure_wizard.toml \\n  --backend tui \\n  --output nickel\n```\n\n**Output** (`infrastructure_config.ncl`):\n\n```\n{\n  workspace_name = "production-eu",\n  deployment_mode = 'enterprise,\n  provider = 'upcloud,\n  taskservs = ["kubernetes", "cilium", "postgres", "redis", "prometheus"],\n  enable_monitoring = true,\n  enable_backup = true,\n  backup_retention_days = 30,\n  email = "ops@company.com",\n}\n```\n\n### Step 4: Use Output in Infrastructure\n\n```\n# main_infrastructure.ncl\nlet config = import "./infrastructure_config.ncl" in\nlet schemas = import "../../provisioning/schemas/main.ncl" in\n\n{\n  # Build infrastructure based on config\n  infrastructure = if config.deployment_mode == 'solo then\n    {\n      servers = [\n        schemas.lib.make_server {\n          name = config.workspace_name,\n          cpu_cores = 2,\n          memory_gb = 4,\n        },\n      ],\n      taskservs = config.taskservs,\n    }\n  else if config.deployment_mode == 'enterprise then\n    {\n      servers = [\n        schemas.lib.make_server { name = "app-01", cpu_cores = 16, memory_gb = 32 },\n        schemas.lib.make_server { name = "app-02", cpu_cores = 16, memory_gb = 32 },\n        schemas.lib.make_server { name = "db-01", cpu_cores = 16, memory_gb = 32 },\n      ],\n      taskservs = config.taskservs,\n      monitoring = { enabled = config.enable_monitoring, email = config.email },\n    }\n  else\n    # default fallback\n    {},\n}\n```\n\n---\n\n## Real-World Example 2: Server Configuration Form\n\n### Form Definition (Advanced)\n\n```\n# server_advanced_form.toml\n[form]\ntitle = "Server Configuration"\ndescription = "Configure server settings with validation"\n\n# Section 1: Basic Info\n[[sections]]\nname = "basic"\ntitle = "Basic Information"\n\n[[fields]]\nname = "server_name"\nsection = "basic"\nlabel = "Server Name"\ntype = "text"\nrequired = true\nvalidation_pattern = "^[a-z0-9-]{3,32}$"\n\n[[fields]]\nname = "description"\nsection = "basic"\nlabel = "Description"\ntype = "textarea"\nrequired = false\nplaceholder = "Server purpose and details"\n\n# Section 2: Resources\n[[sections]]\nname = "resources"\ntitle = "Resources"\n\n[[fields]]\nname = "cpu_cores"\nsection = "resources"\nlabel = "CPU Cores"\ntype = "number"\nrequired = true\ndefault = 4\nmin = 1\nmax = 32\n\n[[fields]]\nname = "memory_gb"\nsection = "resources"\nlabel = "Memory (GB)"\ntype = "number"\nrequired = true\ndefault = 8\nmin = 1\nmax = 256\n\n[[fields]]\nname = "disk_gb"\nsection = "resources"\nlabel = "Disk (GB)"\ntype = "number"\nrequired = true\ndefault = 100\nmin = 10\nmax = 2000\n\n# Section 3: Network\n[[sections]]\nname = "network"\ntitle = "Network Configuration"\n\n[[fields]]\nname = "zone"\nsection = "network"\nlabel = "Availability Zone"\ntype = "select"\nrequired = true\noptions = ["us-nyc1", "eu-fra1", "ap-syd1"]\n\n[[fields]]\nname = "enable_ipv6"\nsection = "network"\nlabel = "Enable IPv6"\ntype = "confirm"\ndefault = false\n\n[[fields]]\nname = "allowed_ports"\nsection = "network"\nlabel = "Allowed Ports"\ntype = "multiselect"\noptions = [\n  { value = "22", label = "SSH (22)" },\n  { value = "80", label = "HTTP (80)" },\n  { value = "443", label = "HTTPS (443)" },\n  { value = "3306", label = "MySQL (3306)" },\n  { value = "5432", label = "PostgreSQL (5432)" },\n]\n\n# Section 4: Advanced\n[[sections]]\nname = "advanced"\ntitle = "Advanced Options"\n\n[[fields]]\nname = "kernel_version"\nsection = "advanced"\nlabel = "Kernel Version"\ntype = "text"\nrequired = false\nplaceholder = "5.15.0 (or leave blank for latest)"\n\n[[fields]]\nname = "enable_monitoring"\nsection = "advanced"\nlabel = "Enable Monitoring"\ntype = "confirm"\ndefault = true\n\n[[fields]]\nname = "monitoring_interval"\nsection = "advanced"\nlabel = "Monitoring Interval (seconds)"\ntype = "number"\nrequired = false\ndefault = 60\nvisible_if = "enable_monitoring == true"\n\n[[fields]]\nname = "tags"\nsection = "advanced"\nlabel = "Tags"\ntype = "multiselect"\noptions = ["production", "staging", "testing", "development"]\n```\n\n### Output Structure\n\n```\n{\n  # Basic\n  server_name = "web-prod-01",\n  description = "Primary web server",\n\n  # Resources\n  cpu_cores = 16,\n  memory_gb = 32,\n  disk_gb = 500,\n\n  # Network\n  zone = "eu-fra1",\n  enable_ipv6 = true,\n  allowed_ports = ["22", "80", "443"],\n\n  # Advanced\n  kernel_version = "5.15.0",\n  enable_monitoring = true,\n  monitoring_interval = 30,\n  tags = ["production"],\n}\n```\n\n---\n\n## API Integration\n\n### TypeDialog REST Endpoints\n\n```\n# Start TypeDialog server\ntypedialog server --port 8080\n\n# Render form via HTTP\ncurl -X POST http://localhost:8080/forms \\n  -H "Content-Type: application/json" \\n  -d @server_form.toml\n```\n\n### Response Format\n\n```\n{\n  "form_id": "srv_abc123",\n  "status": "rendered",\n  "fields": [\n    {\n      "name": "server_name",\n      "label": "Server Name",\n      "type": "text",\n      "required": true,\n      "placeholder": "web-01"\n    }\n  ]\n}\n```\n\n### Submit Form\n\n```\ncurl -X POST http://localhost:8080/forms/srv_abc123/submit \\n  -H "Content-Type: application/json" \\n  -d '{\n    "server_name": "web-01",\n    "cpu_cores": 4,\n    "memory_gb": 8,\n    "zone": "us-nyc1",\n    "monitoring": true,\n    "tags": ["production"]\n  }'\n```\n\n### Response\n\n```\n{\n  "status": "success",\n  "validation": "passed",\n  "output_format": "nickel",\n  "output": {\n    "server_name": "web-01",\n    "cpu_cores": 4,\n    "memory_gb": 8,\n    "zone": "us-nyc1",\n    "monitoring": true,\n    "tags": ["production"]\n  }\n}\n```\n\n---\n\n## Validation\n\n### Contract-Based Validation\n\nTypeDialog validates user input against Nickel contracts:\n\n```\n# Nickel contract\nServerConfig = {\n  cpu_cores | Number,  # Must be number\n  memory_gb | Number,  # Must be number\n  zone | [| 'us-nyc1, 'eu-fra1 |],  # Enum\n}\n\n# If user enters invalid value\n# TypeDialog rejects before serializing\n```\n\n### Validation Rules in Form\n\n```\n[[fields]]\nname = "cpu_cores"\ntype = "number"\nmin = 1\nmax = 32\nhelp = "Must be 1-32 cores"\n# TypeDialog enforces before user can submit\n```\n\n---\n\n## Integration with Provisioning Platform\n\n### Use Case: Infrastructure Initialization\n\n```\n# 1. User runs initialization\nprovisioning init --wizard\n\n# 2. Behind the scenes:\n#    - Loads infrastructure_wizard.toml\n#    - Starts TypeDialog (CLI or TUI)\n#    - User fills form interactively\n\n# 3. Output saved as config\n#    ~/.config/provisioning/infrastructure_config.ncl\n\n# 4. Provisioning uses output\n#    provisioning server create --from-config infrastructure_config.ncl\n```\n\n### Implementation in Nushell\n\n```\n# provisioning/core/nulib/provisioning_init.nu\n\ndef provisioning_init_wizard [] {\n  # Launch TypeDialog form\n  let config = (\n    typedialog form \\n      --config "provisioning/config/infrastructure_wizard.toml" \\n      --backend tui \\n      --output nickel\n  )\n\n  # Save output\n  $config | save ~/.config/provisioning/workspace_config.ncl\n\n  # Validate with provisioning schemas\n  let provisioning = (import "provisioning/schemas/main.ncl")\n  let validated = (\n    nickel export ~/.config/provisioning/workspace_config.ncl\n      | jq . | to json\n  )\n\n  print "Infrastructure configuration created!"\n  print "Use: provisioning deploy --from-config"\n}\n```\n\n---\n\n## Advanced Features\n\n### Conditional Visibility\n\nShow/hide fields based on user selections:\n\n```\n[[fields]]\nname = "backup_retention"\nlabel = "Backup Retention (days)"\ntype = "number"\nvisible_if = "enable_backup == true"  # Only shown if backup enabled\n```\n\n### Dynamic Defaults\n\nSet defaults based on other fields:\n\n```\n[[fields]]\nname = "deployment_mode"\ntype = "select"\noptions = ["solo", "enterprise"]\n\n[[fields]]\nname = "cpu_cores"\ntype = "number"\ndefault_from = "deployment_mode"  # Can reference other fields\n# solo → default 2, enterprise → default 16\n```\n\n### Custom Validation\n\n```\n[[fields]]\nname = "memory_gb"\ntype = "number"\nvalidation_rule = "memory_gb >= cpu_cores * 2"\nhelp = "Memory must be at least 2 GB per CPU core"\n```\n\n---\n\n## Output Formats\n\nTypeDialog can output to multiple formats:\n\n```\n# Output to Nickel (recommended for IaC)\ntypedialog form --config form.toml --output nickel\n\n# Output to JSON (for APIs)\ntypedialog form --config form.toml --output json\n\n# Output to YAML (for K8s)\ntypedialog form --config form.toml --output yaml\n\n# Output to TOML (for application config)\ntypedialog form --config form.toml --output toml\n```\n\n---\n\n## Backends\n\nTypeDialog supports three rendering backends:\n\n### 1. CLI (Command-line prompts)\n\n```\ntypedialog form --config form.toml --backend cli\n```\n\n**Pros**: Lightweight, SSH-friendly, no dependencies\n**Cons**: Basic UI\n\n### 2. TUI (Terminal User Interface - Ratatui)\n\n```\ntypedialog form --config form.toml --backend tui\n```\n\n**Pros**: Rich UI, keyboard navigation, sections\n**Cons**: Requires terminal support\n\n### 3. Web (HTTP Server - Axum)\n\n```\ntypedialog form --config form.toml --backend web --port 3000\n# Opens http://localhost:3000\n```\n\n**Pros**: Beautiful UI, remote access, multi-user\n**Cons**: Requires browser, network\n\n---\n\n## Troubleshooting\n\n### Problem: Form doesn't match Nickel contract\n\n**Cause**: Field names or types don't match contract\n\n**Solution**: Verify field definitions match Nickel schema:\n\n```\n# Form field\n[[fields]]\nname = "cpu_cores"  # Must match Nickel field name\ntype = "number"     # Must match Nickel type\n```\n\n### Problem: Validation fails\n\n**Cause**: User input violates contract constraints\n\n**Solution**: Add help text and validation rules:\n\n```\n[[fields]]\nname = "cpu_cores"\nvalidation_pattern = "^[1-9][0-9]*$"\nhelp = "Must be positive integer"\n```\n\n### Problem: Output not valid Nickel\n\n**Cause**: Missing required fields\n\n**Solution**: Ensure all required fields in form:\n\n```\n[[fields]]\nname = "required_field"\nrequired = true  # User must provide value\n```\n\n---\n\n## Complete Example: End-to-End Workflow\n\n### Step 1: Define Nickel Schema\n\n```\n# workspace_schema.ncl\n{\n  workspace = {\n    name = "",\n    mode = 'solo,\n    provider = 'upcloud,\n    monitoring = true,\n    email = "",\n  },\n}\n```\n\n### Step 2: Define Form\n\n```\n# workspace_form.toml\n[[fields]]\nname = "name"\ntype = "text"\nrequired = true\n\n[[fields]]\nname = "mode"\ntype = "select"\noptions = ["solo", "enterprise"]\n\n[[fields]]\nname = "provider"\ntype = "select"\noptions = ["upcloud", "aws"]\n\n[[fields]]\nname = "monitoring"\ntype = "confirm"\n\n[[fields]]\nname = "email"\ntype = "text"\nrequired = true\n```\n\n### Step 3: User Interaction\n\n```\n$ typedialog form --config workspace_form.toml --backend tui\n# User fills form interactively\n```\n\n### Step 4: Output\n\n```\n{\n  workspace = {\n    name = "production",\n    mode = 'enterprise,\n    provider = 'upcloud,\n    monitoring = true,\n    email = "ops@company.com",\n  },\n}\n```\n\n### Step 5: Use in Provisioning\n\n```\n# main.ncl\nlet config = import "./workspace.ncl" in\nlet schemas = import "provisioning/schemas/main.ncl" in\n\n{\n  # Build infrastructure\n  infrastructure = schemas.deployment.modes.make_mode {\n    deployment_type = config.workspace.mode,\n    provider = config.workspace.provider,\n  },\n}\n```\n\n---\n\n## Summary\n\nTypeDialog + Nickel provides:\n\n✅ **Type-Safe UIs**: Forms validated against Nickel contracts\n✅ **Auto-Generated**: No UI code to maintain\n✅ **Bidirectional**: Nickel → Forms → Nickel\n✅ **Multiple Outputs**: JSON, YAML, TOML, Nickel\n✅ **Three Backends**: CLI, TUI, Web\n✅ **Production-Ready**: Used in real infrastructure\n\n**Key Benefit**: Reduce configuration errors by enforcing schema validation at UI level, not after deployment.\n\n---\n\n**Version**: 1.0.0\n**Status**: Implementation Guide\n**Last Updated**: 2025-12-15
