Add 'Connect to Actions Job Debugger' command

README.md

@@ -1,6 +1,8 @@
 # GitHub Actions for VS Code
 
 > **🐛 Actions Job Debugger (Preview):** To try the latest debugger build, download the `.vsix` artifact from the most recent [Build Debugger Extension](https://github.com/github/vscode-github-actions/actions/workflows/debugger-build.yml) workflow run. On the workflow run page, scroll to **Artifacts** and download **vscode-github-actions-debugger**. Then install it in VS Code by running `code --install-extension <path-to-downloaded.vsix>` or via the Extensions view → `⋯` menu → **Install from VSIX…**.
+>
+> Once installed, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run **GitHub Actions: Connect to Actions Job Debugger…**. Paste the `wss://` tunnel URL from a debug-mode job and the extension will open a full debug session using your current GitHub credentials.
 
 The GitHub Actions extension lets you manage your workflows, view the workflow run history, and helps with authoring workflows.
 

package.json

@@ -25,6 +25,8 @@
   "activationEvents": [
     "onView:workflows",
     "onView:settings",
+    "onDebugResolve:github-actions-job",
+    "onCommand:github-actions.debugger.connect",
     "workspaceContains:**/.github/workflows/**",
     "workspaceContains:**/action.yml",
     "workspaceContains:**/action.yaml"
@@ -97,7 +99,19 @@
         }
       }
     },
+    "debuggers": [
+      {
+        "type": "github-actions-job",
+        "label": "GitHub Actions Job Debugger",
+        "languages": []
+      }
+    ],
     "commands": [
+      {
+        "command": "github-actions.debugger.connect",
+        "category": "GitHub Actions",
+        "title": "Connect to Actions Job Debugger..."
+      },
       {
         "command": "github-actions.explorer.refresh",
         "category": "GitHub Actions",
@@ -544,6 +558,7 @@
     "@types/libsodium-wrappers": "^0.7.10",
     "@types/uuid": "^3.4.6",
     "@types/vscode": "^1.72.0",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^5.40.0",
     "@typescript-eslint/parser": "^5.40.0",
     "@vscode/test-web": "^0.0.69",
@@ -579,7 +594,8 @@
     "tunnel": "0.0.6",
     "util": "^0.12.1",
     "uuid": "^3.3.3",
-    "vscode-languageclient": "^8.0.2"
+    "vscode-languageclient": "^8.0.2",
+    "ws": "^8.20.0"
   },
   "overrides": {
     "browserify-sign": {

src/debugger/debugger.ts

@@ -0,0 +1,181 @@
+import * as crypto from "crypto";
+import * as vscode from "vscode";
+import {getSession, newSession} from "../auth/auth";
+import {log, logDebug, logError} from "../log";
+import {validateTunnelUrl} from "./tunnelUrl";
+import {WebSocketDapAdapter} from "./webSocketDapAdapter";
+
+/** The custom debug type registered in package.json contributes.debuggers. */
+export const DEBUG_TYPE = "github-actions-job";
+
+/**
+ * Extension-private store for auth tokens, keyed by a one-time session
+ * nonce. Tokens are never placed in DebugConfiguration (which is readable
+ * by other extensions via vscode.debug.activeDebugSession.configuration).
+ */
+const pendingTokens = new Map<string, string>();
+
+/**
+ * Registers the Actions Job Debugger command and debug adapter factory.
+ *
+ * Contributes:
+ * - A command-palette command that prompts for a tunnel URL and starts a debug session.
+ * - A DebugAdapterDescriptorFactory that returns an inline DAP-over-WS adapter.
+ */
+export function registerDebugger(context: vscode.ExtensionContext): void {
+  // Register the inline adapter factory for our debug type.
+  context.subscriptions.push(
+    vscode.debug.registerDebugAdapterDescriptorFactory(DEBUG_TYPE, new ActionsDebugAdapterFactory())
+  );
+
+  // Register a tracker to log all DAP traffic for diagnostics.
+  context.subscriptions.push(
+    vscode.debug.registerDebugAdapterTrackerFactory(DEBUG_TYPE, new ActionsDebugTrackerFactory())
+  );
+
+  // Register the connect command.
+  context.subscriptions.push(
+    vscode.commands.registerCommand("github-actions.debugger.connect", () => connectToDebugger())
+  );
+}
+
+async function connectToDebugger(): Promise<void> {
+  // 1. Prompt for the tunnel URL.
+  const rawUrl = await vscode.window.showInputBox({
+    title: "Connect to Actions Job Debugger",
+    prompt: "Enter the debugger tunnel URL (wss://…)",
+    placeHolder: "wss://xxxx-4711.region.devtunnels.ms/",
+    ignoreFocusOut: true,
+    validateInput: input => {
+      if (!input) {
+        return "A tunnel URL is required";
+      }
+      const result = validateTunnelUrl(input);
+      return result.valid ? null : result.reason;
+    }
+  });
+
+  if (!rawUrl) {
+    return; // user cancelled
+  }
+
+  const validation = validateTunnelUrl(rawUrl);
+  if (!validation.valid) {
+    void vscode.window.showErrorMessage(`Invalid tunnel URL: ${validation.reason}`);
+    return;
+  }
+
+  // 2. Acquire a GitHub auth session. The token is used as a Bearer token
+  //    against the Dev Tunnel relay, which accepts VS Code's GitHub app tokens.
+  //    Try silently first; fall back to prompting for sign-in if needed.
+  let session = await getSession();
+  if (!session) {
+    try {
+      session = await newSession("Sign in to GitHub to connect to the Actions job debugger.");
+    } catch {
+      void vscode.window.showErrorMessage(
+        "GitHub authentication is required to connect to the Actions job debugger. Please sign in and try again."
+      );
+      return;
+    }
+  }
+
+  // 3. Launch the debug session. The token is stored in extension-private
+  //    memory (not in the configuration) to avoid exposing it to other extensions.
+  const nonce = crypto.randomBytes(16).toString("hex");
+  pendingTokens.set(nonce, session.accessToken);
+
+  const config: vscode.DebugConfiguration = {
+    type: DEBUG_TYPE,
+    name: "Actions Job Debugger",
+    request: "attach",
+    tunnelUrl: validation.url,
+    __tokenNonce: nonce
+  };
+
+  log(`Starting debug session for ${validation.url}`);
+
+  try {
+    const started = await vscode.debug.startDebugging(undefined, config);
+    if (!started) {
+      void vscode.window.showErrorMessage(
+        "Failed to start the debug session. Check the GitHub Actions output for details."
+      );
+    }
+  } finally {
+    // Clean up if the factory hasn't consumed the token yet
+    pendingTokens.delete(nonce);
+  }
+}
+
+class ActionsDebugAdapterFactory implements vscode.DebugAdapterDescriptorFactory {
+  async createDebugAdapterDescriptor(session: vscode.DebugSession): Promise<vscode.DebugAdapterDescriptor> {
+    const tunnelUrl = session.configuration.tunnelUrl as string | undefined;
+    const nonce = session.configuration.__tokenNonce as string | undefined;
+    const token = nonce ? pendingTokens.get(nonce) : undefined;
+
+    // Consume the token immediately so it cannot be replayed.
+    if (nonce) {
+      pendingTokens.delete(nonce);
+    }
+
+    if (!tunnelUrl || !token) {
+      throw new Error(
+        "Missing tunnel URL or authentication token. Use the 'Connect to Actions Job Debugger' command to start a session."
+      );
+    }
+
+    // Re-validate the tunnel URL as defense-in-depth
+    const revalidation = validateTunnelUrl(tunnelUrl);
+    if (!revalidation.valid) {
+      throw new Error(`Invalid debugger tunnel URL: ${revalidation.reason}`);
+    }
+
+    const adapter = new WebSocketDapAdapter(tunnelUrl, token);
+
+    try {
+      await adapter.connect();
+    } catch (e) {
+      adapter.dispose();
+      const msg = (e as Error).message;
+      logError(e as Error, "Failed to connect debugger adapter");
+      throw new Error(`Could not connect to the debugger tunnel: ${msg}`);
+    }
+
+    return new vscode.DebugAdapterInlineImplementation(adapter);
+  }
+}
+
+class ActionsDebugTrackerFactory implements vscode.DebugAdapterTrackerFactory {
+  createDebugAdapterTracker(): vscode.DebugAdapterTracker {
+    return {
+      onWillReceiveMessage(message: unknown) {
+        const m = message as Record<string, unknown>;
+        logDebug(
+          `[tracker] VS Code → DA: ${String(m.type)}${m.command ? `:${String(m.command)}` : ""} (seq ${String(m.seq)})`
+        );
+      },
+      onDidSendMessage(message: unknown) {
+        const m = message as Record<string, unknown>;
+        const body = m.body as Record<string, unknown> | undefined;
+        let detail = String(m.type);
+        if (m.command) {
+          detail += `:${String(m.command)}`;
+        }
+        if (m.event) {
+          detail += `:${String(m.event)}`;
+        }
+        if (m.event === "stopped" && body) {
+          detail += ` threadId=${String(body.threadId)} allThreadsStopped=${String(body.allThreadsStopped)}`;
+        }
+        logDebug(`[tracker] DA → VS Code: ${detail} (seq ${String(m.seq)})`);
+      },
+      onError(error: Error) {
+        logError(error, "[tracker] DAP error");
+      },
+      onExit(code: number | undefined, signal: string | undefined) {
+        log(`[tracker] DAP session exited: code=${String(code)} signal=${String(signal)}`);
+      }
+    };
+  }
+}