[tooling] CLI de orquestación para extensiones (apimetro-cli)

[galigaribaldi]

Contexto

Actualmente la activación de extensiones (como Plutarco) se maneja con targets del Makefile (make plutarco-setup, make plutarco-status). Esto funciona para el equipo actual (1 extensión, 3 ETLs, pocos contribuidores), pero a medida que el proyecto crezca necesitaremos un mecanismo más robusto.

Señales de que es momento de implementar esto

• Más de 2 extensiones activas con ETLs interdependientes
• Contribuidores nuevos que tardan más de 5 minutos en entender el setup
• Lógica condicional compleja en el Makefile (if/else bash)
• Necesidad de reintentos, progreso visual, o verificación de estado en múltiples capas

Propuesta

CLI en Go (binario único, sin dependencias externas) con subcomandos:

```bash

Listar extensiones disponibles y su estado

apimetro-cli ext list

Activar una extensión (DDL + deps + ETL)

apimetro-cli ext activate plutarco

Ver estado detallado

apimetro-cli ext status plutarco

Desactivar (trunca tablas, no borra esquema)

apimetro-cli ext deactivate plutarco

Health check general

apimetro-cli doctor
```

Subcomando doctor

Verifica las 3 capas:

1. DB: Conexión, esquemas, tablas, permisos
2. API: Proceso corriendo, endpoints respondiendo
3. Extensiones: Tablas con datos, ETLs disponibles, CSVs presentes

Subcomando ext activate <nombre>

Flujo orquestado:

1. Verifica que Docker DEV esté corriendo
2. Aplica migraciones DDL (idempotente)
3. Instala dependencias Python si no existen
4. Verifica presencia de archivos fuente (CSVs/shapefiles)
5. Ejecuta ETLs en orden correcto
6. Valida conteo de registros post-carga
7. Reporta resultado con colores/emojis en terminal

Registro de extensiones

Cada extensión se describe en un archivo YAML:

```yaml

extensions/plutarco.yaml

name: plutarco
description: Datos geoespaciales INEGI + afluencia transporte para VFT
version: 1.0
tables:

• plutarco.agebs
• plutarco.afluencia_linea
• plutarco.afluencia_estacion
• plutarco.catalogo_homologacion
  ddl:
• db/init/init_plutarco.sql
• db/migrations/seed_catalogo_homologacion.sql
  etl:
• script: ETL/DataCharge/LoadAfluencia.py
  requires: ETL/Data/Pesos/afluencia_diaria_historica.xlsx
• script: ETL/DataCharge/LoadAfluenciaEstacion.py
  requires: ETL/Data/Pesos/afluenciastc_simple_04_2026.csv
• script: ETL/DataCharge/LoadAgebs.py
  requires: ETL/Data/AGEBS/
  dependencies:
  python: ETL/requirements.txt
  ```

Decisiones técnicas

• Go (no bash/Python): mismo stack que la API, binario único, cross-platform
• Sin framework CLI pesado: solo flag stdlib o cobra si se justifica
• Config-driven: extensiones se registran vía YAML, no hardcoded
• Idempotente: ejecutar dos veces no rompe nada
• Colores solo en TTY: output plano si se redirige a archivo

Dependencia

• Requiere que la estructura de extensiones se estabilice (al menos 2 extensiones antes de abstraer)
• No bloquea ningún trabajo actual — el Makefile cubre las necesidades presentes

Criterios de aceptación

• Binario apimetro-cli compilable con go build
• ext list muestra extensiones con estado (activada/no activada/parcial)
• ext activate plutarco ejecuta el flujo completo
• doctor reporta salud de DB + API + extensiones
• README o --help documenta todos los subcomandos
• Tests unitarios para la lógica de verificación