@saulwade/swl-ses 1.3.8 → 1.4.0

package/scripts/lib/prompt-builder.js

@@ -1,264 +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');
-}
+'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');
+}