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

package/CHANGELOG.md

@@ -27,6 +27,28 @@ 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`.
+- **2.0.0-beta.5** (ajustes de una tercera prueba):
+  - `init` guía el cambio de línea también desde una línea sin soporte o no LTS (antes solo desde una sin npm 11), y
+    sube `engines.node` si admite una línea que hay que cambiar.
+  - `init` señala el `npm ci` del step que corre en los PR (inline o por su ancla) y aparte los de deploy y
+    publicación, que no necesitan el kit. No repite la imagen si el pipeline ya usa la que propone.
+  - `dockerfile`: en un monorepo, un Dockerfile cuyo contexto de build es una subcarpeta sin `.npmrc` instala sin la
+    política aunque la raíz lo tenga; ahora es error.
+  - Excepción con fecha para diferir el cambio de línea de Node cuando el salto es de más de 2 versiones mayores
+    (`npmSecurityKit.nodeUpgradeDeferredUntil` y `nodeUpgradeReason` en el `package.json`, hasta 183 días): mientras
+    está vigente, los errores de la línea de Node y de npm 10 son avisos e `init` no toca `engines`. El kit la sugiere
+    cuando el salto es grande.
 
 ### 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.5`). Las publicadas, con sus dist-tags:
 `npm view @theoptimalpartner/npm-security-kit dist-tags`.
 
 ## Qué revisa
@@ -12,7 +12,7 @@ Los ejemplos usan la versión de este paquete (`2.0.0-beta.3`). Las publicadas,
 |---|---|---|---|
 | `malware` | `npm audit` sobre **todo** el lockfile, incluidas las devDependencies | Cualquier advisory de malware (CWE-506), con cualquier severidad | — |
 | `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 |
+| `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); con un salto de más de 2 versiones, diferible con una excepción con fecha | 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 |
@@ -44,9 +44,12 @@ 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. Si el salto
+es grande (18 o 20 → 24), ver **Diferir el cambio de Node** en las recetas.
 
 ## Uso
 
@@ -66,7 +69,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.5 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 +89,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.5`): 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.5 check --json > npm-security-kit.json`.
 
 ### Dockerfile
 
@@ -107,24 +110,28 @@ RUN npm ci
 
 Si el `.dockerignore` excluye el `.npmrc` (por ejemplo con `.*`), agregar `!.npmrc` al final.
 
+En un monorepo, si el Dockerfile se construye con una subcarpeta como contexto (`cd backend && docker build .`), el
+`.npmrc` de la raíz no llega a la imagen: copiarlo a esa carpeta o construir con el contexto en la raíz. `check` lo
+marca como error.
+
 ### Adoptarlo en un repo: `init`
 
 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.5 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.5 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` (con la línea de Node del repo, si trae npm 11;
-  si no, la siguiente que lo trae);
+- completa `engines.npm` (`>=11.17`) y `engines.node`: lo agrega si falta, con la línea de Node del repo si trae npm
+  11, y lo sube si admite una línea que hay que cambiar (sin soporte, no LTS o sin npm 11), a la línea propuesta;
 - **no aprueba install scripts**: lista los pendientes y los comandos para revisarlos;
 - **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;
@@ -135,7 +142,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.5 check
 ```
 
 No se instala como devDependency ni usa husky: el `.npmrc` protege el `npm install` local y el pipeline es el
@@ -191,6 +198,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`
@@ -216,6 +226,51 @@ 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`.
 
+### Diferir el cambio de Node (salto grande)
+
+Pasar de Node 18 o 20 a la 24 suele arrastrar dependencias y refactors. Para no frenar el repo mientras se planifica,
+el cambio de línea se puede diferir con una excepción con fecha.
+
+**Cuándo se puede usar**
+
+- Solo si el salto de la línea del repo al destino (hoy la 24) es de **más de 2 versiones mayores**: 18 → 24 o
+  20 → 24 sí; 22 → 24 no (ese cambio es chico y no se difiere). `check` lo sugiere ("Salto grande (Node 18 → 24)…")
+  cuando aplica.
+- Cuando subir ahora no es viable (dependencias que no soportan la línea nueva, un refactor que hay que planificar), y
+  con el OK de quien aprueba los cambios de seguridad del repo. No es para "lo veo después".
+
+**Cómo**
+
+En la raíz del `package.json` (al lado de `dependencies`), en un PR:
+
+```json
+"npmSecurityKit": {
+  "nodeUpgradeDeferredUntil": "2027-03-31",
+  "nodeUpgradeReason": "Express 4 → 5 y los tipos de Node 24"
+}
+```
+
+- `nodeUpgradeDeferredUntil`: fecha `AAAA-MM-DD`, como mucho 183 días desde hoy.
+- `nodeUpgradeReason`: por qué no se puede subir ahora. Es obligatorio.
+- En la descripción del PR: el motivo, quién lo aprobó y el plan para subir antes de la fecha (tarjeta o PR).
+
+**Qué cambia mientras está vigente**
+
+- Los errores de la línea de Node y los de npm 10 (`npm` en uso, `engines.npm`) pasan a aviso, con la fecha y el motivo;
+  `check` dice cuántos días quedan. `init` no toca `engines`: los de la línea nueva, con `engine-strict`, romperían el
+  `npm ci` de la actual.
+- Lo demás sigue bloqueando: malware, vulnerabilidades críticas en producción, install scripts sin aprobar, `.npmrc`
+  y Dockerfiles.
+- **Ojo:** con npm 10 (la 18 no corre npm 11), `min-release-age` y `allowScripts` no hacen nada aunque estén en el
+  `.npmrc`. El repo queda sin la espera de 7 días ni el control de install scripts: el kit sigue revisando malware y
+  vulnerabilidades antes de `npm ci`, pero no reemplaza eso. Por eso la excepción vence.
+
+**Al vencer**
+
+- Los errores vuelven a bloquear el pipeline y `check` pide quitarla o renovarla.
+- Renovarla es otro PR con fecha nueva (como mucho 183 días desde ese día), motivo y OK. Si la fecha es inválida,
+  falta el motivo o pasa de 183 días, el kit la ignora y lo avisa.
+
 ### 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

package/package.json

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

@@ -138,6 +138,10 @@ export async function run(ctx) {
     const own = dirOf(file);
     const context = own && (ctx.exists(join(own, '.dockerignore')) || ctx.exists(join(own, 'package.json'))) ? own : '';
     const hasNpmrc = ctx.exists(join(context, '.npmrc'));
+    // Monorepo: el contexto es una subcarpeta sin .npmrc y la política está en el de la raíz, que
+    // `docker build` no ve desde ahí.
+    const npmrcOutside = Boolean(context) && !hasNpmrc && ctx.exists('.npmrc');
+    let reportedOutside = false;
     const ignoreFile = ctx.exists(`${file}.dockerignore`) ? `${file}.dockerignore` : join(context, '.dockerignore');
     const ignoreText = ctx.readFile(ignoreFile);
     const npmrcIgnored = hasNpmrc ? dockerignoreExcludes(ignoreText, '.npmrc') : null;
@@ -171,6 +175,15 @@ export async function run(ctx) {
         const local = npmInstalls(ins.args).filter((n) => !n.global);
         if (!local.length) continue;
         installs = true;
+        if (npmrcOutside && !mountsNpmrc(ins.args) && !reportedOutside) {
+          reportedOutside = true;
+          findings.push({
+            level: 'error',
+            file,
+            line: ins.line,
+            message: `Instala sin el .npmrc: el contexto de build es ${context}/ (tiene su propio package.json o .dockerignore) y ahí no hay .npmrc; el de la raíz no llega a la imagen. Copiar el .npmrc a ${context}/ y agregarlo al COPY, o construir con el contexto en la raíz.`,
+          });
+        }
         if (hasNpmrc && !brought && !mountsNpmrc(ins.args) && !reported) {
           reported = true;
           findings.push({

package/src/checks/node-version.js

@@ -4,7 +4,9 @@
 // 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 { readDeferral } from '../lib/node-deferral.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 +148,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,31 +160,29 @@ 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);
   if (phase === 'eol') {
-    return { ...base, level: 'error', message: `${prefix}: sin soporte desde ${sch.end}. Actualizar a ${rec}${engineHint}.`, data };
+    return { ...base, level: 'error', message: `${prefix}: sin soporte desde ${sch.end}. Actualizar a ${rec}${engineHint}.`, data: { ...data, lineChange: true } };
   }
   if (phase === 'not-lts') {
     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 };
+    return { ...base, level: 'error', message: `${prefix}: no es LTS, ${why}. Usar ${rec}${engineHint}.`, data: { ...data, lineChange: true } };
   }
   // 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 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}.`,
-      data: { ...data, npm: lineNpm },
+      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, lineChange: true },
     };
   }
 
@@ -191,6 +194,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 +207,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) {
@@ -215,6 +224,40 @@ function evaluate(pin, r, cal, policy) {
   return { ...base, level, message: `${prefix}: ${detail}`, data: { ...data, group: `v${r.major}: ${detail}` } };
 }
 
+// ¿Hay una excepción vigente que aplique a este repo? Aplica si alguna línea fijada que hay que cambiar
+// (sin soporte, no LTS o sin npm 11) está a más de policy.nodeDeferMinJump versiones mayores del destino.
+// La usan npm-policy (npm 10 y engines.npm) e init. Una vez por corrida.
+const deferrals = new WeakMap();
+export function activeDeferral(ctx) {
+  if (!deferrals.has(ctx)) deferrals.set(ctx, computeDeferral(ctx).catch(() => null));
+  return deferrals.get(ctx);
+}
+
+async function computeDeferral(ctx) {
+  const deferral = readDeferral(ctx);
+  if (deferral.status !== 'active') return null;
+  const cal = await loadCalendar(ctx);
+  const target = await upgradeTarget(ctx, cal);
+  if (!target) return null;
+  const majors = bigJumpLines(ctx, cal, target);
+  return majors.length ? { ...deferral, majors, target } : null;
+}
+
+// Las líneas fijadas que hay que cambiar y están a más de nodeDeferMinJump versiones del destino.
+function bigJumpLines(ctx, cal, target) {
+  const out = new Set();
+  for (const pin of findPins(ctx)) {
+    const r = resolvePin(pin, cal);
+    if (r.major === undefined || r.major === null || r.otherImage) continue;
+    if (target.major - r.major <= ctx.policy.nodeDeferMinJump) continue;
+    const phase = cal.phaseOf(r.major);
+    const npm = cal.npmOfLine(r.major);
+    const noNpm = npm && parseVersion(npm) && compareVersions(npm, ctx.policy.minNpmVersion) < 0;
+    if (phase === 'eol' || phase === 'not-lts' || noNpm) out.add(r.major);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
 export async function run(ctx) {
   let cal;
   try {
@@ -224,21 +267,72 @@ 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();
+  const deferral = readDeferral(ctx);
+  const max = ctx.policy.nodeDeferMaxDays;
+  const big = target ? new Set(bigJumpLines(ctx, cal, target)) : new Set();
+  const deferring = deferral.status === 'active' && big.size > 0;
   let nodePins = 0;
   for (const pin of pins) {
     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));
+    const finding = await evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage });
+    // Con la excepción vigente, el cambio de una línea con salto grande pasa a aviso.
+    if (deferring && finding.level === 'error' && finding.data?.lineChange && big.has(r.major)) {
+      findings.push({
+        ...finding,
+        level: 'warn',
+        message: `${finding.message} Diferido hasta ${deferral.until} (${deferral.reason}).`,
+        data: { ...finding.data, deferredUntil: deferral.until },
+      });
+    } else {
+      findings.push(finding);
+    }
+  }
+  // El estado de la excepción, o la sugerencia de declararla cuando el salto es grande.
+  const deferralAt = { file: 'package.json', line: deferral.line };
+  const lines = [...big].map((m) => `Node ${m}`).join(' y ');
+  if (deferral.status === 'invalid') {
+    findings.push({ ...deferralAt, level: 'warn', message: `La excepción para diferir el cambio de Node no vale: ${deferral.problem}. Se ignora.` });
+  } else if (deferral.status === 'expired') {
+    findings.push({
+      ...deferralAt,
+      level: 'warn',
+      message: `La excepción para diferir el cambio de Node venció el ${deferral.until}: los errores vuelven a bloquear. Quitarla del package.json, o renovarla con otra fecha y motivo (máximo ${max} días).`,
+    });
+  } else if (deferral.status === 'active' && !deferring) {
+    findings.push({
+      ...deferralAt,
+      level: 'warn',
+      message: `La excepción para diferir el cambio de Node no hace falta: ninguna línea fijada está a más de ${ctx.policy.nodeDeferMinJump} versiones mayores del destino. Quitarla del package.json.`,
+    });
+  } else if (deferring) {
+    findings.push({
+      ...deferralAt,
+      level: 'warn',
+      message: `Cambio de línea de Node diferido hasta ${deferral.until} (${deferral.reason}): quedan ${deferral.daysLeft} días. Mientras tanto, los errores de ${lines} y de npm 10 son avisos; al vencer, vuelven a bloquear. Destino: ${target.version}.`,
+      data: { deferredUntil: deferral.until, majors: [...big] },
+    });
+  } else if (big.size && findings.some((f) => f.level === 'error' && f.data?.lineChange && big.has(f.data.major))) {
+    findings.push({
+      level: 'info',
+      message:
+        `Salto grande (${lines} → ${target.major}): si no se puede subir ahora, se puede diferir con una excepción con fecha en el package.json, ` +
+        `"npmSecurityKit": { "nodeUpgradeDeferredUntil": "AAAA-MM-DD", "nodeUpgradeReason": "…" } (máximo ${max} días). Mientras esté vigente, estos errores son avisos.`,
+    });
   }
   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,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 { activeDeferral } from './node-version.js';
 import { compareVersions, minVersion, parseVersion } from '../lib/semver.js';
 
 export const id = 'npm-policy';
@@ -11,19 +13,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) {
@@ -73,6 +86,12 @@ export async function run(ctx) {
 
   // engines.npm
   const pkgText = ctx.readFile('package.json');
+  // Con el cambio de Node diferido (salto grande), la línea del repo puede no correr npm 11: engines.npm
+  // y el npm en uso son avisos hasta que venza la excepción. engines.npm >=11.17 con engine-strict
+  // rompería el npm ci de esa línea.
+  const deferral = await activeDeferral(ctx);
+  const deferredNote = deferral ? ` Diferido hasta ${deferral.until} junto con el cambio de Node (${deferral.reason}).` : '';
+  const npmLevel = deferral ? 'warn' : 'error';
   if (pkgText === null) {
     findings.push({ level: 'error', message: 'No hay package.json en el directorio revisado.' });
   } else {
@@ -81,16 +100,16 @@ export async function run(ctx) {
     const min = typeof range === 'string' ? minVersion(range) : null;
     if (typeof range !== 'string') {
       findings.push({
-        level: 'error',
+        level: npmLevel,
         file: 'package.json',
-        message: `Falta engines.npm: agregar "npm": ">=${minNpmShort}" en engines (${NPM10_WHY}).`,
+        message: `Falta engines.npm: agregar "npm": ">=${minNpmShort}" en engines (${NPM10_WHY}).${deferral ? ` Agregarlo al subir de Node: con engine-strict, en la línea actual rompe npm ci.${deferredNote}` : ''}`,
       });
     } else if (!min || compareVersions(min, minNpm) < 0) {
       findings.push({
-        level: 'error',
+        level: npmLevel,
         file: 'package.json',
         line: jsonKeyLine(pkgText, ['engines', 'npm']),
-        message: `engines.npm "${range}" admite npm anteriores a ${minNpm} (${NPM10_WHY}). Cambiar a ">=${minNpmShort}".`,
+        message: `engines.npm "${range}" admite npm anteriores a ${minNpm} (${NPM10_WHY}). Cambiar a ">=${minNpmShort}".${deferredNote}`,
         data: { range, min },
       });
     }
@@ -103,8 +122,10 @@ export async function run(ctx) {
     findings.push({ level: 'warn', message: `No se pudo saber la versión de npm en uso (${(npmVersion.stderr || npmVersion.stdout).trim() || 'sin salida'}).` });
   } 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\`.`,
+      level: npmLevel,
+      message: (({ pipeline, local }) => `npm ${used} en uso: hace falta npm >= ${minNpm} (${NPM10_WHY}). En el pipeline y en el Dockerfile, ${pipeline}. En local, ${local}.${deferredNote}`)(
+        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

@@ -6,11 +6,13 @@ import { join } from 'node:path';
 import * as dockerfileCheck from './checks/dockerfile.js';
 import { OVERRIDE_ENV, packagesWithScripts } from './checks/install-scripts.js';
 import * as nodeVersionCheck from './checks/node-version.js';
+import { activeDeferral } from './checks/node-version.js';
 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 { 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';
@@ -54,9 +56,10 @@ function jsonFormat(text) {
   };
 }
 
-// engines.npm (si falta o admite un npm viejo) y engines.node (solo si falta), conservando la
-// indentación y el salto de línea final del archivo.
-export function mergePackageJson(text, policy, nodeMajor) {
+// engines.npm (si falta o admite un npm viejo) y engines.node (si falta, o con `raiseNode` si admite
+// una línea que hay que cambiar: sin soporte, no LTS o sin npm 11), conservando la indentación y el
+// salto de línea final del archivo.
+export function mergePackageJson(text, policy, nodeMajor, { raiseNode = false } = {}) {
   const pkg = JSON.parse(text);
   const changes = [];
   const minNpm = policy.minNpmVersion.replace(/\.0$/, '');
@@ -66,9 +69,10 @@ export function mergePackageJson(text, policy, nodeMajor) {
     changes.push(`engines.npm: ">=${minNpm}"${engines.npm ? ` (antes: "${engines.npm}")` : ''}`);
     engines.npm = `>=${minNpm}`;
   }
-  if (engines.node === undefined && nodeMajor) {
+  if (nodeMajor && (engines.node === undefined || raiseNode)) {
+    const before = engines.node;
     engines.node = `>=${nodeMajor}`;
-    changes.push(`engines.node: ">=${nodeMajor}"`);
+    changes.push(`engines.node: ">=${nodeMajor}"${before ? ` (antes: "${before}")` : ''}`);
   }
   if (!changes.length) return { text, changes };
   pkg.engines = engines;
@@ -80,21 +84,76 @@ 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;
-  let inUse = 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);
+  const { ok } = linesWithNpm(cal, ctx.policy.minNpmVersion);
+  let inUse = null; // la línea más baja en uso que cumple (LTS con soporte y npm 11)
+  let from = null; // la línea más baja en uso que hay que cambiar, y por qué
+  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 (ok.includes(r.major)) {
+      if (inUse === null || r.major < inUse) inUse = r.major;
+      if (!pipelinePin && pin.file === 'bitbucket-pipelines.yml' && pin.kind === 'docker' && r.exact) pipelinePin = r;
+    } else if (from === null || r.major < from.major) {
+      from = { major: r.major, why: lineProblem(cal, r.major, ctx.policy) };
+    }
+  }
+  if (!target) return { major: null, image: null, npm: null, from };
+  const major = inUse ?? target.major;
+  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 };
   }
-  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 (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 };
+}
+
+// Por qué una línea de Node no sirve, para el mensaje de init.
+function lineProblem(cal, major, policy) {
+  const phase = cal.phaseOf(major);
+  if (phase === 'eol') return `sin soporte desde ${cal.lines.get(major).end}`;
+  if (phase === 'not-lts') return 'que no es LTS';
+  if (phase === 'unknown') return 'que no aparece en el calendario de Node';
+  return `pero ninguna release de la ${major} trae npm >= ${policy.minNpmVersion}, que pide la política`;
+}
+
+// Las líneas `- npm ci` del pipeline: las del step que corre en los PR (inline o por ancla) y el resto
+// (deploys, publicación). El kit va en el de los PR. Sin sección pull-requests, todas cuentan como PR.
+export function npmCiLines(text) {
+  const lines = (text ?? '').split(/\r?\n/);
+  const indent = (l) => l.match(/^ */)[0].length;
+  const isCi = (l) => /^\s*-\s*npm ci(\s|$)/.test(l);
+  const all = lines.flatMap((l, i) => (isCi(l) ? [i + 1] : []));
+  const blockAfter = (start) => {
+    const out = [];
+    for (let i = start + 1; i < lines.length; i++) {
+      if (!lines[i].trim() || lines[i].trim().startsWith('#')) continue;
+      if (indent(lines[i]) <= indent(lines[start])) break;
+      out.push(i);
+    }
+    return out;
+  };
+  const prStart = lines.findIndex((l) => /^\s+pull-requests:\s*(#.*)?$/.test(l));
+  if (prStart < 0) return { pr: all, others: [] };
+  const prBlock = blockAfter(prStart);
+  const pr = new Set(prBlock.filter((i) => isCi(lines[i])).map((i) => i + 1));
+  for (const anchor of new Set(prBlock.flatMap((i) => [...lines[i].matchAll(/\*([\w-]+)/g)].map((m) => m[1])))) {
+    const def = lines.findIndex((l) => new RegExp(`&${anchor}(\\s|$)`).test(l));
+    if (def >= 0) for (const i of blockAfter(def)) if (isCi(lines[i])) pr.add(i + 1);
+  }
+  if (!pr.size) return { pr: all, others: [] };
+  return { pr: [...pr].sort((a, b) => a - b), others: all.filter((n) => !pr.has(n)) };
 }
 
 // Las ramas que despliegan: las claves de `pipelines.branches` (sin globs), en orden.
@@ -205,14 +264,20 @@ 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}`));
 
   // 1. .npmrc y package.json
   const npmrcBefore = ctx.readFile('.npmrc');
   const npmrc = mergeNpmrc(npmrcBefore, ctx.policy);
-  const pkg = mergePackageJson(pkgText, ctx.policy, node.major);
+  // Con el cambio de Node diferido (salto grande, excepción vigente), engines no se toca: los de la línea
+  // nueva, con engine-strict, romperían el npm ci de la actual.
+  const deferral = cal.error ? null : await activeDeferral(ctx);
+  const engNode = JSON.parse(pkgText).engines?.node;
+  const engMin = typeof engNode === 'string' ? minVersion(engNode) : null;
+  const raiseNode = Boolean(engMin && !cal.error && node.major && !linesWithNpm(cal, ctx.policy.minNpmVersion).ok.includes(parseVersion(engMin)[0]));
+  const pkg = deferral ? { text: pkgText, changes: [] } : mergePackageJson(pkgText, ctx.policy, node.major, { raiseNode });
   if (npmrc.changes.length) files['.npmrc'] = npmrc.text;
   if (pkg.changes.length) files['package.json'] = pkg.text;
 
@@ -262,23 +327,38 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   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) {
+  const bigJump = node.from && node.major - node.from.major > ctx.policy.nodeDeferMinJump;
+  if (deferral) {
+    say(
+      `  Cambio de Node diferido hasta ${deferral.until} (${deferral.reason}): el step sigue con la imagen actual y engines no se toca. ` +
+        `Al vencer, pasar a la ${node.major} (node:${image}).`,
+    );
+  } else if (node.from) {
     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.`,
+      `  El repo usa Node ${node.from.major}, ${node.from.why}: ` +
+        `se propone la ${node.major} (node:${image}${node.npm ? `, npm ${node.npm}` : ''}). Pasar a la ${node.major} el .nvmrc, las imágenes del pipeline, los FROM de los Dockerfiles y engines.node.` +
+        (bigJump ? ' Si el salto no se puede hacer ahora, se puede diferir con una excepción con fecha (README: "Diferir el cambio de Node").' : ''),
     );
   }
   const branches = deployBranches(pipeline);
-  const ciLines = (pipeline ?? '').split(/\r?\n/).flatMap((l, i) => (/^\s*-\s*npm ci(\s|$)/.test(l) ? [i + 1] : []));
+  const ci = npmCiLines(pipeline);
   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:`);
+  } else if (ci.pr.length) {
+    say(`  Agregar al step que corre en los PR (bitbucket-pipelines.yml:${ci.pr.join(', ')}), antes de su npm ci, 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 (ci.others.length) {
+      say(`  Los otros npm ci (líneas ${ci.others.join(', ')}: deploys, publicación) no necesitan el kit: ya pasó en el PR.`);
+    }
+    if (!deferral && !new RegExp(`node:${image.replace(/\./g, '\\.')}(\\s|$|-)`).test(pipeline)) {
+      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 +386,15 @@ 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.',
+    ...(deferral
+      ? [`Antes del ${deferral.until}, cuando vence la excepción: pasar de la ${node.from?.major ?? deferral.majors[0]} a la ${node.major} (.nvmrc, imágenes, FROM, engines.node y engines.npm).`]
+      : node.from
+      ? [
+          `Pasar el repo de la ${node.from.major} 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-deferral.js

@@ -0,0 +1,39 @@
+// Excepción para diferir el cambio de línea de Node cuando el salto es grande (decisión del 28-10):
+// subir varias versiones mayores suele arrastrar dependencias y refactors. Se declara en el
+// package.json, así queda en el diff del PR, y vence:
+//
+//   "npmSecurityKit": { "nodeUpgradeDeferredUntil": "AAAA-MM-DD", "nodeUpgradeReason": "por qué" }
+//
+// Vale por hasta policy.nodeDeferMaxDays desde hoy y solo para las líneas cuyo salto al destino es de
+// más de policy.nodeDeferMinJump versiones mayores (eso lo decide quien la usa).
+import { parseDay } from '../context.js';
+import { jsonKeyLine } from './json-lines.js';
+
+const DAY = 86400000;
+const iso = (date) => date.toISOString().slice(0, 10);
+
+// `{ status: 'none' | 'invalid' | 'expired' | 'active', until?, reason?, line?, daysLeft?, problem? }`.
+export function readDeferral(ctx) {
+  const text = ctx.readFile('package.json');
+  let pkg;
+  try {
+    pkg = JSON.parse(text ?? 'null');
+  } catch {
+    return { status: 'none' };
+  }
+  const config = pkg?.npmSecurityKit;
+  if (!config || config.nodeUpgradeDeferredUntil === undefined) return { status: 'none' };
+  const until = config.nodeUpgradeDeferredUntil;
+  const line = jsonKeyLine(text, ['npmSecurityKit', 'nodeUpgradeDeferredUntil']);
+  const reason = typeof config.nodeUpgradeReason === 'string' ? config.nodeUpgradeReason.trim() : '';
+  const date = typeof until === 'string' ? parseDay(until) : null;
+  if (!date) return { status: 'invalid', until, line, problem: 'la fecha tiene que ser "AAAA-MM-DD"' };
+  if (!reason) return { status: 'invalid', until, line, problem: 'falta "nodeUpgradeReason" (por qué no se puede subir ahora)' };
+  const daysLeft = Math.round((date - ctx.today) / DAY);
+  const max = ctx.policy.nodeDeferMaxDays;
+  if (daysLeft > max) {
+    return { status: 'invalid', until, reason, line, problem: `pasa del máximo de ${max} días (como mucho hasta ${iso(new Date(ctx.today.getTime() + max * DAY))})` };
+  }
+  if (daysLeft < 0) return { status: 'expired', until, reason, line };
+  return { status: 'active', until, reason, line, daysLeft };
+}

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

package/src/policy.js

@@ -27,6 +27,10 @@ export const policy = freeze({
   allowedRegistries: ['https://registry.npmjs.org/'],
   // Días de soporte restantes de una línea de Node por debajo de los cuales se avisa.
   nodeEolWarnDays: 180,
+  // El cambio de línea de Node se puede diferir con una excepción con fecha en el package.json solo si
+  // el salto al destino es de más de estas versiones mayores, y por hasta estos días.
+  nodeDeferMinJump: 2,
+  nodeDeferMaxDays: 183,
   // Claves del .npmrc del proyecto. `error`: sin ellas la política no se cumple.
   // `warn`: recomendadas.
   requiredNpmrc: {