syntaxis/docs/provision/the-real-problem.md

# 🎯 EL PROBLEMA REAL: provctl vs project-provisioning

**Fecha**: 2025-11-20
**Propósito**: Entender por qué hay dos proyectos y cuál es el problema a resolver
**Estado**: Análisis crítico

---

## 🏗️ Los Dos Proyectos

### Proyecto 1: project-provisioning

**Ubicación**: `/Users/Akasha/project-provisioning`

**Propósito**: Infraestructura y configuración de provisioning

**Contiene**:
- ✅ Definiciones KCL para infraestructura (orquestación, auth, DNS, etc)
- ✅ Módulo `provctl-bridge` con `catalog.rs`
- ✅ TOML catalog de servicios (`services-catalog.toml`)
- ✅ Generadores de IaC (Docker, K8s, Terraform)
- ✅ Scripts de instalación y configuración

**Scope**: "Cómo se provisiona la infraestructura"

---

### Proyecto 2: provctl

**Ubicación**: `/Users/Akasha/Development/provctl`

**Propósito**: Orquestación de máquinas y control de servicios

**Contiene**:
- ✅ CLI para control local de servicios (systemd, launchd, PID files)
- ✅ SSH-based machine orchestration
- ✅ Deployment strategies (rolling, blue-green, canary)
- ✅ Health checks y monitoring
- ✅ REST API y Leptos dashboard
- ✅ 332+ tests pasando

**Scope**: "Cómo se orquestan máquinas y se controlan servicios"

---

## 🔴 EL PROBLEMA REAL

### El Problema Identificado

**Pregunta que planteas**:
> "Por qué se ha creado provctl si ya existe provisioning?"

**Respuesta**: Resuelven problemas DIFERENTES

```
project-provisioning:
  ¿QUÉ INSTALAR?  (definiciones, configuración)

provctl:
  ¿CÓMO EJECUTAR LO QUE INSTALÉ?  (control, orquestación, monitoreo)
```

**Ejemplo**:
```
project-provisioning te dice:
  "El servicio syntaxis-api debe correr con 2 replicas, puerto 3000, con estas vars env"

provctl te dice:
  "Para ejecutar eso, corre: systemctl start syntaxis-api"
  "Y si falla, reintenta con exponential backoff"
  "Y si sigue fallando, alertame"
```

### Lo Que FALTA

Ambos proyectos existen pero **NO hablan entre sí**:

```
┌─────────────────────────────────────────────┐
│ project-provisioning                        │
│ ├─ Sabe QUÉ instalar (catalog.toml)        │
│ ├─ Genera IaC (Docker, K8s, Terraform)     │
│ ├─ Configura servicios (vars, ports, etc)  │
│ └─ Expone via catalog-cli.rs               │
└─────────────────────────────────────────────┘
             ↓ (¿cómo??)
        FALTA CONEXIÓN
             ↓
┌─────────────────────────────────────────────┐
│ provctl                                     │
│ ├─ Sabe CÓMO ejecutar servicios            │
│ ├─ Maneja ciclo de vida (start/stop/restart)
│ ├─ Monitorea health                        │
│ ├─ Orquesta múltiples máquinas             │
│ └─ Expone via API + CLI                    │
└─────────────────────────────────────────────┘

RESULTADO: Dos sistemas independientes
```

---

## 🎯 El Plan que Mencionas

**"Plan: Enhanced syntaxis Installer con integración provctl"**

**Objetivos**:
1. ✅ Detección inteligente de provctl
2. ✅ Sistema de presets (local, dev, staging, production)
3. ✅ Generación de config declarativa
4. ✅ Fallback cuando provctl no está disponible
5. ✅ Templates de provisioning para diferentes contextos

**Esto SIGNIFICA**:
```
syntaxis installer
  ↓
"¿Quieres gestionar servicios automáticamente?"
  ├─ SÍ: usar provctl
  │  ├─ Detectar provctl
  │  ├─ Generar config para provctl
  │  ├─ Orchestrar servicios
  │  └─ Monitorear
  │
  └─ NO: Manual
     ├─ Mostrar guía
     ├─ Generar scripts
     └─ Usuario hace todo a mano
```

---

## 🔗 La Conexión Que Falta

### HOY (Desconectado)

```
syntaxis/configs/services-catalog.toml
  └─ Define: 6 servicios

catalog-cli (provctl-bridge)
  └─ Lee: services-catalog.toml
  └─ Genera: Docker/K8s/Terraform

provctl CLI
  └─ Ignora: services-catalog.toml
  └─ Sabe: cómo ejecutar servicios (local)

syntaxis installer
  └─ No sabe: de provctl
  └─ No sabe: de servicios
```

### LO QUE SE NECESITA

```
syntaxis installer
  ↓
Leer: services-catalog.toml
  ├─ "¿Provctl está disponible?"
  │  ├─ SÍ:
  │  │  ├─ Generar config provctl
  │  │  ├─ Llamar: provctl config apply
  │  │  └─ Resultado: servicios gestionados
  │  │
  │  └─ NO:
  │     ├─ Mostrar guía manual
  │     ├─ Generar scripts
  │     └─ Usuario los ejecuta manualmente
  │
  └─ Generar presets:
     ├─ local: CLI solo
     ├─ dev: CLI + TUI + API + SurrealDB
     ├─ staging: API + Dashboard + SurrealDB
     └─ production: API + SurrealDB + NATS + HA
```

---

## 📊 Visión Actual vs Propuesta

### ACTUAL (Hoy)

```
El TOML catalog existe pero:
✗ syntaxis core NO lo usa
✗ provctl NO lo sabe
✓ provisioning tools lo leen (catalog-cli)
✓ NuShell scripts lo exploran

Resultado: Catalog es documentación, no fuente de verdad operativa
```

### PROPUESTA (Plan)

```
El TOML catalog sería:
✓ syntaxis installer lo leería
✓ provctl lo consumiría (para orchestration)
✓ provisioning tools lo generan
✓ Presets definidos en él

Resultado: Catalog es fuente de verdad para
  - QUÉ instalar (project-provisioning)
  - CÓMO ejecutar (provctl)
  - QUÉ presets usar (syntaxis installer)
```

---

## 🚨 Las Preguntas Correctas

### 1. ¿Cuál es el propósito del catalog?

**Opciones**:
- A) Documentación (está bien como está)
- B) Definición de presets (para sintaxis installer)
- C) Fuente de verdad para provctl
- D) Todo lo anterior

### 2. ¿Debería provctl leer el catalog?

**Si SÍ**:
```
provctl config apply --from-catalog syntaxis-dev
  ↓
  Lee services-catalog.toml
  ↓
  Genera configuración local
  ↓
  Inicia servicios
```

**Si NO**:
```
provctl config apply --from-file my-services.toml
  ↓
  Usuario copia servicios a archivo separado
  ↓
  Duplicación de definiciones
```

### 3. ¿Debería syntaxis installer usar provctl?

**Si SÍ**:
```
syntaxis-installer --preset dev
  ↓
  Detecta provctl disponible
  ↓
  Usa provctl para orchestration automática
  ↓
  Servicios se inician automáticamente
```

**Si NO**:
```
syntaxis-installer --preset dev
  ↓
  Muestra guía manual
  ↓
  Usuario corre comandos manualmente
```

---

## 💡 Propuesta de Solución

### Fase 1: Clarificar

Responder:
1. ¿Es el catalog TOML la fuente de verdad?
2. ¿Provctl debe consumirlo?
3. ¿Sintaxis installer debe usar provctl?

### Fase 2: Conectar

Si respuestas son SÍ:
1. Extender `catalog.rs` para exportar formato que provctl entienda
2. Integrar lectura de catalog en provctl CLI
3. Agregar soporte en syntaxis installer para detectar/usar provctl

### Fase 3: Validar

Tests de integración:
```bash
# Generar config desde catalog
provctl config --from-catalog syntaxis-dev

# Validar configuración
provctl config validate

# Aplicar y monitorear
provctl config apply
provctl status --all
```

---

## 📝 Resumen

**El problema REAL es**:

> Tenemos dos herramientas potentes (project-provisioning y provctl) pero desconectadas. El catalog TOML podría ser el puente pero:
>
> 1. ❌ No está claro cuál es su propósito
> 2. ❌ provctl no lo consume
> 3. ❌ syntaxis installer no sabe de él
> 4. ❌ No hay "fuente de verdad" única

**La solución REAL requiere**:

> Decidir si el catalog es "fuente de verdad" y si es así:
>
> 1. ✅ Conectar project-provisioning → catalog
> 2. ✅ Conectar provctl → catalog
> 3. ✅ Conectar syntaxis installer → catalog
> 4. ✅ Crear "presets" como combinaciones de servicios

**Lo que NO es el problema**:
- ❌ KCL vs TOML
- ❌ REST API para catalog (puede ser util pero no es el problema)
- ❌ Multi-lenguaje support (util pero no core)
- ❌ Recompilación (no ocurre)

---

**PRÓXIMA DECISIÓN**: ¿El catalog TOML es la fuente de verdad para todo, o solo documentación?