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

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;');
+  });
+});

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

@@ -0,0 +1,190 @@
+// Plantilla del harness → src/common/monitor/monitor-page.ts
+// HTML renderizado en el servidor con React, sin JSX, sin hidratación y sin JavaScript en el cliente.
+import { createElement as h, type CSSProperties, type ReactNode } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { MONITOR_HOME_URL, MONITOR_LOGIN_URL } from './monitor.constants';
+import type { MonitorCard } from './monitor.service';
+
+const color = {
+  bg: '#f5f6f8',
+  card: '#ffffff',
+  text: '#1f2933',
+  muted: '#616e7c',
+  line: '#e4e7eb',
+  accent: '#2457c5',
+  warn: '#9a5b00',
+};
+
+const styles: Record<string, CSSProperties> = {
+  body: {
+    margin: 0,
+    background: color.bg,
+    color: color.text,
+    font: '15px/1.5 system-ui, -apple-system, Segoe UI, sans-serif',
+  },
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 16,
+    padding: '16px 24px',
+    background: color.card,
+    borderBottom: `1px solid ${color.line}`,
+  },
+  title: { margin: 0, fontSize: 18, fontWeight: 600, flex: 1 },
+  muted: { color: color.muted, fontSize: 13 },
+  main: {
+    padding: 24,
+    display: 'grid',
+    gap: 16,
+    gridTemplateColumns: 'repeat(auto-fill, minmax(240px, 1fr))',
+  },
+  card: {
+    background: color.card,
+    border: `1px solid ${color.line}`,
+    borderRadius: 10,
+    padding: 16,
+  },
+  cardTitle: {
+    margin: '0 0 8px',
+    fontSize: 13,
+    fontWeight: 600,
+    color: color.muted,
+    textTransform: 'uppercase',
+    letterSpacing: 0.4,
+  },
+  value: { fontSize: 32, fontWeight: 600, margin: 0 },
+  unavailable: { fontSize: 15, color: color.warn, margin: 0 },
+  list: { listStyle: 'none', padding: 0, margin: '12px 0 0', borderTop: `1px solid ${color.line}` },
+  row: {
+    display: 'flex',
+    justifyContent: 'space-between',
+    padding: '6px 0',
+    borderBottom: `1px solid ${color.line}`,
+    fontSize: 14,
+  },
+  button: {
+    font: 'inherit',
+    padding: '8px 14px',
+    borderRadius: 8,
+    border: `1px solid ${color.line}`,
+    background: color.card,
+    color: color.text,
+    cursor: 'pointer',
+  },
+  primary: {
+    font: 'inherit',
+    padding: '10px 14px',
+    borderRadius: 8,
+    border: 0,
+    background: color.accent,
+    color: '#fff',
+    cursor: 'pointer',
+    width: '100%',
+  },
+  loginBox: {
+    maxWidth: 360,
+    margin: '12vh auto',
+    background: color.card,
+    border: `1px solid ${color.line}`,
+    borderRadius: 12,
+    padding: 24,
+  },
+  input: {
+    font: 'inherit',
+    width: '100%',
+    boxSizing: 'border-box',
+    padding: '10px 12px',
+    margin: '6px 0 16px',
+    borderRadius: 8,
+    border: `1px solid ${color.line}`,
+  },
+  error: { color: '#b42318', margin: '0 0 12px' },
+};
+
+function document(title: string, body: ReactNode): string {
+  const html = h(
+    'html',
+    { lang: 'es' },
+    h(
+      'head',
+      null,
+      h('meta', { charSet: 'utf-8' }),
+      h('meta', { name: 'viewport', content: 'width=device-width, initial-scale=1' }),
+      h('meta', { name: 'robots', content: 'noindex, nofollow' }),
+      h('title', null, title),
+    ),
+    h('body', { style: styles.body }, body),
+  );
+  return `<!doctype html>${renderToStaticMarkup(html)}`;
+}
+
+function card({ id, title, status, value }: MonitorCard): ReactNode {
+  return h(
+    'section',
+    { key: id, style: styles.card, 'data-widget': id },
+    h('h2', { style: styles.cardTitle }, title),
+    status === 'ok' && value
+      ? [
+          h('p', { key: 'v', style: styles.value }, String(value.value)),
+          value.detail?.length
+            ? h(
+                'ul',
+                { key: 'd', style: styles.list },
+                value.detail.map((item) =>
+                  h(
+                    'li',
+                    { key: item.label, style: styles.row },
+                    h('span', null, item.label),
+                    h('strong', null, String(item.value)),
+                  ),
+                ),
+              )
+            : null,
+        ]
+      : h('p', { style: styles.unavailable }, 'No disponible'),
+  );
+}
+
+export function renderMonitorPage(cards: readonly MonitorCard[], generatedAt: Date): string {
+  return document('Monitor', [
+    h(
+      'header',
+      { key: 'h', style: styles.header },
+      h('h1', { style: styles.title }, 'Monitor'),
+      h('span', { style: styles.muted }, `Actualizado ${generatedAt.toISOString()}`),
+      h(
+        'form',
+        { method: 'post', action: `${MONITOR_HOME_URL}/logout` },
+        h('button', { type: 'submit', style: styles.button }, 'Cerrar sesión'),
+      ),
+    ),
+    h('main', { key: 'm', style: styles.main }, cards.map(card)),
+  ]);
+}
+
+export function renderLoginPage(error?: string): string {
+  return document(
+    'Monitor · Ingresar',
+    h(
+      'main',
+      { style: styles.loginBox },
+      h('h1', { style: { ...styles.title, marginBottom: 16 } }, 'Monitor'),
+      error ? h('p', { style: styles.error, role: 'alert' }, error) : null,
+      h(
+        'form',
+        { method: 'post', action: MONITOR_LOGIN_URL },
+        h('label', { htmlFor: 'password' }, 'Contraseña'),
+        h('input', {
+          id: 'password',
+          name: 'password',
+          type: 'password',
+          required: true,
+          autoComplete: 'current-password',
+          autoFocus: true,
+          style: styles.input,
+        }),
+        h('button', { type: 'submit', style: styles.primary }, 'Ingresar'),
+      ),
+    ),
+  );
+}

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

@@ -0,0 +1,46 @@
+// Plantilla del harness → src/common/monitor/monitor-session.guard.spec.ts
+import { ExecutionContext, NotFoundException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { MonitorLoginRequiredException, MonitorSessionGuard } from './monitor-session.guard';
+import { MonitorSessionService } from './monitor-session.service';
+
+const context = (cookie?: string): ExecutionContext =>
+  ({
+    getHandler: () => undefined,
+    getClass: () => undefined,
+    switchToHttp: () => ({ getRequest: () => ({ headers: { cookie } }) }),
+  }) as unknown as ExecutionContext;
+
+describe('MonitorSessionGuard', () => {
+  const session = { isEnabled: jest.fn(), hasValidSession: jest.fn() };
+  const reflector = { getAllAndOverride: jest.fn() };
+  const guard = new MonitorSessionGuard(
+    reflector as unknown as Reflector,
+    session as unknown as MonitorSessionService,
+  );
+
+  beforeEach(() => {
+    session.isEnabled.mockReturnValue(true);
+    session.hasValidSession.mockResolvedValue(false);
+    reflector.getAllAndOverride.mockReturnValue(false);
+  });
+
+  it('answers 404 when the monitor is disabled', async () => {
+    session.isEnabled.mockReturnValue(false);
+    await expect(guard.canActivate(context())).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('lets login routes through without a session', async () => {
+    reflector.getAllAndOverride.mockReturnValue(true);
+    await expect(guard.canActivate(context())).resolves.toBe(true);
+  });
+
+  it('requires a valid session cookie', async () => {
+    await expect(guard.canActivate(context())).rejects.toBeInstanceOf(
+      MonitorLoginRequiredException,
+    );
+    session.hasValidSession.mockResolvedValue(true);
+    await expect(guard.canActivate(context('arness_monitor=t'))).resolves.toBe(true);
+    expect(session.hasValidSession).toHaveBeenCalledWith('arness_monitor=t');
+  });
+});

package/harness/skills/nest-base/templates/monitor/monitor-session.guard.ts

@@ -0,0 +1,36 @@
+// Plantilla del harness → src/common/monitor/monitor-session.guard.ts
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  NotFoundException,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Request } from 'express';
+import { IS_MONITOR_LOGIN_KEY } from './monitor.decorators';
+import { MonitorSessionService } from './monitor-session.service';
+
+/** Caught by MonitorLoginRedirectFilter, which redirects to the login form. */
+export class MonitorLoginRequiredException extends UnauthorizedException {}
+
+/** Cookie session for /monitor. 404 when MONITOR_ENABLED is not true. */
+@Injectable()
+export class MonitorSessionGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly session: MonitorSessionService,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    if (!this.session.isEnabled()) throw new NotFoundException();
+    const isLogin = this.reflector.getAllAndOverride<boolean>(IS_MONITOR_LOGIN_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isLogin) return true;
+    const request = context.switchToHttp().getRequest<Request>();
+    if (await this.session.hasValidSession(request.headers.cookie)) return true;
+    throw new MonitorLoginRequiredException();
+  }
+}