From 7507605be55d70fe11f699d08f80cc458d0c554a Mon Sep 17 00:00:00 2001
From: Colby McHenry <me@colbymchenry.com>
Date: Tue, 7 Apr 2026 14:02:19 -0500
Subject: [PATCH] fix: Add Node.js 25+ compatibility warning for V8 WASM
 compiler bugs

Addresses potential crashes on Node.js 25+ due to V8 turboshaft WASM compiler issues. Adds runtime version check with warning to recommend Node.js 22 LTS and sets upper bound engine constraint to
---
 package.json         |  2 +-
 src/bin/codegraph.ts | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 8746b08..f46a951 100644
--- a/package.json
+++ b/package.json
@@ -54,6 +54,6 @@
     "sqlite-vss": "^0.1.2"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0 <25.0.0"
   }
 }
diff --git a/src/bin/codegraph.ts b/src/bin/codegraph.ts
index 13f603f..1066a07 100644
--- a/src/bin/codegraph.ts
+++ b/src/bin/codegraph.ts
@@ -50,6 +50,22 @@ async function loadCodeGraph(): Promise<typeof import('../index')> {
 const importESM = new Function('specifier', 'return import(specifier)') as
   (specifier: string) => Promise<typeof import('@clack/prompts')>;
 
+// Warn about unsupported Node.js versions (Node 25+ has V8 turboshaft WASM bugs)
+const nodeVersion = process.versions.node;
+const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
+if (nodeMajor >= 25) {
+  console.warn(
+    '\x1b[33m⚠\x1b[0m  CodeGraph may crash on Node.js %s due to a V8 WASM compiler bug in Node 25+.',
+    nodeVersion
+  );
+  console.warn(
+    '   Please use Node.js 22 LTS instead: https://nodejs.org/en/download'
+  );
+  console.warn(
+    '   See: https://github.com/colbymchenry/codegraph/issues/81\n'
+  );
+}
+
 // Check if running with no arguments - run installer
 if (process.argv.length === 2) {
   import('../installer').then(({ runInstaller }) =>