fix: guard dependency installs on unsupported Node versions

.github/workflows/ci.yml

@@ -120,6 +120,9 @@ jobs:
 
       - uses: ./.github/actions/setup
 
+      - name: install guard unit
+        run: bun run test:install-guard
+
       - uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # actions/cache@v5
         with:
           path: .turbo/cache

.node-version

@@ -0,0 +1 @@
+24

package.json

@@ -16,7 +16,9 @@
     "typecheck": "bun turbo typecheck",
     "lint": "eslint \"packages/{app,ui,desktop-electron}/src/**/*.{ts,tsx}\"",
     "lint:ci": "bun run lint",
+    "preinstall": "node script/check-node.mjs",
     "postinstall": "bun run --cwd packages/opencode fix-node-pty",
+    "test:install-guard": "cd script && bun test check-node.test.mjs",
     "test": "echo 'do not run tests from root' && exit 1"
   },
   "workspaces": {

script/check-node.mjs

@@ -0,0 +1,34 @@
+const unsupportedMajor = 25
+const version = process.version
+const match = /^v?(\d+)(?:\.|$)/.exec(version)
+
+let errorMessage = ""
+
+if (!match) {
+  errorMessage = `Unsupported Node version format: ${version}. Use Node 24 for PawWork dependency installs.`
+}
+
+if (match && Number(match[1]) >= unsupportedMajor) {
+  errorMessage = [
+    "Use Node 24 for PawWork dependency installs.",
+    "",
+    `Current node: ${version}`,
+    "",
+    "Node 25+ can make Electron 40.8.0 postinstall leave an incomplete Electron.app while reporting success.",
+    "Switch to Node 24 (see .node-version), delete node_modules, then reinstall dependencies.",
+    "",
+    "macOS/Linux:",
+    "  rm -rf node_modules",
+    "",
+    "PowerShell:",
+    "  Remove-Item -Recurse -Force node_modules",
+    "",
+    "Then reinstall:",
+    "  bun install --frozen-lockfile",
+  ].join("\n")
+}
+
+if (errorMessage) {
+  console.error(errorMessage)
+  process.exit(1)
+}

script/check-node.test.mjs

@@ -0,0 +1,47 @@
+import { expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+
+function runGuard(version) {
+  return spawnSync(
+    "node",
+    [
+      "--input-type=module",
+      "-e",
+      [
+        `Object.defineProperty(process, "version", { value: ${JSON.stringify(version)} })`,
+        `await import("./check-node.mjs")`,
+      ].join(";"),
+    ],
+    {
+      cwd: import.meta.dirname,
+      encoding: "utf8",
+    },
+  )
+}
+
+test("rejects Node 25+ with reinstall guidance", () => {
+  const result = runGuard("v25.0.0")
+
+  expect(result.status).toBe(1)
+  expect(result.stderr).toContain("Current node: v25.0.0")
+  expect(result.stderr).toContain("Node 24")
+  expect(result.stderr).toContain(".node-version")
+  expect(result.stderr).toContain("delete node_modules")
+  expect(result.stderr).toContain("rm -rf node_modules")
+  expect(result.stderr).toContain("Remove-Item -Recurse -Force node_modules")
+  expect(result.stderr).toContain("bun install --frozen-lockfile")
+})
+
+test("allows Node 24", () => {
+  const result = runGuard("v24.14.0")
+
+  expect(result.status).toBe(0)
+  expect(result.stderr).toBe("")
+})
+
+test("rejects unparseable Node versions with a clean message", () => {
+  const result = runGuard("invalid-version")
+
+  expect(result.status).toBe(1)
+  expect(result.stderr).toContain("Unsupported Node version format: invalid-version")
+})