@theoptimalpartner/npm-security-kit 2.0.0-beta.2 → 2.0.0-beta.4

package/CHANGELOG.md

@@ -6,11 +6,38 @@ Cambios del paquete `@theoptimalpartner/npm-security-kit`. Formato basado en
 ## [2.0.0] - sin publicar
 
 Reescritura completa. La v2 es una CLI de Node sin dependencias que corre en el pipeline **antes de `npm ci`**.
-Sale primero como beta (`2.0.0-beta.N`), con el dist-tag `beta`. Desde la `2.0.0-beta.1`, el step del pipeline y
-`init` usan `npx --yes --min-release-age=0`: `npx` no aplica `min-release-age-exclude` y, sin el flag, una versión
-nueva del kit no se puede usar hasta cumplir 7 días. Desde la `2.0.0-beta.2`, `init` propone el Node que ya usa el
-repo si es una LTS con soporte (la imagen del step de ejemplo y, si falta, `engines.node`), en vez de la LTS más
-nueva: un `engines.node` más alto que el Node del repo rompe su `npm ci` con `engine-strict`.
+Sale primero como beta (`2.0.0-beta.N`), con el dist-tag `beta`.
+
+### Betas
+
+- **2.0.0-beta.1:** el step del pipeline e `init` usan `npx --yes --min-release-age=0`: `npx` no aplica
+  `min-release-age-exclude` y, sin el flag, una versión nueva del kit no se puede usar hasta cumplir 7 días.
+- **2.0.0-beta.2:** `init` propone el Node que ya usa el repo si es una LTS con soporte, en vez de la LTS más nueva:
+  un `engines.node` más alto que el Node del repo rompe su `npm ci` con `engine-strict`.
+- **2.0.0-beta.3** (ajustes de una prueba en un repo real):
+  - `node-version` da error en una línea de Node que no trae npm >= 11.17 en ninguna release (la 22 trae npm 10),
+    con la LTS a la que subir.
+  - `init` solo propone una línea de Node cuya release LTS traiga npm >= 11.17: un repo en la 22 (npm 10) recibe la
+    24, con la explicación. La imagen es la release LTS más nueva de esa línea, sin parches de seguridad pendientes.
+  - `npm-policy` dice qué imagen trae npm 11 (`node:24.22.1 (npm 11.19.1) o más nueva`) y qué líneas no.
+  - `init` dice qué líneas agregar al step que ya corre `npm ci`, sin reemplazarlo, y arma la condition con las
+    ramas de `pipelines.branches`.
+  - `vulnerabilities` avisa las `critical` que están solo en devDependencies (no bloquean) y sugiere `npm audit fix`.
+  - Las recetas de lockfile usan `npm install --package-lock-only --ignore-scripts` (sin el flag, con
+    `strict-allow-scripts=true` npm corta con `ESTRICTALLOWSCRIPTS`).
+  - README: los ejemplos usan la versión del paquete (la `2.0.0` todavía no existe), `install-scripts ls` necesita
+    `node_modules`, y `approve` fija la versión (`--no-allow-scripts-pin` para no fijarla).
+- **2.0.0-beta.4** (ajustes de una segunda prueba):
+  - Un solo destino cuando hay que cambiar de línea (sin soporte, no LTS o sin npm 11), en `check`, `init` y el
+    mensaje de npm: la LTS con soporte más baja que trae npm 11, en la release más nueva que ya tiene imagen en
+    Docker Hub. Antes se proponían imágenes que todavía no existían, y la 18 y la 22 recibían destinos distintos.
+  - `init` no propone cambiar la imagen exacta que ya usa el pipeline si es de esa línea, salvo un parche de
+    seguridad que ya tenga imagen.
+  - La LTS nueva sin imagen oficial se informa sin avisar, como la que no tiene release LTS.
+  - En local, si la línea de Node no trae npm 11, el consejo es cambiar de línea con `nvm` (npm 11 sobre esa línea
+    da EBADENGINE con el `engines.node` de `init`). Los pasos siguientes de `init` incluyen el cambio de línea, el
+    lockfile y el `prepare` del proyecto; la sección del pipeline menciona `custom: ci`.
+  - `check` sin `package.json` termina con exit 2 ("no es un proyecto npm"), como `init`.
 
 ### BREAKING
 
@@ -41,7 +68,7 @@ nueva: un `engines.node` más alto que el Node del repo rompe su `npm ci` con `e
    `scripts/security-check.sh`, `.husky/` (y el `"prepare": "husky install"`), los scripts `security:*` del
    `package.json` y el `SECURITY.md` generado.
 2. Si la v1 reemplazó el `bitbucket-pipelines.yml`, recuperar el del repo desde git.
-3. Correr `npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 init` y seguir los pasos que imprime (README).
+3. Correr `npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@<versión> init` (la del README) y seguir los pasos que imprime (README).
 
 ## [1.0.2] y anteriores
 

package/README.md

@@ -3,13 +3,16 @@
 Reglas de seguridad de dependencias npm en un solo comando que corre en el pipeline **antes de `npm ci`**. No tiene
 dependencias: `npx` descarga un solo tarball y revisa el lockfile antes de que se ejecute un solo install script.
 
+Los ejemplos usan la versión de este paquete (`2.0.0-beta.4`). Las publicadas, con sus dist-tags:
+`npm view @theoptimalpartner/npm-security-kit dist-tags`.
+
 ## Qué revisa
 
 | Chequeo | Qué mira | Error (bloquea) | Aviso |
 |---|---|---|---|
 | `malware` | `npm audit` sobre **todo** el lockfile, incluidas las devDependencies | Cualquier advisory de malware (CWE-506), con cualquier severidad | — |
-| `vulnerabilities` | `npm audit --omit=dev` | Vulnerabilidades `critical` en producción | Resumen de las `high` |
-| `node-version` | `.nvmrc`, `.node-version`, `.tool-versions`, `engines.node`, `volta.node`, `FROM node:` y `image:` del pipeline | Línea de Node sin soporte o que no es LTS | Hay una LTS más nueva (mientras no tenga su primera release LTS, solo se informa), pocos días de soporte, parche de seguridad pendiente, versiones mayores distintas, nada fijado |
+| `vulnerabilities` | `npm audit --omit=dev` y, para las de desarrollo, el de todo el árbol | Vulnerabilidades `critical` en producción | Resumen de las `high` en producción; `critical` solo en devDependencies |
+| `node-version` | `.nvmrc`, `.node-version`, `.tool-versions`, `engines.node`, `volta.node`, `FROM node:` y `image:` del pipeline | Línea de Node sin soporte, que no es LTS o que no trae npm >= 11.17 en ninguna release (Node 22 trae npm 10) | Hay una LTS más nueva (mientras no tenga su primera release LTS, solo se informa), pocos días de soporte, parche de seguridad pendiente, versiones mayores distintas, nada fijado |
 | `npm-policy` | `.npmrc`, `engines.npm`, npm en uso, lockfile | Faltan `min-release-age`, `engine-strict` o `strict-allow-scripts`; npm < 11.17; no hay lockfile | Faltan `min-release-age-exclude[]`, `save-exact` o `audit-level`; lockfile < v3 |
 | `install-scripts` | Paquetes con install scripts del lockfile contra `allowScripts` | Alguno sin aprobar (con `strict-allow-scripts`) | Alguno sin aprobar con el override por variable de entorno |
 | `dockerfile` | `COPY` del `.npmrc` antes de `npm ci`, `.dockerignore` | Instala sin el `.npmrc` | Usa `npm install` en vez de `npm ci`; el `.dockerignore` deja fuera el lockfile |
@@ -40,12 +43,20 @@ audit-level=critical
 
 Además, `engines.npm` en `>=11.17`: npm 10 ignora `min-release-age` sin avisar y no aplica `allowScripts`.
 
+**Node y npm:** ninguna release de Node 20 ni de Node 22 trae npm 11 (traen npm 10). Un repo en la 22 tiene que
+subir a una LTS que traiga npm 11. `check` da error en cada lugar que fija la 22 (`.nvmrc`, `engines.node`, `FROM`,
+`image:`) e `init` propone la línea nueva. Cuando hay que cambiar de línea (sin soporte, no LTS o sin npm 11), el
+destino es uno solo: la LTS con soporte más baja que trae npm 11 (hoy la 24), en la release más nueva que **ya tiene
+imagen oficial en Docker Hub** (las imágenes salen días después que la release en nodejs.org). En local, cambiar de
+línea con `nvm install 24 && nvm use 24`: npm 11 sobre la 22 no alcanza, porque `engines.node` pide la 24.
+
 ## Uso
 
 ### En el pipeline
 
-Un step **antes de `npm ci`**, con la versión del kit fija y solo en los PR a ramas que despliegan (ejemplo de
-`bitbucket-pipelines.yml`, el pipeline que lee el chequeo de Node):
+En el step de test que ya existe, **sin reemplazarlo**: el kit antes de `npm ci` y `npm audit signatures` después.
+El step corre solo en los PR a las ramas que despliegan (las de `pipelines.branches`). `init` imprime qué agregar y
+en qué línea. Ejemplo de `bitbucket-pipelines.yml` (el pipeline que lee el chequeo de Node):
 
 ```yaml
 definitions:
@@ -57,10 +68,10 @@ definitions:
           - npm
         script:
           # Antes de instalar: malware, vulnerabilidades, Node, .npmrc, install scripts, Dockerfiles
-          - npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 check
+          - npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 check
           - npm ci            # con strict-allow-scripts, los scripts no aprobados cortan acá
           - npm audit signatures
-          - npm run build
+          # … y lo que ya corría el step: build, lint, tests
 
 pipelines:
   pull-requests:
@@ -68,23 +79,28 @@ pipelines:
       - step:
           <<: *test
           condition:
-            state: BITBUCKET_PR_DESTINATION_BRANCH == "develop" || BITBUCKET_PR_DESTINATION_BRANCH == "main"
+            # Las ramas de pipelines.branches (las que despliegan)
+            state: BITBUCKET_PR_DESTINATION_BRANCH == "main" || BITBUCKET_PR_DESTINATION_BRANCH == "develop"
+  custom:
+    ci:          # para correrlo a mano ("Run pipeline")
+      - step: *test
 ```
 
 - **Antes de `npm ci`:** `npm audit` funciona solo con el lockfile, así que el malware se detecta antes de que
   corra su `postinstall`.
-- **Versión fija** (`@2.0.0`): subir la política en un repo es un cambio visible en su PR.
+- **Versión fija** (`@2.0.0-beta.4`): subir la política en un repo es un cambio visible en su PR.
 - **`--min-release-age=0` solo para `npx`:** `npx` no aplica `min-release-age-exclude` (npm 11.19.1 lo aplica al
   instalar, no al resolver el paquete de `npx`). Sin el flag, dentro de un repo con `min-release-age=7` una versión
   nueva del kit no se puede usar hasta cumplir 7 días (`ETARGET … with a date before`). Afecta solo al kit: la
   versión va fija y no tiene dependencias. El `npm ci` que sigue aplica los 7 días como siempre.
 - **`npm audit signatures`** va después de `npm ci` porque necesita `node_modules`.
-- Para guardar el resultado como artefacto: `npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 check --json > npm-security-kit.json`.
+- Para guardar el resultado como artefacto: `npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 check --json > npm-security-kit.json`.
 
 ### Dockerfile
 
 El `.npmrc` se copia con el lockfile, antes de `npm ci`. Si no, dentro de la imagen no aplican
-`strict-allow-scripts`, `min-release-age` ni `engine-strict`:
+`strict-allow-scripts`, `min-release-age` ni `engine-strict`. El `FROM` tiene que traer npm 11 (Node 24 o más nueva;
+ver **Node y npm** más arriba):
 
 ```dockerfile
 COPY package.json package-lock.json .npmrc ./
@@ -98,20 +114,22 @@ Si el `.dockerignore` excluye el `.npmrc` (por ejemplo con `.*`), agregar `!.npm
 Una vez por repo, en una rama:
 
 ```bash
-npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 init --dry-run
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 init --dry-run
 ```
 
 ```bash
-npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 init
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 init
 ```
 
 `init`:
 
 - agrega al `.npmrc` las claves de la política que faltan (con un comentario) y corrige las que tienen otro valor,
   sin borrar ni reordenar nada;
-- completa `engines.npm` (`>=11.17`) y, solo si falta, `engines.node`;
+- completa `engines.npm` (`>=11.17`) y, solo si falta, `engines.node` (con la línea de Node del repo, si trae npm 11;
+  si no, la siguiente que lo trae);
 - **no aprueba install scripts**: lista los pendientes y los comandos para revisarlos;
-- **no edita** `bitbucket-pipelines.yml` ni los Dockerfiles: muestra el step y los `COPY` corregidos;
+- **no edita** `bitbucket-pipelines.yml` ni los Dockerfiles: dice qué líneas agregar al step que corre `npm ci`, la
+  condition con las ramas que despliegan y los `COPY` corregidos;
 - se puede correr de nuevo sin cambiar nada.
 
 Después: revisar el diff, aprobar o negar los install scripts, aplicar el step y el Dockerfile, y correr `check`.
@@ -119,7 +137,7 @@ Después: revisar el diff, aprobar o negar los install scripts, aplicar el step
 ### En local
 
 ```bash
-npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0 check
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 check
 ```
 
 No se instala como devDependency ni usa husky: el `.npmrc` protege el `npm install` local y el pipeline es el
@@ -144,10 +162,12 @@ Dockerfile y pipeline) va una sola vez, con la lista de archivos.
 
 ### `npm ci` falla con EUSAGE (lockfile incompleto)
 
-Pasa con lockfiles generados con npm 10, a los que les faltan opcionales de plataforma. Regenerarlo con npm 11:
+Pasa con lockfiles generados con npm 10, a los que les faltan opcionales de plataforma. Regenerarlo con npm 11, sin
+scripts (con `strict-allow-scripts=true`, sin `--ignore-scripts` npm corta con `ESTRICTALLOWSCRIPTS` antes de
+regenerarlo):
 
 ```bash
-npm install --package-lock-only
+npm install --package-lock-only --ignore-scripts
 ```
 
 ### Parche urgente con menos de 7 días
@@ -170,6 +190,17 @@ npm install-scripts approve esbuild   # baja el binario de su plataforma: lo nec
 npm install-scripts deny core-js      # solo imprime un mensaje: no hace falta
 ```
 
+`npm install-scripts ls` lee `node_modules`: si el `npm ci --ignore-scripts` falló (por ejemplo con EUSAGE), dice que
+no hay nada pendiente. La lista de `check` e `init` sale del lockfile y no depende de eso.
+
+`--ignore-scripts` tampoco corre los scripts del propio proyecto, como el `prepare` que instala husky: si el repo los
+usa, `npm run prepare` después (si no, el hook de git falla en el próximo commit).
+
+`approve` guarda la versión exacta (`"paquete@1.2.3": true`): cuando se actualiza el paquete, `check` vuelve a dar
+error hasta aprobar la versión nueva. Es a propósito (cada versión nueva se revisa). Para un paquete de confianza que
+se actualiza seguido, `npm install-scripts approve --no-allow-scripts-pin <paquete>` lo aprueba sin versión. `deny`
+siempre guarda el nombre sin versión.
+
 Se aprueba lo que necesita compilar o bajar binarios para funcionar, y se niega lo que es solo telemetría o
 publicidad. El kit no aprueba nada en automático. Queda en `allowScripts` del `package.json`. Reglas (las mismas de
 npm):
@@ -190,6 +221,12 @@ Si un repo no puede adoptar todavía la aprobación de install scripts, se defin
 Con el override, npm ejecuta los scripts sin aprobar y el kit los informa como **aviso**, más un aviso de que el
 override está activo. Dentro del `docker build` la variable no llega sola: hay que pasarla como `ARG`.
 
+### Vulnerabilidades `critical` en devDependencies
+
+No bloquean (no llegan a producción), pero corren en el pipeline y en las máquinas de los devs: `check` las informa
+como aviso. Casi siempre las arregla `npm audit fix` (sin `--force`, que puede subir de major), o subir la
+dependencia que las trae.
+
 ### El registro de npm no responde
 
 El chequeo de malware falla cerrado: `no se pudo consultar los advisories del registro (…); reintentar el step`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoptimalpartner/npm-security-kit",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.4",
   "description": "Revisa el lockfile antes de npm ci: malware, vulnerabilidades, versión de Node, .npmrc, install scripts y Dockerfiles",
   "type": "module",
   "bin": {

package/src/checks/malware.js

@@ -1,6 +1,6 @@
 // Malware en todo el árbol (incluidas las devDependencies), con cualquier severidad.
 // GitHub publica malware como `high` (debug@4.4.2): un umbral de severidad lo deja pasar.
-import { AuditUnavailableError, advisoriesOf, advisoryKey, isMalware, lockfileName, runAudit, unavailableFinding } from '../lib/audit.js';
+import { AuditUnavailableError, FULL_TREE, advisoriesOf, advisoryKey, isMalware, lockfileName, runAudit, unavailableFinding } from '../lib/audit.js';
 
 export const id = 'malware';
 export const title = 'Malware (todo el árbol, cualquier severidad)';
@@ -23,7 +23,7 @@ export async function run(ctx) {
   if (!lockfile) return []; // sin lockfile no hay audit; lo informa npm-policy
   let report;
   try {
-    report = await runAudit(ctx, ['--include=dev', '--include=optional', '--include=peer']);
+    report = await runAudit(ctx, FULL_TREE);
   } catch (error) {
     if (error instanceof AuditUnavailableError) return [unavailableFinding(error)];
     throw error;

package/src/checks/node-version.js

@@ -1,10 +1,12 @@
-// Versión de Node: pasa cualquier LTS con soporte (Active o Maintenance); se avisa si hay una LTS
-// más nueva, si quedan pocos días de soporte o si hay parches de seguridad pendientes. Una línea
-// sin soporte o que no es LTS es error. Todo sale del calendario de nodejs.org.
+// Versión de Node: pasa cualquier LTS con soporte (Active o Maintenance) cuyas releases traigan el npm
+// que pide la política; se avisa si hay una LTS más nueva, si quedan pocos días de soporte o si hay
+// parches de seguridad pendientes. Una línea sin soporte, que no es LTS o que no trae ese npm (la 22
+// trae npm 10) es error. Todo sale del calendario de nodejs.org.
 import { findDockerfiles, nodeImageTag, parseStages } from '../lib/dockerfile.js';
 import { jsonKeyLine } from '../lib/json-lines.js';
 import { loadCalendar } from '../lib/node-calendar.js';
-import { isRange, minVersion, parseVersion } from '../lib/semver.js';
+import { imageExists, newestWithImage, upgradeTarget } from '../lib/node-target.js';
+import { compareVersions, isRange, minVersion, parseVersion } from '../lib/semver.js';
 
 export const id = 'node-version';
 export const title = 'Versión de Node';
@@ -145,7 +147,10 @@ export function resolvePin(pin, cal) {
   return { major: v[0], exact: parts === 3 ? v.join('.') : undefined };
 }
 
-function evaluate(pin, r, cal, policy) {
+// `target` es el destino único cuando hay que cambiar de línea (lib/node-target.js). En los pines de
+// Docker se propone su imagen, que ya existe en Docker Hub.
+async function evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage }) {
+  const { policy } = ctx;
   const base = { file: pin.file, line: pin.line };
   if (r.otherImage) {
     return { ...base, level: 'info', message: `${pin.spec}: imagen sin Node fijado (la versión de Node la decide la imagen).`, data: { pin: pin.pin } };
@@ -154,9 +159,9 @@ function evaluate(pin, r, cal, policy) {
 
   const sch = cal.lines.get(r.major);
   const prefix = `${r.range ? 'el rango admite desde ' : ''}v${r.major}${r.floating ? ` (${r.floating})` : ''}`;
-  const rec = cal.recommended;
-  const engineHint = pin.kind === 'engines' ? ` (en engines: ">=${parseVersion(rec)[0]}")` : '';
-  const data = { pin: pin.pin, major: r.major, phase: cal.phaseOf(r.major), recommended: rec };
+  const rec = target ? (pin.kind === 'docker' ? target.image : target.version) : cal.recommended;
+  const engineHint = pin.kind === 'engines' ? ` (en engines: ">=${target ? target.major : parseVersion(rec)[0]}")` : '';
+  const data = { pin: pin.pin, major: r.major, phase: cal.phaseOf(r.major), recommended: target?.version ?? cal.recommended };
   if (!sch) return { ...base, level: 'warn', message: `${prefix}: no aparece en el calendario de Node.`, data };
 
   const phase = cal.phaseOf(r.major);
@@ -167,6 +172,18 @@ function evaluate(pin, r, cal, policy) {
     const why = sch.lts ? `todavía no es LTS (lo será el ${sch.lts})` : 'línea impar, nunca va a ser LTS';
     return { ...base, level: 'error', message: `${prefix}: no es LTS, ${why}. Usar ${rec}${engineHint}.`, data };
   }
+  // La política pide npm >= minNpmVersion y la imagen de Node trae el suyo: una línea que no lo trae en
+  // ninguna release (la 22 trae npm 10) deja el pipeline y el docker build con npm 10.
+  const lineNpm = cal.npmOfLine(r.major);
+  if (lineNpm && parseVersion(lineNpm) && compareVersions(lineNpm, policy.minNpmVersion) < 0) {
+    const to = target?.npm ? `${rec} (npm ${target.npm})` : rec;
+    return {
+      ...base,
+      level: 'error',
+      message: `${prefix}: trae npm ${lineNpm}, y ninguna release de la ${r.major} trae npm >= ${policy.minNpmVersion}, que pide la política. Subir a una LTS con npm 11: ${to} o más nueva${engineHint}.`,
+      data: { ...data, npm: lineNpm },
+    };
+  }
 
   const notes = [];
   // Mientras la LTS nueva no tiene su primera release LTS nadie puede migrar: se informa sin avisar.
@@ -176,6 +193,8 @@ function evaluate(pin, r, cal, policy) {
     const n = cal.lines.get(cal.newestLts);
     if (cal.newestLtsWithoutRelease) {
       infoNotes.push(`Hay una LTS nueva (v${cal.newestLts}, desde ${n.lts}), aún sin release LTS: planificar la migración cuando salga.`);
+    } else if (newestLtsWithoutImage) {
+      infoNotes.push(`Hay una LTS nueva (v${cal.newestLts}, desde ${n.lts}), aún sin imagen oficial en Docker Hub: planificar la migración cuando salga.`);
     } else {
       notes.push(`Hay una LTS nueva (v${cal.newestLts}, desde ${n.lts}): planificar la migración.`);
     }
@@ -187,7 +206,11 @@ function evaluate(pin, r, cal, policy) {
   }
   if (r.exact) {
     const sec = cal.securityAfter(r.major, r.exact);
-    if (sec.length) notes.push(`Hay releases de seguridad posteriores a ${r.exact}: como mínimo ${sec[0].version.replace(/^v/, '')}.`);
+    if (sec.length) {
+      const first = sec[0].version.replace(/^v/, '');
+      const noImage = pin.kind === 'docker' && (await imageExists(ctx, first)) === false ? ' (todavía sin imagen en Docker Hub)' : '';
+      notes.push(`Hay releases de seguridad posteriores a ${r.exact}: como mínimo ${first}${noImage}.`);
+    }
   }
   const support = `con soporte hasta ${sch.end}${days < policy.nodeEolWarnDays ? ` (quedan ${days} días)` : ''}`;
   if (!notes.length && !infoNotes.length && days >= policy.nodeEolWarnDays) {
@@ -209,6 +232,10 @@ export async function run(ctx) {
   }
   if (!cal.recommended) return [{ level: 'warn', message: 'el calendario de Node no trae releases LTS; se omite el chequeo.' }];
 
+  const target = await upgradeTarget(ctx, cal);
+  // Mientras la LTS más nueva no tiene imagen oficial nadie la puede usar en el pipeline: se informa.
+  const newestLtsWithoutImage =
+    cal.newestLts !== null && !cal.newestLtsWithoutRelease && (await newestWithImage(ctx, cal, cal.newestLts)) === null;
   const pins = findPins(ctx);
   const findings = [];
   const majors = new Set();
@@ -217,13 +244,13 @@ export async function run(ctx) {
     const r = resolvePin(pin, cal);
     if (!r.otherImage) nodePins++;
     if (r.major !== undefined && r.major !== null) majors.add(r.major);
-    findings.push(evaluate(pin, r, cal, ctx.policy));
+    findings.push(await evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage }));
   }
   if (!nodePins) {
-    const major = parseVersion(cal.recommended)[0];
+    const version = target?.version ?? cal.recommended;
     findings.push({
       level: 'warn',
-      message: `No se fija la versión de Node en ningún lado (.nvmrc, engines.node, Dockerfile, pipeline). Fijarla, por ejemplo: .nvmrc con ${cal.recommended} y engines.node ">=${major}".`,
+      message: `No se fija la versión de Node en ningún lado (.nvmrc, engines.node, Dockerfile, pipeline). Fijarla, por ejemplo: .nvmrc con ${version} y engines.node ">=${parseVersion(version)[0]}".`,
     });
   }
   if (majors.size > 1) {

package/src/checks/npm-policy.js

@@ -3,6 +3,8 @@
 import { lockfileName } from '../lib/audit.js';
 import { parseNpmrc, requiredSettings, settingProblem } from '../lib/npmrc.js';
 import { jsonKeyLine } from '../lib/json-lines.js';
+import { linesWithNpm, loadCalendar } from '../lib/node-calendar.js';
+import { upgradeTarget } from '../lib/node-target.js';
 import { compareVersions, minVersion, parseVersion } from '../lib/semver.js';
 
 export const id = 'npm-policy';
@@ -10,6 +12,32 @@ export const title = 'npm y .npmrc';
 
 const NPM10_WHY = 'npm 10 ignora min-release-age sin avisar y no aplica allowScripts';
 
+// Qué hacer para tener ese npm: en el pipeline, la imagen del destino único (lib/node-target.js); en
+// local, cambiar de línea si la del Node que corre no lo trae (con engine-strict y el engines.node de
+// init, npm 11 sobre la 22 da EBADENGINE) o, si la trae, actualizar npm. Sin calendario, lo genérico.
+async function npmHint(ctx, minNpm) {
+  const generic = { pipeline: 'usar la imagen de Node LTS recomendada', local: '`npm install -g npm@11`' };
+  let cal;
+  let target;
+  try {
+    cal = await loadCalendar(ctx);
+    target = await upgradeTarget(ctx, cal);
+  } catch {
+    return generic;
+  }
+  if (!target) return generic;
+  const major = parseVersion(minNpm)[0];
+  const { without } = linesWithNpm(cal, minNpm);
+  const none = without.length ? `; ninguna release de Node ${without.join(' ni ')} trae npm ${major}` : '';
+  const running = parseVersion(ctx.nodeVersion ?? '')?.[0];
+  return {
+    pipeline: `usar una imagen de Node que lo traiga: node:${target.image}${target.npm ? ` (npm ${target.npm})` : ''} o más nueva${none}`,
+    local: without.includes(running)
+      ? `pasar a la ${target.major}: \`nvm install ${target.major} && nvm use ${target.major}\` (la ${running} no trae npm ${major})`
+      : '`npm install -g npm@11`',
+  };
+}
+
 export async function run(ctx) {
   const { policy } = ctx;
   const findings = [];
@@ -88,7 +116,9 @@ export async function run(ctx) {
   } else if (compareVersions(used, minNpm) < 0) {
     findings.push({
       level: 'error',
-      message: `npm ${used} en uso: hace falta npm >= ${minNpm} (${NPM10_WHY}). En el pipeline, usar la imagen de Node LTS recomendada; en local, \`npm install -g npm@11\`.`,
+      message: (({ pipeline, local }) => `npm ${used} en uso: hace falta npm >= ${minNpm} (${NPM10_WHY}). En el pipeline y en el Dockerfile, ${pipeline}. En local, ${local}.`)(
+        await npmHint(ctx, minNpm),
+      ),
       data: { npm: used },
     });
   }
@@ -99,7 +129,7 @@ export async function run(ctx) {
     const other = ['yarn.lock', 'pnpm-lock.yaml'].find((f) => ctx.exists(f));
     findings.push({
       level: 'error',
-      message: `No hay package-lock.json: sin lockfile no hay \`npm ci\` ni audit.${other ? ` (${other} no sirve: el kit revisa proyectos npm.)` : ' Generarlo con `npm install --package-lock-only`.'}`,
+      message: `No hay package-lock.json: sin lockfile no hay \`npm ci\` ni audit.${other ? ` (${other} no sirve: el kit revisa proyectos npm.)` : ' Generarlo con `npm install --package-lock-only --ignore-scripts`.'}`,
     });
   } else {
     const lock = ctx.readJson(lockfile);
@@ -107,13 +137,13 @@ export async function run(ctx) {
       findings.push({
         level: 'error',
         file: lockfile,
-        message: `lockfileVersion ${lock.lockfileVersion ?? '?'}: no trae \`packages\` (ni \`hasInstallScript\`), así que no se pueden revisar los install scripts. Regenerar con npm 11 (\`npm install --package-lock-only\`).`,
+        message: `lockfileVersion ${lock.lockfileVersion ?? '?'}: no trae \`packages\` (ni \`hasInstallScript\`), así que no se pueden revisar los install scripts. Regenerar con npm 11 (\`npm install --package-lock-only --ignore-scripts\`).`,
       });
     } else if (!(lock.lockfileVersion >= 3)) {
       findings.push({
         level: 'warn',
         file: lockfile,
-        message: `lockfileVersion ${lock.lockfileVersion ?? '?'}: regenerar con npm 11 (\`npm install --package-lock-only\`).`,
+        message: `lockfileVersion ${lock.lockfileVersion ?? '?'}: regenerar con npm 11 (\`npm install --package-lock-only --ignore-scripts\`).`,
       });
     }
   }

package/src/checks/vulnerabilities.js

@@ -1,7 +1,10 @@
 // Vulnerabilidades (que no son malware) en dependencias de producción. Bloquea desde
-// `policy.vulnerabilityLevel`; las `high` van en un solo aviso de resumen.
+// `policy.vulnerabilityLevel`; las `high` van en un solo aviso de resumen. Las de ese nivel que están
+// solo en devDependencies van en otro aviso: no llegan a producción, pero corren en el pipeline y en
+// las máquinas de los devs.
 import {
   AuditUnavailableError,
+  FULL_TREE,
   advisoriesOf,
   advisoryKey,
   isMalware,
@@ -75,5 +78,33 @@ export async function run(ctx) {
       data: { severity: 'high', count: high.length, packages: high },
     });
   }
+
+  // El reporte de todo el árbol es el mismo que pide `malware` (una sola llamada). Si el registro no
+  // responde, ese chequeo ya da el error.
+  let full = null;
+  try {
+    full = await runAudit(ctx, FULL_TREE);
+  } catch (error) {
+    if (!(error instanceof AuditUnavailableError)) throw error;
+  }
+  const devOnly = full
+    ? [
+        ...new Set(
+          advisoriesOf(full)
+            .filter((a) => !isMalware(a, ctx.policy) && severityAtLeast(a.severity, level) && !byPackage.has(a.name))
+            .map((a) => a.name),
+        ),
+      ].sort()
+    : [];
+  if (devOnly.length) {
+    findings.push({
+      level: 'warn',
+      file: lockfile,
+      message:
+        `${devOnly.length} paquete(s) con vulnerabilidades ${level} solo en devDependencies (${devOnly.join(', ')}). ` +
+        'No llegan a producción y no bloquean, pero corren en el pipeline y en las máquinas de los devs: `npm audit fix` (sin `--force`) o subir la dependencia que las trae.',
+      data: { severity: level, dev: true, count: devOnly.length, packages: devOnly },
+    });
+  }
   return findings;
 }

package/src/cli.js

@@ -1,7 +1,7 @@
 // Parseo de argumentos y despacho de comandos. Devuelve el exit code:
 // 0 sin errores (puede haber avisos), 1 con al menos un error, 2 por uso incorrecto o fallo interno.
 import { existsSync, statSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { checks } from './checks/index.js';
 import { createContext, parseDay } from './context.js';
@@ -94,6 +94,10 @@ export async function main(argv, io = {}) {
     stderr.write(`npm-security-kit: no existe el directorio ${dir}\n`);
     return 2;
   }
+  if (args.command === 'check' && !existsSync(join(dir, 'package.json'))) {
+    stderr.write(`npm-security-kit: no hay package.json en ${dir}. check se corre en la raíz de un proyecto npm.\n`);
+    return 2;
+  }
   const ctx = createContext({
     dir,
     env,

package/src/context.js

@@ -51,6 +51,7 @@ export function createContext({
   base,
   fetchImpl = globalThis.fetch,
   wait = sleep,
+  nodeVersion = process.versions.node,
 } = {}) {
   const abs = (file) => join(dir, file);
 
@@ -134,6 +135,7 @@ export function createContext({
     platform,
     arch,
     base,
+    nodeVersion,
     kitVersion,
     readFile,
     readJson,

package/src/init.js

@@ -10,7 +10,8 @@ import * as npmPolicyCheck from './checks/npm-policy.js';
 import { loadAllowPolicy, verdict } from './lib/allow-scripts.js';
 import { lockfileName } from './lib/audit.js';
 import { unifiedDiff } from './lib/diff.js';
-import { loadCalendar } from './lib/node-calendar.js';
+import { linesWithNpm, loadCalendar } from './lib/node-calendar.js';
+import { imageExists, newestWithImage, upgradeTarget } from './lib/node-target.js';
 import { parseNpmrc, requiredSettings, settingProblem } from './lib/npmrc.js';
 import { compareVersions, minVersion, parseVersion } from './lib/semver.js';
 import { formatBlocks } from './report.js';
@@ -77,28 +78,79 @@ export function mergePackageJson(text, policy, nodeMajor) {
   return { text: finalNewline ? `${out}${eol}` : out, changes };
 }
 
-// El Node que init propone (engines.node y la imagen del step de ejemplo): el que ya usa el repo si es
-// de una LTS con soporte, para que adoptar el kit no obligue a cambiar de Node. engines.node toma la
-// línea más baja en uso (con engine-strict, un ">=" más alto rompe el npm ci de esa línea), y la imagen,
-// la versión exacta del pipeline. Sin eso, la release LTS recomendada.
-export function repoNode(ctx, cal) {
-  const recommended = cal.recommended ?? null;
-  let major = null;
-  let image = null;
+// El Node que init propone (engines.node, si falta, y la imagen del pipeline): el que ya usa el repo
+// si es de una LTS con soporte, para que adoptar el kit no obligue a cambiar de Node. Tiene que traer
+// el npm que pide la política: si la línea del repo no lo trae en ninguna release (la 22 trae npm 10),
+// la siguiente que sí, y `from` dice de cuál viene. engines.node toma la línea más baja en uso (con
+// engine-strict, un ">=" más alto rompe el npm ci de esa línea). La imagen es la exacta que ya usa el
+// pipeline si es de esa línea y no hay un parche de seguridad posterior con imagen publicada; si no,
+// la release más nueva de la línea con imagen en Docker Hub. Sin Node fijado (o solo líneas sin
+// soporte), el destino único de lib/node-target.js.
+export async function repoNode(ctx, cal) {
+  const target = await upgradeTarget(ctx, cal);
+  let inUse = null;
+  let pipelinePin = null;
   for (const pin of nodeVersionCheck.findPins(ctx)) {
     const r = nodeVersionCheck.resolvePin(pin, cal);
     if (r.major === undefined || r.major === null || r.latest) continue;
     if (!['active', 'maintenance'].includes(cal.phaseOf(r.major))) continue;
-    if (major === null || r.major < major) major = r.major;
-    if (!image && pin.file === 'bitbucket-pipelines.yml' && pin.kind === 'docker' && r.exact) image = r.exact;
+    if (inUse === null || r.major < inUse) inUse = r.major;
+    if (!pipelinePin && pin.file === 'bitbucket-pipelines.yml' && pin.kind === 'docker' && r.exact) pipelinePin = r;
   }
-  return {
-    major: major ?? (recommended ? parseVersion(recommended)[0] : null),
-    image: image ?? recommended,
-  };
+  if (!target) return { major: null, image: null, npm: null, from: null };
+  const major = inUse === null ? target.major : (linesWithNpm(cal, ctx.policy.minNpmVersion).ok.find((m) => m >= inUse) ?? target.major);
+  const from = inUse !== null && major !== inUse ? inUse : null;
+  if (pipelinePin?.major === major) {
+    let patched = false;
+    for (const s of cal.securityAfter(major, pipelinePin.exact)) {
+      if ((await imageExists(ctx, s.version.replace(/^v/, ''))) === true) patched = true;
+    }
+    if (!patched) return { major, image: pipelinePin.exact, npm: cal.npmOf(pipelinePin.exact), from };
+  }
+  if (major === target.major) return { major, image: target.image, npm: target.npm, from };
+  const found = await newestWithImage(ctx, cal, major);
+  return { major, image: found?.image ?? String(major), npm: found?.npm ?? cal.npmOfLine(major), from };
+}
+
+// Las ramas que despliegan: las claves de `pipelines.branches` (sin globs), en orden.
+export function deployBranches(text) {
+  const out = [];
+  let inPipelines = false;
+  let branchesIndent = null;
+  let keyIndent = null;
+  for (const raw of (text ?? '').split(/\r?\n/)) {
+    if (!raw.trim() || raw.trim().startsWith('#')) continue;
+    if (/^\S/.test(raw)) {
+      inPipelines = /^pipelines:\s*(#.*)?$/.test(raw);
+      branchesIndent = null;
+      continue;
+    }
+    if (!inPipelines) continue;
+    const indent = raw.match(/^ */)[0].length;
+    const branches = raw.match(/^( *)branches:\s*(#.*)?$/);
+    if (branches) {
+      branchesIndent = branches[1].length;
+      keyIndent = null;
+      continue;
+    }
+    if (branchesIndent === null) continue;
+    if (indent <= branchesIndent) {
+      branchesIndent = null;
+      continue;
+    }
+    keyIndent ??= indent;
+    const key = raw.match(/^ *(['"]?)([^'"#:\s][^'"#:]*)\1:\s*(#.*)?$/);
+    if (indent === keyIndent && key && !/[*?{}[\]]/.test(key[2])) out.push(key[2].trim());
+  }
+  return out;
 }
 
-export function pipelineStep(kitVersion, nodeVersion) {
+export function prCondition(branches) {
+  const names = branches.length ? branches : ['develop', 'main'];
+  return names.map((b) => `BITBUCKET_PR_DESTINATION_BRANCH == "${b}"`).join(' || ');
+}
+
+export function pipelineStep(kitVersion, nodeVersion, branches = []) {
   return `- step: &test
     name: Test (supply chain + build)
     image: node:${nodeVersion}
@@ -109,14 +161,14 @@ export function pipelineStep(kitVersion, nodeVersion) {
       - npx --yes --min-release-age=0 ${PACKAGE}@${kitVersion} check
       - npm ci
       - npm audit signatures
-      - npm run build
+      # … y lo que ya corre el step: build, lint, tests
 pipelines:
   pull-requests:
     '**':
       - step:
           <<: *test
           condition:
-            state: BITBUCKET_PR_DESTINATION_BRANCH == "develop" || BITBUCKET_PR_DESTINATION_BRANCH == "main"`;
+            state: ${prCondition(branches)}`;
 }
 
 // ctx que ve los archivos como quedarían después de init (para el resumen de --dry-run) y
@@ -168,7 +220,7 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   } catch (error) {
     cal = { error };
   }
-  const node = cal.error ? { major: null, image: null } : repoNode(ctx, cal);
+  const node = cal.error ? { major: null, image: null, npm: null, from: null } : await repoNode(ctx, cal);
 
   say(paint(2, `npm-security-kit ${ctx.kitVersion} · init${dryRun ? ' --dry-run' : ''} · ${ctx.dir}`));
 
@@ -196,7 +248,7 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   section('Install scripts por aprobar (allowScripts en package.json)');
   const lockfile = lockfileName(ctx);
   if (!lockfile) {
-    say('  No hay package-lock.json: generarlo con `npm install --package-lock-only` y volver a correr init.');
+    say('  No hay package-lock.json: generarlo con `npm install --package-lock-only --ignore-scripts` y volver a correr init.');
   } else {
     const policy = loadAllowPolicy(JSON.parse(view.readFile('package.json')), view.readFile('.npmrc'));
     const pending = [
@@ -210,11 +262,13 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
       say('  Ninguno: todos los paquetes con install scripts están aprobados o negados.');
     } else {
       for (const p of pending) say(`  - ${p}`);
-      say('  init no aprueba nada solo. Para revisarlos:');
-      say('    npm ci --ignore-scripts');
+      say('  init no aprueba nada solo. Para revisarlos (`npm install-scripts` lee node_modules: primero hace falta un npm ci):');
+      say('    npm ci --ignore-scripts                 # si da EUSAGE: npm install --package-lock-only --ignore-scripts');
       say('    npm install-scripts ls');
-      say('    npm install-scripts approve <paquete>   # lo que necesita compilar o descargar binarios');
+      say('    npm install-scripts approve <paquete>   # lo que necesita compilar o descargar binarios; fija la versión');
       say('    npm install-scripts deny <paquete>      # telemetría, publicidad o lo que no haga falta');
+      say('  `approve` guarda `paquete@versión`: al actualizar el paquete hay que volver a aprobarlo (o aprobar sin');
+      say('  versión con `npm install-scripts approve --no-allow-scripts-pin <paquete>`).');
     }
   }
 
@@ -222,12 +276,37 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   section('Pipeline: bitbucket-pipelines.yml (init no lo edita)');
   const pipeline = ctx.readFile('bitbucket-pipelines.yml');
   const used = pipeline?.match(/npm-security-kit@([\w.-]+)/);
+  const image = node.image ?? '<versión LTS>';
+  if (node.from !== null && node.from !== undefined) {
+    say(
+      `  El repo usa Node ${node.from}, pero ninguna release de la ${node.from} trae npm >= ${ctx.policy.minNpmVersion}, que pide la política: ` +
+        `se propone la ${node.major} (node:${image}${node.npm ? `, npm ${node.npm}` : ''}). Pasar a la ${node.major} el .nvmrc, las imágenes del pipeline y los FROM de los Dockerfiles.`,
+    );
+  }
+  const branches = deployBranches(pipeline);
+  const ciLines = (pipeline ?? '').split(/\r?\n/).flatMap((l, i) => (/^\s*-\s*npm ci(\s|$)/.test(l) ? [i + 1] : []));
   if (used) {
     say(`  Ya corre el kit (${used[0]}).${used[1] !== ctx.kitVersion ? ` Para esta versión: ${PACKAGE}@${ctx.kitVersion}.` : ''}`);
+  } else if (ciLines.length) {
+    say(`  Agregar al step que ya corre npm ci (bitbucket-pipelines.yml:${ciLines.join(', ')}), sin reemplazar el resto del step:`);
+    say();
+    say(`    - npx --yes --min-release-age=0 ${PACKAGE}@${ctx.kitVersion} check   # antes de npm ci`);
+    say('    - npm audit signatures   # después de npm ci');
+    say();
+    say(`  Con una imagen que traiga npm >= ${ctx.policy.minNpmVersion} (image: node:${image}).`);
+    if (!/^\s+ci:\s*(#.*)?$/m.test(pipeline)) {
+      say('  Para correrlo a mano ("Run pipeline"), un `custom: ci` con el mismo step (ver el README).');
+    }
+    if (!/condition:[\s\S]*BITBUCKET_PR_DESTINATION_BRANCH/.test(pipeline)) {
+      say(`  Y correrlo solo en los PR a las ramas que despliegan${branches.length ? ` (${branches.join(', ')})` : ''}, con la condition del step:`);
+      say();
+      say('    condition:');
+      say(`      state: ${prCondition(branches)}`);
+    }
   } else {
     say(`  ${pipeline === null ? 'No hay bitbucket-pipelines.yml. ' : ''}Agregar el kit en el step de test, ANTES de npm ci, y correrlo solo en los PR a ramas que despliegan:`);
     say();
-    for (const line of pipelineStep(ctx.kitVersion, node.image ?? '<versión LTS>').split('\n')) say(`    ${line}`);
+    for (const line of pipelineStep(ctx.kitVersion, image, branches).split('\n')) say(`    ${line}`);
   }
 
   // 4. Dockerfiles (no se editan)
@@ -245,7 +324,13 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   section('Pasos siguientes');
   const steps = [
     dryRun ? 'Correr init sin --dry-run.' : 'Revisar el diff: git diff .npmrc package.json',
-    'Aprobar o negar los install scripts pendientes.',
+    ...(node.from !== null && node.from !== undefined
+      ? [
+          `Pasar el repo de la ${node.from} a la ${node.major}: .nvmrc, imágenes del pipeline y FROM de los Dockerfiles (node:${node.image}). ` +
+            `En local, \`nvm install ${node.major} && nvm use ${node.major}\`; si npm ci da EUSAGE, \`npm install --package-lock-only --ignore-scripts\`.`,
+        ]
+      : []),
+    'Aprobar o negar los install scripts pendientes (después de `npm ci --ignore-scripts`; si el repo usa husky u otro `prepare`, correr `npm run prepare`).',
     'Agregar el step al pipeline y corregir los Dockerfiles.',
     `Correr el chequeo completo: npx --yes --min-release-age=0 ${PACKAGE}@${ctx.kitVersion} check`,
   ];

package/src/lib/audit.js

@@ -26,9 +26,22 @@ function parseReport(stdout) {
   return { problem: String(detail).split('\n')[0] };
 }
 
-// `--package-lock-only` hace que npm audite el lockfile aunque haya node_modules. Los `--include`
-// le ganan a un `omit` del entorno (por ejemplo NODE_ENV=production, que esconde las devDependencies).
-export async function runAudit(ctx, extraArgs, { attempts = 3 } = {}) {
+// Todo el árbol: los `--include` le ganan a un `omit` del entorno (por ejemplo NODE_ENV=production,
+// que esconde las devDependencies).
+export const FULL_TREE = ['--include=dev', '--include=optional', '--include=peer'];
+
+// `malware` y `vulnerabilities` piden el mismo reporte de todo el árbol: una sola llamada por corrida.
+const cache = new WeakMap();
+export function runAudit(ctx, extraArgs, options) {
+  if (!cache.has(ctx)) cache.set(ctx, new Map());
+  const byArgs = cache.get(ctx);
+  const key = extraArgs.join(' ');
+  if (!byArgs.has(key)) byArgs.set(key, auditWithRetries(ctx, extraArgs, options));
+  return byArgs.get(key);
+}
+
+// `--package-lock-only` hace que npm audite el lockfile aunque haya node_modules.
+async function auditWithRetries(ctx, extraArgs, { attempts = 3 } = {}) {
   const args = ['audit', '--json', '--package-lock-only', ...extraArgs];
   let problem;
   for (let attempt = 1; attempt <= attempts; attempt++) {

package/src/lib/node-calendar.js

@@ -6,9 +6,16 @@ import { compareVersions, parseVersion } from './semver.js';
 export const INDEX_URL = 'https://nodejs.org/dist/index.json';
 export const SCHEDULE_URL = 'https://raw.githubusercontent.com/nodejs/Release/main/schedule.json';
 
-export async function loadCalendar(ctx) {
-  const [index, schedule] = await Promise.all([ctx.fetchJson(INDEX_URL), ctx.fetchJson(SCHEDULE_URL)]);
-  return analyzeCalendar(index, schedule, ctx.today);
+// Una sola lectura por corrida: lo usan node-version, npm-policy e init.
+const cache = new WeakMap();
+export function loadCalendar(ctx) {
+  if (!cache.has(ctx)) {
+    cache.set(
+      ctx,
+      Promise.all([ctx.fetchJson(INDEX_URL), ctx.fetchJson(SCHEDULE_URL)]).then(([index, schedule]) => analyzeCalendar(index, schedule, ctx.today)),
+    );
+  }
+  return cache.get(ctx);
 }
 
 const day = (text) => new Date(`${text}T00:00:00Z`);
@@ -39,6 +46,7 @@ export function analyzeCalendar(index, schedule, today) {
   const newestLts = supported.length ? Math.max(...supported) : null;
 
   const ltsReleases = releases.filter((r) => r.lts);
+  const newestLtsOf = (major) => ltsReleases.find((r) => majorOf(r.version) === major);
   const newestLtsRelease = newestLts !== null ? ltsReleases.find((r) => majorOf(r.version) === newestLts) : undefined;
   const latestLtsRelease = ltsReleases[0];
   const recommendedRelease = newestLtsRelease ?? latestLtsRelease;
@@ -52,6 +60,12 @@ export function analyzeCalendar(index, schedule, today) {
     // La versión a instalar: la release LTS publicada de la LTS más nueva o, si todavía no salió,
     // la última release LTS publicada.
     recommended: recommendedRelease?.version.replace(/^v/, ''),
+    // La release LTS más nueva de la línea y el npm que trae (campo `npm` de index.json).
+    newestLtsOfLine: (major) => newestLtsOf(major)?.version.replace(/^v/, ''),
+    npmOfLine: (major) => newestLtsOf(major)?.npm ?? null,
+    // Las releases LTS de la línea, de la más nueva a la más vieja, y el npm que trae cada release.
+    ltsReleasesOfLine: (major) => ltsReleases.filter((r) => majorOf(r.version) === major).map((r) => r.version.replace(/^v/, '')),
+    npmOf: (version) => releases.find((r) => r.version.replace(/^v/, '') === version)?.npm ?? null,
     // true si la LTS más nueva todavía no tiene release LTS en index.json.
     newestLtsWithoutRelease: newestLts !== null && !newestLtsRelease,
     latestLtsMajor: latestLtsRelease ? majorOf(latestLtsRelease.version) : null,
@@ -71,3 +85,17 @@ export function analyzeCalendar(index, schedule, today) {
       [...lines.entries()].filter(([m, s]) => m > major && s.lts).map(([m]) => m).sort((a, b) => a - b)[0] ?? null,
   };
 }
+
+// Las líneas de Node con soporte cuya release LTS más nueva trae un npm que cumple la política, de la
+// más vieja a la más nueva, y las que no lo traen en ninguna release (index.json dice qué npm trae
+// cada release; la 22 trae npm 10).
+export function linesWithNpm(cal, minNpm) {
+  const supported = [...cal.lines.keys()]
+    .filter((m) => ['active', 'maintenance'].includes(cal.phaseOf(m)) && cal.newestLtsOfLine(m))
+    .sort((a, b) => a - b);
+  const meets = (m) => {
+    const npm = cal.npmOfLine(m);
+    return Boolean(npm && parseVersion(npm)) && compareVersions(npm, minNpm) >= 0;
+  };
+  return { ok: supported.filter(meets), without: supported.filter((m) => !meets(m)) };
+}

package/src/lib/node-target.js

@@ -0,0 +1,55 @@
+// A qué Node se manda a un repo que tiene que cambiar de línea (sin soporte, no LTS, o sin el npm que
+// pide la política): un solo destino para check, init y el mensaje de npm. Es la línea LTS con soporte
+// más baja que trae ese npm: el salto mínimo desde la línea en la que están casi todos los repos
+// (decisión del 28-10). La versión es la release LTS más nueva de esa línea que ya tiene imagen oficial
+// en Docker Hub: las imágenes salen días después que la release en nodejs.org.
+import { linesWithNpm } from './node-calendar.js';
+import { parseVersion } from './semver.js';
+
+export const TAGS_URL = 'https://hub.docker.com/v2/repositories/library/node/tags/';
+// Releases de la línea que se prueban, de la más nueva hacia atrás, antes de rendirse.
+const MAX_TRIES = 4;
+
+// ¿Existe la imagen `node:<tag>`? true, false o null si Docker Hub no responde. Una consulta por tag
+// y corrida, sin reintentos: si Hub está lento, el kit no espera.
+const cache = new WeakMap();
+export function imageExists(ctx, tag) {
+  if (!cache.has(ctx)) cache.set(ctx, new Map());
+  const byTag = cache.get(ctx);
+  if (!byTag.has(tag)) {
+    byTag.set(
+      tag,
+      ctx.fetchJson(`${TAGS_URL}${tag}`, { retries: 0, timeoutMs: 5000 }).then(
+        () => true,
+        (error) => (error?.status === 404 ? false : null),
+      ),
+    );
+  }
+  return byTag.get(tag);
+}
+
+// La release LTS más nueva de la línea con imagen publicada: `{ version, image, npm }`. Si Docker Hub
+// no responde, la más nueva con `image` = `<major>.<minor>` (ese tag existe desde la primera release
+// del minor). null si ninguna de las últimas tiene imagen.
+export async function newestWithImage(ctx, cal, major) {
+  const versions = cal.ltsReleasesOfLine(major).slice(0, MAX_TRIES);
+  for (const version of versions) {
+    const found = await imageExists(ctx, version);
+    if (found === true) return { version, image: version, npm: cal.npmOf(version) };
+    if (found === null) {
+      const [ma, mi] = parseVersion(versions[0]);
+      return { version: versions[0], image: `${ma}.${mi}`, npm: cal.npmOf(versions[0]) };
+    }
+  }
+  return null;
+}
+
+// El destino único: `{ major, version, image, npm }`.
+export async function upgradeTarget(ctx, cal) {
+  for (const major of linesWithNpm(cal, ctx.policy.minNpmVersion).ok) {
+    const found = await newestWithImage(ctx, cal, major);
+    if (found) return { major, ...found };
+  }
+  const rec = cal.recommended;
+  return rec ? { major: parseVersion(rec)[0], version: rec, image: rec, npm: cal.npmOf(rec) } : null;
+}