Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): pin pnpm commands to Node 24.21.0 via devEngines.runtime (#5580)

Nick Gomez3ee4a0980bee
diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjs
index 71c680df7..f39a89c09 100644
--- a/.github/scripts/release-cascade-shape.test.mjs
+++ b/.github/scripts/release-cascade-shape.test.mjs
@@ -2304,7 +2304,11 @@ describe('the release App credential never shares a job with installed packages'
afterAll(() => rmSync(root, { recursive: true, force: true }));
const bin = join(root, 'bin');
mkdirSync(bin);
- const nodeGlobalRoot = join(dirname(process.execPath), '..', 'lib', 'node_modules');
+ const npmCliPath = execFileSync('npm', ['exec', '--call', 'node -p process.env.npm_execpath'], {
+ cwd: tmpdir(),
+ encoding: 'utf8',
+ }).trim();
+ const nodeGlobalRoot = dirname(dirname(dirname(npmCliPath)));
writeFileSync(
join(bin, 'npm'),
'#!/bin/sh\nprintf \'%s\\n\' "$*" >> "$NPM_LOG"\nif [ "$1" = root ]; then printf \'%s\\n\' "$NPM_GLOBAL_ROOT"; exit 0; fi\nif [ "$1" = view ]; then [ -n "$NPM_VIEW" ] || exit 1; printf \'%s\\n\' "$NPM_VIEW"; fi\nexit 0\n',
@@ -2372,7 +2376,7 @@ describe('the release App credential never shares a job with installed packages'
};
const cli = (version, extra = {}) => ({ name: '@inkeep/open-knowledge', version, publishConfig: { access: 'public' }, ...extra });
- test('the stub npm hands the step a real pacote, the one bundled with the npm that runs these tests', () => {
+ test('the stub npm hands the step a real pacote, the one bundled with the npm on PATH', () => {
expect(existsSync(join(nodeGlobalRoot, 'npm', 'node_modules', 'pacote', 'package.json'))).toBe(true);
expect(commands(publishStep())).toContain('pacote="$(npm root -g)/npm/node_modules/pacote"');
expect(commands(publishStep())).not.toMatch(/\btar\s/);
diff --git a/AGENTS.md b/AGENTS.md
index e10748c4b..02d07cec6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,7 @@ This is the public OpenKnowledge repository. Keep changes compatible with the pu
- Read [README.md](./README.md) for the project overview.
- Read [CONTRIBUTING.md](./CONTRIBUTING.md) before changing public PR flow, dependencies, or exported docs.
-- Use Node.js 24 or newer and pnpm 12 or newer.
+- Use pnpm 12 or newer. Corepack and npm need a Node.js to provide it, such as the `.node-version` release; the standalone installer needs none. pnpm commands run the Node.js version `package.json`'s `devEngines.runtime` pins, which equals `.node-version`; select `.node-version` yourself before running `node` directly.
- This repo does not use code comments. Read [Comment policy](#comment-policy) before writing any.
## Commands
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 638402b83..2e6a55085 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,7 +33,7 @@ See `.env.example` for optional settings (OpenTelemetry, a custom dev port).
### Toolchain
-The repo pins **Node.js >=24.2.0** via `engines.node` and `.node-version`, and the `packageManager` field selects the exact **pnpm 12** version. The minor matters: `engines.node` is `>=24.2.0`, not `>=24`, because the build scripts use `import.meta.main`, which landed in 24.2. Run `corepack enable pnpm` once so the `pnpm` commands below use Corepack's shim, or install pnpm 12 standalone (`npm install -g pnpm@12`). A pnpm 10 on your `PATH` cannot switch itself to pnpm 12, so upgrade it or use Corepack. With a Node version manager, use `fnm install`, `mise install`, or `volta install node@24`. pnpm enforces the engine range (`engineStrict` in `pnpm-workspace.yaml`), so on 24.0 or 24.1 `pnpm install` fails fast — pin 24.2.0 or newer first.
+The repo pins **Node.js 24.21.0** in `.node-version` and in `package.json`'s `devEngines.runtime`, and the `packageManager` field selects the exact **pnpm 12** version. `pnpm install` downloads that Node.js into the pnpm store the first time, from the per-platform archives `pnpm-lock.yaml` pins by checksum, so the first install needs network access. After that, every command started through `pnpm run`, `pnpm exec` or a package script runs on it, whichever `node` is on your `PATH`, and `engineStrict` in `pnpm-workspace.yaml` checks the `engines.node` range against it. Keep the two pins equal, and run `pnpm install` after changing them so the commands, and the Turbo cache key the install writes, pick up the new version. Corepack and npm both need a Node.js to provide pnpm, so install the `.node-version` release first with your Node version manager (for example `fnm install`), then run `corepack enable pnpm` once so the `pnpm` commands below use Corepack's shim, or install pnpm 12 with `npm install -g pnpm@12`. The standalone installer from [pnpm.io/installation](https://pnpm.io/installation) needs no Node.js. A pnpm 10 on your `PATH` cannot switch itself to pnpm 12, so upgrade it or use Corepack. For a script you start with `node` directly, select `.node-version` first with your Node version manager, for example `fnm use`.
TypeScript is pinned twice on purpose. `@typescript/native` is this repo's alias for `typescript@~7.0.2`, the Go compiler the gates run; it owns the `tsc` binary, so `node_modules/.bin/tsc --version` at the root reports 7. The root's own `typescript` stays on `~6.0.3` only to supply tsserver to your editor, because TypeScript 7 ships none — that is an API resolution, not the compiler. The split means 7.0-only lib typings or an unchecked side-effect import can red a gate your editor calls clean. Open your editor at the repo root, not inside a package, or its language server falls back to a machine-global TypeScript. Any package that runs `tsc` in a script declares `"typescript": "~7.0.2"` of its own; `node scripts/check-typescript-resolution.mjs`, which `pnpm run check:drift:guards` runs, enforces the *resolved* 7.0 line rather than the declared range; the range is a tilde for that reason, because a caret installs clean today and reds once 7.1 ships. Its errors say why.
diff --git a/package.json b/package.json
index 1ad67b0f0..e3d046f1a 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,13 @@
"engines": {
"node": ">=24.2.0"
},
+ "devEngines": {
+ "runtime": {
+ "name": "node",
+ "version": "24.21.0",
+ "onFail": "download"
+ }
+ },
"scripts": {
"postinstall": "node scripts/create-turbo-cache-key.mjs",
"knip": "turbo run build --filter=@inkeep/open-knowledge-server --filter=@inkeep/open-knowledge-core --output-logs=errors-only && knip",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f7277c93a..24a34bb10 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -184,6 +184,9 @@ importers:
lint-staged:
specifier: ^16.4.0
version: 16.4.0
+ node:
+ specifier: runtime:24.21.0
+ version: runtime:24.21.0
oxlint:
specifier: 1.80.0
version: 1.80.0([email protected])
@@ -9829,6 +9832,138 @@ packages:
resolution: {integrity: sha512-wRNIrw4DmVLKQlbgOMdkMx27Wrpzes2hh5Jtbi2bjPd+4wJstWIqP5A+lscnqbm0xxmT5Bpg8Lec5ItEBwx6BQ==}
engines: {node: '>=18'}
+ node@runtime:24.21.0:
+ resolution:
+ type: variations
+ variants:
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-rseyRkr7mfB4wZywbSAdVDvTsxHLoHEoK84bF8l+WLs=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-aix-ppc64.tar.gz
+ targets:
+ - cpu: ppc64
+ os: aix
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-vtfupTJeEQjzLOUijd1qXw8IpJnuQqp0Qq6lg3AvYFc=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-darwin-arm64.tar.gz
+ targets:
+ - cpu: arm64
+ os: darwin
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-FGLLOzBGuBXPjqQ209pFDsGp8R2sflpGsK2lMF1+gJc=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-darwin-x64.tar.gz
+ targets:
+ - cpu: x64
+ os: darwin
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-ckKCw7Q67JmKqVJzgEZbRdIp4CG1gDX19PYwleq/5dU=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-linux-arm64.tar.gz
+ targets:
+ - cpu: arm64
+ os: linux
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-UcXVMGbukpILYXg7A7Buy5nzZhFg97Fcp36EdBFaZ7w=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-linux-ppc64le.tar.gz
+ targets:
+ - cpu: ppc64le
+ os: linux
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-Xy+jdCLgx13jXBaG/lHXgyTywqj+LMI5pB2cAAop2Tg=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-linux-s390x.tar.gz
+ targets:
+ - cpu: s390x
+ os: linux
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-PWNAX8ZaDS0pdsHwvC/Se7C9ByEkaecFqsPwOuWrTJw=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-linux-x64-musl.tar.gz
+ targets:
+ - cpu: x64
+ os: linux
+ libc: musl
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-bh24fvWLiBnl1UAu/xU2SRsY7djre+5e94l4duiNxf8=
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-linux-x64.tar.gz
+ targets:
+ - cpu: x64
+ os: linux
+ - resolution:
+ archive: zip
+ bin:
+ node: node.exe
+ integrity: sha256-h3mxveHTn41CDjtXqmV7OYka9DTT3kSpGQRM7AZ4WSE=
+ prefix: node-v24.21.0-win-arm64
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-win-arm64.zip
+ targets:
+ - cpu: arm64
+ os: win32
+ - resolution:
+ archive: zip
+ bin:
+ node: node.exe
+ integrity: sha256-FY92hbRN5R9sDfHRU1JsvNPhvHOajfxgdyHO913p5UE=
+ prefix: node-v24.21.0-win-x64
+ type: binary
+ url: https://nodejs.org/download/release/v24.21.0/node-v24.21.0-win-x64.zip
+ targets:
+ - cpu: x64
+ os: win32
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-MEiwgR4VjKDYZytZyDmGF2PhREkpgNjSmzad/uRXR+Q=
+ type: binary
+ url: https://unofficial-builds.nodejs.org/download/release/v24.21.0/node-v24.21.0-linux-arm64-musl.tar.gz
+ targets:
+ - cpu: arm64
+ os: linux
+ libc: musl
+ - resolution:
+ archive: tarball
+ bin:
+ node: bin/node
+ integrity: sha256-AacT402pjntNKjGR7nyj+T3QOE0aLvI8N5shYe5uEzo=
+ type: binary
+ url: https://unofficial-builds.nodejs.org/download/release/v24.21.0/node-v24.21.0-linux-x64-musl.tar.gz
+ targets:
+ - cpu: x64
+ os: linux
+ libc: musl
+ version: 24.21.0
+ hasBin: true
+
resolution: {integrity: sha512-Zhq3a+yFKrYwSBluL4H9XP3m3y5uvQkB/09CwDruCiRmR/UJYnn9W4R48ry0uGC70aeTPKLynBtscP9efFFcPw==}
engines: {node: ^20.17.0 || >=22.9.0}
@@ -21056,6 +21191,8 @@ snapshots:
+ node@runtime:24.21.0: {}
+
dependencies:
abbrev: 4.0.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 5e0b585fe..4e4a81099 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -7,9 +7,6 @@ packageExtensions:
peerDependencies:
zod: '^3.25.0 || ^4.0.0'
-# Fail the install/run fast when the active Node is below the engines.node floor
-# (>=24). CI and local development both use .node-version, so pnpm must not
-# silently continue under a different runtime.
engineStrict: true
# Corepack selects packageManager. Avoid a second pnpm bootstrap and its env