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):

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.