syntaxis/docs/provision/readme-clean.md

📦 Documentación de Provisioning - Guía Limpia

Última actualización: 2025-11-20 Estado: Análisis correcto, solución lista

---

🎯 El Problema

Dockerfile / docker-compose son INSUFICIENTES porque:

❌ No definen CÓMO GESTIONAR servicios (systemd, provctl)
❌ No definen CÓMO VALIDAR salud
❌ No definen CÓMO ORQUESTAR múltiples máquinas
❌ No integran con PROVISIONING
❌ No escalan a diferentes contextos (local/dev/prod)
❌ No declaran requisitos de INFRA

✅ La Solución: Tres Capas Coherentes

CAPA 1: TaskService en provisioning (FUENTE DE VERDAD)

/provisioning/extensions/taskservs/development/syntaxis/
├── kcl/
│   ├── syntaxis.k          ← Schema (como n8n.k, postgres.k)
│   └── dependencies.k      ← Requisitos del sistema
├── default/
│   ├── install-syntaxis.sh ← Script de instalación
│   └── env-syntaxis.j2     ← Template de variables
└── examples/
    ├── syntaxis-dev.k      ← Config para desarrollo
    └── syntaxis-prod.k     ← Config para producción

Define: QUÉ es syntaxis, cómo se estructura, qué requisitos tiene Ejemplo: Como /provisioning/extensions/taskservs/development/n8n/ existente

---

CAPA 2: Config en provctl (GESTIÓN LOCAL)

/provctl/examples/stage1-extended-definitions/
├── syntaxis-local-dev.toml      ← Para desarrollo local
├── syntaxis-prod.toml           ← Para producción
└── syntaxis-staging.toml        ← Para staging

Define: CÓMO ejecutar syntaxis (systemd, health checks, ports, env) Ejemplo: Como /provctl/examples/minimal-app.toml existente

---

CAPA 3: Presets en syntaxis (UX DEL DEVELOPER)

syntaxis/configs/
├── deployment-presets.kcl    ← LOCAL / DEV / STAGING / PRODUCTION
└── (NO MÁS TOML COMPILADO)

Define: Qué servicios en cada contexto Resultado: syntaxis-installer --preset dev detecta automáticamente provctl/provisioning

---

🔗 Cómo Se Conectan

Developer elige preset
  ↓
syntaxis installer lee deployment-presets.kcl
  ├─ local  → CLI solamente (manual)
  ├─ dev    → provctl config (local automático)
  ├─ staging → provisioning (infra escalable)
  └─ prod   → provisioning + HA

Si "dev" (provctl):
  ├─ Detecta provctl disponible
  ├─ Lee provisioning taskserv (syntaxis.k)
  ├─ Genera config provctl (syntaxis-local-dev.toml)
  └─ Inicia servicios con systemd/launchd

Si "prod" (provisioning):
  ├─ syntaxis es un taskserv importable
  ├─ provisioning lo orquesta como su inversión lo permite
  └─ Resultado: Full stack enterprise

---

📊 Comparación

Aspecto	Antes (TOML compilado)	Después (3 Capas)
Definición	TOML → catalog.rs → ingestionable	KCL taskserv (como n8n)
Gestión local	❓ Desconocido	provctl TOML (como minimal-app)
Presets	❌ No existen	✅ KCL en syntaxis
Cambios	Recompilación continua	Solo guardar archivo
Consumible por	provisioning tools	provisioning, provctl, installer
DX	"¿Qué es este TOML?"	"Elige preset: dev/prod ✅"

---

📝 Documentos en Este Directorio

Lectura Necesaria

1. CURRENT_STATE_ANALYSIS.md

   • Análisis de qué existe hoy
   • Qué no existe
   • Hallazgos críticos

2. SOLUTION_ARCHITECTURE_CORRECT.md

   • Capa 1: TaskService (KCL schema)
   • Capa 2: Config provctl (TOML)
   • Capa 3: Presets (KCL)
   • Ejemplos reales basados en n8n y otros

3. PROBLEM_STATEMENT_CORRECT.md

   • Por qué Docker/compose no es suficiente
   • Qué define cada capa
   • Cómo se conectan

Documentos Descartables

• ARCHITECTURE_REVISION.md ❌ (problema hipotético incorrecto)
• KCL_REST_API_DESIGN.md ❌ (solución para problema incorrecto)
• MULTI_LAYER_VALIDATION.md ❌ (enfoque incorrecto)
• VALIDATION_REGISTRY_NUSHELL.md ❌ (enfoque incorrecto)
• THE_REAL_PROBLEM.md ❌ (análisis parcial)

---

🚀 Próximos Pasos

Paso 1: Crear TaskService en provisioning

mkdir -p provisioning/extensions/taskservs/development/syntaxis/kcl
mkdir -p provisioning/extensions/taskservs/development/syntaxis/default
mkdir -p provisioning/extensions/taskservs/development/syntaxis/examples

Copiar estructura de n8n y adaptarla

Paso 2: Crear config provctl

provctl/examples/stage1-extended-definitions/syntaxis-local-dev.toml

Basado en minimal-app.toml

Paso 3: Crear presets en syntaxis

syntaxis/configs/deployment-presets.kcl

Define: local/dev/staging/production

Paso 4: Integrar con syntaxis installer

Extender installer para:

• Leer presets
• Detectar provisioning/provctl
• Aplicar configuración automática

---

✨ Beneficio Final

Developer: "Instala syntaxis"
  ↓
syntaxis-installer

"¿Cómo?:
 1. local (CLI solamente)
 2. dev (Full stack local)
 3. staging (Multi-máquina)
 4. production (HA)"

Developer elige "dev"
  ↓
Installer detecta provctl
  ↓
Auto-configura servicios
  ↓
✅ "Listo para usar"

Sin Docker/compose requirements adicionales. Sin TOML compilado ingestionable. Sin recompilación.

---

📌 Decisión Crítica

¿Es el archivo declarativo KCL la fuente de verdad?

✅ SÍ - Así como n8n.k lo es para n8n, postgres.k lo es para PostgreSQL

¿Provctl puede leerlo?

✅ SÍ - Se genera TOML consumible por provctl (como minimal-app.toml)

¿Provisioning puede usarlo?

✅ SÍ - Es un taskserv, se integra como cualquier otro (postgres, redis, kubernetes)

¿Escala a otros proyectos?

✅ SÍ - Cada proyecto puede ser un taskserv externo en provisioning