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

package/CHANGELOG.md

@@ -6,11 +6,27 @@ 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).
 
 ### BREAKING
 
@@ -41,7 +57,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.3`). 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,18 @@ 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.
+
 ## 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 +66,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.3 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 +77,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.3`): 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.3 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 +112,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.3 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.3 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 +135,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.3 check
 ```
 
 No se instala como devDependency ni usa husky: el `.npmrc` protege el `npm install` local y el pipeline es el
@@ -144,10 +160,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 +188,14 @@ 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.
+
+`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 +216,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.3",
   "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,11 @@
-// 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 { linesWithNpm, loadCalendar } from '../lib/node-calendar.js';
+import { compareVersions, isRange, minVersion, parseVersion } from '../lib/semver.js';
 
 export const id = 'node-version';
 export const title = 'Versión de Node';
@@ -167,6 +168,20 @@ 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 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}")` : '';
+    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 },
+    };
+  }
 
   const notes = [];
   // Mientras la LTS nueva no tiene su primera release LTS nadie puede migrar: se informa sin avisar.

package/src/checks/npm-policy.js

@@ -3,6 +3,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 { compareVersions, minVersion, parseVersion } from '../lib/semver.js';
 
 export const id = 'npm-policy';
@@ -10,6 +11,21 @@ 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) {
+  let cal;
+  try {
+    cal = await loadCalendar(ctx);
+  } catch {
+    return 'usar la imagen de Node LTS recomendada';
+  }
+  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}`;
+}
+
 export async function run(ctx) {
   const { policy } = ctx;
   const findings = [];
@@ -88,7 +104,7 @@ 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: `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\`.`,
       data: { npm: used },
     });
   }
@@ -99,7 +115,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 +123,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/init.js

@@ -10,7 +10,7 @@ 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 { parseNpmrc, requiredSettings, settingProblem } from './lib/npmrc.js';
 import { compareVersions, minVersion, parseVersion } from './lib/semver.js';
 import { formatBlocks } from './report.js';
@@ -77,28 +77,65 @@ 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.
+// 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 major = null;
-  let image = null;
+  let inUse = 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;
   }
-  return {
-    major: major ?? (recommended ? parseVersion(recommended)[0] : null),
-    image: image ?? recommended,
-  };
+  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 };
 }
 
-export function pipelineStep(kitVersion, nodeVersion) {
+// 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 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 +146,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
@@ -196,7 +233,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 +247,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 +261,34 @@ 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}, npm ${cal.npmOfLine(node.major)}). 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 (!/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)

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,9 @@ 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,
     // 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 +82,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)) };
+}