Diagnóstico (koko doctor)
Diagnóstico e Integridad Arquitectónica
El comando `koko doctor` es el guardián de consistencia e introspección de Koko CLI. A medida que un proyecto evoluciona y múltiples desarrolladores incorporan dependencias, módulos y variables de entorno, es habitual que la configuración original sufra desviaciones silenciosas (architecture drift).
Sintaxis y Flags del Comando
Sintaxis: `koko doctor [flags]`
Todos los parámetros disponibles para auditorías locales o integración con pipelines automatizados:
- -f, --fix - Aplica automáticamente las correcciones detectadas y actualiza koko.config.json.
- -d, --dir <ruta> - Especifica el directorio raíz del proyecto a diagnosticar (por defecto: carpeta actual .).
- -v, --verbose - Imprime información detallada de cada paso de validación y chequeo de paquetes.
- --json - Genera la salida en formato JSON estructurado, ideal para pipelines de CI/CD y webhooks.
# Diagnóstico interactivo estándar
koko doctor
# Diagnóstico con auto-reparación de inconsistencias
koko doctor --fix
# Analizar una carpeta específica en modo detallado
koko doctor --dir ./apps/web --verbose
# Salida JSON para pipelines de CI/CD
koko doctor --json Los 5 Pilares de Verificación de Salud
Durante su ejecución, `koko doctor` evalúa cinco áreas críticas del proyecto:
Modo Auto-Reparación (--fix)
Al ejecutar `koko doctor --fix`, el motor realiza una reconciliación transaccional segura en cuatro fases:
1. Análisis en Memoria: Evalúa las discrepancias en el Virtual File System (VFS) sin modificar archivos prematuramente.
2. Sincronización de Manifiesto: Actualiza `koko.config.json` registrando módulos o addons agregados manualmente.
3. Alineación de Scripts: Restaura scripts de compilación estándar (`dev`, `build`, `lint`) en el `package.json` raíz si fueron alterados.
4. Resumen de Ejecución: Emite un reporte limpio de correcciones aplicadas y el tiempo total de ejecución en milisegundos.
$ koko doctor --fix
[✓] koko.config.json schema: OK
[✓] Monorepo workspace mapping: OK
[!] Dependency Drift: @auth/core version out of sync
-> Applying fix: updated koko.config.json to v2.0.0 catalog standard
[✓] Docker container ports: No conflicts detected
✓ Diagnostics passed. 1 auto-fix applied successfully in 18ms. Integración en Pipelines de CI/CD
Puedes incorporar `koko doctor` como un paso de control de calidad (quality gate) en GitHub Actions para asegurar que ningún pull request introduzca drift arquitectónico en la rama principal:
name: Architecture Integrity Check
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Install Koko CLI
run: npm install -g koko-app
- name: Run Koko Doctor Audit
run: koko doctor