breakpoint-mcp 1.0.0

package/dist/csdap.js

@@ -0,0 +1,331 @@
+import { EventEmitter } from "node:events";
+import { DapError } from "./dap.js";
+/**
+ * Minimal DAP client for the C#/.NET debugging plane (D4 C3) — the debugger
+ * analogue of the C2 `CsLspClient`. Transport-agnostic: it drives any
+ * `JsonRpcChannel`, so production spawns **netcoredbg** (Samsung, MIT) over
+ * stdio (`StdioChannel`) while unit tests point it at a loopback TCP mock
+ * (`FramedConnection`) — exactly the way the GDScript `DapClient` tests and the
+ * `CsLspClient` tests do.
+ *
+ * It is deliberately a sibling of `DapClient` rather than a shared base class —
+ * matching the codebase's one-client-per-protocol precedent (dap.ts / lsp.ts,
+ * and now cslsp.ts) — but reuses `DapError` / `DapState` and the framing
+ * primitives so the protocol plumbing isn't re-invented. The only C#-specific
+ * behaviors are the `coreclr` adapterID and pointing launch/attach at a .NET
+ * program/process; everything else is standard DAP the same way Godot's built-in
+ * debug adapter is. On top of read/inspect + a gated `setVariable`, it carries the
+ * GDScript extras netcoredbg actually backs — persistent watches and a `restart()`
+ * (terminate + relaunch, since netcoredbg advertises no `supportsRestartRequest`).
+ * The exception-breakpoint extra needs no client method (the tool drives `request`
+ * + capabilities directly). `goto` / data breakpoints are intentionally NOT ported:
+ * netcoredbg advertises neither `supportsGotoTargetsRequest` nor
+ * `supportsDataBreakpoints`, so those tools would be dead surface here.
+ */
+export class CsDapClient extends EventEmitter {
+    channel;
+    timeoutMs;
+    seq = 1;
+    pending = new Map();
+    breakpoints = new Map();
+    configured = false;
+    /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
+    watches = [];
+    lastStartMode = null;
+    lastStartArgs = null;
+    capabilities = null;
+    state = "disconnected";
+    lastStoppedThreadId = null;
+    lastStoppedReason = null;
+    constructor(channel, timeoutMs) {
+        super();
+        this.channel = channel;
+        this.timeoutMs = timeoutMs;
+        this.channel.onMessage((m) => this.onMessage(m));
+        this.channel.onClose(() => {
+            this.state = "terminated";
+            this.configured = false;
+            for (const [, p] of this.pending) {
+                clearTimeout(p.timer);
+                p.reject(new DapError(p.command, "C# DAP connection closed"));
+            }
+            this.pending.clear();
+            this.emit("closed");
+        });
+    }
+    onMessage(msg) {
+        const type = msg["type"];
+        if (type === "response") {
+            const reqSeq = msg["request_seq"];
+            const p = this.pending.get(reqSeq);
+            if (!p)
+                return;
+            this.pending.delete(reqSeq);
+            clearTimeout(p.timer);
+            if (msg["success"]) {
+                p.resolve((msg["body"] ?? {}));
+            }
+            else {
+                p.reject(new DapError(String(msg["command"] ?? p.command), String(msg["message"] ?? "C# DAP request failed")));
+            }
+        }
+        else if (type === "event") {
+            this.onEvent(String(msg["event"]), (msg["body"] ?? {}));
+        }
+        else if (type === "request") {
+            // Reverse request (e.g. runInTerminal). Ack success so the adapter never stalls.
+            void this.channel.send({
+                seq: this.seq++,
+                type: "response",
+                request_seq: msg["seq"],
+                success: true,
+                command: msg["command"],
+            });
+        }
+    }
+    onEvent(event, body) {
+        switch (event) {
+            case "initialized":
+                this.emit("initialized");
+                break;
+            case "stopped":
+                this.state = "stopped";
+                this.lastStoppedThreadId = body["threadId"] ?? this.lastStoppedThreadId ?? 1;
+                this.lastStoppedReason = body["reason"] ?? null;
+                this.emit("stopped", body);
+                break;
+            case "continued":
+                this.state = "running";
+                break;
+            case "terminated":
+            case "exited":
+                this.state = "terminated";
+                this.emit("terminated", body);
+                break;
+            case "output":
+                this.emit("output", body);
+                break;
+            default:
+                break;
+        }
+    }
+    request(command, args = {}, timeoutMs = this.timeoutMs) {
+        const seq = this.seq++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(seq);
+                reject(new DapError(command, `C# DAP '${command}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(seq, { command, resolve: resolve, reject, timer });
+            this.channel.send({ seq, type: "request", command, arguments: args }).catch((err) => {
+                clearTimeout(timer);
+                this.pending.delete(seq);
+                reject(err);
+            });
+        });
+    }
+    waitEvent(name, timeoutMs) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.removeListener(name, onEvent);
+                resolve();
+            }, timeoutMs);
+            const onEvent = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            this.once(name, onEvent);
+        });
+    }
+    /** Store breakpoints; apply immediately if the session is already configured, else buffer until launch/attach. */
+    async setBreakpoints(path, lines, conditions) {
+        this.breakpoints.set(path, { path, lines, conditions });
+        if (this.configured)
+            return this.applyBreakpoints(path);
+        return { buffered: true, path, lines };
+    }
+    applyBreakpoints(path) {
+        const bp = this.breakpoints.get(path);
+        if (!bp)
+            return Promise.resolve({});
+        return this.request("setBreakpoints", {
+            source: { path },
+            breakpoints: bp.lines.map((line, i) => {
+                const b = { line };
+                const condition = bp.conditions?.[i];
+                if (condition)
+                    b.condition = condition;
+                return b;
+            }),
+        });
+    }
+    // ---- Watch expressions ---------------------------------------------------
+    /** Add expressions to the persistent watch set (deduped, order-preserving). */
+    addWatches(expressions) {
+        for (const e of expressions)
+            if (e && !this.watches.includes(e))
+                this.watches.push(e);
+    }
+    /** Remove specific expressions from the watch set. */
+    removeWatches(expressions) {
+        const drop = new Set(expressions);
+        this.watches = this.watches.filter((e) => !drop.has(e));
+    }
+    /** Clear all watch expressions. */
+    clearWatches() {
+        this.watches = [];
+    }
+    /** The current watch set (a copy). */
+    listWatches() {
+        return [...this.watches];
+    }
+    /**
+     * Evaluate every watch expression in the context of a stopped frame and return
+     * the results. Each is evaluated with DAP `context: "watch"` (the side-effect-free
+     * context IDEs use for watch panels). A single bad expression yields an `error` on
+     * that entry instead of failing the whole call. `timeoutMs` bounds each individual
+     * `evaluate` (callers pass the shorter `csDapEvaluateTimeoutMs`) so a watch the
+     * adapter never answers fails fast on that entry rather than hanging the full DAP
+     * timeout at every stop — mirroring `cs_dbg_evaluate` and the GDScript `DapClient`.
+     */
+    async evaluateWatches(frameId, timeoutMs = this.timeoutMs) {
+        const results = [];
+        for (const expression of this.watches) {
+            try {
+                const body = await this.request("evaluate", { expression, frameId, context: "watch" }, timeoutMs);
+                results.push({ expression, value: String(body["result"] ?? ""), type: String(body["type"] ?? ""), error: null });
+            }
+            catch (err) {
+                const e = err;
+                results.push({ expression, value: "", type: "", error: e.message ?? String(err) });
+            }
+        }
+        return results;
+    }
+    async applyAllBreakpoints() {
+        for (const path of this.breakpoints.keys()) {
+            await this.applyBreakpoints(path).catch(() => undefined);
+        }
+    }
+    /** Full handshake: initialize → launch/attach → (breakpoints) → configurationDone. */
+    async start(mode, args) {
+        this.lastStartMode = mode;
+        this.lastStartArgs = args;
+        // Listen for `initialized` before we ask, so we cannot miss it.
+        const onInit = this.waitEvent("initialized", Math.min(this.timeoutMs, 5000));
+        this.capabilities = await this.request("initialize", {
+            clientID: "breakpoint-mcp",
+            clientName: "Godot Breakpoint MCP",
+            adapterID: "coreclr",
+            pathFormat: "path",
+            linesStartAt1: true,
+            columnsStartAt1: true,
+            supportsRunInTerminalRequest: false,
+        });
+        this.state = "initialized";
+        // Send launch/attach but don't await it yet — many adapters (netcoredbg included)
+        // only resolve it after configurationDone.
+        const startReq = this.request(mode, args);
+        await onInit;
+        await this.applyAllBreakpoints();
+        await this.request("configurationDone", {}).catch(() => undefined);
+        this.configured = true;
+        this.state = "running";
+        // Surface a launch/attach failure if one occurs, but don't hang on success.
+        startReq.catch((err) => this.emit("error", err));
+    }
+    threadId() {
+        return this.lastStoppedThreadId ?? 1;
+    }
+    /**
+     * Issue a resume command (continue / next / stepIn / stepOut) and wait for the
+     * program to settle again — the next `stopped` (hit a breakpoint / step landed)
+     * or `terminated` event — before returning. The stop listener is armed BEFORE
+     * the command is sent so a fast stop can't be missed. If nothing settles within
+     * `waitMs` (e.g. `continue` runs on with no further breakpoint), it resolves with
+     * the current state ("running").
+     */
+    async resume(command, args, waitMs) {
+        const settled = new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timer);
+                this.removeListener("stopped", onStop);
+                this.removeListener("terminated", onTerm);
+                resolve({ state: this.state, reason: this.lastStoppedReason });
+            };
+            const onStop = () => finish();
+            const onTerm = () => finish();
+            const timer = setTimeout(() => {
+                this.removeListener("stopped", onStop);
+                this.removeListener("terminated", onTerm);
+                resolve({ state: this.state, reason: this.lastStoppedReason });
+            }, waitMs);
+            this.once("stopped", onStop);
+            this.once("terminated", onTerm);
+        });
+        // Optimistically mark running so a stale "stopped" isn't reported back.
+        this.state = "running";
+        await this.request(command, args);
+        return settled;
+    }
+    /**
+     * Resolve when the program next settles (`stopped`/`terminated`) or `waitMs`
+     * elapses — the shared wait used after a restart. Listeners are armed by the
+     * caller BEFORE the triggering request is sent so a fast settle can't be missed.
+     */
+    settle(waitMs) {
+        return new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timer);
+                this.removeListener("stopped", onStop);
+                this.removeListener("terminated", onTerm);
+                resolve({ state: this.state, reason: this.lastStoppedReason });
+            };
+            const onStop = () => finish();
+            const onTerm = () => finish();
+            const timer = setTimeout(() => {
+                this.removeListener("stopped", onStop);
+                this.removeListener("terminated", onTerm);
+                resolve({ state: this.state, reason: this.lastStoppedReason });
+            }, waitMs);
+            this.once("stopped", onStop);
+            this.once("terminated", onTerm);
+        });
+    }
+    /**
+     * Restart the debug session. If the adapter advertises `supportsRestartRequest`,
+     * issue a single DAP `restart` (carrying the launch/attach args); otherwise fall
+     * back to `terminate` + a fresh handshake, so restart works on every adapter.
+     * netcoredbg advertises no `supportsRestartRequest`, so in practice the relaunch
+     * path runs. Reuses the last cs_dbg_launch/cs_dbg_attach params; `overrideArgs`
+     * (e.g. a new `stopAtEntry`) are merged over them. `method` tells the caller which
+     * path ran. C# sessions have no scene, so — unlike the GDScript `DapClient` — this
+     * returns no `scene`.
+     */
+    async restart(overrideArgs = {}, waitMs = 15000) {
+        if (!this.lastStartMode || !this.lastStartArgs) {
+            throw new DapError("restart", "no C# debug session to restart — call cs_dbg_launch or cs_dbg_attach first");
+        }
+        const args = { ...this.lastStartArgs, ...overrideArgs };
+        if (this.capabilities?.["supportsRestartRequest"] === true) {
+            // Arm the settle listener before issuing restart so a fast stop isn't missed.
+            const settled = this.settle(waitMs);
+            this.state = "running";
+            await this.request("restart", { arguments: args });
+            this.lastStartArgs = args;
+            const r = await settled;
+            return { method: "restart", state: r.state, reason: r.reason };
+        }
+        // Fallback: ask the debuggee to terminate (best-effort), then re-run the full
+        // initialize → launch/attach → configurationDone handshake with the same args.
+        await this.request("terminate", {}).catch(() => undefined);
+        await this.start(this.lastStartMode, args);
+        return { method: "relaunch", state: this.state, reason: this.lastStoppedReason };
+    }
+    close() {
+        this.channel.close();
+        this.state = "disconnected";
+        this.configured = false;
+    }
+}
+//# sourceMappingURL=csdap.js.map

package/dist/cslsp.js

@@ -0,0 +1,217 @@
+import { fileURLToPath } from "node:url";
+import { LspError } from "./lsp.js";
+/**
+ * Minimal LSP client for the C#/.NET semantic plane (D4 C2). Transport-agnostic:
+ * it drives any `JsonRpcChannel`, so production spawns OmniSharp over stdio
+ * (`StdioChannel`) while unit tests point it at a loopback TCP mock (`FramedConnection`)
+ * exactly as the GDScript `LspClient` tests do.
+ *
+ * It is deliberately a sibling of `LspClient` rather than a shared base class —
+ * matching the codebase's one-client-per-protocol precedent (lsp.ts / dap.ts) —
+ * but reuses `LspError`, `Diagnostic`, and the framing primitives so the protocol
+ * plumbing isn't re-invented. The only C#-specific behaviors are the `csharp`
+ * `languageId` on didOpen and pointing at the C# project root; everything else is
+ * standard LSP the same way Godot's GDScript server is.
+ */
+export class CsLspClient {
+    channel;
+    rootUri;
+    timeoutMs;
+    nextId = 1;
+    pending = new Map();
+    initialized = null;
+    serverCapabilities = null;
+    opened = new Set();
+    diagnostics = new Map();
+    diagWaiters = new Map();
+    /** Absolute project root path (no trailing slash), used to canonicalize URIs. */
+    rootFsPath;
+    constructor(channel, rootUri, timeoutMs) {
+        this.channel = channel;
+        this.rootUri = rootUri;
+        this.timeoutMs = timeoutMs;
+        let root = "";
+        try {
+            root = fileURLToPath(rootUri);
+        }
+        catch {
+            root = rootUri.replace(/^file:\/\//, "");
+        }
+        this.rootFsPath = root.replace(/[\\/]+$/, "");
+        this.channel.onMessage((m) => this.onMessage(m));
+        this.channel.onClose(() => this.onClose());
+    }
+    /**
+     * Reduce any document URI to a stable, project-relative key (e.g. "Player.cs")
+     * so a published-diagnostics URI matches the one we opened the file with,
+     * regardless of how the server spells it (percent-encoded vs literal `file://`).
+     * Mirrors LspClient.diagKey; OmniSharp uses `file://` URIs, but keeping the
+     * `res://` branch costs nothing and keeps the two clients uniform.
+     */
+    diagKey(uri) {
+        let s = uri;
+        try {
+            s = decodeURIComponent(uri);
+        }
+        catch {
+            /* keep raw on malformed encoding */
+        }
+        if (s.startsWith("res://"))
+            return s.slice("res://".length).replace(/^[\\/]+/, "");
+        if (s.startsWith("file://"))
+            s = s.slice("file://".length);
+        if (this.rootFsPath && s.startsWith(this.rootFsPath))
+            s = s.slice(this.rootFsPath.length);
+        return s.replace(/\\/g, "/").replace(/^\/+/, "");
+    }
+    onMessage(msg) {
+        const id = msg["id"];
+        const method = msg["method"];
+        // Response to one of our requests.
+        if (typeof id === "number" && method === undefined) {
+            const p = this.pending.get(id);
+            if (!p)
+                return;
+            this.pending.delete(id);
+            clearTimeout(p.timer);
+            if (msg["error"]) {
+                const e = msg["error"];
+                p.reject(new LspError(e.code ?? -1, e.message ?? "LSP error"));
+            }
+            else {
+                p.resolve(msg["result"] ?? null);
+            }
+            return;
+        }
+        // Server -> client notification.
+        if (typeof method === "string" && id === undefined) {
+            if (method === "textDocument/publishDiagnostics") {
+                const params = (msg["params"] ?? {});
+                const uri = params.uri ?? "";
+                const diags = (params.diagnostics ?? []).map((d) => {
+                    const dd = d;
+                    return {
+                        severity: dd.severity ?? 1,
+                        message: dd.message ?? "",
+                        line: dd.range?.start?.line ?? 0,
+                        character: dd.range?.start?.character ?? 0,
+                    };
+                });
+                const key = this.diagKey(uri);
+                this.diagnostics.set(key, diags);
+                const waiters = this.diagWaiters.get(key);
+                if (waiters) {
+                    this.diagWaiters.delete(key);
+                    for (const w of waiters)
+                        w();
+                }
+            }
+            return;
+        }
+        // Server -> client request (e.g. client/registerCapability, or OmniSharp's
+        // window/workDoneProgress/create): ack with null so the server never blocks
+        // waiting for us.
+        if (typeof method === "string" && typeof id === "number") {
+            void this.channel.send({ jsonrpc: "2.0", id, result: null });
+        }
+    }
+    onClose() {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new LspError("closed", "C# LSP connection closed"));
+        }
+        this.pending.clear();
+        this.initialized = null;
+        this.serverCapabilities = null;
+        this.opened.clear();
+    }
+    rawRequest(method, params, timeoutMs = this.timeoutMs) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new LspError("timeout", `C# LSP '${method}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            this.channel.send({ jsonrpc: "2.0", id, method, params }).catch((err) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(err);
+            });
+        });
+    }
+    notify(method, params) {
+        return this.channel.send({ jsonrpc: "2.0", method, params });
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            this.initialized = (async () => {
+                const result = (await this.rawRequest("initialize", {
+                    processId: process.pid,
+                    rootUri: this.rootUri,
+                    rootPath: decodeURIComponent(this.rootUri.replace(/^file:\/\//, "")),
+                    capabilities: {
+                        textDocument: {
+                            synchronization: { didSave: true, dynamicRegistration: false },
+                            completion: { completionItem: { snippetSupport: false } },
+                            hover: { contentFormat: ["plaintext", "markdown"] },
+                            definition: {},
+                            references: {},
+                            documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+                            signatureHelp: {},
+                            publishDiagnostics: {},
+                        },
+                        workspace: { symbol: {}, workspaceFolders: true },
+                    },
+                    workspaceFolders: [{ uri: this.rootUri, name: "csharp-project" }],
+                    clientInfo: { name: "breakpoint-mcp", version: "0.2.0" },
+                }));
+                this.serverCapabilities = result?.capabilities ?? {};
+                await this.notify("initialized", {});
+                return result;
+            })();
+        }
+        return this.initialized;
+    }
+    async request(method, params, timeoutMs) {
+        await this.ensureInitialized();
+        return this.rawRequest(method, params, timeoutMs);
+    }
+    /**
+     * The server's advertised capabilities from the `initialize` handshake (an
+     * empty object if none). Lets a cs_* tool feature-detect an optional LSP method
+     * before calling it, instead of surfacing a raw `-32601 Method not found`.
+     */
+    async getServerCapabilities() {
+        await this.ensureInitialized();
+        return this.serverCapabilities ?? {};
+    }
+    async ensureOpen(uri, text) {
+        if (this.opened.has(uri))
+            return;
+        await this.ensureInitialized();
+        this.opened.add(uri);
+        await this.notify("textDocument/didOpen", {
+            textDocument: { uri, languageId: "csharp", version: 1, text },
+        });
+    }
+    /** Return cached diagnostics for a URI, waiting up to timeoutMs for the first publish. */
+    waitForDiagnostics(uri, timeoutMs) {
+        const key = this.diagKey(uri);
+        if (this.diagnostics.has(key))
+            return Promise.resolve(this.diagnostics.get(key));
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(this.diagnostics.get(key) ?? []), timeoutMs);
+            const arr = this.diagWaiters.get(key) ?? [];
+            arr.push(() => {
+                clearTimeout(timer);
+                resolve(this.diagnostics.get(key) ?? []);
+            });
+            this.diagWaiters.set(key, arr);
+        });
+    }
+    close() {
+        this.channel.close();
+    }
+}
+//# sourceMappingURL=cslsp.js.map