dap-mcp-server 0.1.12 → 0.1.17

package/README.md

@@ -16,26 +16,42 @@ Any DAP-compliant debug adapter works. Built-in defaults for:
 |----------|---------|---------|
 | Python | debugpy | `pip install debugpy` |
 | Go | Delve | `go install github.com/go-delve/delve/cmd/dlv@latest` |
+| Node.js / TypeScript | vscode-js-debug | Configure its `dapDebugServer.js` path or install it in the project |
 | C/C++ | lldb-dap | `apt install lldb` / `brew install llvm` |
+| Rust | lldb-dap (same `cppdbg` adapter) | as above, plus the Rust LLDB formatters (bundled with rustup toolchains; the `rust-lldb` package on distro-packaged Rust) |
+| PHP | vscode-php-debug + xdebug 3 | Install xdebug, then point the `php` adapter's `program` at `out/phpDebug.js` |
 
-Additional adapters (e.g. Node.js via js-debug) can be registered via the `configure_adapter` tool or config files.
+Additional adapters, and project-specific paths for the built-ins, can be registered via `configure_adapter` or config files.
+
+### Launch recipes are built in
+
+The per-language incantations that usually stand between an agent and its first breakpoint ship with the server:
+
+- **PHP** — the `php` adapter's `launchDefaults` carry the xdebug `runtimeArgs` and listen port. They are merged into a user-configured `php` entry, so you only supply the `phpDebug.js` path. If PHP still runs past a breakpoint, the result carries a `hint` pointing at xdebug.
+- **Rust** — sessions that break in `.rs` files load `lldb_lookup.py` from the active toolchain's sysroot, so `String`, `&str`, `Vec` and `HashMap` render as values instead of raw structs. `debug_at` defaults `program` to `target/debug/<package name>`.
+- **Go** — `cwd` is mirrored to `dlvCwd` so delve builds from the module directory.
+- **Java / JDWP** — `debug_doctor` prints the `-agentlib:jdwp=…` line to start the JVM with; `debug_attach` accepts `breakpoints` so they bind before a `suspend=y` VM resumes.
+
+`debug_doctor` and `debug_at` detect the language from manifests (`pyproject.toml`, `go.mod`, `Cargo.toml`, `composer.json`, `pom.xml`, `build.gradle`, `CMakeLists.txt`, `package.json`), from the breakpoint file's extension, and — for manifest-less script directories — from the source files in `cwd` and `cwd/src`.
 
 ## MCP Tools
 
 | Tool | Description |
 |------|-------------|
-| `debug_inspect` | **One-shot:** launch → run to breakpoint → evaluate expressions → disconnect. Use first when you just need a value at a line. |
+| `debug_doctor` | **Start here:** detect the project, recommend an adapter, verify its complete command, and return setup remediation. |
+| `debug_at` | **Primary debugging call:** infer the adapter, stop at a line, evaluate expressions, and clean up. |
+| `debug_inspect` | **One-shot:** launch → run to breakpoint → evaluate expressions → disconnect when the adapter is already known. |
 | `debug_run` | **One-shot:** launch → run to completion → return all output. Combine with logpoints for printf-style debugging without editing source. |
 | `debug_launch` | Start an interactive debug session (launch a program with breakpoints) |
-| `debug_attach` | Attach to a running process |
+| `debug_attach` | Attach to a running process; pass `breakpoints` / `exceptionBreakpoints` to bind them before it resumes |
 | `debug_restart` | Restart with the same configuration |
 | `debug_disconnect` | End a debug session |
 | `set_breakpoints` | Set/replace breakpoints in a file (use `logMessage` for logpoints) |
 | `set_exception_breakpoints` | Break on exceptions |
 | `list_breakpoints` | List currently-registered breakpoints for a session |
-| `get_state` | Get threads, stack trace, scopes, and variables |
+| `get_state` | Get threads, stack trace, scopes, and variables (`scopes: ["Registers"]` to opt into CPU registers, `detail: "compact"` for a slim view) |
 | `evaluate` | Evaluate an expression in the debuggee context |
-| `step` | Continue, next, stepIn, stepOut, or pause |
+| `step` | Continue, next, stepIn, stepOut, or pause; answers compactly by default (`detail: "full"` for the `get_state` shape) |
 | `get_output` | Get buffered stdout/stderr |
 | `configure_adapter` | Register a custom debug adapter |
 | `list_adapters` | List available adapters |
@@ -57,7 +73,20 @@ npm run build
 
 ## Usage with Claude Code
 
-Add to your MCP configuration (`~/.claude/mcp.json` or project `.mcp.json`):
+Register the server for the current user:
+
+```bash
+claude mcp add --scope user dap -- npx -y dap-mcp-server
+```
+
+The repository also contains a Claude Code plugin that bundles the MCP declaration and the activation skill. During local development, validate and load it with:
+
+```bash
+claude plugin validate integrations/claude/dap-debugging
+claude --plugin-dir ./integrations/claude/dap-debugging
+```
+
+To configure MCP manually, use a project `.mcp.json`:
 
 ```json
 {
@@ -82,16 +111,27 @@ Or if installed globally:
 }
 ```
 
-A `SKILL.md` file is included in the package. Copy it to `.claude/skills/` in your project to teach Claude Code when and how to use the debugger:
+A `SKILL.md` file is included in the package. After a local package install, copy it to the required skill directory layout:
 
 ```bash
-mkdir -p .claude/skills
-cp node_modules/dap-mcp-server/SKILL.md .claude/skills/dap-debugging.md
+mkdir -p .claude/skills/dap-debugging
+cp node_modules/dap-mcp-server/SKILL.md .claude/skills/dap-debugging/SKILL.md
 ```
 
+For a global npm install, the source file is under `$(npm root -g)/dap-mcp-server/SKILL.md`, not the project's `node_modules`.
+
 ## Design
 
-Tools are deliberately coarse-grained. A single `get_state` call returns threads, stack trace, scopes, and variables — instead of requiring 4 separate calls. The `step` tool blocks synchronously until the debuggee stops again and returns the new state. This minimizes round-trips for AI agents that think in terms of "step forward and show me what happened."
+Tools are deliberately coarse-grained. `debug_doctor` makes setup failures actionable and `debug_at` performs the common detect → launch → stop → inspect → cleanup workflow in one call. A single `get_state` call returns threads, stack trace, scopes, and variables. The `step` tool blocks until the debuggee stops again and returns the new state.
+
+Responses are budgeted for an LLM's context window:
+
+- CPU register scopes are never fetched unless asked for by name; skipped scopes are listed in `omittedScopes`.
+- `step` returns a compact state: frame-local scopes only, a 5-frame stack, no thread list for single-threaded programs, minified JSON.
+- A state carries only output that no earlier `debug_launch`/`step` response has reported (capped at the newest 50 entries, with `outputOmitted`); `get_output` always has the whole buffer.
+- `debug_doctor` details only the selected adapter (`verbose: true` for all); a not-ready `debug_at` answers with a one-line summary.
+
+Stops on an exception include `exception: { id, description, breakMode }`. When the program ends, `debug_run`, `debug_at`, `debug_launch` and `step` report its `exitCode` if the adapter provides one.
 
 Session IDs are optional when only one debug session is active. Breakpoints can be set inline with `debug_launch` for single-call debugging setup.
 

package/SKILL.md

@@ -1,209 +1,64 @@
 ---
 name: dap-debugging
-description: Use when debugging a program — when you need to set breakpoints, step through code, inspect variables, or understand runtime behavior instead of guessing with print statements.
+description: Use a real debugger for opaque test failures, crashes, swallowed exceptions, incorrect runtime state, or a bug that remains unexplained after static inspection or a failed fix. Prefer this over adding multiple print statements when actual values, branches, or call stacks are needed.
 ---
 
-# Debugging with DAP MCP Server
+# Debug Code with DAP
 
-You have access to a real debugger via the `dap` MCP server. **Use it instead of adding print/log statements** whenever you need to understand runtime behavior, track down a bug, or verify a fix.
+Use the `dap` MCP server as the default next step when static evidence is insufficient. It can stop a local program at a source line, inspect stack frames and variables, evaluate expressions, and collect output without editing the source.
 
-## When to switch from print() to the debugger
+Do not invoke a debugger for syntax errors, obvious type errors, or failures already explained completely by a short traceback. Debugging executes local code and may trigger the program's normal side effects; do not run untrusted targets.
 
-Reach for the debugger — don't keep guessing — when any of these are true:
+## Preferred Workflow
 
-- **Your first fix attempt was wrong.** Stop iterating on guesses. Inspect actual values.
-- **You're about to add 3+ print statements.** Use a logpoint instead (see below) — same information, no code edits.
-- **You need a value on iteration N of a loop.** Use `hitCondition: "N"` instead of conditional prints.
-- **A test fails with a non-obvious traceback.** Launch the test under the debugger; you'll see locals at the failure site.
-- **You're reasoning about state that's modified across many call sites.** A conditional breakpoint on the value beats grepping for assignments.
-
-Print debugging is fine for: trivial one-line checks, scripts you'll throw away in the next message, or when you genuinely just want to see "did this code path execute?".
-
-## Logpoints — print debugging without editing code
-
-A **logpoint** is a breakpoint that doesn't pause execution. It just emits a formatted message every time it's hit. This is the single most useful feature for AI agents.
-
-Set it via the `logMessage` field on a breakpoint:
-
-```
-set_breakpoints({
-  file: "/abs/path/src/foo.py",
-  breakpoints: [
-    { line: 42, logMessage: "x={x} y={y} state={self.state}" },
-    { line: 88, logMessage: "iteration {i}: items={len(items)}" }
-  ]
-})
-```
-
-Then `step({ action: "continue" })` and let the program run. Retrieve every log with `get_output`. You get the same information as inserting `print(f"x={x} y={y}")` at five places — without touching the source file, without re-running, and with the program's natural execution preserved.
-
-**When to use logpoints over breakpoints**: when you want to *observe* values across many hits rather than *interrupt* execution to inspect one. They are the right tool ~70% of the time.
-
-Expression syntax inside `{...}` depends on the adapter (debugpy: Python; node: JS). The expression is evaluated in the breakpoint's scope.
-
-## Debugging a failing test
-
-This is the dominant case. Use the test runner as the program, with the specific test as an argument.
-
-### pytest
-
-```
-debug_launch({
-  adapter: "python",
-  program: "/abs/path/.venv/bin/pytest",
-  args: ["tests/test_foo.py::test_bar", "-x", "--no-header"],
-  cwd: "/abs/path",
-  breakpoints: [{ file: "/abs/path/src/foo.py", line: 42 }],
-  stopOnEntry: false,
-})
-```
-
-For pytest, also consider setting `exceptionBreakpoints: ["raised"]` — pytest swallows exceptions before you see them, but the debugger will stop at the raise site.
-
-### vitest / jest (Node.js)
-
-Requires the `node` adapter configured (see "Node.js setup" below). Use the runner binary from `node_modules/.bin`:
+1. Call `debug_doctor` with the project `cwd`. It detects project signals, recommends an adapter, validates the complete adapter command, and returns exact remediation if setup is incomplete.
+2. Select an executable code line close to where the first incorrect value is observable. Avoid comments, declarations without executable code, and lines that the failing path never reaches.
+3. Call `debug_at` with the source `file`, `line`, and only the expressions needed to test the current hypothesis. Omit `adapter` unless doctor recommends overriding detection.
 
-```
-debug_launch({
-  adapter: "node",
-  program: "${cwd}/node_modules/.bin/vitest",
-  args: ["run", "tests/foo.test.ts", "-t", "the failing test name"],
-  cwd: "/abs/path",
-  breakpoints: [{ file: "/abs/path/src/foo.ts", line: 42 }],
-  stopOnEntry: false,
-})
-```
-
-### go test
-
-```
-debug_launch({
-  adapter: "go",
-  program: "${cwd}",   // delve takes a package dir, not a binary
-  args: ["-test.run", "TestFoo", "-test.v"],
-  cwd: "/abs/path",
-  breakpoints: [{ file: "/abs/path/foo.go", line: 42 }],
-  stopOnEntry: false,
-})
+```json
+{
+  "cwd": "/workspace/project",
+  "program": "/workspace/project/app.py",
+  "file": "/workspace/project/app.py",
+  "line": 42,
+  "expressions": ["request.user", "result", "len(items)"]
+}
 ```
 
-Delve uses `dlv test` semantics under the hood when the program is a package directory containing test files.
+Interpret the result before changing code:
 
-### Node.js setup
+- `hit: true` includes the stopped location, evaluated values, and captured output.
+- `status: terminated` means execution finished before reaching the line; verify the program, arguments, path, and branch.
+- `timedOut: true` means it neither stopped nor terminated in time; inspect output and narrow the target.
+- With `hit: false`, `breakpoint.verified: false` means the adapter could not bind that source location; move to executable code or verify source mapping.
 
-If `list_adapters` shows no `node` entry, register it once (path depends on installed extension):
+Use `launchConfig` for adapter-specific DAP fields such as a module, request type, runtime executable, or source-map option.
 
-```
-configure_adapter({
-  type: "node",
-  runtime: "node",
-  program: "/abs/path/to/js-debug/src/dapDebugServer.js",
-  args: [],
-  scope: "global",
-})
-```
-
-`js-debug-dap` ships with the VS Code Node debugger extension. Alternatively use `@vscode/js-debug` from npm.
+## Failing Tests
 
-## Quick Start (single-file program)
+Run the smallest failing test, not the full suite. Pass the test runner as `program` (or through adapter-specific `launchConfig`) and the test selector in `args`. Test-runner launch semantics vary by adapter, so use `debug_doctor` first and preserve known-good fields from `.vscode/launch.json` in `launchConfig`.
 
-1. `list_adapters` — see what's installed.
-2. Launch with breakpoints in one call:
+Choose a breakpoint in application code before the assertion or exception boundary. For exceptions hidden by a test framework, use an interactive launch and `set_exception_breakpoints`.
 
-```
-debug_launch({
-  adapter: "python",
-  program: "/abs/path/file.py",
-  stopOnEntry: false,
-  breakpoints: [{ file: "/abs/path/file.py", line: 42 }],
-})
-```
-
-3. The response already contains the full state (threads, stack, scopes, variables) when the breakpoint is hit. No follow-up `get_state` needed.
-4. Step with `step({ action: "next" })` — response includes the new state.
-5. `evaluate({ expression: "len(items)" })` for ad-hoc inspection.
-6. `debug_disconnect` when done.
-
-## Stepping strategy
-
-- **`next`** (step over) is the default choice. Use it unless you have a specific reason not to.
-- **`stepIn`** only when you suspect the bug is *inside* the function being called — not at the call site. Stepping into library code will get you lost fast.
-- **`stepOut`** to bail out of a function you stepped into by mistake.
-- **`continue`** to run to the next breakpoint. With logpoints set, this is how you collect runtime traces.
-
-If you find yourself stepping line-by-line for more than ~10 steps, you're probably doing it wrong. Set a breakpoint at the next interesting location and continue to it.
-
-## Worked example
-
-Bug: `compute_total(items)` returns `0` when items contain a tax-exempt entry.
-
-```
-# Launch under pytest with a breakpoint at the suspect line
-debug_launch({
-  adapter: "python",
-  program: "/proj/.venv/bin/pytest",
-  args: ["tests/test_billing.py::test_tax_exempt", "-x"],
-  cwd: "/proj",
-  breakpoints: [{ file: "/proj/src/billing.py", line: 57 }],
-  stopOnEntry: false,
-})
-
-# Response (paraphrased):
-# {
-#   sessionId: "s-1",
-#   status: "stopped",
-#   location: { file: ".../billing.py", line: 57, functionName: "compute_total" },
-#   scopes: [{ name: "Locals", variables: [
-#     { name: "items", value: "[{...}, {...}]", ... },
-#     { name: "subtotal", value: "100", ... },
-#     { name: "tax", value: "0", ... }
-#   ] }]
-# }
-
-# Inspect the exempt item more closely
-evaluate({ expression: "[i for i in items if i.get('tax_exempt')]" })
-# → [{name: 'book', price: 100, tax_exempt: True}]
-
-# Step over to see what compute_total actually returns
-step({ action: "next" })
-# → see that `total = subtotal + tax` returns 100, not 0. Bug is upstream.
-
-# Continue to verify nothing else changes the return
-step({ action: "continue" })
-
-debug_disconnect()
-```
+## Interactive Exploration
 
-Fix locally, re-run the test, done.
+Use `debug_launch` only when one-shot inspection is insufficient, such as multiple stops or step-by-step control. With breakpoints, it waits by default and explicitly reports stopped, terminated, or timeout.
 
-## Key Rules
+1. `debug_launch` with breakpoints and optional `launchConfig`.
+2. Inspect the returned state; do not immediately duplicate it with `get_state`.
+3. Use `evaluate` for a focused question.
+4. Use `step` with `next` by default; use `stepIn` only when the called function is suspect.
+5. Use `set_breakpoints` to move or add breakpoints.
+6. Always finish with `debug_disconnect`.
 
-- **Do NOT call `get_state` after `step`** — `step` already returns the new stopped state.
-- **Omit `sessionId`** when only one debug session is active.
-- **Use absolute paths** for `program` and breakpoint `file` parameters.
-- **Prefer `stopOnEntry: false` with breakpoints** — it gets you directly to the interesting code.
-- **Use `get_output`** for program stdout/stderr (including logpoint output).
+`step` answers compactly: frame-local scopes, a short stack, and only output not reported before. Call `get_state` when globals, a deeper stack, or `variableDepth` > 1 are needed; CPU registers are fetched only with `scopes: ["Registers"]`. Read the whole output buffer with `get_output`.
 
-## Debugging Strategies
+To debug a process that is already running or was started suspended (JVM with JDWP `suspend=y`, a server), use `debug_attach` and pass `breakpoints` in that same call so they bind before the process resumes.
 
-### Narrowing down a bug
-1. Set a breakpoint where state is known good.
-2. Set another where state is wrong.
-3. Use `step` with `next` to walk between them, or set intermediate logpoints.
+Omit `sessionId` when exactly one session is active. Use absolute paths for programs and source files.
 
-### Understanding a crash
-1. Launch with `exceptionBreakpoints: ["uncaughtExceptions"]` (or `"raised"` for any raise).
-2. When stopped at the exception, inspect stack and locals.
+## Output-First Debugging
 
-### Verifying a fix
-1. Set a breakpoint at the fixed code.
-2. Run to it, inspect variables, confirm new behavior.
-3. Continue to verify the program completes successfully.
+Use `debug_run` when completion status and stdout/stderr are sufficient. For repeated observations without pausing, create logpoints with `set_breakpoints` and `logMessage`, continue execution, then read `get_output`. This provides runtime traces without modifying source files.
 
-### Observing a hot loop without stopping it
-1. Set logpoints at the relevant lines with `{i}` and any state expression.
-2. `continue`.
-3. Read the trace via `get_output`. For long-running programs, poll incrementally:
-   pass the `nextSince` value from each call as the `since` parameter of the next call
-   to receive only newly-emitted entries.
+If doctor reports an unavailable adapter, follow its `nextSteps` before retrying. Do not repeatedly launch a configuration that readiness checks have already rejected.

package/build/adapters/builtin.js

@@ -68,5 +68,30 @@ export const BUILTIN_ADAPTERS = [
         args: [],
         installHint: "apt install lldb (Debian/Ubuntu) or brew install llvm (macOS)",
     },
+    // php adapter: vscode-php-debug's phpDebug.js. Like node, there is no
+    // universal install path, so the user points `program` at it; the
+    // launchDefaults below still apply to that override (the registry merges
+    // them across tiers).
+    {
+        type: "php",
+        runtime: "node",
+        program: "phpDebug.js",
+        args: [],
+        // The adapter listens on `port` and xdebug connects back to it. Without
+        // these runtimeArgs PHP runs to completion before xdebug ever connects,
+        // so no breakpoint is hit.
+        launchDefaults: {
+            port: 9003,
+            hostname: "127.0.0.1",
+            runtimeArgs: [
+                "-dxdebug.mode=debug",
+                "-dxdebug.start_with_request=yes",
+                "-dxdebug.client_host=127.0.0.1",
+                "-dxdebug.client_port=9003",
+            ],
+        },
+        installHint: "Install xdebug 3 and vscode-php-debug, then set the adapter's `program` to its out/phpDebug.js path " +
+            "(e.g. via `configure_adapter`). See https://github.com/xdebug/vscode-php-debug.",
+    },
 ];
 //# sourceMappingURL=builtin.js.map

package/build/adapters/builtin.js.map

@@ -1 +1 @@
-{"version":3,"file":"builtin.js","sourceRoot":"","sources":["../../src/adapters/builtin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,CAAC,iBAAiB,CAAC;QACzB,cAAc,EAAE;YACd,OAAO,EAAE,iBAAiB;SAC3B;QACD,WAAW,EAAE,qBAAqB;KACnC;IACD;QACE,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC;QACrC,SAAS,EAAE,KAAK;QAChB,sDAAsD;QACtD,WAAW,EAAE,yCAAyC;QACtD,WAAW,EAAE,qDAAqD;KACnE;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,2CAA2C;IAC3C;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,mBAAmB;QAC5B,wEAAwE;QACxE,qEAAqE;QACrE,YAAY;QACZ,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC;QACxB,SAAS,EAAE,KAAK;QAChB,yEAAyE;QACzE,WAAW,EAAE,iCAAiC;QAC9C,wEAAwE;QACxE,2CAA2C;QAC3C,cAAc,EAAE;YACd,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,QAAQ;SAClB;QACD,WAAW,EACT,mGAAmG;YACnG,mFAAmF;KACtF;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,UAAU;QACnB,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,+DAA+D;KAC7E;CACF,CAAC"}
+{"version":3,"file":"builtin.js","sourceRoot":"","sources":["../../src/adapters/builtin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,CAAC,iBAAiB,CAAC;QACzB,cAAc,EAAE;YACd,OAAO,EAAE,iBAAiB;SAC3B;QACD,WAAW,EAAE,qBAAqB;KACnC;IACD;QACE,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC;QACrC,SAAS,EAAE,KAAK;QAChB,sDAAsD;QACtD,WAAW,EAAE,yCAAyC;QACtD,WAAW,EAAE,qDAAqD;KACnE;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,2CAA2C;IAC3C;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,mBAAmB;QAC5B,wEAAwE;QACxE,qEAAqE;QACrE,YAAY;QACZ,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC;QACxB,SAAS,EAAE,KAAK;QAChB,yEAAyE;QACzE,WAAW,EAAE,iCAAiC;QAC9C,wEAAwE;QACxE,2CAA2C;QAC3C,cAAc,EAAE;YACd,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,QAAQ;SAClB;QACD,WAAW,EACT,mGAAmG;YACnG,mFAAmF;KACtF;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,UAAU;QACnB,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,+DAA+D;KAC7E;IACD,sEAAsE;IACtE,kEAAkE;IAClE,yEAAyE;IACzE,sBAAsB;IACtB;QACE,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,aAAa;QACtB,IAAI,EAAE,EAAE;QACR,wEAAwE;QACxE,wEAAwE;QACxE,2BAA2B;QAC3B,cAAc,EAAE;YACd,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,WAAW;YACrB,WAAW,EAAE;gBACX,qBAAqB;gBACrB,iCAAiC;gBACjC,gCAAgC;gBAChC,2BAA2B;aAC5B;SACF;QACD,WAAW,EACT,sGAAsG;YACtG,iFAAiF;KACpF;CACF,CAAC"}

package/build/adapters/detect.d.ts

@@ -19,4 +19,16 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+import { AdapterConfig } from "../dap/types.js";
 export declare function checkAdapterAvailable(command: string): Promise<boolean>;
+export interface AdapterAvailability {
+    available: boolean;
+    command: string;
+    reason?: string;
+}
+/**
+ * Validate the complete adapter command, not just its runtime. This prevents
+ * configurations such as `node missing-adapter.js` from being reported as
+ * available merely because Node itself is installed.
+ */
+export declare function inspectAdapterAvailability(config: AdapterConfig): Promise<AdapterAvailability>;

package/build/adapters/detect.js

@@ -20,6 +20,8 @@
  * SOFTWARE.
  */
 import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 export async function checkAdapterAvailable(command) {
@@ -32,4 +34,93 @@ export async function checkAdapterAvailable(command) {
         return false;
     }
 }
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate the complete adapter command, not just its runtime. This prevents
+ * configurations such as `node missing-adapter.js` from being reported as
+ * available merely because Node itself is installed.
+ */
+export async function inspectAdapterAvailability(config) {
+    const command = config.runtime || config.program;
+    if (config.transport === "tcp") {
+        if (!config.portMatcher) {
+            return {
+                available: false,
+                command,
+                reason: "TCP adapters require a portMatcher with one capture group for the listening port.",
+            };
+        }
+        try {
+            new RegExp(config.portMatcher);
+        }
+        catch {
+            return {
+                available: false,
+                command,
+                reason: `The configured portMatcher is not a valid regular expression: ${config.portMatcher}`,
+            };
+        }
+    }
+    if (!(await checkAdapterAvailable(command))) {
+        return {
+            available: false,
+            command,
+            reason: `Executable '${command}' was not found on PATH.`,
+        };
+    }
+    if (!config.runtime) {
+        return { available: true, command };
+    }
+    if (config.program === "-m") {
+        const moduleName = config.args?.[0];
+        if (!moduleName) {
+            return {
+                available: false,
+                command,
+                reason: "The adapter uses '-m' but no module name is configured.",
+            };
+        }
+        try {
+            await execFileAsync(config.runtime, [
+                "-c",
+                "import importlib.util,sys; sys.exit(0 if importlib.util.find_spec(sys.argv[1]) else 1)",
+                moduleName,
+            ]);
+            return { available: true, command: `${config.runtime} -m ${moduleName}` };
+        }
+        catch {
+            return {
+                available: false,
+                command: `${config.runtime} -m ${moduleName}`,
+                reason: `Python module '${moduleName}' is not installed for '${config.runtime}'.`,
+            };
+        }
+    }
+    const looksLikeScript = path.isAbsolute(config.program) ||
+        /[\\/]/.test(config.program) ||
+        /\.(?:cjs|js|mjs|py|jar)$/i.test(config.program);
+    if (!looksLikeScript) {
+        return { available: true, command };
+    }
+    const resolved = path.resolve(config.program);
+    if (await fileExists(resolved)) {
+        return { available: true, command: `${config.runtime} ${resolved}` };
+    }
+    if (await checkAdapterAvailable(config.program)) {
+        return { available: true, command: `${config.runtime} ${config.program}` };
+    }
+    return {
+        available: false,
+        command: `${config.runtime} ${config.program}`,
+        reason: `Adapter program '${config.program}' was not found.`,
+    };
+}
 //# sourceMappingURL=detect.js.map

package/build/adapters/detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/adapters/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAe;IACzD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QAClE,MAAM,aAAa,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/adapters/detect.ts"],"names":[],"mappings":"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"}

package/build/adapters/recipes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { AdapterConfig } from "../dap/types.js";
+export interface LaunchArgOptions {
+    program?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Adapter-specific launch fields, merged below the explicit common options. */
+    launchConfig?: Record<string, unknown>;
+    stopOnEntry: boolean;
+    /** Source files the session will break in; selects language-specific recipes. */
+    sourceFiles?: string[];
+}
+/**
+ * Build the DAP launch arguments shared by debug_launch, debug_inspect/debug_at
+ * and debug_run. Merge order: adapter launchDefaults < launchConfig < explicit
+ * common fields, then per-adapter recipes that a caller would otherwise have
+ * to know by heart.
+ */
+export declare function buildLaunchArgs(config: AdapterConfig, opts: LaunchArgOptions, resolveRustSysroot?: () => Promise<string | undefined>): Promise<Record<string, unknown>>;
+/** `target/debug/<package name>` of the Cargo project in cwd, once it has been built. */
+export declare function defaultCargoProgram(cwd: string): Promise<string | undefined>;
+/** Why a program may have run to completion without the debugger ever binding a breakpoint. */
+export declare function launchFailureHint(adapterType: string): string | undefined;
+/** How to get a first stop with this language/adapter; surfaced by debug_doctor. */
+export declare function adapterUsageNote(languageOrAdapter: string): string | undefined;