syntaxis/docs/provision/provctl-kcl-integration.md

🔗 ¿Provctl Necesita Entender KCL?

Pregunta: ¿Hay que modificar provctl para que entienda KCL?

Respuesta: NO es necesario. Aquí está por qué:

---

🏗️ Arquitectura Sin Cambios a provctl

Capa 1: TaskService en provisioning (KCL)
  └─ File: /provisioning/extensions/taskservs/development/syntaxis/kcl/syntaxis.k
  └─ Format: KCL (type-safe, schema, validation)

        ↓ GENERACIÓN (durante provisioning)

Capa 2: Config TOML para provctl
  └─ File: /provisioning/generated/provctl/syntaxis-dev.toml
  └─ Format: TOML (lo que provctl ya entiende)

        ↓ CONSUMO

Capa 3: provctl consume TOML
  └─ provctl config apply --from-file syntaxis-dev.toml
  └─ SIN CAMBIOS a provctl

Clave: Se genera TOML desde KCL. provctl nunca ve KCL.

---

🔄 Cómo Funciona la Generación

Opción A: KCL genera TOML en compilación (RECOMENDADO)

provisioning build
  ├─ Compila: /provisioning/extensions/taskservs/development/syntaxis/kcl/syntaxis.k
  ├─ Importa: syntaxis_dev_config (esquema Syntaxis_Dev)
  ├─ Genera: /provisioning/generated/provctl/syntaxis-dev.toml
  │   └─ Contiene configuración TOML lista para provctl
  └─ Output: ✅ syntaxis-dev.toml (TOML puro)

Luego:
provctl config apply --from-file provisioning/generated/provctl/syntaxis-dev.toml
  ├─ provctl LEE TOML (como cualquier otro servicio)
  ├─ NO toca KCL
  └─ ✅ Funciona sin cambios

Ejemplo: KCL se convierte en TOML

# KCL (schema)
schema Syntaxis_Dev(Syntaxis):
    api.enabled = True
    api.port = 3000
    db.typ = "sqlite"
    db.path = "/var/lib/syntaxis/syntaxis.db"
    dependencies = ["surrealdb"]

# TOML generado (para provctl)
[service]
name = "syntaxis-api"
binary = "/usr/local/bin/syntaxis-api"
args = ["--bind", "127.0.0.1:3000"]

[service.env_vars]
DATABASE_URL = "sqlite:///var/lib/syntaxis/syntaxis.db"

[[health_checks]]
type = "http"
endpoint = "http://127.0.0.1:3000/health"

---

🛠️ Opción B: Script NuShell que genera TOML (ALTERNATIVA)

# generate-provctl-config.nu

def generate_syntaxis_provctl_config [preset: string] {
    # 1. Cargar KCL (via provisioning CLI)
    let kcl_config = (
        provisioning taskserv export syntaxis --preset $preset
            | from json
    )

    # 2. Generar TOML
    let toml_config = {
        service: {
            name: $kcl_config.api.name
            binary: "/usr/local/bin/syntaxis-api"
            args: ["--bind", $"($kcl_config.http_addr):($kcl_config.http_port)"]
            env_vars: {
                DATABASE_URL: $kcl_config.db.path
            }
        }
        health_checks: [
            {
                type: "http"
                endpoint: $"http://($kcl_config.http_addr):($kcl_config.http_port)/health"
                interval_seconds: 10
            }
        ]
    }

    # 3. Guardar TOML
    $toml_config | to toml | save --force "provisioning/generated/provctl/syntaxis-$preset.toml"

    print $"✅ Generado: provisioning/generated/provctl/syntaxis-($preset).toml"
}

# Uso:
generate_syntaxis_provctl_config "dev"
# Output: /provisioning/generated/provctl/syntaxis-dev.toml

---

📊 Opción A vs B

Aspecto	Opción A (KCL→TOML en build)	Opción B (Script NuShell)
Integración	Native KCL	Via scripting
Overhead	Parte del build de provisioning	Paso separado
Mantenimiento	Menos código	Más código
Performance	Compilación	Runtime script
Acoplamiento	provisioning/KCL	provisioning CLI + NuShell
Recomendación	✅ Preferida	⚠️ Fallback

---

🚀 Implementación Real

Paso 1: Definir TaskService KCL

# /provisioning/extensions/taskservs/development/syntaxis/kcl/syntaxis.k

schema Syntaxis:
    name: str = "syntaxis"
    http_port: int = 3000
    db: Database = {typ = "sqlite"}
    # ... más campos

schema Syntaxis_Dev(Syntaxis):
    api.enabled = True
    # ... config específica de dev

Paso 2: Crear generador en provisioning

Opción A (Recomendado): Crear un script Tera que genere TOML durante build

# /provisioning/extensions/taskservs/development/syntaxis/templates/syntaxis.toml.j2

[service]
name = "syntaxis-api"
binary = "{{ bin_path }}/syntaxis-api"
args = ["--bind", "{{ http_addr }}:{{ http_port }}"]

[service.env_vars]
DATABASE_URL = "{{ db_url }}"
RUST_LOG = "{{ log_level }}"

[[health_checks]]
type = "http"
endpoint = "http://{{ http_addr }}:{{ http_port }}/health"
interval_seconds = 10

Build Process:

provisioning build
  ├─ Compila KCL
  ├─ Carga syntaxis_dev_config
  ├─ Renderiza syntaxis.toml.j2 con valores
  ├─ Guarda: provisioning/generated/provctl/syntaxis-dev.toml
  └─ ✅ Listo para provctl

Paso 3: Consumir en provctl (SIN CAMBIOS)

provctl config apply --from-file provisioning/generated/provctl/syntaxis-dev.toml

provctl consume TOML como siempre. No necesita cambios.

---

💡 ¿Por Qué Esta Arquitectura?

Separación de Concerns

provisioning:
  ✅ Sabe QUÉ es syntaxis (schema KCL)
  ✅ Sabe CÓMO configurarlo (template Tera)
  ✅ Genera TOML para provctl

provctl:
  ✅ Sabe CÓMO ejecutar TOML
  ✅ NO necesita saber de KCL
  ✅ Sin cambios = Sin riesgos

Ventajas

✅ provctl NO toca KCL (riesgo cero)
✅ provisioning es dueño de la generación
✅ TOML es estándar, bien documentado
✅ Reutilizable para otros taskservs
✅ No requiere dependencias nuevas en provctl

---

🎯 Caso de Uso: Developer Local

# Developer en su laptop

# 1. Generar config
provisioning taskserv export syntaxis --preset dev > /tmp/syntaxis.toml

# 2. Usar con provctl
provctl config apply --from-file /tmp/syntaxis.toml

# 3. Ejecutar
provctl start syntaxis-api

# ✅ Todo funciona sin que provctl toque KCL

---

🔮 Futuro: Si provisioning Y provctl Evolucionan

Posible Evolución (NO necesaria ahora)

Si en el futuro:
  - provisioning expone KCL via API
  - provctl quiere consumir directamente

Entonces:
  provctl config apply --from-provisioning syntaxis --preset dev
    ├─ API call a provisioning
    ├─ provisioning genera y envía TOML
    └─ provctl lo consume

Pero esto es OPCIONAL, no requerido hoy.

---

📌 Respuesta Corta

¿Hay que modificar provctl para que entienda KCL?

NO.

• provisioning genera TOML desde KCL
• provctl consume TOML (ya lo sabe hacer)
• Cero cambios requeridos en provctl

Beneficio: Se integra fácilmente, sin riesgos, reutilizable.

---

🚀 Implementación

TODO List

• Crear KCL schema en provisioning (syntaxis.k)
• Crear template Tera (syntaxis.toml.j2) en provisioning
• Agregar step en build de provisioning para generar TOML
• Validar TOML generado
• Documentar para developers
• Cambios en provctl: NINGUNO ✅

---

Conclusión: La belleza de esta arquitectura es que cada herramienta hace lo que sabe hacer. provisioning genera, provctl consume. Sin acoplamientos forzados.