Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mjsindex 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.mdindex 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.## Commandsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.jsonindex 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.yamlindex f7277c93a..24a34bb10 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -184,6 +184,9 @@ importers:lint-staged:specifier: ^16.4.0version: 16.4.0+ node:+ specifier: runtime:24.21.0+ version: runtime:24.21.0oxlint:specifier: 1.80.0version: 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.0diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yamlindex 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