TypeDialog/docs/project-definition.md

# Project Definition - typedialog

**Version**: 0.1.0
**Date**: 2025-12-17
**Status**: Production-ready, pre-publicación

---

## Resumen Ejecutivo

**Nombre Actual**: typedialog v0.1.0
**Categoría**: Interactive Configuration Management System
**Estado**: Production-ready, pre-publicación
**Arquitectura**: Multi-backend Rust workspace (4 crates)

**Propósito Central**: Facilitar la gestión de configuración para aplicaciones, proyectos y scripts mediante inputs interactivos (prompts individuales o forms completos), con integración bidireccional a Nickel para settings tipados y validados.

**Diferenciador Único**: Único sistema en el mercado que integra Nickel schemas → Interactive collection → Multi-format output (YAML/JSON/TOML) con preservación de type contracts.

---

## 1. Identidad del Proyecto

### 1.1 Estado Actual

- **Nombre**: typedialog
- **Origen**: Extraído de `nu_plugin_inquire` (plugin de Nushell)
- **Etimología**: "form" + "inquire" (referencia al crate `inquire`)
- **Versión**: 0.1.0
- **Madurez**: Production-ready, 80+ tests passing, documentación completa
- **Publicación**: No publicado en crates.io aún

### 1.2 Evolución Histórica

```
nu_plugin_inquire (Nushell plugin)
    ↓
typedialog (standalone library extraction)
    ↓
+ CLI backend (inquire-based)
    ↓
+ Nickel integration (bidirectional)
    ↓
+ TUI backend (ratatui)
    ↓
+ Web backend (axum + HTMX)
    ↓
Current: Multi-backend configuration management system
```

**Puntos de Inflexión**:
1. Separación de Nushell → biblioteca standalone
2. Adición Nickel integration → type-safe configuration focus
3. Múltiples backends → multi-context positioning

### 1.3 Descripción Técnica Precisa

**Definición Formal**: Sistema de gestión de configuración interactiva que facilita la recolección, validación y transformación de settings mediante diálogo con el usuario, actuando como puente entre Nickel schemas tipados y formatos de configuración estándar (YAML/JSON/TOML), soportando múltiples interfaces (CLI/TUI/Web) para adaptarse a diferentes contextos de uso.

**Componentes Core**:
- Form/Prompt engine con 8 tipos de inputs
- Nickel parser y code generator (bidirectional)
- Backend abstraction layer (trait-based)
- Template engine (Tera para metaprogramming)
- i18n system (Fluent con en-US, es-ES)
- Multi-format serialization (JSON/YAML/TOML/Nickel)

---

## 2. Propósito y Problema que Resuelve

### 2.1 Problema Space Completo

**Problema Principal**: La configuración de aplicaciones, proyectos y scripts requiere:
1. Recolección interactiva de datos del usuario
2. Validación tipada de inputs
3. Transformación entre formatos (schemas → forms → configs)
4. Adaptación a diferentes contextos (CLI scripts, TUI setup, Web interfaces)
5. Organización con componentes, templates, documentación

**Problemas Secundarios**:
- Herramientas existentes limitadas a un solo backend (CLI-only o Web-only)
- No hay integración con lenguajes de configuración tipados (Nickel, KCL)
- Forms completos ineficientes para capturar un solo valor
- Prompts individuales no escalables para setup complejos
- Falta de preservación de type contracts entre transformaciones
- Configuración manual propensa a errores de tipo

### 2.2 Solución Propuesta

**Enfoque Único**:
```
Nickel Schema (typed, validated, documented)
    ↓ [nickel-to-form]
TOML Form Definition (declarative, reusable)
    ↓ [interactive collection]
User Dialog (CLI/TUI/Web según contexto)
    ↓ [validation + transformation]
Validated Output (JSON/YAML/TOML/Nickel)
    ↓ [consumption]
Application/Script/System
```

**Flexibilidad Clave**:
- **Single Prompt**: `nickelconf prompt --type password "API Key"` → captura un valor
- **Complete Form**: `nickelconf form setup.toml --backend tui` → multi-field wizard
- **Nickel Workflow**: Schema → Form → Config con type preservation

### 2.3 Casos de Uso Concretos

#### 1. Application Settings
- **User**: Developer configurando nueva app
- **Escenario**: Primera instalación de app Rust, necesita DB credentials, API keys, feature flags
- **Solución**: Nickel schema define settings → TUI form para setup inicial → config.yaml generado
- **Valor**: Type-safety, validación, documentación incluida en schema

#### 2. Script Inputs
- **User**: DevOps engineer escribiendo Nushell script de deploy
- **Escenario**: Script necesita environment, region, instance type
- **Solución**: CLI prompts individuales integrados en script → validated JSON output
- **Valor**: Inputs validados on-the-fly, integración natural con script flow

#### 3. Project Configuration
- **User**: Tech lead inicializando nuevo proyecto
- **Escenario**: Proyecto necesita 20+ settings (CI/CD, testing, deployment, monitoring)
- **Solución**: Nickel schema organizado con components → TUI complete form → project.toml
- **Valor**: Configuración completa guiada, validación, defaults inteligentes

#### 4. Web-Based Setup
- **User**: SaaS admin configurando tenant
- **Escenario**: Configuración de tenant via web interface
- **Solución**: Same TOML form → Web backend → Settings guardados en DB
- **Valor**: Mismo form definition, diferente contexto de uso

#### 5. Infrastructure as Code
- **User**: SRE provisionando recursos cloud
- **Escenario**: Crear configuración Terraform/Nickel para nueva infra
- **Solución**: Interactive prompts → Nickel output con contracts → Terraform consumption
- **Valor**: Type-safe IaC generation, validation antes de apply

---

## 3. Arquitectura y Tecnología

### 3.1 Tech Stack Completo

**Core Language**: Rust 2021, MSRV 1.70+

**Crate Structure** (Workspace):
```
typedialog/
├── crates/
│   ├── typedialog-core/     # Core library + backend trait
│   │   ├── form engine (8 input types)
│   │   ├── FormBackend trait
│   │   ├── Nickel integration modules
│   │   ├── Template engine (Tera)
│   │   ├── i18n system (Fluent)
│   │   └── Serialization (serde ecosystem)
│   ├── typedialog/          # CLI binary
│   │   └── InquireBackend impl
│   ├── typedialog-tui/      # TUI binary
│   │   └── RatatuiBackend impl
│   └── typedialog-web/      # Web server binary
│       └── AxumBackend impl
```

**Dependencies Clave**:
- `inquire` - Terminal prompts (CLI backend)
- `ratatui` + `crossterm` - Terminal UI (TUI backend)
- `axum` + `tower` - Web server (Web backend)
- `serde` ecosystem - Serialization (JSON/YAML/TOML)
- `tera` - Template engine (Jinja2-like)
- `fluent` + `fluent-bundle` - i18n/localization
- `clap` - CLI argument parsing
- `chrono` - Date/time handling

**Backend Pattern** (Trait-based abstraction):
```rust
pub trait FormBackend {
    fn execute_field(&mut self, field: &FormField) -> Result<Value>;
    fn execute_form_complete(&mut self, form: &Form) -> Result<HashMap<String, Value>>;
}

// Implementations:
impl FormBackend for InquireBackend { ... }   // CLI
impl FormBackend for RatatuiBackend { ... }   // TUI
impl FormBackend for AxumBackend { ... }      // Web
```

### 3.2 Características Técnicas Distintivas

#### 1. Nickel Integration (Bidirectional)
- **nickel-to-form**: Parse Nickel schemas → Extract metadata → Generate TOML forms
- **form-to-nickel**: Convert form results → Generate Nickel code with contracts
- **Contract Preservation**: `std.string.NonEmpty`, `std.number.between` mantenidos
- **Component Support**: Nickel imports, merging, templates soportados

#### 2. Multi-Backend Architecture
- **Same Form Definition**: Un TOML form funciona en CLI, TUI, Web
- **Identical Output**: Todos los backends producen mismo JSON/YAML/TOML
- **Display Modes**: FieldByField (step-by-step) o Complete (all at once)
- **Backend Selection**: `--backend cli|tui|web` en runtime

#### 3. Form Engine Features
- **8 Input Types**: text, confirm, select, multiselect, password, custom, editor, date
- **Conditional Logic**: Fields con `depends_on` para flujo dinámico
- **Validation**: Regex, length, range, custom validators
- **Defaults**: Static, dynamic (desde otras respuestas), computed
- **Grouping**: Semantic grouping para mejor UX

#### 4. i18n System
- **Fluent-based**: `.ftl` files para traducciones
- **Languages**: en-US (default), es-ES
- **Scopes**: Form UI, field labels, validation messages, help text
- **Fallback**: Graceful degradation a inglés

#### 5. Template System
- **Tera Engine**: Jinja2-like syntax para metaprogramming
- **Nickel Templates**: `.ncl.j2` files para código generation
- **Variable Substitution**: Form results inyectados en templates
- **Conditionals/Loops**: Lógica de template para código complejo

### 3.3 Formatos Soportados

**Input Formats**:
- TOML (form definitions)
- Nickel (schemas para form generation)

**Output Formats**:
- JSON (app configs, API consumption)
- YAML (configs, Kubernetes, Ansible)
- TOML (Rust configs, general settings)
- Nickel (type-safe configs con contracts)
- Plain text (simple key=value)

---

## 4. Análisis de Mercado y Posicionamiento

### 4.1 Target Audience Detallado

**Audiencia Primaria**:

1. **Application Developers** (40%)
   - Stack: Rust, Go, Python apps
   - Need: Settings management con type-safety
   - Pain: Manual config files propensa a errores
   - Value: Nickel schemas + interactive collection + validated output

2. **Script Creators** (30%)
   - Stack: Nushell, Bash, Python scripts
   - Need: Interactive inputs para scripts
   - Pain: Validación manual, error handling repetitivo
   - Value: Validated prompts con minimal code

3. **DevOps/SRE Engineers** (20%)
   - Stack: Terraform, Kubernetes, Ansible
   - Need: Interactive IaC generation
   - Pain: Complex configs, no validation hasta runtime
   - Value: Type-safe config generation, Nickel contracts

4. **Project/Team Leads** (10%)
   - Stack: Project setup, team onboarding
   - Need: Consistent project configuration
   - Pain: Manual setup guides, config drift
   - Value: Reproducible project setup con forms

**Audiencia Secundaria**:
- CLI tool developers agregando interactive features
- SaaS developers para user onboarding/config
- System administrators para server setup wizards

### 4.2 Competitive Landscape

**Categorías de Competidores**:

1. **Terminal Prompt Libraries**: `inquire`, `dialoguer`, `questionary`
   - Gap: Solo prompts, no forms. No type-safety. No multi-backend.

2. **Form Libraries**: HTML forms, `react-hook-form`
   - Gap: Web-only. No CLI/TUI. No Nickel integration.

3. **Configuration Management**: Ansible, Terraform
   - Gap: IaC-specific. No general-purpose forms. No type preservation.

4. **Schema Languages**: JSON Schema, Nickel, KCL
   - Gap: Schema definition only, no interactive collection.

**Competitive Matrix**:

| Feature | typedialog | inquire | HTML forms | Ansible | Nickel |
|---------|-------------|---------|------------|---------|--------|
| Interactive prompts | ✅ | ✅ | ❌ | ⚠️ | ❌ |
| Complete forms | ✅ | ❌ | ✅ | ⚠️ | ❌ |
| Multi-backend | ✅ (3) | ❌ | ❌ | ❌ | ❌ |
| Type-safe schemas | ✅ | ❌ | ❌ | ⚠️ | ✅ |
| Bidirectional schema | ✅ | ❌ | ❌ | ❌ | ❌ |
| Multi-format output | ✅ (4) | ❌ | ⚠️ | ⚠️ | ✅ (1) |
| i18n support | ✅ | ❌ | ⚠️ | ✅ | ❌ |
| Template system | ✅ | ❌ | ❌ | ✅ | ✅ |
| Declarative forms | ✅ | ❌ | ✅ | ⚠️ | N/A |

### 4.3 Value Propositions Completo

**Para Developers**:
- ✅ Type-safe configuration desde día 1 (Nickel schemas)
- ✅ Menos código de validación manual (schemas auto-validan)
- ✅ Documentación incluida en schemas (contratos son docs)
- ✅ Multi-format output (una fuente, múltiples consumidores)

**Para DevOps/SRE**:
- ✅ Interactive IaC generation (menos errores de config)
- ✅ Validación antes de apply (Nickel contracts)
- ✅ Reproducible setup (TOML forms versionables)
- ✅ Script integration (CLI prompts en pipelines)

**Para Organizations**:
- ✅ Consistent configuration (same forms across projects)
- ✅ Reduced onboarding time (guided setup wizards)
- ✅ Auditability (form definitions + results traceable)
- ✅ i18n support (international teams)

**Unique Selling Points**:
1. **Nickel Integration** - Único en mercado
2. **Multi-Backend Flexibility** - Mismo form, diferentes contextos
3. **Forms + Prompts** - No forzado a elegir uno u otro
4. **Type-Safe Pipeline** - Contracts preserved end-to-end
5. **Production-Ready** - i18n, templates, validación, docs

---

## 5. Capacidades y Características

### 5.1 Functional Capabilities

**Input Collection**:
- ✅ 8 tipos de prompts (text, password, select, multiselect, confirm, custom, editor, date)
- ✅ Forms declarativos en TOML
- ✅ Conditional logic (depends_on)
- ✅ Dynamic defaults (computed fields)
- ✅ Validation (regex, range, length, custom)
- ✅ Help text y documentación inline

**Backend Support**:
- ✅ CLI - inquire-based terminal prompts (stdin fallback)
- ✅ TUI - ratatui full-screen interface (3-panel layout, Tab navigation)
- ✅ Web - axum + HTMX browser forms (RESTful API)
- ✅ Display modes: FieldByField, Complete

**Nickel Workflow**:
- ✅ nickel-to-form: Schema → TOML form generation
- ✅ form execution: Interactive collection
- ✅ form-to-nickel: Results → Nickel code generation
- ✅ Contract preservation: Type constraints maintained
- ✅ Component support: Imports, merging, templates

**Output Formats**:
- ✅ JSON (structured data, API consumption)
- ✅ YAML (configs, k8s, ansible)
- ✅ TOML (rust configs, settings)
- ✅ Nickel (type-safe configs)
- ✅ Text (simple key=value)

**i18n & Templates**:
- ✅ Fluent-based localization (en-US, es-ES)
- ✅ Tera template engine
- ✅ Nickel template metaprogramming (.ncl.j2)
- ✅ Variable substitution
- ✅ Conditional rendering

### 5.2 Non-Functional Capabilities

**Performance**:
- Fast compilation (Rust, release build <30s)
- Low memory footprint (CLI <5MB, TUI <10MB)
- Minimal startup time (<100ms)

**Reliability**:
- 80+ passing tests (unit + integration)
- Type-safe Rust (no runtime crashes)
- Graceful error handling
- Fallback behaviors (stdin, default values)

**Usability**:
- Intuitive TOML form syntax
- Clear error messages
- Help text contextual
- i18n for international users

**Maintainability**:
- Modular workspace structure
- Clean trait-based architecture
- Comprehensive documentation
- Example forms included

**Portability**:
- Cross-platform (Linux, macOS, Windows)
- Single binary distribution
- No runtime dependencies
- Docker support

---

## 7. Métricas y Success Criteria

### 7.1 Technical Metrics

**Code Quality**:
- Test coverage > 80%
- Zero clippy warnings (enforce)
- Clean compilation all features
- Documentation coverage > 90%

**Performance**:
- Binary size < 15MB (release)
- Startup time < 100ms
- Memory usage < 20MB (TUI)
- Form rendering < 50ms

### 7.2 Adoption Metrics

**Community**:
- GitHub stars > 100 (first 6 months post-publish)
- crates.io downloads > 1000/month
- Active issues/PRs
- Contributor growth

**Usage**:
- Example forms created by users
- Integration stories shared
- Blog posts/tutorials written
- Conference talks

### 7.3 Quality Metrics

**Reliability**:
- Bug reports < 5/month
- Critical bugs = 0
- Response time < 48h
- Fix time < 7 days (non-critical)

**User Satisfaction**:
- Positive feedback ratio > 80%
- Feature request alignment
- Documentation clarity
- Ease of use reports

---

## 8. Roadmap y Future Considerations

### 8.1 Immediate Focus (v0.1.x)

**Naming Decision**:
- Decide: nickelconf vs nickeltalk vs keep typedialog
- Execute: Rename if chosen
- Update: All documentation and messaging

**Stabilization**:
- Bug fixes from early users
- Documentation improvements
- Example forms expansion
- Performance optimizations

### 8.2 Near-term Enhancements (v0.2.x)

**Nickel Enhancements**:
- Deeper schema introspection
- More contract types supported
- Component template library
- Schema validation improvements

**Backend Improvements**:
- TUI navigation enhancements
- Web backend styling/theming
- CLI colored output options
- Performance optimizations

**New Features**:
- Form composition (reusable sections)
- Field dependencies (advanced logic)
- Custom validators library
- Plugin system for custom fields

### 8.3 Long-term Vision

**Ecosystem**:
- Form marketplace (shared forms)
- IDE integrations (VSCode extension)
- CI/CD integrations
- Cloud service (hosted forms)

**Technology**:
- KCL integration (like Nickel)
- CUE language support
- GraphQL schema support
- Database schema integration

**Beyond Configuration**:
- Survey/questionnaire system
- User onboarding workflows
- Admin panel generation
- API client generation

---

## Conclusión

typedialog es un proyecto maduro y bien posicionado que resuelve un problema real en la gestión de configuración. Su diferenciador único - la integración bidireccional con Nickel combinada con múltiples backends - lo posiciona de manera única en el mercado.

El próximo paso crítico es una decisión de naming estratégica que refuerce esta posición única y comunique claramente el valor propuesto al mercado target.