Dual ESM/CJS build for CommonJS compatibility (#528)

Produce both ESM and CJS outputs from the esbuild config so that
consumers using either module system get a working package automatically.

- Add a second esbuild.build() call with format:"cjs" outputting to dist/cjs/
- Write a dist/cjs/package.json with type:"commonjs" so Node treats .js as CJS
- Update package.json exports with "import" and "require" conditions for both
  the main and ./extension entry points
- Revert getBundledCliPath() to use import.meta.resolve for ESM, with a
  createRequire + path-walking fallback for CJS contexts
- Update CJS compatibility tests to verify the actual dual build
- Update README to document CJS/CommonJS support

Co-Authored-By: Copilot <[email protected]>

Author: SteveSandersonMS

nodejs/README.md

@@ -850,13 +850,18 @@ try {
 - Node.js >= 18.0.0
 - GitHub Copilot CLI installed and in PATH (or provide custom `cliPath`)
 
-### CJS Bundles (esbuild, VS Code extensions)
+### CJS / CommonJS Support
 
-The SDK is ESM-only. When loaded in a CJS-shimmed environment (e.g., a VS Code extension bundled with `esbuild format:"cjs"`), `getBundledCliPath()` resolves the CLI by walking `node_modules`. The `@github/copilot` package **must be present in `node_modules` at runtime** — do not externalize or exclude it from your bundle.
+The SDK ships both ESM and CJS builds. Node.js and bundlers (esbuild, webpack, etc.) automatically select the correct format via the `exports` field in `package.json`:
+
+- `import` / `from` → ESM (`dist/index.js`)
+- `require()` → CJS (`dist/cjs/index.cjs`)
+
+This means the SDK works out of the box in CJS environments such as VS Code extensions bundled with `esbuild format:"cjs"`.
 
 ### System-installed CLI (winget, brew, apt)
 
-If you installed the Copilot CLI separately rather than relying on the SDK's bundled copy, `getBundledCliPath()` will not find it (it only searches `node_modules`). Pass `cliPath` explicitly instead:
+If you installed the Copilot CLI separately rather than relying on the SDK's bundled copy, pass `cliPath` explicitly:
 
 ```typescript
 const client = new CopilotClient({

nodejs/esbuild-copilotsdk-nodejs.ts

@@ -4,6 +4,7 @@ import { execSync } from "child_process";
 
 const entryPoints = globSync("src/**/*.ts");
 
+// ESM build
 await esbuild.build({
     entryPoints,
     outbase: "src",
@@ -15,5 +16,21 @@ await esbuild.build({
     outExtension: { ".js": ".js" },
 });
 
+// CJS build — uses .js extension with a "type":"commonjs" package.json marker
+await esbuild.build({
+    entryPoints,
+    outbase: "src",
+    outdir: "dist/cjs",
+    format: "cjs",
+    platform: "node",
+    target: "es2022",
+    sourcemap: false,
+    outExtension: { ".js": ".js" },
+});
+
+// Mark the CJS directory so Node treats .js files as CommonJS
+import { writeFileSync } from "fs";
+writeFileSync("dist/cjs/package.json", JSON.stringify({ type: "commonjs" }) + "\n");
+
 // Generate .d.ts files
 execSync("tsc", { stdio: "inherit" });

nodejs/package.json

@@ -6,16 +6,28 @@
   },
   "version": "0.1.8",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./extension": {
-      "import": "./dist/extension.js",
-      "types": "./dist/extension.d.ts"
+      "import": {
+        "types": "./dist/extension.d.ts",
+        "default": "./dist/extension.js"
+      },
+      "require": {
+        "types": "./dist/extension.d.ts",
+        "default": "./dist/cjs/extension.js"
+      }
     }
   },
   "type": "module",

nodejs/src/client.ts

@@ -17,7 +17,7 @@ import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { Socket } from "node:net";
 import { dirname, join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import {
     createMessageConnection,
     MessageConnection,
@@ -93,27 +93,33 @@ function getNodeExecPath(): string {
  * Gets the path to the bundled CLI from the @github/copilot package.
  * Uses index.js directly rather than npm-loader.js (which spawns the native binary).
  *
- * The @github/copilot package only exposes an ESM-only "./sdk" export,
- * which breaks in CJS contexts (e.g., VS Code extensions bundled with esbuild).
- * Instead of resolving through the package's exports, we locate the package
- * root by walking module resolution paths and checking for its directory.
- * See: https://github.com/github/copilot-sdk/issues/528
+ * In ESM, uses import.meta.resolve directly. In CJS (e.g., VS Code extensions
+ * bundled with esbuild format:"cjs"), import.meta is empty so we fall back to
+ * walking node_modules to find the package.
  */
 function getBundledCliPath(): string {
-    // import.meta.url is defined in ESM; in CJS bundles (esbuild format:"cjs")
-    // it's undefined, so we fall back to __filename via pathToFileURL.
-    const require = createRequire(import.meta.url ?? pathToFileURL(__filename).href);
-    // The @github/copilot package has strict ESM-only exports, so require.resolve
-    // cannot resolve it. Instead, walk the module resolution paths to find it.
-    const searchPaths = require.resolve.paths("@github/copilot") ?? [];
+    if (typeof import.meta.resolve === "function") {
+        // ESM: resolve via import.meta.resolve
+        const sdkUrl = import.meta.resolve("@github/copilot/sdk");
+        const sdkPath = fileURLToPath(sdkUrl);
+        // sdkPath is like .../node_modules/@github/copilot/sdk/index.js
+        // Go up two levels to get the package root, then append index.js
+        return join(dirname(dirname(sdkPath)), "index.js");
+    }
+
+    // CJS fallback: the @github/copilot package has ESM-only exports so
+    // require.resolve cannot reach it. Walk the module search paths instead.
+    const req = createRequire(__filename);
+    const searchPaths = req.resolve.paths("@github/copilot") ?? [];
     for (const base of searchPaths) {
         const candidate = join(base, "@github", "copilot", "index.js");
         if (existsSync(candidate)) {
             return candidate;
         }
     }
     throw new Error(
-        `Could not find @github/copilot package. Searched ${searchPaths.length} paths. Ensure it is installed.`
+        `Could not find @github/copilot package. Searched ${searchPaths.length} paths. ` +
+            `Ensure it is installed, or pass cliPath/cliUrl to CopilotClient.`,
     );
 }
 

nodejs/test/cjs-compat.test.ts

@@ -1,10 +1,8 @@
 /**
- * CJS shimmed environment compatibility test
+ * Dual ESM/CJS build compatibility tests
  *
- * Verifies that getBundledCliPath() works when the ESM build is loaded in a
- * shimmed CJS environment (e.g., VS Code extensions bundled with esbuild
- * format:"cjs"). In these environments, import.meta.url may be undefined but
- * __filename is available via the CJS shim.
+ * Verifies that both the ESM and CJS builds exist and work correctly,
+ * so consumers using either module system get a working package.
  *
  * See: https://github.com/github/copilot-sdk/issues/528
  */
@@ -14,30 +12,43 @@ import { existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 
-const esmEntryPoint = join(import.meta.dirname, "../dist/index.js");
+const distDir = join(import.meta.dirname, "../dist");
 
-describe("CJS shimmed environment compatibility (#528)", () => {
+describe("Dual ESM/CJS build (#528)", () => {
     it("ESM dist file should exist", () => {
-        expect(existsSync(esmEntryPoint)).toBe(true);
+        expect(existsSync(join(distDir, "index.js"))).toBe(true);
     });
 
-    it("getBundledCliPath() should resolve in a CJS shimmed context", () => {
-        // Simulate what esbuild format:"cjs" does: __filename is defined,
-        // import.meta.url may be undefined. The SDK's fallback logic
-        // (import.meta.url ?? pathToFileURL(__filename).href) handles this.
-        //
-        // We test by requiring the ESM build via --input-type=module in a
-        // subprocess that has __filename available, verifying the constructor
-        // (which calls getBundledCliPath()) doesn't throw.
+    it("CJS dist file should exist", () => {
+        expect(existsSync(join(distDir, "cjs/index.js"))).toBe(true);
+    });
+
+    it("CJS build is requireable and exports CopilotClient", () => {
         const script = `
-            import { createRequire } from 'node:module';
-            const require = createRequire(import.meta.url);
-            const sdk = await import(${JSON.stringify(esmEntryPoint)});
+            const sdk = require(${JSON.stringify(join(distDir, "cjs/index.js"))});
             if (typeof sdk.CopilotClient !== 'function') {
+                console.error('CopilotClient is not a function');
                 process.exit(1);
             }
+            console.log('CJS require: OK');
+        `;
+        const output = execFileSync(
+            process.execPath,
+            ["--eval", script],
+            {
+                encoding: "utf-8",
+                timeout: 10000,
+                cwd: join(import.meta.dirname, ".."),
+            },
+        );
+        expect(output).toContain("CJS require: OK");
+    });
+
+    it("CopilotClient constructor works in CJS context", () => {
+        const script = `
+            const sdk = require(${JSON.stringify(join(distDir, "cjs/index.js"))});
             try {
-                const client = new sdk.CopilotClient({ cliUrl: "8080" });
+                const client = new sdk.CopilotClient({ cliUrl: "http://localhost:8080" });
                 console.log('CopilotClient constructor: OK');
             } catch (e) {
                 console.error('constructor failed:', e.message);
@@ -46,7 +57,7 @@ describe("CJS shimmed environment compatibility (#528)", () => {
         `;
         const output = execFileSync(
             process.execPath,
-            ["--input-type=module", "--eval", script],
+            ["--eval", script],
             {
                 encoding: "utf-8",
                 timeout: 10000,