Add AI Review preflight checks and bump Node.js to >=18

- Add preflight module that detects standalone `agent` CLI or falls
  back to `cursor agent`, and enforces Node >=18
- Update AI Review setup and orchestrator to use preflight validation
- Use process.execPath for MCP server to ensure Node >=18
- Add unit tests for preflight logic with dependency injection
- Update README with AI Review setup instructions

Made-with: Cursor

Author: albin-paul-saju

README.md

@@ -18,6 +18,27 @@ You can also set `gerrit.auth.password` and `gerrit.auth.cookie` in settings; th
 
 Additionally the extension requires the python package [git-review](https://pypi.org/project/git-review/) to be installed.
 
+### AI Review Setup
+
+The AI Review feature requires:
+
+-   **Node.js >= 18** — the extension host and Gerrit MCP server both need Node 18+.
+-   **Cursor Agent CLI** (`agent`) — install it by running:
+
+    ```bash
+    curl https://cursor.com/install -fsS | bash
+    ```
+
+    Verify with `agent --version`. See the [Cursor CLI docs](https://cursor.com/docs/cli/installation) for details.
+
+Once installed, run **Gerrit: Enable AI Review** from the command palette. This will:
+
+1.  Let you pick an AI model and checkout behavior.
+2.  Write a `.cursor/mcp.json` with the `gerrit-review` MCP server configuration.
+3.  Auto-enable the MCP server via `agent mcp enable gerrit-review`.
+
+After setup, use **Gerrit: AI Review Change** (or the lightbulb icon in the Change Explorer) to run an AI-powered review on any Gerrit change.
+
 ## Features
 
 ### Changes panel

package-lock.json

@@ -5,7 +5,7 @@
 	"version": "1.2.58",
 	"engines": {
 		"vscode": "^1.76.0",
-		"node": ">=14.16.0"
+		"node": ">=18.0.0"
 	},
 	"license": "MIT",
 	"categories": [
@@ -1570,6 +1570,7 @@
 		"package": "npm run prepack && npm exec vsce package --no-yarn",
 		"package-dev": "npm run prepush && npm run build:debug && npm exec vsce package --no-yarn",
 		"generate-package": "generate-package-json generate --name Gerrit --input src/commands/defs.ts -w -p package.json --handler src/commands/commands.ts --validate --prefix Gerrit && prettier --write package.json",
+		"test": "TS_NODE_PROJECT=tests/tsconfig.json mocha --require ts-node/register 'tests/**/*.test.ts' --timeout 10000",
 		"prepush": "npm run generate-package && npm run format-staged && npm run lint -- --fix && npm run compile"
 	},
 	"devDependencies": {
@@ -1579,7 +1580,7 @@
 		"@types/fs-extra": "^9.0.13",
 		"@types/glob": "^7.1.4",
 		"@types/mocha": "^9.0.0",
-		"@types/node": "14.x",
+		"@types/node": "18.x",
 		"@types/react": "^17.0.37",
 		"@types/react-dom": "^17.0.11",
 		"@types/vscode": "1.76",

package.json

@@ -1,13 +1,18 @@
 import { getGerritURLFromReviewFile } from '../credentials/enterCredentials';
 import { getGitReviewFileCached } from '../credentials/gitReviewFile';
-import { writeMcpConfig, GerritCredentials } from '../mcp/mcpManager';
-import { window, workspace, ExtensionContext } from 'vscode';
 import { GerritSecrets } from '../credentials/secrets';
-import { getConfiguration } from '../vscode/config';
-import { getGerritRepo } from '../gerrit/gerrit';
-import { selectAiModel } from './modelSelector';
 import { tryExecAsync } from '../git/gitCLI';
+import { getGerritRepo } from '../gerrit/gerrit';
+import { writeMcpConfig, GerritCredentials } from '../mcp/mcpManager';
 import { log } from '../util/log';
+import { getConfiguration } from '../vscode/config';
+import {
+  runPreflight,
+  buildMcpEnableCommand,
+  AgentCommand,
+} from './preflight';
+import { selectAiModel } from './modelSelector';
+import { window, workspace, ExtensionContext } from 'vscode';
 
 type CheckoutBehavior = 'ask' | 'always' | 'never';
 
@@ -16,8 +21,12 @@ export async function enableAiReview(
 ): Promise<void> {
   const config = getConfiguration();
 
-  const cursorOk = await verifyCursorCli();
-  if (!cursorOk) {
+  const preflight = await runPreflight();
+  if (!preflight.ok || !preflight.agent) {
+    void window.showErrorMessage(
+      preflight.error
+      ?? 'AI Review prerequisites not met.'
+    );
     return;
   }
 
@@ -65,7 +74,7 @@ export async function enableAiReview(
       + 'may not have full Gerrit integration.'
     );
   } else {
-    await enableMcpServer();
+    await enableMcpServer(preflight.agent);
   }
 
   await config.update(
@@ -80,31 +89,6 @@ export async function enableAiReview(
   log('AI Review enabled successfully');
 }
 
-async function verifyCursorCli(): Promise<boolean> {
-  const { success, stdout } = await tryExecAsync(
-    'which cursor',
-    { silent: true }
-  );
-
-  if (!success || !stdout.trim()) {
-    const action = await window.showErrorMessage(
-      'Cursor CLI not found. Please ensure '
-      + 'the "cursor" command is available in '
-      + 'your PATH. You can install it from '
-      + 'Cursor settings (Command Palette > '
-      + '"Install \'cursor\' command").',
-      'Retry',
-      'Cancel'
-    );
-    if (action === 'Retry') {
-      return verifyCursorCli();
-    }
-    return false;
-  }
-
-  log('Cursor CLI found at: ' + stdout.trim());
-  return true;
-}
 
 async function pickCheckoutBehavior(): Promise<
   CheckoutBehavior | undefined
@@ -193,12 +177,17 @@ async function extractCredentials(
   };
 }
 
-async function enableMcpServer(): Promise<void> {
+async function enableMcpServer(
+  agent: AgentCommand
+): Promise<void> {
   const cwd =
     workspace.workspaceFolders?.[0]?.uri.fsPath;
 
+  const cmd = buildMcpEnableCommand(
+    agent, 'gerrit-review'
+  );
   const { success, stderr } = await tryExecAsync(
-    'cursor agent mcp enable gerrit-review',
+    cmd,
     { silent: true, cwd }
   );
 

src/lib/ai-review/enableAiReview.ts

@@ -0,0 +1,102 @@
+import { exec } from 'child_process';
+
+const MIN_NODE_MAJOR = 18;
+const INSTALL_URL =
+	'https://cursor.com/docs/cli/installation';
+
+export interface AgentCommand {
+	cmd: string;
+	baseArgs: string[];
+}
+
+export interface PreflightDeps {
+	whichCmd: (
+		name: string
+	) => Promise<boolean>;
+	getNodeMajor: () => number;
+}
+
+function defaultWhich(
+	name: string
+): Promise<boolean> {
+	return new Promise((resolve) => {
+		exec(
+			`which ${name}`,
+			(err, stdout) => {
+				resolve(!err && !!stdout.trim());
+			}
+		);
+	});
+}
+
+const defaultDeps: PreflightDeps = {
+	whichCmd: defaultWhich,
+	getNodeMajor: (): number => {
+		return parseInt(
+			process.versions.node.split('.')[0],
+			10
+		);
+	},
+};
+
+export interface PreflightResult {
+	ok: boolean;
+	agent?: AgentCommand;
+	error?: string;
+}
+
+export async function runPreflight(
+	deps: PreflightDeps = defaultDeps
+): Promise<PreflightResult> {
+	const nodeMajor = deps.getNodeMajor();
+	if (nodeMajor < MIN_NODE_MAJOR) {
+		return {
+			ok: false,
+			error:
+				`Node.js >= ${MIN_NODE_MAJOR} is required `
+				+ 'for AI Review, but found '
+				+ `v${nodeMajor}. Please upgrade Node.js.`,
+		};
+	}
+
+	const hasAgent = await deps.whichCmd('agent');
+	if (hasAgent) {
+		return {
+			ok: true,
+			agent: { cmd: 'agent', baseArgs: [] },
+		};
+	}
+
+	const hasCursor = await deps.whichCmd('cursor');
+	if (hasCursor) {
+		return {
+			ok: true,
+			agent: {
+				cmd: 'cursor',
+				baseArgs: ['agent'],
+			},
+		};
+	}
+
+	return {
+		ok: false,
+		error:
+			'Cursor Agent CLI not found. '
+			+ 'Install it with: '
+			+ 'curl https://cursor.com/install '
+			+ '-fsS | bash  '
+			+ `(${INSTALL_URL})`,
+	};
+}
+
+export function buildMcpEnableCommand(
+	agent: AgentCommand,
+	serverName: string
+): string {
+	const parts = [
+		agent.cmd, ...agent.baseArgs,
+		'mcp', 'enable', serverName,
+	];
+	return parts.join(' ');
+}
+