auto-discover vscode-codeql managed CodeQL CLI dist

The MCP server now automatically finds the CodeQL CLI binary installed
by the GitHub.vscode-codeql extension, which stores it off-PATH at:
  <globalStorage>/github.vscode-codeql/distribution<N>/codeql/codeql

Discovery uses distribution.json (folderIndex hint) with a fallback
to scanning distribution* directories sorted by descending index.

This is implemented at two layers:
- VS Code extension CliResolver (Strategy 3, between PATH and known
  locations) — uses the StoragePaths-provided storage directory
- Server-side cli-executor (fallback when CODEQL_PATH is unset) —
  probes platform-specific VS Code global storage directories for
  Code, Code - Insiders, and VSCodium

Also fixes extension.test.ts constructor mocks for Vitest 4.x
compatibility (vi.clearAllMocks instead of vi.resetAllMocks).

Author: data-douser

.prettierignore

@@ -16,3 +16,6 @@ node_modules
 server/dist/
 query-results*
 workshops/
+
+.vscode-test
+

extensions/vscode/package.json

@@ -137,7 +137,7 @@
     "build": "npm run clean && npm run lint && npm run bundle",
     "bundle": "node esbuild.config.js",
     "bundle:server": "node scripts/bundle-server.js",
-    "clean": "rm -rf dist server *.vsix",
+    "clean": "rm -rf dist server .vscode-test/* *.vsix",
     "lint": "eslint src/ test/",
     "lint:fix": "eslint src/ test/ --fix",
     "package": "vsce package --no-dependencies --out codeql-development-mcp-server-v$(node -e 'process.stdout.write(require(`./package.json`).version)').vsix",

extensions/vscode/src/codeql/cli-resolver.ts

@@ -1,9 +1,13 @@
 import { execFile } from 'child_process';
-import { access } from 'fs/promises';
+import { access, readdir, readFile } from 'fs/promises';
 import { constants } from 'fs';
+import { join } from 'path';
 import { DisposableObject } from '../common/disposable';
 import type { Logger } from '../common/logger';
 
+/** Expected binary name for the CodeQL CLI on the current platform. */
+const CODEQL_BINARY_NAME = process.platform === 'win32' ? 'codeql.exe' : 'codeql';
+
 /** Known filesystem locations where the CodeQL CLI may be installed. */
 const KNOWN_LOCATIONS = [
   '/usr/local/bin/codeql',
@@ -18,15 +22,20 @@ const KNOWN_LOCATIONS = [
  * Detection strategy (in order):
  *  1. `CODEQL_PATH` environment variable
  *  2. `codeql` on `$PATH` (via `which`)
- *  3. Known filesystem locations
+ *  3. `vscode-codeql` managed distribution (via `distribution.json` hint
+ *     or directory scan of `distribution*` folders)
+ *  4. Known filesystem locations
  *
  * Results are cached. Call `invalidateCache()` when the environment changes
  * (e.g. `extensions.onDidChange` fires).
  */
 export class CliResolver extends DisposableObject {
   private cachedPath: string | undefined | null = null; // null = not yet resolved
 
-  constructor(private readonly logger: Logger) {
+  constructor(
+    private readonly logger: Logger,
+    private readonly vsCodeCodeqlStoragePath?: string,
+  ) {
     super();
   }
 
@@ -58,7 +67,15 @@ export class CliResolver extends DisposableObject {
       return whichPath;
     }
 
-    // Strategy 3: known filesystem locations
+    // Strategy 3: vscode-codeql managed distribution
+    const distPath = await this.resolveFromVsCodeDistribution();
+    if (distPath) {
+      this.logger.info(`CodeQL CLI found via vscode-codeql distribution: ${distPath}`);
+      this.cachedPath = distPath;
+      return distPath;
+    }
+
+    // Strategy 4: known filesystem locations
     for (const location of KNOWN_LOCATIONS) {
       const validated = await this.validateBinary(location);
       if (validated) {
@@ -89,6 +106,100 @@ export class CliResolver extends DisposableObject {
     }
   }
 
+  /**
+   * Discover the CodeQL CLI binary from the `vscode-codeql` extension's
+   * managed distribution directory.
+   *
+   * The `GitHub.vscode-codeql` extension downloads the CodeQL CLI into:
+   *   `<globalStorage>/github.vscode-codeql/distribution<N>/codeql/codeql`
+   *
+   * where `<N>` is an incrementing folder index that increases each time
+   * the extension upgrades the CLI. A `distribution.json` file in the
+   * storage root contains a `folderIndex` property that identifies the
+   * current distribution directory. We use that as a fast-path hint and
+   * fall back to scanning for the highest-numbered `distribution*` folder.
+   */
+  private async resolveFromVsCodeDistribution(): Promise<string | undefined> {
+    if (!this.vsCodeCodeqlStoragePath) return undefined;
+
+    try {
+      // Fast path: read distribution.json for the exact folder index
+      const hintPath = await this.resolveFromDistributionJson();
+      if (hintPath) return hintPath;
+    } catch {
+      this.logger.debug('distribution.json hint unavailable, falling back to directory scan');
+    }
+
+    // Fallback: scan for distribution* directories
+    return this.resolveFromDistributionScan();
+  }
+
+  /**
+   * Read `distribution.json` to get the current `folderIndex` and validate
+   * the binary at the corresponding path.
+   */
+  private async resolveFromDistributionJson(): Promise<string | undefined> {
+    if (!this.vsCodeCodeqlStoragePath) return undefined;
+
+    const jsonPath = join(this.vsCodeCodeqlStoragePath, 'distribution.json');
+    const content = await readFile(jsonPath, 'utf-8');
+    const data = JSON.parse(content) as { folderIndex?: number };
+
+    if (typeof data.folderIndex !== 'number') return undefined;
+
+    const binaryPath = join(
+      this.vsCodeCodeqlStoragePath,
+      `distribution${data.folderIndex}`,
+      'codeql',
+      CODEQL_BINARY_NAME,
+    );
+    const validated = await this.validateBinary(binaryPath);
+    if (validated) {
+      this.logger.debug(`Resolved CLI via distribution.json (folderIndex=${data.folderIndex})`);
+      return binaryPath;
+    }
+    return undefined;
+  }
+
+  /**
+   * Scan for `distribution*` directories sorted by numeric suffix (highest
+   * first) and return the first one containing a valid `codeql` binary.
+   */
+  private async resolveFromDistributionScan(): Promise<string | undefined> {
+    if (!this.vsCodeCodeqlStoragePath) return undefined;
+
+    try {
+      const entries = await readdir(this.vsCodeCodeqlStoragePath, { withFileTypes: true });
+
+      const distDirs = entries
+        .filter(e => e.isDirectory() && /^distribution\d*$/.test(e.name))
+        .map(e => ({
+          name: e.name,
+          num: parseInt(e.name.replace('distribution', '') || '0', 10),
+        }))
+        .sort((a, b) => b.num - a.num);
+
+      for (const dir of distDirs) {
+        const binaryPath = join(
+          this.vsCodeCodeqlStoragePath,
+          dir.name,
+          'codeql',
+          CODEQL_BINARY_NAME,
+        );
+        const validated = await this.validateBinary(binaryPath);
+        if (validated) {
+          this.logger.debug(`Resolved CLI via distribution scan: ${dir.name}`);
+          return binaryPath;
+        }
+      }
+    } catch {
+      this.logger.debug(
+        `Could not scan vscode-codeql distribution directory: ${this.vsCodeCodeqlStoragePath}`,
+      );
+    }
+    return undefined;
+  }
+
   /** Attempt to find `codeql` on PATH. */
   private resolveFromPath(): Promise<string | undefined> {
     return new Promise((resolve) => {

extensions/vscode/src/extension.ts

@@ -24,10 +24,10 @@ export async function activate(
   logger.info('CodeQL Development MCP Server extension activating...');
 
   // --- Core components ---
-  const cliResolver = new CliResolver(logger);
+  const storagePaths = new StoragePaths(context);
+  const cliResolver = new CliResolver(logger, storagePaths.getCodeqlGlobalStoragePath());
   const serverManager = new ServerManager(context, logger);
   const packInstaller = new PackInstaller(cliResolver, serverManager, logger);
-  const storagePaths = new StoragePaths(context);
   const envBuilder = new EnvironmentBuilder(
     context,
     cliResolver,

extensions/vscode/test/codeql/cli-resolver.test.ts

@@ -9,10 +9,12 @@ vi.mock('child_process', () => ({
 // Mock fs/promises
 vi.mock('fs/promises', () => ({
   access: vi.fn(),
+  readdir: vi.fn(),
+  readFile: vi.fn(),
 }));
 
 import { execFile } from 'child_process';
-import { access } from 'fs/promises';
+import { access, readdir, readFile } from 'fs/promises';
 
 function createMockLogger() {
   return {
@@ -164,4 +166,181 @@ describe('CliResolver', () => {
   it('should be disposable', () => {
     expect(() => resolver.dispose()).not.toThrow();
   });
+
+  describe('vscode-codeql distribution discovery', () => {
+    const storagePath = '/mock/globalStorage/github.vscode-codeql';
+    const binaryName = process.platform === 'win32' ? 'codeql.exe' : 'codeql';
+
+    beforeEach(() => {
+      const originalEnv = process.env.CODEQL_PATH;
+      delete process.env.CODEQL_PATH;
+
+      // Make `which codeql` fail
+      vi.mocked(execFile).mockImplementation(
+        (_cmd: any, _args: any, callback: any) => {
+          if (String(_cmd) === 'which' || String(_cmd) === 'where') {
+            callback(new Error('not found'), '', '');
+          } else {
+            // codeql --version for validateBinary
+            callback(null, 'CodeQL CLI 2.24.2\n', '');
+          }
+          return {} as any;
+        },
+      );
+
+      // All known filesystem locations fail
+      vi.mocked(access).mockRejectedValue(new Error('ENOENT'));
+
+      return () => {
+        if (originalEnv === undefined) {
+          delete process.env.CODEQL_PATH;
+        } else {
+          process.env.CODEQL_PATH = originalEnv;
+        }
+      };
+    });
+
+    it('should resolve from distribution.json hint', async () => {
+      resolver = new CliResolver(logger, storagePath);
+
+      // distribution.json exists with folderIndex=3
+      vi.mocked(readFile).mockResolvedValueOnce(
+        JSON.stringify({ folderIndex: 3, release: { name: 'v2.24.2' } }),
+      );
+
+      // The binary at distribution3/codeql/codeql is valid
+      const expectedPath = `${storagePath}/distribution3/codeql/${binaryName}`;
+      vi.mocked(access).mockImplementation((path: any) => {
+        if (String(path) === expectedPath) return Promise.resolve(undefined as any);
+        return Promise.reject(new Error('ENOENT'));
+      });
+
+      const result = await resolver.resolve();
+      expect(result).toBe(expectedPath);
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('vscode-codeql distribution'),
+      );
+    });
+
+    it('should fall back to directory scan when distribution.json is missing', async () => {
+      resolver = new CliResolver(logger, storagePath);
+
+      // distribution.json read fails
+      vi.mocked(readFile).mockRejectedValueOnce(new Error('ENOENT'));
+
+      // Directory listing returns distribution directories
+      vi.mocked(readdir).mockResolvedValueOnce([
+        { name: 'distribution1', isDirectory: () => true },
+        { name: 'distribution3', isDirectory: () => true },
+        { name: 'distribution2', isDirectory: () => true },
+        { name: 'queries', isDirectory: () => true },
+        { name: 'distribution.json', isDirectory: () => false },
+      ] as any);
+
+      // Only distribution3 has a valid binary
+      const expectedPath = `${storagePath}/distribution3/codeql/${binaryName}`;
+      vi.mocked(access).mockImplementation((path: any) => {
+        if (String(path) === expectedPath) return Promise.resolve(undefined as any);
+        return Promise.reject(new Error('ENOENT'));
+      });
+
+      const result = await resolver.resolve();
+      expect(result).toBe(expectedPath);
+    });
+
+    it('should scan directories sorted by descending number', async () => {
+      resolver = new CliResolver(logger, storagePath);
+
+      vi.mocked(readFile).mockRejectedValueOnce(new Error('ENOENT'));
+
+      vi.mocked(readdir).mockResolvedValueOnce([
+        { name: 'distribution1', isDirectory: () => true },
+        { name: 'distribution10', isDirectory: () => true },
+        { name: 'distribution2', isDirectory: () => true },
+      ] as any);
+
+      // All binaries are valid — should pick distribution10 (highest number)
+      vi.mocked(access).mockResolvedValue(undefined as any);
+
+      const result = await resolver.resolve();
+      expect(result).toBe(`${storagePath}/distribution10/codeql/${binaryName}`);
+    });
+
+    it('should return undefined when no storage path is provided', async () => {
+      resolver = new CliResolver(logger); // no storage path
+
+      vi.mocked(execFile).mockImplementation(
+        (_cmd: any, _args: any, callback: any) => {
+          callback(new Error('not found'), '', '');
+          return {} as any;
+        },
+      );
+
+      const result = await resolver.resolve();
+      expect(result).toBeUndefined();
+    });
+
+    it('should skip distribution directories without a valid binary', async () => {
+      resolver = new CliResolver(logger, storagePath);
+
+      vi.mocked(readFile).mockRejectedValueOnce(new Error('ENOENT'));
+
+      vi.mocked(readdir).mockResolvedValueOnce([
+        { name: 'distribution3', isDirectory: () => true },
+        { name: 'distribution2', isDirectory: () => true },
+        { name: 'distribution1', isDirectory: () => true },
+      ] as any);
+
+      const expectedPath = `${storagePath}/distribution1/codeql/${binaryName}`;
+      vi.mocked(access).mockImplementation((path: any) => {
+        // Only distribution1 has the binary
+        if (String(path) === expectedPath) return Promise.resolve(undefined as any);
+        return Promise.reject(new Error('ENOENT'));
+      });
+
+      const result = await resolver.resolve();
+      expect(result).toBe(expectedPath);
+    });
+
+    it('should handle distribution.json with invalid JSON gracefully', async () => {
+      resolver = new CliResolver(logger, storagePath);
+
+      // Return non-JSON content
+      vi.mocked(readFile).mockResolvedValueOnce('not-valid-json');
+
+      vi.mocked(readdir).mockResolvedValueOnce([
+        { name: 'distribution1', isDirectory: () => true },
+      ] as any);
+
+      const expectedPath = `${storagePath}/distribution1/codeql/${binaryName}`;
+      vi.mocked(access).mockImplementation((path: any) => {
+        if (String(path) === expectedPath) return Promise.resolve(undefined as any);
+        return Promise.reject(new Error('ENOENT'));
+      });
+
+      const result = await resolver.resolve();
+      expect(result).toBe(expectedPath);
+    });
+
+    it('should handle distribution.json without folderIndex property', async () => {
+      resolver = new CliResolver(logger, storagePath);
+
+      vi.mocked(readFile).mockResolvedValueOnce(
+        JSON.stringify({ release: { name: 'v2.24.2' } }),
+      );
+
+      vi.mocked(readdir).mockResolvedValueOnce([
+        { name: 'distribution1', isDirectory: () => true },
+      ] as any);
+
+      const expectedPath = `${storagePath}/distribution1/codeql/${binaryName}`;
+      vi.mocked(access).mockImplementation((path: any) => {
+        if (String(path) === expectedPath) return Promise.resolve(undefined as any);
+        return Promise.reject(new Error('ENOENT'));
+      });
+
+      const result = await resolver.resolve();
+      expect(result).toBe(expectedPath);
+    });
+  });
 });