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](CURRENT_STATE_ANALYSIS.md)**
   - Análisis de qué existe hoy
   - Qué no existe
   - Hallazgos críticos

2. **[SOLUTION_ARCHITECTURE_CORRECT.md](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](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

```bash
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

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

Basado en minimal-app.toml

### Paso 3: Crear presets en syntaxis

```bash
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