fix VSIX-bundled server install & version artifacts

data-douser · data-douser · commit 6db3048b2cca · 2026-02-23T10:47:23.000-07:00
VSIX install fixes:
- Skip npm install entirely when the VSIX bundle is present; the bundle
  already ships server/dist/, server/ql/, and server/package.json
- PackInstaller now prefers bundled qlpacks from the VSIX over the
  npm-installed copy in globalStorage, fixing version skew between the
  packs being installed and the server code being run
- In the unbundled fallback path (Extension Development Host), compare
  the npm-installed version against the extension's own version instead
  of short-circuiting on targetVersion === 'latest'

Versioned release artifact filenames:
- VSIX: codeql-development-mcp-server-vX.Y.Z.vsix (was unversioned)
- CodeQL pack bundles: ql-mcp-&lt;lang&gt;-tools-src-vX.Y.Z.tar.gz (was unversioned)
- Update release, build-and-test, and package scripts accordingly
- Add *.vsix to .gitignore
- Normalize docs to use vX.Y.Z placeholders consistently
diff --git a/.github/workflows/build-and-test-extension.yml b/.github/workflows/build-and-test-extension.yml
@@ -69,7 +69,9 @@ jobs:
 
       - name: Verify VSIX packaging
         working-directory: extensions/vscode
-        run: npx @vscode/vsce package --no-dependencies --out codeql-development-mcp-server.vsix
+        run: |
+          VERSION=$(node -e "console.log(require('./package.json').version)")
+          npx @vscode/vsce package --no-dependencies --out "codeql-development-mcp-server-v${VERSION}.vsix"
 
       - name: Verify VSIX contents
         working-directory: extensions/vscode
diff --git a/.github/workflows/release-codeql.yml b/.github/workflows/release-codeql.yml
@@ -115,7 +115,8 @@ jobs:
           for lang in ${LANGUAGES}; do
             PACK_DIR="server/ql/${lang}/tools/src"
             if [ -d "${PACK_DIR}" ]; then
-              PACK_NAME="ql-mcp-${lang}-tools-src"
+              VERSION="${{ steps.version.outputs.version }}"
+              PACK_NAME="ql-mcp-${lang}-tools-src-${VERSION}"
               OUTPUT="dist-packs/${PACK_NAME}.tar.gz"
               echo "📦 Bundling ${PACK_DIR} -> ${OUTPUT}..."
               codeql pack bundle --threads=-1 --output="${OUTPUT}" -- "${PACK_DIR}"
diff --git a/.github/workflows/release-vsix.yml b/.github/workflows/release-vsix.yml
@@ -15,7 +15,7 @@ on:
         description: 'The full version string with "v" prefix (e.g., vX.Y.Z)'
         value: ${{ jobs.publish-vsix.outputs.version }}
       vsix_name:
-        description: 'The VSIX filename (e.g., codeql-development-mcp-server.vsix)'
+        description: 'The VSIX filename (e.g., codeql-development-mcp-server-vX.Y.Z.vsix)'
         value: ${{ jobs.publish-vsix.outputs.vsix_name }}
 
 # Note: This workflow is called exclusively via workflow_call from release.yml.
@@ -85,7 +85,8 @@ jobs:
         id: package
         working-directory: extensions/vscode
         run: |
-          VSIX_NAME="codeql-development-mcp-server.vsix"
+          VERSION="${{ steps.version.outputs.version }}"
+          VSIX_NAME="codeql-development-mcp-server-${VERSION}.vsix"
           npx @vscode/vsce package --no-dependencies --out "${VSIX_NAME}"
           echo "vsix_name=${VSIX_NAME}" >> $GITHUB_OUTPUT
           echo "✅ Packaged ${VSIX_NAME}"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -243,7 +243,7 @@ jobs:
           files: |
             codeql-development-mcp-server-${{ needs.resolve-version.outputs.version }}.tar.gz
             dist-packs/*.tar.gz
-            dist-vsix/codeql-development-mcp-server.vsix
+            dist-vsix/codeql-development-mcp-server-${{ needs.resolve-version.outputs.version }}.vsix
           generate_release_notes: true
           tag_name: ${{ needs.resolve-version.outputs.version }}
 
diff --git a/.gitignore b/.gitignore
@@ -26,6 +26,7 @@ codeql-development-mcp-server.code-workspace
 *.swo
 *.tgz
 *.tar.gz
+*.vsix
 *~
 
 .vscode/mcp.json
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -47,7 +47,7 @@ npx -y codeql-development-mcp-server
 ### From GitHub Releases
 
 1. Download the latest release from [Releases](https://github.com/advanced-security/codeql-development-mcp-server/releases)
-2. Extract: `tar -xzf codeql-development-mcp-server-vX.X.X.tar.gz -C /path/to/destination`
+2. Extract: `tar -xzf codeql-development-mcp-server-vX.Y.Z.tar.gz -C /path/to/destination`
 
 ### From Source
 
diff --git a/docs/vscode/extension.md b/docs/vscode/extension.md
@@ -17,12 +17,12 @@ to do by hand.
 
 ### From `.vsix` (GitHub Releases)
 
-Download `codeql-development-mcp-server.vsix` from the latest
+Download `codeql-development-mcp-server-vX.Y.Z.vsix` from the latest
 [GitHub Release](https://github.com/advanced-security/codeql-development-mcp-server/releases),
 then install:
 
 ```bash
-code --install-extension codeql-development-mcp-server.vsix
+code --install-extension codeql-development-mcp-server-vX.Y.Z.vsix
 ```
 
 Or in VS Code: **Extensions** sidebar → `⋯` menu → **Install from VSIX…** → select the file.
@@ -40,7 +40,7 @@ From the repository root:
 
 ```bash
 npm run package:vsix
-code --install-extension extensions/vscode/codeql-development-mcp-server.vsix
+code --install-extension extensions/vscode/codeql-development-mcp-server-vX.Y.Z.vsix
 ```
 
 The extension requires the [CodeQL extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-codeql) (`GitHub.vscode-codeql`) and will prompt you to install it if missing.
diff --git a/extensions/vscode/README.md b/extensions/vscode/README.md
@@ -13,7 +13,7 @@ A VS Code extension that automatically installs, configures, and manages the [Co
 ### From `.vsix`
 
 ```bash
-code --install-extension codeql-development-mcp-server.vsix
+code --install-extension codeql-development-mcp-server-vX.Y.Z.vsix
 ```
 
 Or in VS Code: **Extensions** sidebar → `⋯` menu → **Install from VSIX…** → select the file.
@@ -23,7 +23,7 @@ Or in VS Code: **Extensions** sidebar → `⋯` menu → **Install from VSIX…*
 ```bash
 cd extensions/vscode
 npm run package
-code --install-extension codeql-development-mcp-server.vsix
+code --install-extension codeql-development-mcp-server-vX.Y.Z.vsix
 ```
 
 ## What It Does
diff --git a/extensions/vscode/package.json b/extensions/vscode/package.json
@@ -140,7 +140,7 @@
     "clean": "rm -rf dist server *.vsix",
     "lint": "eslint src/ test/",
     "lint:fix": "eslint src/ test/ --fix",
-    "package": "vsce package --no-dependencies --out codeql-development-mcp-server.vsix",
+    "package": "vsce package --no-dependencies --out codeql-development-mcp-server-v$(node -e 'process.stdout.write(require(`./package.json`).version)').vsix",
     "test": "npm run test:coverage && npm run test:integration",
     "test:coverage": "vitest --run --coverage",
     "test:integration": "vscode-test",
diff --git a/extensions/vscode/src/extension.ts b/extensions/vscode/src/extension.ts
@@ -172,12 +172,7 @@ export async function activate(
     // Run in background — don't block activation
     void (async () => {
       try {
-        const freshInstall = await serverManager.ensureInstalled();
-        if (freshInstall) {
-          logger.info('Fresh npm install completed — running CodeQL pack setup...');
-        } else {
-          logger.info('npm package already present — checking CodeQL packs...');
-        }
+        await serverManager.ensureInstalled();
         await packInstaller.installAll();
         mcpProvider.fireDidChange();
         logger.info('✅ MCP server setup complete. Server is ready to be started.');
diff --git a/extensions/vscode/src/server/pack-installer.ts b/extensions/vscode/src/server/pack-installer.ts
@@ -16,13 +16,19 @@ export interface PackInstallOptions {
 
 /**
  * Installs CodeQL pack dependencies for the bundled tool query packs
- * shipped with the `codeql-development-mcp-server` npm package.
+ * shipped inside the VSIX (or, as fallback, in the locally-installed
+ * `codeql-development-mcp-server` npm package).
  *
- * The npm package bundles the qlpack source files (`.ql` + lock files),
- * but their CodeQL library dependencies (e.g. `codeql/javascript-all`)
- * must be fetched from GHCR via `codeql pack install`. This class
- * automates the `codeql-development-mcp-server-setup-packs` step
- * documented in the getting-started guide.
+ * The VSIX bundles the qlpack source files (`.ql` + lock files) at
+ * `<extensionRoot>/server/ql/<lang>/tools/src/`, and the npm install
+ * mirrors them at `globalStorage/mcp-server/node_modules/.../ql/...`.
+ * The bundled copy is always preferred so that the packs used by
+ * `codeql pack install` match the server code running from the VSIX.
+ *
+ * CodeQL library dependencies (e.g. `codeql/javascript-all`) must be
+ * fetched from GHCR via `codeql pack install`. This class automates
+ * the `codeql-development-mcp-server-setup-packs` step documented in
+ * the getting-started guide.
  */
 export class PackInstaller extends DisposableObject {
   static readonly SUPPORTED_LANGUAGES = [
@@ -46,13 +52,25 @@ export class PackInstaller extends DisposableObject {
   }
 
   /**
-   * Get the qlpack source directories for all languages under the
-   * locally installed npm package.
+   * Get the root directory for qlpack resolution.
+   *
+   * Prefers the bundled `server/` directory inside the VSIX so that the
+   * packs installed match the server version. Falls back to the
+   * npm-installed package root in `globalStorage` (for local dev or when
+   * the VSIX bundle is missing).
+   */
+  private getQlpackRoot(): string {
+    return this.serverManager.getBundledQlRoot()
+      ?? this.serverManager.getPackageRoot();
+  }
+
+  /**
+   * Get the qlpack source directories for all languages.
    */
   getQlpackPaths(): string[] {
-    const packageRoot = this.serverManager.getPackageRoot();
+    const root = this.getQlpackRoot();
     return PackInstaller.SUPPORTED_LANGUAGES.map((lang) =>
-      join(packageRoot, 'ql', lang, 'tools', 'src'),
+      join(root, 'ql', lang, 'tools', 'src'),
     );
   }
 
@@ -69,12 +87,12 @@ export class PackInstaller extends DisposableObject {
       return;
     }
 
-    const packageRoot = this.serverManager.getPackageRoot();
+    const qlRoot = this.getQlpackRoot();
     const languages =
       options?.languages ?? [...PackInstaller.SUPPORTED_LANGUAGES];
 
     for (const lang of languages) {
-      const packDir = join(packageRoot, 'ql', lang, 'tools', 'src');
+      const packDir = join(qlRoot, 'ql', lang, 'tools', 'src');
 
       // Check if the pack directory exists
       try {
diff --git a/extensions/vscode/src/server/server-manager.ts b/extensions/vscode/src/server/server-manager.ts
@@ -24,18 +24,18 @@ export interface InstallOptions {
 }
 
 /**
- * Manages the local npm installation of `codeql-development-mcp-server`
- * into the extension's global storage directory.
+ * Manages the MCP server lifecycle for the VS Code extension.
  *
- * The local install serves two purposes:
- *  1. Provides the qlpack source files so PackInstaller can run
- *     `codeql pack install` to fetch their CodeQL library dependencies.
- *  2. Provides a fallback entry point if the bundled server is missing.
+ * When the extension is installed from a VSIX, the `vscode:prepublish`
+ * step bundles `server/dist/`, `server/ql/`, and `server/package.json`
+ * inside the extension root. In that case no npm install is needed —
+ * the VSIX is fully self-contained.
  *
- * The MCP server is launched from the **bundled** copy inside the VSIX
- * (`server/dist/codeql-development-mcp-server.js`) so the extension is
- * fully self-contained. Override via `codeql-mcp.serverCommand` /
- * `codeql-mcp.serverArgs` settings for local development.
+ * A local npm install into `globalStorage` is performed **only** as a
+ * fallback when the bundled server is missing (e.g. running from the
+ * Extension Development Host without a prepublish build). Override via
+ * `codeql-mcp.serverCommand` / `codeql-mcp.serverArgs` settings for
+ * local development.
  */
 export class ServerManager extends DisposableObject {
   private readonly storageRoot: string;
@@ -90,19 +90,54 @@ export class ServerManager extends DisposableObject {
   }
 
   /**
-   * Ensure the npm package is installed locally.
-   * Returns `true` if a fresh install was performed.
+   * Get the extension's own version from its packageJSON.
+   *
+   * This is the version baked into the VSIX and is used to determine
+   * whether the locally installed npm package is still up-to-date.
+   */
+  getExtensionVersion(): string {
+    return this.context.extension.packageJSON.version as string;
+  }
+
+  /**
+   * Ensure the npm package is available locally.
+   *
+   * When the VSIX bundle is present (the normal installed case), no npm
+   * install is needed — the bundle already ships `server/dist/`,
+   * `server/ql/`, and `server/package.json`. Returns `false` immediately.
+   *
+   * When the bundle is missing (Extension Development Host without a
+   * prepublish build), falls back to npm-installing the package into
+   * `globalStorage`. Returns `true` if a fresh install was performed.
    */
   async ensureInstalled(): Promise<boolean> {
+    // VSIX bundle is self-contained — no npm install required.
+    if (this.getBundledQlRoot()) {
+      this.logger.info(
+        `Using VSIX-bundled server (v${this.getExtensionVersion()}). ` +
+        'No npm install required.',
+      );
+      return false;
+    }
+
+    // Fallback: no bundle — install via npm.
+    this.logger.info(
+      'Bundled server not found — falling back to npm install...',
+    );
     const config = vscode.workspace.getConfiguration('codeql-mcp');
     const targetVersion = config.get<string>('serverVersion', 'latest');
 
     if (await this.isInstalled()) {
       const current = await this.getInstalledVersion();
-      if (targetVersion === 'latest' || current === targetVersion) {
+      const effectiveTarget =
+        targetVersion === 'latest' ? this.getExtensionVersion() : targetVersion;
+      if (current === effectiveTarget) {
         this.logger.info(`MCP server package already installed (v${current}).`);
         return false;
       }
+      this.logger.info(
+        `Installed npm package (v${current}) differs from target (v${effectiveTarget}) — upgrading...`,
+      );
     }
 
     await this.install({ version: targetVersion });
@@ -128,6 +163,34 @@ export class ServerManager extends DisposableObject {
   // Server launch configuration (for McpProvider)
   // ---------------------------------------------------------------------------
 
+  /**
+   * Root of the bundled `server/` directory inside the VSIX.
+   *
+   * In VSIX layout the `vscode:prepublish` step copies `server/dist/`,
+   * `server/ql/`, and `server/package.json` into the extension so the VSIX
+   * is self-contained. Returns the path to that `server/` directory, or
+   * `undefined` if the bundle is missing (local dev without a prepublish
+   * build).
+   */
+  getBundledQlRoot(): string | undefined {
+    const extensionRoot = this.context.extensionUri.fsPath;
+    const candidate = join(extensionRoot, 'server');
+    try {
+      accessSync(join(candidate, 'package.json'), constants.R_OK);
+      return candidate;
+    } catch {
+      // Not in VSIX layout — check monorepo
+    }
+
+    const monorepo = join(extensionRoot, '..', '..', 'server');
+    try {
+      accessSync(join(monorepo, 'package.json'), constants.R_OK);
+      return monorepo;
+    } catch {
+      return undefined;
+    }
+  }
+
   /**
    * Absolute path to the MCP server entry point.
    *
diff --git a/extensions/vscode/test/server/pack-installer.test.ts b/extensions/vscode/test/server/pack-installer.test.ts
@@ -22,8 +22,9 @@ function createMockCliResolver() {
   } as any;
 }
 
-function createMockServerManager() {
+function createMockServerManager(bundledQlRoot?: string) {
   return {
+    getBundledQlRoot: vi.fn().mockReturnValue(bundledQlRoot ?? undefined),
     getPackageRoot: vi.fn().mockReturnValue('/mock/global-storage/mcp-server/node_modules/codeql-development-mcp-server'),
     getInstallDir: vi.fn().mockReturnValue('/mock/global-storage/mcp-server'),
     getCommand: vi.fn().mockReturnValue('npx'),
@@ -70,7 +71,7 @@ describe('PackInstaller', () => {
     expect(languages).toHaveLength(9);
   });
 
-  it('should resolve qlpack paths under the package root', () => {
+  it('should resolve qlpack paths under the npm package root when no bundle', () => {
     const paths = installer.getQlpackPaths();
     expect(paths).toHaveLength(9);
     for (const p of paths) {
@@ -79,6 +80,23 @@ describe('PackInstaller', () => {
     }
   });
 
+  it('should prefer bundled ql root when VSIX bundle exists', () => {
+    const bundledManager = createMockServerManager('/mock/extension/server');
+    const bundledInstaller = new PackInstaller(
+      cliResolver,
+      bundledManager,
+      logger,
+    );
+    const paths = bundledInstaller.getQlpackPaths();
+    expect(paths).toHaveLength(9);
+    for (const p of paths) {
+      expect(p).toMatch(/^\/mock\/extension\/server\/ql\//);
+      expect(p).toContain('/tools/src');
+    }
+    // Should NOT have used npm package root
+    expect(bundledManager.getPackageRoot).not.toHaveBeenCalled();
+  });
+
   it('should skip installation when CLI is not found', async () => {
     cliResolver.resolve.mockResolvedValue(undefined);
 
diff --git a/extensions/vscode/test/server/server-manager.test.ts b/extensions/vscode/test/server/server-manager.test.ts
