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

package/harness/reference/novedades.json

@@ -0,0 +1,158 @@
+{
+  "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. Requiere SecurityModule (templates/security/), que comparte el límite de intentos del login.",
+        "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"
+    },
+    {
+      "id": "login-rate-limit",
+      "since": "0.3.0",
+      "type": "seguridad",
+      "title": "Límite de intentos en /auth/login y /monitor/login",
+      "why": "Toda la API se protege con una contraseña compartida: sin límite se puede adivinar por fuerza bruta.",
+      "checks": ["security.login-rate-limit", "security.trust-proxy"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Copia harness/skills/nest-base/templates/security/ a src/common/security/ y registra SecurityModule en app.module.ts. Copia también templates/config/auth.ts (y su spec) y usa auth: parseAuthConfig(env) en configuration.ts.",
+        "En el login: check(req.ip) → 429 TOO_MANY_ATTEMPTS con Retry-After; contraseña incorrecta → registerFailure(req.ip); correcta → reset(req.ip). Copia también templates/monitor/monitor.controller.ts si usas el monitor.",
+        "Agrega AUTH_LOGIN_MAX_ATTEMPTS, AUTH_LOGIN_WINDOW_SECONDS y HTTP_TRUST_PROXY_HOPS (1 detrás de Azure App Service) y, en main.ts, app.set(\"trust proxy\", hops) solo si hops > 0.",
+        "Avisa a frontend: ante 429 se espera lo que indica Retry-After (FRONT.md)."
+      ],
+      "adr": "0017",
+      "reference": "harness/reference/contrato-http.md (Autenticación › Límite de intentos)"
+    },
+    {
+      "id": "session-max-age",
+      "since": "0.3.0",
+      "type": "seguridad",
+      "title": "Vida máxima de la sesión en /auth/refresh",
+      "why": "Cada refresh entregaba un par nuevo sin límite: un refresh token robado servía indefinidamente.",
+      "checks": ["security.session-max-age"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Con src/common/security/ ya copiado, firma el par con sessionClaims(authTime): el login usa nowInSeconds() y el refresh copia el auth_time del refresh token.",
+        "En el refresh, si isSessionExpired(payload, sessionMaxAgeSeconds) responde 401 SESSION_EXPIRED.",
+        "Agrega AUTH_SESSION_MAX_AGE_SECONDS=43200 a .env.example y .env.local, y avisa a frontend: ante 401 SESSION_EXPIRED vuelve al login. Los refresh tokens emitidos antes no traen auth_time y exigirán un login nuevo."
+      ],
+      "adr": "0017",
+      "reference": "harness/reference/contrato-http.md (Autenticación › Vida máxima de la sesión)"
+    },
+    {
+      "id": "security-headers",
+      "since": "0.3.0",
+      "type": "seguridad",
+      "title": "Cabeceras de seguridad en toda respuesta",
+      "why": "Sin CSP, nosniff, X-Frame-Options ni no-store, el navegador puede interpretar o guardar en caché respuestas con datos privados.",
+      "checks": ["security.headers"],
+      "paths": [],
+      "approval": null,
+      "steps": [
+        "Con src/common/security/ ya copiado, agrega app.use(securityHeaders()) en src/main.ts antes de registrar las rutas.",
+        "Verifica en test/ que una respuesta de la API trae las cabeceras y no trae X-Powered-By."
+      ],
+      "adr": "0017",
+      "reference": "harness/reference/contrato-http.md (Cabeceras de seguridad)"
+    }
+  ]
+}

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>

package/harness/skills/commit-hygiene/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: engram-commit-hygiene
+description: >
+  Commit and branch naming standards for Engram contributors, enforced by GitHub rulesets.
+  Trigger: Any commit creation, review, or branch cleanup.
+license: Apache-2.0
+metadata:
+  author: gentleman-programming
+  version: "2.0"
+---
+
+## When to Use
+
+Use this skill when:
+- Creating commits
+- Creating or naming branches
+- Reviewing commit history in a PR
+- Cleaning up staged changes
+
+---
+
+## Critical Rules
+
+1. **Commit messages MUST follow Conventional Commits** — enforced by GitHub ruleset, rejected on push if invalid
+2. **Branch names MUST follow `type/description` format** — enforced by GitHub ruleset, rejected on push if invalid
+3. Keep one logical change per commit
+4. Message should explain **why**, not only what
+5. **NEVER** include `Co-Authored-By` trailers
+6. **NEVER** commit paths prohibited by the [Transient Artifact Policy](../../CONTRIBUTING.md#transient-artifact-policy)
+
+---
+
+## Commit Message Format (enforced by GitHub ruleset)
+
+**Regex:** `^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+`
+
+```
+<type>(<optional-scope>): <description>
+<type>(<optional-scope>)!: <description>   ← breaking change
+```
+
+### Allowed Types
+
+| Type | Purpose |
+|------|---------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `refactor` | Code refactoring (no behavior change) |
+| `chore` | Maintenance, dependencies |
+| `style` | Formatting, whitespace |
+| `perf` | Performance improvement |
+| `test` | Adding or fixing tests |
+| `build` | Build system changes |
+| `ci` | CI/CD pipeline changes |
+| `revert` | Revert a previous commit |
+
+### Rules
+- Type MUST be lowercase, one of the listed values
+- Scope is optional, lowercase, allows `a-z`, `0-9`, `.`, `_`, `-`
+- `!` before `:` marks a breaking change
+- Description MUST start after `: ` (colon + space)
+- Description should be imperative mood ("add", not "added" or "adds")
+
+### Valid Examples
+```
+feat(cli): add --json flag to session list command
+fix(store): prevent duplicate observation insert on retry
+docs(contributing): update workflow documentation
+refactor(internal): extract search query sanitizer
+chore(deps): bump github.com/charmbracelet/bubbletea to v0.26
+style(tui): fix alignment in session detail view
+perf(store): optimize FTS5 query for large datasets
+test(sync): add coverage for conflict resolution
+ci(workflows): split e2e into separate job
+fix!: change session ID format
+```
+
+### Invalid Examples (push will be rejected)
+```
+Fix bug                          ← no type prefix
+feat: Add login                  ← description should be lowercase
+FEAT(cli): add flag              ← type must be lowercase
+feat (cli): add flag             ← no space before scope
+feat(CLI): add flag              ← scope must be lowercase
+update docs                      ← no conventional commit format
+```
+
+---
+
+## Branch Naming Format (enforced by GitHub ruleset)
+
+**Regex:** `^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$`
+
+```
+<type>/<description>
+```
+
+### Allowed Types
+
+`feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `revert`
+
+### Rules
+- Type MUST be one of the listed values
+- Description MUST be lowercase
+- Only `a-z`, `0-9`, `.`, `_`, `-` allowed in description
+- No uppercase, no spaces, no special characters
+
+### Valid Examples
+```
+feat/json-export-command
+fix/duplicate-observation-insert
+docs/api-reference-update
+refactor/extract-query-sanitizer
+chore/bump-bubbletea-v0.26
+ci/split-e2e-job
+```
+
+### Invalid Examples (push will be rejected)
+```
+feature/add-login                ← "feature" not allowed, use "feat"
+fix/Add-Login                    ← uppercase not allowed
+my-branch                        ← no type prefix
+fix_something                    ← missing "/" separator
+```
+
+---
+
+## Pre-Commit Checklist
+
+- [ ] Commit message matches conventional commits format
+- [ ] Branch name matches `type/description` format
+- [ ] Diff matches commit scope (no unrelated changes)
+- [ ] No secrets, credentials, or `.env` files
+- [ ] Every changed path complies with the [Transient Artifact Policy](../../CONTRIBUTING.md#transient-artifact-policy)
+- [ ] No `Co-Authored-By` trailers
+- [ ] Tests relevant to the change pass

package/harness/skills/nest-base/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: nest-base
+description: Crea la base del proyecto NestJS de este harness (Node.js en su última LTS, NestJS en su última versión estable, pnpm, ESLint y Prettier configurados, y la estructura common/ de AGENTS.md). Úsala solo cuando el repositorio aún no tiene package.json y el humano pide inicializar o crear la base del backend.
+---
+
+# Skill: nest-base
+
+Crea el esqueleto NestJS que exige `AGENTS.md`. Esta skill **instala dependencias y consulta la red**, así que solo se ejecuta cuando el humano lo pide expresamente.
+
+Referencias: `AGENTS.md` §2 (stack y dependencias aprobadas), §4 (estructura y fronteras), §6 a §10 (BD, caché, auth, contrato HTTP y CORS, logging, health y monitor) y §13 (prohibiciones). Detalle de implementación: `harness/reference/configuracion.md` (variables) y `harness/reference/contrato-http.md` (envelope, errores, auth, CORS, caché, logging, health, monitor).
+
+**Plantillas** (`harness/skills/nest-base/templates/`): se copian tal cual al proyecto, sin cambiar su intención. Cada archivo indica su destino en la primera línea; quita ese comentario al copiarlo.
+
+**Raíz del proyecto (`ROOT`):** la carpeta que **contiene** `harness/`, no `harness/` ni el directorio actual. Antes de empezar, haz `cd` a `ROOT`; todas las rutas de esta skill son relativas a él. El proyecto NestJS se crea en `ROOT`, nunca dentro de `harness/`.
+
+## 0. Precondiciones: si alguna falla, detente e informa
+
+1. `./harness/init.sh` termina en 0. Sin `package.json` corre en modo "solo harness".
+2. **No existe `package.json`.** Si existe, la base ya fue creada: no la regeneres; informa y termina.
+3. `pnpm` está disponible (`pnpm -v`). Nunca uses npm ni yarn.
+
+## 1. Resolver versiones (siempre las actuales, nunca de memoria)
+
+```bash
+# Node.js: última LTS publicada
+curl -fsSL https://nodejs.org/dist/index.json \
+  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const r=JSON.parse(s).find(x=>x.lts);console.log(r.version, r.lts)})'
+
+# NestJS: última versión estable (dist-tag "latest", nunca next/beta/rc)
+pnpm view @nestjs/cli version
+pnpm view @nestjs/core version
+
+# pnpm: última estable
+pnpm view pnpm version
+```
+
+- NestJS no publica una línea "LTS". En este harness, "última LTS de NestJS" significa **la última versión estable del dist-tag `latest`**.
+- Si el major de `node -v` no coincide con la LTS resuelta, **detente**. Pide al humano que la instale (por ejemplo `nvm install --lts` o `fnm install --lts`). No instales Node por tu cuenta.
+- Informa al humano las versiones resueltas antes de continuar.
+
+## 2. Generar el proyecto sin pisar el harness
+
+```bash
+# ROOT = primera carpeta hacia arriba que contiene harness/AGENTS.md
+ROOT="$(pwd)"; while [ "$ROOT" != "/" ] && [ ! -f "$ROOT/harness/AGENTS.md" ]; do ROOT="$(dirname "$ROOT")"; done
+[ -f "$ROOT/harness/AGENTS.md" ] || { echo "No se encontró harness/AGENTS.md"; exit 1; }
+cd "$ROOT"
+TMP="$(mktemp -d)"
+pnpm dlx @nestjs/cli@<version-cli> new <nombre-paquete> \
+  --package-manager pnpm --strict --skip-git --directory "$TMP/app"
+rsync -a --ignore-existing --exclude node_modules "$TMP/app/" "$ROOT/"
+rm -rf "$TMP"
+```
+
+- `<nombre-paquete>`: el nombre del directorio del repo en kebab-case, salvo que el humano indique otro.
+- `--ignore-existing` protege `harness/` y los puentes de la raíz (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/`, `.claude/` y `.agents/`).
+- Elimina el ejemplo de Nest (`app.controller.ts`, `app.service.ts`, su spec y `test/app.e2e-spec.ts`).
+- Reemplaza el `README.md` generado por uno breve en español que apunte a `AGENTS.md` y a `./harness/init.sh`.
+
+## 3. Dependencias (solo las aprobadas en AGENTS.md §2)
+
+```bash
+pnpm install
+pnpm add @nestjs/config @nestjs/jwt @nestjs/terminus pg ioredis \
+  class-validator class-transformer nestjs-pino pino-http react react-dom
+pnpm add -D @types/pg @types/react @types/react-dom pino-pretty
+```
+
+- Sin versiones fijadas a mano: pnpm resuelve la última estable y el lockfile las congela.
+- `react` y `react-dom` son solo para el monitor (`src/common/monitor/`); no se usan en ningún otro lugar.
+- `pino-pretty` va **solo en devDependencies**: formato legible de logs en desarrollo (`LOG_FORMAT=pretty`).
+- Si pnpm avisa que ignoró scripts de build (`pnpm approve-builds`), muestra la lista al humano y espera su aprobación.
+- Agrega el harness como devDependency desde npm, con la versión exacta del manifiesto:
+  ```bash
+  pnpm add -D "@bi-analytics/arness-back@$(node -p "require('./harness/.arness.json').version")"
+  ```
+  Si falla (red o registro), detente e informa; no lo quites de la lista.
+- Cualquier paquete adicional requiere aprobación explícita y una decisión en `harness/decisiones/`.
+
+## 4. Toolchain, ESLint y Prettier
+
+1. **Node fijado:** crea `.nvmrc` con la versión LTS resuelta (ej. `v24.11.0`). En `package.json` define:
+   - `"engines": { "node": ">=<major>" }`
+   - `"packageManager": "pnpm@<version>"`
+2. **Scripts de `package.json`:** agrega o ajusta estos. `init.sh` depende de `lint:check`, `format:check`, `build`, `test` y `test:e2e`.
+   ```json
+   {
+     "lint": "eslint \"{src,test}/**/*.ts\" --fix",
+     "lint:check": "eslint \"{src,test}/**/*.ts\" --max-warnings 0",
+     "format": "prettier --write \"{src,test}/**/*.ts\"",
+     "format:check": "prettier --check \"{src,test}/**/*.ts\"",
+     "verify": "./harness/init.sh",
+     "harness:status": "arness status",
+     "harness:sync": "arness sync"
+   }
+   ```
+3. **ESLint:** reemplaza `eslint.config.mjs` con `harness/skills/nest-base/templates/eslint.config.mjs` y copia `.../templates/eslint.boundaries.mjs` a la raíz (la importa `eslint.config.mjs`). Si la versión generada por Nest usa una API distinta (por ejemplo `defineConfig`), conserva su base y porta el bloque de reglas del harness y los overrides por archivo sin cambiar su intención:
+   - no `any`;
+   - no `console`;
+   - no promesas flotantes;
+   - `pg` solo en `common/database` y `*.repository.ts`;
+   - texto SQL solo en `*.sql.ts` (también tras saltos de línea o `(`, e incluidas escrituras);
+   - nada de escrituras o DDL en `*.sql.ts`;
+   - fronteras (`eslint.boundaries.mjs`): `src/common` no importa de `src/modules`, y un módulo no importa de otro módulo ni de otro cliente; solo sale hacia `src/common` y `src/config`. Usa `@typescript-eslint/no-restricted-imports`, separada de la regla de `pg`, sin dependencias nuevas;
+   - configuración (`configBoundaries` de `eslint.boundaries.mjs`): `process.env` solo en `src/config/`, salvo specs y `test/`.
+4. **Prettier:** copia `harness/skills/nest-base/templates/prettierrc.json` → `.prettierrc` y `.../templates/prettierignore` → `.prettierignore`.
+5. **Editor:** copia `harness/skills/nest-base/templates/editorconfig` → `.editorconfig`.
+6. **Aislar el harness del proyecto:**
+   - `tsconfig.json` y `tsconfig.build.json`: agrega `"harness"` a `exclude`.
+   - `.dockerignore`: incluye `harness`, `.agents`, `.claude`, `.cursor`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.env`, `.env.local`, `node_modules`, `dist` y `coverage`.
+   - `.prettierignore`: agrega `harness`.
+7. **`.gitignore`:** asegúrate de que incluye `dist/`, `coverage/`, `node_modules/`, `logs/`, `.env`, `.env.local`, `.env.*.local` y `harness/progress.md`.
+8. **Convención SQL:** las palabras clave SQL se escriben en MAYÚSCULAS. Así las detectan la regla de ESLint y `init.sh`.
+
+## 5. Estructura base (AGENTS.md §4)
+
+Implementa cada pieza con su spec. Sin lógica de negocio y sin módulos de ejemplo: `src/modules/` queda vacío con un `.gitkeep`.
+
+| Ruta | Contenido mínimo |
+|---|---|
+| `src/main.ts` | Logger pino (`bufferLogs`), prefijo `api/v1` excluyendo `health` y `monitor` (`{ exclude: ['health', 'monitor', 'monitor/{*path}'] }`, o la sintaxis de rutas de la versión de Nest), `ValidationPipe({ whitelist, forbidNonWhitelisted, transform })`, `app.enableCors(buildCorsOptions(...))` con los valores validados de config, `app.use(securityHeaders())` antes de las rutas, `app.set('trust proxy', hops)` solo si `app.trustProxyHops > 0` (`NestExpressApplication`), `enableShutdownHooks`, puerto desde `ConfigService` (`app.port`), nunca de `process.env` |
+| `src/app.module.ts` | Importa config, logging, database, cache, auth, health; registra el guard JWT global y el filtro de errores |
+| `src/config/` | `ConfigModule` global con `envFilePath: ['.env.local', '.env']`, `validate` y `load: [configuration]`; validación con class-validator que falla al arrancar, incluida la validación dinámica de `DB_<NOMBRE>_*` por cada nombre en `DATABASES`. `configuration.ts` y `configuration.spec.ts` desde `templates/config/`: **único lugar que lee `process.env`**, exporta `AppConfig` y no da valor por defecto a ningún secreto. `auth.ts` y `auth.spec.ts` desde `templates/config/`: `configuration.ts` llama a `parseAuthConfig` (secretos obligatorios, límite de intentos y vida de la sesión). `cors.ts` y `cors.spec.ts` desde `templates/cors/`: la validación y `configuration.ts` llaman a `parseCorsOrigins` y `parseCorsMaxAge`, así que la app no arranca sin `CORS_ORIGINS` o con `*`. El resto del código consume `ConfigService<AppConfig, true>` |
+| `src/common/database/` | `DatabaseModule` dinámico: un `Pool` por nombre, `getPoolToken(name)`, sesión con `default_transaction_read_only=on` y `statement_timeout`, cierre en shutdown |
+| `src/common/cache/` | `CacheService` sobre ioredis (`lazyConnect`, `enableOfflineQueue: false`, `commandTimeout`, reintentos con backoff). No lanza nunca y devuelve `HIT` / `MISS` / `BYPASS`. Hash estable de filtros (claves ordenadas → sha256). Con `CACHE_ENABLED=false` no conecta |
+| `src/common/security/` | Copia `templates/security/` completo (con sus specs) y registra `SecurityModule` (global) en `app.module.ts`: `LoginAttemptLimiter`, `securityHeaders()` y `sessionClaims` / `isSessionExpired` (contrato-http.md, Autenticación y Cabeceras de seguridad) |
+| `src/common/auth/` | `POST auth/login` y `POST auth/refresh` (`@Public()`), `timingSafeEqual` sobre sha256 de ambos valores, secretos distintos y claim `type`, `JwtAuthGuard` como `APP_GUARD`. Login con `LoginAttemptLimiter` por `req.ip` (`429 TOO_MANY_ATTEMPTS` con `Retry-After`). El par lleva `auth_time` (`sessionClaims`): el login lo fija y el refresh lo copia; `isSessionExpired` → `401 SESSION_EXPIRED`. El guard omite las rutas con `@Public()` y con `IS_MONITOR_ROUTE_KEY` (`@MonitorRoute()`, de `src/common/monitor/monitor.decorators.ts`) |
+| `src/common/http/` | Tipos `{ data, meta? }`, filtro global de errores `{ error: { code, message, details?, requestId, path, timestamp } }`. Errores de pg: `57014` → 504 `QUERY_TIMEOUT`; errores de conexión o `08*` / `57P01` → 503 `DATABASE_UNAVAILABLE` |
+| `src/common/logging/` | `logger-options.ts` y su spec desde `templates/logging/`; `LoggerModule.forRootAsync` con `buildLoggerParams(config.get('logging', { infer: true }))`. JSON por defecto, `pretty` en desarrollo con `LOG_FORMAT`, `genReqId` desde `X-Request-Id` seguro o UUID y devuelto en la respuesta, `redact` de authorization, cookies, password, tokens y secretos |
+| `src/common/health/` | `GET /health` público con terminus. Indicadores `db_<nombre en minúsculas>` por conexión y `cache` con estado `up` / `down` / `disabled`; la caché nunca vuelve el health a 503 |
+| `src/common/monitor/` | Copia `templates/monitor/` completo (con sus specs) y registra `MonitorModule` en `app.module.ts`. `GET /monitor` fuera de `/api/v1`, `404` si `MONITOR_ENABLED` no es `true`, login con `ACCESS_TOKEN` y cookie de sesión, cabeceras CSP sin scripts, widget base `endpoints-total` (contrato-http.md, Monitor) |
+| `test/` | `auth.e2e-spec.ts` (login OK, login inválido, refresh, 401 sin token, `429` con `Retry-After` tras `AUTH_LOGIN_MAX_ATTEMPTS` fallos, `401 SESSION_EXPIRED` al refrescar pasada la vida máxima, refresh token y token del monitor como `Bearer` → 401, access token en `/auth/refresh` → 401, cabeceras de seguridad y sin `X-Powered-By`), `health.e2e-spec.ts` (pools y Redis mockeados con `overrideProvider`), y `cors.e2e-spec.ts` y `monitor.e2e-spec.ts` desde `templates/e2e/` |
+
+### Archivos de soporte
+
+- **`.env.example` y `.env.local`:** las mismas claves. Incluyen `NODE_ENV=development`, `PORT=3000`, `DATABASES=MAIN`, `DB_MAIN_*`, `ACCESS_TOKEN=example123`, `JWT_*`, `AUTH_SESSION_MAX_AGE_SECONDS=43200`, `AUTH_LOGIN_MAX_ATTEMPTS=5`, `AUTH_LOGIN_WINDOW_SECONDS=900`, `HTTP_TRUST_PROXY_HOPS=0`, `CACHE_*`, `REDIS_URL`, `LOG_LEVEL`, `LOG_FORMAT` (`json` en `.env.example`, `pretty` en `.env.local`), `CORS_ORIGINS=http://localhost:4200`, `CORS_MAX_AGE_SECONDS=600`, `MONITOR_ENABLED=false` y `MONITOR_SESSION_EXPIRES_IN=15m`. En `.env.example` todos los secretos llevan valores de ejemplo. **No crees ni toques `.env`.**
+- **`postman/arness-back.postman_collection.json`** (formato v2.1): variables `baseUrl`, `accessToken` y `refreshToken`, y auth Bearer heredada. Carpeta `Auth` con Login (su script de test guarda los tokens) y Refresh, más la request `Health`. Agrega también `postman/local.postman_environment.json` con `baseUrl=http://localhost:3000`.
+- **`FRONT.md`:**
+  - flujo de auth (login, uso del Bearer, refresh ante `401 TOKEN_EXPIRED`, volver al login ante `401 SESSION_EXPIRED`, y ante `429` esperar lo que indica `Retry-After`);
+  - envelope `{ data, meta? }` y formato de error;
+  - significado de `X-Cache`;
+  - CORS: el origen del frontend debe estar en `CORS_ORIGINS` de cada entorno (pedirlo al backend);
+  - endpoints de Auth con su consumo recomendado.
+- **`docs/`:** copia `templates/docs/` (`TECNICO.md`, `EVOLUTIVO.md` y `PENDIENTES.md`). Completa en `TECNICO.md` lo que ya se sabe (cliente, conexión `MAIN`, entornos) y deja en `EVOLUTIVO.md` la entrada "Base del proyecto" con la fecha y hora de Bogotá y el responsable (formato de la plantilla). Los pendientes del reporte final (§7) van a `PENDIENTES.md`.
+- **`Dockerfile`:** multi-stage con `node:<major-lts>-alpine`, `corepack enable`, `pnpm install --frozen-lockfile`, build y una imagen final solo con `dist/` y las dependencias de producción; usuario no root y `HEALTHCHECK` sobre `/health`.
+- **`azure-pipelines.yml`:** Node desde `.nvmrc`, `corepack enable`, `pnpm install --frozen-lockfile`, `lint:check`, `format:check`, `build`, `test` y `docker build`.
+
+## 6. Verificar (con protección contra bucles)
+
+```bash
+pnpm lint && pnpm format
+./harness/init.sh --strict
+```
+
+- Un proyecto nuevo nace cumpliendo todo: `./harness/init.sh --strict` debe terminar en 0, incluido `/health`. Los proyectos existentes usan el modo por defecto (advertencias). Si no hay PostgreSQL local disponible, el health informará las BDs caídas: repórtalo al humano y no lo "arregles" desactivando checks.
+- Corrige solo fallos causados por archivos que esta skill creó. **Máximo 3 intentos de corrección.** Si sigue fallando, detente y reporta la salida de `init.sh`.
+- Nunca relajes reglas de ESLint, umbrales ni checks de `init.sh` para pasar.
+
+## 7. Reporte final
+
+Informa:
+- las versiones resueltas (Node LTS, NestJS, pnpm);
+- los archivos creados;
+- las dependencias instaladas;
+- el resultado de `./harness/init.sh`;
+- los pendientes (por ejemplo, credenciales reales de BD en `.env.local`).
+
+No hagas commit salvo que el humano lo pida.

package/harness/skills/nest-base/templates/config/auth.spec.ts

@@ -0,0 +1,32 @@
+// Plantilla del harness → src/config/auth.spec.ts
+import { parseAuthConfig } from './auth';
+
+const base = {
+  ACCESS_TOKEN: 'example123',
+  JWT_ACCESS_SECRET: 'access-secret',
+  JWT_REFRESH_SECRET: 'refresh-secret',
+};
+
+describe('parseAuthConfig', () => {
+  it('applies non-sensitive defaults', () => {
+    const auth = parseAuthConfig(base);
+    expect(auth.jwt).toEqual({
+      accessSecret: 'access-secret',
+      accessExpiresIn: '15m',
+      refreshSecret: 'refresh-secret',
+      refreshExpiresIn: '7d',
+    });
+    expect(auth.login).toEqual({ maxAttempts: 5, windowSeconds: 900 });
+    expect(auth.sessionMaxAgeSeconds).toBe(43200);
+  });
+
+  it.each([
+    [{ ACCESS_TOKEN: undefined }, /ACCESS_TOKEN is required/],
+    [{ JWT_REFRESH_SECRET: ' ' }, /JWT_REFRESH_SECRET is required/],
+    [{ AUTH_LOGIN_MAX_ATTEMPTS: '0' }, /AUTH_LOGIN_MAX_ATTEMPTS must be an integer/],
+    [{ AUTH_LOGIN_WINDOW_SECONDS: 'abc' }, /AUTH_LOGIN_WINDOW_SECONDS must be an integer/],
+    [{ AUTH_SESSION_MAX_AGE_SECONDS: '30' }, /AUTH_SESSION_MAX_AGE_SECONDS must be an integer/],
+  ])('rejects %p', (overrides, message) => {
+    expect(() => parseAuthConfig({ ...base, ...overrides })).toThrow(message);
+  });
+});

package/harness/skills/nest-base/templates/config/auth.ts

@@ -0,0 +1,80 @@
+// Plantilla del harness → src/config/auth.ts (AGENTS.md §8, harness/reference/configuracion.md "Autenticación").
+// Auth block of AppConfig: secrets (required, no default), login attempt limit and session max age.
+// Errors name the variable, never its value.
+
+export const AUTH_DEFAULT_LOGIN_MAX_ATTEMPTS = 5;
+export const AUTH_DEFAULT_LOGIN_WINDOW_SECONDS = 900;
+export const AUTH_DEFAULT_SESSION_MAX_AGE_SECONDS = 43200;
+
+export interface AuthConfig {
+  accessToken: string;
+  jwt: {
+    accessSecret: string;
+    accessExpiresIn: string;
+    refreshSecret: string;
+    refreshExpiresIn: string;
+  };
+  login: { maxAttempts: number; windowSeconds: number };
+  sessionMaxAgeSeconds: number;
+}
+
+type Env = Record<string, string | undefined>;
+
+function required(env: Env, name: string): string {
+  const value = env[name];
+  if (value === undefined || value.trim() === '') {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}
+
+function intInRange(env: Env, name: string, fallback: number, min: number, max: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim() === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+
+function text(env: Env, name: string, fallback: string): string {
+  const value = env[name];
+  return value === undefined || value.trim() === '' ? fallback : value.trim();
+}
+
+/** Pure: reads and validates the auth block. */
+export function parseAuthConfig(env: Env): AuthConfig {
+  return {
+    accessToken: required(env, 'ACCESS_TOKEN'),
+    jwt: {
+      accessSecret: required(env, 'JWT_ACCESS_SECRET'),
+      accessExpiresIn: text(env, 'JWT_ACCESS_EXPIRES_IN', '15m'),
+      refreshSecret: required(env, 'JWT_REFRESH_SECRET'),
+      refreshExpiresIn: text(env, 'JWT_REFRESH_EXPIRES_IN', '7d'),
+    },
+    login: {
+      maxAttempts: intInRange(
+        env,
+        'AUTH_LOGIN_MAX_ATTEMPTS',
+        AUTH_DEFAULT_LOGIN_MAX_ATTEMPTS,
+        1,
+        100,
+      ),
+      windowSeconds: intInRange(
+        env,
+        'AUTH_LOGIN_WINDOW_SECONDS',
+        AUTH_DEFAULT_LOGIN_WINDOW_SECONDS,
+        1,
+        86400,
+      ),
+    },
+    sessionMaxAgeSeconds: intInRange(
+      env,
+      'AUTH_SESSION_MAX_AGE_SECONDS',
+      AUTH_DEFAULT_SESSION_MAX_AGE_SECONDS,
+      60,
+      2592000,
+    ),
+  };
+}