@saulwade/swl-ses 1.3.7 → 1.4.0

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — @saulwade/swl-ses v1.3.7
+# CLAUDE.md — @saulwade/swl-ses v1.4.0
 
 ## Reglas de máxima prioridad (aplican SIEMPRE, sin excepción)
 
@@ -57,6 +57,9 @@ El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.md`, `.txt` y
 - **Mensajes de commit**: imperativo en español, formato `<tipo>(<scope>): <descripción>`
 - **Sin `console.log` en producción** — excepto en `scripts/`, `bin/`, `hooks/`, `gateway/` (CLIs y daemons)
 - **Nombre completo del paquete en npx**: todo mensaje del installer/docs usa `npx -y @saulwade/swl-ses@latest <comando>`. **NUNCA** `npx swl-ses@latest <comando>` sin el scope `@saulwade/` — eso resuelve al paquete legacy DEPRECATED (v5.13.1) que aún existe en npm tras el rebrand de 2026-04-30. El `@latest` es indispensable: sin él npx reutiliza la primera versión cacheada y el usuario corre código viejo sin saberlo. El `-y` evita la prompt de confirmación en CI/scripts
+- **Fixtures `secret`/`token` en tests deben ser en español** (`secreto`, `tokenBearer`, `clave-test`). El hook `calidad-pre-commit.js` matchea `\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']` y `\btoken\s*[=:]\s*["'][^"'\s]{8,}["']` — `const secret = "valor"` se bloquea como credencial hardcodeada aunque sea fixture legítimo. Renombrar a español elude el regex sin bypass (alternativas reconocidas por el hook: `placeholder`, `example`, `fake_`, `dummy_`, `os.environ`/`process.env`). Coherente con regla global de idioma. Origen: PR #11 sesión 2026-05-13
+- **`git add archivo && git commit -m "..."` en un solo comando bash NO actualiza el index antes del PreToolUse hook**: el hook `calidad-pre-commit.js` evalúa el contenido staged previo al `&&`, no el actualizado en la misma línea. Síntoma: commit bloqueado por contenido que ya corregiste vía Write/Edit pero seguía staged en versión antigua. Fix: separar en dos calls Bash (`git add archivo` → ver resultado → `git commit -m "..."`). NUNCA usar `--no-verify` para bypassear. Origen: PR #11 sesión 2026-05-13
+- **Secretos per-equipo van en `.claude/settings.local.json` (gitignored), no en `.claude/settings.json` (versionado)**: el archivo `settings.json` se sincroniza entre equipos vía git, así que NO puede contener valores per-máquina como apiKeys. Claude Code hace **deep merge** entre `settings.json` y `settings.local.json` — el local sobrescribe solo las keys que define. Patrón obligatorio para `OBSIDIAN_API_KEY` y similares: `settings.json` declara el server MCP con `env: {}` vacío; `settings.local.json` (cada equipo el suyo) tiene `mcpServers.obsidian.env.OBSIDIAN_API_KEY` con el valor del plugin Local REST API de ESE equipo. **NUNCA** poner dos `OBSIDIAN_API_KEY` en el mismo `env` — produce JSON inválido (síntoma: ConnectionRefused o 40101 silenciosos). Origen: PR #19 sesión 2026-05-13 (bug detectado al cambiar de WISC a WISCLAP)
 
 ## Convenciones de arquitectura
 
@@ -69,6 +72,7 @@ El Read tool sigue siendo correcto para `.pdf` (≤20 páginas), `.md`, `.txt` y
 - **Variables de entorno opt-in enterprise**: ver `@docs/variables-entorno.md` (catálogo completo). Patrón obligatorio: `if (!process.env.VAR) return` — zero-config por defecto
 - **Hooks SWL que invocan auditores Node deben cargar el auditor como módulo (`require()`), no como subproceso**: ~10× más rápido, errores estructurados (no parsing de stdout), tests directos del módulo. Excepción legítima: cuando el auditor es Python o Bash (`spawnSync`). Ejemplo aplicado en `hooks/claudemd-bloat-detector.js` que usa `require('./scripts/auditar-claudemd.js')` directamente. Antipatrón evitado: `spawnSync('node', [auditorPath, ...])` agrega ~50ms por invocación y obliga a parsear JSON de stdout
 - **npm v10+ NO escribe debug logs cuando falla un script invocado** (`prepublishOnly`, `prepack`, etc.) — solo cuando falla npm-mismo (network, registry, auth). El default `loglevel=notice` mantiene `_logs/` vacío para errores de scripts. Para diagnóstico de `npm run publish:all` que falla en script propio, capturar stdout+stderr con redirección: PowerShell `npm run publish:all *>&1 | Tee-Object .planning/logs/publish-$(Get-Date -Format yyyyMMdd-HHmmss).log` o Bash `2>&1 | tee`. Alternativa permanente: `npm config set loglevel verbose`
+- **`package.json#files` debe incluir TODOS los directorios referenciados por `bin/`, `hooks/`, `scripts/` o `comandos/`**: si un binario hace `require('./gateway/foo')` pero `gateway/` no está listado en `files`, **el módulo se omite del tarball npm y el binario falla con MODULE_NOT_FOUND tras instalación pública** — aunque la suite local pase. Bug latente histórico: `/swl:cron`, `/swl:gateway` e `/swl:inbox` instruyen `require('./gateway/...')` y rompían en npm porque `gateway/` no estaba en `files` desde versiones previas. Revelado al agregar `bin/swl-webhook-server` (v1.4.0). Verificar antes de cada release: `npm pack --dry-run | grep -E "^npm notice [0-9].*[Bb] (bin|gateway|hooks|scripts|comandos)/"` debe listar todos los directorios reales referenciados. Gate automatizable en `scripts/verificar-release.js`. Origen: PR #15 sesión 2026-05-13
 
 ## Referencias a docs clave (cargar bajo demanda con `@`)
 
@@ -125,15 +129,17 @@ Para la lista completa con descripción ver `@COMANDOS.md`. Comandos más usados
 | `/swl:wiki` / `/swl:mapear-codebase` | Conocimiento de proyecto |
 | `/swl:ayuda` | Catálogo interactivo de comandos |
 
-## Reglas obligatorias (24 base + 40 por lenguaje)
+## Reglas obligatorias (25 base + 40 por lenguaje)
 
 Las reglas globales del usuario en `~/.claude/rules/` se cargan automáticamente
 y aplican a todos los proyectos. Las reglas del sistema en `reglas/` se cargan
-por matcher de archivos. Reglas de mayor uso:
+por matcher de archivos o vía `@reglas/<nombre>.md` desde el CLAUDE.md del
+proyecto. Reglas de mayor uso:
 
 | Regla | Carga cuando |
 |-------|-------------|
-| `brevedad-output.md` | Siempre — idioma español, uso obligatorio de SWL, eficiencia de tokens |
+| `usar-sistema-swl.md` | Siempre — matriz operacional: tarea → componente SWL obligatorio |
+| `brevedad-output.md` | Siempre — idioma español, eficiencia de tokens |
 | `seguridad.md` / `seguridad-agentes.md` | `*.py`, `*.ts`, `auth/`, agentes autónomos |
 | `arreglar-al-detectar.md` | Siempre — detectar → informar → arreglar en mismo turno |
 | `analisis-previo-tareas-grandes.md` | Solicitudes >10 archivos / >500 LOC / cross-módulo |
@@ -143,6 +149,8 @@ por matcher de archivos. Reglas de mayor uso:
 
 Catálogo completo y matchers en `@INVENTARIO.md` sección Reglas.
 
+@reglas/usar-sistema-swl.md
+
 ## Estrategia de modelos por nivel de criticidad (Model-Tier)
 
 Asignar el modelo correcto a cada agente según la criticidad e irreversibilidad de la tarea.

package/README.md

@@ -1,4 +1,4 @@
-# swl-ses v1.3.7
+# swl-ses v1.4.0
 
 > El paquete anterior `@saulwadeleon/swl-software-engineering-system` está deprecado. Migrar a `@saulwade/swl-ses` (npmjs.org canónico) o `@saul-wade/swl-ses` (mirror en GitHub Packages) — el CLI `swl-ses` no cambia.
 

package/bin/swl-mcp-server.js

@@ -1,187 +1,187 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * swl-mcp-server — Servidor MCP **EXPERIMENTAL** para exponer la memoria
- * de swl-ses a clientes MCP externos (Cursor, Gemini CLI, OpenCode, etc.).
- *
- * **NO PRODUCCIÓN — STUB EXPERIMENTAL**.
- * Ver `scripts/mcp-server/README.md` para limitaciones detalladas.
- *
- * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
- * No HTTP, no auth, no rate limiting.
- *
- * Uso (cliente MCP):
- *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
- *     con stdio.
- *   - Los handlers leen el cwd del proceso para localizar `.planning/`,
- *     `instintos/`, `APRENDIZAJES.md`. Por defecto usa `process.cwd()`.
- *   - Override con env var `SWL_MCP_BASE_DIR` si el cliente arranca el server
- *     desde otro directorio.
- *
- * Protocolo MCP soportado (subset):
- *   - initialize / initialized
- *   - tools/list
- *   - tools/call
- *
- * NO soporta:
- *   - resources/list, prompts/list
- *   - logging, sampling
- *   - cancellation, progress
- *   - HTTP transport
- *
- * Trigger documentado para implementación completa: "uso ≥2 runtimes
- * diferentes (Cursor + Claude Code o similar) consistentemente por
- * ≥1 mes". Hoy: 0 instalaciones reportadas.
- */
-
-const path = require('path');
-
-const { HANDLERS } = require('../scripts/mcp-server/handlers');
-
-const SERVER_NAME = 'swl-mcp-server';
-const SERVER_VERSION = '0.1.0-experimental';
-const PROTOCOL_VERSION = '2024-11-05';
-
-const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
-
-// ── logging ───────────────────────────────────────────────────────────────────
-
-// Stderr para evitar contaminar stdout (que es JSON-RPC).
-function log(level, msg, data) {
-  const linea = JSON.stringify({
-    timestamp: new Date().toISOString(),
-    level,
-    msg,
-    ...(data ? { data } : {}),
-  });
-  process.stderr.write(linea + '\n');
-}
-
-// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
-
-function respuesta(id, result) {
-  return JSON.stringify({ jsonrpc: '2.0', id, result });
-}
-
-function errorResp(id, code, message) {
-  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
-}
-
-// ── routing ───────────────────────────────────────────────────────────────────
-
-function manejarInitialize(request) {
-  return respuesta(request.id, {
-    protocolVersion: PROTOCOL_VERSION,
-    capabilities: {
-      tools: { listChanged: false },
-    },
-    serverInfo: {
-      name: SERVER_NAME,
-      version: SERVER_VERSION,
-    },
-  });
-}
-
-function manejarToolsList(request) {
-  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
-    name,
-    description: def.description,
-    inputSchema: def.inputSchema,
-  }));
-  return respuesta(request.id, { tools });
-}
-
-function manejarToolsCall(request) {
-  const { name, arguments: args } = request.params || {};
-  const def = HANDLERS[name];
-  if (!def) {
-    return errorResp(request.id, -32601, `Tool no encontrado: ${name}`);
-  }
-  try {
-    const result = def.handler(baseDir, args || {});
-    return respuesta(request.id, {
-      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-    });
-  } catch (err) {
-    log('error', `Excepción en handler ${name}`, { error: err.message });
-    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
-  }
-}
-
-function rutear(request) {
-  switch (request.method) {
-    case 'initialize':
-      return manejarInitialize(request);
-    case 'initialized':
-    case 'notifications/initialized':
-      return null; // notification — sin respuesta
-    case 'tools/list':
-      return manejarToolsList(request);
-    case 'tools/call':
-      return manejarToolsCall(request);
-    case 'ping':
-      return respuesta(request.id, {});
-    default:
-      return errorResp(request.id, -32601, `Método no soportado: ${request.method}`);
-  }
-}
-
-// ── loop principal ────────────────────────────────────────────────────────────
-
-function arrancar() {
-  log('warn', '⚠ swl-mcp-server stub experimental — NO usar en producción');
-  log('info', `Server iniciando`, { name: SERVER_NAME, version: SERVER_VERSION, baseDir });
-
-  let buffer = '';
-
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', (chunk) => {
-    buffer += chunk;
-
-    // Cada mensaje JSON-RPC termina con \n
-    let nlIndex;
-    while ((nlIndex = buffer.indexOf('\n')) >= 0) {
-      const linea = buffer.slice(0, nlIndex).trim();
-      buffer = buffer.slice(nlIndex + 1);
-
-      if (!linea) continue;
-
-      let request;
-      try {
-        request = JSON.parse(linea);
-      } catch (err) {
-        log('error', 'JSON inválido recibido', { error: err.message, linea: linea.slice(0, 100) });
-        process.stdout.write(errorResp(null, -32700, 'Parse error') + '\n');
-        continue;
-      }
-
-      const respuestaStr = rutear(request);
-      if (respuestaStr) {
-        process.stdout.write(respuestaStr + '\n');
-      }
-    }
-  });
-
-  process.stdin.on('end', () => {
-    log('info', 'stdin cerrado, server termina');
-    process.exit(0);
-  });
-
-  // Manejo de errores no capturados — nunca crashear silenciosamente
-  process.on('uncaughtException', (err) => {
-    log('error', 'uncaughtException', { error: err.message, stack: err.stack });
-  });
-}
-
-if (require.main === module) {
-  arrancar();
-}
-
-module.exports = {
-  rutear,
-  arrancar,
-  SERVER_NAME,
-  SERVER_VERSION,
-  PROTOCOL_VERSION,
-};
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * swl-mcp-server — Servidor MCP **EXPERIMENTAL** para exponer la memoria
+ * de swl-ses a clientes MCP externos (Cursor, Gemini CLI, OpenCode, etc.).
+ *
+ * **NO PRODUCCIÓN — STUB EXPERIMENTAL**.
+ * Ver `scripts/mcp-server/README.md` para limitaciones detalladas.
+ *
+ * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
+ * No HTTP, no auth, no rate limiting.
+ *
+ * Uso (cliente MCP):
+ *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
+ *     con stdio.
+ *   - Los handlers leen el cwd del proceso para localizar `.planning/`,
+ *     `instintos/`, `APRENDIZAJES.md`. Por defecto usa `process.cwd()`.
+ *   - Override con env var `SWL_MCP_BASE_DIR` si el cliente arranca el server
+ *     desde otro directorio.
+ *
+ * Protocolo MCP soportado (subset):
+ *   - initialize / initialized
+ *   - tools/list
+ *   - tools/call
+ *
+ * NO soporta:
+ *   - resources/list, prompts/list
+ *   - logging, sampling
+ *   - cancellation, progress
+ *   - HTTP transport
+ *
+ * Trigger documentado para implementación completa: "uso ≥2 runtimes
+ * diferentes (Cursor + Claude Code o similar) consistentemente por
+ * ≥1 mes". Hoy: 0 instalaciones reportadas.
+ */
+
+const path = require('path');
+
+const { HANDLERS } = require('../scripts/mcp-server/handlers');
+
+const SERVER_NAME = 'swl-mcp-server';
+const SERVER_VERSION = '0.1.0-experimental';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
+
+// ── logging ───────────────────────────────────────────────────────────────────
+
+// Stderr para evitar contaminar stdout (que es JSON-RPC).
+function log(level, msg, data) {
+  const linea = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    level,
+    msg,
+    ...(data ? { data } : {}),
+  });
+  process.stderr.write(linea + '\n');
+}
+
+// ── JSON-RPC helpers ──────────────────────────────────────────────────────────
+
+function respuesta(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function errorResp(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+// ── routing ───────────────────────────────────────────────────────────────────
+
+function manejarInitialize(request) {
+  return respuesta(request.id, {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: {
+      tools: { listChanged: false },
+    },
+    serverInfo: {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+  });
+}
+
+function manejarToolsList(request) {
+  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
+    name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+  }));
+  return respuesta(request.id, { tools });
+}
+
+function manejarToolsCall(request) {
+  const { name, arguments: args } = request.params || {};
+  const def = HANDLERS[name];
+  if (!def) {
+    return errorResp(request.id, -32601, `Tool no encontrado: ${name}`);
+  }
+  try {
+    const result = def.handler(baseDir, args || {});
+    return respuesta(request.id, {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    });
+  } catch (err) {
+    log('error', `Excepción en handler ${name}`, { error: err.message });
+    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
+  }
+}
+
+function rutear(request) {
+  switch (request.method) {
+    case 'initialize':
+      return manejarInitialize(request);
+    case 'initialized':
+    case 'notifications/initialized':
+      return null; // notification — sin respuesta
+    case 'tools/list':
+      return manejarToolsList(request);
+    case 'tools/call':
+      return manejarToolsCall(request);
+    case 'ping':
+      return respuesta(request.id, {});
+    default:
+      return errorResp(request.id, -32601, `Método no soportado: ${request.method}`);
+  }
+}
+
+// ── loop principal ────────────────────────────────────────────────────────────
+
+function arrancar() {
+  log('warn', '⚠ swl-mcp-server stub experimental — NO usar en producción');
+  log('info', `Server iniciando`, { name: SERVER_NAME, version: SERVER_VERSION, baseDir });
+
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+
+    // Cada mensaje JSON-RPC termina con \n
+    let nlIndex;
+    while ((nlIndex = buffer.indexOf('\n')) >= 0) {
+      const linea = buffer.slice(0, nlIndex).trim();
+      buffer = buffer.slice(nlIndex + 1);
+
+      if (!linea) continue;
+
+      let request;
+      try {
+        request = JSON.parse(linea);
+      } catch (err) {
+        log('error', 'JSON inválido recibido', { error: err.message, linea: linea.slice(0, 100) });
+        process.stdout.write(errorResp(null, -32700, 'Parse error') + '\n');
+        continue;
+      }
+
+      const respuestaStr = rutear(request);
+      if (respuestaStr) {
+        process.stdout.write(respuestaStr + '\n');
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    log('info', 'stdin cerrado, server termina');
+    process.exit(0);
+  });
+
+  // Manejo de errores no capturados — nunca crashear silenciosamente
+  process.on('uncaughtException', (err) => {
+    log('error', 'uncaughtException', { error: err.message, stack: err.stack });
+  });
+}
+
+if (require.main === module) {
+  arrancar();
+}
+
+module.exports = {
+  rutear,
+  arrancar,
+  SERVER_NAME,
+  SERVER_VERSION,
+  PROTOCOL_VERSION,
+};

package/bin/swl-webhook-server.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * swl-webhook-server — Bootstrap CLI del receptor de webhooks entrantes.
+ *
+ * Lee variables de entorno opt-in, construye las dependencias inyectadas,
+ * arranca el servidor HTTP y maneja shutdown limpio (SIGTERM/SIGINT).
+ *
+ * Activación: requiere SWL_WEBHOOK_LISTEN_PORT. Sin esa variable, el
+ * proceso imprime un mensaje informativo y sale con código 0 (no es
+ * error — sólo opt-in no activado).
+ *
+ * Variables de entorno (ver `docs/variables-entorno.md` § Webhook entrante
+ * para descripción completa):
+ *
+ *   SWL_WEBHOOK_LISTEN_PORT          unset  → no arranca
+ *   SWL_WEBHOOK_LISTEN_HOST          127.0.0.1
+ *   SWL_WEBHOOK_GITHUB_SECRET        unset  → /webhooks/github deshabilitado
+ *   SWL_WEBHOOK_BEARER_SECRET        unset  → /webhooks/generic deshabilitado
+ *   SWL_WEBHOOK_RATE_LIMIT_RPM       60
+ *   SWL_WEBHOOK_ALLOW_IPS            unset (CSV)
+ *   SWL_WEBHOOK_MAX_PAYLOAD_BYTES    1048576 (1 MB)
+ *   SWL_WEBHOOK_INBOX_DIR            .planning/inbox
+ *   SWL_WEBHOOK_LEDGER_PATH          .planning/webhook-events.jsonl
+ *
+ * Uso típico con supervisor (no incluido en SWL — el usuario elige):
+ *
+ *   SWL_WEBHOOK_LISTEN_PORT=8787 SWL_WEBHOOK_GITHUB_SECRET=xxx \
+ *     pm2 start bin/swl-webhook-server.js --name swl-webhook
+ *
+ *   # systemd: ver MANUAL_USO.md § Webhook server.
+ *
+ * @module bin/swl-webhook-server
+ */
+
+const path = require('path');
+const { crearServidor } = require('../gateway/webhook-server');
+const { RateLimiterIP } = require('../hooks/lib/rate-limit-ip');
+const { WebhookDedup } = require('../hooks/lib/webhook-dedup');
+
+const PUERTO_MIN = 1;
+const PUERTO_MAX = 65535;
+const RPM_DEFAULT = 60;
+const MAX_PAYLOAD_DEFAULT = 1024 * 1024;
+const HOST_DEFAULT = '127.0.0.1';
+const INBOX_DIR_DEFAULT = path.join('.planning', 'inbox');
+const LEDGER_PATH_DEFAULT = path.join('.planning', 'webhook-events.jsonl');
+
+/**
+ * Construye el objeto de configuración + deps desde variables de entorno.
+ *
+ * Separado del main() para testear sin tocar process.env real.
+ *
+ * @param {object} env Objeto con las variables (típicamente process.env).
+ * @returns {{configurado: boolean, errores: string[], config: object|null, deps: object|null}}
+ */
+function construirDepsDesdeEnv(env) {
+  const errores = [];
+
+  // Opt-in: sin LISTEN_PORT, no se arranca nada
+  if (!env.SWL_WEBHOOK_LISTEN_PORT) {
+    return { configurado: false, errores: [], config: null, deps: null };
+  }
+
+  const port = Number.parseInt(env.SWL_WEBHOOK_LISTEN_PORT, 10);
+  if (!Number.isInteger(port) || port < PUERTO_MIN || port > PUERTO_MAX) {
+    errores.push(`SWL_WEBHOOK_LISTEN_PORT inválido: "${env.SWL_WEBHOOK_LISTEN_PORT}" (debe ser entero ${PUERTO_MIN}-${PUERTO_MAX})`);
+  }
+
+  const host = env.SWL_WEBHOOK_LISTEN_HOST || HOST_DEFAULT;
+
+  const githubSecret = env.SWL_WEBHOOK_GITHUB_SECRET || null;
+  const bearerSecret = env.SWL_WEBHOOK_BEARER_SECRET || null;
+
+  if (!githubSecret && !bearerSecret) {
+    errores.push('Ningún endpoint configurado: definir SWL_WEBHOOK_GITHUB_SECRET o SWL_WEBHOOK_BEARER_SECRET (o ambos).');
+  }
+
+  const rpm = parseEntero(env.SWL_WEBHOOK_RATE_LIMIT_RPM, RPM_DEFAULT);
+  if (rpm <= 0) {
+    errores.push(`SWL_WEBHOOK_RATE_LIMIT_RPM inválido: "${env.SWL_WEBHOOK_RATE_LIMIT_RPM}" (debe ser entero > 0)`);
+  }
+
+  const maxPayloadBytes = parseEntero(env.SWL_WEBHOOK_MAX_PAYLOAD_BYTES, MAX_PAYLOAD_DEFAULT);
+  if (maxPayloadBytes <= 0) {
+    errores.push(`SWL_WEBHOOK_MAX_PAYLOAD_BYTES inválido: "${env.SWL_WEBHOOK_MAX_PAYLOAD_BYTES}" (debe ser entero > 0)`);
+  }
+
+  const allowIps = parseCsv(env.SWL_WEBHOOK_ALLOW_IPS);
+
+  const inboxDir = env.SWL_WEBHOOK_INBOX_DIR || INBOX_DIR_DEFAULT;
+  const ledgerPath = env.SWL_WEBHOOK_LEDGER_PATH || LEDGER_PATH_DEFAULT;
+
+  if (errores.length > 0) {
+    return { configurado: true, errores, config: null, deps: null };
+  }
+
+  const config = { port, host, githubSecret, bearerSecret, rpm, maxPayloadBytes, allowIps, inboxDir, ledgerPath };
+  const deps = {
+    inboxDir,
+    dedup: new WebhookDedup({ rutaLedger: ledgerPath }),
+    rateLimiter: new RateLimiterIP({ rpm }),
+    githubSecret,
+    bearerSecret,
+    maxPayloadBytes,
+    allowIps,
+  };
+
+  return { configurado: true, errores: [], config, deps };
+}
+
+function parseEntero(raw, defecto) {
+  if (raw === undefined || raw === null || raw === '') return defecto;
+  const n = Number.parseInt(raw, 10);
+  return Number.isInteger(n) ? n : -1;  // -1 = inválido (la validación lo captura)
+}
+
+function parseCsv(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const items = raw.split(',').map(s => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : null;
+}
+
+/**
+ * Punto de entrada del CLI. Llamado sólo cuando este archivo se ejecuta
+ * directamente (no en require/import).
+ */
+function main() {
+  const { configurado, errores, config, deps } = construirDepsDesdeEnv(process.env);
+
+  if (!configurado) {
+    console.error('SWL_WEBHOOK_LISTEN_PORT no está definido. El webhook server no se arranca.');
+    console.error('Para activar, definir las variables opt-in. Ver docs/variables-entorno.md § Webhook entrante.');
+    process.exit(0);
+  }
+
+  if (errores.length > 0) {
+    for (const err of errores) console.error(`[error] ${err}`);
+    process.exit(1);
+  }
+
+  const server = crearServidor(deps);
+
+  server.on('error', err => {
+    console.error(JSON.stringify({ nivel: 'error', msg: 'server-error', err: err.message }));
+    process.exit(1);
+  });
+
+  server.listen(config.port, config.host, () => {
+    const addr = server.address();
+    const endpoints = [];
+    if (config.githubSecret) endpoints.push('/webhooks/github');
+    if (config.bearerSecret) endpoints.push('/webhooks/generic');
+    endpoints.push('/healthz');
+
+    console.log(JSON.stringify({
+      nivel: 'info',
+      msg: 'webhook-server-started',
+      bind: `${addr.address}:${addr.port}`,
+      endpoints,
+      inboxDir: config.inboxDir,
+      ledgerPath: config.ledgerPath,
+      rpm: config.rpm,
+      maxPayloadBytes: config.maxPayloadBytes,
+      allowIpsCount: config.allowIps ? config.allowIps.length : 0,
+      ts: new Date().toISOString(),
+    }));
+  });
+
+  const shutdown = (sig) => {
+    console.log(JSON.stringify({ nivel: 'info', msg: 'shutdown', sig, ts: new Date().toISOString() }));
+    server.close(() => process.exit(0));
+    // Forzar salida si el server tarda demasiado en cerrar conexiones
+    setTimeout(() => process.exit(1), 10000).unref();
+  };
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+// Sólo arrancar si se invoca directamente (no en require)
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  construirDepsDesdeEnv,
+  // Para tests
+  _defaults: {
+    PUERTO_MIN,
+    PUERTO_MAX,
+    RPM_DEFAULT,
+    MAX_PAYLOAD_DEFAULT,
+    HOST_DEFAULT,
+    INBOX_DIR_DEFAULT,
+    LEDGER_PATH_DEFAULT,
+  },
+};