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

```nushell
# 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

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

```tera
# /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**:
```bash
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)

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

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