feat: add extension API for debug terminal contributions (#2136)

This should help the Bun folks work nicely with the js-debug terminal: oven-sh/bun#15223

Author: connor4312

CDP_SHARE.md renamed to EXTENSION_AUTHORS.md

@@ -1,20 +1,39 @@
-# CDP Sharing Mechanism
+# Extensibility
+
+js-debug has a few ways other extensions can 'plug into' js-debug and provide additional extensibility.
+
+## Extension API
+
+js-debug provides an extension API you can use to do certain things. Please refer to [the typings](https://github.com/microsoft/vscode-js-debug/blob/main/src/typings/vscode-js-debug.d.ts) for capabilities.
+
+To use this, you would:
+
+1. Add a step in your build process to download the typings from https://github.com/microsoft/vscode-js-debug/blob/main/src/typings/vscode-js-debug.d.ts to somewhere in your source tree.
+2. Access the API like so:
+
+   ```js
+   const jsDebugExt = vscode.extensions.getExtension('ms-vscode.js-debug-nightly') || vscode.extensions.getExtension('ms-vscode.js-debug');
+   await jsDebugExt.activate()
+   const jsDebug: import('@vscode/js-debug').IExports = jsDebugExt.exports;
+   ```
+
+## CDP Sharing Mechanism
 
 This file documents the CDP sharing mechanism in js-debug. It can be useful for advanced extensions and plugins. The original feature request can be found in [#892](https://github.com/microsoft/vscode-js-debug/issues/893).
 
-## Requesting a CDP Connection
+### Requesting a CDP Connection
 
 js-debug can be asked to share its CDP connection by running the `extension.js-debug.requestCDPProxy` command with the debug session ID you wish to connect to. js-debug will respond with an object containing a WebSocket server address in the form `{ host: string, port: string }`. You can see a sample extension that requests this information [here](https://github.com/connor4312/cdp-proxy-requestor/blob/main/extension.js).
 
 Note that the server will always be running in the workspace. If you have a UI extension, you may need to forward the port. We also recommend using `permessage-deflate` on the WebSocket for better performance over remote connections.
 
-## Protocol
+### Protocol
 
 The protocol spoken over the WebSocket is, unsurprisingly, CDP. Over the websocket, the `sessionId` will never be used and will always be ignored. This is because a single js-debug debug session corresponds to exactly one CDP session. Other targets--like iframes, workers, and subprocesses--are represented as separate debug sessions which you can connect to separately.
 
 Additionally, by default, you will not receive any CDP events on the socket. This is because the underlying CDP connection is shared between js-debug and consumers of the mechanism, and we want to avoid doing extra work to send events you don't care about. To listen to events, you can use the JsDebug domain:
 
-### JsDebug domain
+#### JsDebug domain
 
 js-debug exposes a `JsDebug` CDP domain for meta-communication. For example, you would call the method `JsDebug.subscribe` to subscribe to evetns.
 

src/extension.ts

@@ -2,6 +2,7 @@
  * Copyright (C) Microsoft Corporation. All rights reserved.
  *--------------------------------------------------------*/
 
+import { IExports } from '@vscode/js-debug';
 import * as l10n from '@vscode/l10n';
 import { tmpdir } from 'os';
 import * as vscode from 'vscode';
@@ -23,14 +24,15 @@ import { registerCustomBreakpointsUI } from './ui/customBreakpointsUI';
 import { debugNpmScript } from './ui/debugNpmScript';
 import { DebugSessionTracker } from './ui/debugSessionTracker';
 import { registerDebugTerminalUI } from './ui/debugTerminalUI';
+import { ExtensionApiFactory } from './ui/extensionApi';
 import { attachProcess, pickProcess } from './ui/processPicker';
 import { registerProfilingCommand } from './ui/profiling';
 import { registerRequestCDPProxy } from './ui/requestCDPProxy';
 import { registerRevealPage } from './ui/revealPage';
 import { toggleSkippingFile } from './ui/toggleSkippingFile';
 import { VSCodeSessionManager } from './ui/vsCodeSessionManager';
 
-export function activate(context: vscode.ExtensionContext) {
+export function activate(context: vscode.ExtensionContext): IExports {
   if (vscode.l10n.bundle) {
     l10n.config({ contents: vscode.l10n.bundle });
   }
@@ -101,6 +103,8 @@ export function activate(context: vscode.ExtensionContext) {
   registerRevealPage(context, debugSessionTracker);
   registerRequestCDPProxy(context, debugSessionTracker);
   services.getAll<IExtensionContribution>(IExtensionContribution).forEach(c => c.register(context));
+
+  return services.get(ExtensionApiFactory).create();
 }
 
 export function deactivate() {

src/ioc-extras.ts

@@ -134,3 +134,8 @@ export interface IExtensionContribution {
 }
 
 export const IExtensionContribution = Symbol('IExtensionContribution');
+
+/**
+ * Binding to a Set<IDebugTerminalOptionsProvider>.
+ */
+export const IDebugTerminalOptionsProviders = Symbol('IDebugTerminalOptionsProviders');

src/targets/node/terminalNodeLauncher.ts

@@ -2,6 +2,7 @@
  * Copyright (C) Microsoft Corporation. All rights reserved.
  *--------------------------------------------------------*/
 
+import { IDebugTerminalOptionsProvider } from '@vscode/js-debug';
 import { randomBytes } from 'crypto';
 import { inject, injectable, optional } from 'inversify';
 import { tmpdir } from 'os';
@@ -16,7 +17,7 @@ import { ITerminalLinkProvider } from '../../common/terminalLinkProvider';
 import { AnyLaunchConfiguration, ITerminalLaunchConfiguration } from '../../configuration';
 import { ErrorCodes } from '../../dap/errors';
 import { ProtocolError } from '../../dap/protocolError';
-import { FS, FsPromises } from '../../ioc-extras';
+import { FS, FsPromises, IDebugTerminalOptionsProviders } from '../../ioc-extras';
 import { ISourcePathResolverFactory } from '../sourcePathResolverFactory';
 import { IStopMetadata, ITarget } from '../targets';
 import { hideDebugInfoFromConsole, INodeBinaryProvider, NodeBinary } from './nodeBinaryProvider';
@@ -78,6 +79,9 @@ export class TerminalNodeLauncher extends NodeLauncherBase<ITerminalLaunchConfig
     @inject(FS) private readonly fs: FsPromises,
     @inject(ISourcePathResolverFactory) pathResolverFactory: ISourcePathResolverFactory,
     @inject(IPortLeaseTracker) portLeaseTracker: IPortLeaseTracker,
+    @inject(IDebugTerminalOptionsProviders) private readonly optionsProviders: ReadonlySet<
+      IDebugTerminalOptionsProvider
+    >,
     @optional()
     @inject(ITerminalLinkProvider)
     private readonly terminalLinkProvider: ITerminalLinkProvider | undefined,
@@ -134,13 +138,22 @@ export class TerminalNodeLauncher extends NodeLauncherBase<ITerminalLaunchConfig
       fileCallback: this.callbackFile,
     });
 
-    const terminal = await this.createTerminal({
+    let options: vscode.TerminalOptions = {
       name: runData.params.name,
       cwd: runData.params.cwd,
       iconPath: new vscode.ThemeIcon('debug'),
       env: hideDebugInfoFromConsole(binary, env).defined(),
       isTransient: true,
-    });
+    };
+
+    for (const provider of this.optionsProviders) {
+      const result = await provider.provideTerminalOptions(options);
+      if (result) {
+        options = result;
+      }
+    }
+
+    const terminal = await this.createTerminal(options);
     this.terminalLinkProvider?.enableHandlingInTerminal(terminal);
     this.terminalCreatedEmitter.fire(terminal);
 

src/typings/vscode-js-debug.d.ts

@@ -0,0 +1,39 @@
+/*---------------------------------------------------------
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------*/
+
+declare module '@vscode/js-debug' {
+  import * as vscode from 'vscode';
+
+  /** @see {IExports.registerDebugTerminalOptionsProvider} */
+  export interface IDebugTerminalOptionsProvider {
+    /**
+     * Called when the user creates a JavaScript Debug Terminal. It's called
+     * with the options js-debug wants to use to create the terminal. It should
+     * modify and return the options to use in the terminal.
+     *
+     * In order to avoid conflicting with existing logic, participants should
+     * try to modify options in a additive way. For example prefer appending
+     * to rather than reading and overwriting `options.env.PATH`.
+     */
+    provideTerminalOptions(options: vscode.TerminalOptions): vscode.ProviderResult<vscode.TerminalOptions>;
+  }
+
+  /**
+   * Defines the exports of the `js-debug` extension. Once you have this typings
+   * file, these can be acquired in your extension using the following code:
+   *
+   * ```
+   * const jsDebugExt = vscode.extensions.getExtension('ms-vscode.js-debug-nightly')
+   *   || vscode.extensions.getExtension('ms-vscode.js-debug');
+   * await jsDebugExt.activate()
+   * const jsDebug: import('@vscode/js-debug').IExports = jsDebug.exports;
+   * ```
+   */
+  export interface IExports {
+    /**
+     * Registers a participant used when the user creates a JavaScript Debug Terminal.
+     */
+    registerDebugTerminalOptionsProvider(provider: IDebugTerminalOptionsProvider): vscode.Disposable;
+  }
+}

src/ui/debugTerminalUI.ts

@@ -24,7 +24,7 @@ import {
   terminalBaseDefaults,
 } from '../configuration';
 import { createPendingDapApi } from '../dap/pending-api';
-import { FS } from '../ioc-extras';
+import { FS, IDebugTerminalOptionsProviders } from '../ioc-extras';
 import { DelegateLauncherFactory } from '../targets/delegate/delegateLauncherFactory';
 import { NodeBinaryProvider } from '../targets/node/nodeBinaryProvider';
 import { noPackageJsonProvider } from '../targets/node/packageJsonProvider';
@@ -216,6 +216,7 @@ export function registerDebugTerminalUI(
       services.get(FS),
       services.get(NodeOnlyPathResolverFactory),
       services.get(IPortLeaseTracker),
+      services.get(IDebugTerminalOptionsProviders),
       services.get(ITerminalLinkProvider),
     );
 
@@ -306,6 +307,7 @@ export function registerDebugTerminalUI(
               services.get(FS),
               services.get(NodeOnlyPathResolverFactory),
               services.get(IPortLeaseTracker),
+              services.get(IDebugTerminalOptionsProviders),
               services.get(ITerminalLinkProvider),
             );
 

src/ui/extensionApi.ts

@@ -0,0 +1,25 @@
+/*---------------------------------------------------------
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------*/
+
+import type { IDebugTerminalOptionsProvider, IExports } from '@vscode/js-debug';
+import { inject, injectable } from 'inversify';
+import { IDebugTerminalOptionsProviders } from '../ioc-extras';
+
+@injectable()
+export class ExtensionApiFactory {
+  constructor(
+    @inject(IDebugTerminalOptionsProviders) private readonly debugTerminalOptionsProviders: Set<
+      IDebugTerminalOptionsProvider
+    >,
+  ) {}
+
+  public create(): IExports {
+    return {
+      registerDebugTerminalOptionsProvider: provider => {
+        this.debugTerminalOptionsProviders.add(provider);
+        return { dispose: () => this.debugTerminalOptionsProviders.delete(provider) };
+      },
+    };
+  }
+}

src/ui/ui-ioc.extensionOnly.ts

@@ -6,7 +6,12 @@ import { Container } from 'inversify';
 import { IDwarfModuleProvider } from '../adapter/dwarf/dwarfModuleProvider';
 import { IRequestOptionsProvider } from '../adapter/resourceProvider/requestOptionsProvider';
 import { ITerminalLinkProvider } from '../common/terminalLinkProvider';
-import { IExtensionContribution, trackDispose, VSCodeApi } from '../ioc-extras';
+import {
+  IDebugTerminalOptionsProviders,
+  IExtensionContribution,
+  trackDispose,
+  VSCodeApi,
+} from '../ioc-extras';
 import { TerminalNodeLauncher } from '../targets/node/terminalNodeLauncher';
 import { ILauncher } from '../targets/targets';
 import { IExperimentationService } from '../telemetry/experimentationService';
@@ -25,6 +30,7 @@ import { DisableSourceMapUI } from './disableSourceMapUI';
 import { DwarfModuleProvider } from './dwarfModuleProviderImpl';
 import { EdgeDevToolOpener } from './edgeDevToolOpener';
 import { ExcludedCallersUI } from './excludedCallersUI';
+import { ExtensionApiFactory } from './extensionApi';
 import { LaunchJsonCompletions } from './launchJsonCompletions';
 import { ILinkedBreakpointLocation } from './linkedBreakpointLocation';
 import { LinkedBreakpointLocationUI } from './linkedBreakpointLocationUI';
@@ -95,6 +101,11 @@ export const registerUiComponents = (container: Container) => {
     .bind(ITerminationConditionFactory)
     .to(BreakpointTerminationConditionFactory)
     .inSingletonScope();
+
+  container.bind(IDebugTerminalOptionsProviders)
+    .toConstantValue(new Set());
+
+  container.bind(ExtensionApiFactory).toSelf().inSingletonScope();
 };
 
 export const registerTopLevelSessionComponents = (container: Container) => {