v0.6.3 — Python TCP attach + DAP refactor

What's new

dbg attach <port> --runtime python actually works now

Previously dbg attach <port> --runtime python was broken: it spawned a second debugpy.adapter process and asked that adapter to attach — adapter-on-top-of-adapter, which exited immediately with DAP adapter process terminated.

Now dbg connects directly over TCP to the debugpy listener:

# Start your app under debugpy
python -m debugpy --listen 5678 -m uvicorn myapp:app

# From another terminal — attaches over TCP, no second adapter spawned
dbg attach 5678 --runtime python

Internal: DAP transport + connector strategies

The DAP layer was refactored to separate two orthogonal concerns:

• Transport — how bytes flow (StdioTransport vs TcpTransport)
• Provisioning — how we obtain a DAP endpoint (SpawnAdapterConnector vs TcpAttachConnector)

Each DapRuntimeConfig now declares its connector for launch and (optionally) attach. Adding new DAP runtimes (Go via delve, Ruby via rdbg) is now a config-file change, not a DapClient change.

Other code-quality improvements in src/dap/:

• DapClient.send is strongly typed via a command map derived from @vscode/debugprotocol
• DAP messages are zod-validated on the wire (no more as casts in handleMessage)
• SessionCapabilities → SessionFeatures (avoids name collision with DAP's DebugProtocol.Capabilities)
• _runtime narrows to a zod-derived CanonicalRuntime union

Bug fixes

• Fix break-rm for function breakpoints — function breakpoints are now stored alongside file breakpoints in the unified breakpoints array (#10 / #11).

Install

bun install --global debug-that@0.6.3
# or
npx debug-that@0.6.3

🤖 Release notes generated with Claude Code

Demo assets v1

Large media assets for the meetup slides deck (demo/slides/). Kept out of the git tree to avoid bloating repo history. Referenced by URL from slides.md.

v0.6.0 — Java Hotpatch & ECJ Expression Eval

Highlights

Hot code replace for Java — fix a running Spring Boot app without restarting the JVM.

dbg hotpatch PricingController.java recompiles with ECJ and injects the new bytecode via JDI redefineClasses — the same technique IntelliJ uses for "Reload Changed Classes".

What's New

Java Expression Evaluation (ECJ compile+inject)

• Full Java expression support in dbg eval — arithmetic, method calls, ternary, constructors, collections
• Automatic reflection fallback for private field access
• Compiles expressions to bytecode with ECJ 3.40.0, injects via JDI ClassLoader.defineClass

Java Hot Code Replace (dbg hotpatch)

• .java input → compiles with ECJ using debuggee classpath → redefines classes in the JVM
• .class input → reads bytecode directly, auto-detects inner classes
• Obsolete frame detection with restart-frame support
• Works with Spring Boot: attach to running app, hotpatch controller, verify with curl

SUSPEND_ALL Breakpoint Policy

• Matches IntelliJ behavior: all threads suspend on breakpoint hit
• Prevents JVM freeze when redefineClasses is called during debugging
• Breakpoints disabled/re-enabled around class redefinition (IntelliJ approach)

Unified Structured Logger

• Single JSONL log file per session (replaces separate CDP + daemon logs)
• Typed Logger<N> with compile-time data shape enforcement
• Custom formatters per source: dbg logs --src dap --level trace
• Colored output with --color flag

Installer Improvements

• Maven-based dependency resolution (replaces manual JAR downloads)
• java-debug 0.53.2 built from source (pinned commit) for suspendAllThreads support
• bun run build:java for quick adapter recompilation
• dbg install java always recompiles (no stale cache)

Other

• DAP runtime configs extracted into src/dap/runtimes/ with typed interface
• Unified WaitForStopOptions across CDP and DAP sessions
• -cp classpath support for Java launch
• PathSearchingVirtualMachine.classPath() for safe classpath resolution

Install

bun install -g debug-that
dbg install java

Full Changelog

See CHANGELOG.md

v0.5.0 — Java Debugging Support

New Features

• Java debugging via DAP — launch and attach to JVM programs using Microsoft's java-debug.core adapter
  • dbg launch --runtime java Hello.java — launch with breakpoints, stepping, variable inspection, eval
  • dbg attach localhost:5005 --runtime java — attach to a running JVM via JDWP
  • dbg install java — managed install (~3.5MB from Maven Central, compiled locally)
  • Conditional breakpoints, exception pause, function breakpoints
  • Auto-detect mvn, gradle, gradlew, mvnw, mvnDebug as Java runtimes

Internal

• Adapter installer registry — AdapterInstaller interface; adding a new adapter = one file + one registry entry
• DapSession runtime strategy pattern — replaced if/else chain with DapRuntimeConfig per runtime
• Build-time asset bundling — Java adapter sources tarball generated at build time, bundled as Bun file asset
• Extracted lldb installer into adapters/lldb.ts, fixed liblldb extraction bug
• Bun.$ shell syntax, Bun.which(), path.delimiter for cross-platform support
• Attach-mode disconnect preserves debuggee

Full Changelog: v0.4.0...v0.5.0

v0.4.0

New Features

• path-map and symbols commands for DAP debug info management (LLDB, Python)
• Auto-detect runtime from command binary name — dbg launch node app.js no longer needs --runtime node
• Deferred breakpoint rebinding with source-map awareness for Jest/Vitest — breakpoints set in .ts files resolve correctly when test runners compile to .js
• Pending breakpoint status — break-ls now shows [pending] for breakpoints not yet resolved to a script

Bug Fixes

• CLI parser: value flags now accept dash-prefixed values — --timeout -1 and --condition -x work correctly instead of being misinterpreted as flags
• CLI parser: POSIX combined short flags with values — -p9229 and -vp9229 now correctly parse the value remainder
• CLI parser: stricter command suggestion threshold — short typos like dbg zz no longer produce false "Did you mean" suggestions
• Source map translation for logpoints and run-to — coordinates now resolve correctly through source maps
• DAP adapter errors surfaced when stopOnEntry fails
• Socket directory permissions restricted to owner only (security fix)

Internal

• Restructured session architecture: extracted BaseSession, Session interface, and SessionCapabilities
• Replaced registerCommand() with declarative defineCommand() using Zod schemas
• Rewritten CLI parser as tokenizer/parser two-phase architecture
• Typed RefEntry as discriminated union with deterministic pending rebinds
• Introduced SourceLocation/RuntimeLocation types for coordinate spaces

Full Changelog: v0.3.0...v0.4.0