Introduce IDE mode installer (#4877)

packages/core/src/config/config.test.ts

@@ -18,6 +18,7 @@ import {
 } from '../core/contentGenerator.js';
 import { GeminiClient } from '../core/client.js';
 import { GitService } from '../services/gitService.js';
+import { IdeClient } from '../ide/ide-client.js';
 
 vi.mock('fs', async (importOriginal) => {
   const actual = await importOriginal<typeof import('fs')>();
@@ -119,6 +120,7 @@ describe('Server Config (config.ts)', () => {
     telemetry: TELEMETRY_SETTINGS,
     sessionId: SESSION_ID,
     model: MODEL,
+    ideClient: IdeClient.getInstance(false),
   };
 
   beforeEach(() => {

packages/core/src/config/config.ts

@@ -185,7 +185,7 @@ export interface ConfigParameters {
   noBrowser?: boolean;
   summarizeToolOutput?: Record<string, SummarizeToolOutputSettings>;
   ideMode?: boolean;
-  ideClient?: IdeClient;
+  ideClient: IdeClient;
 }
 
 export class Config {
@@ -229,7 +229,7 @@ export class Config {
   private readonly extensionContextFilePaths: string[];
   private readonly noBrowser: boolean;
   private readonly ideMode: boolean;
-  private readonly ideClient: IdeClient | undefined;
+  private readonly ideClient: IdeClient;
   private inFallbackMode = false;
   private readonly maxSessionTurns: number;
   private readonly listExtensions: boolean;
@@ -593,7 +593,7 @@ export class Config {
     return this.ideMode;
   }
 
-  getIdeClient(): IdeClient | undefined {
+  getIdeClient(): IdeClient {
     return this.ideClient;
   }
 

packages/core/src/config/flashFallback.test.ts

@@ -7,6 +7,7 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { Config } from './config.js';
 import { DEFAULT_GEMINI_MODEL, DEFAULT_GEMINI_FLASH_MODEL } from './models.js';
+import { IdeClient } from '../ide/ide-client.js';
 import fs from 'node:fs';
 
 vi.mock('node:fs');
@@ -25,6 +26,7 @@ describe('Flash Model Fallback Configuration', () => {
       debugMode: false,
       cwd: '/test',
       model: DEFAULT_GEMINI_MODEL,
+      ideClient: IdeClient.getInstance(false),
     });
 
     // Initialize contentGeneratorConfig for testing
@@ -49,6 +51,7 @@ describe('Flash Model Fallback Configuration', () => {
         debugMode: false,
         cwd: '/test',
         model: DEFAULT_GEMINI_MODEL,
+        ideClient: IdeClient.getInstance(false),
       });
 
       // Should not crash when contentGeneratorConfig is undefined
@@ -72,6 +75,7 @@ describe('Flash Model Fallback Configuration', () => {
         debugMode: false,
         cwd: '/test',
         model: 'custom-model',
+        ideClient: IdeClient.getInstance(false),
       });
 
       expect(newConfig.getModel()).toBe('custom-model');

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;
+}

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;
+  }
 }

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',
+        );
+      });
+    });
+  });
+});

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;
+  }
+}

packages/core/src/index.ts

@@ -48,6 +48,8 @@ export * from './services/gitService.js';
 // Export IDE specific logic
 export * from './ide/ide-client.js';
 export * from './ide/ideContext.js';
+export * from './ide/ide-installer.js';
+export { getIdeDisplayName, DetectedIde } from './ide/detect-ide.js';
 
 // Export Shell Execution Service
 export * from './services/shellExecutionService.js';

packages/core/src/telemetry/telemetry.test.ts

@@ -12,6 +12,7 @@ import {
 } from './sdk.js';
 import { Config } from '../config/config.js';
 import { NodeSDK } from '@opentelemetry/sdk-node';
+import { IdeClient } from '../ide/ide-client.js';
 
 vi.mock('@opentelemetry/sdk-node');
 vi.mock('../config/config.js');
@@ -29,6 +30,7 @@ describe('telemetry', () => {
       targetDir: '/test/dir',
       debugMode: false,
       cwd: '/test/dir',
+      ideClient: IdeClient.getInstance(false),
     });
     vi.spyOn(mockConfig, 'getTelemetryEnabled').mockReturnValue(true);
     vi.spyOn(mockConfig, 'getTelemetryOtlpEndpoint').mockReturnValue(

packages/core/src/tools/tool-registry.test.ts

@@ -30,6 +30,7 @@ import {
   Schema,
 } from '@google/genai';
 import { spawn } from 'node:child_process';
+import { IdeClient } from '../ide/ide-client.js';
 import fs from 'node:fs';
 
 vi.mock('node:fs');
@@ -139,6 +140,7 @@ const baseConfigParams: ConfigParameters = {
   geminiMdFileCount: 0,
   approvalMode: ApprovalMode.DEFAULT,
   sessionId: 'test-session-id',
+  ideClient: IdeClient.getInstance(false),
 };
 
 describe('ToolRegistry', () => {

packages/core/src/utils/flashFallback.integration.test.ts

@@ -17,6 +17,7 @@ import {
 import { DEFAULT_GEMINI_FLASH_MODEL } from '../config/models.js';
 import { retryWithBackoff } from './retry.js';
 import { AuthType } from '../core/contentGenerator.js';
+import { IdeClient } from '../ide/ide-client.js';
 
 vi.mock('node:fs');
 
@@ -34,6 +35,7 @@ describe('Flash Fallback Integration', () => {
       debugMode: false,
       cwd: '/test',
       model: 'gemini-2.5-pro',
+      ideClient: IdeClient.getInstance(false),
     });
 
     // Reset simulation state for each test