@saulwade/swl-ses 1.3.8 → 1.4.0

package/scripts/lib/configurar-ci.js

@@ -1,380 +1,380 @@
-'use strict';
-
-/**
- * scripts/lib/configurar-ci.js
- *
- * Lógica reutilizable para /swl:configurar-ci.
- * Gestiona la instalación, estado y desinstalación de los workflows CI/CD
- * de swl-ses en proyectos de usuarios.
- *
- * API pública:
- *   init(opciones)              — copia plantillas al proyecto destino
- *   status(opciones)            — lista workflows instalados y secrets faltantes
- *   uninstall(opciones)         — elimina workflows SWL del proyecto
- *   detectarMetodoProteccion()  — detecta si usar Rulesets o legacy (para branch protection)
- *   construirPayloadRuleset()   — construye el payload para la API de Rulesets
- *   construirPayloadClassic()   — construye el payload para branch protection legacy
- *
- * Ninguna función hace network ni invoca gh CLI directamente.
- * El llamador (comando /swl:configurar-ci) orquesta las llamadas interactivas.
- *
- * NOTA: Las funciones de branch protection (detectarMetodoProteccion,
- * construirPayloadRuleset, construirPayloadClassic) están aquí para que el
- * comando distribuido /swl:configurar-ci pueda usarlas sin depender del
- * script del repo madre (configurar-branch-protection.js), que NO se
- * distribuye a los proyectos de los usuarios.
- *
- * 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
- */
-
-const fs   = require('node:fs');
-const path = require('node:path');
-const os   = require('node:os');
-
-// ---------------------------------------------------------------------------
-// Rutas y constantes
-// ---------------------------------------------------------------------------
-
-/** Directorio de plantillas dentro del repo swl-ses instalado. */
-const PLANTILLAS_DIR = path.join(__dirname, '..', '..', 'plantillas', 'github-workflows');
-
-/** Nombre del directorio destino en el proyecto del usuario. */
-const WORKFLOWS_DIR = '.github/workflows';
-
-/** Workflows que este módulo gestiona (identificados por nombre de archivo). */
-const WORKFLOWS_SWL = {
-  security: 'swl-security.yml',
-  ci:       'swl-ci.yml',
-  release:  'release-please.yml',
-};
-
-/** Secrets que requiere cada workflow. */
-const SECRETS_REQUERIDOS = {
-  'swl-security.yml': ['CLAUDE_API_KEY'],
-  'swl-ci.yml':       [],
-  'release-please.yml': [],
-};
-
-// ---------------------------------------------------------------------------
-// Helpers internos
-// ---------------------------------------------------------------------------
-
-/**
- * Valida que el path del proyecto destino sea seguro.
- * Previene path traversal y paths relativos.
- *
- * @param {string} proyectPath
- * @throws {Error} Si el path no es seguro
- */
-function validarPathProyecto(proyectPath) {
-  if (!path.isAbsolute(proyectPath)) {
-    throw new Error(`El path del proyecto debe ser absoluto. Recibido: "${proyectPath}"`);
-  }
-  // Normalizar y verificar que no escape con ..
-  const normalizado = path.normalize(proyectPath);
-  if (normalizado !== proyectPath) {
-    throw new Error(`El path contiene secuencias inseguras: "${proyectPath}"`);
-  }
-  // Bloquear paths sospechosos (rutas del sistema)
-  const peligrosos = ['/etc', '/usr', '/var', '/bin', '/sbin', '/boot', '/proc', '/sys'];
-  const enPeligroso = peligrosos.some(p => normalizado.startsWith(p + path.sep) || normalizado === p);
-  if (enPeligroso) {
-    throw new Error(`El path apunta a un directorio del sistema: "${proyectPath}"`);
-  }
-}
-
-/**
- * Detecta el directorio del proyecto actual.
- * Usa override para tests.
- *
- * @param {string|undefined} override
- * @returns {string}
- */
-function detectarProyecto(override) {
-  const dir = override || process.cwd();
-  validarPathProyecto(dir);
-  return dir;
-}
-
-/**
- * Lista los archivos en el directorio de plantillas.
- *
- * @returns {string[]} nombres de archivo
- */
-function listarPlantillas() {
-  try {
-    return fs.readdirSync(PLANTILLAS_DIR).filter(f => f.endsWith('.yml'));
-  } catch (_) {
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// init
-// ---------------------------------------------------------------------------
-
-/**
- * Copia los workflows seleccionados al proyecto destino.
- *
- * @param {object} opciones
- * @param {boolean} [opciones.withSecurity=true]         Instalar swl-security.yml
- * @param {boolean} [opciones.withCi=true]               Instalar swl-ci.yml
- * @param {boolean} [opciones.withReleasePlease=false]   Instalar release-please.yml
- * @param {boolean} [opciones.dryRun=false]              Solo mostrar cambios, no copiar
- * @param {boolean} [opciones.force=false]               Sobreescribir archivos existentes
- * @param {string}  [opciones._proyectoPathOverride]     Path del proyecto (tests)
- * @returns {{ copiados: string[], existentes: string[], error?: string }}
- */
-function init({
-  withSecurity = true,
-  withCi       = true,
-  withReleasePlease = false,
-  dryRun       = false,
-  force        = false,
-  _proyectoPathOverride,
-} = {}) {
-  const proyecto = detectarProyecto(_proyectoPathOverride);
-  const destDir  = path.join(proyecto, WORKFLOWS_DIR);
-
-  const seleccionados = [];
-  if (withSecurity)     seleccionados.push(WORKFLOWS_SWL.security);
-  if (withCi)           seleccionados.push(WORKFLOWS_SWL.ci);
-  if (withReleasePlease) seleccionados.push(WORKFLOWS_SWL.release);
-
-  const copiados   = [];
-  const existentes = [];
-
-  for (const archivo of seleccionados) {
-    const origen  = path.join(PLANTILLAS_DIR, archivo);
-    const destino = path.join(destDir, archivo);
-
-    if (!fs.existsSync(origen)) {
-      return { copiados, existentes, error: `Plantilla no encontrada: ${origen}` };
-    }
-
-    if (fs.existsSync(destino) && !force) {
-      existentes.push(archivo);
-      continue;
-    }
-
-    if (!dryRun) {
-      fs.mkdirSync(destDir, { recursive: true });
-      fs.copyFileSync(origen, destino);
-    }
-    copiados.push(archivo);
-  }
-
-  return { copiados, existentes };
-}
-
-// ---------------------------------------------------------------------------
-// status
-// ---------------------------------------------------------------------------
-
-/**
- * Verifica qué workflows SWL están instalados en el proyecto.
- *
- * @param {object} opciones
- * @param {string} [opciones._proyectoPathOverride]
- * @returns {{ instalados: string[], faltantes: string[], secretsFaltantes: Record<string,string[]> }}
- */
-function status({ _proyectoPathOverride } = {}) {
-  const proyecto  = detectarProyecto(_proyectoPathOverride);
-  const destDir   = path.join(proyecto, WORKFLOWS_DIR);
-  const instalados = [];
-  const faltantes  = [];
-  const secretsFaltantes = {};
-
-  for (const [, archivo] of Object.entries(WORKFLOWS_SWL)) {
-    const ruta = path.join(destDir, archivo);
-    if (fs.existsSync(ruta)) {
-      instalados.push(archivo);
-      const requeridos = SECRETS_REQUERIDOS[archivo] || [];
-      if (requeridos.length > 0) {
-        // No podemos verificar secrets reales sin gh CLI — reportar los necesarios
-        secretsFaltantes[archivo] = requeridos;
-      }
-    } else {
-      faltantes.push(archivo);
-    }
-  }
-
-  return { instalados, faltantes, secretsFaltantes };
-}
-
-// ---------------------------------------------------------------------------
-// uninstall
-// ---------------------------------------------------------------------------
-
-/**
- * Elimina los workflows SWL del proyecto destino.
- * Solo elimina archivos gestionados por swl-ses, no otros workflows.
- *
- * @param {object} opciones
- * @param {boolean} [opciones.confirmar=false]   Si false, solo lista qué se eliminaría
- * @param {string}  [opciones._proyectoPathOverride]
- * @returns {{ eliminados: string[], noEncontrados: string[] }}
- */
-function uninstall({ confirmar = false, _proyectoPathOverride } = {}) {
-  const proyecto  = detectarProyecto(_proyectoPathOverride);
-  const destDir   = path.join(proyecto, WORKFLOWS_DIR);
-  const eliminados    = [];
-  const noEncontrados = [];
-
-  for (const [, archivo] of Object.entries(WORKFLOWS_SWL)) {
-    const ruta = path.join(destDir, archivo);
-    if (!fs.existsSync(ruta)) {
-      noEncontrados.push(archivo);
-      continue;
-    }
-    if (confirmar) {
-      fs.unlinkSync(ruta);
-    }
-    eliminados.push(archivo);
-  }
-
-  return { eliminados, noEncontrados };
-}
-
-// ---------------------------------------------------------------------------
-// Branch protection — lógica distribuible
-//
-// Estas funciones replican la lógica de scripts/configurar-branch-protection.js
-// para uso en el comando /swl:configurar-ci. Son puras (sin side effects de red).
-// El llamador es responsable de ejecutar gh api con el payload devuelto.
-// ---------------------------------------------------------------------------
-
-/** Status checks requeridos por defecto para la protección de rama. */
-const STATUS_CHECKS_DEFAULT = ['test (22)', 'test (24)', 'smoke'];
-
-/** Nombre canónico del ruleset gestionado por swl-ses. */
-const NOMBRE_RULESET_SWL = 'swl-protection-main';
-
-/**
- * Detecta qué método de branch protection conviene usar según el plan del repo.
- *
- * Diseñado para ser llamado con el output de `gh api /repos/{owner}/{repo}`.
- * No hace network — recibe repoInfo ya parseado.
- *
- * Lógica:
- *   - Repo privado + plan Free o desconocido → 'rulesets'
- *   - Repo privado + plan Pro/Team/Enterprise → 'classic'
- *   - Repo público → 'classic'
- *   - --prefer-rulesets → 'rulesets' (override)
- *   - --prefer-classic  → 'classic'  (override)
- *
- * Referencia: https://docs.github.com/en/rest/repos/repos#get-a-repository
- *   Campo `private` (boolean), campo `owner.plan.name` (string)
- *
- * @param {{ private: boolean, owner?: { plan?: { name?: string } } } | null} repoInfo
- * @param {{ preferRulesets?: boolean, preferClassic?: boolean }} [flags]
- * @returns {'rulesets'|'classic'}
- */
-function detectarMetodoProteccion(repoInfo, flags = {}) {
-  if (flags.preferRulesets) return 'rulesets';
-  if (flags.preferClassic)  return 'classic';
-
-  if (!repoInfo) return 'rulesets'; // fallback seguro si no hay info
-
-  const esPrivado = repoInfo.private === true;
-  const plan      = repoInfo.owner?.plan?.name || 'desconocido';
-
-  if (esPrivado && (plan === 'free' || plan === 'desconocido')) {
-    return 'rulesets';
-  }
-  return 'classic';
-}
-
-/**
- * Construye el payload para la API de GitHub Rulesets.
- *
- * Fuente: https://docs.github.com/en/rest/repos/rules#create-a-repository-ruleset
- *
- * @param {{ rama?: string, approvals?: number, statusChecks?: string[] }} [opciones]
- * @returns {object} Payload listo para JSON.stringify y envío a la API
- */
-function construirPayloadRuleset({ rama = 'main', approvals = 1, statusChecks = STATUS_CHECKS_DEFAULT } = {}) {
-  return {
-    name:        NOMBRE_RULESET_SWL,
-    target:      'branch',
-    enforcement: 'active',
-    conditions: {
-      ref_name: {
-        include: ['refs/heads/' + rama],
-        exclude: [],
-      },
-    },
-    rules: [
-      {
-        type: 'pull_request',
-        parameters: {
-          required_approving_review_count:   approvals,
-          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: statusChecks.map(c => ({
-            context:        c,
-            integration_id: null,
-          })),
-          strict_required_status_checks_policy: true,
-        },
-      },
-      { type: 'non_fast_forward' },
-      { type: 'deletion' },
-    ],
-  };
-}
-
-/**
- * Construye el payload para la API de Branch protection legacy.
- *
- * Fuente: https://docs.github.com/en/rest/branches/branch-protection
- *
- * @param {{ approvals?: number, statusChecks?: string[] }} [opciones]
- * @returns {object}
- */
-function construirPayloadClassic({ approvals = 1, statusChecks = STATUS_CHECKS_DEFAULT } = {}) {
-  return {
-    required_status_checks: {
-      strict:   true,
-      contexts: statusChecks,
-    },
-    enforce_admins: false,
-    required_pull_request_reviews: {
-      required_approving_review_count: approvals,
-      dismiss_stale_reviews:           false,
-      require_code_owner_reviews:      false,
-    },
-    restrictions:       null,
-    allow_force_pushes: false,
-    allow_deletions:    false,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-module.exports = {
-  init,
-  status,
-  uninstall,
-  // Lógica de branch protection distribuible
-  detectarMetodoProteccion,
-  construirPayloadRuleset,
-  construirPayloadClassic,
-  // Constantes para tests y para el comando
-  WORKFLOWS_SWL,
-  WORKFLOWS_DIR,
-  PLANTILLAS_DIR,
-  SECRETS_REQUERIDOS,
-  NOMBRE_RULESET_SWL,
-  STATUS_CHECKS_DEFAULT,
-};
+'use strict';
+
+/**
+ * scripts/lib/configurar-ci.js
+ *
+ * Lógica reutilizable para /swl:configurar-ci.
+ * Gestiona la instalación, estado y desinstalación de los workflows CI/CD
+ * de swl-ses en proyectos de usuarios.
+ *
+ * API pública:
+ *   init(opciones)              — copia plantillas al proyecto destino
+ *   status(opciones)            — lista workflows instalados y secrets faltantes
+ *   uninstall(opciones)         — elimina workflows SWL del proyecto
+ *   detectarMetodoProteccion()  — detecta si usar Rulesets o legacy (para branch protection)
+ *   construirPayloadRuleset()   — construye el payload para la API de Rulesets
+ *   construirPayloadClassic()   — construye el payload para branch protection legacy
+ *
+ * Ninguna función hace network ni invoca gh CLI directamente.
+ * El llamador (comando /swl:configurar-ci) orquesta las llamadas interactivas.
+ *
+ * NOTA: Las funciones de branch protection (detectarMetodoProteccion,
+ * construirPayloadRuleset, construirPayloadClassic) están aquí para que el
+ * comando distribuido /swl:configurar-ci pueda usarlas sin depender del
+ * script del repo madre (configurar-branch-protection.js), que NO se
+ * distribuye a los proyectos de los usuarios.
+ *
+ * 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
+ */
+
+const fs   = require('node:fs');
+const path = require('node:path');
+const os   = require('node:os');
+
+// ---------------------------------------------------------------------------
+// Rutas y constantes
+// ---------------------------------------------------------------------------
+
+/** Directorio de plantillas dentro del repo swl-ses instalado. */
+const PLANTILLAS_DIR = path.join(__dirname, '..', '..', 'plantillas', 'github-workflows');
+
+/** Nombre del directorio destino en el proyecto del usuario. */
+const WORKFLOWS_DIR = '.github/workflows';
+
+/** Workflows que este módulo gestiona (identificados por nombre de archivo). */
+const WORKFLOWS_SWL = {
+  security: 'swl-security.yml',
+  ci:       'swl-ci.yml',
+  release:  'release-please.yml',
+};
+
+/** Secrets que requiere cada workflow. */
+const SECRETS_REQUERIDOS = {
+  'swl-security.yml': ['CLAUDE_API_KEY'],
+  'swl-ci.yml':       [],
+  'release-please.yml': [],
+};
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+/**
+ * Valida que el path del proyecto destino sea seguro.
+ * Previene path traversal y paths relativos.
+ *
+ * @param {string} proyectPath
+ * @throws {Error} Si el path no es seguro
+ */
+function validarPathProyecto(proyectPath) {
+  if (!path.isAbsolute(proyectPath)) {
+    throw new Error(`El path del proyecto debe ser absoluto. Recibido: "${proyectPath}"`);
+  }
+  // Normalizar y verificar que no escape con ..
+  const normalizado = path.normalize(proyectPath);
+  if (normalizado !== proyectPath) {
+    throw new Error(`El path contiene secuencias inseguras: "${proyectPath}"`);
+  }
+  // Bloquear paths sospechosos (rutas del sistema)
+  const peligrosos = ['/etc', '/usr', '/var', '/bin', '/sbin', '/boot', '/proc', '/sys'];
+  const enPeligroso = peligrosos.some(p => normalizado.startsWith(p + path.sep) || normalizado === p);
+  if (enPeligroso) {
+    throw new Error(`El path apunta a un directorio del sistema: "${proyectPath}"`);
+  }
+}
+
+/**
+ * Detecta el directorio del proyecto actual.
+ * Usa override para tests.
+ *
+ * @param {string|undefined} override
+ * @returns {string}
+ */
+function detectarProyecto(override) {
+  const dir = override || process.cwd();
+  validarPathProyecto(dir);
+  return dir;
+}
+
+/**
+ * Lista los archivos en el directorio de plantillas.
+ *
+ * @returns {string[]} nombres de archivo
+ */
+function listarPlantillas() {
+  try {
+    return fs.readdirSync(PLANTILLAS_DIR).filter(f => f.endsWith('.yml'));
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// init
+// ---------------------------------------------------------------------------
+
+/**
+ * Copia los workflows seleccionados al proyecto destino.
+ *
+ * @param {object} opciones
+ * @param {boolean} [opciones.withSecurity=true]         Instalar swl-security.yml
+ * @param {boolean} [opciones.withCi=true]               Instalar swl-ci.yml
+ * @param {boolean} [opciones.withReleasePlease=false]   Instalar release-please.yml
+ * @param {boolean} [opciones.dryRun=false]              Solo mostrar cambios, no copiar
+ * @param {boolean} [opciones.force=false]               Sobreescribir archivos existentes
+ * @param {string}  [opciones._proyectoPathOverride]     Path del proyecto (tests)
+ * @returns {{ copiados: string[], existentes: string[], error?: string }}
+ */
+function init({
+  withSecurity = true,
+  withCi       = true,
+  withReleasePlease = false,
+  dryRun       = false,
+  force        = false,
+  _proyectoPathOverride,
+} = {}) {
+  const proyecto = detectarProyecto(_proyectoPathOverride);
+  const destDir  = path.join(proyecto, WORKFLOWS_DIR);
+
+  const seleccionados = [];
+  if (withSecurity)     seleccionados.push(WORKFLOWS_SWL.security);
+  if (withCi)           seleccionados.push(WORKFLOWS_SWL.ci);
+  if (withReleasePlease) seleccionados.push(WORKFLOWS_SWL.release);
+
+  const copiados   = [];
+  const existentes = [];
+
+  for (const archivo of seleccionados) {
+    const origen  = path.join(PLANTILLAS_DIR, archivo);
+    const destino = path.join(destDir, archivo);
+
+    if (!fs.existsSync(origen)) {
+      return { copiados, existentes, error: `Plantilla no encontrada: ${origen}` };
+    }
+
+    if (fs.existsSync(destino) && !force) {
+      existentes.push(archivo);
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(origen, destino);
+    }
+    copiados.push(archivo);
+  }
+
+  return { copiados, existentes };
+}
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica qué workflows SWL están instalados en el proyecto.
+ *
+ * @param {object} opciones
+ * @param {string} [opciones._proyectoPathOverride]
+ * @returns {{ instalados: string[], faltantes: string[], secretsFaltantes: Record<string,string[]> }}
+ */
+function status({ _proyectoPathOverride } = {}) {
+  const proyecto  = detectarProyecto(_proyectoPathOverride);
+  const destDir   = path.join(proyecto, WORKFLOWS_DIR);
+  const instalados = [];
+  const faltantes  = [];
+  const secretsFaltantes = {};
+
+  for (const [, archivo] of Object.entries(WORKFLOWS_SWL)) {
+    const ruta = path.join(destDir, archivo);
+    if (fs.existsSync(ruta)) {
+      instalados.push(archivo);
+      const requeridos = SECRETS_REQUERIDOS[archivo] || [];
+      if (requeridos.length > 0) {
+        // No podemos verificar secrets reales sin gh CLI — reportar los necesarios
+        secretsFaltantes[archivo] = requeridos;
+      }
+    } else {
+      faltantes.push(archivo);
+    }
+  }
+
+  return { instalados, faltantes, secretsFaltantes };
+}
+
+// ---------------------------------------------------------------------------
+// uninstall
+// ---------------------------------------------------------------------------
+
+/**
+ * Elimina los workflows SWL del proyecto destino.
+ * Solo elimina archivos gestionados por swl-ses, no otros workflows.
+ *
+ * @param {object} opciones
+ * @param {boolean} [opciones.confirmar=false]   Si false, solo lista qué se eliminaría
+ * @param {string}  [opciones._proyectoPathOverride]
+ * @returns {{ eliminados: string[], noEncontrados: string[] }}
+ */
+function uninstall({ confirmar = false, _proyectoPathOverride } = {}) {
+  const proyecto  = detectarProyecto(_proyectoPathOverride);
+  const destDir   = path.join(proyecto, WORKFLOWS_DIR);
+  const eliminados    = [];
+  const noEncontrados = [];
+
+  for (const [, archivo] of Object.entries(WORKFLOWS_SWL)) {
+    const ruta = path.join(destDir, archivo);
+    if (!fs.existsSync(ruta)) {
+      noEncontrados.push(archivo);
+      continue;
+    }
+    if (confirmar) {
+      fs.unlinkSync(ruta);
+    }
+    eliminados.push(archivo);
+  }
+
+  return { eliminados, noEncontrados };
+}
+
+// ---------------------------------------------------------------------------
+// Branch protection — lógica distribuible
+//
+// Estas funciones replican la lógica de scripts/configurar-branch-protection.js
+// para uso en el comando /swl:configurar-ci. Son puras (sin side effects de red).
+// El llamador es responsable de ejecutar gh api con el payload devuelto.
+// ---------------------------------------------------------------------------
+
+/** Status checks requeridos por defecto para la protección de rama. */
+const STATUS_CHECKS_DEFAULT = ['test (22)', 'test (24)', 'smoke'];
+
+/** Nombre canónico del ruleset gestionado por swl-ses. */
+const NOMBRE_RULESET_SWL = 'swl-protection-main';
+
+/**
+ * Detecta qué método de branch protection conviene usar según el plan del repo.
+ *
+ * Diseñado para ser llamado con el output de `gh api /repos/{owner}/{repo}`.
+ * No hace network — recibe repoInfo ya parseado.
+ *
+ * Lógica:
+ *   - Repo privado + plan Free o desconocido → 'rulesets'
+ *   - Repo privado + plan Pro/Team/Enterprise → 'classic'
+ *   - Repo público → 'classic'
+ *   - --prefer-rulesets → 'rulesets' (override)
+ *   - --prefer-classic  → 'classic'  (override)
+ *
+ * Referencia: https://docs.github.com/en/rest/repos/repos#get-a-repository
+ *   Campo `private` (boolean), campo `owner.plan.name` (string)
+ *
+ * @param {{ private: boolean, owner?: { plan?: { name?: string } } } | null} repoInfo
+ * @param {{ preferRulesets?: boolean, preferClassic?: boolean }} [flags]
+ * @returns {'rulesets'|'classic'}
+ */
+function detectarMetodoProteccion(repoInfo, flags = {}) {
+  if (flags.preferRulesets) return 'rulesets';
+  if (flags.preferClassic)  return 'classic';
+
+  if (!repoInfo) return 'rulesets'; // fallback seguro si no hay info
+
+  const esPrivado = repoInfo.private === true;
+  const plan      = repoInfo.owner?.plan?.name || 'desconocido';
+
+  if (esPrivado && (plan === 'free' || plan === 'desconocido')) {
+    return 'rulesets';
+  }
+  return 'classic';
+}
+
+/**
+ * Construye el payload para la API de GitHub Rulesets.
+ *
+ * Fuente: https://docs.github.com/en/rest/repos/rules#create-a-repository-ruleset
+ *
+ * @param {{ rama?: string, approvals?: number, statusChecks?: string[] }} [opciones]
+ * @returns {object} Payload listo para JSON.stringify y envío a la API
+ */
+function construirPayloadRuleset({ rama = 'main', approvals = 1, statusChecks = STATUS_CHECKS_DEFAULT } = {}) {
+  return {
+    name:        NOMBRE_RULESET_SWL,
+    target:      'branch',
+    enforcement: 'active',
+    conditions: {
+      ref_name: {
+        include: ['refs/heads/' + rama],
+        exclude: [],
+      },
+    },
+    rules: [
+      {
+        type: 'pull_request',
+        parameters: {
+          required_approving_review_count:   approvals,
+          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: statusChecks.map(c => ({
+            context:        c,
+            integration_id: null,
+          })),
+          strict_required_status_checks_policy: true,
+        },
+      },
+      { type: 'non_fast_forward' },
+      { type: 'deletion' },
+    ],
+  };
+}
+
+/**
+ * Construye el payload para la API de Branch protection legacy.
+ *
+ * Fuente: https://docs.github.com/en/rest/branches/branch-protection
+ *
+ * @param {{ approvals?: number, statusChecks?: string[] }} [opciones]
+ * @returns {object}
+ */
+function construirPayloadClassic({ approvals = 1, statusChecks = STATUS_CHECKS_DEFAULT } = {}) {
+  return {
+    required_status_checks: {
+      strict:   true,
+      contexts: statusChecks,
+    },
+    enforce_admins: false,
+    required_pull_request_reviews: {
+      required_approving_review_count: approvals,
+      dismiss_stale_reviews:           false,
+      require_code_owner_reviews:      false,
+    },
+    restrictions:       null,
+    allow_force_pushes: false,
+    allow_deletions:    false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  init,
+  status,
+  uninstall,
+  // Lógica de branch protection distribuible
+  detectarMetodoProteccion,
+  construirPayloadRuleset,
+  construirPayloadClassic,
+  // Constantes para tests y para el comando
+  WORKFLOWS_SWL,
+  WORKFLOWS_DIR,
+  PLANTILLAS_DIR,
+  SECRETS_REQUERIDOS,
+  NOMBRE_RULESET_SWL,
+  STATUS_CHECKS_DEFAULT,
+};