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

package/CHANGELOG.md

@@ -27,6 +27,17 @@ Sale primero como beta (`2.0.0-beta.N`), con el dist-tag `beta`.
     `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
 

package/README.md

@@ -3,7 +3,7 @@
 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.3`). Las publicadas, con sus dist-tags:
+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
@@ -44,9 +44,11 @@ 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 (Node 24 o más nueva: `node:24.22.1` trae npm 11.19.1). `check` da error en cada
-lugar que fija la 22 (`.nvmrc`, `engines.node`, `FROM`, `image:`) con la versión a la que subir, e `init` propone
-esa línea.
+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
 
@@ -66,7 +68,7 @@ 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-beta.3 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
           # … y lo que ya corría el step: build, lint, tests
@@ -86,13 +88,13 @@ pipelines:
 
 - **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-beta.3`): 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-beta.3 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
 
@@ -112,11 +114,11 @@ 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-beta.3 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-beta.3 init
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 init
 ```
 
 `init`:
@@ -135,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-beta.3 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
@@ -191,6 +193,9 @@ 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoptimalpartner/npm-security-kit",
-  "version": "2.0.0-beta.3",
+  "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/node-version.js

@@ -4,7 +4,8 @@
 // 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 { linesWithNpm, loadCalendar } from '../lib/node-calendar.js';
+import { loadCalendar } from '../lib/node-calendar.js';
+import { imageExists, newestWithImage, upgradeTarget } from '../lib/node-target.js';
 import { compareVersions, isRange, minVersion, parseVersion } from '../lib/semver.js';
 
 export const id = 'node-version';
@@ -146,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 } };
@@ -155,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);
@@ -172,13 +176,11 @@ function evaluate(pin, r, cal, policy) {
   // 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 target = linesWithNpm(cal, policy.minNpmVersion).ok.find((m) => m > r.major);
-    const to = target ? `${cal.newestLtsOfLine(target)} (npm ${cal.npmOfLine(target)})` : rec;
-    const hint = pin.kind === 'engines' && target ? ` (en engines: ">=${target}")` : '';
+    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${hint}.`,
+      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 },
     };
   }
@@ -191,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.`);
     }
@@ -202,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) {
@@ -224,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();
@@ -232,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

@@ -4,6 +4,7 @@ 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';
@@ -11,19 +12,30 @@ export const title = 'npm y .npmrc';
 
 const NPM10_WHY = 'npm 10 ignora min-release-age sin avisar y no aplica allowScripts';
 
-// Qué imagen usar para tener ese npm. Sin calendario, el consejo genérico.
-async function npmImageHint(ctx, minNpm) {
+// 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 'usar la imagen de Node LTS recomendada';
+    return generic;
   }
-  const { ok, without } = linesWithNpm(cal, minNpm);
-  if (!ok.length) return 'usar la imagen de Node LTS recomendada';
-  const first = ok[0];
-  const none = without.length ? `; ninguna release de Node ${without.join(' ni ')} trae npm ${parseVersion(minNpm)[0]}` : '';
-  return `usar una imagen de Node que lo traiga: node:${cal.newestLtsOfLine(first)} (npm ${cal.npmOfLine(first)}) o más nueva${none}`;
+  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) {
@@ -104,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 y en el Dockerfile, ${await npmImageHint(ctx, minNpm)}. 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 },
     });
   }

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

@@ -11,6 +11,7 @@ import { loadAllowPolicy, verdict } from './lib/allow-scripts.js';
 import { lockfileName } from './lib/audit.js';
 import { unifiedDiff } from './lib/diff.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';
@@ -80,21 +81,35 @@ export function mergePackageJson(text, policy, nodeMajor) {
 // 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 línea 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) y la imagen es la release LTS más
-// nueva de la línea (sin parches de seguridad pendientes). Sin Node fijado, la release recomendada.
-export function repoNode(ctx, cal) {
-  const recommended = cal.recommended ?? null;
+// 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 (inUse === null || r.major < inUse) inUse = r.major;
+    if (!pipelinePin && pin.file === 'bitbucket-pipelines.yml' && pin.kind === 'docker' && r.exact) pipelinePin = r;
   }
-  const major = inUse === null ? null : (linesWithNpm(cal, ctx.policy.minNpmVersion).ok.find((m) => m >= inUse) ?? null);
-  if (major === null) return { major: recommended ? parseVersion(recommended)[0] : null, image: recommended, from: null };
-  return { major, image: cal.newestLtsOfLine(major), from: major !== inUse ? inUse : null };
+  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.
@@ -205,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}`));
 
@@ -265,7 +280,7 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   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}, npm ${cal.npmOfLine(node.major)}). Pasar a la ${node.major} el .nvmrc, las imágenes del pipeline y los FROM de los Dockerfiles.`,
+        `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);
@@ -279,6 +294,9 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
     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();
@@ -306,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/node-calendar.js

@@ -63,6 +63,9 @@ export function analyzeCalendar(index, schedule, today) {
     // 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,

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;
+}