@saulwade/swl-ses 1.3.7 → 1.4.0

package/scripts/limpiar-artefactos-python.js

@@ -1,131 +1,131 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * limpiar-artefactos-python.js — limpia caché Python antes de empaquetar.
- *
- * Se ejecuta como `prepack` antes de `npm pack` y `npm publish` para evitar
- * que artefactos locales (.pyc, __pycache__/) contaminen el tarball publicado.
- *
- * Reglas de seguridad (defensa en profundidad):
- *   1. Aborta si cwd no coincide con la raíz del package.json del repo.
- *   2. Profundidad máxima de recursión: 3 niveles desde la raíz.
- *   3. Allowlist explícita de directorios a EXCLUIR de la búsqueda
- *      (node_modules, .git, temp, .planning, respositorios-git, _userland).
- *   4. Solo elimina directorios cuyo nombre coincide exactamente con el
- *      conjunto cerrado: __pycache__, .pytest_cache, .mypy_cache, .ruff_cache.
- *   5. Solo elimina archivos sueltos con extensiones .pyc, .pyo.
- *   6. En CI no-interactivo respeta el flag SWL_PREPACK_DRY=1 (no borra,
- *      solo lista).
- *
- * Exit codes:
- *   0 — OK (limpieza ejecutada o nada que limpiar)
- *   1 — error de invariante (cwd incorrecto, package.json no encontrado)
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-const { NOMBRES_VALIDOS } = require('./lib/paquetes-conocidos');
-const {
-  DIRS_ARTEFACTOS_PYTHON: DIRS_A_LIMPIAR,
-  EXTS_ARTEFACTOS_PYTHON: EXTS_A_LIMPIAR,
-} = require('./lib/artefactos-python');
-
-const PROFUNDIDAD_MAX = 3;
-const DIRS_EXCLUIDOS  = new Set([
-  'node_modules', '.git', 'temp', '.planning', 'respositorios-git',
-  '_userland', 'tests', '.github',
-]);
-
-const dryRun = process.env.SWL_PREPACK_DRY === '1';
-
-function log(msg) { process.stdout.write(`[prepack] ${msg}\n`); }
-function err(msg) { process.stderr.write(`[prepack] ERROR: ${msg}\n`); }
-
-/**
- * Verifica que el cwd actual contiene el package.json del repo swl-ses.
- * Esto evita que el script borre directorios en la máquina del usuario si
- * algún día se invocara desde un cwd incorrecto (ej. dentro de un tarball
- * extraído por npm en .npm/_cacache).
- */
-function verificarRaiz() {
-  const cwd = process.cwd();
-  const pkgPath = path.join(cwd, 'package.json');
-  if (!fs.existsSync(pkgPath)) {
-    err(`no existe package.json en cwd: ${cwd}`);
-    process.exit(1);
-  }
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  if (!NOMBRES_VALIDOS.includes(pkg.name)) {
-    err(`package.json en ${cwd} no corresponde a swl-ses (name: ${pkg.name}). Abortando por seguridad.`);
-    process.exit(1);
-  }
-  return cwd;
-}
-
-/**
- * Recorre el árbol desde root con profundidad limitada y elimina los
- * artefactos Python detectados. No sigue symlinks.
- */
-function limpiar(root, profundidad = 0) {
-  if (profundidad > PROFUNDIDAD_MAX) return { dirs: 0, files: 0 };
-
-  let dirsEliminados = 0;
-  let filesEliminados = 0;
-
-  let entries;
-  try {
-    entries = fs.readdirSync(root, { withFileTypes: true });
-  } catch (e) {
-    err(`no se pudo leer ${root}: ${e.message}`);
-    return { dirs: 0, files: 0 };
-  }
-
-  for (const entry of entries) {
-    if (entry.isSymbolicLink()) continue;
-    const fullPath = path.join(root, entry.name);
-
-    if (entry.isDirectory()) {
-      if (DIRS_A_LIMPIAR.has(entry.name)) {
-        if (dryRun) {
-          log(`[dry-run] borraría dir: ${path.relative(process.cwd(), fullPath)}`);
-        } else {
-          fs.rmSync(fullPath, { recursive: true, force: true });
-          log(`borrado dir: ${path.relative(process.cwd(), fullPath)}`);
-        }
-        dirsEliminados++;
-      } else if (!DIRS_EXCLUIDOS.has(entry.name) && !entry.name.startsWith('.')) {
-        const sub = limpiar(fullPath, profundidad + 1);
-        dirsEliminados  += sub.dirs;
-        filesEliminados += sub.files;
-      }
-    } else if (entry.isFile()) {
-      const ext = path.extname(entry.name).toLowerCase();
-      if (EXTS_A_LIMPIAR.has(ext)) {
-        if (dryRun) {
-          log(`[dry-run] borraría archivo: ${path.relative(process.cwd(), fullPath)}`);
-        } else {
-          fs.rmSync(fullPath, { force: true });
-        }
-        filesEliminados++;
-      }
-    }
-  }
-
-  return { dirs: dirsEliminados, files: filesEliminados };
-}
-
-function main() {
-  const root = verificarRaiz();
-  const result = limpiar(root);
-
-  if (result.dirs === 0 && result.files === 0) {
-    log('sin artefactos Python que limpiar.');
-  } else {
-    const accion = dryRun ? 'detectados' : 'eliminados';
-    log(`${accion}: ${result.dirs} directorios + ${result.files} archivos.`);
-  }
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * limpiar-artefactos-python.js — limpia caché Python antes de empaquetar.
+ *
+ * Se ejecuta como `prepack` antes de `npm pack` y `npm publish` para evitar
+ * que artefactos locales (.pyc, __pycache__/) contaminen el tarball publicado.
+ *
+ * Reglas de seguridad (defensa en profundidad):
+ *   1. Aborta si cwd no coincide con la raíz del package.json del repo.
+ *   2. Profundidad máxima de recursión: 3 niveles desde la raíz.
+ *   3. Allowlist explícita de directorios a EXCLUIR de la búsqueda
+ *      (node_modules, .git, temp, .planning, respositorios-git, _userland).
+ *   4. Solo elimina directorios cuyo nombre coincide exactamente con el
+ *      conjunto cerrado: __pycache__, .pytest_cache, .mypy_cache, .ruff_cache.
+ *   5. Solo elimina archivos sueltos con extensiones .pyc, .pyo.
+ *   6. En CI no-interactivo respeta el flag SWL_PREPACK_DRY=1 (no borra,
+ *      solo lista).
+ *
+ * Exit codes:
+ *   0 — OK (limpieza ejecutada o nada que limpiar)
+ *   1 — error de invariante (cwd incorrecto, package.json no encontrado)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { NOMBRES_VALIDOS } = require('./lib/paquetes-conocidos');
+const {
+  DIRS_ARTEFACTOS_PYTHON: DIRS_A_LIMPIAR,
+  EXTS_ARTEFACTOS_PYTHON: EXTS_A_LIMPIAR,
+} = require('./lib/artefactos-python');
+
+const PROFUNDIDAD_MAX = 3;
+const DIRS_EXCLUIDOS  = new Set([
+  'node_modules', '.git', 'temp', '.planning', 'respositorios-git',
+  '_userland', 'tests', '.github',
+]);
+
+const dryRun = process.env.SWL_PREPACK_DRY === '1';
+
+function log(msg) { process.stdout.write(`[prepack] ${msg}\n`); }
+function err(msg) { process.stderr.write(`[prepack] ERROR: ${msg}\n`); }
+
+/**
+ * Verifica que el cwd actual contiene el package.json del repo swl-ses.
+ * Esto evita que el script borre directorios en la máquina del usuario si
+ * algún día se invocara desde un cwd incorrecto (ej. dentro de un tarball
+ * extraído por npm en .npm/_cacache).
+ */
+function verificarRaiz() {
+  const cwd = process.cwd();
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    err(`no existe package.json en cwd: ${cwd}`);
+    process.exit(1);
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  if (!NOMBRES_VALIDOS.includes(pkg.name)) {
+    err(`package.json en ${cwd} no corresponde a swl-ses (name: ${pkg.name}). Abortando por seguridad.`);
+    process.exit(1);
+  }
+  return cwd;
+}
+
+/**
+ * Recorre el árbol desde root con profundidad limitada y elimina los
+ * artefactos Python detectados. No sigue symlinks.
+ */
+function limpiar(root, profundidad = 0) {
+  if (profundidad > PROFUNDIDAD_MAX) return { dirs: 0, files: 0 };
+
+  let dirsEliminados = 0;
+  let filesEliminados = 0;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch (e) {
+    err(`no se pudo leer ${root}: ${e.message}`);
+    return { dirs: 0, files: 0 };
+  }
+
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    const fullPath = path.join(root, entry.name);
+
+    if (entry.isDirectory()) {
+      if (DIRS_A_LIMPIAR.has(entry.name)) {
+        if (dryRun) {
+          log(`[dry-run] borraría dir: ${path.relative(process.cwd(), fullPath)}`);
+        } else {
+          fs.rmSync(fullPath, { recursive: true, force: true });
+          log(`borrado dir: ${path.relative(process.cwd(), fullPath)}`);
+        }
+        dirsEliminados++;
+      } else if (!DIRS_EXCLUIDOS.has(entry.name) && !entry.name.startsWith('.')) {
+        const sub = limpiar(fullPath, profundidad + 1);
+        dirsEliminados  += sub.dirs;
+        filesEliminados += sub.files;
+      }
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (EXTS_A_LIMPIAR.has(ext)) {
+        if (dryRun) {
+          log(`[dry-run] borraría archivo: ${path.relative(process.cwd(), fullPath)}`);
+        } else {
+          fs.rmSync(fullPath, { force: true });
+        }
+        filesEliminados++;
+      }
+    }
+  }
+
+  return { dirs: dirsEliminados, files: filesEliminados };
+}
+
+function main() {
+  const root = verificarRaiz();
+  const result = limpiar(root);
+
+  if (result.dirs === 0 && result.files === 0) {
+    log('sin artefactos Python que limpiar.');
+  } else {
+    const accion = dryRun ? 'detectados' : 'eliminados';
+    log(`${accion}: ${result.dirs} directorios + ${result.files} archivos.`);
+  }
+}
+
+main();

package/scripts/mcp-server/README.md

@@ -1,128 +1,128 @@
-# swl-mcp-server — STUB EXPERIMENTAL
-
-> ⚠ **NO USAR EN PRODUCCIÓN**. Este es un stub experimental que demuestra
-> el patrón de exponer la memoria de swl-ses a clientes MCP externos. La
-> implementación completa requiere trabajo adicional (auth, observabilidad,
-> tests de integración, schema migration). Ver sección "Limitaciones" más
-> abajo.
-
-## Qué hace
-
-`bin/swl-mcp-server.js` es un servidor MCP en modo stdio que expone 3
-endpoints de solo lectura:
-
-1. **`swl_memory_search`** — búsqueda hybrid sobre memoria SWL
-   (aprendizajes + sesiones + instintos) usando `hooks/lib/memory-search`
-   con RRF fusion.
-2. **`swl_aprendizajes_recientes`** — últimos N aprendizajes de
-   `.planning/APRENDIZAJES.md`.
-3. **`swl_instintos_activos`** — instintos con `effective_confidence ≥
-   umbral`.
-
-El server lee el estado file-based de swl-ses tal como existe en `cwd`
-(o el directorio especificado por `SWL_MCP_BASE_DIR`). NO escribe — solo
-lectura.
-
-## Cómo arrancar (para testing)
-
-```bash
-# Modo standalone (smoke test)
-echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node bin/swl-mcp-server.js
-
-# Output esperado en stdout:
-# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"swl-mcp-server","version":"0.1.0-experimental"}}}
-
-# Listar herramientas
-echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node bin/swl-mcp-server.js
-
-# Buscar memoria
-echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"swl_memory_search","arguments":{"query":"RRF fusion","limit":3}}}' | node bin/swl-mcp-server.js
-```
-
-## Cómo configurar en clientes MCP (NO recomendado en producción)
-
-### Cursor (~/.cursor/mcp.json)
-
-```json
-{
-  "mcpServers": {
-    "swl-memory": {
-      "command": "node",
-      "args": ["/ruta/absoluta/a/swl-ses/bin/swl-mcp-server.js"],
-      "env": {
-        "SWL_MCP_BASE_DIR": "/ruta/al/proyecto/que/quiero/recuperar"
-      }
-    }
-  }
-}
-```
-
-### Gemini CLI
-
-Similar, agregando el server a la config del cliente que soporte MCP stdio.
-
-### Claude Code (NO necesario)
-
-Claude Code ya tiene acceso directo a los archivos de swl-ses dentro de
-su propio runtime. NO usar el MCP server desde Claude Code en el mismo
-proyecto — sería redundante y agregaría latencia.
-
-## Limitaciones (lo que NO se hace en este stub)
-
-| Limitación | Impacto | Cuándo se debe arreglar |
-|---|---|---|
-| **Sin auth** | Cualquier proceso con acceso al stdio puede leer toda la memoria | Antes de exponer en redes públicas o multi-usuario |
-| **Sin rate limiting** | Cliente malicioso/buggy puede saturar lectura de archivos | Cuando se observen ≥1 incidentes de saturación |
-| **Sin HTTP transport** | Solo stdio; no se puede conectar remotamente | Cuando el caso de uso requiera servidor de red |
-| **Sin tests de integración** | Solo smoke tests manuales | Antes de v1.0 del MCP server |
-| **Sin observabilidad / métricas** | Logs JSON a stderr son lo único que hay | Cuando se use en >1 cliente simultáneo |
-| **Sin hot-reload** | Cambios en swl-ses no se reflejan hasta restart del server | Ya — el server lee files en cada call, así que SÍ se reflejan; documentado por completitud |
-| **Sin caching** | Cada call lee files de disco | Cuando latencia sea problema (~10ms hoy) |
-| **Sin schema versioning** | Si cambia formato de APRENDIZAJES.md, los handlers pueden romper | Cuando se introduzca breaking change en el formato |
-| **Sin support de resources/prompts** | Solo tools | Cuando el caso de uso lo demande |
-| **Sin paginación** | Resultados grandes se truncan a `limit` | Cuando se requiera browse de >50 entries |
-| **Single-tenant** | Asume un solo proyecto por instancia | Multi-tenancy necesita rediseño |
-
-## Trigger para implementación completa
-
-**Hoy**: 0 instalaciones reportadas. Mantener como stub.
-
-**Trigger para invertir esfuerzo en implementación robusta**: el usuario
-reporta uso real consistente de ≥2 runtimes distintos (Cursor + Claude
-Code, o Gemini + Claude Code, etc.) sobre el mismo proyecto SWL durante
-≥1 mes. Sin esto, la inversión de ~25 horas en hardening del server
-no se justifica.
-
-## Diseño futuro (cuando se implemente completo)
-
-1. **Auth**: API key estática + bearer token con scopes:
-   - `swl:memory:read` (búsqueda y lectura)
-   - `swl:memory:write` (crear aprendizajes desde MCP — requiere validación)
-   - `swl:instintos:write` (modificar confidence — alto riesgo)
-2. **HTTP transport opcional**: además de stdio, ofrecer servidor HTTP/SSE
-   con TLS y CORS configurable.
-3. **Telemetría**: requests por handler, latencia p50/p95, errores por
-   tipo. Persistir en `.planning/evolucion/mcp-metrics.jsonl`.
-4. **Caching invalidable**: caché en memoria de las lecturas de
-   APRENDIZAJES.md / instintos con `mtime`-based invalidation.
-5. **Schema versioning**: cada handler declara `schema_version`. El
-   cliente puede pedir un version range. Breaking changes bumpan major.
-6. **Tests de integración**: arrancar el server contra una fixture y
-   ejecutar 50+ scenarios. Smoke en CI.
-
-## Estado de seguridad (auditoría rápida del stub)
-
-- ✓ NO expone credenciales ni archivos fuera de `baseDir`.
-- ✓ NO ejecuta código (solo lee files y devuelve JSON).
-- ✓ NO modifica archivos.
-- ✗ NO valida que `baseDir` sea un proyecto SWL válido — un cliente
-  podría apuntarlo a un directorio arbitrario y leer cualquier
-  archivo `*.md` que llamemos `APRENDIZAJES.md`.
-- ✗ NO sanitiza queries de búsqueda (los regex en `instintos.yaml` parser
-  son seguros, pero falta hardening).
-- ✗ NO hay timeout — un proyecto enorme con miles de sesiones podría
-  hacer colgar el server.
-
-Estos puntos son ACEPTABLES para un stub experimental usado por el
-mantenedor en un proyecto propio. NO ACEPTABLES para uso multi-usuario
-o expuesto a la red.
+# swl-mcp-server — STUB EXPERIMENTAL
+
+> ⚠ **NO USAR EN PRODUCCIÓN**. Este es un stub experimental que demuestra
+> el patrón de exponer la memoria de swl-ses a clientes MCP externos. La
+> implementación completa requiere trabajo adicional (auth, observabilidad,
+> tests de integración, schema migration). Ver sección "Limitaciones" más
+> abajo.
+
+## Qué hace
+
+`bin/swl-mcp-server.js` es un servidor MCP en modo stdio que expone 3
+endpoints de solo lectura:
+
+1. **`swl_memory_search`** — búsqueda hybrid sobre memoria SWL
+   (aprendizajes + sesiones + instintos) usando `hooks/lib/memory-search`
+   con RRF fusion.
+2. **`swl_aprendizajes_recientes`** — últimos N aprendizajes de
+   `.planning/APRENDIZAJES.md`.
+3. **`swl_instintos_activos`** — instintos con `effective_confidence ≥
+   umbral`.
+
+El server lee el estado file-based de swl-ses tal como existe en `cwd`
+(o el directorio especificado por `SWL_MCP_BASE_DIR`). NO escribe — solo
+lectura.
+
+## Cómo arrancar (para testing)
+
+```bash
+# Modo standalone (smoke test)
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node bin/swl-mcp-server.js
+
+# Output esperado en stdout:
+# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"swl-mcp-server","version":"0.1.0-experimental"}}}
+
+# Listar herramientas
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node bin/swl-mcp-server.js
+
+# Buscar memoria
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"swl_memory_search","arguments":{"query":"RRF fusion","limit":3}}}' | node bin/swl-mcp-server.js
+```
+
+## Cómo configurar en clientes MCP (NO recomendado en producción)
+
+### Cursor (~/.cursor/mcp.json)
+
+```json
+{
+  "mcpServers": {
+    "swl-memory": {
+      "command": "node",
+      "args": ["/ruta/absoluta/a/swl-ses/bin/swl-mcp-server.js"],
+      "env": {
+        "SWL_MCP_BASE_DIR": "/ruta/al/proyecto/que/quiero/recuperar"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Similar, agregando el server a la config del cliente que soporte MCP stdio.
+
+### Claude Code (NO necesario)
+
+Claude Code ya tiene acceso directo a los archivos de swl-ses dentro de
+su propio runtime. NO usar el MCP server desde Claude Code en el mismo
+proyecto — sería redundante y agregaría latencia.
+
+## Limitaciones (lo que NO se hace en este stub)
+
+| Limitación | Impacto | Cuándo se debe arreglar |
+|---|---|---|
+| **Sin auth** | Cualquier proceso con acceso al stdio puede leer toda la memoria | Antes de exponer en redes públicas o multi-usuario |
+| **Sin rate limiting** | Cliente malicioso/buggy puede saturar lectura de archivos | Cuando se observen ≥1 incidentes de saturación |
+| **Sin HTTP transport** | Solo stdio; no se puede conectar remotamente | Cuando el caso de uso requiera servidor de red |
+| **Sin tests de integración** | Solo smoke tests manuales | Antes de v1.0 del MCP server |
+| **Sin observabilidad / métricas** | Logs JSON a stderr son lo único que hay | Cuando se use en >1 cliente simultáneo |
+| **Sin hot-reload** | Cambios en swl-ses no se reflejan hasta restart del server | Ya — el server lee files en cada call, así que SÍ se reflejan; documentado por completitud |
+| **Sin caching** | Cada call lee files de disco | Cuando latencia sea problema (~10ms hoy) |
+| **Sin schema versioning** | Si cambia formato de APRENDIZAJES.md, los handlers pueden romper | Cuando se introduzca breaking change en el formato |
+| **Sin support de resources/prompts** | Solo tools | Cuando el caso de uso lo demande |
+| **Sin paginación** | Resultados grandes se truncan a `limit` | Cuando se requiera browse de >50 entries |
+| **Single-tenant** | Asume un solo proyecto por instancia | Multi-tenancy necesita rediseño |
+
+## Trigger para implementación completa
+
+**Hoy**: 0 instalaciones reportadas. Mantener como stub.
+
+**Trigger para invertir esfuerzo en implementación robusta**: el usuario
+reporta uso real consistente de ≥2 runtimes distintos (Cursor + Claude
+Code, o Gemini + Claude Code, etc.) sobre el mismo proyecto SWL durante
+≥1 mes. Sin esto, la inversión de ~25 horas en hardening del server
+no se justifica.
+
+## Diseño futuro (cuando se implemente completo)
+
+1. **Auth**: API key estática + bearer token con scopes:
+   - `swl:memory:read` (búsqueda y lectura)
+   - `swl:memory:write` (crear aprendizajes desde MCP — requiere validación)
+   - `swl:instintos:write` (modificar confidence — alto riesgo)
+2. **HTTP transport opcional**: además de stdio, ofrecer servidor HTTP/SSE
+   con TLS y CORS configurable.
+3. **Telemetría**: requests por handler, latencia p50/p95, errores por
+   tipo. Persistir en `.planning/evolucion/mcp-metrics.jsonl`.
+4. **Caching invalidable**: caché en memoria de las lecturas de
+   APRENDIZAJES.md / instintos con `mtime`-based invalidation.
+5. **Schema versioning**: cada handler declara `schema_version`. El
+   cliente puede pedir un version range. Breaking changes bumpan major.
+6. **Tests de integración**: arrancar el server contra una fixture y
+   ejecutar 50+ scenarios. Smoke en CI.
+
+## Estado de seguridad (auditoría rápida del stub)
+
+- ✓ NO expone credenciales ni archivos fuera de `baseDir`.
+- ✓ NO ejecuta código (solo lee files y devuelve JSON).
+- ✓ NO modifica archivos.
+- ✗ NO valida que `baseDir` sea un proyecto SWL válido — un cliente
+  podría apuntarlo a un directorio arbitrario y leer cualquier
+  archivo `*.md` que llamemos `APRENDIZAJES.md`.
+- ✗ NO sanitiza queries de búsqueda (los regex en `instintos.yaml` parser
+  son seguros, pero falta hardening).
+- ✗ NO hay timeout — un proyecto enorme con miles de sesiones podría
+  hacer colgar el server.
+
+Estos puntos son ACEPTABLES para un stub experimental usado por el
+mantenedor en un proyecto propio. NO ACEPTABLES para uso multi-usuario
+o expuesto a la red.