dap-mcp-server 0.1.12 → 0.1.16

package/README.md

@@ -16,15 +16,18 @@ 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` |
 
-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.
 
 ## 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 |
@@ -57,7 +60,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 +98,18 @@ 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.
 
 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,60 @@
 ---
 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.
+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.
 
-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`:
-
-```
-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,
-})
+```json
+{
+  "cwd": "/workspace/project",
+  "program": "/workspace/project/app.py",
+  "file": "/workspace/project/app.py",
+  "line": 42,
+  "expressions": ["request.user", "result", "len(items)"]
+}
 ```
 
-### go test
+Interpret the result before changing code:
 
-```
-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,
-})
-```
-
-Delve uses `dlv test` semantics under the hood when the program is a package directory containing test files.
-
-### Node.js setup
-
-If `list_adapters` shows no `node` entry, register it once (path depends on installed extension):
-
-```
-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.
-
-## Quick Start (single-file program)
+- `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.
 
-1. `list_adapters` — see what's installed.
-2. Launch with breakpoints in one call:
+Use `launchConfig` for adapter-specific DAP fields such as a module, request type, runtime executable, or source-map option.
 
-```
-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.
+## Failing Tests
 
-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()
-```
+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`.
 
-Fix locally, re-run the test, done.
+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`.
 
-## Key Rules
+## Interactive Exploration
 
-- **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).
+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.
 
-## Debugging Strategies
+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`.
 
-### 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/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/registry.js

@@ -34,24 +34,47 @@ export class AdapterRegistry {
         this.builtins = new Map(BUILTIN_ADAPTERS.map((a) => [a.type, a]));
     }
     get(type) {
-        return this.project.get(type) ?? this.global.get(type) ?? this.builtins.get(type);
+        const builtin = this.builtins.get(type);
+        const global = this.global.get(type);
+        const project = this.project.get(type);
+        if (!builtin && !global && !project)
+            return undefined;
+        const merged = {};
+        for (const layer of [builtin, global, project]) {
+            if (!layer)
+                continue;
+            for (const [key, value] of Object.entries(layer)) {
+                if (value !== undefined && key !== "launchDefaults") {
+                    merged[key] = value;
+                }
+            }
+        }
+        merged.launchDefaults = {
+            ...builtin?.launchDefaults,
+            ...global?.launchDefaults,
+            ...project?.launchDefaults,
+        };
+        return merged;
     }
     register(config, scope = "project") {
         const map = scope === "global" ? this.global : this.project;
         map.set(config.type, config);
     }
     listAll() {
-        const result = new Map();
-        for (const [type, config] of this.builtins) {
-            result.set(type, { ...config, source: "builtin" });
-        }
-        for (const [type, config] of this.global) {
-            result.set(type, { ...config, source: "global" });
-        }
-        for (const [type, config] of this.project) {
-            result.set(type, { ...config, source: "project" });
-        }
-        return Array.from(result.values());
+        const types = new Set([
+            ...this.builtins.keys(),
+            ...this.global.keys(),
+            ...this.project.keys(),
+        ]);
+        return Array.from(types, (type) => {
+            const config = this.get(type);
+            const source = this.project.has(type)
+                ? "project"
+                : this.global.has(type)
+                    ? "global"
+                    : "builtin";
+            return { ...config, source };
+        });
     }
     async load() {
         this.global = await this.loadFile(path.join(this.globalDir, "adapters.json"));

package/build/adapters/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/adapters/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/adapters/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,OAAO,eAAe;IAClB,QAAQ,CAA6B;IACrC,MAAM,GAA+B,IAAI,GAAG,EAAE,CAAC;IAC/C,OAAO,GAA+B,IAAI,GAAG,EAAE,CAAC;IAChD,SAAS,CAAS;IAClB,UAAU,CAAS;IAE3B,YAAY,SAAiB,EAAE,UAAkB;QAC/C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,GAAG,CAAC,IAAY;QACd,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAEtD,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,MAAM,KAAK,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;YAC/C,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,IAAI,KAAK,KAAK,SAAS,IAAI,GAAG,KAAK,gBAAgB,EAAE,CAAC;oBACnD,MAAkC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBACnD,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,CAAC,cAAc,GAAG;YACtB,GAAG,OAAO,EAAE,cAAc;YAC1B,GAAG,MAAM,EAAE,cAAc;YACzB,GAAG,OAAO,EAAE,cAAc;SAC3B,CAAC;QACF,OAAO,MAAuB,CAAC;IACjC,CAAC;IAED,QAAQ,CAAC,MAAqB,EAAE,QAA8B,SAAS;QACrE,MAAM,GAAG,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QAC5D,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO;QACL,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC;YACpB,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE;YACvB,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YACrB,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;SACvB,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBACnC,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;oBACrB,CAAC,CAAC,QAAQ;oBACV,CAAC,CAAC,SAAS,CAAC;YAChB,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC;QAC/B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC;QAC9E,IAAI,CAAC,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;IAClF,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAA2B;QACpC,MAAM,GAAG,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;QAClE,MAAM,GAAG,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QAC5D,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACrF,CAAC;IAEO,KAAK,CAAC,QAAQ,CAAC,QAAgB;QACrC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkC,CAAC;YACjE,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;CACF"}

package/build/diagnostics/doctor.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 { AdapterRegistry } from "../adapters/registry.js";
+import { AdapterConfig } from "../dap/types.js";
+export interface ProjectSignals {
+    languages: string[];
+    testFrameworks: string[];
+    packageManager?: string;
+    pythonPath?: string;
+    launchJson?: string;
+}
+export interface DoctorAdapter {
+    type: string;
+    source: "builtin" | "global" | "project";
+    selected: boolean;
+    available: boolean;
+    command: string;
+    reason?: string;
+    installHint?: string;
+    runtime?: string;
+    program: string;
+    transport: "stdio" | "tcp";
+}
+export interface DoctorResult {
+    cwd: string;
+    ready: boolean;
+    recommendedAdapter?: string;
+    detected: ProjectSignals;
+    adapters: DoctorAdapter[];
+    nextSteps: string[];
+}
+export interface ResolvedProjectAdapter {
+    result: DoctorResult;
+    config?: AdapterConfig;
+}
+export declare function detectProjectSignals(cwd: string, sourceFile?: string): Promise<ProjectSignals>;
+export declare function resolveProjectAdapter(registry: AdapterRegistry, options?: {
+    cwd?: string;
+    adapter?: string;
+    sourceFile?: string;
+}): Promise<ResolvedProjectAdapter>;
+export declare function runDebugDoctor(registry: AdapterRegistry, options?: {
+    cwd?: string;
+    adapter?: string;
+}): Promise<DoctorResult>;