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": "Debug Running Job…"
+      },
       {
         "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,206 @@
+import * as crypto from "crypto";
+import * as vscode from "vscode";
+import {getClient} from "../api/api";
+import {getSession, newSession} from "../auth/auth";
+import {getGitHubApiUri} from "../configuration/configuration";
+import {log, logDebug, logError} from "../log";
+import {parseJobUrl} from "./jobUrl";
+import {validateTunnelUrl} from "./tunnelUrl";
+import {WebSocketDapAdapter} from "./webSocketDapAdapter";
+
+export const DEBUG_TYPE = "github-actions-job";
+
+/**
+ * Extension-private token store keyed by one-time nonce. Tokens are never
+ * placed in DebugConfiguration (readable by other extensions).
+ */
+const pendingTokens = new Map<string, string>();
+
+export function registerDebugger(context: vscode.ExtensionContext): void {
+  context.subscriptions.push(
+    vscode.debug.registerDebugAdapterDescriptorFactory(DEBUG_TYPE, new ActionsDebugAdapterFactory())
+  );
+
+  context.subscriptions.push(
+    vscode.debug.registerDebugAdapterTrackerFactory(DEBUG_TYPE, new ActionsDebugTrackerFactory())
+  );
+
+  context.subscriptions.push(
+    vscode.commands.registerCommand("github-actions.debugger.connect", () => connectToDebugger())
+  );
+}
+
+async function connectToDebugger(): Promise<void> {
+  const rawUrl = await vscode.window.showInputBox({
+    title: "Connect to Actions Job Debugger",
+    prompt: "Paste the URL of the Actions job to debug",
+    placeHolder: "https://github.com/owner/repo/actions/runs/123/job/456",
+    ignoreFocusOut: true,
+    validateInput: input => {
+      if (!input) {
+        return "A job URL is required";
+      }
+      const result = parseJobUrl(input, getGitHubApiUri());
+      return result.valid ? null : result.reason;
+    }
+  });
+
+  if (!rawUrl) {
+    return;
+  }
+
+  const parsed = parseJobUrl(rawUrl, getGitHubApiUri());
+  if (!parsed.valid) {
+    void vscode.window.showErrorMessage(`Invalid job URL: ${parsed.reason}`);
+    return;
+  }
+
+  // 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;
+    }
+  }
+
+  const token = session.accessToken;
+  let debuggerUrl: string;
+  try {
+    debuggerUrl = await vscode.window.withProgress(
+      {location: vscode.ProgressLocation.Notification, title: "Connecting to Actions job debugger…"},
+      async () => {
+        const octokit = getClient(token);
+        const response = await octokit.request("GET /repos/{owner}/{repo}/actions/jobs/{job_id}/debugger", {
+          owner: parsed.owner,
+          repo: parsed.repo,
+          job_id: parsed.jobId
+        });
+        return (response.data as {debugger_url: string}).debugger_url;
+      }
+    );
+  } catch (e) {
+    const status = (e as {status?: number}).status;
+    if (status === 404) {
+      void vscode.window.showErrorMessage(
+        "Debugger is not available for this job. Make sure the job is running with debugging enabled."
+      );
+    } else if (status === 403) {
+      void vscode.window.showErrorMessage(
+        "Permission denied. You may need to re-authenticate or check your access to this repository."
+      );
+    } else {
+      const msg = (e as Error).message || "Unknown error";
+      void vscode.window.showErrorMessage(`Failed to fetch debugger URL: ${msg}`);
+    }
+    return;
+  }
+
+  const validation = validateTunnelUrl(debuggerUrl);
+  if (!validation.valid) {
+    void vscode.window.showErrorMessage(`Invalid debugger URL returned by API: ${validation.reason}`);
+    return;
+  }
+
+  // Store token in extension-private memory (not in the config) to avoid
+  // exposing it to other extensions.
+  const nonce = crypto.randomBytes(16).toString("hex");
+  pendingTokens.set(nonce, token);
+
+  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 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."
+      );
+    }
+
+    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)}`);
+      }
+    };
+  }
+}