@saulwade/swl-ses 1.0.0

package/scripts/comandos/skills.js

@@ -0,0 +1,211 @@
+'use strict';
+
+const { listarComponentes, agregarComponente } = require('../lib/gestor-componentes');
+const { descubrirSkills, limpiarDescubrimiento } = require('../lib/resolver-externo');
+const { selectorCheckbox, mostrarBanner, mostrarInfoFuente } = require('../lib/selector-interactivo');
+
+const AYUDA = `
+swl-ses skills — Gestión de skills
+
+USO:
+  swl-ses skills <subcomando> [opciones]
+
+SUBCOMANDOS:
+  list                          Lista skills instalados
+  add <fuente> [--skill <n>]    Agrega skill desde repo Git o path local
+  remove <nombre>               Remueve un skill
+
+OPCIONES:
+  --target <runtime>    Runtime destino (default: claude)
+  --skill <nombre>      Nombre del skill a instalar directamente (sin selector)
+  --global              Operar en directorio global
+  --force               Sobreescribir sin confirmar
+  --all                 Instalar todos los skills sin preguntar
+
+FUENTES SOPORTADAS:
+  owner/repo                    GitHub shorthand
+  github:user/repo              GitHub con prefijo
+  https://github.com/user/repo  URL completa
+  ./path/local                  Path local
+
+EJEMPLOS:
+  swl-ses skills list
+  swl-ses skills add anthropics/skills
+  swl-ses skills add anthropics/skills --skill docx
+  swl-ses skills add https://github.com/user/repo --all
+  swl-ses skills add ./path/local/mi-skill
+  swl-ses skills remove mi-skill
+`;
+
+async function skills(subcomando, opciones) {
+  if (!subcomando || subcomando === 'help') {
+    console.log(AYUDA);
+    return;
+  }
+
+  switch (subcomando) {
+    case 'list': {
+      const resultado = listarComponentes('skills', opciones);
+      console.log(`\nSkills instalados (${resultado.total}):\n`);
+      if (resultado.total === 0) {
+        console.log('  (ninguno)');
+      } else {
+        console.log('  Nombre                          Fuente     Válido');
+        console.log('  ' + '-'.repeat(60));
+        for (const c of resultado.componentes) {
+          const nombre = c.nombre.padEnd(30);
+          const fuente = (c.fuente || 'sistema').padEnd(10);
+          const valido = c.valido ? 'sí' : 'no';
+          console.log(`  ${nombre}  ${fuente} ${valido}`);
+        }
+      }
+      console.log('');
+      break;
+    }
+
+    case 'add': {
+      const fuente = opciones._args && opciones._args[0];
+      if (!fuente) {
+        console.error('Error: Se requiere una fuente (URL Git, owner/repo, o path local)');
+        console.error('Ejemplo: swl-ses skills add anthropics/skills');
+        process.exit(1);
+      }
+
+      await agregarSkillsInteractivo(fuente, opciones);
+      break;
+    }
+
+    case 'remove': {
+      const nombre = opciones._args && opciones._args[0];
+      if (!nombre) {
+        console.error('Error: Se requiere el nombre del skill a remover');
+        process.exit(1);
+      }
+      console.log(`\nRemoviendo skill: ${nombre}\n`);
+      try {
+        const { removerComponente } = require('../lib/gestor-componentes');
+        removerComponente('skills', nombre, opciones);
+        console.log('\nSkill removido exitosamente.');
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      console.log('');
+      break;
+    }
+
+    default:
+      console.error(`Subcomando desconocido: "${subcomando}"`);
+      console.log(AYUDA);
+      process.exit(1);
+  }
+}
+
+async function agregarSkillsInteractivo(fuente, opciones) {
+  const skillDirecto = opciones.skill;
+  const instalarTodos = opciones.all || false;
+
+  // Si se especifica --skill, ir directo sin selector
+  if (skillDirecto) {
+    console.log(`\nAgregando skill "${skillDirecto}" desde: ${fuente}\n`);
+    try {
+      const resultado = agregarComponente('skills', fuente, {
+        ...opciones,
+        nombre: skillDirecto,
+      });
+      mostrarResultadoInstalacion(resultado);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Descubrir skills disponibles
+  mostrarBanner();
+
+  let info;
+  try {
+    process.stdout.write('  Clonando repositorio...');
+    info = descubrirSkills(fuente);
+    process.stdout.write('\r\x1b[K');
+  } catch (err) {
+    process.stdout.write('\r\x1b[K');
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (info.skills.length === 0) {
+    limpiarDescubrimiento(info);
+    console.error('  No se encontraron skills en la fuente.');
+    process.exit(1);
+  }
+
+  mostrarInfoFuente(info.fuente, info.skills.length);
+
+  let skillsAInstalar;
+
+  if (instalarTodos) {
+    skillsAInstalar = info.skills.map(s => s.nombre);
+    console.log(`  Instalando todos (${skillsAInstalar.length} skills)...\n`);
+  } else if (info.skills.length === 1) {
+    // Solo un skill: instalar directamente
+    skillsAInstalar = [info.skills[0].nombre];
+  } else {
+    // Selector interactivo
+    const items = info.skills
+      .sort((a, b) => a.nombre.localeCompare(b.nombre))
+      .map(s => ({ nombre: s.nombre, descripcion: s.descripcion }));
+
+    skillsAInstalar = await selectorCheckbox(
+      'Select skills to install',
+      items,
+      { todosSeleccionados: false }
+    );
+
+    if (skillsAInstalar.length === 0) {
+      console.log('\n  Instalación cancelada.\n');
+      limpiarDescubrimiento(info);
+      return;
+    }
+  }
+
+  // Instalar skills seleccionados reutilizando el repo ya clonado
+  console.log('');
+  let totalInstalados = 0;
+  const advertencias = [];
+
+  for (const nombre of skillsAInstalar) {
+    try {
+      const resultado = agregarComponente('skills', fuente, {
+        ...opciones,
+        nombre,
+        cacheDir: info.tmpDir,
+      });
+      totalInstalados += resultado.instalados.length;
+      advertencias.push(...resultado.advertencias);
+    } catch (err) {
+      advertencias.push(`${nombre}: ${err.message}`);
+    }
+  }
+
+  limpiarDescubrimiento(info);
+
+  console.log(`\n  \x1b[32m✓\x1b[0m Instalados: ${totalInstalados} skill${totalInstalados !== 1 ? 's' : ''}`);
+  if (advertencias.length > 0) {
+    console.log('  Advertencias:');
+    for (const a of advertencias) console.log(`    ! ${a}`);
+  }
+  console.log('');
+}
+
+function mostrarResultadoInstalacion(resultado) {
+  console.log(`\n  \x1b[32m✓\x1b[0m Instalados: ${resultado.instalados.length}`);
+  if (resultado.advertencias.length > 0) {
+    console.log('  Advertencias:');
+    for (const a of resultado.advertencias) console.log(`    ! ${a}`);
+  }
+  console.log('');
+}
+
+module.exports = skills;

package/scripts/configurar-branch-protection.js

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+/**
+ * configurar-branch-protection.js
+ *
+ * Aplica protección de rama a `main` en el repositorio GitHub del proyecto.
+ * Requiere `gh` CLI instalado y autenticado.
+ *
+ * Auto-detección de método:
+ *   - Repos privados en GitHub Free → usa GitHub Rulesets (API moderna, gratuita)
+ *   - Repos públicos o con plan Pro/Team/Enterprise → Branch protection rules (legacy)
+ *   - Se puede forzar el método con --prefer-rulesets o --prefer-classic
+ *
+ * Referencia API Rulesets: https://docs.github.com/en/rest/repos/rules
+ * Restricción de plan legacy: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
+ *
+ * Uso:
+ *   node scripts/configurar-branch-protection.js [--dry-run] [--approvals N]
+ *     [--prefer-rulesets] [--prefer-classic] [--bypass-always]
+ *
+ * Flags:
+ *   --dry-run           Muestra qué haría sin aplicar cambios.
+ *   --approvals N       Número de approvals requeridos (default: 1).
+ *   --prefer-rulesets   Fuerza Rulesets aunque el repo sea público o tenga Pro.
+ *   --prefer-classic    Fuerza branch protection legacy (puede fallar con 403 en Free privado).
+ *   --bypass-always     OrganizationAdmin puede saltarse las reglas con push directo
+ *                       a main, no solo dentro del flujo de PR. Solo activar para
+ *                       hotfix bloqueante o setup inicial sin CI configurado.
+ *                       Default es 'pull_request' (más seguro).
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+// --- Argumentos ---
+const args            = process.argv.slice(2);
+const isDryRun        = args.includes('--dry-run');
+const preferRulesets  = args.includes('--prefer-rulesets');
+const preferClassic   = args.includes('--prefer-classic');
+// Por defecto el bypass del owner solo aplica dentro del flujo de PR
+// (puede mergear sin esperar todos los status checks tras review). Para
+// permitir push directo a main sin pasar por PR (escenario de hotfix
+// urgente o setup inicial cuando los workflows aún no tienen secrets),
+// pasar --bypass-always explícitamente. Default endurecido: 'pull_request'.
+const bypassAlways    = args.includes('--bypass-always');
+const approvalsIdx    = args.indexOf('--approvals');
+const requiredApprovals = approvalsIdx !== -1 ? parseInt(args[approvalsIdx + 1], 10) : 1;
+
+// Status checks que deben pasar antes de hacer merge.
+// Incluye los jobs del ci.yml (test con matrix 22+24, smoke).
+const STATUS_CHECKS = [
+  'test (22)',
+  'test (24)',
+  'smoke',
+];
+
+const NOMBRE_RAMA = 'main';
+const NOMBRE_RULESET = 'swl-protection-main';
+
+// --- Helpers ---
+
+function ejecutar(cmd, argsList, opciones = {}) {
+  return execFileSync(cmd, argsList, {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    ...opciones,
+  }).trim();
+}
+
+function log(msg)      { process.stdout.write(msg + '\n'); }
+function logError(msg) { process.stderr.write('[ERROR] ' + msg + '\n'); }
+function logInfo(msg)  { process.stdout.write('[INFO] ' + msg + '\n'); }
+
+/**
+ * Ejecuta gh api con método + endpoint + payload opcional.
+ * Devuelve el body como string o lanza en caso de error.
+ *
+ * @param {string} metodo  GET, POST, PUT, PATCH, DELETE
+ * @param {string} endpoint  URL relativa a la API (sin host)
+ * @param {object|null} [payload]  Objeto que se serializa como JSON
+ * @returns {string}
+ */
+function ghApi(metodo, endpoint, payload) {
+  // --silent suprime stdout; lo aplicamos solo cuando no necesitamos la respuesta
+  // (típicamente PUT/POST de mutación). Para GET siempre queremos el body.
+  const argsList = ['api', '-X', metodo, endpoint];
+  if (payload) {
+    argsList.push('--input', '-');
+    argsList.push('--silent');
+  }
+  try {
+    return execFileSync(
+      'gh',
+      argsList,
+      {
+        encoding: 'utf8',
+        stdio: payload ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+        ...(payload ? { input: JSON.stringify(payload) } : {}),
+      }
+    ).trim();
+  } catch (e) {
+    const stderr = e.stderr || '';
+    const stdout = e.stdout || '';
+    throw Object.assign(new Error(stderr || stdout || String(e)), {
+      stderr,
+      stdout,
+      exitCode: e.status,
+    });
+  }
+}
+
+// --- Verificar gh CLI ---
+log('Verificando gh CLI...');
+try {
+  const version = ejecutar('gh', ['--version']);
+  log('  gh CLI: ' + version.split('\n')[0]);
+} catch (_) {
+  logError('gh CLI no está instalado o no está en PATH.');
+  logError('Instalar desde: https://cli.github.com/');
+  process.exit(1);
+}
+
+// --- Verificar autenticación ---
+log('Verificando autenticación con GitHub...');
+try {
+  ejecutar('gh', ['auth', 'status']);
+  log('  Autenticación: OK');
+} catch (e) {
+  logError('No estás autenticado con GitHub CLI.');
+  logError('Ejecutar: gh auth login');
+  process.exit(1);
+}
+
+// --- Detectar owner/repo ---
+log('Detectando repositorio...');
+let repo;
+try {
+  repo = ejecutar('gh', [
+    'repo', 'view',
+    '--json', 'nameWithOwner',
+    '--jq', '.nameWithOwner',
+  ]);
+  log('  Repositorio: ' + repo);
+} catch (e) {
+  logError('No se pudo determinar el repositorio. ¿Estás en el directorio correcto?');
+  process.exit(1);
+}
+
+const [owner, repoName] = repo.split('/');
+
+// --- Detectar plan del repositorio ---
+/**
+ * Detecta el método de protección apropiado para este repo.
+ *
+ * GitHub Free + repo privado → Rulesets (gratuito, API moderna)
+ * GitHub Pro/Team/Enterprise + repo privado → branch protection legacy (también funciona)
+ * Repo público → branch protection legacy funciona siempre
+ *
+ * Referencia: https://docs.github.com/en/rest/repos/repos#get-a-repository
+ *   - Campo `private` (boolean)
+ *   - Campo `owner.plan.name` (string) — solo visible para el dueño autenticado
+ *     Valores: 'free', 'pro', 'team', 'enterprise'
+ *
+ * @returns {'rulesets'|'classic'}
+ */
+function detectarMetodo() {
+  if (preferRulesets) return 'rulesets';
+  if (preferClassic)  return 'classic';
+
+  let esPrivado   = false;
+  let plan        = 'desconocido';
+
+  try {
+    const repoInfo = JSON.parse(ghApi('GET', `/repos/${owner}/${repoName}`));
+    esPrivado = repoInfo.private === true;
+    plan = repoInfo.owner?.plan?.name || 'desconocido';
+  } catch (e) {
+    // Si falla la consulta del repo, asumir privado Free (fallback más seguro)
+    logInfo('No se pudo consultar el plan del repositorio — asumiendo Free privado.');
+    logInfo('  Motivo: ' + (e.stderr || e.message || String(e)).split('\n')[0]);
+    return 'rulesets';
+  }
+
+  log('  Plan detectado: ' + plan + (esPrivado ? ' (privado)' : ' (público)'));
+
+  // Repos privados en Free no pueden usar branch protection legacy (HTTP 403)
+  if (esPrivado && (plan === 'free' || plan === 'desconocido')) {
+    return 'rulesets';
+  }
+
+  // Pro, Team, Enterprise o repo público → legacy funciona
+  return 'classic';
+}
+
+log('Detectando método de protección óptimo...');
+const metodo = detectarMetodo();
+log('  Método seleccionado: ' + (metodo === 'rulesets' ? 'GitHub Rulesets (API moderna)' : 'Branch protection clásica (legacy)'));
+
+// --- Mostrar plan ---
+log('');
+log('=== CONFIGURACIÓN DE PROTECCIÓN DE RAMA ===');
+log('  Rama:              ' + NOMBRE_RAMA);
+log('  Repositorio:       ' + repo);
+log('  Approvals req.:    ' + requiredApprovals);
+log('  Force push:        bloqueado');
+log('  Deletions:         bloqueadas');
+log('  Status checks:');
+STATUS_CHECKS.forEach((c) => log('    - ' + c));
+log('  Método:            ' + (metodo === 'rulesets' ? 'Rulesets' : 'Branch protection legacy'));
+log('');
+
+if (isDryRun) {
+  log('[DRY RUN] No se aplicaron cambios.');
+  log('');
+  if (metodo === 'rulesets') {
+    log('Se usaría POST/PUT /repos/' + repo + '/rulesets (GitHub Rulesets API)');
+    log('  Ruleset: ' + NOMBRE_RULESET);
+    log('  Endpoint ref: https://docs.github.com/en/rest/repos/rules');
+  } else {
+    log('Se usaría PUT /repos/' + repo + '/branches/' + NOMBRE_RAMA + '/protection (legacy)');
+  }
+  log('');
+  log('Para aplicar, ejecutar sin --dry-run:');
+  log('  node scripts/configurar-branch-protection.js' + (preferRulesets ? ' --prefer-rulesets' : '') + (preferClassic ? ' --prefer-classic' : ''));
+  process.exit(0);
+}
+
+// --- Implementaciones de cada método ---
+
+/**
+ * Aplica protección vía GitHub Rulesets (API moderna).
+ * Disponible GRATIS en repos privados Free desde 2024.
+ *
+ * Referencia: https://docs.github.com/en/rest/repos/rules#create-a-repository-ruleset
+ *
+ * El ruleset se nombra 'swl-protection-main' para facilitar la idempotencia:
+ * si ya existe, se actualiza (PUT); si no, se crea (POST).
+ */
+function aplicarRuleset() {
+  log('Aplicando protección vía Rulesets...');
+
+  // Buscar si ya existe un ruleset con nuestro nombre
+  let rulesetId = null;
+  try {
+    const existentesRaw = ghApi('GET', `/repos/${owner}/${repoName}/rulesets`);
+    if (!existentesRaw) {
+      throw new Error('GET /rulesets devolvió respuesta vacía');
+    }
+    const existentes = JSON.parse(existentesRaw);
+    if (!Array.isArray(existentes)) {
+      throw new Error('GET /rulesets no devolvió array: ' + existentesRaw.slice(0, 80));
+    }
+    const swlRuleset = existentes.find(r => r.name === NOMBRE_RULESET);
+    if (swlRuleset) {
+      rulesetId = swlRuleset.id;
+      logInfo('Ruleset existente encontrado (id: ' + rulesetId + '). Se actualizará.');
+    } else {
+      logInfo(`No hay ruleset previo con nombre '${NOMBRE_RULESET}'. Se creará uno nuevo.`);
+    }
+  } catch (e) {
+    // Si falla listar (403, 404, parse), intentamos crear y dejamos que la API decida
+    logInfo('No se pudo listar rulesets existentes (' + e.message + ') — se intentará crear.');
+  }
+
+  /**
+   * Payload para la API de Rulesets.
+   * Fuente: https://docs.github.com/en/rest/repos/rules#create-a-repository-ruleset
+   *
+   * Reglas incluidas:
+   *   - pull_request: requiere N approvals, descarta reviews obsoletas en push
+   *   - required_status_checks: los jobs de CI deben pasar antes de merge
+   *   - non_fast_forward: bloquea force-push
+   *   - deletion: bloquea borrado de la rama
+   */
+  const payload = {
+    name:        NOMBRE_RULESET,
+    target:      'branch',
+    enforcement: 'active',
+    // Bypass a OrganizationAdmin acotado al flujo de PR por defecto. En ese
+    // modo el owner puede mergear un PR sin esperar todos los status checks,
+    // pero NO puede hacer push directo a main sin pasar por PR — eso evita
+    // que un token comprometido empuje código sin trazabilidad de review.
+    // Para emergencias (setup inicial sin secrets de CI, hotfix bloqueado),
+    // pasar --bypass-always en la CLI; queda registrado en el log de
+    // ejecución y obliga a una decisión consciente.
+    bypass_actors: [
+      {
+        actor_id: 1,
+        actor_type: 'OrganizationAdmin',
+        bypass_mode: bypassAlways ? 'always' : 'pull_request',
+      },
+    ],
+    conditions: {
+      ref_name: {
+        include: ['refs/heads/' + NOMBRE_RAMA],
+        exclude: [],
+      },
+    },
+    rules: [
+      {
+        type: 'pull_request',
+        parameters: {
+          required_approving_review_count:  requiredApprovals,
+          dismiss_stale_reviews_on_push:    true,
+          require_code_owner_review:        false,
+          require_last_push_approval:       false,
+          required_review_thread_resolution: false,
+        },
+      },
+      {
+        type: 'required_status_checks',
+        parameters: {
+          required_status_checks: STATUS_CHECKS.map(c => ({ context: c })),
+          strict_required_status_checks_policy: true,
+        },
+      },
+      { type: 'non_fast_forward' },
+      { type: 'deletion' },
+    ],
+  };
+
+  try {
+    if (rulesetId) {
+      // Actualizar ruleset existente
+      ghApi('PUT', `/repos/${owner}/${repoName}/rulesets/${rulesetId}`, payload);
+      log('Ruleset actualizado correctamente.');
+    } else {
+      // Crear ruleset nuevo
+      ghApi('POST', `/repos/${owner}/${repoName}/rulesets`, payload);
+      log('Ruleset creado correctamente.');
+    }
+  } catch (e) {
+    const msg = e.stderr || e.stdout || e.message || String(e);
+    logError('Error al aplicar el Ruleset:');
+    logError(msg);
+    logError('');
+    logError('Puedes configurar la protección manualmente en:');
+    logError('  https://github.com/' + repo + '/settings/rules');
+    logError('');
+    logError('Documentación: https://docs.github.com/en/rest/repos/rules');
+    process.exit(1);
+  }
+}
+
+/**
+ * Aplica protección vía Branch protection rules (API legacy).
+ * Requiere plan Pro en repos privados. Funciona en repos públicos sin restricción.
+ *
+ * Referencia: https://docs.github.com/en/rest/branches/branch-protection
+ */
+function aplicarBranchProtectionClassic() {
+  log('Aplicando branch protection (método legacy)...');
+
+  const proteccion = {
+    required_status_checks: {
+      strict:   true,
+      contexts: STATUS_CHECKS,
+    },
+    enforce_admins: false,
+    required_pull_request_reviews: {
+      required_approving_review_count: requiredApprovals,
+      dismiss_stale_reviews:           false,
+      require_code_owner_reviews:      false,
+    },
+    restrictions:      null,
+    allow_force_pushes: false,
+    allow_deletions:    false,
+  };
+
+  const endpoint = `/repos/${owner}/${repoName}/branches/${NOMBRE_RAMA}/protection`;
+
+  try {
+    ghApi('PUT', endpoint, proteccion);
+    log('Branch protection aplicada correctamente.');
+  } catch (e) {
+    const msg = e.stderr || e.stdout || e.message || String(e);
+
+    // HTTP 403 con el mensaje característico de GitHub Free privado
+    if (msg.includes('Upgrade to GitHub Pro') || msg.includes('HTTP 403')) {
+      logError('Error 403: este repo es privado en GitHub Free.');
+      logError('La API legacy de branch protection requiere plan Pro ($4/mes) en repos privados.');
+      logError('');
+      logError('Solución: usar GitHub Rulesets (gratuito en repos privados Free):');
+      logError('  node scripts/configurar-branch-protection.js --prefer-rulesets');
+      logError('');
+      logError('Referencia: https://docs.github.com/en/rest/repos/rules');
+    } else if (msg.includes('422')) {
+      // 422 = ya existe — es idempotente
+      log('La branch protection ya estaba configurada (idempotente).');
+      return;
+    } else {
+      logError('Error al aplicar la branch protection:');
+      logError(msg);
+    }
+    process.exit(1);
+  }
+}
+
+// --- Aplicar según método detectado ---
+if (metodo === 'rulesets') {
+  aplicarRuleset();
+} else {
+  aplicarBranchProtectionClassic();
+}
+
+// --- Verificación ---
+log('');
+log('=== VERIFICACIÓN ===');
+if (metodo === 'rulesets') {
+  log('Revisar manualmente en:');
+  log('  https://github.com/' + repo + '/settings/rules');
+} else {
+  log('Revisar manualmente en:');
+  log('  https://github.com/' + repo + '/settings/branches');
+}
+log('');
+log('La configuración de protección es activa inmediatamente.');
+log('Los PRs existentes no se ven afectados hasta que reciban nuevo push.');