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

package/harness/skills/nest-base/templates/docs/EVOLUTIVO.md

@@ -0,0 +1,22 @@
+<!-- Plantilla del harness → docs/EVOLUTIVO.md (AGENTS.md §12). Quita este comentario al copiarla. -->
+# Evolutivo
+
+Trazabilidad de lo que se ha entregado en el proyecto, en orden cronológico. Cada entrega agrega una entrada al final; las anteriores no se reescriben ni se borran.
+
+**Solo avance.** Aquí no van pendientes, bloqueos, stoppers ni riesgos: esos van en `docs/PENDIENTES.md`.
+
+Formato de cada entrada (lenguaje entendible para negocio):
+
+```markdown
+## AAAA-MM-DD · <cliente>/<módulo>
+
+- **Entregado:** <qué se puede hacer ahora, en una o dos frases>.
+- **Detalle técnico:** <endpoint, conexión, widget o cambio de contrato>.
+- **Referencia:** <commit, PR o tag>.
+```
+
+## AAAA-MM-DD · Base del proyecto
+
+- **Entregado:** base del backend lista para agregar reportes: autenticación, salud del servicio y caché.
+- **Detalle técnico:** proyecto NestJS creado con la skill `nest-base` del harness.
+- **Referencia:** <commit inicial>.

package/harness/skills/nest-base/templates/docs/PENDIENTES.md

@@ -0,0 +1,20 @@
+<!-- Plantilla del harness → docs/PENDIENTES.md (AGENTS.md §12). Quita este comentario al copiarla. -->
+# Pendientes
+
+Pendientes, bloqueos, stoppers, recomendaciones, deuda técnica y advertencias de `./harness/init.sh` que no se corrigieron. Lo entregado va en `docs/EVOLUTIVO.md`.
+
+Cada ítem lleva fecha, contexto y tipo. Al resolverse, se mueve a **Resueltos** con la fecha de cierre (y, si fue una entrega, se registra en `docs/EVOLUTIVO.md`).
+
+Tipos: `pendiente` · `bloqueo` · `recomendación` · `deuda técnica` · `advertencia init.sh`.
+
+## Abiertos
+
+| Fecha | Contexto (cliente/módulo) | Tipo | Descripción | Responsable |
+|---|---|---|---|---|
+| | | | | |
+
+## Resueltos
+
+| Fecha | Cierre | Contexto | Tipo | Descripción |
+|---|---|---|---|---|
+| | | | | |

package/harness/skills/nest-base/templates/docs/TECNICO.md

@@ -0,0 +1,43 @@
+<!-- Plantilla del harness → docs/TECNICO.md (AGENTS.md §12). Quita este comentario al copiarla. -->
+# Documentación técnica
+
+Backend de analítica de **<cliente o producto>**: reportes de solo lectura sobre PostgreSQL. Las reglas de trabajo están en `AGENTS.md`; el contrato con frontend, en `FRONT.md`.
+
+## Arquitectura
+
+- NestJS por capas hexagonales por endpoint: controller → service (Cache-Aside) → repository (`pg`) → `*.sql.ts`.
+- Organización `src/modules/<cliente>/<modulo>/<endpoint>/`; lo transversal vive en `src/common/`.
+- Autenticación JWT (access + refresh) en todos los endpoints salvo `login`, `refresh` y `health`.
+- Caché Redis opcional: la API responde igual si Redis está caído o deshabilitado.
+
+## Módulos
+
+| Cliente | Módulo | Propósito | Conexión | README |
+|---|---|---|---|---|
+| | | | | |
+
+## Conexiones de base de datos
+
+Solo nombres lógicos y origen; **nunca** hosts, usuarios ni contraseñas.
+
+| Nombre (`DATABASES`) | Propósito | Esquemas o vistas principales |
+|---|---|---|
+| MAIN | | |
+
+## Configuración
+
+Variables por tema en `src/config/configuration.ts` y referencia completa en `harness/reference/configuracion.md`. Variables propias de este proyecto:
+
+| Variable | Para qué | Obligatoria |
+|---|---|---|
+| | | |
+
+## Despliegue
+
+- Imagen Docker (`Dockerfile`) y pipeline `azure-pipelines.yml`.
+- Entornos: <desarrollo, QA, producción> y sus URLs base.
+- `GET /health` reporta cada BD y la caché; `GET /monitor` solo donde `MONITOR_ENABLED=true`.
+
+## Decisiones
+
+Las decisiones del proyecto están en `harness/decisiones/` (índice en su `README.md`).

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

@@ -0,0 +1,60 @@
+// Plantilla del harness → test/cors.e2e-spec.ts
+import { Controller, Get, INestApplication } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { buildCorsOptions } from '../src/config/cors';
+
+@Controller('probe')
+class ProbeController {
+  @Get()
+  get(): { data: string } {
+    return { data: 'ok' };
+  }
+}
+
+describe('CORS (e2e)', () => {
+  let app: INestApplication<App>;
+  const allowed = 'https://app.example.com';
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({ controllers: [ProbeController] }).compile();
+    app = moduleRef.createNestApplication();
+    app.enableCors(buildCorsOptions([allowed], 600));
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('answers an allowed preflight with the CORS headers', async () => {
+    const res = await request(app.getHttpServer())
+      .options('/probe')
+      .set('Origin', allowed)
+      .set('Access-Control-Request-Method', 'GET')
+      .set('Access-Control-Request-Headers', 'Authorization');
+    expect(res.status).toBe(204);
+    expect(res.headers['access-control-allow-origin']).toBe(allowed);
+    expect(res.headers['access-control-allow-methods']).toBe('GET,POST,OPTIONS');
+    expect(res.headers['access-control-allow-headers']).toBe(
+      'Authorization,Content-Type,X-Request-Id',
+    );
+    expect(res.headers['access-control-max-age']).toBe('600');
+    expect(res.headers['access-control-allow-credentials']).toBeUndefined();
+  });
+
+  it('exposes X-Cache and X-Request-Id to allowed origins', async () => {
+    const res = await request(app.getHttpServer()).get('/probe').set('Origin', allowed);
+    expect(res.headers['access-control-allow-origin']).toBe(allowed);
+    expect(res.headers['access-control-expose-headers']).toBe('X-Cache,X-Request-Id');
+  });
+
+  it('does not allow an origin outside the allowlist', async () => {
+    const res = await request(app.getHttpServer())
+      .options('/probe')
+      .set('Origin', 'https://evil.example.com')
+      .set('Access-Control-Request-Method', 'GET');
+    expect(res.headers['access-control-allow-origin']).toBeUndefined();
+  });
+});

package/harness/skills/nest-base/templates/e2e/monitor.e2e-spec.ts

@@ -0,0 +1,134 @@
+// Plantilla del harness → test/monitor.e2e-spec.ts
+import { Controller, Get, INestApplication, ValidationPipe } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { MonitorModule } from '../src/common/monitor/monitor.module';
+import { MONITOR_WIDGETS, MonitorWidget } from '../src/common/monitor/monitor-widget.interface';
+import { EndpointsTotalWidget } from '../src/common/monitor/widgets/endpoints-total.widget';
+
+@Controller('cartera')
+class CarteraController {
+  @Get('resumen')
+  summary(): void {}
+
+  @Get('detalle')
+  detail(): void {}
+}
+
+@Controller('health')
+class HealthController {
+  @Get()
+  check(): void {}
+}
+
+const brokenWidget: MonitorWidget = {
+  id: 'broken',
+  title: 'Widget roto',
+  order: 99,
+  collect: () => Promise.reject(new Error('connect ECONNREFUSED 10.0.0.5:5432')),
+};
+
+async function createApp(enabled: boolean): Promise<INestApplication<App>> {
+  const moduleRef = await Test.createTestingModule({
+    imports: [
+      ConfigModule.forRoot({
+        isGlobal: true,
+        ignoreEnvFile: true,
+        load: [
+          () => ({
+            MONITOR_ENABLED: String(enabled),
+            MONITOR_SESSION_EXPIRES_IN: '15m',
+            ACCESS_TOKEN: 'example123',
+            JWT_ACCESS_SECRET: 'e2e-access-secret-with-enough-length',
+          }),
+        ],
+      }),
+      MonitorModule,
+    ],
+    controllers: [CarteraController, HealthController],
+  })
+    .overrideProvider(MONITOR_WIDGETS)
+    .useFactory({
+      factory: (total: EndpointsTotalWidget) => [total, brokenWidget],
+      inject: [EndpointsTotalWidget],
+    })
+    .compile();
+  const app = moduleRef.createNestApplication<INestApplication<App>>();
+  app.useGlobalPipes(
+    new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }),
+  );
+  await app.init();
+  return app;
+}
+
+describe('Monitor (e2e)', () => {
+  let app: INestApplication<App>;
+
+  beforeAll(async () => {
+    app = await createApp(true);
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  const login = (password: string): request.Test =>
+    request(app.getHttpServer()).post('/monitor/login').type('form').send({ password });
+
+  it('redirects to the login form without a session', async () => {
+    const res = await request(app.getHttpServer()).get('/monitor');
+    expect(res.status).toBe(303);
+    expect(res.headers.location).toBe('/monitor/login');
+  });
+
+  it('serves the login form with the security headers and no scripts', async () => {
+    const res = await request(app.getHttpServer()).get('/monitor/login');
+    expect(res.status).toBe(200);
+    expect(res.headers['content-type']).toMatch(/text\/html/);
+    expect(res.headers['content-security-policy']).toContain("default-src 'none'");
+    expect(res.headers['cache-control']).toBe('no-store');
+    expect(res.headers['x-frame-options']).toBe('DENY');
+    expect(res.text).not.toMatch(/<script/i);
+  });
+
+  it('rejects a wrong password with 401 and no cookie', async () => {
+    const res = await login('wrong');
+    expect(res.status).toBe(401);
+    expect(res.headers['set-cookie']).toBeUndefined();
+    expect(res.text).toContain('Contraseña incorrecta');
+  });
+
+  it('logs in, shows the endpoint count and isolates a failing widget', async () => {
+    const res = await login('example123');
+    expect(res.status).toBe(303);
+    expect(res.headers.location).toBe('/monitor');
+    const cookie = String(res.headers['set-cookie']);
+    expect(cookie).toMatch(
+      /arness_monitor=.+; Max-Age=900; Path=\/monitor; HttpOnly; Secure; SameSite=Strict/,
+    );
+
+    const page = await request(app.getHttpServer())
+      .get('/monitor')
+      .set('Cookie', cookie.split(';')[0]);
+    expect(page.status).toBe(200);
+    expect(page.text).toMatch(/data-widget="endpoints-total".*?>2</);
+    expect(page.text).toContain('No disponible');
+    expect(page.text).not.toContain('ECONNREFUSED');
+    expect(page.text).not.toMatch(/<script/i);
+  });
+
+  it('logout clears the cookie', async () => {
+    const res = await request(app.getHttpServer()).post('/monitor/logout');
+    expect(res.status).toBe(303);
+    expect(String(res.headers['set-cookie'])).toContain('arness_monitor=; Max-Age=0');
+  });
+
+  it('answers 404 when MONITOR_ENABLED=false', async () => {
+    const disabled = await createApp(false);
+    await request(disabled.getHttpServer()).get('/monitor').expect(404);
+    await request(disabled.getHttpServer()).get('/monitor/login').expect(404);
+    await disabled.close();
+  });
+});

package/harness/skills/nest-base/templates/editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/harness/skills/nest-base/templates/eslint.boundaries.mjs

@@ -0,0 +1,65 @@
+// @ts-check
+// Fronteras de arquitectura del harness (AGENTS.md §4). Sin dependencias: solo
+// @typescript-eslint/no-restricted-imports con patrones. Se copia a la raíz del proyecto y la
+// importa eslint.config.mjs. Usa una regla distinta de no-restricted-imports (la de `pg`) para que
+// los overrides de una no apaguen la otra. También exporta configBoundaries (process.env solo en
+// src/config/, AGENTS.md §14).
+
+const RULE = '@typescript-eslint/no-restricted-imports';
+
+export const COMMON_IMPORTS_MODULES =
+  'src/common no importa de src/modules: lo compartido vive en common (AGENTS.md §4).';
+export const MODULE_IMPORTS_OTHER_MODULE =
+  'Un módulo no importa de otro módulo ni de otro cliente: lo compartido va a src/common (AGENTS.md §4).';
+export const MODULE_ABSOLUTE_IMPORT =
+  'Dentro de un módulo usa imports relativos; importar otro módulo está prohibido (AGENTS.md §4).';
+export const PROCESS_ENV_OUTSIDE_CONFIG =
+  'process.env solo se lee en src/config/configuration.ts; usa ConfigService (AGENTS.md §13 y §14).';
+
+/** Niveles de carpeta bajo src/modules/<cliente>/<modulo>/ que se verifican. */
+const MAX_DEPTH = 5;
+
+/**
+ * Un archivo a `depth` carpetas bajo la raíz de su módulo sale del módulo con depth + 1 `../`.
+ * Desde ahí solo puede llegar a src/common o src/config (dos niveles más arriba: cliente y modules).
+ */
+const leavesModule = (depth) => `^(\\.\\./){${depth + 1}}(?!\\.\\./\\.\\./(common|config)(/|$))`;
+
+/** @type {import('eslint').Linter.Config[]} */
+export const architectureBoundaries = [
+  {
+    files: ['src/common/**/*.ts'],
+    rules: {
+      [RULE]: ['error', { patterns: [{ regex: '(^|/)modules(/|$)', message: COMMON_IMPORTS_MODULES }] }],
+    },
+  },
+  ...Array.from({ length: MAX_DEPTH }, (_, depth) => ({
+    files: [`src/modules/*/*/${'*/'.repeat(depth)}*.ts`],
+    rules: {
+      [RULE]: [
+        'error',
+        {
+          patterns: [
+            { regex: leavesModule(depth), message: MODULE_IMPORTS_OTHER_MODULE },
+            { regex: '^src/modules/', message: MODULE_ABSOLUTE_IMPORT },
+          ],
+        },
+      ],
+    },
+  })),
+];
+
+/**
+ * Configuración centralizada: process.env solo en src/config/. Los tests (specs y test/) pueden
+ * preparar variables. Usa no-restricted-properties, que ningún otro override del harness apaga.
+ * @type {import('eslint').Linter.Config[]}
+ */
+export const configBoundaries = [
+  {
+    files: ['src/**/*.ts'],
+    ignores: ['src/config/**', 'src/**/*.spec.ts'],
+    rules: {
+      'no-restricted-properties': ['error', { object: 'process', property: 'env', message: PROCESS_ENV_OUTSIDE_CONFIG }],
+    },
+  },
+];

package/harness/skills/nest-base/templates/eslint.config.mjs

@@ -0,0 +1,82 @@
+// @ts-check
+// ESLint del harness (AGENTS.md §4, §5, §6, §13 y §14).
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import { architectureBoundaries, configBoundaries } from './eslint.boundaries.mjs';
+
+// Las palabras clave SQL se escriben en MAYÚSCULAS por convención. Detecta el SQL al inicio del
+// literal, también tras saltos de línea o paréntesis (subconsultas), incluidas escrituras.
+const SQL_TEXT = '^[\\s(]*(SELECT|WITH|INSERT|UPDATE|DELETE|MERGE)\\s';
+const SQL_WRITE =
+  '\\b(INSERT\\s+INTO|UPDATE\\s+\\S+\\s+SET|DELETE\\s+FROM|MERGE\\s+INTO|TRUNCATE|DROP\\s|ALTER\\s|CREATE\\s|GRANT\\s|REVOKE\\s)';
+
+const SQL_OUTSIDE_SQL_FILE = 'El texto SQL solo puede vivir en *.sql.ts (AGENTS.md §5).';
+const SQL_WRITE_FORBIDDEN = 'La BD es de solo lectura: prohibido escribir o ejecutar DDL (AGENTS.md §6).';
+
+export default tseslint.config(
+  { ignores: ['dist/**', 'coverage/**', 'node_modules/**', 'eslint.config.mjs', 'eslint.boundaries.mjs'] },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: { ...globals.node, ...globals.jest },
+      sourceType: 'commonjs',
+      parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/explicit-module-boundary-types': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'no-console': 'error',
+      eqeqeq: ['error', 'always'],
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [
+            {
+              name: 'pg',
+              message: 'pg solo se usa en src/common/database y en *.repository.ts (AGENTS.md §5).',
+            },
+          ],
+        },
+      ],
+      'no-restricted-syntax': [
+        'error',
+        { selector: `Literal[value=/${SQL_TEXT}/]`, message: SQL_OUTSIDE_SQL_FILE },
+        { selector: `TemplateElement[value.raw=/${SQL_TEXT}/]`, message: SQL_OUTSIDE_SQL_FILE },
+      ],
+    },
+  },
+  // Fronteras: common no importa de modules y los módulos no se importan entre sí.
+  ...architectureBoundaries,
+  // Configuración: process.env solo en src/config/ (configuration.ts).
+  ...configBoundaries,
+  {
+    files: ['src/common/database/**/*.ts', 'src/**/*.repository.ts', 'src/**/*.repository.spec.ts'],
+    rules: { 'no-restricted-imports': 'off' },
+  },
+  {
+    files: ['src/**/*.sql.ts'],
+    rules: {
+      'no-restricted-syntax': [
+        'error',
+        { selector: `Literal[value=/${SQL_WRITE}/]`, message: SQL_WRITE_FORBIDDEN },
+        { selector: `TemplateElement[value.raw=/${SQL_WRITE}/]`, message: SQL_WRITE_FORBIDDEN },
+      ],
+    },
+  },
+  {
+    files: ['src/**/*.sql.spec.ts'],
+    rules: { 'no-restricted-syntax': 'off' },
+  },
+  {
+    files: ['**/*.spec.ts', 'test/**/*.ts'],
+    rules: { '@typescript-eslint/unbound-method': 'off' },
+  },
+);

package/harness/skills/nest-base/templates/logging/logger-options.spec.ts

@@ -0,0 +1,57 @@
+// Plantilla del harness → src/common/logging/logger-options.spec.ts
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { buildLoggerParams, parseLogFormat, REDACT_PATHS, requestId } from './logger-options';
+
+type PinoHttpOptions = Exclude<NonNullable<ReturnType<typeof buildLoggerParams>['pinoHttp']>, unknown[]>;
+const options = (params: ReturnType<typeof buildLoggerParams>): PinoHttpOptions =>
+  params.pinoHttp as PinoHttpOptions;
+
+describe('parseLogFormat', () => {
+  it('defaults to json and accepts pretty outside production', () => {
+    expect(parseLogFormat(undefined, 'production')).toBe('json');
+    expect(parseLogFormat(' Pretty ', 'development')).toBe('pretty');
+  });
+
+  it('rejects unknown formats and pretty in production', () => {
+    expect(() => parseLogFormat('xml', 'development')).toThrow('json or pretty');
+    expect(() => parseLogFormat('pretty', 'production')).toThrow('not allowed');
+  });
+});
+
+describe('buildLoggerParams', () => {
+  it('json: no transport and the same redaction as pretty', () => {
+    const json = options(buildLoggerParams({ level: 'info', format: 'json' }, true));
+    const pretty = options(buildLoggerParams({ level: 'debug', format: 'pretty' }, true));
+    expect(json.transport).toBeUndefined();
+    expect(pretty.transport).toEqual(expect.objectContaining({ target: 'pino-pretty' }));
+    expect(json.redact).toEqual(pretty.redact);
+    expect(REDACT_PATHS).toEqual(
+      expect.arrayContaining(['req.headers.authorization', 'req.headers.cookie', '*.password']),
+    );
+  });
+
+  it('falls back to json when pino-pretty is not installed', () => {
+    expect(options(buildLoggerParams({ level: 'info', format: 'pretty' }, false)).transport).toBeUndefined();
+  });
+});
+
+describe('requestId', () => {
+  const call = (header?: string): { id: string; sent: string } => {
+    const res = { setHeader: jest.fn() };
+    const id = requestId(
+      { headers: header === undefined ? {} : { 'x-request-id': header } } as IncomingMessage,
+      res as unknown as ServerResponse,
+    );
+    return { id, sent: res.setHeader.mock.calls[0][1] as string };
+  };
+
+  it('reuses a safe X-Request-Id and returns it in the response', () => {
+    expect(call('abc-123')).toEqual({ id: 'abc-123', sent: 'abc-123' });
+  });
+
+  it.each([undefined, '', 'bad id <script>', 'x'.repeat(129)])('generates a UUID for %p', (header) => {
+    const { id, sent } = call(header);
+    expect(id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(sent).toBe(id);
+  });
+});

package/harness/skills/nest-base/templates/logging/logger-options.ts

@@ -0,0 +1,85 @@
+// Plantilla del harness → src/common/logging/logger-options.ts (AGENTS.md §10, harness/reference/contrato-http.md "Logging").
+// JSON in production; one readable line per event in local development (LOG_FORMAT=pretty).
+// Both formats carry the same fields and the same redaction.
+import { randomUUID } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Params } from 'nestjs-pino';
+
+export const LOG_FORMATS = ['json', 'pretty'] as const;
+export type LogFormat = (typeof LOG_FORMATS)[number];
+
+export interface LoggingConfig {
+  level: string;
+  format: LogFormat;
+}
+
+/** Never logged in any format: credentials, tokens, session cookies and secrets. */
+export const REDACT_PATHS = [
+  'req.headers.authorization',
+  'req.headers.cookie',
+  'res.headers["set-cookie"]',
+  '*.password',
+  '*.accessToken',
+  '*.refreshToken',
+  '*.ACCESS_TOKEN',
+  '*.JWT_ACCESS_SECRET',
+  '*.JWT_REFRESH_SECRET',
+];
+
+/** Incoming X-Request-Id is reused only if it is short and safe; otherwise a UUID is generated. */
+const REQUEST_ID = /^[A-Za-z0-9._-]{1,128}$/;
+
+export const PRETTY_OPTIONS = {
+  colorize: true,
+  singleLine: true,
+  translateTime: 'SYS:HH:MM:ss',
+  ignore: 'pid,hostname,req,res,requestId,responseTime',
+  messageFormat: '[{requestId}] {msg}',
+};
+
+/** Parses LOG_FORMAT (default json). pretty is rejected with NODE_ENV=production. */
+export function parseLogFormat(raw: string | undefined, nodeEnv: string): LogFormat {
+  const value = (raw ?? '').trim().toLowerCase() || 'json';
+  if (!(LOG_FORMATS as readonly string[]).includes(value)) {
+    throw new Error('LOG_FORMAT must be json or pretty');
+  }
+  if (value === 'pretty' && nodeEnv === 'production') {
+    throw new Error('LOG_FORMAT=pretty is not allowed with NODE_ENV=production');
+  }
+  return value as LogFormat;
+}
+
+/** pino-pretty is a devDependency: images built for production do not include it. */
+export function isPrettyInstalled(): boolean {
+  try {
+    require.resolve('pino-pretty');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function requestId(req: IncomingMessage, res: ServerResponse): string {
+  const header = req.headers['x-request-id'];
+  const incoming = typeof header === 'string' ? header.trim() : '';
+  const id = REQUEST_ID.test(incoming) ? incoming : randomUUID();
+  res.setHeader('X-Request-Id', id);
+  return id;
+}
+
+/** Options for LoggerModule.forRootAsync({ useFactory }). Falls back to JSON if pino-pretty is missing. */
+export function buildLoggerParams(config: LoggingConfig, prettyInstalled = isPrettyInstalled()): Params {
+  const pretty = config.format === 'pretty' && prettyInstalled;
+  return {
+    pinoHttp: {
+      level: config.level,
+      genReqId: requestId,
+      customProps: (req) => ({ requestId: String(req.id) }),
+      customSuccessMessage: (req, res, responseTime) =>
+        `${req.method} ${req.url} ${res.statusCode} ${Math.round(responseTime)}ms`,
+      customErrorMessage: (req, res) => `${req.method} ${req.url} ${res.statusCode} failed`,
+      redact: { paths: REDACT_PATHS, censor: '[REDACTED]' },
+      ...(pretty ? { transport: { target: 'pino-pretty', options: PRETTY_OPTIONS } } : {}),
+    },
+  };
+}

package/harness/skills/nest-base/templates/monitor/monitor-login-redirect.filter.ts

@@ -0,0 +1,16 @@
+// Plantilla del harness → src/common/monitor/monitor-login-redirect.filter.ts
+import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
+import type { Response } from 'express';
+import { MONITOR_LOGIN_URL, MONITOR_SECURITY_HEADERS } from './monitor.constants';
+import { MonitorLoginRequiredException } from './monitor-session.guard';
+
+@Catch(MonitorLoginRequiredException)
+export class MonitorLoginRedirectFilter implements ExceptionFilter {
+  catch(_exception: MonitorLoginRequiredException, host: ArgumentsHost): void {
+    host
+      .switchToHttp()
+      .getResponse<Response>()
+      .set(MONITOR_SECURITY_HEADERS)
+      .redirect(303, MONITOR_LOGIN_URL);
+  }
+}

package/harness/skills/nest-base/templates/monitor/monitor-login.dto.ts

@@ -0,0 +1,8 @@
+// Plantilla del harness → src/common/monitor/monitor-login.dto.ts
+import { IsString, MaxLength } from 'class-validator';
+
+export class MonitorLoginDto {
+  @IsString()
+  @MaxLength(512)
+  password!: string;
+}

package/harness/skills/nest-base/templates/monitor/monitor-page.spec.ts

@@ -0,0 +1,41 @@
+// Plantilla del harness → src/common/monitor/monitor-page.spec.ts
+import { renderLoginPage, renderMonitorPage } from './monitor-page';
+
+describe('monitor pages', () => {
+  const html = renderMonitorPage(
+    [
+      {
+        id: 'endpoints-total',
+        title: 'Endpoints de la API',
+        status: 'ok',
+        value: { value: 3, detail: [{ label: 'cartera', value: 3 }] },
+      },
+      { id: 'broken', title: 'Roto', status: 'unavailable' },
+    ],
+    new Date('2026-10-20T12:00:00Z'),
+  );
+
+  it('renders the widgets, "No disponible" and a logout form', () => {
+    expect(html.startsWith('<!doctype html>')).toBe(true);
+    expect(html).toContain('Endpoints de la API');
+    expect(html).toContain('cartera');
+    expect(html).toContain('No disponible');
+    expect(html).toContain('action="/monitor/logout"');
+  });
+
+  it('never ships scripts or inline event handlers', () => {
+    for (const page of [html, renderLoginPage('Contraseña incorrecta')]) {
+      expect(page).not.toMatch(/<script/i);
+      expect(page).not.toMatch(/\son[a-z]+=/i);
+    }
+  });
+
+  it('escapes widget values', () => {
+    const page = renderMonitorPage(
+      [{ id: 'x', title: '<b>', status: 'ok', value: { value: '<script>' } }],
+      new Date(),
+    );
+    expect(page).not.toContain('<script>');
+    expect(page).toContain('&lt;script&gt;');
+  });
+});