@saulwade/swl-ses 1.0.0

package/scripts/lib/prompt-builder.js

@@ -0,0 +1,264 @@
+'use strict';
+
+/**
+ * prompt-builder.js — Construcción dinámica de instrucciones para comandos
+ * `/swl:*` y agentes desde un base + contexto + apéndices YAML por proyecto.
+ *
+ * Patrón adaptado de `temp/claudian-main/src/core/prompt/mainAgent.ts`
+ * (plugin Obsidian Claudian, Yishen Tu, MIT). Diferencias respecto al
+ * original:
+ *   - SWL no controla el system prompt del subagente (lo gestiona Claude
+ *     Code). Esta librería se enfoca en composición de mensajes/instrucciones
+ *     que comandos `/swl:*` o agentes generan dinámicamente al delegar.
+ *   - Zero-deps Node stdlib (sin js-yaml). Parser YAML mínimo y suficiente
+ *     para apéndices simples (key: scalar, listas y bloques `>`).
+ *
+ * Uso programático:
+ *   const pb = require('./scripts/lib/prompt-builder');
+ *   const apendices = pb.cargarApendices(); // lee instintos/prompt-appendices.yaml
+ *   const mensaje = pb.construirPrompt({
+ *     base: 'Implementa la fase X siguiendo el PLAN.md.',
+ *     contexto: { proyecto: 'sigaf', fase: '03-validacion' },
+ *     appendices: ['estilo_respuesta', 'restricciones_dominio'],
+ *     apendicesDisponibles: apendices,
+ *   });
+ *
+ * Uso CLI (debug):
+ *   node scripts/lib/prompt-builder.js --base "instr" --apendice estilo_respuesta
+ *
+ * @module scripts/lib/prompt-builder
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RUTA_APENDICES_DEFAULT = path.join(process.cwd(), 'instintos', 'prompt-appendices.yaml');
+
+/**
+ * Parser YAML mínimo zero-deps. Soporta:
+ *   - claves de primer nivel con valor escalar: `key: value`
+ *   - claves con bloque `>` o `|`: continúa hasta encontrar otra clave de
+ *     primer nivel o EOF
+ *   - secciones anidadas de un nivel: `parent:\n  hijo: valor`
+ *   - listas inline `key: [a, b, c]` o multilínea con `- ` (no profundas)
+ *
+ * NO soporta: anidamiento profundo arbitrario, anclas `&`, alias `*`, tags.
+ * Si se requiere YAML complejo, cargar js-yaml como dependencia opcional
+ * (NO incluido aquí por principio zero-deps).
+ *
+ * @param {string} texto
+ * @returns {object}
+ */
+function parsearYamlMinimo(texto) {
+  if (!texto || typeof texto !== 'string') return {};
+  const lineas = texto.split(/\r?\n/);
+  const resultado = {};
+
+  let claveSeccion = null;
+  let bufferBloque = null;
+  let claveBloque = null;
+  let modoBloque = null;
+  let seccionActual = null;
+
+  const esLineaIndentadaSeccion = (l) => /^\s{2,}\S/.test(l);
+  const esComentario = (l) => /^\s*#/.test(l) || l.trim() === '';
+
+  function commitBloque() {
+    if (claveBloque !== null && bufferBloque !== null) {
+      const valor = modoBloque === '>'
+        ? bufferBloque.replace(/\n+/g, ' ').trim()
+        : bufferBloque.replace(/\n$/, '');
+      if (claveSeccion) {
+        if (!resultado[claveSeccion] || typeof resultado[claveSeccion] !== 'object') {
+          resultado[claveSeccion] = {};
+        }
+        resultado[claveSeccion][claveBloque] = valor;
+      } else {
+        resultado[claveBloque] = valor;
+      }
+    }
+    bufferBloque = null;
+    claveBloque = null;
+    modoBloque = null;
+  }
+
+  for (const linea of lineas) {
+    if (claveBloque !== null) {
+      if (esComentario(linea)) continue;
+      if (esLineaIndentadaSeccion(linea)) {
+        bufferBloque += linea.replace(/^\s+/, '') + '\n';
+        continue;
+      } else {
+        commitBloque();
+      }
+    }
+
+    if (esComentario(linea)) continue;
+
+    const matchSeccion = linea.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*$/);
+    if (matchSeccion) {
+      commitBloque();
+      claveSeccion = matchSeccion[1];
+      seccionActual = claveSeccion;
+      if (!resultado[claveSeccion]) resultado[claveSeccion] = {};
+      continue;
+    }
+
+    const matchBloque = linea.match(/^(\s*)([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*([>|])\s*$/);
+    if (matchBloque) {
+      const [, indent, k, modo] = matchBloque;
+      if (indent.length > 0 && claveSeccion) {
+        claveBloque = k;
+      } else {
+        commitBloque();
+        claveSeccion = null;
+        claveBloque = k;
+      }
+      bufferBloque = '';
+      modoBloque = modo;
+      continue;
+    }
+
+    const matchKV = linea.match(/^(\s*)([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.+?)\s*$/);
+    if (matchKV) {
+      const [, indent, k, rawV] = matchKV;
+      const v = rawV.replace(/^["'](.*)["']$/, '$1');
+      if (indent.length > 0 && seccionActual) {
+        if (!resultado[seccionActual] || typeof resultado[seccionActual] !== 'object') {
+          resultado[seccionActual] = {};
+        }
+        resultado[seccionActual][k] = v;
+      } else {
+        seccionActual = null;
+        claveSeccion = null;
+        resultado[k] = v;
+      }
+      continue;
+    }
+  }
+  commitBloque();
+  return resultado;
+}
+
+/**
+ * Carga el archivo `instintos/prompt-appendices.yaml` si existe.
+ * Retorna `{}` si no existe o si el parseo falla (zero-throw).
+ *
+ * @param {string} [ruta] - Ruta absoluta opcional para tests.
+ * @returns {object} mapa de apéndices
+ */
+function cargarApendices(ruta) {
+  const r = ruta || RUTA_APENDICES_DEFAULT;
+  try {
+    if (!fs.existsSync(r)) return {};
+    const contenido = fs.readFileSync(r, 'utf8');
+    return parsearYamlMinimo(contenido);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Sustituye placeholders `{clave}` en una cadena con valores del contexto.
+ * Solo claves planas (no expresiones); valores undefined dejan el placeholder.
+ *
+ * @param {string} texto
+ * @param {object} contexto
+ * @returns {string}
+ */
+function interpolar(texto, contexto) {
+  if (!texto || !contexto) return texto || '';
+  return String(texto).replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, clave) => {
+    const v = contexto[clave];
+    return v === undefined ? `{${clave}}` : String(v);
+  });
+}
+
+/**
+ * Construye un prompt/instrucción dinámico componiendo:
+ *   1. base (obligatorio)
+ *   2. apéndices seleccionados del catálogo (instintos/prompt-appendices.yaml)
+ *   3. customAppend (instrucciones ad-hoc no en catálogo)
+ *
+ * Todos los componentes pasan por `interpolar()` con el contexto provisto.
+ *
+ * @param {object} opts
+ * @param {string} opts.base                       - Texto base obligatorio.
+ * @param {object} [opts.contexto]                 - Variables para interpolación.
+ * @param {string[]} [opts.appendices]             - Nombres de apéndices a incluir.
+ * @param {object} [opts.apendicesDisponibles]     - Catálogo (resultado de cargarApendices).
+ * @param {string} [opts.customAppend]             - Texto adicional sin pasar por catálogo.
+ * @returns {string}
+ */
+function construirPrompt(opts = {}) {
+  const base = opts.base;
+  if (!base || typeof base !== 'string') {
+    throw new Error('construirPrompt: opts.base es obligatorio (string)');
+  }
+  const contexto = opts.contexto || {};
+  const apendicesDisp = opts.apendicesDisponibles || {};
+  const seleccion = Array.isArray(opts.appendices) ? opts.appendices : [];
+
+  const partes = [interpolar(base, contexto).trim()];
+
+  for (const nombre of seleccion) {
+    const valor = apendicesDisp[nombre];
+    if (valor && typeof valor === 'string' && valor.trim().length > 0) {
+      partes.push(interpolar(valor, contexto).trim());
+    }
+  }
+
+  if (opts.customAppend && typeof opts.customAppend === 'string' && opts.customAppend.trim()) {
+    partes.push(interpolar(opts.customAppend, contexto).trim());
+  }
+
+  return partes.filter(Boolean).join('\n\n');
+}
+
+/**
+ * Calcula un identificador estable de un prompt construido. Útil para
+ * caché o deduplicación (mismo input → misma key).
+ *
+ * Patrón adaptado de `computeSystemPromptKey` de claudian.
+ *
+ * @param {object} opts
+ * @returns {string}
+ */
+function calcularKey(opts = {}) {
+  const partes = [
+    opts.base || '',
+    JSON.stringify(opts.contexto || {}),
+    (opts.appendices || []).join('||'),
+    opts.customAppend || '',
+  ];
+  return partes.join('::');
+}
+
+module.exports = {
+  construirPrompt,
+  cargarApendices,
+  calcularKey,
+  _internals: {
+    parsearYamlMinimo,
+    interpolar,
+    RUTA_APENDICES_DEFAULT,
+  },
+};
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--base') opts.base = args[++i];
+    else if (args[i] === '--apendice') {
+      opts.appendices = opts.appendices || [];
+      opts.appendices.push(args[++i]);
+    } else if (args[i] === '--ruta-apendices') opts.rutaApendices = args[++i];
+  }
+  if (!opts.base) {
+    process.stderr.write('Uso: node prompt-builder.js --base "<texto>" [--apendice <nombre>]+ [--ruta-apendices <ruta>]\n');
+    process.exit(1);
+  }
+  opts.apendicesDisponibles = cargarApendices(opts.rutaApendices);
+  process.stdout.write(construirPrompt(opts) + '\n');
+}

package/scripts/lib/resolver-externo.js

@@ -0,0 +1,332 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+/**
+ * Resuelve una fuente externa (URL Git o path local) a archivos de skills/agentes.
+ *
+ * @param {string} fuente - URL Git, shorthand owner/repo, github:user/repo, o path local
+ * @param {object} opciones
+ * @param {string} opciones.tipo - 'skills' | 'agents'
+ * @param {string} opciones.nombre - Nombre específico del componente (--skill X o --agent X)
+ * @param {string} opciones.cacheDir - Directorio temporal ya clonado (evita re-clonar)
+ * @returns {{ archivos: Array<{nombre, ruta, contenido, esDirectorio}>, metadata: object }}
+ */
+function resolverFuente(fuente, opciones = {}) {
+  const tipo = opciones.tipo || 'skills';
+  const nombreFiltro = opciones.nombre || null;
+
+  // Si hay un directorio en caché (ya clonado), usarlo como local
+  if (opciones.cacheDir && fs.existsSync(opciones.cacheDir)) {
+    const resultado = resolverLocal(opciones.cacheDir, tipo, nombreFiltro);
+    // Mantener la URL original como fuente en la metadata
+    resultado.metadata.fuente = fuente;
+    resultado.metadata.tipo = 'git';
+    return resultado;
+  }
+
+  // Determinar si es path local o URL
+  if (esPathLocal(fuente)) {
+    return resolverLocal(path.resolve(fuente), tipo, nombreFiltro);
+  }
+
+  // Normalizar URL
+  const url = normalizarUrl(fuente);
+  return resolverGit(url, tipo, nombreFiltro);
+}
+
+/**
+ * Determina si una fuente es un path local
+ */
+function esPathLocal(fuente) {
+  // owner/repo shorthand no es path local
+  if (/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(fuente) && !fs.existsSync(fuente)) return false;
+  if (fuente.startsWith('/') || fuente.startsWith('./') || fuente.startsWith('..')) return true;
+  if (/^[a-zA-Z]:[\\/]/.test(fuente)) return true; // Windows absolute path
+  if (fs.existsSync(fuente)) return true;
+  return false;
+}
+
+/**
+ * Normaliza URLs: soporta owner/repo, github:user/repo, https://github.com/user/repo
+ */
+function normalizarUrl(fuente) {
+  // github:user/repo → https://github.com/user/repo.git
+  if (fuente.startsWith('github:')) {
+    return `https://github.com/${fuente.slice(7)}.git`;
+  }
+  // owner/repo shorthand (sin protocolo, sin puntos, con exactamente un /)
+  if (/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(fuente)) {
+    return `https://github.com/${fuente}.git`;
+  }
+  // Si no tiene .git al final, agregarlo
+  if (fuente.startsWith('https://') && !fuente.endsWith('.git')) {
+    return fuente + '.git';
+  }
+  return fuente;
+}
+
+/**
+ * Resuelve componentes desde un path local
+ */
+function resolverLocal(rutaAbsoluta, tipo, nombreFiltro) {
+  if (!fs.existsSync(rutaAbsoluta)) {
+    throw new Error(`Ruta no encontrada: ${rutaAbsoluta}`);
+  }
+
+  const archivos = [];
+  const stat = fs.statSync(rutaAbsoluta);
+
+  if (tipo === 'skills') {
+    if (stat.isDirectory()) {
+      // Buscar SKILL.md en el directorio o subdirectorios
+      const skills = buscarSkills(rutaAbsoluta, nombreFiltro);
+      archivos.push(...skills);
+    }
+  } else if (tipo === 'agents') {
+    if (stat.isFile() && rutaAbsoluta.endsWith('.md')) {
+      archivos.push({
+        nombre: path.basename(rutaAbsoluta, '.md'),
+        ruta: rutaAbsoluta,
+        contenido: fs.readFileSync(rutaAbsoluta, 'utf-8'),
+        esDirectorio: false,
+      });
+    } else if (stat.isDirectory()) {
+      const agentes = buscarAgentes(rutaAbsoluta, nombreFiltro);
+      archivos.push(...agentes);
+    }
+  }
+
+  if (archivos.length === 0) {
+    throw new Error(`No se encontraron ${tipo} en: ${rutaAbsoluta}`);
+  }
+
+  return {
+    archivos,
+    metadata: {
+      fuente: rutaAbsoluta,
+      tipo: 'local',
+      fecha: new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Resuelve componentes desde un repo Git
+ */
+function resolverGit(url, tipo, nombreFiltro) {
+  // Crear directorio temporal
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swl-ses-'));
+
+  try {
+    // Clonar con depth 1
+    console.log(`  Clonando ${url}...`);
+    execSync(`git clone --depth 1 "${url}" "${tmpDir}"`, {
+      stdio: 'pipe',
+      timeout: 30000,
+    });
+
+    const archivos = [];
+
+    if (tipo === 'skills') {
+      const skills = buscarSkills(tmpDir, nombreFiltro);
+      // Leer contenidos antes de limpiar tmpdir
+      for (const skill of skills) {
+        skill.contenidoDir = leerDirectorioRecursivo(skill.ruta);
+      }
+      archivos.push(...skills);
+    } else if (tipo === 'agents') {
+      const agentes = buscarAgentes(tmpDir, nombreFiltro);
+      archivos.push(...agentes);
+    }
+
+    if (archivos.length === 0) {
+      throw new Error(`No se encontraron ${tipo} en: ${url}`);
+    }
+
+    return {
+      archivos,
+      metadata: {
+        fuente: url,
+        tipo: 'git',
+        fecha: new Date().toISOString(),
+      },
+    };
+  } finally {
+    // Limpiar directorio temporal
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // Ignorar errores de limpieza
+    }
+  }
+}
+
+/**
+ * Busca directorios de skills (que contengan SKILL.md) recursivamente hasta 3 niveles
+ */
+function buscarSkills(dir, nombreFiltro) {
+  const resultados = [];
+
+  function escarbar(directorio, profundidad) {
+    if (profundidad > 3) return;
+
+    const entradas = fs.readdirSync(directorio, { withFileTypes: true });
+
+    for (const entrada of entradas) {
+      if (!entrada.isDirectory()) continue;
+      if (entrada.name.startsWith('.') || entrada.name === 'node_modules') continue;
+
+      const skillMd = path.join(directorio, entrada.name, 'SKILL.md');
+      if (fs.existsSync(skillMd)) {
+        if (nombreFiltro && entrada.name !== nombreFiltro) continue;
+
+        resultados.push({
+          nombre: entrada.name,
+          ruta: path.join(directorio, entrada.name),
+          contenido: fs.readFileSync(skillMd, 'utf-8'),
+          esDirectorio: true,
+        });
+      } else {
+        // Buscar en subdirectorios si no encontramos SKILL.md aquí
+        escarbar(path.join(directorio, entrada.name), profundidad + 1);
+      }
+    }
+  }
+
+  escarbar(dir, 0);
+
+  // También verificar si el propio directorio es un skill
+  const skillMdRaiz = path.join(dir, 'SKILL.md');
+  if (fs.existsSync(skillMdRaiz) && resultados.length === 0) {
+    const nombre = nombreFiltro || path.basename(dir);
+    resultados.push({
+      nombre,
+      ruta: dir,
+      contenido: fs.readFileSync(skillMdRaiz, 'utf-8'),
+      esDirectorio: true,
+    });
+  }
+
+  return resultados;
+}
+
+/**
+ * Busca archivos .md de agentes (con frontmatter YAML)
+ */
+function buscarAgentes(dir, nombreFiltro) {
+  const resultados = [];
+  const entradas = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entrada of entradas) {
+    if (!entrada.isFile() || !entrada.name.endsWith('.md')) continue;
+    if (entrada.name.startsWith('.') || entrada.name === 'README.md') continue;
+
+    const ruta = path.join(dir, entrada.name);
+    const contenido = fs.readFileSync(ruta, 'utf-8');
+
+    // Verificar que tiene frontmatter YAML (es un agente, no solo doc)
+    if (!contenido.startsWith('---\n')) continue;
+
+    const nombre = entrada.name.replace('.md', '');
+    if (nombreFiltro && nombre !== nombreFiltro) continue;
+
+    resultados.push({
+      nombre,
+      ruta,
+      contenido,
+      esDirectorio: false,
+    });
+  }
+
+  return resultados;
+}
+
+/**
+ * Lee recursivamente un directorio y retorna su contenido
+ */
+function leerDirectorioRecursivo(dir) {
+  const resultado = {};
+  const entradas = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entrada of entradas) {
+    const rutaCompleta = path.join(dir, entrada.name);
+    if (entrada.isDirectory()) {
+      resultado[entrada.name] = { tipo: 'dir', contenido: leerDirectorioRecursivo(rutaCompleta) };
+    } else {
+      resultado[entrada.name] = { tipo: 'file', contenido: fs.readFileSync(rutaCompleta, 'utf-8') };
+    }
+  }
+
+  return resultado;
+}
+
+/**
+ * Descubre todos los skills de una fuente sin instalar (para selección interactiva)
+ */
+function descubrirSkills(fuente) {
+  const url = esPathLocal(fuente) ? null : normalizarUrl(fuente);
+  const esLocal = esPathLocal(fuente);
+
+  if (esLocal) {
+    const rutaAbsoluta = path.resolve(fuente);
+    if (!fs.existsSync(rutaAbsoluta)) {
+      throw new Error(`Ruta no encontrada: ${rutaAbsoluta}`);
+    }
+    const skills = buscarSkills(rutaAbsoluta, null);
+    return {
+      skills: skills.map(s => ({ nombre: s.nombre, descripcion: extraerDescripcion(s.contenido) })),
+      fuente: rutaAbsoluta,
+      tipo: 'local',
+    };
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swl-ses-'));
+  try {
+    execSync(`git clone --depth 1 "${url}" "${tmpDir}"`, { stdio: 'pipe', timeout: 30000 });
+    const skills = buscarSkills(tmpDir, null);
+    return {
+      skills: skills.map(s => ({ nombre: s.nombre, descripcion: extraerDescripcion(s.contenido) })),
+      fuente: url,
+      tipo: 'git',
+      tmpDir,
+    };
+  } catch (err) {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * Limpia directorio temporal de descubrimiento
+ */
+function limpiarDescubrimiento(info) {
+  if (info && info.tmpDir) {
+    try { fs.rmSync(info.tmpDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
+/**
+ * Extrae la descripción del frontmatter YAML de un SKILL.md
+ */
+function extraerDescripcion(contenido) {
+  if (!contenido.startsWith('---')) return '';
+  const cierre = contenido.indexOf('---', 3);
+  if (cierre === -1) return '';
+  const frontmatter = contenido.slice(3, cierre);
+  const match = frontmatter.match(/description:\s*>?\s*\n?([\s\S]*?)(?:\n[a-z]|\n---)/i)
+    || frontmatter.match(/description:\s*["']?([^\n"']+)/i);
+  if (!match) return '';
+  return match[1].trim().replace(/\s+/g, ' ').slice(0, 120);
+}
+
+module.exports = {
+  resolverFuente,
+  descubrirSkills,
+  limpiarDescubrimiento,
+  esPathLocal,
+  normalizarUrl,
+};