provisioning/.typedialog/README.md

TypeDialog Configuration Structure

This directory contains TypeDialog forms, templates, and configuration data organized by subsystem.

Directory Organization

.typedialog/
├── core/           # Core subsystem forms (setup, auth, infrastructure)
├── provisioning/   # Main provisioning configuration fragments
└── platform/       # Platform services forms (future)

Why Multiple Subdirectories

Different subsystems have different form requirements:

1. core/ - Core infrastructure operations

   • System setup wizard
   • Authentication (login, MFA)
   • Infrastructure confirmations (delete, deploy)
   • Users: Developers, operators

2. provisioning/ - Project provisioning configuration

   • Deployment target selection (docker, k8s, ssh)
   • Database configuration (postgres, mysql, sqlite)
   • Monitoring setup
   • Users: Project setup, CI/CD

3. platform/ (future) - Platform services

   • Orchestrator configuration
   • Control center setup
   • Service-specific forms
   • Users: Platform administrators

Structure Within Each Subdirectory

Each subdirectory follows this pattern:

{subsystem}/
├── forms/          # TOML form definitions
├── templates/      # Nickel/Jinja2 templates
├── defaults/       # Default configurations
├── constraints/    # Validation rules
└── generated/      # Generated configs (gitignored)

Core Subsystem (core/)

Purpose: Core infrastructure operations (setup, auth, confirmations)

Forms:

• forms/setup-wizard.toml - Initial system setup
• forms/auth-login.toml - User authentication
• forms/mfa-enroll.toml - MFA enrollment
• forms/infrastructure/*.toml - Delete confirmations (server, cluster, taskserv)

Bash Wrappers (TTY-safe):

• ../../core/shlib/setup-wizard-tty.sh
• ../../core/shlib/auth-login-tty.sh
• ../../core/shlib/mfa-enroll-tty.sh

Usage:

# Run setup wizard
./provisioning/core/shlib/setup-wizard-tty.sh

# Nushell reads result
let config = (open provisioning/.typedialog/core/generated/setup-wizard-result.json | from json)

Provisioning Subsystem (provisioning/)

Purpose: Main provisioning configuration (deployments, databases, monitoring)

Structure:

• form.toml - Main provisioning form
• fragments/ - Modular form fragments
  • deployment-*.toml - Docker, K8s, SSH deployments
  • database-*.toml - Database configurations
  • monitoring.toml - Monitoring setup
  • auth-*.toml - Authentication methods
• constraints.toml - Validation constraints
• defaults/ - Default values
• schemas/ - Nickel schemas

Usage:

# Configure provisioning
nu provisioning/.typedialog/provisioning/configure.nu --backend web

Platform Subsystem (platform/ - Future)

Purpose: Platform services configuration

Planned forms:

• Orchestrator configuration
• Control center setup
• MCP server configuration
• Vault service setup

Status: Structure planned, not yet implemented

Integration with Code

Bash Wrappers (TTY-safe)

Located in: provisioning/core/shlib/*-tty.sh

These wrappers solve Nushell's TTY input limitations by:

1. Handling interactive input in bash
2. Calling TypeDialog with proper TTY forwarding
3. Generating JSON output for Nushell consumption

Pattern:

Bash wrapper → TypeDialog (TTY input) → Nickel config → JSON → Nushell

Nushell Integration

Located in: provisioning/core/nulib/lib_provisioning/

Functions that call the bash wrappers:

• setup/wizard.nu::run-setup-wizard-interactive
• plugins/auth.nu::login-interactive
• plugins/auth.nu::mfa-enroll-interactive

Generated Files

Location: {subsystem}/generated/

Files:

• *.ncl - Nickel configuration files
• *.json - JSON exports for Nushell
• *-defaults.ncl - Default configurations

Note: All generated files are gitignored

Form Naming Conventions

1. Top-level forms: {purpose}.toml

   • Example: setup-wizard.toml, auth-login.toml

2. Fragment forms: fragments/{category}-{variant}.toml

   • Example: deployment-docker.toml, database-postgres.toml

3. Infrastructure forms: forms/infrastructure/{operation}_{resource}_confirm.toml

   • Example: server_delete_confirm.toml

Adding New Forms

For Core Operations

1. Create form: .typedialog/core/forms/{operation}.toml
2. Create wrapper: core/shlib/{operation}-tty.sh
3. Integrate in Nushell: core/nulib/lib_provisioning/

For Provisioning Config

1. Create fragment: .typedialog/provisioning/fragments/{category}-{variant}.toml
2. Update main form: .typedialog/provisioning/form.toml
3. Add defaults: .typedialog/provisioning/defaults/

For Platform Services (Future)

1. Create subsystem: .typedialog/platform/
2. Follow same structure as core/ or provisioning/
3. Document in this README

Related Documentation

• Bash wrappers: provisioning/core/shlib/README.md
• TypeDialog integration: provisioning/platform/.typedialog/README.md
• Nushell setup: provisioning/core/nulib/lib_provisioning/setup/wizard.nu

---

Last Updated: 2025-01-09 Structure Version: 2.0 (Multi-subsystem organization)