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:

# 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?