@saulwade/swl-ses 1.5.1 → 1.6.0

package/scripts/lib/mcp_config.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""mcp_config.py — Carga unificada de configuracion MCP con deep merge.
+
+Replica la semantica de fusion de Claude Code: combina por clave los archivos
+mcp-servers.json -> .claude/settings.json -> .claude/settings.local.json
+(el ultimo gana por clave, env se mergea por sub-clave). Asi un equipo puede
+mantener `command` y `args` en settings.json versionado y override solo el
+`env` (con credenciales por maquina) en settings.local.json gitignored.
+
+Uso programatico:
+    from mcp_config import cargar_config_mcp
+    servers = cargar_config_mcp(Path('.'))
+
+Uso CLI (para tests y debugging):
+    python scripts/lib/mcp_config.py [cwd]
+    -> imprime json con el mapa de servidores fusionado
+
+Origen: fix bug donde mcp-orchestrator.py / mcp-pool-manager.py hacian
+first-wins y rompian /swl:mcp-status cuando settings.local.json contenia
+solo overrides parciales. Coherente con la regla del repo en CLAUDE.md
+seccion "Code style": settings.local.json sobrescribe por key, no reemplaza.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+# Orden de capas: base -> override. La ultima capa gana por clave al hacer
+# merge, igual que el deep merge interno de Claude Code.
+CAPAS_DEFAULT = (
+    'mcp-servers.json',
+    '.claude/settings.json',
+    '.claude/settings.local.json',
+)
+
+
+def _leer_servers(ruta: Path) -> dict:
+    """Lee un archivo JSON y devuelve su seccion mcpServers, o {} si falla.
+
+    Tolera archivos inexistentes, JSON invalido y archivos sin la clave
+    mcpServers. NUNCA levanta — la fusion debe ser robusta a capas faltantes.
+    """
+    if not ruta.exists():
+        return {}
+    try:
+        data = json.loads(ruta.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    servers = data.get('mcpServers')
+    if not isinstance(servers, dict):
+        return {}
+    return servers
+
+
+def _fusionar_servidor(base: dict, override: dict) -> dict:
+    """Combina dos definiciones de servidor.
+
+    Reglas:
+    - Claves escalares de `override` reemplazan a `base` (command, cwd, url).
+    - `env` se mergea por sub-clave: el override anade o sobrescribe variables
+      sin perder las que solo existen en `base`.
+    - `args` reemplaza completamente si el override lo define (lista entera,
+      no merge — para no producir listas ambiguas).
+    - Cualquier otro dict anidado se mergea superficial (override gana).
+    """
+    if not isinstance(base, dict) or not isinstance(override, dict):
+        return override if isinstance(override, dict) else base
+
+    resultado: dict[str, Any] = dict(base)
+
+    for clave, valor in override.items():
+        if clave == 'env' and isinstance(valor, dict):
+            env_base = resultado.get('env') if isinstance(resultado.get('env'), dict) else {}
+            resultado['env'] = {**env_base, **valor}
+        elif clave == 'args':
+            # args reemplaza, no mergea: una lista parcial seria peligrosa.
+            resultado['args'] = valor
+        elif isinstance(valor, dict) and isinstance(resultado.get(clave), dict):
+            resultado[clave] = {**resultado[clave], **valor}
+        else:
+            resultado[clave] = valor
+
+    return resultado
+
+
+def cargar_config_mcp(cwd: Path, config_path: str | None = None) -> dict:
+    """Devuelve el mapa de servidores MCP fusionado siguiendo CAPAS_DEFAULT.
+
+    Si `config_path` se especifica, solo se lee ese archivo (modo override
+    completo para CI o tests). De lo contrario se aplican las tres capas.
+
+    Garantia: el dict devuelto contiene TODOS los servidores definidos en
+    cualquier capa. Las capas mas profundas refinan (no reemplazan) la
+    definicion de cada servidor por clave.
+    """
+    if config_path:
+        return _leer_servers(Path(config_path))
+
+    fusionado: dict[str, dict] = {}
+    for nombre_capa in CAPAS_DEFAULT:
+        capa = _leer_servers(cwd / nombre_capa)
+        for nombre_servidor, cfg in capa.items():
+            if nombre_servidor in fusionado:
+                fusionado[nombre_servidor] = _fusionar_servidor(
+                    fusionado[nombre_servidor], cfg
+                )
+            else:
+                fusionado[nombre_servidor] = cfg if isinstance(cfg, dict) else {}
+    return fusionado
+
+
+def _main(argv: list[str]) -> int:
+    """Entry point CLI: imprime el JSON fusionado para uso en tests."""
+    cwd = Path(argv[0]) if argv else Path('.')
+    if not cwd.is_dir():
+        sys.stderr.write(f'[mcp_config] CWD no es directorio: {cwd}\n')
+        return 1
+    resultado = cargar_config_mcp(cwd)
+    sys.stdout.write(json.dumps(resultado, indent=2, ensure_ascii=False))
+    sys.stdout.write('\n')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(_main(sys.argv[1:]))

package/scripts/lib/npm-version.js

@@ -1,261 +1,261 @@
-'use strict';
-
-/**
- * npm-version.js — utilidades compartidas para consultar versiones en npm.
- *
- * Lib usada por scripts/check-update.js, hooks/check-update.js,
- * scripts/doctor.js y scripts/actualizar.js. Consolida tres preocupaciones
- * que estaban duplicadas en los 4 archivos:
- *   1. Aumento de PATH (necesario en git-bash Windows donde el PATH
- *      heredado no incluye node/npm).
- *   2. Consulta paralela a npm view de los nombres conocidos del paquete.
- *   3. Comparación robusta de versiones SemVer con soporte para
- *      pre-release/build metadata (5.7.5-beta.1+abc).
- *
- * Por seguridad usa execFile (sin shell) en lugar de execSync con shell:true.
- */
-
-const fs   = require('fs');
-const path = require('path');
-const os   = require('os');
-const { execFile, execFileSync } = require('child_process');
-
-const { NOMBRES_DETECCION } = require('./paquetes-conocidos');
-
-const TIMEOUT_DEFAULT_MS = 10_000;
-
-/**
- * Resuelve la ruta absoluta a `npm-cli.js` que viene con la instalación
- * de Node. En Windows `npm.cmd` y en POSIX `npm` son shims que terminan
- * invocando este JS con el binario de Node. Llamamos directamente a Node
- * con el script para evitar:
- *   1. La diferencia .cmd vs binario nativo entre Windows y POSIX.
- *   2. El requerimiento de `shell: true` en Node 20+ para ejecutar .cmd
- *      (que dispara DEP0190 cuando hay args, aunque estén validados).
- *
- * Si no se encuentra (ej. instalación no estándar), devuelve null y
- * caemos al fallback con shell.
- */
-function localizarNpmCli() {
-  const dir = path.dirname(process.execPath);
-  const candidatos = [
-    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
-    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
-    path.join(os.homedir(), 'AppData', 'Roaming', 'npm', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
-  ];
-  for (const c of candidatos) {
-    try {
-      if (fs.existsSync(c)) return c;
-    } catch { /* continuar */ }
-  }
-  return null;
-}
-
-const NPM_CLI_JS = localizarNpmCli();
-
-if (!NPM_CLI_JS) {
-  // Si no encontramos npm-cli.js (instalación de Node atípica), emitimos
-  // un aviso pero NO caemos a `shell: true` — eso reintroduciría DEP0190
-  // y exigiría confiar en el regex como única defensa contra inyección.
-  // En su lugar, los callers reciben null/error y deciden cómo continuar.
-  process.stderr.write(
-    `[npm-version] aviso: no se encontró npm-cli.js junto a node ` +
-    `(${process.execPath}). Las consultas a npm view fallarán hasta que ` +
-    `node esté instalado con npm bundled (instalación oficial).\n`
-  );
-}
-
-/**
- * Whitelist de nombres de paquete: scope opcional + nombre alfanumérico
- * con guiones/puntos/underscore. Rechaza espacios, comillas, $, |, ;, etc.
- * Defensa en profundidad — actualmente los nombres son constantes del
- * código, pero esta validación protege ante regresiones futuras donde
- * el nombre venga de variable de entorno o input externo.
- */
-const REGEX_NOMBRE_PAQUETE_SEGURO = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
-
-function asegurarNombrePaqueteSeguro(pkg) {
-  if (typeof pkg !== 'string' || !REGEX_NOMBRE_PAQUETE_SEGURO.test(pkg)) {
-    throw new Error(`nombre de paquete inválido: ${JSON.stringify(pkg)}`);
-  }
-}
-
-/**
- * Construye [bin, args] para invocar npm de forma segura:
- *   - Si encontramos npm-cli.js, usa el binario de Node directamente
- *     (cross-platform, sin shell, sin DEP0190).
- *   - Si no se encontró, lanza error explícito en lugar de caer a shell.
- *     Eliminar el fallback `shell: true` cierra la última superficie de
- *     ataque por inyección si en el futuro un nombre de paquete se
- *     parametriza desde input externo (defensa en profundidad).
- */
-function comandoNpm(args) {
-  if (!NPM_CLI_JS) {
-    throw new Error('npm-cli.js no localizado: instala Node con npm bundled');
-  }
-  return { bin: process.execPath, argsList: [NPM_CLI_JS, ...args], opts: {} };
-}
-
-/**
- * Aumenta PATH con ubicaciones típicas de Node/npm en Windows.
- * Devuelve un PATH listo para inyectar en el env de un subproceso.
- */
-function pathAumentado() {
-  const extras = [
-    '/c/Program Files/nodejs',
-    '/c/Program Files (x86)/nodejs',
-    'C:\\Program Files\\nodejs',
-    'C:\\Program Files (x86)\\nodejs',
-    path.join(os.homedir(), 'AppData', 'Roaming', 'npm'),
-  ];
-  const sep = process.platform === 'win32' ? ';' : ':';
-  return extras.join(sep) + sep + (process.env.PATH || '');
-}
-
-/**
- * Parsea una versión SemVer aceptando suffixes pre-release/build metadata.
- * Devuelve null si la cadena no es semver válida.
- */
-function parseSemver(v) {
-  const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(String(v));
-  if (!m) return null;
-  return [Number(m[1]), Number(m[2]), Number(m[3])];
-}
-
-/**
- * Compara dos cadenas semver. Retorna 1, 0, -1 o null si alguna no parsea.
- */
-function compararSemver(a, b) {
-  const pa = parseSemver(a);
-  const pb = parseSemver(b);
-  if (!pa || !pb) return null;
-  for (let i = 0; i < 3; i++) {
-    if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
-  }
-  return 0;
-}
-
-/**
- * Versión asíncrona: ejecuta `npm view <pkg> version` sin shell.
- * Usa execFile para evitar inyección si el nombre del paquete viniera
- * de input no confiable (defensa en profundidad — actualmente los
- * nombres son constantes literales).
- */
-function consultarUna(pkg, { timeoutMs = TIMEOUT_DEFAULT_MS, env = process.env } = {}) {
-  return new Promise((resolve) => {
-    try {
-      asegurarNombrePaqueteSeguro(pkg);
-    } catch (e) {
-      resolve({ paquete: pkg, version: null, error: e.message });
-      return;
-    }
-    const { bin, argsList, opts } = comandoNpm(['view', pkg, 'version']);
-    execFile(bin, argsList, {
-      timeout: timeoutMs,
-      encoding: 'utf-8',
-      env,
-      ...opts,
-    }, (err, stdout) => {
-      if (err) {
-        resolve({ paquete: pkg, version: null, error: String(err.message).slice(0, 120) });
-        return;
-      }
-      const ver = String(stdout).trim();
-      if (/^\d+\.\d+\.\d+/.test(ver)) {
-        resolve({ paquete: pkg, version: ver });
-      } else {
-        resolve({ paquete: pkg, version: null, error: `formato inválido: ${ver.slice(0, 60)}` });
-      }
-    });
-  });
-}
-
-/**
- * Consulta en paralelo la versión publicada de los nombres conocidos.
- * Devuelve la primera versión válida encontrada (preferencia por orden
- * en NOMBRES_DETECCION: canónico npmjs > mirror GH > legacy).
- *
- * Diseño:
- *   - Ejecuta las consultas en paralelo con Promise.allSettled para que
- *     el peor caso sea max(timeout) en vez de N × timeout en serie.
- *   - Conserva orden de prioridad post-resolución para devolver el
- *     resultado más canónico cuando varios responden con éxito.
- *
- * @returns {{paquete: string|null, version: string|null, intentos: Array}}
- */
-async function versionRemotaParalela({ timeoutMs = TIMEOUT_DEFAULT_MS, paquetes = NOMBRES_DETECCION } = {}) {
-  const env = { ...process.env, PATH: pathAumentado() };
-  const promesas = paquetes.map(pkg => consultarUna(pkg, { timeoutMs, env }));
-  const settled = await Promise.allSettled(promesas);
-
-  // Registrar TODOS los resultados — éxitos y fallos — para que el
-  // diagnóstico downstream pueda mostrar cuántos paquetes respondieron.
-  // Antes este bloque omitía los éxitos posteriores al primer 'mejor',
-  // dejando intentos vacío cuando 2-3 paquetes resolvían correctamente.
-  const intentos = [];
-  let mejor = null;
-
-  for (let i = 0; i < paquetes.length; i++) {
-    const r = settled[i];
-    if (r.status === 'fulfilled') {
-      const { paquete, version, error } = r.value;
-      if (version) {
-        if (!mejor) mejor = { paquete, version };
-        intentos.push({ paquete, resultado: 'ok', version });
-      } else {
-        intentos.push({ paquete, resultado: 'error', error: error || 'sin versión' });
-      }
-    } else {
-      intentos.push({ paquete: paquetes[i], resultado: 'rejected', error: String(r.reason).slice(0, 120) });
-    }
-  }
-
-  if (mejor) return { ...mejor, intentos };
-  return { paquete: null, version: null, intentos };
-}
-
-/**
- * Versión síncrona-bloqueante de la consulta. Útil para scripts CLI
- * donde el flujo de control síncrono es más simple. Acepta también el
- * orden de prioridad sin paralelizar.
- *
- * Implementación: usa deasync vía execFileSync con timeout corto por
- * paquete (no paraleliza, pero sigue siendo más rápido que el patrón
- * anterior gracias al timeout reducido por intento).
- */
-function versionRemotaSync({ timeoutMs = TIMEOUT_DEFAULT_MS, paquetes = NOMBRES_DETECCION } = {}) {
-  const env = { ...process.env, PATH: pathAumentado() };
-  const intentos = [];
-
-  for (const pkg of paquetes) {
-    try {
-      asegurarNombrePaqueteSeguro(pkg);
-      const { bin, argsList, opts } = comandoNpm(['view', pkg, 'version']);
-      const result = execFileSync(bin, argsList, {
-        timeout: timeoutMs,
-        encoding: 'utf-8',
-        env,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        ...opts,
-      });
-      const ver = String(result).trim();
-      if (/^\d+\.\d+\.\d+/.test(ver)) {
-        return { paquete: pkg, version: ver, intentos };
-      }
-      intentos.push({ paquete: pkg, resultado: 'formato inválido', raw: ver.slice(0, 80) });
-    } catch (err) {
-      intentos.push({ paquete: pkg, resultado: 'error', error: String(err.message).slice(0, 120) });
-    }
-  }
-  return { paquete: null, version: null, intentos };
-}
-
-module.exports = {
-  pathAumentado,
-  parseSemver,
-  compararSemver,
-  consultarUna,
-  versionRemotaParalela,
-  versionRemotaSync,
-  TIMEOUT_DEFAULT_MS,
-};
+'use strict';
+
+/**
+ * npm-version.js — utilidades compartidas para consultar versiones en npm.
+ *
+ * Lib usada por scripts/check-update.js, hooks/check-update.js,
+ * scripts/doctor.js y scripts/actualizar.js. Consolida tres preocupaciones
+ * que estaban duplicadas en los 4 archivos:
+ *   1. Aumento de PATH (necesario en git-bash Windows donde el PATH
+ *      heredado no incluye node/npm).
+ *   2. Consulta paralela a npm view de los nombres conocidos del paquete.
+ *   3. Comparación robusta de versiones SemVer con soporte para
+ *      pre-release/build metadata (5.7.5-beta.1+abc).
+ *
+ * Por seguridad usa execFile (sin shell) en lugar de execSync con shell:true.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { execFile, execFileSync } = require('child_process');
+
+const { NOMBRES_DETECCION } = require('./paquetes-conocidos');
+
+const TIMEOUT_DEFAULT_MS = 10_000;
+
+/**
+ * Resuelve la ruta absoluta a `npm-cli.js` que viene con la instalación
+ * de Node. En Windows `npm.cmd` y en POSIX `npm` son shims que terminan
+ * invocando este JS con el binario de Node. Llamamos directamente a Node
+ * con el script para evitar:
+ *   1. La diferencia .cmd vs binario nativo entre Windows y POSIX.
+ *   2. El requerimiento de `shell: true` en Node 20+ para ejecutar .cmd
+ *      (que dispara DEP0190 cuando hay args, aunque estén validados).
+ *
+ * Si no se encuentra (ej. instalación no estándar), devuelve null y
+ * caemos al fallback con shell.
+ */
+function localizarNpmCli() {
+  const dir = path.dirname(process.execPath);
+  const candidatos = [
+    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(os.homedir(), 'AppData', 'Roaming', 'npm', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  for (const c of candidatos) {
+    try {
+      if (fs.existsSync(c)) return c;
+    } catch { /* continuar */ }
+  }
+  return null;
+}
+
+const NPM_CLI_JS = localizarNpmCli();
+
+if (!NPM_CLI_JS) {
+  // Si no encontramos npm-cli.js (instalación de Node atípica), emitimos
+  // un aviso pero NO caemos a `shell: true` — eso reintroduciría DEP0190
+  // y exigiría confiar en el regex como única defensa contra inyección.
+  // En su lugar, los callers reciben null/error y deciden cómo continuar.
+  process.stderr.write(
+    `[npm-version] aviso: no se encontró npm-cli.js junto a node ` +
+    `(${process.execPath}). Las consultas a npm view fallarán hasta que ` +
+    `node esté instalado con npm bundled (instalación oficial).\n`
+  );
+}
+
+/**
+ * Whitelist de nombres de paquete: scope opcional + nombre alfanumérico
+ * con guiones/puntos/underscore. Rechaza espacios, comillas, $, |, ;, etc.
+ * Defensa en profundidad — actualmente los nombres son constantes del
+ * código, pero esta validación protege ante regresiones futuras donde
+ * el nombre venga de variable de entorno o input externo.
+ */
+const REGEX_NOMBRE_PAQUETE_SEGURO = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
+
+function asegurarNombrePaqueteSeguro(pkg) {
+  if (typeof pkg !== 'string' || !REGEX_NOMBRE_PAQUETE_SEGURO.test(pkg)) {
+    throw new Error(`nombre de paquete inválido: ${JSON.stringify(pkg)}`);
+  }
+}
+
+/**
+ * Construye [bin, args] para invocar npm de forma segura:
+ *   - Si encontramos npm-cli.js, usa el binario de Node directamente
+ *     (cross-platform, sin shell, sin DEP0190).
+ *   - Si no se encontró, lanza error explícito en lugar de caer a shell.
+ *     Eliminar el fallback `shell: true` cierra la última superficie de
+ *     ataque por inyección si en el futuro un nombre de paquete se
+ *     parametriza desde input externo (defensa en profundidad).
+ */
+function comandoNpm(args) {
+  if (!NPM_CLI_JS) {
+    throw new Error('npm-cli.js no localizado: instala Node con npm bundled');
+  }
+  return { bin: process.execPath, argsList: [NPM_CLI_JS, ...args], opts: {} };
+}
+
+/**
+ * Aumenta PATH con ubicaciones típicas de Node/npm en Windows.
+ * Devuelve un PATH listo para inyectar en el env de un subproceso.
+ */
+function pathAumentado() {
+  const extras = [
+    '/c/Program Files/nodejs',
+    '/c/Program Files (x86)/nodejs',
+    'C:\\Program Files\\nodejs',
+    'C:\\Program Files (x86)\\nodejs',
+    path.join(os.homedir(), 'AppData', 'Roaming', 'npm'),
+  ];
+  const sep = process.platform === 'win32' ? ';' : ':';
+  return extras.join(sep) + sep + (process.env.PATH || '');
+}
+
+/**
+ * Parsea una versión SemVer aceptando suffixes pre-release/build metadata.
+ * Devuelve null si la cadena no es semver válida.
+ */
+function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(String(v));
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Compara dos cadenas semver. Retorna 1, 0, -1 o null si alguna no parsea.
+ */
+function compararSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * Versión asíncrona: ejecuta `npm view <pkg> version` sin shell.
+ * Usa execFile para evitar inyección si el nombre del paquete viniera
+ * de input no confiable (defensa en profundidad — actualmente los
+ * nombres son constantes literales).
+ */
+function consultarUna(pkg, { timeoutMs = TIMEOUT_DEFAULT_MS, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    try {
+      asegurarNombrePaqueteSeguro(pkg);
+    } catch (e) {
+      resolve({ paquete: pkg, version: null, error: e.message });
+      return;
+    }
+    const { bin, argsList, opts } = comandoNpm(['view', pkg, 'version']);
+    execFile(bin, argsList, {
+      timeout: timeoutMs,
+      encoding: 'utf-8',
+      env,
+      ...opts,
+    }, (err, stdout) => {
+      if (err) {
+        resolve({ paquete: pkg, version: null, error: String(err.message).slice(0, 120) });
+        return;
+      }
+      const ver = String(stdout).trim();
+      if (/^\d+\.\d+\.\d+/.test(ver)) {
+        resolve({ paquete: pkg, version: ver });
+      } else {
+        resolve({ paquete: pkg, version: null, error: `formato inválido: ${ver.slice(0, 60)}` });
+      }
+    });
+  });
+}
+
+/**
+ * Consulta en paralelo la versión publicada de los nombres conocidos.
+ * Devuelve la primera versión válida encontrada (preferencia por orden
+ * en NOMBRES_DETECCION: canónico npmjs > mirror GH > legacy).
+ *
+ * Diseño:
+ *   - Ejecuta las consultas en paralelo con Promise.allSettled para que
+ *     el peor caso sea max(timeout) en vez de N × timeout en serie.
+ *   - Conserva orden de prioridad post-resolución para devolver el
+ *     resultado más canónico cuando varios responden con éxito.
+ *
+ * @returns {{paquete: string|null, version: string|null, intentos: Array}}
+ */
+async function versionRemotaParalela({ timeoutMs = TIMEOUT_DEFAULT_MS, paquetes = NOMBRES_DETECCION } = {}) {
+  const env = { ...process.env, PATH: pathAumentado() };
+  const promesas = paquetes.map(pkg => consultarUna(pkg, { timeoutMs, env }));
+  const settled = await Promise.allSettled(promesas);
+
+  // Registrar TODOS los resultados — éxitos y fallos — para que el
+  // diagnóstico downstream pueda mostrar cuántos paquetes respondieron.
+  // Antes este bloque omitía los éxitos posteriores al primer 'mejor',
+  // dejando intentos vacío cuando 2-3 paquetes resolvían correctamente.
+  const intentos = [];
+  let mejor = null;
+
+  for (let i = 0; i < paquetes.length; i++) {
+    const r = settled[i];
+    if (r.status === 'fulfilled') {
+      const { paquete, version, error } = r.value;
+      if (version) {
+        if (!mejor) mejor = { paquete, version };
+        intentos.push({ paquete, resultado: 'ok', version });
+      } else {
+        intentos.push({ paquete, resultado: 'error', error: error || 'sin versión' });
+      }
+    } else {
+      intentos.push({ paquete: paquetes[i], resultado: 'rejected', error: String(r.reason).slice(0, 120) });
+    }
+  }
+
+  if (mejor) return { ...mejor, intentos };
+  return { paquete: null, version: null, intentos };
+}
+
+/**
+ * Versión síncrona-bloqueante de la consulta. Útil para scripts CLI
+ * donde el flujo de control síncrono es más simple. Acepta también el
+ * orden de prioridad sin paralelizar.
+ *
+ * Implementación: usa deasync vía execFileSync con timeout corto por
+ * paquete (no paraleliza, pero sigue siendo más rápido que el patrón
+ * anterior gracias al timeout reducido por intento).
+ */
+function versionRemotaSync({ timeoutMs = TIMEOUT_DEFAULT_MS, paquetes = NOMBRES_DETECCION } = {}) {
+  const env = { ...process.env, PATH: pathAumentado() };
+  const intentos = [];
+
+  for (const pkg of paquetes) {
+    try {
+      asegurarNombrePaqueteSeguro(pkg);
+      const { bin, argsList, opts } = comandoNpm(['view', pkg, 'version']);
+      const result = execFileSync(bin, argsList, {
+        timeout: timeoutMs,
+        encoding: 'utf-8',
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        ...opts,
+      });
+      const ver = String(result).trim();
+      if (/^\d+\.\d+\.\d+/.test(ver)) {
+        return { paquete: pkg, version: ver, intentos };
+      }
+      intentos.push({ paquete: pkg, resultado: 'formato inválido', raw: ver.slice(0, 80) });
+    } catch (err) {
+      intentos.push({ paquete: pkg, resultado: 'error', error: String(err.message).slice(0, 120) });
+    }
+  }
+  return { paquete: null, version: null, intentos };
+}
+
+module.exports = {
+  pathAumentado,
+  parseSemver,
+  compararSemver,
+  consultarUna,
+  versionRemotaParalela,
+  versionRemotaSync,
+  TIMEOUT_DEFAULT_MS,
+};