@saulwade/swl-ses 1.0.0 → 1.1.1

package/scripts/lib/gitignore-manifest.js

@@ -18,6 +18,15 @@
 const fs = require("fs");
 const path = require("path");
 
+// Atomic write para .gitignore y manifest. Estos archivos viven en el
+// repo del usuario; corromperlos durante install puede romper su workflow.
+let atomicWriteSync;
+try {
+  ({ atomicWriteSync } = require(path.join(__dirname, "..", "..", "hooks", "lib", "atomic-write.js")));
+} catch {
+  atomicWriteSync = (p, c, e) => fs.writeFileSync(p, c, e);
+}
+
 const MARKER_INICIO = "# [swl-ses:inicio]";
 const MARKER_FIN = "# [swl-ses:fin]";
 const MANIFEST_FILE = ".swl-ses";
@@ -126,6 +135,27 @@ const ENTRADAS_POR_RUNTIME = {
  * @returns {string}            Ruta al .gitignore
  */
 function actualizarGitignore(cwd, extras = []) {
+  // Guarda defensiva: el bloque inyectado dice "swl-ses es tooling de
+  // desarrollo — no forma parte del proyecto". En el repo madre, swl-ses
+  // ES el proyecto, así que el bloque no aplica y rompería trackings
+  // legítimos (.planning/APRENDIZAJES.md, instintos/, hooks/). Si se
+  // detecta el package.json del madre, abortar sin tocar el .gitignore.
+  const pkgPath = path.join(cwd, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+      const esRepoMadre =
+        pkg.name === "@saulwade/swl-ses" ||
+        pkg.name === "@saul-wade/swl-ses" ||
+        pkg.name === "swl-ses";
+      if (esRepoMadre) {
+        return path.join(cwd, ".gitignore"); // no-op
+      }
+    } catch (_) {
+      // package.json corrupto — proceder con la lógica normal
+    }
+  }
+
   const gitignorePath = path.join(cwd, ".gitignore");
   let existente = fs.existsSync(gitignorePath)
     ? fs.readFileSync(gitignorePath, "utf-8")
@@ -168,7 +198,7 @@ function actualizarGitignore(cwd, extras = []) {
     "",
   ].join("\n");
 
-  fs.writeFileSync(gitignorePath, existente.trimEnd() + seccion, "utf-8");
+  atomicWriteSync(gitignorePath, existente.trimEnd() + seccion, "utf-8");
   return gitignorePath;
 }
 
@@ -214,7 +244,7 @@ function escribirManifest(cwd, data) {
   const manifestPath = path.join(cwd, MANIFEST_FILE);
   const existente = leerManifest(cwd) || {};
   const manifest = { ...existente, ...data };
-  fs.writeFileSync(
+  atomicWriteSync(
     manifestPath,
     JSON.stringify(manifest, null, 2) + "\n",
     "utf-8",

package/scripts/lib/semantic-search.js

@@ -26,6 +26,16 @@
  * Backend: el módulo NO requiere Xenova. Si SWL_SEMANTIC_BACKEND=xenova y
  * @xenova/transformers está instalado, se usa para embeddings. Si no, Jaccard.
  *
+ * Instalación opt-in del backend de embeddings:
+ *
+ *   npm install -g @xenova/transformers
+ *   export SWL_SEMANTIC_BACKEND=xenova
+ *
+ * @xenova/transformers ya NO es dependencia del paquete swl-ses (v1.0.1+)
+ * porque arrastra `prebuild-install@7.1.3` deprecated y sumaba ~50 MB al
+ * install para una feature opt-in raramente usada. El usuario que quiera
+ * el backend semántico lo instala manualmente.
+ *
  * @module scripts/lib/semantic-search
  */
 

package/scripts/migrar-csv-a-array.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Migración 3A — convierte campos CSV a array YAML inline en frontmatter de
+ * agentes. Afecta `tools`, `skillsInvocables`, `skillsRestringidos`.
+ *
+ * Antes:  tools: Read, Write, Edit, Bash
+ * Después: tools: [Read, Write, Edit, Bash]
+ *
+ * Razón: el schema declara `type: array` pero el uso real es CSV string. YAML
+ * estándar NO convierte CSV a array — el parser produce una sola string. Esto
+ * causó bugs históricos documentados en CLAUDE.md ("regla obligatoria CSV
+ * estricto"). Migrar a array inline elimina la ambigüedad.
+ *
+ * Idempotente: skip si ya es array.
+ *
+ * Casos especiales detectados en agentes:
+ *   - skillsInvocables: <ninguno>      → mantener literal
+ *   - skillsRestringidos: ninguno      → convertir a [] (array vacío)
+ *   - skillsRestringidos: \n  - x\n    → ya es array YAML multilinea, mantener
+ *
+ * Uso:
+ *   node scripts/migrar-csv-a-array.js [--dry-run]
+ *
+ * Zero-dependencies. Compatible Windows (CRLF-safe), Node 18+.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTES_DIR = path.join(__dirname, '..', 'agentes');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// Campos que migran de CSV a array
+const CAMPOS_CSV = ['tools', 'skillsInvocables', 'skillsRestringidos'];
+
+// Valores especiales que NO son listas y deben preservarse
+const VALORES_LITERAL = new Set(['ninguno', 'ninguna', '<ninguno>', '<ninguna>', 'none', 'null']);
+
+function parsearValorCSV(valorStr) {
+  // Detectar si ya es array inline `[a, b, c]`
+  if (/^\s*\[/.test(valorStr)) return null;
+
+  // Limpiar
+  const valor = valorStr.trim();
+  if (!valor) return [];
+
+  // Valor especial literal
+  if (VALORES_LITERAL.has(valor.toLowerCase())) return [];
+
+  // CSV split
+  return valor
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function migrarFrontmatter(contenido) {
+  const match = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) return { contenido, cambios: 0 };
+
+  const eol = match[0].includes('\r\n') ? '\r\n' : '\n';
+  const fmCompleto = match[0];
+
+  let nuevoFm = fmCompleto;
+  let cambios = 0;
+
+  for (const campo of CAMPOS_CSV) {
+    // Patrón 2 PRIMERO: array YAML multilínea
+    //   skillsRestringidos:
+    //     - angular-moderno
+    //     - typescript-avanzado
+    // El campo está solo en su línea (sin valor) seguido de líneas con `  - X`
+    const re2 = new RegExp(`^(${campo}):[ \\t]*\\r?\\n((?:[ \\t]+-[ \\t]+[^\\r\\n]+\\r?\\n)+)`, 'm');
+    const m2 = nuevoFm.match(re2);
+    if (m2) {
+      const bloque = m2[2];
+      const items = bloque
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.startsWith('- '))
+        .map((l) => l.slice(2).trim().replace(/^["']|["']$/g, ''));
+      if (items.length > 0) {
+        const arrayInline = `[${items.join(', ')}]`;
+        const reemplazo = `${campo}: ${arrayInline}${eol}`;
+        nuevoFm = nuevoFm.replace(re2, reemplazo);
+        cambios++;
+      }
+      continue; // procesado, no aplicar regex 1
+    }
+
+    // Patrón 1: campo en una sola línea con valor (CSV o array inline)
+    //   tools: Read, Write
+    //   skillsRestringidos: ninguno
+    //   tools: [Read, Write]   ← skip, ya es array
+    // CRÍTICO: usar [ \\t]* (NO \\s*) para no consumir newlines
+    const re1 = new RegExp(`^(${campo}):[ \\t]*([^\\r\\n]+)$`, 'm');
+    const m1 = nuevoFm.match(re1);
+    if (m1) {
+      const valorStr = m1[2];
+      const items = parsearValorCSV(valorStr);
+      if (items === null) continue; // ya es array, skip
+      const arrayInline = `[${items.join(', ')}]`;
+      const reemplazo = `${campo}: ${arrayInline}`;
+      if (m1[0] !== reemplazo) {
+        nuevoFm = nuevoFm.replace(re1, reemplazo);
+        cambios++;
+      }
+    }
+  }
+
+  if (cambios === 0) return { contenido, cambios: 0 };
+
+  return { contenido: contenido.replace(fmCompleto, nuevoFm), cambios };
+}
+
+function migrarAgente(archivo) {
+  const contenido = fs.readFileSync(archivo, 'utf-8');
+  const { contenido: nuevo, cambios } = migrarFrontmatter(contenido);
+
+  if (cambios === 0) {
+    return { archivo: path.basename(archivo), status: 'sin-cambios' };
+  }
+
+  if (DRY_RUN) {
+    return { archivo: path.basename(archivo), status: 'dry-run', cambios };
+  }
+
+  fs.writeFileSync(archivo, nuevo, 'utf-8');
+  return { archivo: path.basename(archivo), status: 'migrado', cambios };
+}
+
+function main() {
+  console.log(`Migrando CSV → array YAML${DRY_RUN ? ' (dry-run)' : ''}...\n`);
+
+  const archivos = fs
+    .readdirSync(AGENTES_DIR)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
+    .map((f) => path.join(AGENTES_DIR, f));
+
+  const resultados = archivos.map(migrarAgente);
+
+  const stats = {
+    'sin-cambios': 0,
+    migrado: 0,
+    'dry-run': 0,
+    totalCambios: 0,
+  };
+
+  for (const r of resultados) {
+    stats[r.status] = (stats[r.status] || 0) + 1;
+    if (r.cambios) stats.totalCambios += r.cambios;
+  }
+
+  console.log(`Sin cambios: ${stats['sin-cambios']}`);
+  console.log(`Migrados: ${stats.migrado}`);
+  console.log(`Dry-run: ${stats['dry-run']}`);
+  console.log(`Total ediciones: ${stats.totalCambios}`);
+
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { parsearValorCSV, migrarFrontmatter };

package/scripts/migrar-fase-dominio.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Migración Sprint 2B — añade campos `fase` y `dominio` al frontmatter de los
+ * 59 agentes de SWL. Skip si ya los tiene. Inserta antes de `exclusiones:` o
+ * al final del frontmatter.
+ *
+ * Idempotente: corre dos veces sin efectos.
+ *
+ * Uso:
+ *   node scripts/migrar-fase-dominio.js [--dry-run]
+ *
+ * Origen: análisis de temp/ + propuesta consolidada (mayo 2026).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTES_DIR = path.join(__dirname, '..', 'agentes');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// Mapeo agente → (fase, dominio). Vocabulario controlado del schema.
+const MAPEO = {
+  'accesibilidad-wcag-swl': ['verify', 'ux'],
+  'arquitecto-swl': ['plan', 'general'],
+  'auto-evolucion-swl': ['learn', 'meta'],
+  'backend-api-swl': ['implement', 'backend'],
+  'backend-csharp-swl': ['implement', 'backend'],
+  'backend-go-swl': ['implement', 'backend'],
+  'backend-java-swl': ['implement', 'backend'],
+  'backend-node-swl': ['implement', 'backend'],
+  'backend-python-swl': ['implement', 'backend'],
+  'backend-rust-swl': ['implement', 'backend'],
+  'backend-workers-swl': ['implement', 'backend'],
+  'cloud-infra-swl': ['release', 'infra'],
+  'consolidador-swl': ['learn', 'meta'],
+  'datos-swl': ['implement', 'data'],
+  'depurador-swl': ['implement', 'general'],
+  'devops-ci-swl': ['release', 'infra'],
+  'disenador-ui-swl': ['plan', 'ux'],
+  'documentador-swl': ['meta', 'docs'],
+  'frontend-angular-swl': ['implement', 'frontend'],
+  'frontend-css-swl': ['implement', 'frontend'],
+  'frontend-react-swl': ['implement', 'frontend'],
+  'frontend-swl': ['implement', 'frontend'],
+  'frontend-tailwind-swl': ['implement', 'frontend'],
+  'implementador-swl': ['implement', 'general'],
+  'investigador-swl': ['discover', 'general'],
+  'investigador-ux-swl': ['discover', 'ux'],
+  'llm-apps-swl': ['implement', 'backend'],
+  'migrador-swl': ['implement', 'data'],
+  'mobile-android-swl': ['implement', 'mobile'],
+  'mobile-cross-swl': ['implement', 'mobile'],
+  'mobile-ios-swl': ['implement', 'mobile'],
+  'mobile-testing-swl': ['verify', 'quality'],
+  'notificador-swl': ['meta', 'meta'],
+  'observabilidad-swl': ['release', 'infra'],
+  'orquestador-swl': ['meta', 'process'],
+  'pagos-swl': ['implement', 'backend'],
+  'perfilador-usuario-swl': ['meta', 'meta'],
+  'planificador-swl': ['plan', 'process'],
+  'producto-prd-swl': ['discover', 'process'],
+  'red-team-swl': ['verify', 'security'],
+  'release-manager-swl': ['release', 'process'],
+  'rendimiento-swl': ['verify', 'quality'],
+  'resolutor-build-swl': ['implement', 'general'],
+  'revisor-angular-swl': ['verify', 'quality'],
+  'revisor-codigo-swl': ['verify', 'quality'],
+  'revisor-csharp-swl': ['verify', 'quality'],
+  'revisor-go-swl': ['verify', 'quality'],
+  'revisor-java-swl': ['verify', 'quality'],
+  'revisor-kotlin-swl': ['verify', 'quality'],
+  'revisor-nextjs-swl': ['verify', 'quality'],
+  'revisor-php-swl': ['verify', 'quality'],
+  'revisor-react-swl': ['verify', 'quality'],
+  'revisor-rust-swl': ['verify', 'quality'],
+  'revisor-seguridad-swl': ['verify', 'security'],
+  'revisor-swift-swl': ['verify', 'quality'],
+  'revisor-typescript-swl': ['verify', 'quality'],
+  'sre-swl': ['release', 'infra'],
+  'tdd-qa-swl': ['verify', 'quality'],
+  'ux-disenador-swl': ['plan', 'ux'],
+};
+
+function migrarAgente(nombre) {
+  const archivo = path.join(AGENTES_DIR, `${nombre}.md`);
+  if (!fs.existsSync(archivo)) {
+    return { nombre, status: 'no-existe' };
+  }
+
+  const par = MAPEO[nombre];
+  if (!par) {
+    return { nombre, status: 'sin-mapeo' };
+  }
+  const [fase, dominio] = par;
+
+  const contenido = fs.readFileSync(archivo, 'utf-8');
+
+  // Detectar el frontmatter delimitado por `---` (acepta CRLF y LF)
+  const match = contenido.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!match) {
+    return { nombre, status: 'sin-frontmatter' };
+  }
+
+  const frontmatter = match[1];
+
+  // Idempotencia: skip si ya tiene fase y dominio
+  const tieneFase = /^fase:\s*\S+/m.test(frontmatter);
+  const tieneDominio = /^dominio:\s*\S+/m.test(frontmatter);
+  if (tieneFase && tieneDominio) {
+    return { nombre, status: 'ya-migrado', fase, dominio };
+  }
+
+  // Insertar antes de `exclusiones:` o al final del frontmatter
+  let nuevoFrontmatter;
+  if (/^exclusiones:/m.test(frontmatter)) {
+    nuevoFrontmatter = frontmatter.replace(
+      /^(exclusiones:)/m,
+      `fase: ${fase}\ndominio: ${dominio}\n$1`
+    );
+  } else {
+    // Sin exclusiones: agregar al final del frontmatter
+    nuevoFrontmatter = frontmatter.trimEnd() + `\nfase: ${fase}\ndominio: ${dominio}\n`;
+  }
+
+  // Preservar el line ending detectado
+  const eol = match[0].includes('\r\n') ? '\r\n' : '\n';
+  const fm = nuevoFrontmatter.replace(/\r\n/g, '\n').replace(/\n/g, eol);
+  const nuevoContenido = contenido.replace(match[0], `---${eol}${fm}${eol}---${eol}`);
+
+  if (DRY_RUN) {
+    return { nombre, status: 'dry-run-ok', fase, dominio };
+  }
+
+  fs.writeFileSync(archivo, nuevoContenido, 'utf-8');
+  return { nombre, status: 'migrado', fase, dominio };
+}
+
+function main() {
+  console.log(`Migrando fase/dominio en agentes${DRY_RUN ? ' (dry-run)' : ''}...\n`);
+
+  const archivosEnDisco = fs
+    .readdirSync(AGENTES_DIR)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
+    .map((f) => f.replace(/\.md$/, ''));
+
+  const resultados = archivosEnDisco.map(migrarAgente);
+
+  const stats = {
+    migrado: 0,
+    'ya-migrado': 0,
+    'dry-run-ok': 0,
+    'sin-mapeo': [],
+    'sin-frontmatter': [],
+    'no-existe': [],
+  };
+
+  for (const r of resultados) {
+    if (typeof stats[r.status] === 'number') {
+      stats[r.status]++;
+    } else if (Array.isArray(stats[r.status])) {
+      stats[r.status].push(r.nombre);
+    }
+  }
+
+  console.log(`Migrados: ${stats.migrado}`);
+  console.log(`Ya migrados (skip): ${stats['ya-migrado']}`);
+  console.log(`Dry-run OK: ${stats['dry-run-ok']}`);
+  if (stats['sin-mapeo'].length) {
+    console.log(`\n⚠️  Sin mapeo en MAPEO (${stats['sin-mapeo'].length}):`);
+    stats['sin-mapeo'].forEach((n) => console.log(`  - ${n}`));
+  }
+  if (stats['sin-frontmatter'].length) {
+    console.log(`\n❌ Sin frontmatter detectable:`);
+    stats['sin-frontmatter'].forEach((n) => console.log(`  - ${n}`));
+  }
+
+  // Validación: el mapeo debe cubrir todos los agentes en disco
+  const enMapeo = new Set(Object.keys(MAPEO));
+  const enDisco = new Set(archivosEnDisco);
+  const faltanEnMapeo = [...enDisco].filter((n) => !enMapeo.has(n));
+  const sobranEnMapeo = [...enMapeo].filter((n) => !enDisco.has(n));
+
+  if (faltanEnMapeo.length) {
+    console.log(`\n⚠️  Agentes en disco sin entrada en MAPEO:`);
+    faltanEnMapeo.forEach((n) => console.log(`  - ${n}`));
+  }
+  if (sobranEnMapeo.length) {
+    console.log(`\nℹ️  Entradas en MAPEO sin archivo en disco (probablemente renombrados):`);
+    sobranEnMapeo.forEach((n) => console.log(`  - ${n}`));
+  }
+
+  process.exit(stats['sin-frontmatter'].length || faltanEnMapeo.length ? 1 : 0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { MAPEO, migrarAgente };

package/scripts/validar-userland-vacio.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * validar-userland-vacio.js — guard pre-publish.
+ *
+ * Verifica que `_userland/` solo contenga archivos `.gitkeep` antes de
+ * empaquetar el tarball. Si algún contributor accidentalmente commiteó
+ * agentes, skills o credenciales experimentales en `_userland/`, este
+ * gate aborta el publish con exit 1 y lista los archivos extraños.
+ *
+ * Por qué existe (defensa en profundidad):
+ *   `_userland/` es el directorio donde el USUARIO instala su contenido
+ *   custom. En el repo del sistema debe permanecer vacío (solo
+ *   `.gitkeep` para preservar la estructura). El campo `files` de
+ *   package.json incluye `_userland/`, así que cualquier archivo real
+ *   que se cuele entrará al tarball publicado a npm — exposición
+ *   potencial de IP o secretos. Aunque `.gitignore` y `.npmignore` ya
+ *   cubren los vectores típicos (.env, credenciales), este guard
+ *   garantiza que la regla "_userland/ vacío en distribución" se cumpla
+ *   determinísticamente.
+ *
+ * Variables de entorno:
+ *   SWL_USERLAND_GUARD_ALLOW=archivo1,archivo2 — permite archivos extra
+ *     (uso excepcional documentado en commit que active la variable).
+ *
+ * Exit codes:
+ *   0 — OK, _userland/ solo contiene .gitkeep
+ *   1 — hay archivos extraños; lista impresa a stderr
+ *   2 — error de invariante (cwd incorrecto, _userland/ no existe)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const USERLAND_DIR = '_userland';
+const PERMITIDOS_BASE = new Set(['.gitkeep', '.gitignore']);
+
+function log(msg) { process.stdout.write(`[userland-guard] ${msg}\n`); }
+function err(msg) { process.stderr.write(`[userland-guard] ERROR: ${msg}\n`); }
+
+/**
+ * Normaliza una ruta relativa al separador POSIX (`/`) para que la
+ * comparación contra la allowlist funcione idéntica en Windows y POSIX.
+ */
+function normalizar(rel) {
+  return rel.replace(/\\/g, '/');
+}
+
+function obtenerExtras() {
+  const extras = process.env.SWL_USERLAND_GUARD_ALLOW;
+  if (!extras) return new Set();
+  return new Set(extras.split(',').map(s => normalizar(s.trim())).filter(Boolean));
+}
+
+function listarRecursivo(dir, baseDir = dir, acumulador = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    const rel  = normalizar(path.relative(baseDir, full));
+    if (entry.isDirectory()) {
+      listarRecursivo(full, baseDir, acumulador);
+    } else if (entry.isFile()) {
+      acumulador.push(rel);
+    } else if (entry.isSymbolicLink()) {
+      // Symlinks dentro del paquete distribuido son anti-patrón.
+      acumulador.push(`${rel} (symlink)`);
+    }
+  }
+  return acumulador;
+}
+
+function main() {
+  const cwd = process.cwd();
+  const userland = path.join(cwd, USERLAND_DIR);
+
+  if (!fs.existsSync(userland)) {
+    err(`${USERLAND_DIR}/ no existe en ${cwd}. ¿cwd incorrecto?`);
+    process.exit(2);
+  }
+
+  const extrasPermitidos = obtenerExtras();
+  const archivos = listarRecursivo(userland);
+
+  const noPermitidos = archivos.filter(rel => {
+    const nombre = path.basename(rel);
+    if (PERMITIDOS_BASE.has(nombre)) return false;
+    if (extrasPermitidos.has(rel)) return false;
+    return true;
+  });
+
+  if (noPermitidos.length > 0) {
+    err(`${USERLAND_DIR}/ contiene ${noPermitidos.length} archivo(s) que no deberían distribuirse en el tarball npm:`);
+    for (const rel of noPermitidos) {
+      err(`  - ${USERLAND_DIR}/${rel}`);
+    }
+    err('');
+    err('Acciones posibles:');
+    err(`  1. Mover el contenido fuera de ${USERLAND_DIR}/ si es del sistema base`);
+    err(`  2. Borrarlo si era código experimental local`);
+    err(`  3. Permitir explícitamente con SWL_USERLAND_GUARD_ALLOW="ruta1,ruta2"`);
+    err('     (documentar la excepción en el mensaje de commit)');
+    process.exit(1);
+  }
+
+  log(`OK: ${USERLAND_DIR}/ solo contiene ${archivos.length} archivo(s) permitido(s).`);
+  process.exit(0);
+}
+
+main();