@saulwade/swl-ses 1.0.0

package/habilidades/node-experto/recursos/patrones-completos.md

@@ -0,0 +1,283 @@
+# Node.js Experto — Patrones Completos de Referencia
+
+Implementaciones completas de Express, Fastify, streams, worker threads, ORMs y más.
+
+---
+
+## Fastify — Setup Recomendado
+
+```typescript
+// src/app.ts
+import Fastify from 'fastify';
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+
+const app = Fastify({
+  logger: {
+    level: process.env.LOG_LEVEL ?? 'info',
+    transport: process.env.NODE_ENV === 'development'
+      ? { target: 'pino-pretty' }
+      : undefined,
+  },
+}).withTypeProvider<TypeBoxTypeProvider>();
+
+await app.register(import('@fastify/cors'), {
+  origin: process.env.CORS_ORIGIN?.split(',') ?? false,
+});
+await app.register(import('@fastify/helmet'));
+await app.register(import('./routes/usuarios'), { prefix: '/api/v1/usuarios' });
+
+export { app };
+```
+
+## Express — Con TypeScript Moderno
+
+```typescript
+import express, { Express } from 'express';
+import { usuariosRouter } from './routes/usuarios';
+import { errorMiddleware } from './middleware/error';
+
+export function createApp(): Express {
+  const app = express();
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: true }));
+  app.use('/api/v1/usuarios', usuariosRouter);
+  app.use(errorMiddleware);
+  return app;
+}
+```
+
+---
+
+## Streams y Buffers — Ejemplos Completos
+
+### Procesar archivo grande sin cargar en memoria
+
+```typescript
+import { createReadStream, createWriteStream } from 'fs';
+import { pipeline } from 'stream/promises';
+import { createGzip } from 'zlib';
+import { Transform } from 'stream';
+
+async function procesarArchivoGrande(entrada: string, salida: string): Promise<void> {
+  const transformador = new Transform({
+    objectMode: false,
+    transform(chunk: Buffer, _encoding, callback) {
+      const procesado = chunk.toString().toUpperCase();
+      callback(null, procesado);
+    },
+  });
+  await pipeline(createReadStream(entrada), transformador, createGzip(), createWriteStream(salida));
+}
+```
+
+### Streaming HTTP response
+
+```typescript
+import { Readable } from 'stream';
+
+app.get('/exportar', async (req, reply) => {
+  reply.header('Content-Type', 'text/csv');
+  reply.header('Content-Disposition', 'attachment; filename="export.csv"');
+  const stream = Readable.from(generarCSV());
+  return reply.send(stream);
+});
+
+async function* generarCSV(): AsyncGenerator<string> {
+  yield 'id,nombre,email\n';
+  const cursor = db.usuario.cursor();
+  for await (const usuario of cursor) {
+    yield `${usuario.id},${usuario.nombre},${usuario.email}\n`;
+  }
+}
+```
+
+---
+
+## Worker Threads y Clustering
+
+### Worker Threads
+
+```typescript
+// src/workers/procesador.worker.ts
+import { workerData, parentPort } from 'worker_threads';
+
+function procesarIntensivo(datos: number[]): number {
+  return datos.reduce((acc, n) => acc + Math.sqrt(n), 0);
+}
+
+const resultado = procesarIntensivo(workerData.datos);
+parentPort!.postMessage({ resultado });
+
+// src/services/procesamiento.service.ts
+import { Worker } from 'worker_threads';
+import path from 'path';
+
+export function procesarEnWorker(datos: number[]): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(
+      path.resolve(__dirname, '../workers/procesador.worker.js'),
+      { workerData: { datos } },
+    );
+    worker.once('message', ({ resultado }) => resolve(resultado));
+    worker.once('error', reject);
+    worker.once('exit', code => {
+      if (code !== 0) reject(new Error(`Worker salió con código ${code}`));
+    });
+  });
+}
+```
+
+### Pool de workers con Piscina
+
+```typescript
+import { Piscina } from 'piscina';
+
+const pool = new Piscina({
+  filename: path.resolve(__dirname, 'workers/procesador.worker.js'),
+  maxThreads: Math.max(1, os.cpus().length - 1),
+});
+
+const resultado = await pool.run({ datos: arrayGrande });
+```
+
+### Clustering
+
+```typescript
+import cluster from 'cluster';
+import os from 'os';
+
+if (cluster.isPrimary) {
+  const numCPUs = os.cpus().length;
+  for (let i = 0; i < numCPUs; i++) cluster.fork();
+  cluster.on('exit', (worker, code) => {
+    console.log(`Worker ${worker.process.pid} murió (código ${code}), reiniciando...`);
+    cluster.fork();
+  });
+} else {
+  const { app } = await import('./app');
+  app.listen(3000, () => console.log(`Worker ${process.pid} escuchando en 3000`));
+}
+```
+
+---
+
+## Prisma — Patterns de Producción
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query', 'warn', 'error'] : ['error'],
+  });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+
+// Query tipada con include
+const usuario = await prisma.usuario.findUniqueOrThrow({
+  where: { id },
+  include: { perfil: true, roles: { include: { permisos: true } } },
+});
+
+// Transacción
+const resultado = await prisma.$transaction(async (tx) => {
+  const user = await tx.usuario.create({ data: usuarioData });
+  await tx.auditLog.create({ data: { accion: 'CREATE', entityId: user.id } });
+  return user;
+});
+```
+
+## Drizzle — Schema y Queries
+
+```typescript
+import { pgTable, uuid, varchar, boolean, timestamp } from 'drizzle-orm/pg-core';
+
+export const usuarios = pgTable('usuarios', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  nombre: varchar('nombre', { length: 255 }).notNull(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  activo: boolean('activo').default(true).notNull(),
+  creadoEn: timestamp('creado_en').defaultNow().notNull(),
+});
+
+const activos = await db
+  .select().from(usuarios)
+  .where(eq(usuarios.activo, true))
+  .orderBy(asc(usuarios.nombre))
+  .limit(20);
+```
+
+---
+
+## Validación con Zod
+
+```typescript
+import { z } from 'zod';
+
+export const UsuarioCreateSchema = z.object({
+  nombre: z.string().min(2, 'Nombre muy corto').max(100),
+  email: z.string().email('Email inválido'),
+  edad: z.number().int().min(18).max(120).optional(),
+  rol: z.enum(['admin', 'usuario', 'moderador']).default('usuario'),
+});
+
+export type UsuarioCreate = z.infer<typeof UsuarioCreateSchema>;
+
+export function validar<T>(schema: z.ZodSchema<T>) {
+  return asyncHandler(async (req, _res, next) => {
+    const resultado = schema.safeParse(req.body);
+    if (!resultado.success) {
+      throw new ValidationError(
+        'Datos de entrada inválidos',
+        resultado.error.flatten().fieldErrors as Record<string, string[]>,
+      );
+    }
+    req.body = resultado.data;
+    next();
+  });
+}
+```
+
+---
+
+## Graceful Shutdown
+
+```typescript
+import { app } from './app';
+import { prisma } from './lib/prisma';
+import { logger } from './lib/logger';
+
+const server = app.listen(3000);
+
+async function shutdown(signal: string): Promise<void> {
+  logger.info(`Recibida señal ${signal}, iniciando graceful shutdown`);
+  server.close(async () => {
+    try {
+      await prisma.$disconnect();
+      logger.info('Graceful shutdown completado');
+      process.exit(0);
+    } catch (err) {
+      logger.error({ err }, 'Error durante graceful shutdown');
+      process.exit(1);
+    }
+  });
+  setTimeout(() => {
+    logger.error('Graceful shutdown timeout — forzando cierre');
+    process.exit(1);
+  }, 10_000);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('unhandledRejection', (reason, promise) => {
+  logger.error({ reason, promise }, 'Unhandled Promise Rejection');
+  shutdown('unhandledRejection');
+});
+process.on('uncaughtException', (err) => {
+  logger.error({ err }, 'Uncaught Exception');
+  process.exit(1);
+});
+```

package/habilidades/notificaciones-multicanal/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: notificaciones-multicanal
+description: Sistema de notificaciones para el agente notificador-swl. Cubre configuración de canales (desktop, Telegram, WhatsApp, email, webhook), formato de mensaje por canal, priorización de eventos, rate limiting, templates, integración con claude-notifications-go y ejemplos de config.json.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para notificaciones push del navegador al usuario final (Web Push API, PWA notifications) — para notificaciones al usuario en el frontend cargar `frontend-avanzado`."
+  - "No cargar para alertas de monitoreo de sistemas en producción (Prometheus Alertmanager, PagerDuty, OpsGenie) — para alerting de observabilidad cargar `monitoring-alertas`."
+  - "No cargar para envío masivo de correos de marketing o transaccionales a usuarios finales (SendGrid, Mailchimp, SES para millones de destinatarios) — para email marketing cargar el skill del proveedor correspondiente."
+  - "No cargar para notificaciones en tiempo real dentro de la app de usuario (WebSockets, SSE para actualizar la UI) — para realtime en el cliente cargar `frontend-avanzado`."
+---
+# Notificaciones Multicanal — notificador-swl
+
+## Cuándo NO cargar
+
+- La tarea es notificaciones push del navegador al usuario final (Web Push, PWA): cargar `frontend-avanzado`.
+- La tarea es alerting de monitoreo de sistemas (Prometheus Alertmanager, PagerDuty): cargar `monitoring-alertas`.
+- La tarea es envío masivo de correos a usuarios finales (marketing, transaccional a millones): cargar el skill del proveedor de email.
+- La tarea es actualizar la UI en tiempo real vía WebSockets o SSE: cargar `frontend-avanzado`.
+
+## Visión General
+
+El sistema de notificaciones multicanal permite que los agentes SWL comuniquen
+eventos importantes al humano a través de múltiples canales, priorizando según
+la urgencia y respetando el tiempo de atención del receptor.
+
+El binario `claude-notifications-go` actúa como broker central:
+recibe eventos via stdin (JSON) o HTTP local y los enruta al canal apropiado.
+
+```
+Agente SWL
+    |
+    v
+claude-notifications-go  --> Desktop (nativo OS)
+    |                    --> Telegram Bot
+    |                    --> WhatsApp Business API
+    |                    --> Email (SMTP)
+    +-------------------> Webhook HTTP
+```
+
+---
+
+## Reglas Obligatorias
+
+1. **NUNCA hardcodear tokens en config.json** — usar siempre variables de entorno (`${TELEGRAM_BOT_TOKEN}`).
+2. **La notificación es best-effort, NO bloqueante** — si falla, el hook NO debe fallar.
+3. **SIEMPRE incluir `proyecto` en el payload** — sin él, es imposible filtrar en el historial.
+4. **NUNCA usar prioridad `critico` para eventos rutinarios** — causa fatiga de alertas.
+5. **SIEMPRE configurar horario No Molestar** — interrupciones fuera de horario son inaceptables.
+6. **Canal email: máximo 1 vez por hora** — no para eventos de alta frecuencia.
+
+---
+
+## Priorización de Eventos
+
+| Nivel | Canales activados | Ejemplos |
+|-------|------------------|---------|
+| `critico` | Todos los canales simultáneamente | Error irreversible, pérdida de datos |
+| `urgente` | Desktop + Telegram (simultáneo) | human-action bloqueante |
+| `alta` | Desktop + Telegram (secuencial) | checkpoint decision |
+| `normal` | Canal primario únicamente | human-verify, progreso |
+| `baja` | Solo log local | Métricas, telemetría interna |
+
+### Mapeo evento a prioridad
+
+```jsonc
+{
+  "mapeo": {
+    "checkpoint.human-action":         "urgente",
+    "checkpoint.decision":             "alta",
+    "checkpoint.human-verify":         "normal",
+    "error.critico":                   "critico",
+    "error.recuperable":               "alta",
+    "fase.completada":                 "normal",
+    "alerta.seguridad":                "critico"
+  }
+}
+```
+
+---
+
+## Integración con claude-notifications-go
+
+### Envío desde hook (stdin)
+
+```javascript
+// hooks/notify.js
+const { execSync } = require('child_process');
+
+function notificar(evento) {
+  const payload = JSON.stringify(evento);
+  try {
+    execSync('claude-notifications-go send', {
+      input: payload,
+      stdio: ['pipe', 'ignore', 'ignore'],
+      timeout: 5000,
+    });
+  } catch {
+    // Fallo silencioso — la notificación no es crítica para el flujo
+  }
+}
+
+notificar({
+  tipo: 'checkpoint.human-verify',
+  proyecto: process.env.PROJECT_NAME,
+  titulo: 'Slice 1 completado',
+  resumen: 'CRUD de usuarios implementado y testeado.',
+  accion_requerida: true,
+});
+```
+
+### Envío via HTTP local
+
+```bash
+curl -s -X POST http://localhost:19999/notify \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tipo": "checkpoint.decision",
+    "proyecto": "sigaf-backend",
+    "titulo": "Decision requerida: motor de base de datos",
+    "prioridad": "alta"
+  }'
+```
+
+### Comandos de gestión
+
+```bash
+claude-notifications-go start --config ~/.claude/notifications/config.json
+claude-notifications-go status
+claude-notifications-go test --canal telegram
+claude-notifications-go log --ultimas 20
+claude-notifications-go flush-queue
+```
+
+---
+
+## Anti-patrones
+
+- Enviar notificaciones de prioridad `critico` para eventos rutinarios (fatiga de alertas)
+- Hardcodear tokens en `config.json` en lugar de usar variables de entorno
+- No configurar el horario No Molestar (interrupciones fuera de horario)
+- Fallar el hook si la notificación falla (la notificación es best-effort)
+- Usar el canal email para eventos de alta frecuencia
+- Omitir `proyecto` en el payload
+
+---
+
+Para configuración completa de canales (config.json), formato de mensaje por canal (Desktop, Telegram, WhatsApp, Email, Webhook), rate limiting, supresión de duplicados, templates de mensajes y flujo de diagnóstico, ver [recursos/configuracion-y-templates.md](recursos/configuracion-y-templates.md).
+
+## Gotchas / Errores comunes no obvios
+
+**El hook falla cuando `claude-notifications-go` no está en el PATH del proceso de Claude Code aunque esté instalado globalmente**: Claude Code ejecuta hooks con un PATH reducido (sin `~/.local/bin` ni `/usr/local/bin` en algunas configuraciones de shell). Si el binario está instalado fuera del PATH del sistema base, el `execSync('claude-notifications-go send')` lanza `ENOENT` y, si el catch está vacío como se recomienda, el hook silencia el error sin notificar nada. Causa: el PATH del proceso de hook depende del shell y la configuración del usuario, no del PATH interactivo. Fix: usar la ruta absoluta del binario: `which claude-notifications-go` para obtenerla y configurarla como variable en el hook, o añadir el directorio de instalación a `PATH` en el archivo de perfil del shell que Claude Code hereda.
+
+**Los mensajes de Telegram con más de 4,096 caracteres son silenciosamente truncados por la API de Telegram sin error**: si el campo `resumen` del payload incluye stack traces o diffs largos, la API retorna `ok: true` pero el usuario recibe el mensaje cortado sin ningún indicador visual de que falta contenido. Causa: la API de Telegram Bot tiene un límite de 4,096 caracteres por mensaje en modo texto y 1,024 en modo caption. Fix: en el hook, truncar el `resumen` a 3,500 caracteres antes de enviar y agregar `"\n... [mensaje truncado]"` si se supera el límite. Alternativamente, enviar como archivo adjunto `.txt` para mensajes largos.
+
+**El canal email falla silenciosamente cuando el servidor SMTP requiere TLS pero `claude-notifications-go` está configurado con `port: 25` (plaintext)**: la conexión se establece pero el servidor SMTP rechaza los comandos de autenticación sin TLS. El error del servidor (`534 Authentication required`) llega como respuesta SMTP pero `claude-notifications-go` lo registra en su log local, no lo propaga al hook. Causa: el puerto 25 es para relay servidor-a-servidor sin autenticación; los usuarios deben usar 587 (STARTTLS) o 465 (SSL/TLS). Fix: configurar `port: 587` con `tls: starttls` o `port: 465` con `tls: ssl` en `config.json` según el proveedor SMTP. Verificar con `claude-notifications-go test --canal email` que devuelve éxito.
+
+**La prioridad `critico` activa todos los canales simultáneamente, y si el canal email tiene rate limiting de 1/hora, el segundo evento crítico en menos de una hora llega sin el correo aunque sí por Telegram y desktop**: el usuario recibe la notificación pero asume que "falta el email" es un fallo del sistema, cuando en realidad es el rate limiting configurado. Causa: el rate limiting por canal se aplica independientemente de la prioridad del evento. Fix: excluir el canal email del rate limiting para eventos de prioridad `critico`, ya que son raros por definición (si son frecuentes, el problema es el uso incorrecto de la prioridad). Documentar en el runbook qué canales tienen rate limiting para evitar confusión operacional.

package/habilidades/notificaciones-multicanal/recursos/config-template.json

@@ -0,0 +1,115 @@
+{
+  "_instrucciones": [
+    "Copiar este archivo a ~/.claude/notifications/config.json",
+    "Reemplazar los valores entre <angulos> con los valores reales",
+    "Las credenciales sensibles deben ir en variables de entorno (sintaxis ${VAR})",
+    "Borrar este campo '_instrucciones' antes de usar el archivo"
+  ],
+  "version": "2",
+  "defaults": {
+    "canal_primario": "desktop",
+    "prioridad_minima": "normal",
+    "idioma": "es-MX",
+    "zona_horaria": "America/Mexico_City"
+  },
+  "notificaciones": {
+    "desktop": {
+      "enabled": true,
+      "motor": "auto",
+      "icono": "~/.claude/assets/swl-icon.png",
+      "sonido": true,
+      "duracion_ms": 5000,
+      "persistente_si_prioridad": "urgente"
+    },
+    "telegram": {
+      "enabled": false,
+      "bot_token": "${TELEGRAM_BOT_TOKEN}",
+      "chat_id": "${TELEGRAM_CHAT_ID}",
+      "parse_mode": "HTML",
+      "disable_preview": true,
+      "timeout_segundos": 10,
+      "_nota": "Crear bot en @BotFather, obtener token. Agregar bot al chat y obtener chat_id via /getUpdates"
+    },
+    "whatsapp": {
+      "enabled": false,
+      "proveedor": "twilio",
+      "account_sid": "${TWILIO_ACCOUNT_SID}",
+      "auth_token": "${TWILIO_AUTH_TOKEN}",
+      "from_number": "${TWILIO_WHATSAPP_FROM}",
+      "to_number": "${WHATSAPP_TO_NUMBER}",
+      "_nota": "Requiere cuenta Twilio con WhatsApp Sandbox habilitado. from_number formato: whatsapp:+14155238886"
+    },
+    "email": {
+      "enabled": false,
+      "smtp_host": "${SMTP_HOST}",
+      "smtp_port": 587,
+      "smtp_user": "${SMTP_USER}",
+      "smtp_password": "${SMTP_PASSWORD}",
+      "smtp_tls": true,
+      "from": "swl-notifier@<tu-dominio.com>",
+      "to": ["<destinatario@empresa.com>"],
+      "asunto_prefijo": "[SWL]",
+      "_nota": "Para Gmail usar smtp.gmail.com:587 con App Password (no la contraseña de la cuenta)"
+    },
+    "webhook": {
+      "enabled": false,
+      "url": "${WEBHOOK_URL}",
+      "metodo": "POST",
+      "headers": {
+        "Authorization": "Bearer ${WEBHOOK_TOKEN}",
+        "Content-Type": "application/json"
+      },
+      "timeout_segundos": 5,
+      "reintentos": 2,
+      "_nota": "El payload enviado sigue el esquema de webhook definido en la habilidad notificaciones-multicanal"
+    }
+  },
+  "prioridades": {
+    "mapeo": {
+      "checkpoint.human-action": "urgente",
+      "checkpoint.decision": "alta",
+      "checkpoint.human-verify": "normal",
+      "error.critico": "critico",
+      "error.recuperable": "alta",
+      "fase.completada": "normal",
+      "fase.iniciada": "baja",
+      "tarea.completada": "baja",
+      "alerta.seguridad": "critico"
+    },
+    "canales_por_nivel": {
+      "critico": ["desktop", "telegram", "email", "whatsapp"],
+      "urgente": ["desktop", "telegram"],
+      "alta": ["desktop", "telegram"],
+      "normal": ["desktop"],
+      "baja": []
+    }
+  },
+  "rate_limiting": {
+    "ventana_segundos": 300,
+    "maximo_por_ventana": {
+      "desktop": 10,
+      "telegram": 20,
+      "whatsapp": 5,
+      "email": 3,
+      "webhook": 50
+    },
+    "excepcion_prioridades": ["critico", "urgente"]
+  },
+  "no_molestar": {
+    "habilitado": false,
+    "inicio": "22:00",
+    "fin": "08:00",
+    "zona_horaria": "America/Mexico_City",
+    "excepciones": ["critico"],
+    "acumulacion": {
+      "habilitada": true,
+      "resumen_en": "08:00",
+      "canal_resumen": "telegram"
+    }
+  },
+  "deduplicacion": {
+    "habilitada": true,
+    "ventana_segundos": 60,
+    "clave": "evento.tipo + evento.proyecto + mensaje.titulo"
+  }
+}