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

package/harness/playbooks/add-database.md

@@ -0,0 +1,16 @@
+# Playbook: agregar una conexión de BD
+
+Referencia: `AGENTS.md` §6 y §13.
+
+1. **Confirmar con el humano:** el nombre lógico de la conexión (UPPER_SNAKE, ej. `REPORTS`) y qué módulos la usarán. Nunca pidas ni escribas credenciales reales en el código ni en el chat.
+2. Agrega el nombre a `DATABASES` y el bloque de variables `DB_<NOMBRE>_*` en:
+   - `.env.example`, con valores de ejemplo;
+   - `.env.local`, con valores locales de desarrollo.
+   - **No toques `.env`.**
+3. Verifica que la validación de `src/config/` exige las variables de cada nombre listado en `DATABASES`, y que `parseDatabases` de `src/config/configuration.ts` arma su bloque en `AppConfig.databases`. Normalmente no requiere cambios de código, porque ambas son dinámicas. Nunca leas `DB_<NOMBRE>_*` con `process.env` fuera de `src/config/`.
+4. En los repositories que la usen, inyecta el pool con `@Inject(getPoolToken('<NOMBRE>'))`.
+5. Confirma que `/health` reporta la nueva conexión.
+6. Documenta la conexión en el `README.md` de cada módulo que la use y en la tabla de conexiones de `docs/TECNICO.md` (solo nombre lógico y origen, nunca credenciales), y agrega una entrada en `docs/EVOLUTIVO.md`.
+7. Corre `./harness/init.sh`.
+
+Recuerda que el usuario de BD debe ser de solo lectura. El pool fuerza `default_transaction_read_only = on` como segunda barrera, no como única.

package/harness/playbooks/new-endpoint.md

@@ -0,0 +1,88 @@
+# Playbook: crear un endpoint (reporte)
+
+Referencia de reglas: `AGENTS.md` §5 (patrón), §6 (BD), §7 (caché), §9 (contrato), §12 (documentación).
+
+## 0. Confirmar el contrato (antes de escribir código)
+
+Presenta esto al humano y espera su confirmación:
+
+```
+Endpoint:     GET /api/v1/<modulo>/<segmento>
+Ubicación:    src/modules/<cliente>/<modulo>/<endpoint>/
+Conexión BD:  <NOMBRE>   Origen: <schema.tabla | vista>
+Columnas:     <col1: tipo>, <col2: tipo>, ...
+Filtros:      <nombre: tipo, obligatorio|opcional, default>
+Paginación:   sí|no  (pageSize default N, máx M)
+Orden:        <columnas permitidas>, default <col DESC>
+Caché TTL:    <segundos>
+```
+
+Si falta información, pregunta. No inventes columnas, tablas ni reglas.
+
+## 1. Archivos, en este orden
+
+1. `<endpoint>.columns.ts`: `export const X_COLUMNS = Object.freeze([...] as const)`.
+2. `<endpoint>.entity.ts`: el tipo de la fila, derivado de las columnas.
+3. `<endpoint>-query.dto.ts`: los params HTTP con `class-validator` (`@IsOptional`, `@IsDateString`, `@IsInt`, `@Min`, `@Max`, `@IsIn`).
+4. `<endpoint>-filters.dto.ts`: los filtros normalizados (fechas como `Date`, defaults aplicados, `page`/`pageSize` resueltos).
+5. `<endpoint>.sql.ts`: funciones puras `buildXQuery(filters): { text: string; values: unknown[] }` y, si pagina, `buildXCountQuery(filters)`. Todo valor va como `$n`, y el ORDER BY sale de una allowlist de `columns.ts`.
+6. `<endpoint>.repository.ts`: el token `X_REPOSITORY`, la interfaz `XRepository` y la clase `PgXRepository`, que inyecta el pool de la conexión nombrada.
+7. `<endpoint>.service.ts`: Cache-Aside con `CacheService`, y retorna `{ data, meta? }` junto al estado de caché.
+8. `<endpoint>.controller.ts`: `@Get('<segmento>')`, recibe el DTO, lo convierte en filtros, llama al service y fija `X-Cache`.
+9. Registrar controller, service y provider del repository (`{ provide: X_REPOSITORY, useClass: PgXRepository }`) en `<modulo>.module.ts`.
+
+Aplica la regla de agrupación (más de 2 archivos del mismo tipo en una carpeta → carpeta por tipo). `init.sh` verifica que el endpoint tenga todos estos archivos y los specs de la sección 2.
+
+## 2. Tests
+
+- `*.sql.spec.ts`: valida `text` y `values` para cada combinación de filtros, y que ningún valor aparezca interpolado en `text`.
+- `*.service.spec.ts`: HIT, MISS, BYPASS (caché lanza error o está deshabilitada), con y sin paginación.
+- `*.controller.spec.ts`: delega al service y fija `X-Cache`.
+- `*.repository.spec.ts`: con pool mockeado, verifica que ejecuta el SQL del builder y mapea las filas.
+- `*-query.dto.spec.ts`: casos válidos e inválidos.
+- E2E en `test/`: 401 sin token, 200 con token y envelope correcto, 400 con filtro inválido.
+
+## 3. Documentación
+
+### Postman
+
+Agrega la request en `postman/arness-back.postman_collection.json`, dentro de la carpeta `<cliente>/<modulo>`:
+- `GET {{baseUrl}}/api/v1/<modulo>/<segmento>?param=ejemplo`
+- Auth: heredada de la colección (`Bearer {{accessToken}}`)
+- Sin descripciones largas.
+
+### FRONT.md
+
+Agrega una sección con esta plantilla:
+
+````markdown
+### <Nombre legible del reporte>
+
+`GET /api/v1/<modulo>/<segmento>` · requiere `Authorization: Bearer <accessToken>`
+
+Qué devuelve: <una frase>.
+
+| Parámetro | Tipo | Obligatorio | Ejemplo |
+|---|---|---|---|
+| desde | fecha ISO | sí | 2026-01-01 |
+| page | número | no (default 1) | 1 |
+
+```json
+{ "data": [{ "col1": "…", "col2": 0 }], "meta": { "pagination": { "page": 1, "pageSize": 50, "total": 120, "totalPages": 3 } } }
+```
+
+**Consumo recomendado:** <paginar con pageSize ≤ N | traer completo>; <filtros a enviar siempre>; ante `401 TOKEN_EXPIRED`, llamar a `/auth/refresh` y reintentar una vez; datos cacheados en servidor por <TTL>, así que no hace falta hacer polling más frecuente.
+````
+
+### README del módulo
+
+Agrega el endpoint, su conexión y el origen de datos.
+
+### docs/
+
+- `docs/EVOLUTIVO.md`: agrega al final una entrada `## <fecha> · <cliente>/<modulo>` con lo entregado en lenguaje de negocio (qué reporte quedó disponible), el endpoint y la referencia. Solo avance.
+- `docs/PENDIENTES.md`: lo que quedó abierto (por ejemplo, una vista que aún no existe en la BD o un filtro aplazado).
+
+## 4. Cierre
+
+Corre `./harness/init.sh` y revisa el Definition of Done de `AGENTS.md` §15.

package/harness/playbooks/new-module.md

@@ -0,0 +1,21 @@
+# Playbook: crear un módulo o cliente
+
+Referencia: `AGENTS.md` §4 y §5.
+
+1. **Confirmar con el humano:** nombre del cliente (carpeta de primer nivel), nombre del módulo, segmento base de la URL y conexión de BD por defecto.
+2. **Cliente nuevo:** crea `src/modules/<cliente>/`. Si se quiere agrupar sus módulos, agrega `<cliente>.module.ts` que los importe, y regístralo en `app.module.ts`.
+3. **Módulo nuevo:** crea `src/modules/<cliente>/<modulo>/` con:
+   - `<modulo>.module.ts`: `@Module({ controllers: [], providers: [] })`, sin imports de otros módulos de negocio. El código del módulo solo importa de su propia carpeta, de `src/common/` y de `src/config/` (ESLint lo verifica).
+   - `README.md` con esta plantilla:
+     ```markdown
+     # <Módulo>
+     Propósito: <una frase>.
+     Conexión BD: <NOMBRE>.
+     | Endpoint | Origen de datos | Caché TTL |
+     |---|---|---|
+     ```
+4. Registra el módulo en su padre (el módulo del cliente o `app.module.ts`).
+5. Crea la carpeta `<cliente>/<modulo>` en la colección de Postman y un encabezado `## <Módulo>` en `FRONT.md`.
+6. Agrega endpoints con `new-endpoint.md`.
+7. Agrega el módulo a la tabla de módulos de `docs/TECNICO.md` y una entrada en `docs/EVOLUTIVO.md` (solo avance; lo abierto va a `docs/PENDIENTES.md`).
+8. Corre `./harness/init.sh`.

package/harness/playbooks/new-monitor-widget.md

@@ -0,0 +1,31 @@
+# Playbook: agregar un widget al monitor
+
+Referencia: `AGENTS.md` §10 y §13, y `harness/reference/contrato-http.md` (Monitor). El monitor ya existe en `src/common/monitor/` (skill `nest-base`).
+
+## 0. Confirmar con el humano
+
+```
+Widget:      <id-kebab>  ·  Título: <texto corto>  ·  Orden: <número>
+Muestra:     <qué cifra o estado técnico>  ·  Desglose: <sí/no, por qué>
+Origen:      <de dónde sale el dato: Nest, pool, caché, process>
+Costo:       <consultas o llamadas por carga de página>
+```
+
+**Qué puede mostrar:** conteos, estados (`up`/`down`), versiones, uptime, tamaños de pool y latencias agregadas.
+**Qué nunca muestra:** secretos o variables de entorno, SQL, mensajes de error de PostgreSQL o Redis, hosts o usuarios de BD, y datos de negocio (filas, montos, nombres de clientes). Si el humano pide algo de esta lista, detente: requiere una decisión en `harness/decisiones/`.
+
+## 1. Implementar
+
+1. Crea `src/common/monitor/widgets/<id>.widget.ts`: una clase `@Injectable()` que implementa `MonitorWidget` (`id`, `title`, `order`, `collect(): Promise<MonitorValue>`).
+2. `collect()` debe ser barato y de solo lectura: sin escrituras, sin SQL de negocio y sin depender de Redis. Si necesita la BD, usa una consulta técnica en un `*.sql.ts` y el repository de `common/`; si falla, deja que lance: el monitor lo muestra como "No disponible" y registra solo el tipo de error.
+3. Regístrala en `src/common/monitor/monitor.module.ts`, agregándola al arreglo `WIDGETS`. El multi-provider `MONITOR_WIDGETS` la recoge sola.
+4. `src/common/` no importa de `src/modules/`. Si el dato es de un módulo de negocio, no va al monitor base: regístralo como decisión.
+
+## 2. Tests
+
+- `<id>.widget.spec.ts`: el valor y el desglose esperados, y que un error del origen se propaga (no se traga ni se formatea).
+- Si cambia el HTML, ajusta `test/monitor.e2e-spec.ts` para que siga comprobando que no hay `<script>` y que un widget con error no rompe la página.
+
+## 3. Cierre
+
+Agrega una entrada en `docs/EVOLUTIVO.md` (qué muestra ahora el monitor). Corre `./harness/init.sh` y revisa el checklist de `harness/playbooks/review.md` (un widget con datos sensibles es bloqueante).

package/harness/playbooks/review.md

@@ -0,0 +1,40 @@
+# Playbook: revisar un cambio
+
+Revisa el diff contra `AGENTS.md` y reporta cada hallazgo con archivo y línea, del más grave al menos grave.
+
+## Bloqueantes
+
+- [ ] SQL fuera de `*.sql.ts`, o valores concatenados o interpolados en SQL
+- [ ] `ORDER BY` o nombres de columna que no salen de una allowlist
+- [ ] Cualquier escritura, DDL o migración
+- [ ] Un endpoint nuevo sin guard JWT, o un `@Public()` fuera de `login`, `refresh` o `health`
+- [ ] CORS abierto: `enableCors()` sin opciones, `origin: true`, `'*'`, reflejar el `Origin`, `credentials: true`, o `CORS_ORIGINS` con comodín
+- [ ] El monitor sin `MonitorSessionGuard`, marcado `@Public()`, dentro de `/api/v1`, con `<script>`, o un widget que muestra secretos, SQL, errores crudos o datos de negocio
+- [ ] Tokens, contraseñas o secretos en logs, respuestas, código o commits
+- [ ] `pino-pretty` en `dependencies` (va en devDependencies) o `LOG_FORMAT=pretty` para producción
+- [ ] Cambios en `.env`, o `.env.local` incluido en el commit
+- [ ] `process.env` fuera de `src/config/` en código nuevo (salvo tests), o un secreto con valor por defecto en `configuration.ts`
+- [ ] Una dependencia nueva sin aprobación
+- [ ] La API falla si Redis está caído o deshabilitado
+- [ ] Se editó la base del harness (`AGENTS.md`, puentes o playbooks) en lugar de registrar la decisión en `harness/decisiones/`
+- [ ] El cambio contradice una decisión `Aceptada` de `harness/decisiones/`, o toma una decisión nueva sin registrarla
+- [ ] `./harness/init.sh` termina en 1 (crítico, `--strict` o `required`), o el cambio agrega advertencias nuevas respecto a la línea base
+- [ ] Se silenció un chequeo en `harness/arness.config.json` sin aprobación humana o sin motivo
+
+## Contrato y arquitectura
+
+- [ ] Estructura del endpoint según §5, y regla de agrupación (más de 2 archivos del mismo tipo en una carpeta)
+- [ ] Fronteras: `common/` no importa de `modules/` y ningún módulo importa de otro módulo o cliente
+- [ ] El service depende de la interfaz del repository, no de `pg`
+- [ ] Envelope `{ data, meta? }` y errores `{ error: {...} }` con el status correcto
+- [ ] Si cambió `.columns.ts` o los filtros, `FRONT.md` está actualizado y la versión de la clave de caché subió
+
+## Completitud
+
+- [ ] Un spec por archivo, incluidos los casos HIT/MISS/BYPASS
+- [ ] Postman, `FRONT.md` y el README del módulo actualizados
+- [ ] Entrada nueva al final de `docs/EVOLUTIVO.md` (sin reescribir las anteriores) y lo abierto en `docs/PENDIENTES.md`
+- [ ] `docs/EVOLUTIVO.md` no contiene pendientes, bloqueos, stoppers ni riesgos
+- [ ] Variables nuevas en `.env.example`, `.env.local`, la validación y `src/config/configuration.ts` (`AppConfig`)
+- [ ] `./harness/init.sh` termina en 0 sin advertencias nuevas; las preexistentes se reportan, no se corrigen fuera de alcance
+- [ ] Código en inglés, docs en español, commit con formato Conventional Commits

package/harness/reference/configuracion.md

@@ -0,0 +1,104 @@
+# Referencia: variables de entorno
+
+Parte de la base del harness (AGENTS.md §6 a §10). Todas las variables:
+- se declaran en `.env.example` con valores de ejemplo y en `.env.local` con valores locales;
+- se validan en `src/config/` al arrancar.
+
+`.env` nunca lo toca un agente. Si falta una variable requerida, la app falla al arrancar con un mensaje claro.
+
+## Dónde se leen las variables
+
+`process.env` se lee **solo** en `src/config/configuration.ts` (plantilla `harness/skills/nest-base/templates/config/`). Ese archivo agrupa las variables por tema y convierte sus tipos; el resto del código recibe la configuración ya tipada.
+
+```typescript
+// src/config/configuration.ts (extracto)
+export function buildConfiguration(env: Env): AppConfig {
+  return {
+    app: { nodeEnv: text(env, 'NODE_ENV', 'development'), port: int(env, 'PORT', 3000) },
+    databases: parseDatabases(env), // DATABASES=MAIN,REPORTS → { MAIN: { host, port, ... }, REPORTS: {...} }
+    auth: { accessToken: required(env, 'ACCESS_TOKEN'), jwt: { accessSecret: required(env, 'JWT_ACCESS_SECRET'), ... } },
+    // cache, cors, monitor...
+  };
+}
+export default (): AppConfig => buildConfiguration(process.env);
+```
+
+- **Registro:** `ConfigModule.forRoot({ isGlobal: true, envFilePath: ['.env.local', '.env'], validate, load: [configuration] })`. La validación (class-validator) revisa las variables crudas; `configuration.ts` solo agrupa y convierte.
+- **Consumo:** `ConfigService<AppConfig, true>` con rutas tipadas, por ejemplo `config.get('cache.enabled', { infer: true })`. También en `main.ts` (`app.get(ConfigService)`): ni siquiera el puerto se lee de `process.env`.
+- **Secretos sin valor por defecto** (`ACCESS_TOKEN`, `JWT_*_SECRET`, `DB_*_PASSWORD`): si faltan, la app no arranca. El error nombra la variable, nunca su valor. Los defaults son solo para valores no sensibles.
+- **Tests:** los specs y `test/` pueden preparar `process.env`; `buildConfiguration(env)` es una función pura que se prueba con un objeto propio.
+- **Verificación:** ESLint (`configBoundaries` de `eslint.boundaries.mjs`, regla `no-restricted-properties`) e `init.sh` (`env.process-env`, `env.configuration-file`, `env.eslint`).
+
+**Agregar una variable** es, en el mismo cambio: `.env.example` + `.env.local` + validación + `configuration.ts` (y su tipo `AppConfig`) + esta referencia.
+
+## App
+
+```dotenv
+NODE_ENV=development             # development | test | production (default development)
+PORT=3000
+LOG_LEVEL=info                   # en desarrollo se recomienda debug
+LOG_FORMAT=json                  # json (default, producción) | pretty (solo desarrollo local)
+```
+
+- `LOG_FORMAT=pretty` requiere `pino-pretty` en devDependencies y no se acepta con `NODE_ENV=production`. `.env.local` usa `pretty`; `.env.example` documenta `json`.
+
+## Bases de datos (conexiones nombradas)
+
+```dotenv
+DATABASES=MAIN,REPORTS          # una sola BD: DATABASES=MAIN
+
+DB_MAIN_HOST=localhost
+DB_MAIN_PORT=5432
+DB_MAIN_NAME=analytics
+DB_MAIN_USER=readonly_user
+DB_MAIN_PASSWORD=change-me
+DB_MAIN_SSL=false
+DB_MAIN_POOL_MAX=10
+DB_MAIN_STATEMENT_TIMEOUT_MS=30000
+
+DB_REPORTS_HOST=...             # mismo bloque por cada nombre en DATABASES
+```
+
+- `common/database` crea un `Pool` por nombre y lo expone con `getPoolToken('<NOMBRE>')`.
+- Requeridas por conexión: `HOST`, `PORT`, `NAME`, `USER` y `PASSWORD`. `init.sh` las verifica en `.env.example`.
+
+## Caché
+
+```dotenv
+CACHE_ENABLED=true
+REDIS_URL=redis://localhost:6379
+CACHE_DEFAULT_TTL_SECONDS=300
+CACHE_KEY_PREFIX=arness
+CACHE_OP_TIMEOUT_MS=200
+```
+
+## Autenticación
+
+```dotenv
+ACCESS_TOKEN=example123          # contraseña compartida para /auth/login
+JWT_ACCESS_SECRET=change-me
+JWT_ACCESS_EXPIRES_IN=15m
+JWT_REFRESH_SECRET=change-me-too # distinto de JWT_ACCESS_SECRET
+JWT_REFRESH_EXPIRES_IN=7d
+```
+
+## CORS
+
+```dotenv
+CORS_ORIGINS=http://localhost:4200,https://reportes.example.com   # obligatoria; orígenes exactos separados por comas
+CORS_MAX_AGE_SECONDS=600                                           # opcional; caché del preflight (0–86400)
+```
+
+- `CORS_ORIGINS` es **obligatoria**: sin ella la app no arranca. No admite `*` ni comodines, solo orígenes (`esquema://host[:puerto]`, sin ruta), y exige `https://` salvo `localhost`, `127.0.0.1` y `[::1]`.
+- Cada entorno define su lista (desarrollo, QA, producción). `init.sh` verifica que `.env.example` la define y que no lleva `*`.
+
+## Monitor
+
+```dotenv
+MONITOR_ENABLED=false             # true para habilitar GET /monitor; con false responde 404
+MONITOR_SESSION_EXPIRES_IN=15m    # duración de la cookie de sesión del monitor
+```
+
+- Por defecto `false`. Habilítalo solo donde el equipo lo necesite; en producción requiere aprobación.
+- El login usa `ACCESS_TOKEN` y la sesión se firma con `JWT_ACCESS_SECRET`: no hay secretos nuevos.
+- Si existe `src/common/monitor/`, `init.sh` verifica que `.env.example` define ambas variables.

package/harness/reference/contrato-http.md

@@ -0,0 +1,138 @@
+# Referencia: contrato HTTP
+
+Parte de la base del harness (AGENTS.md §8, §9 y §10).
+
+## Respuesta exitosa
+
+`meta` aparece **solo** cuando el endpoint pagina o filtra.
+
+```jsonc
+// Sin paginación ni filtros
+{ "data": [ /* filas */ ] }
+
+// Con paginación y/o filtros
+{
+  "data": [ /* filas */ ],
+  "meta": {
+    "pagination": { "page": 1, "pageSize": 50, "total": 1234, "totalPages": 25 },
+    "filters": { "desde": "2026-01-01", "regional": "ANT" }
+  }
+}
+```
+
+## Respuesta de error
+
+Siempre con el status HTTP correcto. `details` es opcional.
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "El parámetro 'desde' debe ser una fecha ISO",
+    "details": [{ "field": "desde", "issue": "isDateString" }],
+    "requestId": "b1f2c3...",
+    "path": "/api/v1/cartera/resumen",
+    "timestamp": "2026-09-25T14:00:00.000Z"
+  }
+}
+```
+
+| Status | `code` | Origen típico |
+|---|---|---|
+| 400 | `VALIDATION_ERROR` | DTO inválido |
+| 401 | `UNAUTHORIZED` / `TOKEN_EXPIRED` / `INVALID_CREDENTIALS` | guard o login |
+| 403 | `FORBIDDEN` | — |
+| 404 | `NOT_FOUND` | ruta o recurso |
+| 503 | `DATABASE_UNAVAILABLE` | pg: conexión rechazada, `08*`, `57P01` |
+| 504 | `QUERY_TIMEOUT` | pg: `57014` (statement_timeout) |
+| 500 | `INTERNAL_ERROR` | cualquier otro; sin stack ni SQL |
+
+## Autenticación
+
+| Endpoint | Body | Respuesta |
+|---|---|---|
+| `POST /api/v1/auth/login` | `{ "password": "..." }` | `{ data: { accessToken, refreshToken, expiresIn } }` |
+| `POST /api/v1/auth/refresh` | `{ "refreshToken": "..." }` | `{ data: { accessToken, refreshToken, expiresIn } }` |
+
+- `password` se compara con `ACCESS_TOKEN` en tiempo constante: `crypto.timingSafeEqual` sobre el sha256 de ambos valores.
+- Los tokens usan secretos distintos; el claim `type` (`access` o `refresh`) se valida.
+- Los clientes envían `Authorization: Bearer <accessToken>`. Ante `401 TOKEN_EXPIRED`, llaman a `/auth/refresh` y reintentan una vez.
+
+## CORS
+
+Allowlist por entorno: solo los orígenes de `CORS_ORIGINS` reciben `Access-Control-Allow-Origin`. Implementación de referencia: `harness/skills/nest-base/templates/cors/cors.ts` → `src/config/cors.ts`.
+
+| Opción de `app.enableCors()` | Valor |
+|---|---|
+| `origin` | función que acepta solo los orígenes exactos de `CORS_ORIGINS` (sin `Origin` → sin cabeceras CORS) |
+| `methods` | `GET, POST, OPTIONS` |
+| `allowedHeaders` | `Authorization, Content-Type, X-Request-Id` |
+| `exposedHeaders` | `X-Cache, X-Request-Id` |
+| `credentials` | `false` (la API usa `Bearer`, no cookies) |
+| `maxAge` | `CORS_MAX_AGE_SECONDS` (default 600) |
+| `optionsSuccessStatus` | `204` |
+
+- **Validación al arrancar** (`src/config/`): `CORS_ORIGINS` es obligatoria; se rechazan `*` y comodines, valores que no son un origen (`esquema://host[:puerto]`, sin ruta) y `http://` fuera de `localhost`, `127.0.0.1` o `[::1]`.
+- **Prohibido:** `enableCors()` sin opciones, `origin: true`, `origin: '*'`, reflejar el `Origin` recibido o `credentials: true`.
+- **Tests:** `src/config/cors.spec.ts` (parseo y validación) y `test/cors.e2e-spec.ts`: preflight permitido → `204` con `Access-Control-Allow-Origin`, métodos, cabeceras y `max-age`; preflight de un origen no permitido → sin `Access-Control-Allow-Origin`.
+- `init.sh` advierte si `.env.example` no define `CORS_ORIGINS` o lo define con `*`, y si `src/main.ts` no llama a `enableCors` o lo abre a cualquier origen.
+
+## Caché
+
+- Header `X-Cache: HIT | MISS | BYPASS` en toda respuesta cacheable.
+- Clave: `<prefix>:<cliente>:<modulo>:<endpoint>:v<version>:<hash-estable-de-filtros>`. El hash se calcula con sha256 sobre el JSON de los filtros con las claves ordenadas.
+
+## Logging
+
+- JSON estructurado (`nestjs-pino`). `requestId` desde `X-Request-Id` (si es seguro: `[A-Za-z0-9._-]`, máximo 128) o UUID generado, devuelto en la respuesta.
+- Por request: método, ruta, status, duración, resultado de caché y conexión de BD.
+- Redact: `authorization`, cookies (`cookie` y `set-cookie`), `password`, `accessToken`, `refreshToken`, `*_SECRET` y `*_PASSWORD`.
+- Plantilla: `harness/skills/nest-base/templates/logging/logger-options.ts` (`buildLoggerParams`, `parseLogFormat`, `REDACT_PATHS`).
+
+### Formato por entorno (`LOG_FORMAT`)
+
+| Entorno | `LOG_FORMAT` | Ejemplo |
+|---|---|---|
+| Producción, QA, CI (y por defecto) | `json` | `{"level":30,"requestId":"a1b2c3","req":{"method":"GET","url":"/api/v1/cartera/resumen"},"res":{"statusCode":200},"responseTime":42,"msg":"GET /api/v1/cartera/resumen 200 42ms"}` |
+| Desarrollo local | `pretty` | `10:21:03 INFO: [a1b2c3] GET /api/v1/cartera/resumen 200 42ms {"cache":"HIT"}` |
+
+- Ambos formatos llevan los mismos campos y la **misma redacción**: el formato legible nunca muestra secretos.
+- `pretty` usa `pino-pretty`, que es **devDependency**: la imagen de producción no lo incluye. Si se pide `pretty` y no está instalado, el logger vuelve a JSON.
+- La validación rechaza `LOG_FORMAT=pretty` con `NODE_ENV=production`, y cualquier valor distinto de `json` o `pretty`.
+- Los logs no incluyen el SQL ejecutado ni sus parámetros en ningún formato.
+
+## Health
+
+`GET /health` es público y usa terminus. Indicadores:
+- `db_<nombre en minúsculas>`, uno por conexión;
+- `cache`, con estado `up`, `down` o `disabled`.
+
+| Situación | Respuesta |
+|---|---|
+| Todas las BDs arriba | `200` |
+| Alguna BD caída | `503` |
+| Redis caído o deshabilitado | sigue en `200`; `cache: down / disabled` |
+
+`init.sh` consume este formato para informar qué base está caída.
+
+## Monitor
+
+Tablero de estado para el equipo, **fuera de `/api/v1`** y apagado por defecto. Implementación de referencia: `harness/skills/nest-base/templates/monitor/` → `src/common/monitor/`.
+
+| Ruta | Sesión | Respuesta |
+|---|---|---|
+| `GET /monitor` | cookie | HTML con los widgets; sin sesión → `303` a `/monitor/login` |
+| `GET /monitor/login` | — | formulario HTML (`password`) |
+| `POST /monitor/login` | — | correcta → `303` a `/monitor` y `Set-Cookie`; incorrecta → `401` con el formulario y sin cookie |
+| `POST /monitor/logout` | — | borra la cookie (`Max-Age=0`) y `303` a `/monitor/login` |
+
+- **Activación:** `MONITOR_ENABLED=true`. Con cualquier otro valor, todas las rutas responden `404`.
+- **Render:** `react-dom/server` (`renderToStaticMarkup`) con `createElement`, sin JSX, sin hidratación, sin bundler y sin `<script>`. Estilos inline.
+- **Login:** la contraseña se compara con `ACCESS_TOKEN` en tiempo constante, igual que `/auth/login`. Al acertar se emite un JWT con `type: "monitor"` (firmado con `JWT_ACCESS_SECRET`, dura `MONITOR_SESSION_EXPIRES_IN`) en la cookie `arness_monitor`: `HttpOnly; Secure; SameSite=Strict; Path=/monitor; Max-Age=<duración>`. Un access token (`type: "access"`) no sirve como cookie ni la cookie sirve como `Bearer`.
+- **Guards:** el controller lleva `@MonitorRoute()`, que `JwtAuthGuard` omite, y `MonitorSessionGuard`, que exige la cookie salvo en los handlers `@MonitorLogin()` (formulario, login y logout). No es `@Public()`.
+- **Rate limiting:** cuando el harness incorpore límite de intentos para `/auth/login`, el login del monitor lo comparte.
+- **Cabeceras en toda respuesta:** `Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`, `Cache-Control: no-store`, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff` y `Referrer-Policy: no-referrer`.
+- **Widgets:** `MonitorWidget { id; title; order; collect(): Promise<MonitorValue> }`, registrados en el multi-provider `MONITOR_WIDGETS` de `MonitorModule`. Un widget que lanza o tarda más de 2 s se muestra como "No disponible"; el log registra solo el tipo de error, nunca su mensaje.
+- **Widget base `endpoints-total`:** cuenta las rutas HTTP con `DiscoveryService` y `MetadataScanner`, excluye `monitor`, `health` y `auth`, y desglosa por el primer segmento de la ruta (el módulo).
+- **Nunca se muestran:** secretos, variables de entorno, SQL, errores de PostgreSQL ni datos de negocio (filas, montos, nombres de clientes). Solo conteos y estados técnicos.
+- **Tests:** unit de servicio, página, sesión, guard y widget; e2e `test/monitor.e2e-spec.ts` (redirección sin cookie, `401` sin cookie con contraseña incorrecta, login y conteo correcto con controllers de prueba, widget con error que no rompe la página, sin `<script>`, `404` con `MONITOR_ENABLED=false`).

package/harness/reference/novedades.json

@@ -0,0 +1,107 @@
+{
+  "schema": 1,
+  "description": "Novedades adoptables por versión del harness. Las lee `arness doctor` (qué falta adoptar) y `arness sync` (qué trae la versión). Tipos: seguridad | recomendada | opcional. Una novedad está adoptada cuando existen sus `paths` y init.sh no reporta ninguno de sus `checks`.",
+  "novedades": [
+    {
+      "id": "cors-allowlist",
+      "since": "0.2.0",
+      "type": "seguridad",
+      "title": "CORS con allowlist por entorno",
+      "why": "Sin allowlist, cualquier sitio web puede llamar la API desde el navegador de un usuario autenticado.",
+      "checks": ["security.cors-env", "security.cors", "security.cors-open"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Copia harness/skills/nest-base/templates/cors/ (cors.ts y su spec) a src/config/ y valida CORS_ORIGINS al arrancar.",
+        "En src/main.ts usa app.enableCors(buildCorsOptions(...)) con los valores validados.",
+        "Agrega CORS_ORIGINS y CORS_MAX_AGE_SECONDS a .env.example y .env.local, y define los orígenes de cada entorno antes de desplegar."
+      ],
+      "adr": "0006",
+      "reference": "harness/reference/contrato-http.md (CORS)"
+    },
+    {
+      "id": "eslint-boundaries",
+      "since": "0.2.0",
+      "type": "recomendada",
+      "title": "Fronteras de arquitectura verificadas por ESLint",
+      "why": "Evita que common/ dependa de los módulos y que un módulo o cliente importe de otro.",
+      "checks": ["architecture.eslint-boundaries"],
+      "paths": ["eslint.boundaries.mjs"],
+      "approval": null,
+      "steps": [
+        "Copia harness/skills/nest-base/templates/eslint.boundaries.mjs a la raíz.",
+        "Impórtala en eslint.config.mjs y agrega ...architectureBoundaries.",
+        "Si aparecen imports entre módulos, mueve lo compartido a src/common/ cuando toques ese módulo."
+      ],
+      "adr": "0007",
+      "reference": "harness/AGENTS.md §4"
+    },
+    {
+      "id": "monitor",
+      "since": "0.2.0",
+      "type": "opcional",
+      "title": "Tablero monitor (GET /monitor)",
+      "why": "Muestra el estado técnico del backend (endpoints, salud) sin exponer datos de negocio.",
+      "checks": ["security.monitor-env", "security.monitor-guard"],
+      "paths": ["src/common/monitor"],
+      "approval": "react y react-dom (aprobadas en AGENTS.md §2 solo para el monitor); registra la adopción en harness/decisiones/ si el proyecto aún no las usa.",
+      "steps": [
+        "Copia harness/skills/nest-base/templates/monitor/ a src/common/monitor/ y registra MonitorModule.",
+        "Excluye monitor del prefijo global y haz que JwtAuthGuard omita IS_MONITOR_ROUTE_KEY.",
+        "Agrega MONITOR_ENABLED=false y MONITOR_SESSION_EXPIRES_IN=15m a .env.example y .env.local."
+      ],
+      "adr": "0008",
+      "reference": "harness/playbooks/new-monitor-widget.md"
+    },
+    {
+      "id": "env-config",
+      "since": "0.2.0",
+      "type": "recomendada",
+      "title": "Configuración centralizada en src/config/configuration.ts",
+      "why": "Toda la configuración tipada en un solo lugar, sin process.env disperso ni secretos con valor por defecto.",
+      "checks": ["env.configuration-file", "env.process-env", "env.eslint"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Copia harness/skills/nest-base/templates/config/ (configuration.ts y su spec) a src/config/ y regístrala con ConfigModule.forRoot({ load: [configuration] }).",
+        "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."
+      ],
+      "adr": "0009",
+      "reference": "harness/reference/configuracion.md (Dónde se leen las variables)"
+    },
+    {
+      "id": "log-format",
+      "since": "0.2.0",
+      "type": "opcional",
+      "title": "Logs legibles en desarrollo (LOG_FORMAT=pretty)",
+      "why": "Una línea legible por petición en la terminal local; producción sigue en JSON.",
+      "checks": ["logging.format-env"],
+      "paths": [],
+      "approval": "pino-pretty, solo como devDependency (aprobada en AGENTS.md §2).",
+      "steps": [
+        "pnpm add -D pino-pretty",
+        "Copia harness/skills/nest-base/templates/logging/ a src/common/logging/ y usa buildLoggerParams en LoggerModule.forRootAsync.",
+        "Agrega LOG_FORMAT=json a .env.example y LOG_FORMAT=pretty a .env.local."
+      ],
+      "adr": "0010",
+      "reference": "harness/reference/contrato-http.md (Logging)"
+    },
+    {
+      "id": "project-docs",
+      "since": "0.2.0",
+      "type": "recomendada",
+      "title": "Documentación del proyecto en docs/ (técnico, evolutivo y pendientes)",
+      "why": "Negocio ve lo entregado en EVOLUTIVO.md y lo abierto queda en PENDIENTES.md, sin mezclarse.",
+      "checks": ["docs.files"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Copia harness/skills/nest-base/templates/docs/ a docs/.",
+        "Completa docs/TECNICO.md con lo que ya existe y, si quieres, resume lo entregado en docs/EVOLUTIVO.md."
+      ],
+      "adr": "0011",
+      "reference": "harness/AGENTS.md §12"
+    }
+  ]
+}

package/harness/reference/progress-plantilla.md

@@ -0,0 +1,50 @@
+# Progress
+
+> Estado compartido del trabajo en curso. **Solo lo escribe el `lider`**; el `implementador` y el `revisor` lo leen.
+> Aquí van resúmenes, no diffs ni logs completos. Mantenlo por debajo de ~150 líneas: las tareas cerradas se reducen a una línea en la tabla.
+
+## Objetivo
+
+<Qué pidió el humano, en una o dos frases.>
+
+## Estado
+
+- **Estado:** EN CURSO
+- **Actualizado:** AAAA-MM-DD HH:MM
+- **init.sh (última ejecución):** <fecha> · <exit 0 + N advertencias | exit 1: resumen de fallos>
+- **Línea base de advertencias (inicio de la sesión):** <ids de init.sh --json, o "ninguna">
+
+## Contrato confirmado
+
+<Lo confirmado con el humano (AGENTS.md §15.1): cliente/módulo/segmento, conexión y origen, columnas, filtros, paginación, TTL. Escribe "—" si no aplica.>
+
+## Decisiones de esta sesión
+
+- <Enlaces a harness/decisiones/NNNN-*.md aceptadas o propuestas, y acuerdos del humano que aún no son decisión formal.>
+
+## Tareas
+
+| ID | Tarea | Responsable | Estado | Ronda | Veredicto |
+|---|---|---|---|---|---|
+| T-001 | <título> | implementador | PENDIENTE | 0 | — |
+
+Estados: `PENDIENTE` · `EN CURSO` · `EN REVISIÓN` · `CAMBIOS REQUERIDOS` · `APROBADA` · `BLOQUEADA`.
+
+## Detalle por tarea
+
+### T-001 · <título>
+
+- **Encargo:** objetivo, playbook, archivos y criterios de aceptación.
+- **Fuera de alcance:** <...>
+- **Última entrega:** <resumen del reporte del implementador>
+- **Último veredicto:** <resumen de los hallazgos del revisor, con archivo:línea>
+
+## Bloqueos y preguntas abiertas
+
+- <Pregunta o bloqueo · a quién le toca responder>
+
+## Bitácora
+
+<Append-only: una línea por evento.>
+
+- AAAA-MM-DD HH:MM · lider · <evento>