@bi-analytics/arness-back 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+Formato basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y [SemVer](https://semver.org/lang/es/):
+- **major:** cambios de estructura o rutas del harness, con migración en `arness sync`;
+- **minor:** reglas, playbooks, skills o checks nuevos compatibles;
+- **patch:** correcciones.
+
+## [Sin publicar]
+
+### Agregado
+- **Última LTS de Node** (ADR 0015): `init.sh` compara `.nvmrc` con la última LTS de `nodejs.org` y advierte `toolchain.node-lts` si hay un major más nuevo; sin red lo omite. `NODE_LTS_VERSION` fija la LTS de referencia (`off` desactiva). Playbook `update-node-lts.md`: el agente analiza el impacto, lo presenta y actualiza solo con aprobación humana. AGENTS.md §0 y §16, agente `lider` y pistas de `doctor`.
+- **Endurecimiento de la autenticación** (ADR 0017), sin dependencias nuevas:
+  - plantillas `templates/security/` (`LoginAttemptLimiter`, `securityHeaders()`, `sessionClaims` / `isSessionExpired` y `SecurityModule`) y `templates/config/auth.ts` (`parseAuthConfig`, bloque `auth` de la configuración), con specs;
+  - límite de intentos por IP en `/auth/login` y `/monitor/login` (`429 TOO_MANY_ATTEMPTS` con `Retry-After`);
+  - vida máxima de la sesión con `auth_time` (`401 SESSION_EXPIRED`);
+  - cabeceras de seguridad en toda respuesta;
+  - variables `AUTH_LOGIN_MAX_ATTEMPTS`, `AUTH_LOGIN_WINDOW_SECONDS`, `AUTH_SESSION_MAX_AGE_SECONDS` y `HTTP_TRUST_PROXY_HOPS`;
+  - `init.sh`: `security.headers`, `security.trust-proxy`, `security.login-rate-limit`, y `security.session-max-age`; tres novedades de seguridad en `doctor`;
+  - `auth.e2e-spec.ts` exige que la cookie del monitor y el refresh token no sirvan como `Bearer`.
+
+### Cambiado
+- El monitor comparte el límite de intentos del login: `templates/monitor/monitor.controller.ts` y `templates/e2e/monitor.e2e-spec.ts` usan `LoginAttemptLimiter`.
+- `arness sync` solo anuncia las novedades hasta la versión que instala (antes también mostraba las de versiones posteriores presentes en el catálogo).
+- **Evolutivo con hora y responsable** (ADR 0016): cada entrada de `docs/EVOLUTIVO.md` lleva fecha, hora y zona de Bogotá (`AAAA-MM-DD HH:mm -0500`) y el responsable (`git config user.name`). Plantilla, AGENTS.md §12, `new-endpoint`, `review.md`, `revisor` y `nest-base`.
+
+### Para proyectos existentes
+- `init.sh` puede mostrar la advertencia nueva `toolchain.node-lts`. No rompe nada: el agente propone el análisis y solo actualiza Node si lo apruebas. Si no, queda en `docs/PENDIENTES.md`.
+- Las entradas existentes de `docs/EVOLUTIVO.md` no se reescriben: el formato nuevo aplica desde la siguiente entrega. Verifica que cada persona tenga `git config user.name`.
+- **Seguridad:** `init.sh` mostrará `security.*` nuevos como advertencias y `pnpm arness doctor` los lista con sus pasos. Ninguna impide arrancar: los secretos actuales siguen sirviendo. Al adoptar la vida máxima de la sesión, los usuarios con un refresh token anterior deberán volver a iniciar sesión. Detrás de Azure App Service, define `HTTP_TRUST_PROXY_HOPS=1`. Avisa a frontend de `429 TOO_MANY_ATTEMPTS` y `401 SESSION_EXPIRED`.
+
+## [0.2.0] - 2026-10-23
+
+### Cambiado
+- **Distribución por npm** (ADR 0013 y 0014, reemplaza a 0004): el paquete se publica en el registro público de npm como `@bi-analytics/arness-back`. Se instala con `pnpm add -D @bi-analytics/arness-back@X.Y.Z` (o `pnpm dlx @bi-analytics/arness-back@X.Y.Z init` en un repo sin `package.json`), sin acceso al repo de GitHub. La skill `nest-base` y el mensaje de `arness init` usan el nombre del paquete.
+- `init.sh` ya no bloquea por defecto: los hallazgos son **advertencias** y termina en 0, con un resumen por categoría. Cada chequeo tiene un id (`categoria.nombre`).
+- Única excepción crítica: `.env` o `.env.local` versionado en git sigue terminando en 1 y no se puede silenciar.
+- AGENTS.md §0 y §15, agentes `lider`, `implementador` y `revisor`, y `review.md`: el agente reporta las advertencias y continúa, sin corregir lo que está fuera de alcance ni introducir advertencias nuevas.
+- `arness sync` respalda la base anterior en `harness/.arness-backup/` antes de escribir y ya no modifica `.gitignore`. Sin cambios no crea respaldo.
+- La skill `nest-base` verifica el proyecto nuevo con `./harness/init.sh --strict`. El CI del paquete también usa `--strict`.
+- La detección de SQL fuera de `*.sql.ts` (ESLint e `init.sh`) reconoce consultas tras saltos de línea o `(` y las escrituras `INSERT INTO`, `UPDATE … SET`, `DELETE FROM` y `MERGE INTO`, sin marcar enums como `SELECT = 'x'` ni `'DELETE'` como método HTTP.
+- AGENTS.md §5: la regla de agrupación cuenta archivos del mismo tipo **en una misma carpeta**, y los specs mínimos por endpoint son de controller, service, repository, sql y query DTO.
+- El repo del paquete tiene `eslint` como devDependency para sus pruebas; el CI ejecuta `pnpm install --frozen-lockfile` antes de los tests. No afecta a los proyectos instalados.
+
+### Agregado
+- `init.sh --strict` (comportamiento anterior) y `--json` (salida para agentes y pipelines).
+- `harness/arness.config.json` (opcional, del repo; `sync` no lo toca): `strict`, `ignore` con motivo y `required`.
+- `arness rollback [--dry-run] [--force]`: restaura la base desde el último respaldo.
+- `arness doctor [--full]`: qué le falta al proyecto para cumplir la versión instalada, sin modificar nada.
+- `arness sync --diff`: diff línea a línea de cada archivo de la base.
+- Tests de compatibilidad: sincronizar un proyecto instalado no cambia ningún archivo fuera de la base, `init.sh` sigue en 0 y `rollback` restaura la base exacta.
+- ADR 0005.
+- **CORS con allowlist por entorno** (ADR 0006): regla en AGENTS.md §9 y §13, detalle en `contrato-http.md`, variables `CORS_ORIGINS` (obligatoria en proyectos nuevos) y `CORS_MAX_AGE_SECONDS` en `configuracion.md`, plantilla `templates/cors/` (`cors.ts` + spec) y e2e `templates/e2e/cors.e2e-spec.ts` en `nest-base`. `init.sh`: `security.cors-env`, `security.cors` y `security.cors-open`. `review.md`: CORS abierto o con comodín es bloqueante.
+- **Fronteras de arquitectura verificadas** (ADR 0007): plantilla `eslint.boundaries.mjs` (`@typescript-eslint/no-restricted-imports`, sin dependencias nuevas) que impide importar `modules/` desde `common/` y entre módulos o clientes. `init.sh`, sección Arquitectura: `architecture.eslint-boundaries`, `architecture.common-imports-modules`, `architecture.module-imports`, `architecture.grouping` y `architecture.endpoint-files`. Prueba `test/eslint-boundaries.test.mjs` con casos de imports prohibidos y permitidos.
+- **Tablero monitor** (ADR 0008): `GET /monitor` renderizado en el servidor con React, sin JavaScript en el cliente, protegido por `ACCESS_TOKEN` con cookie de sesión y `MonitorSessionGuard`, cabeceras CSP, widgets `MonitorWidget` con el multi-provider `MONITOR_WIDGETS` y widget base `endpoints-total`. Plantillas `templates/monitor/` y `templates/e2e/monitor.e2e-spec.ts`, variables `MONITOR_ENABLED` y `MONITOR_SESSION_EXPIRES_IN`, playbook `new-monitor-widget.md`. `init.sh`: `security.monitor-env` y `security.monitor-guard`. `react` y `react-dom` pasan a dependencias aprobadas, solo para el monitor.
+- **Configuración centralizada** (ADR 0009): `process.env` se lee solo en `src/config/configuration.ts` (plantilla `templates/config/` con `AppConfig`, `buildConfiguration` y spec; secretos sin valor por defecto). Regla §13.12 y §14 en AGENTS.md, sección "Dónde se leen las variables" en `configuracion.md`, `NODE_ENV` documentada. ESLint: `configBoundaries` en `eslint.boundaries.mjs` (`no-restricted-properties`). `init.sh`, sección Variables de entorno: `env.configuration-file`, `env.process-env` y `env.eslint`.
+- **Formato de logs por entorno** (ADR 0010): `LOG_FORMAT=json|pretty` (default `json`; `pretty` rechazado con `NODE_ENV=production`). Plantilla `templates/logging/logger-options.ts` con spec: `buildLoggerParams`, `parseLogFormat`, `REDACT_PATHS` comunes, mensaje `MÉTODO ruta status duración` y `X-Request-Id` entrante solo si es seguro. `pino-pretty` aprobado solo como devDependency (AGENTS.md §2 y §10). `init.sh`, sección Logging: `logging.format-env` y `logging.pretty-production`.
+- **Documentación del proyecto en `docs/`** (ADR 0011): plantillas `templates/docs/` con `TECNICO.md`, `EVOLUTIVO.md` (solo avance, una entrada por entrega) y `PENDIENTES.md` (pendientes, bloqueos, recomendaciones). AGENTS.md §4, §12 y §15, playbooks `new-endpoint`, `new-module`, `add-database` y `new-monitor-widget`, agentes y `review.md`. `FRONT.md` no cambia. `init.sh`: `docs.files`.
+- **`arness doctor` con novedades por versión** (ADR 0012): catálogo `harness/reference/novedades.json` (tipo seguridad/recomendada/opcional, checks de `init.sh`, pasos, ADR y aprobación). `doctor` muestra versión instalada frente a la disponible, novedades por adoptar, adoptadas y declinadas, y el resto de los hallazgos; `--json` y `--since <versión>`. `harness/arness.config.json` acepta `declined` con motivo. `sync` anuncia las novedades de la versión destino. AGENTS.md §0 y agente `lider`: tras un `sync`, informar las novedades sin implementarlas.
+
+### Para proyectos existentes
+- **Instalación desde npm con nombre nuevo** (ADR 0014): quita la devDependency `@linktic/arness-back` (`git+https://...#vX.Y.Z`) con `pnpm remove @linktic/arness-back`, instala `pnpm add -D @bi-analytics/arness-back@0.2.0` y ejecuta `pnpm arness sync`.
+- **No hay cambios obligatorios.** Después de `pnpm arness sync`, `./harness/init.sh` puede mostrar advertencias que antes eran fallos: el proyecto sigue funcionando igual.
+- Ejecuta `pnpm arness doctor`: lista las novedades de esta versión por adoptar, con sus pasos. Adóptalas cuando convenga o declínalas con motivo en `harness/arness.config.json` → `declined`.
+- Si tienes `.env` o `.env.local` en git, `init.sh` terminará en 1: sácalo del índice (`git rm --cached .env`) y rota los secretos.
+- Si quieres el comportamiento anterior, crea `harness/arness.config.json` con `{ "strict": true }`.
+- Si algo no te convence: `pnpm arness rollback`.
+- **CORS:** `init.sh` advertirá `security.cors-env` / `security.cors` hasta que lo adoptes. Copia `harness/skills/nest-base/templates/cors/cors.ts` (y su spec) a `src/config/`, valida `CORS_ORIGINS` al arrancar, cambia `app.enableCors(...)` en `src/main.ts` por `app.enableCors(buildCorsOptions(...))` y agrega `CORS_ORIGINS` y `CORS_MAX_AGE_SECONDS` a `.env.example` y `.env.local`. Antes de desplegar, define en cada entorno los orígenes de los frontends que consumen la API: con la allowlist, un origen no listado deja de funcionar desde el navegador.
+- **Fronteras:** copia `templates/eslint.boundaries.mjs` a la raíz e impórtala en `eslint.config.mjs` (`...architectureBoundaries`). Si aparecen imports entre módulos, mueve lo compartido a `src/common/`. Los hallazgos de `architecture.*` son advertencias: corrígelos cuando toques ese módulo.
+- **Configuración centralizada:** copia `harness/skills/nest-base/templates/config/` (`configuration.ts` y su spec) a `src/config/`, regístrala con `ConfigModule.forRoot({ ..., load: [configuration] })` y cambia, módulo por módulo, cada `process.env.X` por `ConfigService<AppConfig, true>`. Actualiza `eslint.boundaries.mjs` desde la plantilla y agrega `...configBoundaries` en `eslint.config.mjs`. Mientras tanto, `init.sh` muestra `env.*` como advertencias.
+- **Logs (opcional):** sin `LOG_FORMAT` todo sigue en JSON. Para el formato legible en desarrollo: `pnpm add -D pino-pretty` (aprobado como devDependency en AGENTS.md §2 desde esta versión), copia `templates/logging/` a `src/common/logging/`, usa `buildLoggerParams` en `LoggerModule.forRootAsync`, agrega `LOG_FORMAT=json` a `.env.example` y `LOG_FORMAT=pretty` a `.env.local`. El mensaje por request pasa a `MÉTODO ruta status duración`: revisa alertas que busquen el texto "request completed".
+- **`docs/`:** copia `harness/skills/nest-base/templates/docs/` a `docs/`, completa `TECNICO.md` con lo que ya existe y, si quieres, resume en `EVOLUTIVO.md` lo entregado hasta hoy. `sync` no lo crea; hasta entonces `init.sh` muestra `docs.files` como advertencia.
+- **Monitor (opcional):** requiere aprobar `react` y `react-dom` en el proyecto. Copia `templates/monitor/` a `src/common/monitor/`, registra `MonitorModule`, excluye `monitor` del prefijo global, haz que `JwtAuthGuard` omita `IS_MONITOR_ROUTE_KEY` y agrega `MONITOR_ENABLED=false` y `MONITOR_SESSION_EXPIRES_IN=15m`. Sin `src/common/monitor/`, `init.sh` no verifica nada del monitor.
+
+## [0.1.0] - 2026-09-25
+
+### Agregado
+- CLI `arness`: `init`, `sync`, `status`, `verify` y `decision new`.
+- Base del harness en `harness/`:
+  - `AGENTS.md` e `init.sh`;
+  - agentes `lider`, `implementador` y `revisor`;
+  - skill `nest-base`;
+  - playbooks, referencias y plantilla de `progress.md`.
+- Esqueleto de `harness/decisiones/`, que pertenece al repo instalador.
+- Puentes para Claude Code, Codex, Gemini CLI y Cursor, con copia automática donde no hay symlinks.
+- Instalación desde git con tags `vX.Y.Z` (sin registro npm).

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @bi-analytics/arness-back
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Harness de agentes IA para los **backends NestJS de analítica**. Funciona con Claude Code, Codex, Gemini CLI y Cursor, e incluye:
+- reglas (`AGENTS.md`);
+- verificación de estado (`init.sh`);
+- agentes `lider`, `implementador` y `revisor`;
+- la skill `nest-base`;
+- playbooks y referencias.
+
+Se publica en el **registro público de npm** como `@bi-analytics/arness-back` (ADR 0013); cada versión tiene además su tag git `vX.Y.Z`. Las **decisiones de cada proyecto** (`harness/decisiones/`) quedan en el repo que lo instala, y el paquete nunca las modifica.
+
+## Requisitos
+
+- Node.js ≥ 20, pnpm y git.
+
+Para ver la última versión publicada:
+
+```bash
+pnpm view @bi-analytics/arness-back version
+```
+
+## Instalación
+
+Elige el caso según el estado del repo donde vas a instalarlo. En los comandos, `0.2.0` es la versión; usa la última de [CHANGELOG.md](CHANGELOG.md).
+
+### A. Repo nuevo, antes de crear el proyecto NestJS (sin `package.json`)
+
+`pnpm add` crearía un `package.json` antes que Nest. Por eso el harness se instala con `pnpm dlx`, que ejecuta el CLI sin agregarlo al proyecto:
+
+```bash
+cd mi-backend                       # carpeta del nuevo backend (con git init hecho)
+
+pnpm dlx @bi-analytics/arness-back@0.2.0 init
+
+./harness/init.sh                   # debe quedar en verde (modo solo harness)
+```
+
+Después, pide a tu agente **"crea la base del proyecto NestJS"** (skill `nest-base`). Por ejemplo en Claude Code: `claude --agent lider`, o `/nest-base`. La skill crea el proyecto en la raíz y agrega el harness como devDependency con la misma versión.
+
+### B. Proyecto que ya tiene `package.json`
+
+```bash
+pnpm add -D @bi-analytics/arness-back@0.2.0
+pnpm arness init
+./harness/init.sh
+```
+
+Si el proyecto lo tenía instalado desde git (`git+https://...#vX.Y.Z`), basta con el `pnpm add` de arriba y `pnpm arness sync`.
+
+### Qué hace `arness init`
+
+- Copia la base a `harness/` y crea `harness/decisiones/` con el README y la plantilla.
+- Crea los puentes de la raíz: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/`, `.claude/` y `.agents/`.
+- Escribe `harness/.arness.json` con la versión instalada y el hash de cada archivo de la base.
+- Agrega `harness/progress.md` al `.gitignore`.
+
+Luego haz commit de todo. El harness queda versionado y funciona recién clonado, antes de `pnpm install`.
+
+```
+harness/
+├── .arness.json        manifiesto: versión + hash de cada archivo gestionado
+├── AGENTS.md, init.sh, agents/, skills/, playbooks/, reference/    ← del paquete (no editar)
+├── decisiones/         ← del repo: se crea una vez y sync nunca la toca
+├── arness.config.json  ← del repo, opcional: strict / ignore / required de init.sh
+├── .arness-backup/     ← respaldos de sync para arness rollback (ignorados en git)
+└── progress.md         ← del repo, no versionado
+AGENTS.md → harness/AGENTS.md · CLAUDE.md · GEMINI.md · .cursor/rules/ · .claude/{agents,skills} · .agents/skills
+```
+
+## Uso diario
+
+```bash
+./harness/init.sh                                   # o: pnpm arness verify
+pnpm arness doctor                                  # novedades por adoptar y hallazgos (no modifica nada)
+pnpm arness decision new "Usar réplica de lectura"  # nueva decisión en harness/decisiones/
+pnpm arness status                                  # versión instalada e integridad de la base
+```
+
+### `init.sh`: advertencias por defecto
+
+Los hallazgos se muestran como advertencias (`⚠`) y el script termina en 0: el proyecto sigue funcionando. Al final aparece un resumen por categoría.
+
+- **Crítico (siempre exit 1):** `.env` o `.env.local` versionado en git.
+- `--strict`: los hallazgos fallan (exit 1). Recomendado en CI y en proyectos nuevos.
+- `--json`: resultado para agentes y pipelines (`{ mode, exitCode, summary, issues: [{ level, id, section, message }] }`).
+
+Configuración opcional del repo en `harness/arness.config.json` (sync no la toca):
+
+```json
+{
+  "strict": false,
+  "ignore": { "toolchain.nvmrc": "La versión de Node la fija la plataforma de despliegue" },
+  "required": ["sql.write"]
+}
+```
+
+`ignore` silencia un chequeo y exige un motivo. `required` hace que un chequeo falle aunque no haya `--strict`. Los ids aparecen entre corchetes en la salida de `init.sh`. `declined` (`{ "monitor": "No aplica a este cliente" }`) marca una novedad que el repo decidió no adoptar; también exige motivo.
+
+### `arness doctor`: novedades por adoptar
+
+Cada versión declara sus novedades en `harness/reference/novedades.json` (tipo **seguridad**, **recomendada** u **opcional**, con pasos, ADR y si requieren aprobación). `doctor` las cruza con `init.sh` y muestra, sin modificar nada:
+
+- versión instalada frente a la del paquete, y aviso si hay una más nueva;
+- novedades **por adoptar**, de seguridad a opcionales, con lo que falta y sus pasos;
+- novedades ya adoptadas y declinadas (`declined` en `harness/arness.config.json`);
+- el resto de los hallazgos de `init.sh`, por categoría.
+
+`--json` da el mismo resultado para agentes y pipelines; `--since 0.2.0` muestra solo lo posterior a esa versión; `--full` incluye lint, build, tests y health. Nunca termina en 1 por novedades sin adoptar, solo por críticos.
+
+## Actualizar a una versión nueva
+
+`pnpm outdated @bi-analytics/arness-back` muestra si hay una versión nueva.
+
+```bash
+pnpm add -D @bi-analytics/arness-back@0.3.0
+pnpm arness sync --dry-run --diff   # ver qué cambiaría, línea a línea
+pnpm arness sync                    # aplicar (respalda la versión anterior)
+pnpm arness doctor                  # novedades de la versión nueva y cómo adoptarlas
+./harness/init.sh
+git add -A && git commit -m "chore(harness): update to v0.3.0"
+```
+
+Actualizar **no rompe un proyecto que funciona**: las reglas nuevas aparecen como advertencias y cada versión trae una sección "Para proyectos existentes" en el CHANGELOG. Para volver atrás: `pnpm arness rollback`.
+
+`arness sync`:
+- solo escribe los archivos del manifiesto (`harness/` y puentes). Nunca toca el código del proyecto (`src/`, `test/`, `package.json`, `.env*`, `.gitignore`, `Dockerfile`, pipelines), `harness/decisiones/`, `harness/arness.config.json` ni `harness/progress.md`;
+- antes de escribir guarda la base anterior en `harness/.arness-backup/` (los últimos 3, ignorados en git), que `arness rollback` restaura;
+- si alguien editó un archivo de la base, **se detiene**. Ese cambio debe registrarse como decisión del repo o proponerse a este paquete (`--force` sobrescribe);
+- con `--copy` crea copias en lugar de enlaces simbólicos, útil en Windows sin symlinks. `init` lo hace solo si no puede crear el enlace.
+
+## Desarrollo del paquete
+
+```bash
+pnpm test               # tests del CLI (node --test)
+./harness/init.sh       # en este repo verifica el harness y el CLI, no un proyecto NestJS
+pnpm pack:check         # archivos que se instalan
+```
+
+- La base que se distribuye es todo `harness/`, salvo las decisiones numeradas y `progress.md`. **El paquete es público:** nada de secretos, datos de clientes ni información interna sensible.
+- Las decisiones de diseño **del harness** están en `docs/adr/` y no se instalan.
+
+### Publicar una versión
+
+Requiere una cuenta npm con permiso de escritura en el scope `@bi-analytics` (`pnpm login`; comprueba con `pnpm whoami`).
+
+1. Actualiza `CHANGELOG.md` y, si aplica, `harness/reference/novedades.json`.
+2. Verifica: `pnpm test`, `./harness/init.sh --strict` y `pnpm pack:check` (revisa la lista: todo lo que aparece será público).
+3. Sube la versión con `pnpm version <patch|minor|major>`, que crea el commit y el tag `vX.Y.Z`:
+   - **patch:** correcciones;
+   - **minor:** reglas, playbooks o skills compatibles;
+   - **major:** cambios de estructura o rutas.
+4. Publica en npm con `pnpm publish` (desde `main`, con el árbol limpio; `publishConfig` ya fija `access: public`).
+5. Sube el commit y el tag con `git push --follow-tags`.
+
+Una versión publicada no se puede reemplazar: si algo sale mal, publica una nueva.
+
+El CI (`azure-pipelines.yml`) corre los tests y valida que el tag coincida con `package.json`.