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

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,167 @@
+---
+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, `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. `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/auth/` | `POST auth/login` y `POST auth/refresh` (`@Public()`), `timingSafeEqual` sobre sha256 de ambos valores, secretos distintos y claim `type`, `JwtAuthGuard` como `APP_GUARD`. 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), `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_*`, `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`);
+  - 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 de hoy. 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/configuration.spec.ts

@@ -0,0 +1,84 @@
+// Plantilla del harness → src/config/configuration.spec.ts
+import { buildConfiguration, type Env } from './configuration';
+
+const base: Env = {
+  DATABASES: 'MAIN',
+  DB_MAIN_HOST: 'localhost',
+  DB_MAIN_NAME: 'analytics',
+  DB_MAIN_USER: 'readonly_user',
+  DB_MAIN_PASSWORD: 'change-me',
+  ACCESS_TOKEN: 'example123',
+  JWT_ACCESS_SECRET: 'access-secret',
+  JWT_REFRESH_SECRET: 'refresh-secret',
+  CORS_ORIGINS: 'http://localhost:4200',
+};
+
+describe('buildConfiguration', () => {
+  it('groups variables by topic and applies non-sensitive defaults', () => {
+    const config = buildConfiguration(base);
+    expect(config.app).toEqual({ nodeEnv: 'development', port: 3000 });
+    expect(config.logging).toEqual({ level: 'info', format: 'json' });
+    expect(config.databases.MAIN).toEqual({
+      host: 'localhost',
+      port: 5432,
+      name: 'analytics',
+      user: 'readonly_user',
+      password: 'change-me',
+      ssl: false,
+      poolMax: 10,
+      statementTimeoutMs: 30000,
+    });
+    expect(config.cache.enabled).toBe(false);
+    expect(config.auth.jwt.accessExpiresIn).toBe('15m');
+    expect(config.cors).toEqual({ origins: ['http://localhost:4200'], maxAgeSeconds: 600 });
+    expect(config.monitor).toEqual({ enabled: false, sessionExpiresIn: '15m' });
+  });
+
+  it('converts numbers, booleans and one block per database', () => {
+    const config = buildConfiguration({
+      ...base,
+      PORT: '8080',
+      DATABASES: 'MAIN, reports',
+      DB_MAIN_SSL: 'true',
+      DB_REPORTS_HOST: 'replica',
+      DB_REPORTS_PORT: '6432',
+      DB_REPORTS_NAME: 'reports',
+      DB_REPORTS_USER: 'ro',
+      DB_REPORTS_PASSWORD: 'x',
+      CACHE_ENABLED: 'true',
+      REDIS_URL: 'redis://localhost:6379',
+    });
+    expect(config.app.port).toBe(8080);
+    expect(config.databases.MAIN.ssl).toBe(true);
+    expect(config.databases.REPORTS.port).toBe(6432);
+    expect(config.cache).toMatchObject({ enabled: true, redisUrl: 'redis://localhost:6379' });
+  });
+
+  it.each(['ACCESS_TOKEN', 'JWT_ACCESS_SECRET', 'JWT_REFRESH_SECRET', 'DB_MAIN_PASSWORD'])(
+    'fails without the secret %s and does not print any value',
+    (name) => {
+      const env = { ...base, [name]: '' };
+      expect(() => buildConfiguration(env)).toThrow(`${name} is required`);
+    },
+  );
+
+  it('requires REDIS_URL only when the cache is enabled', () => {
+    expect(() => buildConfiguration({ ...base, CACHE_ENABLED: 'true' })).toThrow(
+      'REDIS_URL is required',
+    );
+  });
+
+  it('does not allow pretty logs in production', () => {
+    expect(() =>
+      buildConfiguration({ ...base, NODE_ENV: 'production', LOG_FORMAT: 'pretty' }),
+    ).toThrow('not allowed');
+  });
+
+  it.each([
+    ['PORT', 'abc', /integer/],
+    ['MONITOR_ENABLED', 'yes', /true or false/],
+    ['LOG_FORMAT', 'xml', /json or pretty/],
+  ])('rejects %s=%p', (name, value, message) => {
+    expect(() => buildConfiguration({ ...base, [name]: value })).toThrow(message);
+  });
+});

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

@@ -0,0 +1,143 @@
+// Plantilla del harness → src/config/configuration.ts (AGENTS.md §14, harness/reference/configuracion.md).
+// Single place in the project that reads process.env. The rest of the code receives AppConfig
+// through ConfigService<AppConfig, true>. Variables are validated at startup (env validation in
+// src/config/); this file only groups them and converts their types.
+import { type LogFormat, parseLogFormat } from '../common/logging/logger-options';
+import { parseCorsMaxAge, parseCorsOrigins } from './cors';
+
+export type Env = Record<string, string | undefined>;
+
+export interface DatabaseConfig {
+  host: string;
+  port: number;
+  name: string;
+  user: string;
+  password: string;
+  ssl: boolean;
+  poolMax: number;
+  statementTimeoutMs: number;
+}
+
+export interface AppConfig {
+  app: { nodeEnv: string; port: number };
+  logging: { level: string; format: LogFormat };
+  databases: Record<string, DatabaseConfig>;
+  cache: {
+    enabled: boolean;
+    redisUrl: string | undefined;
+    defaultTtlSeconds: number;
+    keyPrefix: string;
+    opTimeoutMs: number;
+  };
+  auth: {
+    accessToken: string;
+    jwt: {
+      accessSecret: string;
+      accessExpiresIn: string;
+      refreshSecret: string;
+      refreshExpiresIn: string;
+    };
+  };
+  cors: { origins: string[]; maxAgeSeconds: number };
+  monitor: { enabled: boolean; sessionExpiresIn: string };
+}
+
+/** Required variable. The error names the variable, never its value. Secrets have no default. */
+export function required(env: Env, name: string): string {
+  const value = env[name];
+  if (value === undefined || value.trim() === '') {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}
+
+/** Optional text variable with a non-sensitive default. */
+export function text(env: Env, name: string, fallback: string): string {
+  const value = env[name];
+  return value === undefined || value.trim() === '' ? fallback : value.trim();
+}
+
+export function int(env: Env, name: string, fallback: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim() === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer`);
+  }
+  return value;
+}
+
+export function bool(env: Env, name: string, fallback: boolean): boolean {
+  const raw = env[name]?.trim().toLowerCase();
+  if (raw === undefined || raw === '') return fallback;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  throw new Error(`${name} must be true or false`);
+}
+
+/** DATABASES=MAIN,REPORTS → one block per name, read from DB_<NAME>_*. */
+export function parseDatabases(env: Env): Record<string, DatabaseConfig> {
+  const names = required(env, 'DATABASES')
+    .split(',')
+    .map((name) => name.trim().toUpperCase())
+    .filter(Boolean);
+  return Object.fromEntries(
+    names.map((name): [string, DatabaseConfig] => {
+      const key = (part: string): string => `DB_${name}_${part}`;
+      return [
+        name,
+        {
+          host: required(env, key('HOST')),
+          port: int(env, key('PORT'), 5432),
+          name: required(env, key('NAME')),
+          user: required(env, key('USER')),
+          password: required(env, key('PASSWORD')),
+          ssl: bool(env, key('SSL'), false),
+          poolMax: int(env, key('POOL_MAX'), 10),
+          statementTimeoutMs: int(env, key('STATEMENT_TIMEOUT_MS'), 30000),
+        },
+      ];
+    }),
+  );
+}
+
+/** Pure: builds the configuration from an env object (tests pass their own). */
+export function buildConfiguration(env: Env): AppConfig {
+  const cacheEnabled = bool(env, 'CACHE_ENABLED', false);
+  const nodeEnv = text(env, 'NODE_ENV', 'development');
+  return {
+    app: { nodeEnv, port: int(env, 'PORT', 3000) },
+    logging: {
+      level: text(env, 'LOG_LEVEL', 'info'),
+      format: parseLogFormat(env.LOG_FORMAT, nodeEnv),
+    },
+    databases: parseDatabases(env),
+    cache: {
+      enabled: cacheEnabled,
+      redisUrl: cacheEnabled ? required(env, 'REDIS_URL') : env.REDIS_URL,
+      defaultTtlSeconds: int(env, 'CACHE_DEFAULT_TTL_SECONDS', 300),
+      keyPrefix: text(env, 'CACHE_KEY_PREFIX', 'arness'),
+      opTimeoutMs: int(env, 'CACHE_OP_TIMEOUT_MS', 200),
+    },
+    auth: {
+      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'),
+      },
+    },
+    cors: {
+      origins: parseCorsOrigins(env.CORS_ORIGINS),
+      maxAgeSeconds: parseCorsMaxAge(env.CORS_MAX_AGE_SECONDS),
+    },
+    monitor: {
+      enabled: bool(env, 'MONITOR_ENABLED', false),
+      sessionExpiresIn: text(env, 'MONITOR_SESSION_EXPIRES_IN', '15m'),
+    },
+  };
+}
+
+/** Factory for ConfigModule.forRoot({ load: [configuration] }). */
+export default (): AppConfig => buildConfiguration(process.env);

package/harness/skills/nest-base/templates/cors/cors.spec.ts

@@ -0,0 +1,53 @@
+// Plantilla del harness → src/config/cors.spec.ts
+import { buildCorsOptions, parseCorsMaxAge, parseCorsOrigins } from './cors';
+
+describe('parseCorsOrigins', () => {
+  it('returns normalized, unique origins', () => {
+    expect(
+      parseCorsOrigins(' https://app.example.com ,http://localhost:4200,https://app.example.com/'),
+    ).toEqual(['https://app.example.com', 'http://localhost:4200']);
+  });
+
+  it.each([
+    ['', /required/],
+    [undefined, /required/],
+    ['*', /wildcards/],
+    ['https://*.example.com', /wildcards/],
+    ['not-a-url', /invalid origin/],
+    ['https://app.example.com/path', /origins only/],
+    ['http://app.example.com', /https/],
+  ])('rejects %p', (raw, message) => {
+    expect(() => parseCorsOrigins(raw)).toThrow(message);
+  });
+});
+
+describe('parseCorsMaxAge', () => {
+  it('defaults to 600 and validates the range', () => {
+    expect(parseCorsMaxAge(undefined)).toBe(600);
+    expect(parseCorsMaxAge('120')).toBe(120);
+    expect(() => parseCorsMaxAge('-1')).toThrow();
+    expect(() => parseCorsMaxAge('abc')).toThrow();
+  });
+});
+
+describe('buildCorsOptions', () => {
+  const options = buildCorsOptions(['https://app.example.com'], 600);
+  const decide = (origin: string | undefined): boolean | undefined => {
+    let result: boolean | undefined;
+    (
+      options.origin as (
+        o: string | undefined,
+        cb: (e: Error | null, allow?: boolean) => void,
+      ) => void
+    )(origin, (_err, allow) => (result = allow));
+    return result;
+  };
+
+  it('allows only origins in the allowlist and never uses credentials', () => {
+    expect(decide('https://app.example.com')).toBe(true);
+    expect(decide('https://evil.example.com')).toBe(false);
+    expect(decide(undefined)).toBe(false);
+    expect(options.credentials).toBe(false);
+    expect(options.methods).toEqual(['GET', 'POST', 'OPTIONS']);
+  });
+});

package/harness/skills/nest-base/templates/cors/cors.ts

@@ -0,0 +1,75 @@
+// Plantilla del harness → src/config/cors.ts (AGENTS.md §9, harness/reference/contrato-http.md "CORS").
+import type { CorsOptions } from '@nestjs/common/interfaces/external/cors-options.interface';
+
+export const CORS_METHODS = ['GET', 'POST', 'OPTIONS'];
+export const CORS_ALLOWED_HEADERS = ['Authorization', 'Content-Type', 'X-Request-Id'];
+export const CORS_EXPOSED_HEADERS = ['X-Cache', 'X-Request-Id'];
+export const CORS_DEFAULT_MAX_AGE_SECONDS = 600;
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+/**
+ * Parses CORS_ORIGINS (comma separated) into exact origins.
+ * Throws on an empty list, wildcards, values that are not an origin, or http:// outside localhost.
+ */
+export function parseCorsOrigins(raw: string | undefined): string[] {
+  const items = (raw ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (items.length === 0) {
+    throw new Error('CORS_ORIGINS is required: list the allowed origins separated by commas');
+  }
+  return [
+    ...new Set(
+      items.map((item) => {
+        if (item.includes('*')) {
+          throw new Error(`CORS_ORIGINS does not accept wildcards: ${item}`);
+        }
+        let url: URL;
+        try {
+          url = new URL(item);
+        } catch {
+          throw new Error(`CORS_ORIGINS has an invalid origin: ${item}`);
+        }
+        if (url.origin === 'null' || url.origin !== item.replace(/\/$/, '')) {
+          throw new Error(`CORS_ORIGINS must contain origins only (scheme://host[:port]): ${item}`);
+        }
+        if (
+          url.protocol !== 'https:' &&
+          !(url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname))
+        ) {
+          throw new Error(`CORS_ORIGINS requires https:// except for localhost: ${item}`);
+        }
+        return url.origin;
+      }),
+    ),
+  ];
+}
+
+/** Parses CORS_MAX_AGE_SECONDS; defaults to 600 seconds. */
+export function parseCorsMaxAge(raw: string | undefined): number {
+  if (raw === undefined || raw.trim() === '') return CORS_DEFAULT_MAX_AGE_SECONDS;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 86400) {
+    throw new Error('CORS_MAX_AGE_SECONDS must be an integer between 0 and 86400');
+  }
+  return value;
+}
+
+/** Options for app.enableCors(): only origins in the allowlist get Access-Control-Allow-Origin. */
+export function buildCorsOptions(origins: readonly string[], maxAgeSeconds: number): CorsOptions {
+  const allowed = new Set(origins);
+  return {
+    origin: (
+      origin: string | undefined,
+      callback: (err: Error | null, allow?: boolean) => void,
+    ): void => callback(null, origin !== undefined && allowed.has(origin)),
+    methods: CORS_METHODS,
+    allowedHeaders: CORS_ALLOWED_HEADERS,
+    exposedHeaders: CORS_EXPOSED_HEADERS,
+    credentials: false,
+    maxAge: maxAgeSeconds,
+    optionsSuccessStatus: 204,
+  };
+}