@saulwade/swl-ses 1.0.0 → 1.0.1

package/CLAUDE.md

@@ -87,7 +87,7 @@ scripts/       bin/            _userland/      .claude/        .planning/
 | `/swl:contribuir` | Contribuir evoluciones de _userland/ al core vía PR (filtro dominio + PluginEval ≥80) |
 | `/swl:ayuda` | Ayuda interactiva: catálogo, detalle de comando, búsqueda por keyword |
 
-## Reglas obligatorias (20 base + 40 por lenguaje)
+## Reglas obligatorias (21 base + 40 por lenguaje)
 
 | Regla | Carga cuando |
 |-------|-------------|
@@ -109,6 +109,7 @@ scripts/       bin/            _userland/      .claude/        .planning/
 | `markitdown.md` | Lectura de archivos Office/Jupyter |
 | `patrones.md` | Patrones de diseño y arquitectura |
 | `testing.md` | test*/, *.test.*, *.spec.* |
+| `usar-context7.md` | OBLIGATORIA al generar código que importe librerías/frameworks externos. Aplica a `backend-*-swl`, `frontend-*-swl`, `mobile-*-swl`, `implementador-swl`, `llm-apps-swl`, `pagos-swl`, `datos-swl`. Verifica versión actual y deprecaciones via Context7 MCP antes de agregar deps o generar imports. |
 
 Reglas por lenguaje (5 por lenguaje × 8 lenguajes): Java, Go, Rust, C#, Kotlin, Swift, PHP, Next.js — en `reglas/` con subdirectorios.
 

package/bin/swl-ses.js

@@ -64,13 +64,34 @@ function verificarCoherenciaVersion() {
     }
 
     if (versionMax && compararSemver(versionMax, VERSION) === 1) {
-      process.stderr.write(
-        `\n[swl-ses] AVISO: CLI desactualizado — ejecutando v${VERSION}, pero tu instalación SWL es v${versionMax}.\n` +
-        `[swl-ses] npm tiene cacheada una versión vieja. Para usar la versión correcta:\n` +
-        `[swl-ses]   npx @saulwade/swl-ses@latest <comando>\n` +
-        `[swl-ses] O limpia la caché de npx:\n` +
-        `[swl-ses]   npx clear-npx-cache\n\n`
+      const localPS  = parseSemver(versionMax);
+      const cliPS    = parseSemver(VERSION);
+      // Tras el rebrand 2026-04-30, el CLI nuevo @saulwade/swl-ses
+      // arrancó en v1.0.0 mientras el paquete legacy (@saulwadeleon/...
+      // o swl-ses sin scope) estaba en 5.13.1. Si la diferencia de
+      // major es ≥3 hacia abajo del CLI nuevo, NO es "desactualizado":
+      // el state apunta a una instalación previa al rebrand. En ese
+      // caso emitimos un aviso DIFERENTE: "reinstala para sincronizar".
+      const esDriftDePaqueteLegacy = (
+        localPS && cliPS &&
+        localPS[0] >= 5 && cliPS[0] === 1 &&
+        (localPS[0] - cliPS[0]) >= 3
       );
+      if (esDriftDePaqueteLegacy) {
+        process.stderr.write(
+          `\n[swl-ses] Detectada instalación previa del paquete legacy (v${versionMax}).\n` +
+          `[swl-ses] El sistema fue renombrado a @saulwade/swl-ses con SemVer reset (v${VERSION}).\n` +
+          `[swl-ses] Para sincronizar: npx @saulwade/swl-ses@latest install --target claude --profile <perfil> --force\n\n`
+        );
+      } else {
+        process.stderr.write(
+          `\n[swl-ses] AVISO: CLI desactualizado — ejecutando v${VERSION}, pero tu instalación SWL es v${versionMax}.\n` +
+          `[swl-ses] npm tiene cacheada una versión vieja. Para usar la versión correcta:\n` +
+          `[swl-ses]   npx @saulwade/swl-ses@latest <comando>\n` +
+          `[swl-ses] O limpia la caché de npx:\n` +
+          `[swl-ses]   npx clear-npx-cache\n\n`
+        );
+      }
     }
   } catch { /* nunca bloquear el CLI por este check */ }
 }

package/manifiestos/modulos.json

@@ -835,7 +835,8 @@
         "reglas/arquitectura.md",
         "reglas/brevedad-output.md",
         "reglas/seguridad-agentes.md",
-        "reglas/memoria-consolidada.md"
+        "reglas/memoria-consolidada.md",
+        "reglas/usar-context7.md"
       ],
       "targets": [
         "claude",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saulwade/swl-ses",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot con 59 agentes, 151 habilidades, 42 comandos, 60 reglas y 37 hooks. Soporta 11 lenguajes y 5 runtimes: Claude Code, Copilot, OpenCode, Codex y Gemini CLI. 100% en espanol (Mexico). Incluye gateway bidireccional con relay Telegram a Claude Code.",
   "bin": {
     "swl-ses": "bin/swl-ses.js",
@@ -31,9 +31,10 @@
     "test:smoke": "node scripts/smoke-test.js",
     "test:aislamiento": "node scripts/validar-tests-aislamiento.js",
     "test:all": "npm test && node scripts/validar.js && node scripts/validar-manifest.js",
-    "test:release": "npm run test:all && npm run test:smoke",
+    "test:userland": "node scripts/validar-userland-vacio.js",
+    "test:release": "npm run test:all && npm run test:userland && npm run test:smoke",
     "doctor": "node scripts/doctor.js",
-    "prepack": "node scripts/limpiar-artefactos-python.js",
+    "prepack": "node scripts/limpiar-artefactos-python.js && node scripts/validar-userland-vacio.js",
     "prepublishOnly": "npm run test:release",
     "publish:all": "node scripts/publicar.js",
     "publish:github": "node scripts/publicar.js --solo-github",
@@ -76,9 +77,6 @@
   "dependencies": {
     "docx": "^9.6.1"
   },
-  "optionalDependencies": {
-    "@xenova/transformers": "^2.17.2"
-  },
   "overrides": {
     "pako": "^2.1.0",
     "readable-stream": "^4.7.0"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "swl-ses",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Sistema de ingenieria de software auto-evolutivo multi-runtime polyglot. 59 agentes, 151 habilidades, 42 comandos, 60 reglas y 37 hooks. 60 librerias. 11 lenguajes. Soporta Claude Code, Copilot, OpenCode, Codex y Gemini CLI.",
   "author": "Saul Wade Leon",
   "license": "MIT",

package/reglas/usar-context7.md

@@ -0,0 +1,226 @@
+# Regla: Consultar Context7 antes de generar código con dependencias externas
+
+Esta regla es OBLIGATORIA para todo agente o skill del sistema SWL que
+genere código que use librerías, frameworks, SDKs o APIs externas. La regla
+se carga automáticamente para los agentes de stack (`backend-*-swl`,
+`frontend-*-swl`, `mobile-*-swl`, `implementador-swl`, `llm-apps-swl`,
+`pagos-swl`, `datos-swl`) y para skills de implementación.
+
+---
+
+## Por qué existe esta regla
+
+El conocimiento del modelo sobre librerías de terceros tiene fecha de
+corte. Una librería que en el corte estaba en la versión X y era la
+recomendación, hoy puede estar:
+
+- En una versión Y mayor con cambios incompatibles
+- Deprecada y reemplazada por otra librería
+- Con vulnerabilidades conocidas que requieren un parche
+- Renombrada o migrada a otra organización
+
+Generar código sin verificar la versión actual genera tres clases de
+defectos en producción:
+
+1. **Imports a APIs deprecadas** que arrastran warnings o se eliminan
+   en próximas versiones (ejemplo histórico: `@xenova/transformers`
+   migrado a `@huggingface/transformers`).
+2. **Dependencias transitivas obsoletas** que el usuario ve como
+   warnings al instalar (ejemplo: `prebuild-install@7.1.3` arrastrada
+   por una librería que el sistema eligió sin verificar la salud).
+3. **Vulnerabilidades CVE conocidas** que están parchadas en versiones
+   más nuevas que el modelo no conoce.
+
+Context7 (MCP `mcp__claude_ai_Context7__query-docs` y
+`mcp__claude_ai_Context7__resolve-library-id`) provee documentación
+actualizada de librerías y frameworks. Su uso es la primera línea de
+defensa contra estos tres problemas.
+
+---
+
+## Cuándo consultar Context7 (OBLIGATORIO)
+
+Antes de:
+
+1. **Agregar una nueva dependencia** a `package.json`, `requirements.txt`,
+   `pom.xml`, `Cargo.toml`, `go.mod`, `composer.json`, `Package.swift` o
+   equivalente.
+2. **Generar código que importe o use una librería externa** que no
+   estaba ya en uso en el proyecto, aunque la librería ya esté
+   instalada.
+3. **Actualizar la versión** de una dependencia existente.
+4. **Migrar de una librería a otra** alternativa (ej.
+   `axios` → `fetch`, `moment` → `date-fns`, `jest` → `vitest`).
+5. **Resolver un warning de deprecación** de una dependencia
+   transitiva.
+6. **Implementar un patrón nuevo** del framework (ej. Server Actions
+   en Next.js, Signals en Angular, Suspense en React) — la API
+   correcta cambia rápido.
+
+NO es necesario consultar Context7 cuando:
+
+- La librería es interna al proyecto SWL (`scripts/lib/*`,
+  `hooks/lib/*`).
+- Es la biblioteca estándar del lenguaje (Node `fs`, Python `os`).
+- Es código que no usa dependencias externas (algoritmos, lógica de
+  negocio sin librerías de terceros).
+- El cambio es trivial (renombrar variable, formatear).
+
+---
+
+## Cómo consultar Context7
+
+El MCP de Context7 expone dos herramientas principales:
+
+```
+mcp__claude_ai_Context7__resolve-library-id(libraryName)
+  → Resuelve un nombre de librería (ej. "react", "next.js") al ID
+    canónico que Context7 usa internamente.
+
+mcp__claude_ai_Context7__query-docs(library, topic, version?)
+  → Devuelve documentación actualizada de la librería sobre el
+    topic específico. Acepta versión opcional.
+```
+
+Flujo típico:
+
+1. Resolver el ID de la librería:
+   ```
+   const id = mcp__claude_ai_Context7__resolve-library-id({
+     libraryName: "next.js"
+   });
+   ```
+
+2. Consultar el tema específico:
+   ```
+   const docs = mcp__claude_ai_Context7__query-docs({
+     library: id,
+     topic: "Server Actions",
+     version: "16"
+   });
+   ```
+
+3. Verificar:
+   - ¿La librería sigue siendo la recomendada o está deprecada?
+   - ¿Hay una alternativa migrada que deberíamos usar?
+   - ¿La API que voy a generar es la actual o cambió?
+   - ¿La versión que recomienda Context7 coincide con la del
+     `package.json` del proyecto?
+
+---
+
+## Reglas estrictas
+
+### NUNCA agregar dependencia sin verificar
+
+Antes de escribir `npm install <paquete>`, `pip install <paquete>`,
+`go get <paquete>` o equivalente:
+
+- Consultar Context7 para confirmar que la librería sigue activa.
+- Confirmar la versión más reciente compatible con el resto del
+  stack del proyecto.
+- Si Context7 reporta deprecación, **NO la uses**. Buscar la
+  alternativa migrada.
+
+### NUNCA generar código con API obsoleta
+
+Si el usuario pide implementar X usando librería Y:
+
+- Consultar Context7 sobre cómo se hace X en la versión actual de Y.
+- Si la API que aparece en el contexto del modelo difiere de la que
+  Context7 reporta como actual, **usar la de Context7**.
+- Documentar en un comentario corto la versión consultada y la
+  fecha si la API es notable.
+
+### NUNCA copiar ejemplos de la web sin verificar versión
+
+Stack Overflow, blogs y tutoriales tienen alta probabilidad de
+mostrar código deprecado. Si el agente consulta una web (vía
+WebSearch o WebFetch) y obtiene un ejemplo, ese ejemplo debe
+validarse contra Context7 antes de incorporarlo.
+
+---
+
+## Excepción: Context7 no responde o no tiene la librería
+
+Si Context7 no tiene documentación disponible para una librería
+específica:
+
+1. **Documentar en el código** que Context7 no respondió y la API se
+   tomó de la fuente oficial (npm registry, docs del repo).
+2. **Verificar al menos**: la librería existe, no está deprecada en
+   npm/PyPI, su última publicación es reciente (≤ 12 meses).
+3. **NO bloquear** el flujo del usuario por este caso — proceder con
+   diligencia razonable.
+
+---
+
+## Auditoría retroactiva
+
+Esta regla aplica también al código existente del proyecto SWL:
+
+- Si durante un refactor se detecta una dependencia que arrastra
+  warnings de deprecación, abrir un ticket para auditarla con
+  Context7 y migrar si hay alternativa actual.
+- El comando `/swl:auditar-deps` (cuando esté disponible) debe
+  cruzar las dependencias del proyecto contra Context7 para
+  detectar deprecaciones silenciosas.
+
+---
+
+## Aplicabilidad por agente
+
+| Agente | Aplica | Cuándo |
+|---|---|---|
+| `backend-python-swl` | SÍ | Al generar código FastAPI/Django/SQLAlchemy |
+| `backend-node-swl` | SÍ | Al generar código Express/Fastify/NestJS |
+| `backend-java-swl` | SÍ | Al generar código Spring Boot/JPA |
+| `backend-go-swl` | SÍ | Al generar código Go con frameworks |
+| `backend-rust-swl` | SÍ | Al generar código Axum/Actix |
+| `backend-csharp-swl` | SÍ | Al generar código ASP.NET Core |
+| `frontend-react-swl` | SÍ | Al generar código React/Next.js |
+| `frontend-angular-swl` | SÍ | Al generar código Angular |
+| `frontend-css-swl` | SÍ | Al usar PostCSS/Tailwind plugins |
+| `frontend-tailwind-swl` | SÍ | Al usar Tailwind v4+ APIs |
+| `frontend-swl` | SÍ | Al usar Vue/Svelte/Lit |
+| `mobile-android-swl` | SÍ | Al usar Jetpack Compose libs |
+| `mobile-ios-swl` | SÍ | Al usar SwiftUI/Combine |
+| `mobile-cross-swl` | SÍ | Al usar React Native/Flutter |
+| `implementador-swl` | SÍ | Generalista — siempre |
+| `llm-apps-swl` | SÍ | LangChain, OpenAI SDK, Anthropic SDK |
+| `pagos-swl` | SÍ | Stripe SDK actualizado |
+| `datos-swl` | SÍ | ORMs y drivers de BD |
+| `arquitecto-swl` | RECOMENDADO | Al evaluar tradeoffs entre librerías |
+| `revisor-codigo-swl` | RECOMENDADO | Al detectar deps deprecadas en review |
+| `revisor-seguridad-swl` | OBLIGATORIO | Al verificar CVEs de dependencias |
+| Resto de agentes | NO | No generan código con dependencias externas |
+
+---
+
+## Checklist de consulta Context7
+
+Antes de marcar una tarea como completa:
+
+- [ ] ¿Las dependencias agregadas/usadas se verificaron contra Context7?
+- [ ] ¿La versión usada está alineada con la que Context7 reporta como actual?
+- [ ] ¿No hay imports de APIs deprecadas según Context7?
+- [ ] ¿Las dependencias transitivas conocidas no son warnings de
+      deprecación al instalar?
+- [ ] Si Context7 no tenía la librería, ¿se documentó el motivo?
+
+---
+
+## Origen de esta regla
+
+Esta regla se formalizó tras observar en la primera instalación pública
+de `@saulwade/swl-ses@1.0.0` (2026-04-30) un warning de
+`prebuild-install@7.1.3 deprecated` arrastrado por
+`@xenova/transformers` que estaba en `optionalDependencies`. La
+dependencia se eligió en una iteración anterior sin verificar Context7;
+la migración oficial era `@huggingface/transformers`. El warning se vio
+en cada `npm install` del paquete distribuido. Resuelto en v1.0.1
+eliminando la dependencia opcional y elevando esta regla a obligatoria
+para que no se repita.
+
+Memoria asociada: `feedback_usar_context7.md` (preferencia previa del
+usuario, formalizada como regla).

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