Introduce IDE mode installer (#4877)

4 files changed, 316 insertions, 1 deletions

diff --git a/packages/core/src/ide/detect-ide.ts b/packages/core/src/ide/detect-ide.ts
new file mode 100644
index 00000000..ae46789e
--- /dev/null
+++ b/packages/core/src/ide/detect-ide.ts
@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export enum DetectedIde {
+  VSCode = 'vscode',
+}
+
+export function getIdeDisplayName(ide: DetectedIde): string {
+  switch (ide) {
+    case DetectedIde.VSCode:
+      return 'VSCode';
+    default:
+      throw new Error(`Unsupported IDE: ${ide}`);
+  }
+}
+
+export function detectIde(): DetectedIde | undefined {
+  if (process.env.TERM_PROGRAM === 'vscode') {
+    return DetectedIde.VSCode;
+  }
+  return undefined;
+}
diff --git a/packages/core/src/ide/ide-client.ts b/packages/core/src/ide/ide-client.ts
index 3c670d54..4dd720dd 100644
--- a/packages/core/src/ide/ide-client.ts
+++ b/packages/core/src/ide/ide-client.ts
@@ -4,6 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import {
+  detectIde,
+  DetectedIde,
+  getIdeDisplayName,
+} from '../ide/detect-ide.js';
 import { ideContext, IdeContextNotificationSchema } from '../ide/ideContext.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
@@ -32,13 +37,34 @@ export class IdeClient {
   private state: IDEConnectionState = {
     status: IDEConnectionStatus.Disconnected,
   };
+  private static instance: IdeClient;
+  private readonly currentIde: DetectedIde | undefined;
+  private readonly currentIdeDisplayName: string | undefined;
 
-  constructor() {
+  private constructor(ideMode: boolean) {
+    if (!ideMode) {
+      return;
+    }
+    this.currentIde = detectIde();
+    if (this.currentIde) {
+      this.currentIdeDisplayName = getIdeDisplayName(this.currentIde);
+    }
     this.init().catch((err) => {
       logger.debug('Failed to initialize IdeClient:', err);
     });
   }
 
+  static getInstance(ideMode: boolean): IdeClient {
+    if (!IdeClient.instance) {
+      IdeClient.instance = new IdeClient(ideMode);
+    }
+    return IdeClient.instance;
+  }
+
+  getCurrentIde(): DetectedIde | undefined {
+    return this.currentIde;
+  }
+
   getConnectionStatus(): IDEConnectionState {
     return this.state;
   }
@@ -141,6 +167,14 @@ export class IdeClient {
     if (this.state.status === IDEConnectionStatus.Connected) {
       return;
     }
+    if (!this.currentIde) {
+      this.setState(
+        IDEConnectionStatus.Disconnected,
+        'Not running in a supported IDE, skipping connection.',
+      );
+      return;
+    }
+
     this.setState(IDEConnectionStatus.Connecting);
 
     if (!this.validateWorkspacePath()) {
@@ -154,4 +188,8 @@ export class IdeClient {
 
     await this.establishConnection(port);
   }
+
+  getDetectedIdeDisplayName(): string | undefined {
+    return this.currentIdeDisplayName;
+  }
 }
diff --git a/packages/core/src/ide/ide-installer.test.ts b/packages/core/src/ide/ide-installer.test.ts
new file mode 100644
index 00000000..83459d6b
--- /dev/null
+++ b/packages/core/src/ide/ide-installer.test.ts
@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { getIdeInstaller, IdeInstaller } from './ide-installer.js';
+import * as child_process from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import { DetectedIde } from './detect-ide.js';
+
+vi.mock('child_process');
+vi.mock('fs');
+vi.mock('os');
+
+describe('ide-installer', () => {
+  describe('getIdeInstaller', () => {
+    it('should return a VsCodeInstaller for "vscode"', () => {
+      const installer = getIdeInstaller(DetectedIde.VSCode);
+      expect(installer).not.toBeNull();
+      // A more specific check might be needed if we export the class
+      expect(installer).toBeInstanceOf(Object);
+    });
+
+    it('should return null for an unknown IDE', () => {
+      const installer = getIdeInstaller('unknown' as DetectedIde);
+      expect(installer).toBeNull();
+    });
+  });
+
+  describe('VsCodeInstaller', () => {
+    let installer: IdeInstaller;
+
+    beforeEach(() => {
+      // We get a new installer for each test to reset the find command logic
+      installer = getIdeInstaller(DetectedIde.VSCode)!;
+      vi.spyOn(child_process, 'execSync').mockImplementation(() => '');
+      vi.spyOn(fs, 'existsSync').mockReturnValue(false);
+      vi.spyOn(os, 'homedir').mockReturnValue('/home/user');
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    describe('isInstalled', () => {
+      it('should return true if command is in PATH', async () => {
+        expect(await installer.isInstalled()).toBe(true);
+      });
+
+      it('should return true if command is in a known location', async () => {
+        vi.spyOn(child_process, 'execSync').mockImplementation(() => {
+          throw new Error('Command not found');
+        });
+        vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+        // Re-create the installer so it re-runs findVsCodeCommand
+        installer = getIdeInstaller(DetectedIde.VSCode)!;
+        expect(await installer.isInstalled()).toBe(true);
+      });
+
+      it('should return false if command is not found', async () => {
+        vi.spyOn(child_process, 'execSync').mockImplementation(() => {
+          throw new Error('Command not found');
+        });
+        vi.spyOn(fs, 'existsSync').mockReturnValue(false);
+        // Re-create the installer so it re-runs findVsCodeCommand
+        installer = getIdeInstaller(DetectedIde.VSCode)!;
+        expect(await installer.isInstalled()).toBe(false);
+      });
+    });
+
+    describe('install', () => {
+      it('should return a failure message if VS Code is not installed', async () => {
+        vi.spyOn(child_process, 'execSync').mockImplementation(() => {
+          throw new Error('Command not found');
+        });
+        vi.spyOn(fs, 'existsSync').mockReturnValue(false);
+        // Re-create the installer so it re-runs findVsCodeCommand
+        installer = getIdeInstaller(DetectedIde.VSCode)!;
+        const result = await installer.install();
+        expect(result.success).toBe(false);
+        expect(result.message).toContain(
+          'not found in your PATH or common installation locations',
+        );
+      });
+    });
+  });
+});
diff --git a/packages/core/src/ide/ide-installer.ts b/packages/core/src/ide/ide-installer.ts
new file mode 100644
index 00000000..725f4f7c
--- /dev/null
+++ b/packages/core/src/ide/ide-installer.ts
@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as child_process from 'child_process';
+import * as process from 'process';
+import { glob } from 'glob';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+import { fileURLToPath } from 'url';
+import { DetectedIde } from './detect-ide.js';
+
+const VSCODE_COMMAND = process.platform === 'win32' ? 'code.cmd' : 'code';
+const VSCODE_COMPANION_EXTENSION_FOLDER = 'vscode-ide-companion';
+
+export interface IdeInstaller {
+  install(): Promise<InstallResult>;
+  isInstalled(): Promise<boolean>;
+}
+
+export interface InstallResult {
+  success: boolean;
+  message: string;
+}
+
+async function findVsCodeCommand(): Promise<string | null> {
+  // 1. Check PATH first.
+  try {
+    child_process.execSync(
+      process.platform === 'win32'
+        ? `where.exe ${VSCODE_COMMAND}`
+        : `command -v ${VSCODE_COMMAND}`,
+      { stdio: 'ignore' },
+    );
+    return VSCODE_COMMAND;
+  } catch {
+    // Not in PATH, continue to check common locations.
+  }
+
+  // 2. Check common installation locations.
+  const locations: string[] = [];
+  const platform = process.platform;
+  const homeDir = os.homedir();
+
+  if (platform === 'darwin') {
+    // macOS
+    locations.push(
+      '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code',
+      path.join(homeDir, 'Library/Application Support/Code/bin/code'),
+    );
+  } else if (platform === 'linux') {
+    // Linux
+    locations.push(
+      '/usr/share/code/bin/code',
+      '/snap/bin/code',
+      path.join(homeDir, '.local/share/code/bin/code'),
+    );
+  } else if (platform === 'win32') {
+    // Windows
+    locations.push(
+      path.join(
+        process.env.ProgramFiles || 'C:\\Program Files',
+        'Microsoft VS Code',
+        'bin',
+        'code.cmd',
+      ),
+      path.join(
+        homeDir,
+        'AppData',
+        'Local',
+        'Programs',
+        'Microsoft VS Code',
+        'bin',
+        'code.cmd',
+      ),
+    );
+  }
+
+  for (const location of locations) {
+    if (fs.existsSync(location)) {
+      return location;
+    }
+  }
+
+  return null;
+}
+
+class VsCodeInstaller implements IdeInstaller {
+  private vsCodeCommand: Promise<string | null>;
+
+  constructor() {
+    this.vsCodeCommand = findVsCodeCommand();
+  }
+
+  async isInstalled(): Promise<boolean> {
+    return (await this.vsCodeCommand) !== null;
+  }
+
+  async install(): Promise<InstallResult> {
+    const commandPath = await this.vsCodeCommand;
+    if (!commandPath) {
+      return {
+        success: false,
+        message: `VS Code command-line tool not found in your PATH or common installation locations.`,
+      };
+    }
+
+    const bundleDir = path.dirname(fileURLToPath(import.meta.url));
+    // The VSIX file is copied to the bundle directory as part of the build.
+    let vsixFiles = glob.sync(path.join(bundleDir, '*.vsix'));
+    if (vsixFiles.length === 0) {
+      // If the VSIX file is not in the bundle, it might be a dev
+      // environment running with `npm start`. Look for it in the original
+      // package location, relative to the bundle dir.
+      const devPath = path.join(
+        bundleDir, // .../packages/core/dist/src/ide
+        '..', // .../packages/core/dist/src
+        '..', // .../packages/core/dist
+        '..', // .../packages/core
+        '..', // .../packages
+        VSCODE_COMPANION_EXTENSION_FOLDER,
+        '*.vsix',
+      );
+      vsixFiles = glob.sync(devPath);
+    }
+    if (vsixFiles.length === 0) {
+      return {
+        success: false,
+        message:
+          'Could not find the required VS Code companion extension. Please file a bug via /bug.',
+      };
+    }
+
+    const vsixPath = vsixFiles[0];
+    const command = `"${commandPath}" --install-extension "${vsixPath}" --force`;
+    try {
+      child_process.execSync(command, { stdio: 'pipe' });
+      return {
+        success: true,
+        message:
+          'VS Code companion extension installed successfully. Restart gemini-cli in a fresh terminal window.',
+      };
+    } catch (_error) {
+      return {
+        success: false,
+        message: 'Failed to install VS Code companion extension.',
+      };
+    }
+  }
+}
+
+export function getIdeInstaller(ide: DetectedIde): IdeInstaller | null {
+  switch (ide) {
+    case 'vscode':
+      return new VsCodeInstaller();
+    default:
+      return null;
+  }
+}