@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/lib/provenance-tracker.js

@@ -1,191 +1,191 @@
-'use strict';
-
-/**
- * Provenance Tracker — Rastreo de proveniencia de skills y componentes.
- *
- * Registra de dónde viene cada skill/agente instalado: si es del core SWL,
- * de un repo externo, de auto-evolución, o de la comunidad. Genera y lee
- * archivos meta.json por componente.
- *
- * Patrón adoptado de skillshare (internal/install/meta.go).
- *
- * Zero dependencias externas.
- *
- * Uso:
- *   const { registrarProveniencia, leerProveniencia, listarProveniencias } = require('./lib/provenance-tracker');
- *
- *   registrarProveniencia('/ruta/skill', {
- *     origin: 'core',
- *     repoUrl: 'https://github.com/saulwadeleon/swl-ses',
- *     version: '5.6.3',
- *   });
- *
- *   const meta = leerProveniencia('/ruta/skill');
- *   // { origin: 'core', repoUrl: '...', version: '5.6.3', installedAt: '...' }
- *
- * @module hooks/lib/provenance-tracker
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-// Escritura atómica obligatoria para meta.json (regla CLAUDE.md).
-let atomicWriteJSON;
-try {
-  ({ atomicWriteJSON } = require('./atomic-write'));
-} catch {
-  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
-}
-
-// ---------------------------------------------------------------------------
-// Constantes
-// ---------------------------------------------------------------------------
-
-const META_FILENAME = 'meta.json';
-
-/**
- * Orígenes válidos de un componente.
- * @readonly
- */
-const ORIGENES = Object.freeze({
-  CORE:           'core',           // Del paquete swl-ses
-  AUTO_EVOLUTION: 'auto-evolution', // Generado por /swl:evolucionar
-  IMPORTED:       'imported',       // Importado de repo externo
-  COMMUNITY:      'community',     // De skills.sh o similares
-  USERLAND:       'userland',       // Del usuario (_userland/)
-  ANTHROPIC:      'anthropic',      // De anthropics/skills
-});
-
-// ---------------------------------------------------------------------------
-// API pública
-// ---------------------------------------------------------------------------
-
-/**
- * Registra la proveniencia de un componente instalado.
- *
- * Crea o actualiza meta.json en el directorio del componente.
- *
- * @param {string} componentDir - Ruta al directorio del componente
- * @param {object} datos
- * @param {string} datos.origin     - Origen (ver ORIGENES)
- * @param {string} [datos.repoUrl]  - URL del repo de origen
- * @param {string} [datos.commit]   - Commit hash del origen
- * @param {string} [datos.version]  - Versión del sistema al instalar
- * @param {string} [datos.author]   - Autor o equipo
- * @param {string} [datos.note]     - Nota libre
- */
-function registrarProveniencia(componentDir, datos) {
-  const metaPath = path.join(componentDir, META_FILENAME);
-
-  const meta = {
-    origin: datos.origin || ORIGENES.CORE,
-    repoUrl: datos.repoUrl || null,
-    commit: datos.commit || null,
-    version: datos.version || null,
-    author: datos.author || null,
-    note: datos.note || null,
-    installedAt: new Date().toISOString(),
-    installedBy: `swl-ses v${datos.version || 'unknown'}`,
-  };
-
-  // Si ya existe, preservar datos anteriores y agregar historial
-  if (fs.existsSync(metaPath)) {
-    try {
-      const existing = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-      // Mover datos anteriores a historial
-      if (!existing.history) existing.history = [];
-      const { history, ...prevData } = existing;
-      existing.history.push({ ...prevData, replacedAt: meta.installedAt });
-
-      // Actualizar con nuevos datos
-      Object.assign(existing, meta);
-      existing.history = existing.history.slice(-5); // Máximo 5 entradas de historial
-
-      atomicWriteJSON(metaPath, existing);
-    } catch {
-      // Error leyendo existente — sobrescribir
-      atomicWriteJSON(metaPath, meta);
-    }
-  } else {
-    atomicWriteJSON(metaPath, meta);
-  }
-}
-
-/**
- * Lee la proveniencia de un componente.
- *
- * @param {string} componentDir - Ruta al directorio del componente
- * @returns {object|null} Datos de proveniencia o null si no existe
- */
-function leerProveniencia(componentDir) {
-  const metaPath = path.join(componentDir, META_FILENAME);
-  if (!fs.existsSync(metaPath)) return null;
-
-  try {
-    return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Lista la proveniencia de todos los componentes en un directorio.
- *
- * @param {string} parentDir - Directorio padre (ej: habilidades/)
- * @returns {Array<{ name: string, origin: string, version: string, installedAt: string }>}
- */
-function listarProveniencias(parentDir) {
-  if (!fs.existsSync(parentDir)) return [];
-
-  const resultado = [];
-  const entries = fs.readdirSync(parentDir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const meta = leerProveniencia(path.join(parentDir, entry.name));
-    resultado.push({
-      name: entry.name,
-      origin: meta ? meta.origin : 'unknown',
-      version: meta ? meta.version : null,
-      installedAt: meta ? meta.installedAt : null,
-      repoUrl: meta ? meta.repoUrl : null,
-    });
-  }
-
-  return resultado;
-}
-
-/**
- * Genera un resumen de proveniencia por origen.
- *
- * @param {string} parentDir - Directorio padre
- * @returns {{ total: number, byOrigin: Object<string, number>, unknown: number }}
- */
-function resumenProveniencia(parentDir) {
-  const lista = listarProveniencias(parentDir);
-  const byOrigin = {};
-  let unknown = 0;
-
-  for (const item of lista) {
-    if (item.origin === 'unknown') {
-      unknown++;
-    } else {
-      byOrigin[item.origin] = (byOrigin[item.origin] || 0) + 1;
-    }
-  }
-
-  return { total: lista.length, byOrigin, unknown };
-}
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-module.exports = {
-  registrarProveniencia,
-  leerProveniencia,
-  listarProveniencias,
-  resumenProveniencia,
-  ORIGENES,
-  META_FILENAME,
-};
+'use strict';
+
+/**
+ * Provenance Tracker — Rastreo de proveniencia de skills y componentes.
+ *
+ * Registra de dónde viene cada skill/agente instalado: si es del core SWL,
+ * de un repo externo, de auto-evolución, o de la comunidad. Genera y lee
+ * archivos meta.json por componente.
+ *
+ * Patrón adoptado de skillshare (internal/install/meta.go).
+ *
+ * Zero dependencias externas.
+ *
+ * Uso:
+ *   const { registrarProveniencia, leerProveniencia, listarProveniencias } = require('./lib/provenance-tracker');
+ *
+ *   registrarProveniencia('/ruta/skill', {
+ *     origin: 'core',
+ *     repoUrl: 'https://github.com/saulwadeleon/swl-ses',
+ *     version: '5.6.3',
+ *   });
+ *
+ *   const meta = leerProveniencia('/ruta/skill');
+ *   // { origin: 'core', repoUrl: '...', version: '5.6.3', installedAt: '...' }
+ *
+ * @module hooks/lib/provenance-tracker
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Escritura atómica obligatoria para meta.json (regla CLAUDE.md).
+let atomicWriteJSON;
+try {
+  ({ atomicWriteJSON } = require('./atomic-write'));
+} catch {
+  atomicWriteJSON = (p, o) => fs.writeFileSync(p, JSON.stringify(o, null, 2), 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const META_FILENAME = 'meta.json';
+
+/**
+ * Orígenes válidos de un componente.
+ * @readonly
+ */
+const ORIGENES = Object.freeze({
+  CORE:           'core',           // Del paquete swl-ses
+  AUTO_EVOLUTION: 'auto-evolution', // Generado por /swl:evolucionar
+  IMPORTED:       'imported',       // Importado de repo externo
+  COMMUNITY:      'community',     // De skills.sh o similares
+  USERLAND:       'userland',       // Del usuario (_userland/)
+  ANTHROPIC:      'anthropic',      // De anthropics/skills
+});
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra la proveniencia de un componente instalado.
+ *
+ * Crea o actualiza meta.json en el directorio del componente.
+ *
+ * @param {string} componentDir - Ruta al directorio del componente
+ * @param {object} datos
+ * @param {string} datos.origin     - Origen (ver ORIGENES)
+ * @param {string} [datos.repoUrl]  - URL del repo de origen
+ * @param {string} [datos.commit]   - Commit hash del origen
+ * @param {string} [datos.version]  - Versión del sistema al instalar
+ * @param {string} [datos.author]   - Autor o equipo
+ * @param {string} [datos.note]     - Nota libre
+ */
+function registrarProveniencia(componentDir, datos) {
+  const metaPath = path.join(componentDir, META_FILENAME);
+
+  const meta = {
+    origin: datos.origin || ORIGENES.CORE,
+    repoUrl: datos.repoUrl || null,
+    commit: datos.commit || null,
+    version: datos.version || null,
+    author: datos.author || null,
+    note: datos.note || null,
+    installedAt: new Date().toISOString(),
+    installedBy: `swl-ses v${datos.version || 'unknown'}`,
+  };
+
+  // Si ya existe, preservar datos anteriores y agregar historial
+  if (fs.existsSync(metaPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      // Mover datos anteriores a historial
+      if (!existing.history) existing.history = [];
+      const { history, ...prevData } = existing;
+      existing.history.push({ ...prevData, replacedAt: meta.installedAt });
+
+      // Actualizar con nuevos datos
+      Object.assign(existing, meta);
+      existing.history = existing.history.slice(-5); // Máximo 5 entradas de historial
+
+      atomicWriteJSON(metaPath, existing);
+    } catch {
+      // Error leyendo existente — sobrescribir
+      atomicWriteJSON(metaPath, meta);
+    }
+  } else {
+    atomicWriteJSON(metaPath, meta);
+  }
+}
+
+/**
+ * Lee la proveniencia de un componente.
+ *
+ * @param {string} componentDir - Ruta al directorio del componente
+ * @returns {object|null} Datos de proveniencia o null si no existe
+ */
+function leerProveniencia(componentDir) {
+  const metaPath = path.join(componentDir, META_FILENAME);
+  if (!fs.existsSync(metaPath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lista la proveniencia de todos los componentes en un directorio.
+ *
+ * @param {string} parentDir - Directorio padre (ej: habilidades/)
+ * @returns {Array<{ name: string, origin: string, version: string, installedAt: string }>}
+ */
+function listarProveniencias(parentDir) {
+  if (!fs.existsSync(parentDir)) return [];
+
+  const resultado = [];
+  const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = leerProveniencia(path.join(parentDir, entry.name));
+    resultado.push({
+      name: entry.name,
+      origin: meta ? meta.origin : 'unknown',
+      version: meta ? meta.version : null,
+      installedAt: meta ? meta.installedAt : null,
+      repoUrl: meta ? meta.repoUrl : null,
+    });
+  }
+
+  return resultado;
+}
+
+/**
+ * Genera un resumen de proveniencia por origen.
+ *
+ * @param {string} parentDir - Directorio padre
+ * @returns {{ total: number, byOrigin: Object<string, number>, unknown: number }}
+ */
+function resumenProveniencia(parentDir) {
+  const lista = listarProveniencias(parentDir);
+  const byOrigin = {};
+  let unknown = 0;
+
+  for (const item of lista) {
+    if (item.origin === 'unknown') {
+      unknown++;
+    } else {
+      byOrigin[item.origin] = (byOrigin[item.origin] || 0) + 1;
+    }
+  }
+
+  return { total: lista.length, byOrigin, unknown };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  registrarProveniencia,
+  leerProveniencia,
+  listarProveniencias,
+  resumenProveniencia,
+  ORIGENES,
+  META_FILENAME,
+};