syntaxis/docs/provision/current-state-analysis.md

📊 ANÁLISIS DEL ESTADO ACTUAL

Fecha: 2025-11-20 Propósito: Evaluación objetiva de qué existe realmente hoy Estado: Revisión crítica (sin generar nuevas propuestas)

---

🎯 Diagrama ACTUAL (No Ideal)

┌─────────────────────────────────────────────────────────────┐
│ SYNTAXIS (Rust monorepository)                              │
│ ─────────────────────────────────────────────────────────── │
│                                                              │
│ /Users/Akasha/Development/syntaxis/                         │
│ └── configs/services-catalog.toml  ← SOURCE OF TRUTH ACTUAL │
│     - 6 servicios definidos en TOML                         │
│     - 4 patrones de deployment                              │
│     - 6 grupos de servicios                                 │
│     - Puertos y networking config                           │
│                                                              │
│ core/crates/syntaxis-core/                                  │
│ └── src/persistence/ [TODO: search for catalog usage]       │
│                                                              │
│ core/crates/cli/                                            │
│ └── CONSUME: configs/services-catalog.toml (si lo hace)     │
│                                                              │
│ core/crates/tui/                                            │
│ └── CONSUME: configs/services-catalog.toml (si lo hace)     │
│                                                              │
│ core/crates/syntaxis-api/                                   │
│ └── CONSUME: configs/services-catalog.toml (si lo hace)     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ PROJECT-PROVISIONING (Otro repositorio)                     │
│ ─────────────────────────────────────────────────────────── │
│                                                              │
│ /Users/Akasha/project-provisioning/                         │
│ provisioning/platform/provctl-bridge/                       │
│ └── src/catalog.rs                                          │
│     - ServiceCatalog struct (lee TOML)                      │
│     - 3 generadores de código (Docker, K8s, TF)             │
│     - Tests: 34/34 passing ✅                               │
│                                                              │
│ └── examples/catalog-cli.rs                                 │
│     - CLI tool que apunta a syntaxis TOML                   │
│     - const CATALOG_PATH = /Users/.../services-catalog.toml │
└─────────────────────────────────────────────────────────────┘

CONEXIÓN ACTUAL:
    catalog-cli.rs (provctl-bridge)
         ↓
    reads: /Users/Akasha/Development/syntaxis/configs/services-catalog.toml
         ↓
    ServiceCatalog::from_file()
         ↓
    Genera Docker/K8s/Terraform
         ↓
    Tests pasan ✅

---

✅ Lo Que SÍ Funciona Hoy

1. Archivo Central TOML (CONFIRMADO)

Ubicación: /Users/Akasha/Development/syntaxis/configs/services-catalog.toml

Consumidores CONFIRMADOS:

• ✅ catalog-cli.rs en provctl-bridge
• ✅ scripts/provisioning/service-catalog.nu (NuShell)
• ✅ scripts/provisioning/test-catalog.nu (NuShell)

Consumidores en syntaxis core: ❌ NINGUNO ENCONTRADO

• Búsqueda realizada: No hay referencias a "catalog" en /core/crates

Contenido (6 servicios):

• ✅ syntaxis-cli
• ✅ syntaxis-tui
• ✅ syntaxis-api
• ✅ syntaxis-dashboard
• ✅ surrealdb
• ✅ nats

Estructura: TOML con secciones claras

• [service.xxx] - Definición del servicio
• [groups.xxx] - Agrupaciones
• [pattern.xxx] - Patrones de deployment
• [ports] - Mapeo de puertos

2. Módulo Rust (provctl-bridge)

Archivo: /Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge/src/catalog.rs

Estructura:

pub struct ServiceCatalog {
    version: CatalogVersion,
    service: HashMap<String, ServiceDefinition>,
    preset: Option<HashMap<String, PresetDefinition>>,
    group: Option<HashMap<String, GroupDefinition>>,
    // ... más campos
}

impl ServiceCatalog {
    pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, ...> {
        let contents = fs::read_to_string(path)?;
        let catalog: ServiceCatalog = toml::from_str(&contents)?;
        Ok(catalog)
    }
}

Métodos existentes:

• from_file() - Carga TOML
• get_service() - Obtiene servicio
• get_preset_services() - Obtiene servicios de preset
• service_names() - Lista de servicios
• export_preset_yaml() - Exporta a YAML
• Generadores: Docker, Kubernetes, Terraform

3. CLI Tool (catalog-cli)

Ubicación: /Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge/examples/catalog-cli.rs

Comandos (8 funcionando):

list              - Listar servicios
show <name>       - Detalles de servicio
validate          - Validar integridad
generate <fmt>    - Generar IaC (docker, kubernetes, terraform)
patterns          - Listar patrones
ports             - Mapeo de puertos
groups            - Grupos de servicios
help              - Ayuda

Estado: 34/34 tests pasando ✅

4. Generadores de Código

Formatos soportados:

• ✅ Docker Compose
• ✅ Kubernetes manifests
• ✅ Terraform HCL

Estado: Tests de generación pasan ✅

---

❌ Lo Que NO Funciona / No Existe

1. Integración en syntaxis

Pregunta crítica: ¿Consume syntaxis el TOML de /Users/Akasha/Development/syntaxis/configs/services-catalog.toml?

Estado: 🔍 DESCONOCIDO - Necesario investigar

Búsqueda hecha:

grep -r "services-catalog" /Users/Akasha/Development/syntaxis --include="*.rs"

Resultado: Buscaré esto

2. API REST

Estado: ❌ NO EXISTE

Propuesto en KCL_REST_API_DESIGN.md:

// Propuesto pero no implementado
let routes = Router::new()
    .route("/api/v1/services", get(list_services))
    .route("/api/v1/patterns", get(list_patterns))
    // etc

Realidad: No hay servidor HTTP exponiendo el catalog

3. KCL Definitions

Estado: ✅ SÍ EXISTEN, PERO...

Ubicación: /Users/Akasha/project-provisioning/provisioning/kcl/services.k

IMPORTANTE: Este KCL es para PROVISIONING PLATFORM (infraestructura), NO para syntaxis services

• Define: ServiceRegistry schema para plataforma
• Categorías: "orchestration", "auth", "dns", "git", "registry", "api", "ui", "monitoring"
• Tipos: "platform", "infrastructure", "utility"
• Deployments: binary, docker, docker-compose, kubernetes, remote

NO ES para:

• Servicios de syntaxis (CLI, TUI, API, Dashboard, etc)
• El catalog TOML en /Users/Akasha/Development/syntaxis/configs/services-catalog.toml

Relación:

KCL en provisioning (services.k)
  └─ Para infraestructura de provisioning

TOML en syntaxis (services-catalog.toml)
  └─ Para servicios de syntaxis

Son INDEPENDIENTES, NO se sincronizan

4. Sincronización KCL ↔ TOML

Estado: ❌ NO EXISTE

Preguntas sin responder:

• ¿Dónde vivía el catalog antes en provisioning?
• ¿Se duplica en KCL?
• ¿Se sincroniza?

---

🔴 Problemas Reales Identificados

Problema 1: Recompilación para cambios

Situación:

# Para cambiar el catalog hoy:
1. Edit /Users/Akasha/Development/syntaxis/configs/services-catalog.toml
2. ¿syntaxis se da cuenta automáticamente? ← NO SABEMOS
3. ¿syntaxis recompila? ← PROBABLEMENTE

Impacto: Si cambias TOML, necesitas cargo build en syntaxis

Problema 2: Consumidor desconocido

Pregunta: ¿Quién lee el TOML en syntaxis?

Búsqueda necesaria:

grep -r "services-catalog\|ServiceCatalog" /Users/Akasha/Development/syntaxis/core --include="*.rs"

Problema 3: Múltiples fuentes de verdad (potencial)

Posibilidades:

Opción A: TOML en syntaxis ES la verdad
         └─ provisioning lo copia/referencia
         └─ KCL en provisioning NO existe

Opción B: KCL en provisioning ES la verdad
         └─ TOML en syntaxis se sincroniza
         └─ Posible desincronización

Opción C: Ambos existen independientemente
         └─ Riesgo alto de inconsistencia

Problema 4: Solo Rust puede consumir

Realidad:

• syntaxis (Rust) ✅ puede usar TOML directamente
• Node.js app ❌ ¿cómo obtiene el catalog?
• Python script ❌ ¿cómo obtiene el catalog?
• DevOps ✅ puede parsear TOML (manual)

---

📋 Investigaciones Necesarias

1️⃣ Búsqueda: ¿Cómo consume syntaxis el catalog?

# En syntaxis
find . -name "*.rs" -type f | xargs grep -l "catalog\|service.*definition" | head -20

Resultado esperado: Archivos que cargan o usan el TOML

2️⃣ Búsqueda: ¿Existe algo en provisioning?

find /Users/Akasha/project-provisioning -name "*.k" -type f | head -10

Resultado esperado: Saber si hay KCL definitions

3️⃣ Búsqueda: ¿Dónde está el primer catalog?

# En project-provisioning
find . -name "*catalog*" -o -name "*service*definition*" | grep -v target

Resultado esperado: Dónde vivía el catalog originalmente

4️⃣ Lectura: ¿Qué hace el catalog-cli realmente?

# Ver qué comandos existen
cargo run --example catalog-cli -- list
cargo run --example catalog-cli -- show syntaxis-cli

Resultado esperado: Confirmar que está funcionando

---

🎯 Lo Que Debemos Entender

Antes de cualquier arquitectura:

1. ¿Dónde vive LA VERDAD hoy?

   • ¿En /Users/Akasha/Development/syntaxis/configs/services-catalog.toml?
   • ¿O en provisioning?
   • ¿O en ambos (y cómo se sincronizan)?

2. ¿Quién la consume?

   • syntaxis ← necesario confirmación
   • provisioning ← confirmado (catalog-cli)
   • Otros ← necesario identificar

3. ¿Cuál es el problema REAL?

   • ¿Recompilación de syntaxis cuando cambia TOML?
   • ¿Inconsistencia entre TOML y KCL?
   • ¿Apps no-Rust sin acceso al catalog?
   • ¿Otro problema?

4. ¿Qué cambio MÍNIMO resolvería el problema?

   • Extender catalog-cli para servir HTTP (REST API)?
   • Sincronizar TOML ↔ KCL?
   • Mover TOML a provisioning?
   • Crear bindings multi-lenguaje?

---

🚀 Próximos Pasos

PASO 1: Investigar syntaxis

# Ver si syntaxis usa el catalog
grep -r "services-catalog\|ServiceCatalog\|catalog\|service.*definition" \
  /Users/Akasha/Development/syntaxis/core \
  --include="*.rs" \
  | head -30

PASO 2: Investigar provisioning

# Ver si hay KCL definitions
find /Users/Akasha/project-provisioning \
  -name "*.k" \
  -type f \
  | head -20

PASO 3: Ejecutar catalog-cli

cd /Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge
cargo run --example catalog-cli -- list
cargo run --example catalog-cli -- validate

PASO 4: Entender el flujo actual

# ¿Qué tests hay?
ls -la /Users/Akasha/project-provisioning/provisioning/platform/provctl-bridge/tests/

---

🔴 HALLAZGOS CRÍTICOS (Basado en Investigación Real)

1. El TOML Catalog NO es consumido por syntaxis core

Hecho: No hay referencias a "catalog" en /Users/Akasha/Development/syntaxis/core/crates

Implicación:

• El TOML existe pero NO controla el comportamiento de syntaxis
• syntaxis está diseñado INDEPENDIENTEMENTE del catalog
• El catalog es para PROVISIONING/DEPLOYMENT, no para el código de syntaxis

2. El Catalog ES consumido por provisioning tools

Consumidores REALES:

• ✅ catalog-cli.rs - CLI tool que lee y genera IaC
• ✅ scripts/provisioning/service-catalog.nu - Script NuShell
• ✅ scripts/provisioning/test-catalog.nu - Tests NuShell

Propósito: Conocer qué servicios están disponibles para generar IaC

3. KCL existe PERO es para otra cosa

KCL en provisioning (/Users/Akasha/project-provisioning/provisioning/kcl/services.k):

• ✅ Define schema para infraestructura de provisioning platform
• ❌ NO define servicios de syntaxis
• ❌ NO se sincroniza con TOML catalog

Relación:

provisioning/kcl/services.k  (infra de provisioning)
           ↕
           X (NO sincroniza)
           ↕
syntaxis/configs/services-catalog.toml (servicios de syntaxis)

4. El "Problema Real" que definimos NO existe

Asunción Inicial: "¿Cambiar catalog requiere recompilación de syntaxis?"

Realidad:

• syntaxis NO lee el catalog TOML
• Cambiar el TOML NO afecta a syntaxis
• El catalog es para provisioning/deployment

---

📌 Conclusión Real

Hoy tenemos:

• ✅ Un TOML catalog en syntaxis (pero syntaxis NO lo usa)
• ✅ Tooling en provisioning que SÍ lo usa
• ✅ Generadores de IaC que funcionan
• ✅ Tests que pasan (34/34)
• ✅ Scripts NuShell para exploración

El "problema" de ARCHITECTURE_REVISION.md NO EXISTE:

• ✅ No hay acoplamiento Rust (sintaxis es independiente)
• ✅ No hay recompilación necesaria (no consume el catalog)
• ✅ No hay múltiples fuentes de verdad (el catalog es para provisioning)

Lo que SÍ hay:

• ✅ Dos sistemas SEPARADOS funcionando bien
  • syntaxis: código Rust independiente
  • provisioning: tools que entienden servicios

---

⚠️ Reevaluación Necesaria

Toda la arquitectura propuesta (KCL + REST API, etc) se basaba en problema que NO existe.

Preguntas correctas ahora:

1. ¿Cuál es el problema REAL que queremos resolver?

   • ¿Mejor documentation de servicios?
   • ¿API multi-lenguaje para descubrimiento?
   • ¿Sincronización entre entornos?
   • ¿Otra cosa?

2. ¿El catalog TOML está cumpliendo su propósito?

   • ¿Es usado por algo?
   • ¿Genera valor?
   • ¿Está sincronizado?

3. ¿Hay que hacer algo o está bien como está?

   • Provisioning tools funcionan ✅
   • Generación de IaC funciona ✅
   • Tests pasan ✅
   • ¿Qué está "roto"?

---

PRÓXIMA ACCIÓN: Entender cuál es el problema REAL que queremos resolver con este catalog.