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)