@saulwade/swl-ses 1.0.0

package/habilidades/nextjs-testing/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: nextjs-testing
+description: >
+  Testing Next.js con Vitest, React Testing Library, Playwright y MSW.
+  Cubre Server Components, Server Actions, page objects E2E y mocking de API.
+  Cargar cuando se escriban tests de componentes, integración o E2E en Next.js.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para tests React puros fuera del contexto de Next.js (Vite, CRA, Remix) — los mocks del router de Next.js y los Server Components son específicos del framework."
+  - "No cargar para implementar la lógica del componente que se está testando — si aún no está implementado, cargar `nextjs-experto` primero; los tests se escriben sobre código existente."
+  - "No cargar para configurar Playwright en un proyecto no-Next.js — Playwright funciona con cualquier web app, pero este skill cubre la configuración específica de Next.js con `next/server` y Server Actions."
+  - "No cargar para cobertura de código o análisis de calidad de tests existentes — para métricas de calidad cargar `checklist-calidad`."
+evolvable: true  # default para skill estandar
+---
+# Next.js Testing — Vitest, RTL, Playwright y MSW
+
+El App Router introduce complejidad de testing: Server Components son async,
+los Server Actions requieren contexto de servidor, y el router de Next.js necesita
+mocks específicos. Este skill cubre la configuración y los patrones para cada tipo
+de test en proyectos Next.js modernos.
+
+## Cuándo cargar este skill
+
+Invoca `Skill("nextjs-testing")` cuando:
+
+- Se configuren Vitest o Jest para un proyecto Next.js
+- Se escriban tests de componentes con React Testing Library
+- Se implementen tests E2E con Playwright
+- Se mockeen APIs externas con MSW en tests
+- Se prueben Server Actions o route handlers
+
+## Cuándo NO cargar
+
+- El proyecto usa React sin Next.js (Vite, CRA, Remix) — los mocks de `next/navigation` y los patrones de Server Components son específicos de Next.js.
+- El componente que se quiere testear no está implementado aún — primero implementar con `nextjs-experto`, luego escribir tests.
+- La pregunta es sobre configurar Playwright en un proyecto no-Next.js — Playwright funciona con cualquier web app pero este skill cubre integración con `next/server` y Server Actions.
+- La pregunta es sobre cobertura de código o análisis de calidad de tests existentes — para métricas de calidad cargar `checklist-calidad`.
+
+## Conceptos clave
+
+### Qué testear en Next.js
+
+Server Components: testear la lógica de transformación de datos y el HTML
+renderizado. Client Components: testear interacciones, estado y callbacks.
+Server Actions: testear validación, mutaciones y revalidación. E2E: testear
+flujos completos de usuario en el browser real.
+
+### Vitest vs Jest
+
+Vitest es la opción moderna: compatible con Vite, más rápido, soporte nativo
+de ESM. Jest requiere más configuración para Next.js con App Router. Ambos son
+compatibles con React Testing Library.
+
+### MSW (Mock Service Worker)
+
+MSW intercepta requests HTTP a nivel de Service Worker (browser) o a nivel de
+Node.js (tests). Permite definir handlers una vez y usarlos en tests de unidad,
+integracion y en el browser de desarrollo.
+
+### Estrategia de cobertura por capas
+
+Testear Next.js requiere una estrategia sistemática por capas. Cada capa cubre
+un tipo de riesgo distinto — no son intercambiables:
+
+| Capa | Qué testea | Herramienta | Ejemplo |
+|------|-----------|-------------|---------|
+| **Componente** | UI aislada, interacciones, estados visuales | Vitest + RTL | `render(<Boton />)` + click + assert texto |
+| **Página (RSC)** | Data fetching + transformación + render | Vitest (async) | `await Pagina({params})` + assert contenido |
+| **Hook** | Lógica reutilizable, efectos, estado | `renderHook` | `renderHook(() => useFiltros())` + act |
+| **Integración** | Server Actions, validación + mutación + revalidación | Vitest + mocks BD | `await crearProducto(formData)` + assert BD |
+| **E2E** | Flujos completos de usuario en browser real | Playwright | Navegar → llenar form → submit → verificar |
+
+**Regla de proporción**: ~60% componente/página, ~25% integración, ~15% E2E.
+Los tests E2E son lentos y frágiles — cubrir solo los flujos críticos de negocio.
+Los tests de componente son baratos — cubrir todas las variantes de estado.
+
+## Reglas obligatorias
+
+### Configurar next/jest o Vitest correctamente antes de escribir cualquier test
+
+```javascript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+    plugins: [react()],
+    test: {
+        environment: 'jsdom',
+        setupFiles: ['./tests/setup.ts'],
+        globals: true,
+    },
+    resolve: {
+        alias: { '@': path.resolve(__dirname, './') },
+    },
+});
+```
+
+### Mockear next/navigation y next/router SIEMPRE en tests de componentes
+
+```typescript
+// tests/setup.ts
+vi.mock('next/navigation', () => ({
+    useRouter: () => ({ push: vi.fn(), replace: vi.fn(), prefetch: vi.fn() }),
+    useSearchParams: () => new URLSearchParams(),
+    usePathname: () => '/',
+}));
+```
+
+Sin este mock, cualquier componente que importe de `next/navigation` fallará.
+
+### MSW handlers en archivo centralizado, no inline en cada test
+
+```typescript
+// tests/msw/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+    http.get('/api/productos', () => {
+        return HttpResponse.json({ data: [{ id: 1, nombre: 'Laptop' }] });
+    }),
+    http.post('/api/productos', async ({ request }) => {
+        const body = await request.json();
+        return HttpResponse.json({ data: { id: 99, ...body } }, { status: 201 });
+    }),
+];
+```
+
+## Patrones recomendados
+
+### Testing de Client Component con interacciones
+
+```typescript
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import FormularioProducto from '@/components/FormularioProducto';
+
+describe('FormularioProducto', () => {
+    it('envia el formulario con datos validos', async () => {
+        const user = userEvent.setup();
+        const mockSubmit = vi.fn();
+
+        render(<FormularioProducto onSubmit={mockSubmit} />);
+
+        await user.type(screen.getByLabelText('Nombre'), 'Laptop Pro');
+        await user.type(screen.getByLabelText('Precio'), '25000');
+        await user.click(screen.getByRole('button', { name: /guardar/i }));
+
+        await waitFor(() => {
+            expect(mockSubmit).toHaveBeenCalledWith({
+                nombre: 'Laptop Pro',
+                precio: 25000,
+            });
+        });
+    });
+
+    it('muestra error cuando el nombre esta vacio', async () => {
+        const user = userEvent.setup();
+        render(<FormularioProducto onSubmit={vi.fn()} />);
+
+        await user.click(screen.getByRole('button', { name: /guardar/i }));
+
+        expect(screen.getByText('El nombre es requerido')).toBeInTheDocument();
+    });
+});
+```
+
+### Testing de Server Component (async)
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import ListaProductos from '@/app/productos/page';
+
+// Mockear la función de fetch de datos
+vi.mock('@/lib/api', () => ({
+    obtenerProductos: vi.fn().mockResolvedValue([
+        { id: 1, nombre: 'Laptop', precio: 25000 },
+        { id: 2, nombre: 'Mouse', precio: 500 },
+    ]),
+}));
+
+it('renderiza lista de productos', async () => {
+    const ui = await ListaProductos({});
+    render(ui);
+
+    expect(screen.getByText('Laptop')).toBeInTheDocument();
+    expect(screen.getByText('Mouse')).toBeInTheDocument();
+});
+```
+
+### Testing de Server Action
+
+```typescript
+import { crearProducto } from '@/app/actions/productos';
+import { db } from '@/lib/db';
+
+vi.mock('@/lib/db');
+vi.mock('@/lib/auth', () => ({
+    auth: vi.fn().mockResolvedValue({ user: { id: '1', rol: 'admin' } }),
+}));
+
+describe('crearProducto', () => {
+    it('crea producto con datos validos', async () => {
+        const formData = new FormData();
+        formData.append('nombre', 'Laptop Pro');
+        formData.append('precio', '25000');
+
+        const resultado = await crearProducto(formData);
+
+        expect(resultado).not.toHaveProperty('error');
+        expect(db.producto.create).toHaveBeenCalled();
+    });
+
+    it('retorna errores de validacion con datos invalidos', async () => {
+        const formData = new FormData();
+        formData.append('nombre', ''); // invalido
+
+        const resultado = await crearProducto(formData);
+
+        expect(resultado?.error?.nombre).toBeDefined();
+    });
+});
+```
+
+### Playwright Page Object para E2E
+
+```typescript
+// tests/e2e/pages/ProductosPage.ts
+import { Page, Locator } from '@playwright/test';
+
+export class ProductosPage {
+    readonly page: Page;
+    readonly botonNuevo: Locator;
+    readonly tablaProductos: Locator;
+
+    constructor(page: Page) {
+        this.page = page;
+        this.botonNuevo = page.getByRole('button', { name: 'Nuevo producto' });
+        this.tablaProductos = page.getByRole('table', { name: 'Productos' });
+    }
+
+    async navegar() {
+        await this.page.goto('/dashboard/productos');
+    }
+
+    async crearProducto(nombre: string, precio: number) {
+        await this.botonNuevo.click();
+        await this.page.getByLabel('Nombre').fill(nombre);
+        await this.page.getByLabel('Precio').fill(precio.toString());
+        await this.page.getByRole('button', { name: 'Guardar' }).click();
+    }
+}
+
+// tests/e2e/productos.spec.ts
+import { test, expect } from '@playwright/test';
+import { ProductosPage } from './pages/ProductosPage';
+
+test('admin puede crear un producto', async ({ page }) => {
+    const productosPage = new ProductosPage(page);
+    await productosPage.navegar();
+    await productosPage.crearProducto('Laptop Pro', 25000);
+
+    await expect(page.getByText('Laptop Pro')).toBeVisible();
+});
+```
+
+### MSW en tests de integración con servidor Node
+
+```typescript
+// tests/setup.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './msw/handlers';
+
+const server = setupServer(...handlers);
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+## Anti-patrones conocidos
+
+### getByTestId como primera opción
+
+```typescript
+// MAL — acoplado a detalles de implementación
+screen.getByTestId('boton-submit');
+
+// BIEN — accesible y más semántico
+screen.getByRole('button', { name: /guardar/i });
+screen.getByLabelText('Email');
+screen.getByText('Confirmar pedido');
+```
+
+Prioridad: getByRole > getByLabelText > getByPlaceholderText > getByText > getByTestId.
+
+### Snapshot tests para componentes que cambian frecuentemente
+
+Los snapshots se desactualizan y se actualizan sin revisar el cambio real.
+Preferir assertions específicas sobre el contenido crítico.
+
+## Gotchas / Errores comunes no obvios
+
+**`vi.mock('next/navigation')` no afecta si se importa antes del mock**: si el componente bajo test importa `useRouter` en el nivel de módulo antes de que `vi.mock` se evalúe, el mock no se aplica. Causa: Vitest hoistea los `vi.mock()` al inicio del archivo, pero en algunos setups con transformaciones el orden puede fallar. Fix: asegurarse que `vi.mock('next/navigation', ...)` está en el archivo de setup global (`tests/setup.ts`) y se carga antes de cualquier import del componente.
+
+**Server Component async no se puede renderizar directamente con `render()`**: `render(<MiServerComponent />)` falla con `Objects are not valid as a React child (found: [object Promise])` porque RTL no sabe manejar un componente async. Causa: React Testing Library en su versión estable no soporta async Server Components directamente. Fix: `await` el componente primero (`const ui = await MiServerComponent({params})`), luego `render(ui)`.
+
+**MSW con `onUnhandledRequest: 'error'` falla en tests que hacen fetches a rutas internas de Next.js**: el test lanza error porque `_next/static/...` o rutas internas del framework generan requests que MSW no tiene handlers para. Causa: Next.js en modo test puede generar requests internos. Fix: usar `onUnhandledRequest: 'warn'` o agregar handlers para las rutas internas de Next.js, o filtrar con una función: `onUnhandledRequest: (req) => { if (!req.url.includes('_next')) throw new Error(...) }`.
+
+**`userEvent.setup()` debe llamarse fuera del `it()` o re-instanciarse por test**: compartir una instancia de `userEvent` entre tests causa que el estado del puntero/teclado se acumule entre tests, causando comportamiento impredecible. Causa: `userEvent.setup()` crea un estado de dispositivo virtual que persiste. Fix: llamar `const user = userEvent.setup()` dentro de cada `it()` o en `beforeEach`, no al nivel de `describe`.
+
+## Checklist de verificación
+
+- [ ] Vitest/Jest configurado con next/jest transform o plugin react
+- [ ] next/navigation mockeado en setup global de tests
+- [ ] MSW handlers en archivo centralizado
+- [ ] Tests de Client Component usan userEvent (no fireEvent para interacciones)
+- [ ] Server Actions testeadas con FormData real
+- [ ] E2E con Page Objects para reutilizar selectores
+- [ ] `onUnhandledRequest: 'error'` en MSW para detectar fetches sin handler
+
+## Referencias
+
+- [Testing Next.js](https://nextjs.org/docs/app/building-your-application/testing)
+- [MSW](https://mswjs.io/docs)
+- [Playwright](https://playwright.dev/docs/intro)
+
+---
+*Skill creado con swl:crear-skill el 2026-03-31. Versión 1.0.0.*

package/habilidades/node-experto/.evolved.json

@@ -0,0 +1,9 @@
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "5.3.3",
+    "evolvedAt": "2026-04-09",
+    "evolvedBy": "aprender",
+    "evolvedNote": "anti-patrón JSDoc glob, JSONL append-only, webhook fire-and-forget, dual-use scripts"
+  }
+}

package/habilidades/node-experto/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: node-experto
+description: Node.js y TypeScript backend moderno. Cubre patterns de Express/Fastify/NestJS, error handling middleware, streams y buffers, worker threads y clustering, Prisma/Drizzle ORM, validación con Zod, graceful shutdown y anti-patrones críticos como callback hell y event loop blocking.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Glob]
+exclusiones:
+  - "No cargar para aplicaciones Next.js con App Router — Next.js tiene patrones de Server Components, SSR y caché que difieren del backend Node puro; cargar `nextjs-experto`."
+  - "No cargar para proyectos NestJS con DI compleja — NestJS tiene su propio sistema de módulos y decoradores que merece su skill; cargar `nestjs-experto`."
+  - "No cargar para scripting Python o backend no-JS — este skill cubre el stack Node.js específicamente."
+  - "No cargar para errores de compilación TypeScript o tsconfig — para esos cargar `build-errors-typescript`; este skill asume que el código compila."
+evolvable: true  # default para skill estandar
+---
+# Node.js Experto — Backend TypeScript Moderno
+
+## Cuándo NO cargar
+
+- El proyecto usa Next.js App Router — los patrones de Server Components, SSR y caché son específicos de Next.js; cargar `nextjs-experto`.
+- El proyecto usa NestJS con inyección de dependencias, decoradores y módulos — NestJS tiene su propio sistema opinionado; cargar `nestjs-experto`.
+- El backend es Python, Go, Java u otro lenguaje no-JS — este skill cubre Node.js específicamente.
+- La pregunta es sobre errores de compilación TypeScript o tsconfig — cargar `build-errors-typescript`; este skill asume que el código compila.
+
+## Filosofía
+
+Node.js es monohilo y asíncrono. Todo el rendimiento depende de
+**no bloquear el event loop**. Operaciones I/O siempre asíncronas,
+CPU-intensivo en worker threads, errores siempre manejados.
+
+---
+
+## Frameworks: Cuándo Usar Cuál
+
+| Framework | Usar cuando |
+|-----------|------------|
+| **Fastify** | API de alto rendimiento, microservicio |
+| **Express** | Proyecto legacy, equipo familiarizado |
+| **NestJS** | Aplicación empresarial grande, DI, estructura opinionada |
+
+---
+
+## Error Handling — Reglas Obligatorias
+
+1. **Jerarquía de errores tipados**: `AppError` > `ValidationError`, `NotFoundError`, etc.
+2. **Error middleware SIEMPRE al final** de la cadena.
+3. **`asyncHandler` wrapper** para capturar errores async sin try/catch repetido.
+4. **Errores operacionales** (400, 404): respuesta descriptiva al cliente.
+5. **Errores no esperados** (500): log completo, respuesta genérica. NUNCA stack traces al cliente.
+
+```typescript
+export class AppError extends Error {
+  constructor(
+    public readonly message: string,
+    public readonly statusCode: number,
+    public readonly code: string,
+    public readonly isOperational = true,
+  ) {
+    super(message);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} con id ${id} no encontrado`, 404, 'NOT_FOUND');
+  }
+}
+```
+
+---
+
+## Streams — Reglas
+
+- SIEMPRE usar `pipeline()` de `stream/promises` (maneja errores y backpressure).
+- Para archivos grandes: NUNCA cargar todo en memoria. Usar streams.
+- Para respuestas HTTP grandes: `Readable.from()` con generador async.
+- Concatenar buffers con `Buffer.concat()`, NUNCA con `+=` de strings.
+
+---
+
+## Worker Threads y Clustering
+
+- CPU-intensivo SIEMPRE en worker threads, NUNCA en el hilo principal.
+- Pool de workers con Piscina para reutilización.
+- Clustering: un worker por CPU core con auto-restart en muerte.
+
+---
+
+## ORM — Prisma y Drizzle
+
+- **Prisma**: singleton con `globalThis` para evitar múltiples conexiones.
+- **Transacciones**: `prisma.$transaction()` para operaciones atómicas.
+- **Drizzle**: esquema tipado con `pgTable`, queries type-safe.
+
+---
+
+## Validación con Zod
+
+- Schemas reutilizables con `z.infer<typeof Schema>` para tipos.
+- Middleware `validar(schema)` que parsea y lanza `ValidationError` automáticamente.
+
+---
+
+## Graceful Shutdown — OBLIGATORIO
+
+1. Dejar de aceptar nuevas conexiones: `server.close()`
+2. Cerrar conexiones a BD: `prisma.$disconnect()`
+3. Timeout de seguridad (10s) para forzar cierre.
+4. Capturar `SIGTERM`, `SIGINT`, `unhandledRejection`, `uncaughtException`.
+
+---
+
+## Anti-patrones Críticos
+
+| Anti-patrón | Corrección |
+|-------------|------------|
+| Callback hell | async/await |
+| `crypto.pbkdf2Sync` en handler | Worker thread |
+| `promise.then()` sin `.catch()` | asyncHandler o try/catch |
+| `require()` dinámico en hot path | Importar al inicio |
+| Operaciones síncronas de fs en requests | `fs.promises.*` |
+
+```typescript
+// MAL: bloquea el event loop
+const hash = crypto.pbkdf2Sync(pass, salt, 100000, 64, 'sha512');
+
+// BIEN: en worker thread
+const hash = await pool.run({ pass, salt });
+```
+
+---
+
+## Checklist Node.js
+
+- [ ] NUNCA bloquear el event loop con operaciones síncronas
+- [ ] Error middleware al final de la cadena
+- [ ] Graceful shutdown implementado
+- [ ] CPU-intensivo en worker threads
+- [ ] Streams para archivos/respuestas grandes
+- [ ] Validación de input con Zod
+- [ ] Singleton de Prisma client
+- [ ] `unhandledRejection` y `uncaughtException` capturados
+
+Para implementaciones completas de Fastify, Express, streams, workers, ORMs, Zod y graceful shutdown, ver [recursos/patrones-completos.md](recursos/patrones-completos.md).
+
+---
+
+## Gotchas de JSDoc y comentarios multilínea
+
+### NUNCA usar glob `*` dentro de bloques `/** */`
+
+**Problema**: El patrón `habilidades/*/SKILL.md` dentro de un bloque JSDoc `/** ... */`
+es interpretado por el parser JS como cierre del comentario en `*/`.
+Produce `SyntaxError: Unexpected identifier` al cargar el módulo.
+
+```javascript
+// MAL — el */ en "habilidades/*/SKILL.md" cierra el bloque JSDoc prematuramente
+/**
+ * Scannea habilidades/*/SKILL.md y extrae metadata.
+ *                           ^ este */ cierra el comentario aquí
+ */
+
+// BIEN — usar <nombre> o texto descriptivo sin glob en JSDoc
+/**
+ * Scannea habilidades/<nombre>/SKILL.md y extrae metadata.
+ */
+```
+
+Este mismo anti-patrón aplica a cualquier ruta con `*/` dentro de `/** */`:
+`src/*/index.js`, `dist/**/*.js`, etc.
+
+---
+
+## Patrones de I/O para observabilidad
+
+### JSONL + `appendFileSync` para streams de eventos de alta frecuencia
+
+Para archivos de telemetría, auditoría o logs append-only, `fs.appendFileSync` es
+superior a escritura atómica JSON:
+
+```javascript
+// MAL para eventos frecuentes — lee y reescribe todo el archivo cada vez
+const eventos = JSON.parse(fs.readFileSync(archivo, 'utf8'));
+eventos.push(nuevoEvento);
+fs.writeFileSync(archivo, JSON.stringify(eventos, null, 2));
+
+// BIEN — append-only O(1), sin leer el archivo existente
+fs.appendFileSync(archivo, JSON.stringify(nuevoEvento) + '\n', 'utf8');
+
+// Para leer de vuelta: parsear línea a línea
+const eventos = fs.readFileSync(archivo, 'utf8')
+  .split('\n').filter(Boolean).map(l => JSON.parse(l));
+```
+
+Usar `atomicWriteJSON` para archivos de estado (mutation frecuente).
+Usar `appendFileSync` para archivos de eventos (solo escritura secuencial).
+
+### Webhook fire-and-forget con `http`/`https` nativo (zero-deps)
+
+Para exportaciones opcionales (OTLP, audit webhooks, Slack, Datadog):
+
+```javascript
+const http  = require('http');
+const https = require('https');
+
+function enviarWebhookAsync(url, payload) {
+  if (!url) return; // No lanzar si no está configurado
+
+  try {
+    const body   = JSON.stringify(payload);
+    const parsed = new URL(url);
+    const modulo = parsed.protocol === 'https:' ? https : http;
+
+    const req = modulo.request({
+      hostname: parsed.hostname,
+      port:     parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path:     parsed.pathname + (parsed.search || ''),
+      method:   'POST',
+      headers:  {
+        'Content-Type':   'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    });
+    req.on('error', () => {}); // Silencioso — nunca interrumpir el flujo principal
+    req.write(body);
+    req.end();
+  } catch (_) {}
+}
+```
+
+Verificar siempre `process.env.WEBHOOK_URL` antes de llamar — sin config requerida.
+
+---
+
+## Scripts dual-use: librería + CLI
+
+### `require.main === module` para scripts en `scripts/lib/`
+
+Permite que el mismo archivo funcione como librería importable Y como CLI
+sin duplicar lógica:
+
+```javascript
+// scripts/lib/mi-script.js
+function miFuncion(cwd) { /* ... */ }
+module.exports = { miFuncion };
+
+// Solo se ejecuta cuando se invoca directamente con `node scripts/lib/mi-script.js`
+// NO se ejecuta cuando otro módulo lo importa con require('./mi-script')
+if (require.main === module) {
+  const args     = process.argv.slice(2);
+  const query    = args.filter(a => !a.startsWith('--'))[0] || '';
+  const resultado = miFuncion(process.cwd(), query);
+  process.stdout.write(JSON.stringify(resultado, null, 2) + '\n');
+}
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**Prisma Client creado en cada request agota el pool de conexiones**: instanciar `new PrismaClient()` dentro de un handler crea una nueva pool por cada request. En producción esto provoca `Too many connections` en la BD. Fix: exportar un singleton con el patrón `globalThis.__prisma || new PrismaClient()` y reutilizarlo en todos los handlers.
+
+**`unhandledRejection` no captura errores en callbacks síncronos dentro de Promises**: el handler `process.on('unhandledRejection', ...)` captura promesas rechazadas sin `.catch()`, pero no captura errores lanzados en código síncrono dentro de un `Promise` executor si ese error no se propaga al reject. Causa: `new Promise((resolve, reject) => { throw new Error('X') })` sí se captura, pero `setTimeout(() => { throw new Error('X') }, 0)` dentro de una promesa no. Fix: usar `uncaughtException` también, y never usar setTimeout con código que puede lanzar dentro de promesas.
+
+**`stream.pipeline()` no limpia streams en versiones < Node 16 con errores en mitad del pipe**: en Node 14, un error en un transform stream intermedio deja el readable stream sin destruir, causando memory leak. Fix: usar Node 18+ o agregar listeners de `error` en cada stream del pipeline manualmente en proyectos que deben soportar Node 14/16.
+
+**Zod `.parse()` vs `.safeParse()` en middleware**: usar `schema.parse(body)` en un middleware Express lanza una excepción no capturada si no hay un try/catch, y el error llega al cliente con stack trace completo. Fix: usar siempre `schema.safeParse(body)` en middleware y verificar `result.success` antes de continuar; pasar `result.error` al error handler con `next(result.error)`.
+
+**`response.json()` sobre body vacío lanza `SyntaxError: Unexpected end of JSON input`**: cuando el servidor responde con 204 No Content, 205 Reset Content, o con `Content-Length: 0`, el body está vacío — `fetch(...).then(r => r.json())` falla en el cliente porque JSON.parse sobre string vacío lanza excepción. Causa: el contrato de fetch no verifica el status antes de parsear; el cliente asume que siempre hay JSON. Fix: verificar status y Content-Length antes de parsear: `if (r.status === 204 || r.status === 205 || r.headers.get('content-length') === '0') return null;`. Si el servidor FastAPI retorna 200 con body vacío por bug, considerar helper `await r.text()` antes y `JSON.parse` con try/catch — o mejor, devolver 204 explícito en endpoints que no retornan cuerpo.