@saulwade/swl-ses 1.0.0

package/scripts/lib/skill-metrics.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * skill-metrics.js — Métricas de uso y rendimiento de habilidades SWL.
+ *
+ * Portado del patrón de persistencia de Multica (skill success tracking).
+ * Registra invocaciones de habilidades con estado y duración para:
+ *   - Identificar skills con alta tasa de error (candidatos a evolución)
+ *   - Detectar skills lentos (duración promedio alta)
+ *   - Respaldar el diagnóstico de /swl:aprender Paso 7.5
+ *   - Alimentar el dashboard de /swl:metricas
+ *
+ * Almacena entradas brutas en .planning/skill-metrics.json (append atómico).
+ * Las métricas agregadas se calculan on-demand desde las entradas brutas.
+ *
+ * API:
+ *   registrarUso(cwd, skillName, estado, duracionMs) → void
+ *   obtenerMetricas(cwd)                              → SkillMetric[]
+ *   topFallidos(cwd, n)                               → SkillMetric[]
+ *   topLentos(cwd, n)                                 → SkillMetric[]
+ *   resumen(cwd)                                      → ResumenMetricas
+ *
+ * Uso CLI:
+ *   node scripts/lib/skill-metrics.js            → resumen en tabla
+ *   node scripts/lib/skill-metrics.js json        → métricas por skill en JSON
+ *
+ * @module scripts/lib/skill-metrics
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const atomicWritePath = path.join(__dirname, '..', '..', 'hooks', 'lib', 'atomic-write.js');
+const { atomicWriteJSON } = require(atomicWritePath);
+
+const METRICS_FILE = path.join('.planning', 'skill-metrics.json');
+const MAX_ENTRIES  = 10_000; // límite de entradas brutas (purgar las más antiguas)
+const MIN_USOS     = 3;      // mínimo de invocaciones para aparecer en top-fallidos/lentos
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee el archivo de métricas. Retorna estructura vacía si no existe.
+ *
+ * @param {string} cwd
+ * @returns {{ version: number, entries: object[] }}
+ */
+function leerMetricas(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, METRICS_FILE), 'utf8'));
+  } catch (_) {
+    return { version: 1, entries: [] };
+  }
+}
+
+/**
+ * Escribe el archivo de métricas de forma atómica.
+ *
+ * @param {string} cwd
+ * @param {{ version: number, entries: object[] }} datos
+ */
+function escribirMetricas(cwd, datos) {
+  const planDir = path.join(cwd, '.planning');
+  if (!fs.existsSync(planDir)) fs.mkdirSync(planDir, { recursive: true });
+  atomicWriteJSON(path.join(cwd, METRICS_FILE), datos);
+}
+
+// ---------------------------------------------------------------------------
+// API pública
+// ---------------------------------------------------------------------------
+
+/**
+ * Registra una invocación de habilidad.
+ *
+ * @param {string} cwd
+ * @param {string} skillName                 - Nombre del skill (ej: 'fastapi-experto')
+ * @param {'ok'|'error'|'skip'} estado       - Resultado de la invocación
+ * @param {number} [duracionMs=0]            - Duración en milisegundos
+ */
+function registrarUso(cwd, skillName, estado, duracionMs = 0) {
+  const datos = leerMetricas(cwd);
+
+  datos.entries.push({
+    skill:      String(skillName),
+    estado:     String(estado),
+    duracionMs: Number(duracionMs) || 0,
+    timestamp:  new Date().toISOString(),
+  });
+
+  // Purgar si supera el límite (eliminar las entradas más antiguas)
+  if (datos.entries.length > MAX_ENTRIES) {
+    datos.entries.splice(0, datos.entries.length - MAX_ENTRIES);
+  }
+
+  escribirMetricas(cwd, datos);
+}
+
+/**
+ * Agrega las entradas brutas en métricas por skill.
+ *
+ * @param {string} cwd
+ * @returns {Array<{
+ *   skill: string,
+ *   total: number,
+ *   ok: number,
+ *   error: number,
+ *   skip: number,
+ *   tasaError: number,
+ *   duracionPromMs: number,
+ *   ultimoUso: string
+ * }>}
+ */
+function obtenerMetricas(cwd) {
+  const datos = leerMetricas(cwd);
+  const mapa  = Object.create(null);
+
+  for (const entry of datos.entries) {
+    const skill = entry.skill;
+    if (!mapa[skill]) {
+      mapa[skill] = { skill, total: 0, ok: 0, error: 0, skip: 0, duracionTotal: 0, ultimoUso: '' };
+    }
+    const m = mapa[skill];
+    m.total++;
+    if (entry.estado === 'ok')    m.ok++;
+    if (entry.estado === 'error') m.error++;
+    if (entry.estado === 'skip')  m.skip++;
+    m.duracionTotal += Number(entry.duracionMs) || 0;
+    if (entry.timestamp > m.ultimoUso) m.ultimoUso = entry.timestamp;
+  }
+
+  return Object.values(mapa).map(m => ({
+    skill:          m.skill,
+    total:          m.total,
+    ok:             m.ok,
+    error:          m.error,
+    skip:           m.skip,
+    tasaError:      m.total > 0 ? +(m.error / m.total).toFixed(3) : 0,
+    duracionPromMs: m.total > 0 ? Math.round(m.duracionTotal / m.total) : 0,
+    ultimoUso:      m.ultimoUso,
+  }));
+}
+
+/**
+ * Top N skills con mayor tasa de error (mínimo MIN_USOS invocaciones).
+ *
+ * @param {string} cwd
+ * @param {number} [n=5]
+ * @returns {object[]}
+ */
+function topFallidos(cwd, n = 5) {
+  return obtenerMetricas(cwd)
+    .filter(m => m.total >= MIN_USOS)
+    .sort((a, b) => b.tasaError - a.tasaError || b.total - a.total)
+    .slice(0, n);
+}
+
+/**
+ * Top N skills más lentos por duración promedio (mínimo MIN_USOS invocaciones).
+ *
+ * @param {string} cwd
+ * @param {number} [n=5]
+ * @returns {object[]}
+ */
+function topLentos(cwd, n = 5) {
+  return obtenerMetricas(cwd)
+    .filter(m => m.total >= MIN_USOS)
+    .sort((a, b) => b.duracionPromMs - a.duracionPromMs)
+    .slice(0, n);
+}
+
+/**
+ * Resumen global de métricas de habilidades.
+ *
+ * @param {string} cwd
+ * @returns {{
+ *   totalSkills: number,
+ *   totalInvocaciones: number,
+ *   tasaErrorGlobal: number,
+ *   topFallidos: object[],
+ *   topLentos: object[],
+ *   generadoEn: string
+ * }}
+ */
+function resumen(cwd) {
+  const metricas = obtenerMetricas(cwd);
+  const total    = metricas.reduce((acc, m) => acc + m.total,  0);
+  const errores  = metricas.reduce((acc, m) => acc + m.error, 0);
+
+  return {
+    totalSkills:       metricas.length,
+    totalInvocaciones: total,
+    tasaErrorGlobal:   total > 0 ? +(errores / total).toFixed(3) : 0,
+    topFallidos:       topFallidos(cwd, 5),
+    topLentos:         topLentos(cwd, 5),
+    generadoEn:        new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { registrarUso, obtenerMetricas, topFallidos, topLentos, resumen };
+
+// ---------------------------------------------------------------------------
+// CLI dual-use
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  const cwd = process.cwd();
+  const cmd = process.argv[2] || 'resumen';
+
+  if (cmd === 'json') {
+    process.stdout.write(JSON.stringify(obtenerMetricas(cwd), null, 2) + '\n');
+    process.exit(0);
+  }
+
+  // Modo resumen (default)
+  const r = resumen(cwd);
+  process.stdout.write('\nMétricas de habilidades SWL\n');
+  process.stdout.write('─'.repeat(52) + '\n');
+  process.stdout.write(`Skills registrados:   ${r.totalSkills}\n`);
+  process.stdout.write(`Total invocaciones:   ${r.totalInvocaciones}\n`);
+  process.stdout.write(`Tasa error global:    ${(r.tasaErrorGlobal * 100).toFixed(1)}%\n`);
+
+  if (r.topFallidos.length > 0) {
+    process.stdout.write('\nTop skills con errores:\n');
+    for (const m of r.topFallidos) {
+      const pct = `${(m.tasaError * 100).toFixed(0)}%`.padStart(5);
+      process.stdout.write(`  ${m.skill.padEnd(36)} ${pct} error  (${m.total} usos)\n`);
+    }
+  }
+
+  if (r.topLentos.length > 0) {
+    process.stdout.write('\nTop skills más lentos:\n');
+    for (const m of r.topLentos) {
+      const ms = `${m.duracionPromMs}ms`.padStart(8);
+      process.stdout.write(`  ${m.skill.padEnd(36)} ${ms} prom   (${m.total} usos)\n`);
+    }
+  }
+
+  process.stdout.write('\n');
+}

package/scripts/lib/skill-normalizer.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * Módulo: skill-normalizer.js
+ * Normaliza frontmatter de skills aplicando la regla de 3 capas de swl-ses.
+ * Campos propios del sistema deben estar en español; los alias en inglés son legacy.
+ * Zero-deps, solo Node stdlib.
+ *
+ * Referencia: REC-S15 del reporte analisis-skill-authoring-patterns-2026-04-19.md.
+ */
+
+// Pares alias-inglés → canónico-español
+const ALIASES = Object.freeze({
+  provenance: 'procedencia',
+  targets: 'destinos',
+  evolvable: 'evolucionable',
+  evolvable_scope: 'evolucionable_alcance',
+});
+
+// Campos del protocolo Anthropic que se dejan tal cual (no se renombran)
+const PROTOCOL_FIELDS = Object.freeze(new Set([
+  'name', 'description', 'user-invocable', 'allowed-tools',
+  'when_to_use', 'disable-model-invocation',
+]));
+
+/**
+ * Retorna el frontmatter con los alias en inglés promovidos a su equivalente
+ * en español cuando el español no está presente. Preserva campos de protocolo.
+ *
+ * @param {object} frontmatter - Frontmatter ya parseado.
+ * @returns {object} Frontmatter normalizado.
+ */
+function normalizar(frontmatter) {
+  if (!frontmatter || typeof frontmatter !== 'object') return frontmatter;
+  const out = { ...frontmatter };
+  for (const [legacy, canonico] of Object.entries(ALIASES)) {
+    if (out[legacy] !== undefined && out[canonico] === undefined) {
+      out[canonico] = out[legacy];
+    }
+  }
+  return out;
+}
+
+/**
+ * Detecta divergencias entre campos alias y su equivalente en español.
+ * Retorna array de warnings W010 (uno por par divergente).
+ *
+ * @param {object} frontmatter
+ * @returns {Array<{codigo: string, par: [string,string], valorLegacy: *, valorCanonico: *}>}
+ */
+function detectarDivergencias(frontmatter) {
+  if (!frontmatter || typeof frontmatter !== 'object') return [];
+  const warnings = [];
+  for (const [legacy, canonico] of Object.entries(ALIASES)) {
+    if (tieneAmbos(frontmatter, legacy, canonico)) {
+      const igualJSON = JSON.stringify(frontmatter[legacy]) === JSON.stringify(frontmatter[canonico]);
+      if (!igualJSON) {
+        warnings.push({
+          codigo: 'W010',
+          par: [legacy, canonico],
+          valorLegacy: frontmatter[legacy],
+          valorCanonico: frontmatter[canonico],
+          mensaje: `W010 ALIAS_DIVERGENTE: '${legacy}' y '${canonico}' tienen valores distintos.`,
+        });
+      }
+    }
+  }
+  return warnings;
+}
+
+/**
+ * Verifica si el frontmatter contiene ambos campos (legacy e inglés).
+ *
+ * @param {object} fm - Frontmatter parseado.
+ * @param {string} a - Campo legacy en inglés.
+ * @param {string} b - Campo canónico en español.
+ * @returns {boolean}
+ */
+function tieneAmbos(fm, a, b) {
+  return fm[a] !== undefined && fm[b] !== undefined;
+}
+
+/**
+ * Detecta si un skill está usando el nombre legacy en inglés y debería
+ * migrarse al canónico en español. Retorna lista de sugerencias.
+ *
+ * @param {object} frontmatter
+ * @returns {Array<{codigo: string, campoLegacy: string, campoCanonico: string}>}
+ */
+function detectarUsoLegacy(frontmatter) {
+  if (!frontmatter || typeof frontmatter !== 'object') return [];
+  const sugerencias = [];
+  for (const [legacy, canonico] of Object.entries(ALIASES)) {
+    if (frontmatter[legacy] !== undefined && frontmatter[canonico] === undefined) {
+      sugerencias.push({
+        codigo: 'W010',
+        campoLegacy: legacy,
+        campoCanonico: canonico,
+        mensaje: `W010 USO_LEGACY: '${legacy}' esta en uso; migrar a '${canonico}' (espanol SWL).`,
+      });
+    }
+  }
+  return sugerencias;
+}
+
+module.exports = {
+  ALIASES,
+  PROTOCOL_FIELDS,
+  normalizar,
+  detectarDivergencias,
+  detectarUsoLegacy,
+};

package/scripts/lib/skills-hub.js

@@ -0,0 +1,340 @@
+'use strict';
+
+/**
+ * Skills Hub — Cliente para descubrimiento e instalación de plugins SWL.
+ *
+ * Implementación GitHub-based (v1):
+ *   - Registro = repositorios GitHub con topic "swl-plugin"
+ *   - Búsqueda via GitHub API (sin autenticación para búsqueda pública)
+ *   - Instalación via git clone --depth 1
+ *   - Validación contra schemas/plugin.schema.json
+ *   - Escaneo de seguridad con prompt-injection-scanner
+ *
+ * Inspirado en Hermes Agent (hermes_cli/skills_hub.py → agentskills.io).
+ *
+ * @module scripts/lib/skills-hub
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const https = require('https');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const PLUGINS_DIR    = '_userland/plugins';
+const PLUGINS_RECORD = '.planning/PLUGINS.md';
+const GITHUB_API     = 'https://api.github.com';
+const SEARCH_TOPIC   = 'swl-plugin';
+const USER_AGENT     = 'SWL-SES-SkillsHub/1.0';
+
+// ---------------------------------------------------------------------------
+// Búsqueda
+// ---------------------------------------------------------------------------
+
+/**
+ * Busca plugins en GitHub por topic "swl-plugin".
+ *
+ * @param {string} query - Texto de búsqueda.
+ * @param {object} [opts]
+ * @param {string} [opts.sort='stars']  - Ordenar por: stars, updated, relevance.
+ * @param {number} [opts.limit=20]      - Máximo de resultados.
+ * @returns {Promise<object[]>} Array de resultados.
+ */
+async function search(query, opts = {}) {
+  const sort  = opts.sort || 'stars';
+  const limit = opts.limit || 20;
+
+  const q = encodeURIComponent(`topic:${SEARCH_TOPIC} ${query}`);
+  const url = `${GITHUB_API}/search/repositories?q=${q}&sort=${sort}&per_page=${limit}`;
+
+  const data = await _fetchJSON(url);
+
+  return (data.items || []).map(repo => ({
+    name:        repo.name,
+    fullName:    repo.full_name,
+    description: repo.description || '',
+    url:         repo.html_url,
+    cloneUrl:    repo.clone_url,
+    stars:       repo.stargazers_count,
+    updated:     repo.updated_at,
+    author:      repo.owner?.login || 'unknown',
+    license:     repo.license?.spdx_id || 'unknown',
+    topics:      repo.topics || [],
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Instalación
+// ---------------------------------------------------------------------------
+
+/**
+ * Instala un plugin desde un repositorio GitHub.
+ *
+ * @param {string} repoUrl  - URL del repositorio (https://github.com/user/repo).
+ * @param {string} baseDir  - Directorio raíz del proyecto SWL.
+ * @returns {{ success: boolean, error?: string, name?: string, path?: string }}
+ */
+function install(repoUrl, baseDir) {
+  // Validar URL (solo GitHub)
+  if (!repoUrl.includes('github.com')) {
+    return { success: false, error: 'Solo se permiten repositorios de GitHub.' };
+  }
+
+  // Extraer nombre del repo
+  const match = repoUrl.match(/github\.com\/[\w.-]+\/([\w.-]+)/);
+  if (!match) {
+    return { success: false, error: `URL no válida: ${repoUrl}` };
+  }
+
+  const repoName  = match[1].replace(/\.git$/, '');
+  const pluginDir = path.join(baseDir, PLUGINS_DIR, repoName);
+
+  // Verificar si ya está instalado
+  if (fs.existsSync(pluginDir)) {
+    return { success: false, error: `Plugin "${repoName}" ya está instalado en ${pluginDir}` };
+  }
+
+  // Clonar
+  try {
+    const pluginsBase = path.join(baseDir, PLUGINS_DIR);
+    if (!fs.existsSync(pluginsBase)) fs.mkdirSync(pluginsBase, { recursive: true });
+
+    execSync(`git clone --depth 1 "${repoUrl}" "${pluginDir}"`, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 30000,
+    });
+  } catch (err) {
+    return { success: false, error: `Error clonando: ${err.message}` };
+  }
+
+  // Validar plugin-manifest.json (o plugin.json)
+  const validation = validate(pluginDir);
+  if (!validation.valid) {
+    // Rollback: eliminar directorio clonado
+    try { fs.rmSync(pluginDir, { recursive: true, force: true }); } catch (_) {}
+    return { success: false, error: `Validación falló: ${validation.errors.join(', ')}` };
+  }
+
+  // Escanear por inyecciones de prompt
+  const scanResult = _scanPluginForThreats(pluginDir);
+  if (scanResult.blocked) {
+    try { fs.rmSync(pluginDir, { recursive: true, force: true }); } catch (_) {}
+    return { success: false, error: `Seguridad: ${scanResult.reason}` };
+  }
+
+  // Registrar en PLUGINS.md
+  _registerPlugin(baseDir, repoName, repoUrl, validation.manifest);
+
+  return { success: true, name: repoName, path: pluginDir };
+}
+
+/**
+ * Desinstala un plugin.
+ *
+ * @param {string} pluginName - Nombre del plugin.
+ * @param {string} baseDir
+ * @returns {{ success: boolean, error?: string }}
+ */
+function uninstall(pluginName, baseDir) {
+  const pluginDir = path.join(baseDir, PLUGINS_DIR, pluginName);
+
+  if (!fs.existsSync(pluginDir)) {
+    return { success: false, error: `Plugin "${pluginName}" no encontrado.` };
+  }
+
+  try {
+    fs.rmSync(pluginDir, { recursive: true, force: true });
+  } catch (err) {
+    return { success: false, error: `Error eliminando: ${err.message}` };
+  }
+
+  _unregisterPlugin(baseDir, pluginName);
+  return { success: true };
+}
+
+/**
+ * Lista plugins instalados.
+ *
+ * @param {string} baseDir
+ * @returns {object[]}
+ */
+function list(baseDir) {
+  const pluginsBase = path.join(baseDir, PLUGINS_DIR);
+  if (!fs.existsSync(pluginsBase)) return [];
+
+  return fs.readdirSync(pluginsBase)
+    .filter(d => {
+      const stat = fs.statSync(path.join(pluginsBase, d));
+      return stat.isDirectory();
+    })
+    .map(name => {
+      const manifest = _loadManifest(path.join(pluginsBase, name));
+      return {
+        name,
+        version:     manifest?.version || 'unknown',
+        description: manifest?.description || '',
+        author:      manifest?.author || 'unknown',
+        path:        path.join(pluginsBase, name),
+      };
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Validación
+// ---------------------------------------------------------------------------
+
+/**
+ * Valida un directorio de plugin contra el schema.
+ *
+ * @param {string} pluginDir
+ * @returns {{ valid: boolean, errors: string[], manifest?: object }}
+ */
+function validate(pluginDir) {
+  const errors = [];
+
+  // Buscar manifest
+  const manifest = _loadManifest(pluginDir);
+  if (!manifest) {
+    // Permitir plugins sin manifest si tienen al menos un SKILL.md
+    const hasSkill = _findFiles(pluginDir, 'SKILL.md').length > 0;
+    const hasAgent = _findFiles(pluginDir, '.md').filter(f => !f.includes('README')).length > 0;
+    if (!hasSkill && !hasAgent) {
+      errors.push('Sin plugin.json y sin SKILL.md ni agentes .md');
+    }
+    return { valid: errors.length === 0, errors };
+  }
+
+  // Validar campos requeridos
+  if (!manifest.name) errors.push('Campo "name" requerido en plugin.json');
+  if (!manifest.version) errors.push('Campo "version" requerido');
+  if (!manifest.description) errors.push('Campo "description" requerido');
+  if (manifest.name && !/^[a-z][a-z0-9-]+$/.test(manifest.name)) {
+    errors.push('Campo "name" debe ser kebab-case');
+  }
+  if (manifest.version && !/^\d+\.\d+\.\d+$/.test(manifest.version)) {
+    errors.push('Campo "version" debe ser SemVer (X.Y.Z)');
+  }
+
+  return { valid: errors.length === 0, errors, manifest };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+function _loadManifest(pluginDir) {
+  for (const name of ['plugin.json', 'plugin-manifest.json', 'package.json']) {
+    const p = path.join(pluginDir, name);
+    try {
+      if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch (_) {}
+  }
+  return null;
+}
+
+function _findFiles(dir, pattern) {
+  const results = [];
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        results.push(..._findFiles(full, pattern));
+      } else if (entry.name.includes(pattern) || entry.name.endsWith(pattern)) {
+        results.push(full);
+      }
+    }
+  } catch (_) {}
+  return results;
+}
+
+function _scanPluginForThreats(pluginDir) {
+  let scanner;
+  try {
+    scanner = require('../../hooks/lib/prompt-injection-scanner');
+  } catch (_) {
+    return { blocked: false }; // Scanner no disponible — permitir
+  }
+
+  const files = _findFiles(pluginDir, '.md')
+    .concat(_findFiles(pluginDir, '.yaml'))
+    .concat(_findFiles(pluginDir, '.yml'));
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, 'utf8');
+      const result  = scanner.scan(content, path.relative(pluginDir, file));
+      if (result.criticalCount > 0) {
+        return {
+          blocked: true,
+          reason: `Amenazas críticas en ${path.relative(pluginDir, file)}: ${result.threats.filter(t => t.severity === 'critical').map(t => t.type).join(', ')}`,
+        };
+      }
+    } catch (_) {}
+  }
+
+  return { blocked: false };
+}
+
+function _registerPlugin(baseDir, name, url, manifest) {
+  const recordPath = path.join(baseDir, PLUGINS_RECORD);
+  const dir = path.dirname(recordPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  let content = '';
+  try {
+    if (fs.existsSync(recordPath)) content = fs.readFileSync(recordPath, 'utf8');
+  } catch (_) {}
+
+  if (!content.includes('# Plugins Instalados')) {
+    content = '# Plugins Instalados\n\n' + content;
+  }
+
+  const entry = `- **${name}** v${manifest?.version || '?'} — ${manifest?.description || url} (${new Date().toISOString().split('T')[0]})\n`;
+
+  if (!content.includes(`**${name}**`)) {
+    content += entry;
+    try { fs.writeFileSync(recordPath, content, 'utf8'); } catch (_) {}
+  }
+}
+
+function _unregisterPlugin(baseDir, name) {
+  const recordPath = path.join(baseDir, PLUGINS_RECORD);
+  try {
+    if (!fs.existsSync(recordPath)) return;
+    let content = fs.readFileSync(recordPath, 'utf8');
+    content = content.replace(new RegExp(`^- \\*\\*${name}\\*\\*.*\\n`, 'm'), '');
+    fs.writeFileSync(recordPath, content, 'utf8');
+  } catch (_) {}
+}
+
+function _fetchJSON(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, {
+      headers: {
+        'User-Agent': USER_AGENT,
+        'Accept': 'application/vnd.github.v3+json',
+      },
+      timeout: 10000,
+    }, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch (err) {
+          reject(new Error(`JSON parse error: ${err.message}`));
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { search, install, uninstall, list, validate };