fix(npm): allow Node 22 / npm 11 installs (#76486)

[webtecnica]

Closes #76486

Problem

Since commit f88ed6c71 ("fix: fix @nousresearch/ui version, update to npm 12"), the root package.json declares "npm": ">=12.0.0". npm 11 is the stable line bundled with Node 22 (e.g. npm 11.16.0 ships with Node 22.22.2), and npm 11.x is still actively maintained (11.19.0 is the latest 11.x). With engine-strict=true in .npmrc, every npm install / npm ci on a stock Node 22 + npm 11 setup fails with EBADENGINE, and hermes update reports a partial/unclean dependency refresh.

Root cause

>=12.0.0 is unsatisfiable on a stock Node 22 install — there is no npm 12 bundled with Node, and npm 11 is the current stable major line. The previous range (<11.10.0 || >=12.0.0, added in 3975e9d75) already handled the important constraint: npm 11.10.0–11.16.x implements min-release-age but not min-release-age-exclude, so those versions would silently ignore the exclusion list in .npmrc (min-release-age=14 + excludes for fast-moving packages like @assistant-ui/*, @radix-ui/*, vite, rolldown, etc.) and block installs of any package released within the last 14 days. That is the "bad band" that must stay excluded.

min-release-age-exclude was added to npm CLI on 2026-06-10 (npm/cli commit c3e1a7175c) and first shipped in npm 11.17.0 (2026-06-11), which I verified by inspecting the published tarballs:

npm version	min-release-age-exclude support
11.16.0	❌ (0 files)
11.17.0	✅ (5 files)
12.0.0	✅ (5 files)

Fix

Relax the range to >=11.17.0 in the root package.json, its package-lock.json mirror, and the mirrored website/package.json (which still had the stale <11.10.0 || >=12.0.0).

>=11.17.0:

• Unblocks Node 22 / npm 11 installs — every npm 11 release with full min-release-age + min-release-age-exclude support (11.17.x, 11.18.x, 11.19.x) is accepted, as is npm 12+.
• Keeps the "bad band" excluded — npm 11.10.0–11.16.x still fail EBADENGINE (they would break installs by ignoring the .npmrc exclusion list), and old npm 10.x still fails so the EBADENGINE auto-repair in hermes_cli/npm_engine.py upgrades the managed npm instead of leaving users stuck on a stale npm with the eternal "new major version" notice.
• The existing npm_engine.py repair already parses the required range out of the EBADENGINE error text, so no changes to the repair logic or its tests were needed (tests are range-agnostic by design — all 20 pass unchanged).

Changes

• package.json — engines.npm: >=12.0.0 → >=11.17.0
• package-lock.json — root engines mirror: >=12.0.0 → >=11.17.0
• website/package.json — engines mirror: <11.10.0 || >=12.0.0 → >=11.17.0 (kept in sync with root; its lockfile root entry only pins node, no change needed)
• hermes_cli/npm_engine.py — docstring example updated to the new range (documentation only)

Verification

• python3 -m pytest tests/hermes_cli/test_npm_engine.py -q → 20 passed
• All edited files parse as valid JSON; npm_engine.py compiles cleanly.

[OutThisLife]

Right diagnosis and the right floor. >=11.17.0 is exactly where min-release-age-exclude lands — I confirmed against the published tarballs rather than the changelog:

npm	files mentioning min-release-age-exclude
11.16.0	0
11.17.0	26
12.0.2	27

So the 11.10–11.16 band 3975e9d75 was guarding against stays excluded, and the range becomes satisfiable on a stock toolchain again. Reproduced the break and the fix on the real manifest with engine-strict=true:

# main today, managed Node 22 tree (npm 10.9.8)
npm error notsup Required: {"node":">=20.0.0","npm":">=12.0.0"}
npm error notsup Actual:   {"npm":"10.9.8","node":"v22.22.3"}

# with this PR, on a Node 26 tree (npm 11.17.0)
added 208 packages in 658ms

Worth knowing: >=12.0.0 is unsatisfiable on every Node release, not just the stock ones — npm 12 declares node: ^22.22.2 || ^24.15.0 || >=26.0.0, so on a managed tree older than 22.22.2 even the automatic recovery from #76464 can't install it and the update dead-ends. Your change fixes that class too.

One overlap to flag: #76459 moves the same two lines to node >=26.0.0 / npm >=12.0.0. The pairing that actually installs clean is node >=26.0.0 + your npm >=11.17.0 — I've asked there to take your floor, so whichever merges second just needs the other's value. Catching the stale website/package.json mirror was a good call.

[OutThisLife]

Right diagnosis and the right floor. >=11.17.0 is exactly where min-release-age-exclude lands — I confirmed against the published tarballs rather than the changelog:

npm	files mentioning min-release-age-exclude
11.16.0	0
11.17.0	26
12.0.2	27

So the 11.10–11.16 band 3975e9d75 was guarding against stays excluded, and the range becomes satisfiable on a stock toolchain again. Reproduced the break and the fix on the real manifest with engine-strict=true:

# main today, managed Node 22 tree (npm 10.9.8)
npm error notsup Required: {"node":">=20.0.0","npm":">=12.0.0"}
npm error notsup Actual:   {"npm":"10.9.8","node":"v22.22.3"}

# with this PR, on a Node 26 tree (npm 11.17.0)
added 208 packages in 658ms

Worth knowing: >=12.0.0 is unsatisfiable on every Node release, not just the stock ones — npm 12 declares node: ^22.22.2 || ^24.15.0 || >=26.0.0, so on a managed tree older than 22.22.2 even the automatic recovery from #76464 can't install it and the update dead-ends. Your change fixes that class too.

One overlap to flag: #76459 moves the same two lines to node >=26.0.0 / npm >=12.0.0. The pairing that actually installs clean is node >=26.0.0 + your npm >=11.17.0 — I've asked there to take your floor, so whichever merges second just needs the other's value. Catching the stale website/package.json mirror was a good call.

[teknium1]

Thanks — this is a focused correction to the npm engine floor. GitHub current main requires npm >=12.0.0 in package.json:55-58 and package-lock.json:31-34, while the repository enables engine-strict in .npmrc:1-4. The PR updates those root values and the independently enforced website value (website/package.json:55-58) to >=11.17.0.

hermes_cli/main.py:5497-5506 already derives the failed engine range from npm output, upgrades only a Hermes-managed npm, and retries, so no repair-path implementation change is needed. The existing member review on this PR independently verified the npm 11.17 capability boundary against published tarballs; the preceding incompatibility guard originated in 3975e9d753.

Automated hermes-sweeper review.

[OutThisLife]

Superseded by #76459.

Your diagnosis was right and the >=11.17.0 floor was correctly researched — I verified the min-release-age-exclude boundary against the published tarballs and it lands exactly where you said (11.16.0: 0 files, 11.17.0: 26).

What changed is the other side of the constraint. #76459 now installs npm 12 into the vendored Node tree itself, on both POSIX and Windows, so the toolchain satisfies >=12.0.0 instead of the manifest relaxing to meet the tarball:

✓ Node v26.5.1 installed
→ Upgrading bundled npm to satisfy >=12.0.0...
✓ npm 12.0.2 installed
$ npm ci → added 208 packages

That fixes #76486 for the same users, so this one is redundant rather than wrong. Thanks for catching the stale website/package.json mirror too — worth a separate PR if it still drifts after #76459 lands.