Skip to content

πŸ™Œ OpenHands: AI-Driven Development

chore: replace remaining Node 22 runtime pins (#17997)

Engel Nysta972ca444b8b
diff --git a/.agents/skills/desktop-electron/references/guide.md b/.agents/skills/desktop-electron/references/guide.md
index 1e896ec5a1..43cdc841fb 100644
--- a/.agents/skills/desktop-electron/references/guide.md
+++ b/.agents/skills/desktop-electron/references/guide.md
@@ -10,4 +10,4 @@
- Electron desktop app name in dev (macOS) β€” `npm run desktop` shows the app as "Electron" in the Dock unless `scripts/brand-dev-electron.mjs` (wired as the `predesktop` hook) has run. There are **three independent name sources** and they must all be set; getting one wrong looks like the fix silently not working. (1) `app.name` β€” Electron-internal, drives the menu bar, About panel and `app.getPath("userData")`. It comes from `productName` in `electron/package.json`, read by Electron's `default_app` in dev and `lib/browser/init` when packaged. Note `default_app` only reads `<arg>/package.json`, so `npm run desktop` must point electron at the `electron/` **directory** β€” `electron electron/main.mjs` makes it probe `electron/main.mjs/package.json`, miss, and leave `app.name` at the host bundle default. (2) `CFBundleDisplayName` / `CFBundleName` in the running bundle's Info.plist β€” what `lsappinfo` and `NSRunningApplication.localizedName` report. (3) **The `.app` directory name β€” this is what the Dock tooltip actually shows.** macOS prefers the bundle's filesystem name over the plist keys; `/Applications/DBeaver.app` displays as "DBeaver" despite `CFBundleName = "DBeaver Community"`. So patching only the plist is NOT enough β€” the script also renames `node_modules/electron/dist/Electron.app` β†’ `<productName>.app` and rewrites `node_modules/electron/path.txt` to match (`getElectronPath()` in `node_modules/electron/index.js` joins path.txt onto `dist/` and silently re-downloads Electron ~100 MB if it doesn't resolve, so the two must move together). `CFBundleExecutable` is deliberately left as `Electron` β€” `/Applications/Antigravity.app` ships that exact value and still displays correctly, so it only affects `ps`/Activity Monitor. Editing the plist does not break code signing: Electron's dist is ad-hoc *linker-signed* (`Info.plist=not bound`, `Sealed Resources=none`), so the signature covers only the Mach-O. `npm run build:desktop` is unaffected by the rename β€” electron-builder packages from `~/Library/Caches/electron/electron-v*.zip`, never from `node_modules/electron/dist`. The packaged app never had the problem: electron-builder emits `<productName>.app` with matching plist keys. Already-running instances keep the name they launched with, so quit and relaunch when verifying.
-- Electron desktop `node` / `npm` / `npx` PATH bridging β€” when the packaged `.app` is launched from Finder/Spotlight on macOS, the OS gives it a minimal PATH (`/usr/bin:/bin`). Homebrew, nvm, asdf installs of Node.js are invisible to spawned subprocesses. Two breakages flow from that: (1) backend launcher scripts that do `spawn("node", ...)` can't find Node; (2) most stdio MCP marketplace entries (Slack, GitHub, Figma, etc.) use `command: "npx"`, and when the agent-server tries to spawn them the missing `npx` makes the spawn fail with ENOENT β€” the SDK reports it as an `error_kind: "connection"` MCP test failure, which the install modal renders as `MCP$TEST_ERROR_CONNECTION` ("Could not reach the server. Check the URL and server type."), a misleading error since no URL is involved. **First fix attempt β€” DOES NOT WORK for stdio MCPs:** wrap `node`/`npm`/`npx` with thin shell scripts that run Electron with `ELECTRON_RUN_AS_NODE=1` against the package's CLI JS. That bridges the ENOENT but stdio JSON-RPC servers spawned through the wrapper exit with `McpError: Connection closed` before completing the MCP handshake β€” Electron-as-Node has subtly different stdin/stdout pipe semantics from a vanilla `node` binary when used as a stdio child of a windowed process. **Working fix:** bundle the real Node.js distribution. `scripts/download-node.mjs` downloads the official `node-v<ver>-<platform>-<arch>` tarball from `https://nodejs.org/dist/v<ver>/` into `resources/node/` (gitignored), prunes `include/`, `share/`, docs, and `node_modules/corepack` to keep the size down (~130 MB on Linux x64, dominated by the Node binary itself). Default pin: `NODE_BUNDLE_VERSION = "22.12.0"` (the volta pin in `package.json`; every 22.x build shares the Electron 42 ABI β€” the `engines.node` floor is now `>=24`, so it is no longer the rationale); override with `NODE_VERSION=`. `electron-builder.config.mjs` ships `resources/node/` as an extraResource β†’ `<Resources>/node/`. `electron/main.mjs::injectBundledNode()` prepends the platform-appropriate bin dir to `PATH` (POSIX: `<Resources>/node/bin`; Windows: `<Resources>/node/`) so subsequent spawns of `node`/`npm`/`npx` resolve to real binaries with full stdio fidelity. It also `chmod +x`'s the binaries on POSIX because electron-builder doesn't always preserve the bit. `injectBundledNode()` is a no-op when `!app.isPackaged` (dev `npm run desktop` uses the developer's system node). `build:desktop` and `build:desktop:universal` both run `download-node.mjs` after `download-uv.mjs`. If the bundled dir is missing at runtime, `injectBundledNode()` logs a loud `[desktop]` warning instead of silently leaving PATH bare. **extraResources will not copy the distribution's root `node_modules`:** `app-builder-lib/src/util/filter.ts::createFilter` returns `false` for any entry whose path relative to the copy root is exactly `node_modules`, *before* the `filter` patterns are consulted, so no `filter` value can opt back in. The Windows Node zip puts npm at `<root>/node_modules/npm` and hits this exactly; POSIX tarballs put it at `<root>/lib/node_modules/npm` and are unaffected β€” which is why this only broke Windows. Shipped result: a working `node.exe` beside `npm.cmd`/`npx.cmd` shims pointing at a missing `node_modules\npm\bin\npx-cli.js`, so every `npx -y <pkg>` spawn dies with `MODULE_NOT_FOUND` *and* shadows the user's own npm, since the dir is PREPENDED to PATH. The `afterPack` hook (`restoreBundledNodeNpm`) copies that directory into the packed output and then hard-fails the build if `npm-cli.js` still isn't there, mirroring the check `download-node.mjs` already runs on the source tree.
+- Electron desktop `node` / `npm` / `npx` PATH bridging β€” when the packaged `.app` is launched from Finder/Spotlight on macOS, the OS gives it a minimal PATH (`/usr/bin:/bin`). Homebrew, nvm, asdf installs of Node.js are invisible to spawned subprocesses. Two breakages flow from that: (1) backend launcher scripts that do `spawn("node", ...)` can't find Node; (2) most stdio MCP marketplace entries (Slack, GitHub, Figma, etc.) use `command: "npx"`, and when the agent-server tries to spawn them the missing `npx` makes the spawn fail with ENOENT β€” the SDK reports it as an `error_kind: "connection"` MCP test failure, which the install modal renders as `MCP$TEST_ERROR_CONNECTION` ("Could not reach the server. Check the URL and server type."), a misleading error since no URL is involved. **First fix attempt β€” DOES NOT WORK for stdio MCPs:** wrap `node`/`npm`/`npx` with thin shell scripts that run Electron with `ELECTRON_RUN_AS_NODE=1` against the package's CLI JS. That bridges the ENOENT but stdio JSON-RPC servers spawned through the wrapper exit with `McpError: Connection closed` before completing the MCP handshake β€” Electron-as-Node has subtly different stdin/stdout pipe semantics from a vanilla `node` binary when used as a stdio child of a windowed process. **Working fix:** bundle the real Node.js distribution. `scripts/download-node.mjs` downloads the official `node-v<ver>-<platform>-<arch>` tarball from `https://nodejs.org/dist/v<ver>/` into `resources/node/` (gitignored), prunes `include/`, `share/`, docs, and `node_modules/corepack` to keep the size down (~130 MB on Linux x64, dominated by the Node binary itself). Default pin: `NODE_BUNDLE_VERSION = "24.21.0"` (aligned with the volta pin in `package.json` and the `engines.node >=24` requirement); override with `NODE_VERSION=`. `electron-builder.config.mjs` ships `resources/node/` as an extraResource β†’ `<Resources>/node/`. `electron/main.mjs::injectBundledNode()` prepends the platform-appropriate bin dir to `PATH` (POSIX: `<Resources>/node/bin`; Windows: `<Resources>/node/`) so subsequent spawns of `node`/`npm`/`npx` resolve to real binaries with full stdio fidelity. It also `chmod +x`'s the binaries on POSIX because electron-builder doesn't always preserve the bit. `injectBundledNode()` is a no-op when `!app.isPackaged` (dev `npm run desktop` uses the developer's system node). `build:desktop` and `build:desktop:universal` both run `download-node.mjs` after `download-uv.mjs`. If the bundled dir is missing at runtime, `injectBundledNode()` logs a loud `[desktop]` warning instead of silently leaving PATH bare. **extraResources will not copy the distribution's root `node_modules`:** `app-builder-lib/src/util/filter.ts::createFilter` returns `false` for any entry whose path relative to the copy root is exactly `node_modules`, *before* the `filter` patterns are consulted, so no `filter` value can opt back in. The Windows Node zip puts npm at `<root>/node_modules/npm` and hits this exactly; POSIX tarballs put it at `<root>/lib/node_modules/npm` and are unaffected β€” which is why this only broke Windows. Shipped result: a working `node.exe` beside `npm.cmd`/`npx.cmd` shims pointing at a missing `node_modules\npm\bin\npx-cli.js`, so every `npx -y <pkg>` spawn dies with `MODULE_NOT_FOUND` *and* shadows the user's own npm, since the dir is PREPENDED to PATH. The `afterPack` hook (`restoreBundledNodeNpm`) copies that directory into the packed output and then hard-fails the build if `npm-cli.js` still isn't there, mirroring the check `download-node.mjs` already runs on the source tree.
diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.md
index ef7f9a869f..6adefbc04e 100644
--- a/docs/SELF_HOSTING.md
+++ b/docs/SELF_HOSTING.md
@@ -110,7 +110,7 @@ Install the prerequisites on the machine. On Ubuntu:
```bash
apt-get update
apt-get install -y curl git
-# Node.js 22.x (use nvm, asdf, or NodeSource β€” whatever you prefer)
+# Node.js 24.x (use nvm, asdf, or NodeSource β€” whatever you prefer)
# uv (for the agent-server uvx runtime):
curl -LsSf https://astral.sh/uv/install.sh | sh
```
diff --git a/package.json b/package.json
index ff84fba0d5..05fa1a2f2f 100644
--- a/package.json
+++ b/package.json
@@ -176,7 +176,7 @@
},
"packageManager": "[email protected]",
"volta": {
- "node": "22.12.0"
+ "node": "24.21.0"
},
"msw": {
"workerDirectory": [
diff --git a/scripts/download-node.mjs b/scripts/download-node.mjs
index b68b8b5dbe..d3da85f065 100644
--- a/scripts/download-node.mjs
+++ b/scripts/download-node.mjs
@@ -28,7 +28,7 @@
*
* Usage:
* node scripts/download-node.mjs # host arch β†’ resources/node/
- * NODE_VERSION=22.10.0 node scripts/download-node.mjs
+ * NODE_VERSION=24.21.0 node scripts/download-node.mjs
* ELECTRON_ARCH=universal node scripts/download-node.mjs # macOS only
*
* Output (per platform):
@@ -57,22 +57,17 @@ import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { execFileSync } from "node:child_process";
-import { resolveDownloadArches, resourceDirName } from "./download-arch-utils.mjs";
+import {
+ resolveDownloadArches,
+ resourceDirName,
+} from "./download-arch-utils.mjs";
const __dirname = dirname(fileURLToPath(import.meta.url));
const projectRoot = join(__dirname, "..");
-// Pinned Node version. Electron 42 ships Node 22, so we bundle a 22.x
-// LTS release to match the embedded runtime's ABI/native-module surface.
-// We intentionally use 22.12.0 β€” the repo's own support floor
-// (package.json engines.node >=22.12.0, volta 22.12.0) β€” rather than
-// Electron 42.3.2's exact embedded Node patch level: the bundled binary
-// runs this repo's launcher scripts, and native modules only need ABI
-// parity (NODE_MODULE_VERSION 127, shared by all 22.x builds).
-// Override at build time with NODE_VERSION=… (e.g. to test against a
-// newer release). Major version >=22 only; engines.node in npm 10.x
-// requires ^18.17.0 || >=20.5.0.
-const NODE_BUNDLE_VERSION = "22.12.0";
+// Keep the subprocess runtime aligned with the package.json Volta pin.
+// Override at build time with NODE_VERSION=… to test another release.
+const NODE_BUNDLE_VERSION = "24.21.0";
// ── Platform detection ───────────────────────────────────────────────────────
@@ -104,7 +99,9 @@ export function getPlatformSpec(version, platform = PLATFORM, arch = ARCH) {
const distArch = arch === "arm64" ? "arm64" : "x64";
return { name: `${base}-win-${distArch}`, ext: "zip" };
}
- throw new Error(`Unsupported platform for Node download: ${platform}/${arch}`);
+ throw new Error(
+ `Unsupported platform for Node download: ${platform}/${arch}`,
+ );
}
// ── Version resolution ───────────────────────────────────────────────────────
@@ -393,7 +390,9 @@ async function main() {
failOnDanglingSymlinks(outDir);
const mb = Math.round(dirSizeBytes(outDir) / (1024 * 1024));
- console.log(`[download-node] βœ“ Node v${version} ready at ${outDir} (~${mb} MB)`);
+ console.log(
+ `[download-node] βœ“ Node v${version} ready at ${outDir} (~${mb} MB)`,
+ );
} finally {
try {
rmSync(tmpFile, { force: true });
@@ -407,7 +406,10 @@ async function main() {
// module to exercise getPlatformSpec with zero network I/O.
// process.argv[1] is undefined when the module is plain-imported (vitest),
// and pathToFileURL(undefined) would throw, so guard on it first.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (
+ process.argv[1] &&
+ import.meta.url === pathToFileURL(process.argv[1]).href
+) {
main().catch((err) => {
console.error("[download-node] Error:", err.message);
process.exit(1);