@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/lib/transformadores/cursor.js

@@ -0,0 +1,359 @@
+'use strict';
+
+/**
+ * Transformador para Cursor.
+ *
+ * Cursor consume (formato confirmado vía docs oficiales el 2026-05-15):
+ *   - `.cursor/agents/<name>.md` con frontmatter YAML compatible con Claude:
+ *       name, description, model (default "inherit"), readonly, is_background
+ *     Cursor también acepta `.claude/agents/` y `.codex/agents/` como legacy.
+ *     Origen: https://cursor.com/es/docs/subagents
+ *
+ *   - `.cursor/skills/<name>/SKILL.md` (mismo formato que Claude Code skills):
+ *     directorio con SKILL.md + scripts/ + references/ + assets/ opcionales.
+ *     Frontmatter: name, description, paths (opcional), disable-model-invocation.
+ *     Cursor también acepta `.agents/skills/`, `.claude/skills/` y `.codex/skills/`.
+ *     Origen: https://cursor.com/es/docs/skills
+ *
+ *   - `.cursor/rules/*.mdc` con frontmatter YAML:
+ *       description, alwaysApply, globs (opcional).
+ *
+ *   - `.cursor/mcp.json` o `~/.cursor/mcp.json` con:
+ *       { "mcpServers": { "<nombre>": { "command": "...", "args": [...], "env": {...} } } }
+ *
+ * Cursor NO soporta nativamente desde filesystem:
+ *  - Comandos slash custom (descartados — fuera de scope).
+ *  - Hooks (PreToolUse, PostToolUse, etc.).
+ *
+ * Side effect: si `contexto.withMcp`, escribe `.cursor/mcp.json` con `swl-memory`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const TransformadorBase = require('./base');
+const { atomicWriteSync } = require('../../../hooks/lib/atomic-write');
+
+const MAX_DESCRIPTION_LEN = 200;
+
+class TransformadorCursor extends TransformadorBase {
+  transformarAgente(contenidoMd, metadatos) {
+    // Cursor lee agentes desde .cursor/agents/<name>.md (Sub-fase 7 v1.5.0).
+    // El frontmatter Claude es subset del soportado por Cursor — pasamos el
+    // archivo tal cual normalizando solo los campos que Cursor reconoce.
+    const { frontmatter, cuerpo } = this.parsearFrontmatter(contenidoMd);
+
+    const fmCursor = {};
+    if (frontmatter.name) fmCursor.name = frontmatter.name;
+    if (frontmatter.description) fmCursor.description = frontmatter.description;
+    // Cursor admite `model: inherit` para heredar del padre. Si el agente SWL
+    // declara modelo, lo mantenemos; si no, default a inherit.
+    fmCursor.model = frontmatter.model || 'inherit';
+    // Mapeo conservador: si el agente declara `permisosEscritura: false` en SWL,
+    // se propaga como `readonly: true` en Cursor.
+    if (frontmatter.permisosEscritura === false || frontmatter.readonly === true) {
+      fmCursor.readonly = true;
+    }
+    if (frontmatter.is_background === true) {
+      fmCursor.is_background = true;
+    }
+
+    return {
+      contenido: this.construirMarkdown(fmCursor, cuerpo),
+      rutaRelativa: `agents/${metadatos.nombreArchivo}`,
+    };
+  }
+
+  transformarSkill(dirSkill, metadatos) {
+    // Cursor carga skills desde .cursor/skills/<name>/SKILL.md (Sub-fase 7 v1.5.0).
+    // Mismo formato que Claude Code skills — pasar el directorio completo.
+    return {
+      tipo: 'directorio',
+      rutaRelativa: `skills/${metadatos.nombreDirectorio}`,
+    };
+  }
+
+  transformarRegla(contenidoMd, metadatos) {
+    const { frontmatter, cuerpo } = this.parsearFrontmatter(contenidoMd);
+
+    // Derivar descripción para el .mdc (Cursor la lee del frontmatter)
+    // Priorizar el `description:` si existe, si no, usar el name, si no, el nombre del archivo.
+    let descripcion = frontmatter.description || frontmatter.name || metadatos.nombreArchivo || 'Regla SWL';
+    descripcion = String(descripcion).replace(/\s+/g, ' ').trim();
+    if (descripcion.length > MAX_DESCRIPTION_LEN) {
+      descripcion = descripcion.slice(0, MAX_DESCRIPTION_LEN - 3) + '...';
+    }
+
+    // alwaysApply: las reglas SWL son políticas obligatorias → true por default.
+    // Si el frontmatter declara `globs`, los propagamos.
+    const globs = Array.isArray(frontmatter.globs) ? frontmatter.globs : null;
+    const alwaysApply = globs ? false : true;
+
+    const fm = { description: descripcion, alwaysApply };
+    if (globs) fm.globs = globs;
+
+    // .mdc usa el MISMO formato Markdown que .md, solo cambia el reconocimiento
+    // por parte de Cursor. Pasamos el cuerpo tal cual (regla SWL completa).
+    const contenido = this.construirMdc(fm, cuerpo);
+
+    // Cambiar extensión .md → .mdc
+    const baseNombre = (metadatos.nombreArchivo || 'regla.md').replace(/\.md$/i, '');
+    return {
+      contenido,
+      rutaRelativa: `rules/${baseNombre}.mdc`,
+    };
+  }
+
+  transformarComando(contenidoMd, metadatos) {
+    // Cursor no soporta comandos slash custom — descartar
+    return null;
+  }
+
+  /**
+   * Genera un archivo principal consolidado de agentes en .cursor/rules/swl-agentes.mdc.
+   * Es el equivalente a generarArchivoInstrucciones de otros targets, pero se enmascara
+   * como una "regla SWL" para que Cursor lo cargue siempre.
+   *
+   * @param {object} contexto
+   * @param {string} contexto.version
+   * @param {string} contexto.perfil
+   * @param {Array} contexto.agentes
+   * @param {Array} contexto.skills (solo para tabla referencial)
+   * @param {boolean} [contexto.esGlobal]
+   * @param {string} [contexto.dirRuntimeGlobal]
+   * @param {boolean} [contexto.withMcp]
+   * @param {string} [contexto.swlBinPath]
+   * @returns {object} Metadata de escritura
+   */
+  generarArchivoInstrucciones(contexto) {
+    const lineas = [];
+    const fecha = new Date().toISOString().split('T')[0];
+
+    lineas.push('# Sistema SWL — agentes y referencia operativa (Cursor)');
+    lineas.push('');
+    lineas.push(`> Generado por swl-ses v${contexto.version} — ${fecha}`);
+    lineas.push(`> Perfil: \`${contexto.perfil || 'default'}\`. Scope: \`${contexto.esGlobal ? 'global (~/.cursor/)' : 'proyecto'}\`.`);
+    lineas.push(`> Regenerar con: \`npx @saulwade/swl-ses@latest install --target cursor${contexto.esGlobal ? ' --global' : ''} --force\`.`);
+    lineas.push('');
+
+    lineas.push('## Reglas de máxima prioridad');
+    lineas.push('');
+    lineas.push('1. **Idioma: español de México** — respuestas, comentarios, commits, docs.');
+    lineas.push('2. **Investigar antes de editar** — leer el archivo completo antes de modificar.');
+    lineas.push('3. **Memoria SWL accesible vía MCP** — usar `swl-memory` (server MCP) si está configurado para consultar aprendizajes, sesiones e instintos del proyecto.');
+    lineas.push('');
+
+    if (contexto.agentes && contexto.agentes.length > 0) {
+      lineas.push('## Agentes disponibles (referencia conceptual)');
+      lineas.push('');
+      lineas.push(`> Total: ${contexto.agentes.length} agentes. Cursor no carga agentes desde filesystem; esta tabla documenta qué rol invocar conceptualmente al pedir tareas.`);
+      lineas.push('');
+      lineas.push('| Agente | Descripción |');
+      lineas.push('|--------|-------------|');
+      for (const ag of contexto.agentes) {
+        const { frontmatter } = this.parsearFrontmatter(ag.contenido || '');
+        const nombre = frontmatter.name || ag.nombre || 'sin-nombre';
+        const desc = String(frontmatter.description || '').replace(/\|/g, '\\|');
+        const descCorta = desc.length > 100 ? desc.slice(0, 97) + '...' : desc;
+        lineas.push(`| \`${nombre}\` | ${descCorta} |`);
+      }
+      lineas.push('');
+    }
+
+    if (contexto.skills && contexto.skills.length > 0) {
+      lineas.push('## Skills (acceso vía MCP swl-memory)');
+      lineas.push('');
+      lineas.push(`> Total: ${contexto.skills.length} skills. Cursor no carga skills desde filesystem. Si \`swl-memory\` está activo, usa las tools del MCP para invocar conocimiento operacional.`);
+      lineas.push('');
+    }
+
+    lineas.push('## Memoria SWL (MCP)');
+    lineas.push('');
+    if (contexto.withMcp) {
+      lineas.push('El servidor `swl-memory` está configurado en `.cursor/mcp.json`. Cursor lo expone con las tools:');
+      lineas.push('');
+      lineas.push('- `swl_memory_search` — búsqueda híbrida en memoria SWL.');
+      lineas.push('- `swl_aprendizajes_recientes` — últimos aprendizajes del proyecto.');
+      lineas.push('- `swl_instintos_activos` — patrones validados.');
+      lineas.push('');
+      lineas.push('Verificar en Cursor: Settings → Features → MCP debería listar `swl-memory` conectado.');
+    } else {
+      lineas.push('Para habilitar la memoria SWL en Cursor:');
+      lineas.push('');
+      lineas.push('```bash');
+      lineas.push(`npx @saulwade/swl-ses@latest install --target cursor${contexto.esGlobal ? ' --global' : ''} --with-mcp --force`);
+      lineas.push('```');
+    }
+    lineas.push('');
+
+    // Side effect: si withMcp, escribir mcp.json
+    if (contexto.withMcp) {
+      this._escribirMcpJson(contexto);
+    }
+
+    const cuerpo = lineas.join('\n');
+    const fm = {
+      description: 'Sistema SWL — agentes, reglas obligatorias y memoria MCP para Cursor',
+      alwaysApply: true,
+    };
+    const contenido = this.construirMdc(fm, cuerpo);
+
+    const dirBase = contexto.esGlobal && contexto.dirRuntimeGlobal
+      ? contexto.dirRuntimeGlobal
+      : '.cursor';
+
+    return {
+      contenido,
+      rutaRelativa: 'rules/swl-agentes.mdc',
+      dirBase,
+    };
+  }
+
+  /**
+   * Sub-fase 10 v1.5.0: Cursor SÍ soporta hooks via .cursor/hooks.json
+   * (cursor.com/es/docs/hooks). Schema:
+   *   { "version": 1, "hooks": { "preToolUse": [{ "command": "...", "type": "command", ... }] } }
+   *
+   * Mapeo Claude → Cursor:
+   *   PreToolUse → preToolUse, PostToolUse → postToolUse, Stop → stop,
+   *   SessionStart → sessionStart, UserPromptSubmit → beforeSubmitPrompt,
+   *   SubagentStop → subagentStop.
+   *   Notification → sin equivalente, descartar.
+   */
+  transformarHooks(hooksConfig, opciones) {
+    if (!hooksConfig || typeof hooksConfig !== 'object') return null;
+    const opts = opciones || {};
+    const hookFilesFiltro = Array.isArray(opts.hookFiles) ? new Set(opts.hookFiles) : null;
+    const rutaHooksDir = opts.rutaHooksDir || 'hooks';
+
+    const MAPEO = {
+      PreToolUse: 'preToolUse',
+      PostToolUse: 'postToolUse',
+      Stop: 'stop',
+      SessionStart: 'sessionStart',
+      UserPromptSubmit: 'beforeSubmitPrompt',
+      SubagentStop: 'subagentStop',
+    };
+
+    const grupos = {};
+    const descartados = [];
+
+    for (const [hookFile, def] of Object.entries(hooksConfig)) {
+      if (hookFilesFiltro && !hookFilesFiltro.has(hookFile)) continue;
+      if (!def || !Array.isArray(def.events)) continue;
+
+      for (const event of def.events) {
+        const cursorEvent = MAPEO[event];
+        if (!cursorEvent) {
+          descartados.push({ hookFile, event, motivo: 'sin equivalente Cursor' });
+          continue;
+        }
+        if (!grupos[cursorEvent]) grupos[cursorEvent] = [];
+        // Cursor: entrada plana, sin grupo intermedio.
+        const entry = {
+          command: `node ${rutaHooksDir}/${hookFile}`,
+          type: 'command',
+          ...(def.timeout ? { timeout: def.timeout } : {}),
+          ...(def.matcher ? { matcher: def.matcher } : {}),
+          ...(def.failClosed === true ? { failClosed: true } : {}),
+        };
+        grupos[cursorEvent].push(entry);
+      }
+    }
+
+    return {
+      formato: 'cursor-hooks-json',
+      destino: 'hooks.json',
+      config: { version: 1, hooks: grupos },
+      descartados,
+    };
+  }
+
+  soportaTipo(tipo) {
+    // Sub-fase 7 + 10 v1.5.0: Cursor soporta agentes, habilidades, reglas Y hooks.
+    // Comandos slash custom: NO existen como filesystem (equivalente = skills).
+    return ['agentes', 'habilidades', 'reglas', 'hooks'].includes(tipo);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Construye un archivo .mdc (formato Cursor) con frontmatter YAML mínimo.
+   * Solo serializa los campos que Cursor entiende: description, alwaysApply, globs.
+   */
+  construirMdc(frontmatter, cuerpo) {
+    const lineas = ['---'];
+    if (frontmatter.description !== undefined) {
+      lineas.push(`description: ${this._yamlString(frontmatter.description)}`);
+    }
+    if (frontmatter.alwaysApply !== undefined) {
+      lineas.push(`alwaysApply: ${Boolean(frontmatter.alwaysApply)}`);
+    }
+    if (Array.isArray(frontmatter.globs) && frontmatter.globs.length > 0) {
+      const items = frontmatter.globs.map(g => this._yamlString(g)).join(', ');
+      lineas.push(`globs: [${items}]`);
+    }
+    lineas.push('---');
+    lineas.push('');
+    lineas.push(cuerpo);
+    return lineas.join('\n');
+  }
+
+  _yamlString(s) {
+    // Escapado simple para YAML inline — doblequotes con escape de backslash y doblequote.
+    const escapado = String(s)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, ' ');
+    return `"${escapado}"`;
+  }
+
+  /**
+   * Escribe (o actualiza idempotentemente) `.cursor/mcp.json` con el server `swl-memory`.
+   * Preserva otros mcpServers ya configurados por el usuario.
+   *
+   * Cursor lee `.cursor/mcp.json` per-proyecto y `~/.cursor/mcp.json` global. La función
+   * decide según `contexto.esGlobal`.
+   */
+  _escribirMcpJson(contexto) {
+    if (!contexto.swlBinPath) {
+      console.warn('[cursor] withMcp=true pero no se proporcionó swlBinPath; .cursor/mcp.json no actualizado.');
+      return;
+    }
+    const dirBase = contexto.esGlobal && contexto.dirRuntimeGlobal
+      ? contexto.dirRuntimeGlobal
+      : path.resolve('.cursor');
+    fs.mkdirSync(dirBase, { recursive: true });
+
+    const rutaMcp = path.join(dirBase, 'mcp.json');
+    let existente = { mcpServers: {} };
+    if (fs.existsSync(rutaMcp)) {
+      try {
+        const raw = fs.readFileSync(rutaMcp, 'utf-8');
+        if (raw.trim().length > 0) {
+          const parsed = JSON.parse(raw);
+          existente = parsed && typeof parsed === 'object' ? parsed : { mcpServers: {} };
+          if (!existente.mcpServers || typeof existente.mcpServers !== 'object') {
+            existente.mcpServers = {};
+          }
+        }
+      } catch (err) {
+        console.warn(`[cursor] .cursor/mcp.json existente no es JSON válido (${err.message}). Se reemplazará preservando solo la entrada swl-memory.`);
+        existente = { mcpServers: {} };
+      }
+    }
+
+    existente.mcpServers['swl-memory'] = {
+      command: 'node',
+      args: [contexto.swlBinPath],
+      env: {
+        SWL_MCP_BASE_DIR: process.cwd(),
+      },
+    };
+
+    atomicWriteSync(rutaMcp, JSON.stringify(existente, null, 2) + '\n', 'utf8', { mode: 0o600 });
+  }
+}
+
+module.exports = TransformadorCursor;

package/scripts/lib/transformadores/index.js

@@ -5,6 +5,7 @@ const TransformadorCopilot = require('./copilot');
 const TransformadorOpenCode = require('./opencode');
 const TransformadorCodex = require('./codex');
 const TransformadorGemini = require('./gemini');
+const TransformadorCursor = require('./cursor');
 
 const TRANSFORMADORES = {
   claude: TransformadorClaude,
@@ -13,6 +14,7 @@ const TRANSFORMADORES = {
   opencode: TransformadorOpenCode,
   codex: TransformadorCodex,
   gemini: TransformadorGemini,
+  cursor: TransformadorCursor,      // ADR-0019 Sub-fase 2
 };
 
 function obtenerTransformador(targetId, runtimeConfig) {

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();