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

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

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

@@ -0,0 +1,57 @@
+// Plantilla del harness → src/common/monitor/monitor-session.service.spec.ts
+import { ConfigService } from '@nestjs/config';
+import { JwtService } from '@nestjs/jwt';
+import { MonitorSessionService, readCookie } from './monitor-session.service';
+
+const env: Record<string, string> = {
+  MONITOR_ENABLED: 'true',
+  ACCESS_TOKEN: 'example123',
+  JWT_ACCESS_SECRET: 'test-access-secret-with-enough-length',
+  MONITOR_SESSION_EXPIRES_IN: '10m',
+};
+const config = (overrides: Record<string, string> = {}): ConfigService =>
+  new ConfigService({ ...env, ...overrides });
+
+describe('MonitorSessionService', () => {
+  const jwt = new JwtService({});
+  const service = new MonitorSessionService(config(), jwt);
+
+  it('is disabled unless MONITOR_ENABLED is true', () => {
+    expect(service.isEnabled()).toBe(true);
+    expect(new MonitorSessionService(config({ MONITOR_ENABLED: 'false' }), jwt).isEnabled()).toBe(
+      false,
+    );
+  });
+
+  it('compares the password with ACCESS_TOKEN', () => {
+    expect(service.verifyPassword('example123')).toBe(true);
+    expect(service.verifyPassword('example12')).toBe(false);
+    expect(new MonitorSessionService(config({ ACCESS_TOKEN: '' }), jwt).verifyPassword('')).toBe(
+      false,
+    );
+  });
+
+  it('issues an HttpOnly, Secure, SameSite=Strict cookie scoped to /monitor', async () => {
+    const cookie = await service.createSessionCookie();
+    expect(cookie).toMatch(
+      /^arness_monitor=[\w-]+\.[\w-]+\.[\w-]+; Max-Age=600; Path=\/monitor; HttpOnly; Secure; SameSite=Strict$/,
+    );
+    expect(await service.hasValidSession(cookie.split(';')[0])).toBe(true);
+  });
+
+  it('rejects missing, tampered and non-monitor tokens', async () => {
+    const accessToken = await jwt.signAsync({ type: 'access' }, { secret: env.JWT_ACCESS_SECRET });
+    expect(await service.hasValidSession(undefined)).toBe(false);
+    expect(await service.hasValidSession('arness_monitor=abc.def.ghi')).toBe(false);
+    expect(await service.hasValidSession(`arness_monitor=${accessToken}`)).toBe(false);
+  });
+
+  it('clears the cookie on logout', () => {
+    expect(service.clearSessionCookie()).toContain('arness_monitor=; Max-Age=0; Path=/monitor');
+  });
+
+  it('reads a cookie from the header', () => {
+    expect(readCookie('a=1; arness_monitor=xyz; b=2', 'arness_monitor')).toBe('xyz');
+    expect(readCookie(undefined, 'arness_monitor')).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,77 @@
+// Plantilla del harness → src/common/monitor/monitor-session.service.ts
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { JwtService, JwtSignOptions } from '@nestjs/jwt';
+import { createHash, timingSafeEqual } from 'node:crypto';
+import {
+  MONITOR_COOKIE,
+  MONITOR_DEFAULT_SESSION_EXPIRES_IN,
+  MONITOR_HOME_URL,
+  MONITOR_TOKEN_TYPE,
+} from './monitor.constants';
+
+const sha256 = (value: string): Buffer => createHash('sha256').update(value).digest();
+
+/** Reads one cookie from a raw Cookie header without extra dependencies. */
+export function readCookie(header: string | undefined, name: string): string | undefined {
+  for (const part of (header ?? '').split(';')) {
+    const index = part.indexOf('=');
+    if (index > 0 && part.slice(0, index).trim() === name) return part.slice(index + 1).trim();
+  }
+  return undefined;
+}
+
+@Injectable()
+export class MonitorSessionService {
+  constructor(
+    private readonly config: ConfigService,
+    private readonly jwt: JwtService,
+  ) {}
+
+  isEnabled(): boolean {
+    const value = this.config.get<unknown>('MONITOR_ENABLED');
+    return value === true || value === 'true';
+  }
+
+  /** Same comparison as /auth/login: sha256 of both values and timingSafeEqual. */
+  verifyPassword(candidate: string): boolean {
+    const expected = this.config.get<string>('ACCESS_TOKEN') ?? '';
+    return expected.length > 0 && timingSafeEqual(sha256(candidate), sha256(expected));
+  }
+
+  async createSessionCookie(): Promise<string> {
+    const expiresIn = (this.config.get<string>('MONITOR_SESSION_EXPIRES_IN') ||
+      MONITOR_DEFAULT_SESSION_EXPIRES_IN) as JwtSignOptions['expiresIn'];
+    const token = await this.jwt.signAsync(
+      { type: MONITOR_TOKEN_TYPE },
+      { secret: this.secret(), expiresIn },
+    );
+    const { exp, iat } = this.jwt.decode<{ exp: number; iat: number }>(token);
+    return this.cookie(token, exp - iat);
+  }
+
+  clearSessionCookie(): string {
+    return this.cookie('', 0);
+  }
+
+  async hasValidSession(cookieHeader: string | undefined): Promise<boolean> {
+    const token = readCookie(cookieHeader, MONITOR_COOKIE);
+    if (!token) return false;
+    try {
+      const payload = await this.jwt.verifyAsync<{ type?: string }>(token, {
+        secret: this.secret(),
+      });
+      return payload.type === MONITOR_TOKEN_TYPE;
+    } catch {
+      return false;
+    }
+  }
+
+  private secret(): string {
+    return this.config.getOrThrow<string>('JWT_ACCESS_SECRET');
+  }
+
+  private cookie(value: string, maxAgeSeconds: number): string {
+    return `${MONITOR_COOKIE}=${value}; Max-Age=${maxAgeSeconds}; Path=${MONITOR_HOME_URL}; HttpOnly; Secure; SameSite=Strict`;
+  }
+}

package/harness/skills/nest-base/templates/monitor/monitor-widget.interface.ts

@@ -0,0 +1,18 @@
+// Plantilla del harness → src/common/monitor/monitor-widget.interface.ts
+export interface MonitorValue {
+  /** Main figure shown on the card. Never secrets, SQL, driver errors or business data. */
+  value: string | number;
+  /** Optional breakdown (label → value). */
+  detail?: ReadonlyArray<{ label: string; value: string | number }>;
+}
+
+export interface MonitorWidget {
+  readonly id: string;
+  readonly title: string;
+  /** Ascending position on the page. */
+  readonly order: number;
+  collect(): Promise<MonitorValue>;
+}
+
+/** Multi-provider token: every widget registered in MonitorModule. */
+export const MONITOR_WIDGETS = Symbol('MONITOR_WIDGETS');

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

@@ -0,0 +1,25 @@
+// Plantilla del harness → src/common/monitor/monitor.constants.ts (AGENTS.md §10).
+export const MONITOR_PATH = 'monitor';
+export const MONITOR_LOGIN_URL = `/${MONITOR_PATH}/login`;
+export const MONITOR_HOME_URL = `/${MONITOR_PATH}`;
+export const MONITOR_COOKIE = 'arness_monitor';
+export const MONITOR_TOKEN_TYPE = 'monitor';
+export const MONITOR_DEFAULT_SESSION_EXPIRES_IN = '15m';
+export const MONITOR_WIDGET_TIMEOUT_MS = 2000;
+
+/** Route segments that never count as business endpoints. */
+export const MONITOR_EXCLUDED_SEGMENTS: ReadonlySet<string> = new Set([
+  MONITOR_PATH,
+  'health',
+  'auth',
+]);
+
+/** Sent on every monitor response: no scripts, no framing, no caching. */
+export const MONITOR_SECURITY_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  'Content-Security-Policy':
+    "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+  'Cache-Control': 'no-store',
+  'X-Frame-Options': 'DENY',
+  'X-Content-Type-Options': 'nosniff',
+  'Referrer-Policy': 'no-referrer',
+});

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

@@ -0,0 +1,63 @@
+// Plantilla del harness → src/common/monitor/monitor.controller.ts
+import { Body, Controller, Get, Post, Res, UseFilters, UseGuards } from '@nestjs/common';
+import type { Response } from 'express';
+import {
+  MONITOR_HOME_URL,
+  MONITOR_LOGIN_URL,
+  MONITOR_PATH,
+  MONITOR_SECURITY_HEADERS,
+} from './monitor.constants';
+import { MonitorLogin, MonitorRoute } from './monitor.decorators';
+import { MonitorLoginRedirectFilter } from './monitor-login-redirect.filter';
+import { MonitorLoginDto } from './monitor-login.dto';
+import { renderLoginPage, renderMonitorPage } from './monitor-page';
+import { MonitorSessionGuard } from './monitor-session.guard';
+import { MonitorSessionService } from './monitor-session.service';
+import { MonitorService } from './monitor.service';
+
+function sendHtml(res: Response, status: number, html: string): void {
+  res.status(status).set(MONITOR_SECURITY_HEADERS).type('html').send(html);
+}
+
+/** Fuera de /api/v1. No es @Public(): lo protege MonitorSessionGuard con cookie, no el Bearer. */
+@MonitorRoute()
+@UseGuards(MonitorSessionGuard)
+@UseFilters(MonitorLoginRedirectFilter)
+@Controller(MONITOR_PATH)
+export class MonitorController {
+  constructor(
+    private readonly monitor: MonitorService,
+    private readonly session: MonitorSessionService,
+  ) {}
+
+  @Get()
+  async page(@Res() res: Response): Promise<void> {
+    sendHtml(res, 200, renderMonitorPage(await this.monitor.collect(), new Date()));
+  }
+
+  @MonitorLogin()
+  @Get('login')
+  loginForm(@Res() res: Response): void {
+    sendHtml(res, 200, renderLoginPage());
+  }
+
+  @MonitorLogin()
+  @Post('login')
+  async login(@Body() body: MonitorLoginDto, @Res() res: Response): Promise<void> {
+    if (!this.session.verifyPassword(body.password)) {
+      sendHtml(res, 401, renderLoginPage('Contraseña incorrecta'));
+      return;
+    }
+    res
+      .set(MONITOR_SECURITY_HEADERS)
+      .setHeader('Set-Cookie', await this.session.createSessionCookie());
+    res.redirect(303, MONITOR_HOME_URL);
+  }
+
+  @MonitorLogin()
+  @Post('logout')
+  logout(@Res() res: Response): void {
+    res.set(MONITOR_SECURITY_HEADERS).setHeader('Set-Cookie', this.session.clearSessionCookie());
+    res.redirect(303, MONITOR_LOGIN_URL);
+  }
+}

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

@@ -0,0 +1,11 @@
+// Plantilla del harness → src/common/monitor/monitor.decorators.ts
+import { CustomDecorator, SetMetadata } from '@nestjs/common';
+
+export const IS_MONITOR_ROUTE_KEY = 'arness:monitor-route';
+export const IS_MONITOR_LOGIN_KEY = 'arness:monitor-login';
+
+/** Marks the monitor controller: JwtAuthGuard skips it and MonitorSessionGuard protects it instead. */
+export const MonitorRoute = (): CustomDecorator<string> => SetMetadata(IS_MONITOR_ROUTE_KEY, true);
+
+/** Monitor handlers reachable without a session (login form, login and logout). */
+export const MonitorLogin = (): CustomDecorator<string> => SetMetadata(IS_MONITOR_LOGIN_KEY, true);

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

@@ -0,0 +1,30 @@
+// Plantilla del harness → src/common/monitor/monitor.module.ts
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { JwtModule } from '@nestjs/jwt';
+import { MonitorController } from './monitor.controller';
+import { MonitorSessionGuard } from './monitor-session.guard';
+import { MonitorSessionService } from './monitor-session.service';
+import { MonitorService } from './monitor.service';
+import { MONITOR_WIDGETS, MonitorWidget } from './monitor-widget.interface';
+import { EndpointsTotalWidget } from './widgets/endpoints-total.widget';
+
+/** Widgets del tablero: agrega la clase a WIDGETS (playbook new-monitor-widget). */
+const WIDGETS = [EndpointsTotalWidget];
+
+@Module({
+  imports: [DiscoveryModule, JwtModule.register({})],
+  controllers: [MonitorController],
+  providers: [
+    MonitorService,
+    MonitorSessionService,
+    MonitorSessionGuard,
+    ...WIDGETS,
+    {
+      provide: MONITOR_WIDGETS,
+      useFactory: (...widgets: MonitorWidget[]): MonitorWidget[] => widgets,
+      inject: WIDGETS,
+    },
+  ],
+})
+export class MonitorModule {}

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

@@ -0,0 +1,55 @@
+// Plantilla del harness → src/common/monitor/monitor.service.spec.ts
+import { Test } from '@nestjs/testing';
+import { MONITOR_WIDGETS, MonitorWidget } from './monitor-widget.interface';
+import { MonitorService } from './monitor.service';
+
+const widget = (id: string, order: number, collect: MonitorWidget['collect']): MonitorWidget => ({
+  id,
+  title: id,
+  order,
+  collect,
+});
+
+describe('MonitorService', () => {
+  const build = async (widgets: MonitorWidget[]): Promise<MonitorService> => {
+    const moduleRef = await Test.createTestingModule({
+      providers: [MonitorService, { provide: MONITOR_WIDGETS, useValue: widgets }],
+    }).compile();
+    return moduleRef.get(MonitorService);
+  };
+
+  it('returns the widgets ordered by order', async () => {
+    const service = await build([
+      widget('b', 20, () => Promise.resolve({ value: 2 })),
+      widget('a', 10, () => Promise.resolve({ value: 1 })),
+    ]);
+    expect((await service.collect()).map((c) => c.id)).toEqual(['a', 'b']);
+  });
+
+  it('marks a failing widget as unavailable without exposing the error', async () => {
+    const service = await build([
+      widget('ok', 1, () => Promise.resolve({ value: 7 })),
+      widget('broken', 2, () =>
+        Promise.reject(new Error('password authentication failed for user "x"')),
+      ),
+      widget('throws', 3, () => {
+        throw new Error('sync');
+      }),
+    ]);
+    const cards = await service.collect();
+    expect(cards).toEqual([
+      { id: 'ok', title: 'ok', status: 'ok', value: { value: 7 } },
+      { id: 'broken', title: 'broken', status: 'unavailable' },
+      { id: 'throws', title: 'throws', status: 'unavailable' },
+    ]);
+  });
+
+  it('marks a slow widget as unavailable', async () => {
+    jest.useFakeTimers();
+    const service = await build([widget('slow', 1, () => new Promise(() => undefined))]);
+    const pending = service.collect();
+    await jest.advanceTimersByTimeAsync(2000);
+    expect((await pending)[0].status).toBe('unavailable');
+    jest.useRealTimers();
+  });
+});

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

@@ -0,0 +1,49 @@
+// Plantilla del harness → src/common/monitor/monitor.service.ts
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { MONITOR_WIDGET_TIMEOUT_MS } from './monitor.constants';
+import { MONITOR_WIDGETS, MonitorValue, MonitorWidget } from './monitor-widget.interface';
+
+export interface MonitorCard {
+  id: string;
+  title: string;
+  status: 'ok' | 'unavailable';
+  value?: MonitorValue;
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error('timeout')), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+@Injectable()
+export class MonitorService {
+  private readonly logger = new Logger(MonitorService.name);
+
+  constructor(@Inject(MONITOR_WIDGETS) private readonly widgets: MonitorWidget[]) {}
+
+  /** A failing or slow widget becomes "unavailable"; the page always renders. */
+  async collect(): Promise<MonitorCard[]> {
+    const ordered = [...this.widgets].sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+    return Promise.all(
+      ordered.map(async (widget): Promise<MonitorCard> => {
+        const { id, title } = widget;
+        try {
+          const value = await withTimeout(
+            Promise.resolve().then(() => widget.collect()),
+            MONITOR_WIDGET_TIMEOUT_MS,
+          );
+          return { id, title, status: 'ok', value };
+        } catch (error) {
+          // Only the error type: messages may carry SQL, hosts or data.
+          this.logger.warn(
+            `Monitor widget "${id}" unavailable (${error instanceof Error ? error.name : 'unknown'})`,
+          );
+          return { id, title, status: 'unavailable' };
+        }
+      }),
+    );
+  }
+}