syntaxis/docs/provision/index.md

📚 Índice de Documentación - Provisioning & Orquestación de Syntaxis

Última actualización: 2025-11-20 Estado: Documentación completa y lista para implementación

---

🎯 Lectura Recomendada por Tipo de Usuario

Para Arquitectos / Tech Leads

Lectura en orden:

1. README_CLEAN.md (5 min)

   • Resumen ejecutivo del problema y solución
   • Diagrama de 3 capas
   • Tabla comparativa: Antes vs Después

2. SOLUTION_ARCHITECTURE_CORRECT.md (20 min)

   • Arquitectura detallada
   • Ejemplos reales basados en n8n
   • Patrones de integración

3. PROVCTL_KCL_INTEGRATION.md (15 min)

   • Responde: "¿Provctl necesita cambios?"
   • Muestra separación de concerns
   • Opciones de generación TOML

4. IMPLEMENTATION_PLAN.md (25 min)

   • Roadmap completo con pasos
   • Archivos específicos a crear
   • Checklist de implementación

---

Para Desarrolladores Implementando

Lectura en orden:

1. IMPLEMENTATION_PLAN.md (Principal)

   • Pasos concretos a realizar
   • Ubicaciones exactas de archivos
   • Ejemplos de código para cada archivo

2. CURRENT_STATE_ANALYSIS.md (Referencia)

   • Qué existe hoy
   • Qué está en provisioning
   • Qué está en provctl

3. SOLUTION_ARCHITECTURE_CORRECT.md (Referencia)

   • Patrones completos
   • Ejemplos reales (n8n)
   • Decisiones arquitectónicas

---

Para Revisar Contexto Histórico

Solo si necesitas entender cómo llegamos aquí:

• THE_REAL_PROBLEM.md - Análisis iterativo del problema real
• PROBLEM_STATEMENT_CORRECT.md - Por qué Docker no es suficiente

⚠️ NO LEER (documentos descartables):

• ARCHITECTURE_REVISION.md - Problema incorrecto
• KCL_REST_API_DESIGN.md - Solución para problema incorrecto
• MULTI_LAYER_VALIDATION.md - Enfoque incorrecto
• VALIDATION_REGISTRY_NUSHELL.md - Enfoque incorrecto

---

📋 Guía de Documentos Actuales

✅ DOCUMENTOS PRINCIPALES (LEER ESTOS)

1. README_CLEAN.md

Propósito: Resumen ejecutivo Audiencia: Todos (especialmente managers/leads) Duración: 5-10 minutos Contiene:

• El problema en una página
• Solución de 3 capas visual
• Comparación antes/después
• Próximos pasos

---

2. SOLUTION_ARCHITECTURE_CORRECT.md

Propósito: Arquitectura detallada Audiencia: Arquitectos, implementadores Duración: 20-30 minutos Contiene:

• Explicación de cada capa
• Estructura de directorios exacta
• Código de ejemplo (KCL, TOML)
• Patrones reales de n8n
• Decisiones arquitectónicas

---

3. CURRENT_STATE_ANALYSIS.md

Propósito: Análisis de situación actual Audiencia: Quienes necesitan entender qué existe Duración: 15-20 minutos Contiene:

• Qué hace provisioning hoy
• Qué hace provctl hoy
• Dónde está el TOML catalog
• Quién lo consume
• Brecha identificada

---

4. PROVCTL_KCL_INTEGRATION.md

Propósito: Responder pregunta crítica sobre integración Audiencia: Todos (especialmente quienes dudan sobre cambios a provctl) Duración: 15-20 minutos Contiene:

• Respuesta: "¿Provctl necesita cambios?" → NO
• Cómo funciona la generación TOML
• Dos opciones (build-time vs runtime)
• Ejemplo concreto: KCL → TOML
• Beneficios de separación de concerns

---

5. IMPLEMENTATION_PLAN.md

Propósito: Guía paso a paso para implementación Audiencia: Desarrolladores implementando Duración: 25-40 minutos (lectura + ejecución) Contiene:

• Fase 1: TaskService en provisioning (CAPA 1)
  • Estructura exacta de directorios
  • Contenido de cada archivo KCL
  • Archivos de configuración
  • Scripts de instalación
• Fase 2: Configs provctl (CAPA 2)
  • TOML para cada ambiente
  • Variables de entorno
  • Health checks
• Fase 3: Presets en syntaxis (CAPA 3)
  • KCL para presets declarativos
  • 4 modos (local, dev, staging, prod)
• Fase 4: Integración
  • Cómo conectan las capas
  • Generación TOML
  • Consumo en installer
• Checklist completo
• Matrices de decisión

---

⚠️ DOCUMENTOS CONTEXTO (LECTURA OPCIONAL)

THE_REAL_PROBLEM.md

Propósito: Entender la evolución del análisis Cuándo leer: Si quieres ver cómo llegamos al análisis correcto Contiene:

• Descripción de provisioning vs provctl
• El problema identificado
• Preguntas que surgieron

---

PROBLEM_STATEMENT_CORRECT.md

Propósito: Explicar por qué Docker/docker-compose no son suficientes Cuándo leer: Si necesitas convencer al equipo por qué esta arquitectura Contiene:

• Por qué Docker/compose fallan
• El flujo correcto de 3 partes
• Comparación TOML vs solución correcta

---

❌ DOCUMENTOS DESCARTABLES (NO LEER)

Estos fueron generados basados en un entendimiento incorrecto del problema:

• ARCHITECTURE_REVISION.md - Asume problema incorrecto (recompilación de syntaxis)
• KCL_REST_API_DESIGN.md - Propone REST API innecesario
• MULTI_LAYER_VALIDATION.md - Enfoque incorrecto de validación
• VALIDATION_REGISTRY_NUSHELL.md - Solución para problema incorrecto

Por qué están mal:

• Se basaban en entendimiento de que TOML catalog debería ser "fuente de verdad" para syntaxis
• No reconocían que el catalog ya existe y es consumido por herramientas distintas
• No entendían que syntaxis podría ser un taskservs sin modificación

---

🎯 Resumen de Decisiones Arquitectónicas

Decisión 1: Syntaxis como TaskService

Pregunta: ¿Debería syntaxis ser un taskservs de provisioning? Respuesta: ✅ SÍ Razón: Permite integración limpia sin cambios forzados Referencia: SOLUTION_ARCHITECTURE_CORRECT.md, sección "Capa 1"

---

Decisión 2: Provctl No Necesita Cambios

Pregunta: ¿Hay que modificar provctl para que entienda KCL? Respuesta: ✅ NO Razón: Provisioning genera TOML, provctl lo consume Referencia: PROVCTL_KCL_INTEGRATION.md

---

Decisión 3: Formato para Presets

Pregunta: ¿KCL o YAML para deployment-presets.kcl? Respuesta: ✅ KCL (aprovecha inversión existente) Razón: Type-safe, validación nativa, consistencia con provisioning Referencia: IMPLEMENTATION_PLAN.md, sección "Matrices de Decisión"

---

Decisión 4: Generación TOML

Pregunta: ¿Cuándo generar TOML desde KCL (build vs runtime)? Respuesta: ✅ Build time (opción recomendada) Razón: Performance, consistency, debuggability Referencia: IMPLEMENTATION_PLAN.md, sección "Paso 4.1"

---

📊 Comparación Visual

ANTES (Problemático)

syntaxis/
└── configs/
    └── services-catalog.toml (436 líneas)
         ↑ consumido por...
         ├─ provisioning tools (catalog.rs)
         ├─ NuShell scripts (service-catalog.nu)
         └─ ❌ NO por syntaxis core
         └─ ❌ NO por provctl

PROBLEMA:
- TOML compilado (no es eficiente)
- No es fuente de verdad
- No hay presets claros
- Requiere recompilación para cambios

DESPUÉS (Solución)

CAPA 1: provisioning/extensions/taskservs/development/syntaxis/
└── kcl/syntaxis.k (definición)
     ↓ genera
CAPA 2: provctl/examples/stage1-extended-definitions/
└── syntaxis-*.toml (TOML consumible)
     ↑ configura
CAPA 3: syntaxis/configs/
└── deployment-presets.kcl (UX del developer)

BENEFICIOS:
✅ KCL como fuente de verdad
✅ Generación TOML automática
✅ Presets claros (local/dev/staging/prod)
✅ Sin recompilación (cambiar = guardar KCL)
✅ Sin cambios a provisioning o provctl
✅ Reutilizable para otros proyectos

---

🚀 Roadmap de Implementación

Fase 1: TaskService Provisioning

Ubicación: /Users/Akasha/project-provisioning/provisioning/extensions/taskservs/development/syntaxis/ Archivos: 8 nuevos archivos KCL + scripts Duración estimada: 2-3 horas Referencia: IMPLEMENTATION_PLAN.md, Fase 1

Fase 2: Configuración provctl

Ubicación: /Users/Akasha/Development/provctl/examples/stage1-extended-definitions/ Archivos: 3 nuevos archivos TOML Duración estimada: 1 hora Referencia: IMPLEMENTATION_PLAN.md, Fase 2

Fase 3: Presets en Syntaxis

Ubicación: /Users/Akasha/Development/syntaxis/configs/ Archivos: 1 nuevo archivo KCL Duración estimada: 1 hora Referencia: IMPLEMENTATION_PLAN.md, Fase 3

Fase 4: Integración & Testing

Ubicación: Múltiples (provisioning build, syntaxis installer) Duración estimada: 3-4 horas Referencia: IMPLEMENTATION_PLAN.md, Fase 4

Total estimado: 7-11 horas de implementación

---

💡 Preguntas Frecuentes

P: ¿Necesito cambiar provctl?

R: NO. Provctl consume TOML generado desde KCL. Sin cambios. Referencia: PROVCTL_KCL_INTEGRATION.md

P: ¿Dónde va el código KCL?

R: /provisioning/extensions/taskservs/development/syntaxis/kcl/syntaxis.k Referencia: IMPLEMENTATION_PLAN.md, Paso 1.2

P: ¿Cómo sé qué debe ir en cada capa?

R:

• CAPA 1 (KCL): QUÉ es syntaxis, esquema, servicios
• CAPA 2 (TOML): CÓMO ejecutar (systemd, ports, env)
• CAPA 3 (KCL presets): PRESETS del usuario (local/dev/prod)

P: ¿Qué pasa si el usuario no tiene provisioning o provctl?

R: Fallback graceful. Mostrar guía manual. Referencia: IMPLEMENTATION_PLAN.md, Paso 4.2

P: ¿Es realmente "sin cambios" a provctl?

R: ✅ Sí. Provctl sigue consumiendo TOML como hoy. Referencia: PROVCTL_KCL_INTEGRATION.md, sección "Clave"

---

🔗 Navegación Rápida

Necesito...	Debo leer...
Resumen rápido (5 min)	README_CLEAN.md
Entender arquitectura completa	SOLUTION_ARCHITECTURE_CORRECT.md
Ver qué existe hoy	CURRENT_STATE_ANALYSIS.md
Confirmar provctl sin cambios	PROVCTL_KCL_INTEGRATION.md
Instrucciones paso a paso	IMPLEMENTATION_PLAN.md
Entender decisiones	PROBLEM_STATEMENT_CORRECT.md
Histórico de análisis	THE_REAL_PROBLEM.md

---

📝 Notas Finales

Qué aprendimos

1. El problema REAL: No hay forma declarativa para developer definir proyecto
2. La solución: 3 capas coherentes (KCL → TOML → Presets)
3. Key insight: Cada herramienta hace lo que sabe (provisioning genera, provctl ejecuta, syntaxis orquesta)
4. Sin cambios: Provisioning usa patrón existente, provctl consume TOML, solo nueva capa de presets

Qué hace especial esta solución

• ✅ Reutilizable: Otros proyectos pueden seguir mismo patrón
• ✅ Escalable: De local a distributed production sin rediseño
• ✅ Mantenible: Cambios = guardar archivo KCL
• ✅ Integrado: Aprovecha inversión existente en provisioning
• ✅ Flexible: Fallback graceful si faltan herramientas

---

Próximo paso: Leer IMPLEMENTATION_PLAN.md y comenzar Fase 1 (TaskService en provisioning)