@saulwade/swl-ses 1.4.1 → 1.4.2

package/scripts/configurar-branch-protection.js

@@ -1,418 +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.');
+#!/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.');