Add Java debugging support via DAP (java-debug.core)

Wraps Microsoft's java-debug.core library with lightweight providers
for source lookup and JDI-based evaluation. Supports launch, attach,
breakpoints, stepping, variable inspection, and exception pausing.

Architecture:
- src/dap/adapters/ — AdapterInstaller registry (lldb, java)
- src/dap/adapters/java/ — Java adapter sources (tarball bundled as Bun asset)
- DapSession runtime configs refactored from if/else chain to strategy pattern
- build.ts generates adapter tarball at build time (never committed)

Includes integration tests (launch, attach, limitations) gated on
adapter availability, and detects mvn/gradle as Java runtimes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: waltoss

.gitignore

@@ -36,3 +36,10 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 # C test fixture build artifacts
 tests/fixtures/c/hello
 tests/fixtures/c/*.dSYM
+
+# Java build artifacts
+*.class
+tests/fixtures/java/multi-package/out/
+
+# Generated at build time
+src/dap/adapters/java/adapter-sources.tar.gz

build.ts

@@ -0,0 +1,10 @@
+import { $ } from "bun";
+
+// Generate Java adapter sources tarball
+await $`tar czf src/dap/adapters/java/adapter-sources.tar.gz -C src/dap/adapters/java com/debugthat/adapter`;
+
+// Bundle
+await $`bun build src/main.ts --outdir dist --target=bun`;
+
+// Clean up generated tarball
+await $`rm src/dap/adapters/java/adapter-sources.tar.gz`;

package.json

@@ -32,7 +32,7 @@
   ],
   "scripts": {
     "dev": "bun run src/main.ts",
-    "build": "bun build src/main.ts --outdir dist --target=bun",
+    "build": "bun run build.ts",
     "test": "bun test tests/unit/ && bun test --concurrent tests/integration/",
     "lint": "biome check .",
     "format": "biome check --write .",
@@ -54,4 +54,4 @@
     "zod": "^4.0.0"
   },
   "module": "index.ts"
-}
+}

src/commands/install.ts

@@ -1,37 +1,9 @@
-import { existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync } from "node:fs";
 import { z } from "zod";
 import { defineCommand } from "../cli/command.ts";
+import { getAdapterInstaller, listAdapterNames } from "../dap/adapters/index.ts";
 import { getManagedAdaptersDir } from "../dap/session.ts";
 
-const LLVM_VERSION = "19.1.7";
-
-function getPlatformArch(): { os: string; arch: string } {
-	const os = process.platform; // "darwin", "linux", "win32"
-	const arch = process.arch; // "arm64", "x64"
-	return { os, arch };
-}
-
-function getLlvmDownloadUrl(version: string, os: string, arch: string): string | null {
-	if (os === "darwin") {
-		if (arch === "arm64") {
-			return `https://github.com/llvm/llvm-project/releases/download/llvmorg-${version}/LLVM-${version}-macOS-ARM64.tar.xz`;
-		}
-		if (arch === "x64") {
-			return `https://github.com/llvm/llvm-project/releases/download/llvmorg-${version}/LLVM-${version}-macOS-X64.tar.xz`;
-		}
-	}
-	if (os === "linux") {
-		if (arch === "x64") {
-			return `https://github.com/llvm/llvm-project/releases/download/llvmorg-${version}/LLVM-${version}-Linux-X64.tar.xz`;
-		}
-		if (arch === "arm64") {
-			return `https://github.com/llvm/llvm-project/releases/download/llvmorg-${version}/LLVM-${version}-Linux-AArch64.tar.xz`;
-		}
-	}
-	return null;
-}
-
 defineCommand({
 	name: "install",
 	description: "Download managed adapter binary",
@@ -44,6 +16,7 @@ defineCommand({
 	}),
 	handler: async (ctx) => {
 		const adapter = ctx.positional || undefined;
+		const supported = listAdapterNames();
 
 		if (ctx.flags.list) {
 			const dir = getManagedAdaptersDir();
@@ -65,124 +38,32 @@ defineCommand({
 
 		if (!adapter) {
 			console.error("Usage: dbg install <adapter>");
-			console.error("  Supported adapters: lldb");
+			console.error(`  Supported adapters: ${supported.join(", ")}`);
 			console.error("  Options: --list (show installed adapters)");
 			return 1;
 		}
 
-		if (adapter !== "lldb") {
+		const installer = getAdapterInstaller(adapter);
+		if (!installer) {
 			console.error(`Unknown adapter: ${adapter}`);
-			console.error("  Supported adapters: lldb");
+			console.error(`  Supported adapters: ${supported.join(", ")}`);
 			return 1;
 		}
 
-		const { os, arch } = getPlatformArch();
-		const url = getLlvmDownloadUrl(LLVM_VERSION, os, arch);
-
-		if (!url) {
-			console.error(`Unsupported platform: ${os}-${arch}`);
-			console.error("  Supported: darwin-arm64, darwin-x64, linux-x64, linux-arm64");
-			return 1;
-		}
-
-		const adaptersDir = getManagedAdaptersDir();
-		const targetPath = join(adaptersDir, "lldb-dap");
-
-		if (existsSync(targetPath)) {
-			console.log(`lldb-dap already installed at ${targetPath}`);
-			console.log(`  To reinstall, remove it first: rm ${targetPath}`);
+		if (installer.isInstalled()) {
+			console.log(`${installer.name} is already installed.`);
+			console.log("  To reinstall, remove ~/.debug-that/adapters/ entry first.");
 			return 0;
 		}
 
-		console.log(`Downloading LLVM ${LLVM_VERSION} for ${os}-${arch}...`);
-		console.log(`  From: ${url}`);
-
-		// Download the tarball
-		const response = await fetch(url, { redirect: "follow" });
-		if (!response.ok) {
-			console.error(`Download failed: HTTP ${response.status}`);
-			console.error("  -> Check your internet connection or try again later");
-			return 1;
-		}
-
-		const tarball = await response.arrayBuffer();
-		console.log(`Downloaded ${(tarball.byteLength / 1024 / 1024).toFixed(1)} MB`);
-
-		// Extract lldb-dap from the tarball using tar
-		mkdirSync(adaptersDir, { recursive: true });
-
-		const tmpTar = join(adaptersDir, "llvm-download.tar.xz");
-		await Bun.write(tmpTar, tarball);
-
-		// Find lldb-dap inside the archive and extract just that binary
-		console.log("Extracting lldb-dap...");
-		const listResult = Bun.spawnSync(["tar", "-tf", tmpTar], {
-			stdout: "pipe",
-		});
-		const files = listResult.stdout.toString().split("\n");
-		const lldbDapEntry = files.find((f) => f.endsWith("/bin/lldb-dap") || f === "bin/lldb-dap");
-
-		if (!lldbDapEntry) {
-			Bun.spawnSync(["rm", tmpTar]);
-			console.error("Could not find lldb-dap in the LLVM archive");
-			console.error(`  Archive entries searched: ${files.length}`);
-			console.error("  -> Try installing manually: brew install llvm");
-			return 1;
-		}
-
-		// Extract just the lldb-dap binary
-		const extractResult = Bun.spawnSync(
-			[
-				"tar",
-				"-xf",
-				tmpTar,
-				"-C",
-				adaptersDir,
-				"--strip-components",
-				String(lldbDapEntry.split("/").length - 1),
-				lldbDapEntry,
-			],
-			{ stdout: "pipe", stderr: "pipe" },
-		);
-
-		// Clean up tarball
-		Bun.spawnSync(["rm", tmpTar]);
-
-		if (extractResult.exitCode !== 0) {
-			console.error(`Extraction failed: ${extractResult.stderr.toString()}`);
-			return 1;
-		}
-
-		// Also extract liblldb if present (needed on some platforms)
-		const liblldbEntries = files.filter(
-			(f) => f.includes("liblldb") && (f.endsWith(".so") || f.endsWith(".dylib")),
-		);
-		for (const libEntry of liblldbEntries) {
-			Bun.spawnSync(
-				[
-					"tar",
-					"-xf",
-					tmpTar,
-					"-C",
-					adaptersDir,
-					"--strip-components",
-					String(libEntry.split("/").length - 1),
-					libEntry,
-				],
-				{ stdout: "pipe", stderr: "pipe" },
-			);
-		}
-
-		// Make executable
-		Bun.spawnSync(["chmod", "+x", targetPath]);
-
-		if (existsSync(targetPath)) {
-			console.log(`Installed lldb-dap to ${targetPath}`);
+		try {
+			console.log(`Installing ${installer.name}...`);
+			await installer.install((msg) => console.log(msg));
+			console.log(`${installer.name} installed successfully.`);
 			return 0;
+		} catch (e) {
+			console.error(`Installation failed: ${(e as Error).message}`);
+			return 1;
 		}
-
-		console.error("Installation failed — lldb-dap not found after extraction");
-		console.error("  -> Try installing manually: brew install llvm");
-		return 1;
 	},
 });

src/dap/adapters/assets.d.ts

@@ -0,0 +1,4 @@
+declare module "*.tar.gz" {
+	const path: string;
+	export default path;
+}

src/dap/adapters/index.ts

@@ -0,0 +1,18 @@
+import { javaInstaller } from "./java.ts";
+import { lldbInstaller } from "./lldb.ts";
+import type { AdapterInstaller } from "./types.ts";
+
+const ADAPTERS: Record<string, AdapterInstaller> = {
+	lldb: lldbInstaller,
+	java: javaInstaller,
+};
+
+export function getAdapterInstaller(name: string): AdapterInstaller | undefined {
+	return ADAPTERS[name];
+}
+
+export function listAdapterNames(): string[] {
+	return Object.keys(ADAPTERS);
+}
+
+export { getJavaAdapterClasspath, isJavaAdapterInstalled } from "./java.ts";

src/dap/adapters/java.ts

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { $ } from "bun";
+import { getManagedAdaptersDir } from "../session.ts";
+import type { AdapterInstaller } from "./types.ts";
+
+const MAVEN_CENTRAL = "https://repo1.maven.org/maven2";
+
+const JAVA_DEPS: Record<string, string> = {
+	"com.microsoft.java.debug.core-0.53.0.jar":
+		"com/microsoft/java/com.microsoft.java.debug.core/0.53.0/com.microsoft.java.debug.core-0.53.0.jar",
+	"commons-lang3-3.14.0.jar": "org/apache/commons/commons-lang3/3.14.0/commons-lang3-3.14.0.jar",
+	"gson-2.10.1.jar": "com/google/code/gson/gson/2.10.1/gson-2.10.1.jar",
+	"rxjava-2.2.21.jar": "io/reactivex/rxjava2/rxjava/2.2.21/rxjava-2.2.21.jar",
+	"reactive-streams-1.0.4.jar":
+		"org/reactivestreams/reactive-streams/1.0.4/reactive-streams-1.0.4.jar",
+	"commons-io-2.15.1.jar": "commons-io/commons-io/2.15.1/commons-io-2.15.1.jar",
+};
+
+const JAVA_DEP_NAMES = Object.keys(JAVA_DEPS);
+
+function getJavaAdapterDir(): string {
+	return join(getManagedAdaptersDir(), "java");
+}
+
+/** Check if the Java adapter is fully installed (all JARs + compiled classes). */
+export function isJavaAdapterInstalled(): boolean {
+	const dir = getJavaAdapterDir();
+	const depsDir = join(dir, "deps");
+	if (!existsSync(join(dir, "classes", "com", "debugthat", "adapter", "Main.class"))) {
+		return false;
+	}
+	return JAVA_DEP_NAMES.every((jar) => existsSync(join(depsDir, jar)));
+}
+
+/** Build the classpath string for running the Java adapter. */
+export function getJavaAdapterClasspath(): string {
+	const dir = getJavaAdapterDir();
+	const depsDir = join(dir, "deps");
+	const classesDir = join(dir, "classes");
+	const jars = JAVA_DEP_NAMES.map((jar) => join(depsDir, jar));
+	return [classesDir, ...jars].join(delimiter);
+}
+
+/**
+ * Extract Java adapter sources for compilation.
+ * In dev: uses source tree directly. In bundle: extracts from bundled tarball asset.
+ */
+async function extractAdapterSources(installDir: string): Promise<string[]> {
+	// Dev mode: source tree exists, use directly
+	const devPackageDir = join(import.meta.dir, "java", "com", "debugthat", "adapter");
+	if (existsSync(devPackageDir)) {
+		return Array.from(new Bun.Glob("*.java").scanSync(devPackageDir)).map((f) =>
+			join(devPackageDir, f),
+		);
+	}
+
+	// Bundle mode: lazy-import the tarball asset and extract
+	const { default: tarballPath } = await import("./java/adapter-sources.tar.gz" as string);
+	const resolved = tarballPath.startsWith("/") ? tarballPath : join(import.meta.dir, tarballPath);
+	const srcDir = join(installDir, "src");
+	mkdirSync(srcDir, { recursive: true });
+	await $`tar xzf ${resolved} -C ${srcDir}`;
+	const packageDir = join(srcDir, "com", "debugthat", "adapter");
+	return Array.from(new Bun.Glob("*.java").scanSync(packageDir)).map((f) => join(packageDir, f));
+}
+
+export const javaInstaller: AdapterInstaller = {
+	name: "java (java-debug.core)",
+
+	isInstalled: isJavaAdapterInstalled,
+
+	async install(log) {
+		const javaVersionResult = await $`java -version`.quiet().nothrow();
+		const stderr = javaVersionResult.stderr.toString().trim();
+		const versionMatch = stderr.match(/version "(\d+)/);
+		const version = versionMatch?.[1] ? parseInt(versionMatch[1], 10) : 0;
+		if (version < 11) {
+			throw new Error(`Java 11+ required (found: ${stderr.split("\n")[0]?.trim() ?? "none"})`);
+		}
+
+		const dir = getJavaAdapterDir();
+		const depsDir = join(dir, "deps");
+		mkdirSync(depsDir, { recursive: true });
+
+		for (const [jarName, mavenPath] of Object.entries(JAVA_DEPS)) {
+			const jarPath = join(depsDir, jarName);
+			if (!existsSync(jarPath)) {
+				log(`  Downloading ${jarName}...`);
+				const response = await fetch(`${MAVEN_CENTRAL}/${mavenPath}`, {
+					redirect: "follow",
+				});
+				if (!response.ok) {
+					throw new Error(`Failed to download ${jarName}: HTTP ${response.status}`);
+				}
+				await Bun.write(jarPath, response);
+			}
+		}
+
+		log("  Compiling adapter...");
+		const cp = JAVA_DEP_NAMES.map((jar) => join(depsDir, jar)).join(delimiter);
+		const classesDir = join(dir, "classes");
+		mkdirSync(classesDir, { recursive: true });
+
+		const sourceFiles = await extractAdapterSources(dir);
+		await $`javac -d ${classesDir} -cp ${cp} -source 11 -target 11 ${sourceFiles}`;
+
+		log("  Adapter compiled.");
+	},
+};

src/dap/adapters/java/com/debugthat/adapter/DefaultVirtualMachineManagerProvider.java

@@ -0,0 +1,16 @@
+package com.debugthat.adapter;
+
+import com.microsoft.java.debug.core.adapter.IVirtualMachineManagerProvider;
+import com.sun.jdi.Bootstrap;
+import com.sun.jdi.VirtualMachineManager;
+
+/**
+ * Default VMM provider using JDI Bootstrap.
+ */
+public class DefaultVirtualMachineManagerProvider implements IVirtualMachineManagerProvider {
+
+    @Override
+    public VirtualMachineManager getVirtualMachineManager() {
+        return Bootstrap.virtualMachineManager();
+    }
+}