@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/cli/loop-telemetry.js

@@ -1,125 +1,125 @@
-'use strict';
-
-/**
- * Wrapper CLI `swl-ses loop-telemetry <op>` — telemetría de loops iterativos.
- * Reemplaza los inline `require('./hooks/lib/loop-telemetry')` relativos al
- * proyecto (rotos downstream; ver docs/invocacion-cli-cross-scope.md).
- *
- * Ops:
- *   iniciar   --tipo=X [--direccion=higher_is_better] [--config='{json}']  → imprime dir
- *   registrar --dir=D --iteracion=N --metrica=M [--delta=D] [--estado=keep]
- *             [--descripcion="..."]
- *   handoff   --dir=D --source=X --status=Y [--findings='[json]'] [--config='{json}']
- *   listar    (default) — resumen de las últimas 10 corridas
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-const lt = require('../../hooks/lib/loop-telemetry');
-
-// Parseo no degradante: si el flag está presente pero su JSON es inválido,
-// reporta y devuelve {ok:false} en vez de silenciar a fallback (anti-fallback
-// silencioso). El fallback solo aplica cuando el flag está ausente.
-function parseJSON(v, fallback, flagName) {
-  if (v === undefined) return { ok: true, val: fallback };
-  try {
-    return { ok: true, val: JSON.parse(v) };
-  } catch (e) {
-    console.error(`[loop-telemetry] --${flagName} JSON inválido: ${e.message}`);
-    return { ok: false };
-  }
-}
-
-function requireDir(opciones) {
-  if (!opciones.dir) {
-    console.error('Error: falta --dir=<ruta>');
-    process.exitCode = 1;
-    return false;
-  }
-  return true;
-}
-
-function loopTelemetry(opciones = {}) {
-  const op = (opciones._args && opciones._args[0]) || opciones.op || 'listar';
-
-  if (op === 'iniciar') {
-    const config = parseJSON(opciones.config, {}, 'config');
-    if (!config.ok) {
-      process.exitCode = 1;
-      return;
-    }
-    const r = lt.iniciarCorrida({
-      tipo: opciones.tipo,
-      direccion: opciones.direccion || 'higher_is_better',
-      config: config.val,
-    });
-    console.log(r.dir);
-    return;
-  }
-
-  if (op === 'registrar') {
-    if (!requireDir(opciones)) return;
-    const fila = {
-      iteracion: Number(opciones.iteracion),
-      metrica: Number(opciones.metrica),
-      estado: opciones.estado || 'keep',
-      descripcion: opciones.descripcion || '',
-    };
-    if (opciones.delta !== undefined) fila.delta = Number(opciones.delta);
-    lt.registrarIteracion(opciones.dir, fila);
-    console.log('[loop-telemetry] iteración registrada en ' + opciones.dir);
-    return;
-  }
-
-  if (op === 'handoff') {
-    if (!requireDir(opciones)) return;
-    const findings = parseJSON(opciones.findings, [], 'findings');
-    const config = parseJSON(opciones.config, {}, 'config');
-    if (!findings.ok || !config.ok) {
-      process.exitCode = 1;
-      return;
-    }
-    lt.escribirHandoff(opciones.dir, {
-      source: opciones.source,
-      status: opciones.status,
-      findings: findings.val,
-      config: config.val,
-    });
-    console.log('[loop-telemetry] handoff escrito en ' + opciones.dir);
-    return;
-  }
-
-  // listar (default)
-  const base = path.join(process.cwd(), lt.DIR_LOOPS);
-  let dirs = [];
-  try {
-    dirs = fs
-      .readdirSync(base)
-      .map((d) => path.join(base, d))
-      .filter((d) => fs.statSync(d).isDirectory());
-  } catch {
-    /* sin directorio de loops */
-  }
-  if (dirs.length === 0) {
-    console.log('(sin corridas de loops registradas)');
-    return;
-  }
-  for (const dir of dirs.sort().slice(-10)) {
-    try {
-      const t = lt.analizarTrayectoria(dir);
-      const h = lt.leerHandoff(dir);
-      console.log(
-        path.basename(dir) +
-          ' | iters: ' + t.totalIteraciones +
-          ' | keep/revert: ' + t.keeps + '/' + t.reverts +
-          ' | métrica: ' + t.metricaInicial + ' → ' + t.metricaFinal +
-          ' | plateau: ' + (t.plateau ? 'SÍ' : 'no') +
-          ' | status: ' + (h ? h.status : 'en curso')
-      );
-    } catch (e) {
-      console.log(path.basename(dir) + ' | (ilegible: ' + e.message + ')');
-    }
-  }
-}
-
-module.exports = loopTelemetry;
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses loop-telemetry <op>` — telemetría de loops iterativos.
+ * Reemplaza los inline `require('./hooks/lib/loop-telemetry')` relativos al
+ * proyecto (rotos downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Ops:
+ *   iniciar   --tipo=X [--direccion=higher_is_better] [--config='{json}']  → imprime dir
+ *   registrar --dir=D --iteracion=N --metrica=M [--delta=D] [--estado=keep]
+ *             [--descripcion="..."]
+ *   handoff   --dir=D --source=X --status=Y [--findings='[json]'] [--config='{json}']
+ *   listar    (default) — resumen de las últimas 10 corridas
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const lt = require('../../hooks/lib/loop-telemetry');
+
+// Parseo no degradante: si el flag está presente pero su JSON es inválido,
+// reporta y devuelve {ok:false} en vez de silenciar a fallback (anti-fallback
+// silencioso). El fallback solo aplica cuando el flag está ausente.
+function parseJSON(v, fallback, flagName) {
+  if (v === undefined) return { ok: true, val: fallback };
+  try {
+    return { ok: true, val: JSON.parse(v) };
+  } catch (e) {
+    console.error(`[loop-telemetry] --${flagName} JSON inválido: ${e.message}`);
+    return { ok: false };
+  }
+}
+
+function requireDir(opciones) {
+  if (!opciones.dir) {
+    console.error('Error: falta --dir=<ruta>');
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+function loopTelemetry(opciones = {}) {
+  const op = (opciones._args && opciones._args[0]) || opciones.op || 'listar';
+
+  if (op === 'iniciar') {
+    const config = parseJSON(opciones.config, {}, 'config');
+    if (!config.ok) {
+      process.exitCode = 1;
+      return;
+    }
+    const r = lt.iniciarCorrida({
+      tipo: opciones.tipo,
+      direccion: opciones.direccion || 'higher_is_better',
+      config: config.val,
+    });
+    console.log(r.dir);
+    return;
+  }
+
+  if (op === 'registrar') {
+    if (!requireDir(opciones)) return;
+    const fila = {
+      iteracion: Number(opciones.iteracion),
+      metrica: Number(opciones.metrica),
+      estado: opciones.estado || 'keep',
+      descripcion: opciones.descripcion || '',
+    };
+    if (opciones.delta !== undefined) fila.delta = Number(opciones.delta);
+    lt.registrarIteracion(opciones.dir, fila);
+    console.log('[loop-telemetry] iteración registrada en ' + opciones.dir);
+    return;
+  }
+
+  if (op === 'handoff') {
+    if (!requireDir(opciones)) return;
+    const findings = parseJSON(opciones.findings, [], 'findings');
+    const config = parseJSON(opciones.config, {}, 'config');
+    if (!findings.ok || !config.ok) {
+      process.exitCode = 1;
+      return;
+    }
+    lt.escribirHandoff(opciones.dir, {
+      source: opciones.source,
+      status: opciones.status,
+      findings: findings.val,
+      config: config.val,
+    });
+    console.log('[loop-telemetry] handoff escrito en ' + opciones.dir);
+    return;
+  }
+
+  // listar (default)
+  const base = path.join(process.cwd(), lt.DIR_LOOPS);
+  let dirs = [];
+  try {
+    dirs = fs
+      .readdirSync(base)
+      .map((d) => path.join(base, d))
+      .filter((d) => fs.statSync(d).isDirectory());
+  } catch {
+    /* sin directorio de loops */
+  }
+  if (dirs.length === 0) {
+    console.log('(sin corridas de loops registradas)');
+    return;
+  }
+  for (const dir of dirs.sort().slice(-10)) {
+    try {
+      const t = lt.analizarTrayectoria(dir);
+      const h = lt.leerHandoff(dir);
+      console.log(
+        path.basename(dir) +
+          ' | iters: ' + t.totalIteraciones +
+          ' | keep/revert: ' + t.keeps + '/' + t.reverts +
+          ' | métrica: ' + t.metricaInicial + ' → ' + t.metricaFinal +
+          ' | plateau: ' + (t.plateau ? 'SÍ' : 'no') +
+          ' | status: ' + (h ? h.status : 'en curso')
+      );
+    } catch (e) {
+      console.log(path.basename(dir) + ' | (ilegible: ' + e.message + ')');
+    }
+  }
+}
+
+module.exports = loopTelemetry;

package/scripts/cli/mark-evolved.js

@@ -1,56 +1,56 @@
-'use strict';
-
-/**
- * Wrapper CLI `swl-ses mark-evolved` — marca un componente SWL como evolucionado
- * (frontmatter evolved: true + metadatos). Reemplaza el inline
- * `require('./hooks/lib/evolution-tracker')` relativo al proyecto (roto
- * downstream; ver docs/invocacion-cli-cross-scope.md).
- *
- * Uso: swl-ses mark-evolved <ruta> [--from=VER] [--by=aprender]
- *                           [--note="..."] [--rounds=N] [--score="A% → B%"]
- */
-
-const path = require('node:path');
-const { markAsEvolved } = require('../../hooks/lib/evolution-tracker');
-
-function markEvolved(opciones = {}) {
-  const ruta = (opciones._args && opciones._args[0]) || opciones.ruta;
-  if (!ruta) {
-    console.error('Error: falta <ruta> del archivo a marcar');
-    process.exitCode = 1;
-    return;
-  }
-  // Guard anti path-traversal: la ruta debe resolver dentro del proyecto actual
-  // y ser un componente del sistema (.md/.json). Evita sobrescribir archivos
-  // arbitrarios con frontmatter si el flag se sintetiza desde input no confiable.
-  const cwd = process.cwd();
-  const resuelta = path.resolve(cwd, ruta);
-  if (resuelta !== cwd && !resuelta.startsWith(cwd + path.sep)) {
-    console.error('Error: la ruta debe estar dentro del proyecto actual');
-    process.exitCode = 1;
-    return;
-  }
-  if (!/\.(md|json)$/i.test(resuelta)) {
-    console.error('Error: solo se pueden marcar componentes .md o .json');
-    process.exitCode = 1;
-    return;
-  }
-  let from = opciones.from;
-  if (!from) {
-    try {
-      from = require(path.resolve(process.cwd(), 'package.json')).version;
-    } catch {
-      from = undefined;
-    }
-  }
-  const meta = { from, by: opciones.by || 'aprender' };
-  if (opciones.note) meta.note = opciones.note;
-  if (opciones.rounds) meta.rounds = Number(opciones.rounds);
-  if (opciones.score) meta.score = opciones.score;
-
-  const r = markAsEvolved(ruta, meta);
-  console.log(r.marked ? 'Marcado como evolucionado' : 'Error: ' + r.error);
-  if (!r.marked) process.exitCode = 1;
-}
-
-module.exports = markEvolved;
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses mark-evolved` — marca un componente SWL como evolucionado
+ * (frontmatter evolved: true + metadatos). Reemplaza el inline
+ * `require('./hooks/lib/evolution-tracker')` relativo al proyecto (roto
+ * downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses mark-evolved <ruta> [--from=VER] [--by=aprender]
+ *                           [--note="..."] [--rounds=N] [--score="A% → B%"]
+ */
+
+const path = require('node:path');
+const { markAsEvolved } = require('../../hooks/lib/evolution-tracker');
+
+function markEvolved(opciones = {}) {
+  const ruta = (opciones._args && opciones._args[0]) || opciones.ruta;
+  if (!ruta) {
+    console.error('Error: falta <ruta> del archivo a marcar');
+    process.exitCode = 1;
+    return;
+  }
+  // Guard anti path-traversal: la ruta debe resolver dentro del proyecto actual
+  // y ser un componente del sistema (.md/.json). Evita sobrescribir archivos
+  // arbitrarios con frontmatter si el flag se sintetiza desde input no confiable.
+  const cwd = process.cwd();
+  const resuelta = path.resolve(cwd, ruta);
+  if (resuelta !== cwd && !resuelta.startsWith(cwd + path.sep)) {
+    console.error('Error: la ruta debe estar dentro del proyecto actual');
+    process.exitCode = 1;
+    return;
+  }
+  if (!/\.(md|json)$/i.test(resuelta)) {
+    console.error('Error: solo se pueden marcar componentes .md o .json');
+    process.exitCode = 1;
+    return;
+  }
+  let from = opciones.from;
+  if (!from) {
+    try {
+      from = require(path.resolve(process.cwd(), 'package.json')).version;
+    } catch {
+      from = undefined;
+    }
+  }
+  const meta = { from, by: opciones.by || 'aprender' };
+  if (opciones.note) meta.note = opciones.note;
+  if (opciones.rounds) meta.rounds = Number(opciones.rounds);
+  if (opciones.score) meta.score = opciones.score;
+
+  const r = markAsEvolved(ruta, meta);
+  console.log(r.marked ? 'Marcado como evolucionado' : 'Error: ' + r.error);
+  if (!r.marked) process.exitCode = 1;
+}
+
+module.exports = markEvolved;

package/scripts/cli/metricas-dora.js

@@ -1,26 +1,26 @@
-'use strict';
-
-/**
- * Wrapper CLI `swl-ses metricas-dora` — calcula métricas DORA del repo actual.
- * Reemplaza `node scripts/lib/metricas-dora.js` relativo al proyecto (roto
- * downstream; ver docs/invocacion-cli-cross-scope.md).
- *
- * Uso: swl-ses metricas-dora [--json] [--dias=N]
- */
-
-const { calcularDora, persistir } = require('../lib/metricas-dora');
-
-function metricasDora(opciones = {}) {
-  const dias = Number(opciones.dias);
-  const ventanaDias = Math.max(1, Math.min(365, Number.isFinite(dias) && dias > 0 ? dias : 30));
-  const baseDir = process.cwd();
-  const dora = calcularDora(baseDir, { ventanaDias });
-  try {
-    persistir(baseDir, dora);
-  } catch {
-    /* persistencia best-effort: no romper el informe si el disco falla */
-  }
-  console.log(JSON.stringify(dora, null, 2));
-}
-
-module.exports = metricasDora;
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses metricas-dora` — calcula métricas DORA del repo actual.
+ * Reemplaza `node scripts/lib/metricas-dora.js` relativo al proyecto (roto
+ * downstream; ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses metricas-dora [--json] [--dias=N]
+ */
+
+const { calcularDora, persistir } = require('../lib/metricas-dora');
+
+function metricasDora(opciones = {}) {
+  const dias = Number(opciones.dias);
+  const ventanaDias = Math.max(1, Math.min(365, Number.isFinite(dias) && dias > 0 ? dias : 30));
+  const baseDir = process.cwd();
+  const dora = calcularDora(baseDir, { ventanaDias });
+  try {
+    persistir(baseDir, dora);
+  } catch {
+    /* persistencia best-effort: no romper el informe si el disco falla */
+  }
+  console.log(JSON.stringify(dora, null, 2));
+}
+
+module.exports = metricasDora;

package/scripts/cli/near-duplicate.js

@@ -1,55 +1,55 @@
-'use strict';
-
-/**
- * Wrapper CLI `swl-ses near-duplicate` — detecta si un aprendizaje nuevo es
- * duplicado cercano de los existentes en APRENDIZAJES.md. Reemplaza el inline
- * `require('./hooks/lib/fingerprint-id')` relativo al proyecto (roto downstream;
- * ver docs/invocacion-cli-cross-scope.md).
- *
- * Uso: swl-ses near-duplicate --texto="..." [--archivo=ruta] [--threshold=0.6]
- *      echo "texto..." | swl-ses near-duplicate [--archivo=ruta]
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { isNearDuplicate } = require('../../hooks/lib/fingerprint-id');
-
-function nearDuplicate(opciones = {}) {
-  const archivo = opciones.archivo || '.planning/APRENDIZAJES.md';
-  let nuevo = opciones.texto;
-  if (!nuevo && !process.stdin.isTTY) {
-    try {
-      nuevo = fs.readFileSync(0, 'utf8');
-    } catch {
-      nuevo = '';
-    }
-  }
-  if (!nuevo) {
-    console.error('Error: falta --texto="..." o entrada por stdin');
-    process.exitCode = 1;
-    return;
-  }
-  // Guard anti path-traversal: --archivo debe resolver dentro del proyecto.
-  const cwd = process.cwd();
-  const resuelta = path.resolve(cwd, archivo);
-  if (resuelta !== cwd && !resuelta.startsWith(cwd + path.sep)) {
-    console.error('Error: --archivo debe estar dentro del proyecto actual');
-    process.exitCode = 1;
-    return;
-  }
-  let existentes = [];
-  try {
-    existentes = fs.readFileSync(resuelta, 'utf8').split(/^## /m).filter(Boolean);
-  } catch (e) {
-    // Sin archivo de aprendizajes legible: avisar (no degradar en silencio) y
-    // tratar todo como único.
-    if (e.code !== 'ENOENT') console.error('[near-duplicate] aviso: ' + e.code);
-  }
-  const t = Number(opciones.threshold);
-  const threshold = Number.isFinite(t) && t > 0 ? t : 0.6;
-
-  const r = isNearDuplicate(nuevo, existentes, threshold);
-  console.log(r.nearDuplicate ? 'DUPLICADO (sim=' + r.similarity + ')' : 'ÚNICO');
-}
-
-module.exports = nearDuplicate;
+'use strict';
+
+/**
+ * Wrapper CLI `swl-ses near-duplicate` — detecta si un aprendizaje nuevo es
+ * duplicado cercano de los existentes en APRENDIZAJES.md. Reemplaza el inline
+ * `require('./hooks/lib/fingerprint-id')` relativo al proyecto (roto downstream;
+ * ver docs/invocacion-cli-cross-scope.md).
+ *
+ * Uso: swl-ses near-duplicate --texto="..." [--archivo=ruta] [--threshold=0.6]
+ *      echo "texto..." | swl-ses near-duplicate [--archivo=ruta]
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { isNearDuplicate } = require('../../hooks/lib/fingerprint-id');
+
+function nearDuplicate(opciones = {}) {
+  const archivo = opciones.archivo || '.planning/APRENDIZAJES.md';
+  let nuevo = opciones.texto;
+  if (!nuevo && !process.stdin.isTTY) {
+    try {
+      nuevo = fs.readFileSync(0, 'utf8');
+    } catch {
+      nuevo = '';
+    }
+  }
+  if (!nuevo) {
+    console.error('Error: falta --texto="..." o entrada por stdin');
+    process.exitCode = 1;
+    return;
+  }
+  // Guard anti path-traversal: --archivo debe resolver dentro del proyecto.
+  const cwd = process.cwd();
+  const resuelta = path.resolve(cwd, archivo);
+  if (resuelta !== cwd && !resuelta.startsWith(cwd + path.sep)) {
+    console.error('Error: --archivo debe estar dentro del proyecto actual');
+    process.exitCode = 1;
+    return;
+  }
+  let existentes = [];
+  try {
+    existentes = fs.readFileSync(resuelta, 'utf8').split(/^## /m).filter(Boolean);
+  } catch (e) {
+    // Sin archivo de aprendizajes legible: avisar (no degradar en silencio) y
+    // tratar todo como único.
+    if (e.code !== 'ENOENT') console.error('[near-duplicate] aviso: ' + e.code);
+  }
+  const t = Number(opciones.threshold);
+  const threshold = Number.isFinite(t) && t > 0 ? t : 0.6;
+
+  const r = isNearDuplicate(nuevo, existentes, threshold);
+  console.log(r.nearDuplicate ? 'DUPLICADO (sim=' + r.similarity + ')' : 'ÚNICO');
+}
+
+module.exports = nearDuplicate;