@saulwade/swl-ses 1.4.2 → 1.5.1

package/bin/swl-mcp-server.js

@@ -1,187 +1,214 @@
-#!/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 de solo lectura para exponer la memoria
+ * de swl-ses a clientes MCP externos (Cursor, Codex CLI, Gemini CLI, etc.).
+ *
+ * v1.0.0 (ADR-0019 Sub-fase 3) — promovido de stub experimental a versión
+ * estable con auth opt-in, caching mtime-based, telemetría JSONL y schema
+ * versioning. Mantiene compatibilidad total con clientes existentes que
+ * conectan sin auth (si `SWL_MCP_API_KEY` no está set, comportamiento idéntico
+ * al stub v0.1.x).
+ *
+ * Modo de transporte: stdio (JSON-RPC sobre stdin/stdout).
+ *
+ * Uso (cliente MCP):
+ *   - Configurar el cliente para ejecutar `node /path/to/swl-ses/bin/swl-mcp-server.js`
+ *     con stdio.
+ *   - El cwd del proceso determina baseDir (override con `SWL_MCP_BASE_DIR`).
+ *
+ * Variables opt-in (env del server):
+ *   - SWL_MCP_API_KEY      — Si set, requiere params._auth en cada tools/call.
+ *   - SWL_MCP_CACHE_TTL_MS — TTL del cache mtime-based (default 60000).
+ *   - SWL_MCP_METRICS      — Si "1" o "true", persiste metrics en
+ *                            .planning/evolucion/mcp-metrics.jsonl.
+ *
+ * Schema versioning:
+ *   - Cada handler declara `schemaVersion` en su definición.
+ *   - El cliente puede inspeccionarlo via `tools/list` (campo `_schemaVersion`).
+ *
+ * Protocolo MCP soportado (subset):
+ *   - initialize / initialized
+ *   - tools/list
+ *   - tools/call
+ *   - ping
+ */
+
+const path = require('path');
+
+const { HANDLERS } = require('../scripts/mcp-server/handlers');
+const { construirValidador } = require('../scripts/mcp-server/auth');
+const { construirTelemetria } = require('../scripts/mcp-server/telemetry');
+
+const SERVER_NAME = 'swl-mcp-server';
+const SERVER_VERSION = '1.0.0';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const baseDir = process.env.SWL_MCP_BASE_DIR || process.cwd();
+const authValidator = construirValidador();
+const telemetry = construirTelemetria({ baseDir });
+
+// ── 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,
+      authRequired: authValidator.requerida,
+      telemetryEnabled: telemetry.habilitada,
+    },
+  });
+}
+
+function manejarToolsList(request) {
+  const tools = Object.entries(HANDLERS).map(([name, def]) => ({
+    name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+    _schemaVersion: def.schemaVersion || '1.0.0',
+  }));
+  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}`);
+  }
+  const inicio = Date.now();
+  try {
+    const result = def.handler(baseDir, args || {});
+    const duracionMs = Date.now() - inicio;
+    telemetry.registrar({ tool: name, durationMs: duracionMs, ok: true, baseDir });
+    return respuesta(request.id, {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    });
+  } catch (err) {
+    const duracionMs = Date.now() - inicio;
+    log('error', `Excepción en handler ${name}`, { error: err.message });
+    telemetry.registrar({ tool: name, durationMs: duracionMs, ok: false, error: err.message, baseDir });
+    return errorResp(request.id, -32603, `Error interno: ${err.message}`);
+  }
+}
+
+/**
+ * Punto de entrada del routing — público para tests.
+ *
+ * @param {object} request - Mensaje JSON-RPC parseado.
+ * @returns {string|null} - String JSON-RPC respuesta o null (notification).
+ */
+function rutear(request) {
+  // Auth gate: si SWL_MCP_API_KEY está set, validar antes de routing.
+  const auth = authValidator.validar(request);
+  if (!auth.ok) {
+    return errorResp(request.id, auth.code, auth.message);
+  }
+
+  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('info', `${SERVER_NAME} v${SERVER_VERSION} iniciando`, {
+    baseDir,
+    authRequired: authValidator.requerida,
+    telemetryEnabled: telemetry.habilitada,
+  });
+
+  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-ses.js

@@ -336,6 +336,35 @@ function main() {
     }
   }
 
+  // ADR-0019 Sub-fase 2.5: Multi-target install/update/uninstall
+  //
+  // Si `--target=a,b,c` (CSV) o `--all-runtimes` está activo, iterar el comando
+  // por cada target. Solo aplica a comandos que aceptan `--target`. Para el resto,
+  // se pasa el comando tal cual.
+  const COMANDOS_MULTI_TARGET = ['install', 'update', 'uninstall'];
+  if (COMANDOS_MULTI_TARGET.includes(comando)) {
+    const { expandirTargets: expandir } = require('../scripts/lib/expandir-targets');
+    const expansion = expandir(opciones);
+    if (expansion.errores.length > 0) {
+      for (const e of expansion.errores) console.error(`[swl-ses] ${e}`);
+      process.exit(1);
+    }
+    const targets = expansion.targets;
+    if (targets.length > 1) {
+      ejecutarMultiTarget(comando, opciones, targets).catch(err => {
+        console.error(`Error en multi-target ${comando}: ${err.message}`);
+        if (opciones.verbose) console.error(err.stack);
+        process.exit(1);
+      });
+      return;
+    }
+    // Si targets.length === 1, ya viene normalizado y continuamos al flujo normal.
+    if (targets.length === 1) {
+      opciones.target = targets[0];
+      opciones.objetivo = targets[0];
+    }
+  }
+
   try {
     const modulo = require(COMANDOS[comando]);
     const resultado = modulo(opciones);
@@ -357,4 +386,49 @@ function main() {
   }
 }
 
+/**
+ * Ejecuta un comando (install/update/uninstall) sobre múltiples targets en serie.
+ *
+ * Atomicidad por target (ADR-0019 punto 9): si un target falla, los anteriores
+ * quedan instalados y se reporta el error sin rollback. Los targets siguientes
+ * igual se intentan — el usuario decide qué hacer después.
+ *
+ * @param {string} comando - install | update | uninstall
+ * @param {object} opcionesBase - Opciones parseadas (se clonan por target)
+ * @param {string[]} targets - Lista de target IDs ≥1
+ */
+async function ejecutarMultiTarget(comando, opcionesBase, targets) {
+  console.log(`\n[swl-ses] Multi-target ${comando}: ${targets.join(', ')}`);
+  console.log('='.repeat(60));
+
+  const resultados = [];
+  for (const t of targets) {
+    console.log(`\n[swl-ses] ▶ Target: ${t}`);
+    console.log('-'.repeat(60));
+    const opciones = { ...opcionesBase, target: t, objetivo: t };
+    try {
+      const modulo = require(COMANDOS[comando]);
+      const r = modulo(opciones);
+      if (r && typeof r.then === 'function') await r;
+      resultados.push({ target: t, ok: true });
+    } catch (err) {
+      console.error(`[swl-ses] ✘ Falló ${comando} para target "${t}": ${err.message}`);
+      if (opciones.verbose) console.error(err.stack);
+      resultados.push({ target: t, ok: false, error: err.message });
+    }
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log(`[swl-ses] Resumen multi-target ${comando}:`);
+  for (const r of resultados) {
+    const marca = r.ok ? '✓' : '✘';
+    const detalle = r.error ? ` — ${r.error}` : '';
+    console.log(`  ${marca} ${r.target}${detalle}`);
+  }
+  const fallidos = resultados.filter(r => !r.ok);
+  if (fallidos.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
 main();

package/comandos/swl/ejecutar-fase.md

@@ -4,20 +4,41 @@ description: Recibe el número de una fase y la implementa siguiendo el PLAN.md.
 allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
 ---
 
-# /swl:ejecutar-fase <n> — Ejecutar implementación de una fase
+# /swl:ejecutar-fase <n> [--iterative] — Ejecutar implementación de una fase
 
 Eres el coordinador de ejecución SWL. Orquestas la implementación real del código para una fase, delegando al agente implementador-swl, verificando cada slice y manteniendo el estado del proyecto actualizado.
 
 ## Uso
 
 ```
-/swl:ejecutar-fase 1
-/swl:ejecutar-fase 2
+/swl:ejecutar-fase 1                # modo default — oleadas paralelas
+/swl:ejecutar-fase 2 --iterative    # modo iterativo — 1 tarea, review per-task, auto-debug
 ```
 
+### Cuándo usar `--iterative` (modo opt-in)
+
+Activar el flag `--iterative` cuando:
+
+- La fase tiene **dependencias secuenciales fuertes** entre tareas.
+- El módulo es **crítico** (dinero, permisos, datos irreversibles) y cada tarea merece revisión adversarial inmediata.
+- La fase tiene **>12 tareas** y el modo paralelo arriesga acumular deuda silenciosa.
+- El usuario pide explícitamente "tarea por tarea con revisión".
+
+NO usar `--iterative` para fases pequeñas (<5 tareas) o cuando las tareas son
+independientes y de bajo riesgo — el overhead per-task supera el beneficio.
+
 ## Paso 0 — Carga de habilidades
 
-Carga obligatoria:
+Si `--iterative` está presente, carga:
+```
+Skill("ejecutar-task-iterativo")
+```
+
+El skill iterativo redirige el flujo: 1 tarea por iteración, contexto fresco
+por implementer, review task-local con `protocolo-revision-swl`, auto-debug
+en BLOCKED con `depurador-swl`, y commits atómicos estrictos por tarea.
+
+Si NO hay `--iterative`, carga el flujo default:
 ```
 Skill("ejecutar-fase")
 ```
@@ -31,6 +52,14 @@ Luego carga habilidades específicas del stack detectado en PLAN.md o PROYECTO.m
 - Autenticación: `Skill("auth-patrones")`
 - Siempre: `Skill("manejo-errores")`
 
+### Si `--iterative` está activo
+
+Tras cargar `ejecutar-task-iterativo`, sigue el protocolo definido ahí
+(loop per-task con Pasos 1-8 internos del skill). El resto de pasos de
+este comando se delegan al skill iterativo. Saltar los Pasos 2-7 de este
+comando. El Paso 8 (Reporte final) y Reglas de comportamiento siguen
+aplicando en ambos modos.
+
 ## Paso 1 — Verificación de prerrequisitos
 
 Verifica en orden:

package/comandos/swl/metricas.md

@@ -21,6 +21,7 @@ costo estimado, herramientas más usadas y estado del presupuesto configurado.
 ```
 /swl:metricas             — Resumen de métricas de la sesión
 /swl:metricas detalle     — Desglose completo por herramienta y timeline
+/swl:metricas fases       — Progreso de fases del proyecto desde feature-list.json
 /swl:metricas historico   — Abre el dashboard histórico multi-sesión (alias de /swl:dashboard)
 ```
 
@@ -246,6 +247,77 @@ EOF
 
 ---
 
+## Subcomando: `fases` — Progreso de fases del proyecto
+
+Si el usuario invoca `/swl:metricas fases`, muestra el estado actual de las
+fases del proyecto leyendo el JSON derivado de `HOJA-RUTA.md`.
+
+### Generación y lectura del estado
+
+```bash
+# Regenerar el JSON desde HOJA-RUTA.md (fuente de verdad markdown)
+node scripts/derivar-feature-list.js
+
+# Leer el JSON generado en .planning/feature-list.json
+cat .planning/feature-list.json | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+t = data['totales']
+total = t['fases'] or 1
+pct = (t['completadas'] / total) * 100
+
+print(f\"\\nSWL — Progreso de fases del proyecto\")
+print('─' * 60)
+print(f\"  Total de fases:        {t['fases']}\")
+print(f\"  Completadas:           {t['completadas']}  ({pct:.0f}%)\")
+print(f\"  En progreso:           {t['en_progreso']}\")
+print(f\"  Pendientes:            {t['pendientes']}\")
+print(f\"  Bloqueadas:            {t['bloqueadas']}\")
+print(f\"  Spec lista:            {t['spec_listas']}\")
+print('─' * 60)
+print()
+for f in data['fases']:
+    estado = f['estado']
+    marca = {'completado': '✓', 'en_progreso': '◐', 'pendiente': '○',
+             'bloqueado': '✗', 'spec_listo': '◔'}.get(estado, '?')
+    nombre = f['nombre'][:48]
+    art = f.get('artefactos') or {}
+    plan = ' [PLAN]' if art.get('plan_md') else ''
+    resumen = ' [RESUMEN]' if art.get('resumen_md') else ''
+    print(f\"  {marca} Fase {f['numero']:>2}: {nombre:<50}{plan}{resumen}\")
+print()
+print(f\"  Fuente: {data['fuente']}  ·  Generado: {data['generado_en']}\")
+"
+```
+
+### Lo que se reporta
+
+- **Totales**: cuántas fases hay y cuántas en cada estado canónico (`completado`,
+  `en_progreso`, `pendiente`, `bloqueado`, `spec_listo`).
+- **Lista de fases** con marca visual de estado y artefactos presentes
+  (`[PLAN]` si existe `0N-PLAN.md`, `[RESUMEN]` si existe `0N-RESUMEN.md`).
+- **Timestamp** de generación para detectar staleness.
+
+### Cuándo usar
+
+- Antes de retomar trabajo en una fase, para ver el estado actualizado.
+- Al cerrar una sesión productiva, para verificar progreso vs HOJA-RUTA.md.
+- Para auditoría programática (consumir el JSON desde un hook o dashboard externo).
+
+### Detección de drift
+
+Si `HOJA-RUTA.md` se modifica pero `feature-list.json` no se regenera, los datos
+quedan desactualizados. Para verificar:
+
+```bash
+node scripts/derivar-feature-list.js --check
+# exit 0 = sincronizado, exit 2 = drift detectado
+```
+
+`/swl:metricas fases` siempre regenera primero, así que ve estado fresco.
+
+---
+
 ## Subcomando: `historico`
 
 Si el usuario invoca `/swl:metricas historico`, redirigir inmediatamente a: