npm - @i-scope/mcp-server - Versions diffs - 0.4.2 - Mend

@i-scope/mcp-server 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

package/CHANGELOG.md +147 -0
package/LICENSE +21 -0
package/README.md +373 -0
package/dist/src/abi-check.d.ts +19 -0
package/dist/src/abi-check.js +66 -0
package/dist/src/bridge-driver.d.ts +90 -0
package/dist/src/bridge-driver.js +290 -0
package/dist/src/dap-client.d.ts +80 -0
package/dist/src/dap-client.js +296 -0
package/dist/src/dap-driver.d.ts +162 -0
package/dist/src/dap-driver.js +703 -0
package/dist/src/index.d.ts +3 -0
package/dist/src/index.js +175 -0
package/dist/src/state.d.ts +86 -0
package/dist/src/state.js +15 -0
package/dist/src/tools/abi-check.d.ts +3 -0
package/dist/src/tools/abi-check.js +64 -0
package/dist/src/tools/breakpoints.d.ts +3 -0
package/dist/src/tools/breakpoints.js +56 -0
package/dist/src/tools/execution.d.ts +3 -0
package/dist/src/tools/execution.js +75 -0
package/dist/src/tools/helpers.d.ts +27 -0
package/dist/src/tools/helpers.js +134 -0
package/dist/src/tools/inspection.d.ts +3 -0
package/dist/src/tools/inspection.js +141 -0
package/dist/src/tools/lifecycle.d.ts +3 -0
package/dist/src/tools/lifecycle.js +103 -0
package/dist/src/tools/preflight.d.ts +3 -0
package/dist/src/tools/preflight.js +95 -0
package/dist/src/tools/registry.d.ts +15 -0
package/dist/src/tools/registry.js +19 -0
package/dist/src/tools/snapshot.d.ts +3 -0
package/dist/src/tools/snapshot.js +117 -0
package/dist/src/tools/source-maps.d.ts +3 -0
package/dist/src/tools/source-maps.js +232 -0
package/dist/src/tools/sync.d.ts +3 -0
package/dist/src/tools/sync.js +80 -0
package/dist/src/tools/ui-modal.d.ts +3 -0
package/dist/src/tools/ui-modal.js +182 -0
package/package.json +73 -0
package/src/abi-check.ts +97 -0
package/src/bridge-driver.ts +328 -0
package/src/dap-client.ts +336 -0
package/src/dap-driver.ts +810 -0
package/src/index.ts +155 -0
package/src/state.ts +115 -0
package/src/tools/abi-check.ts +66 -0
package/src/tools/breakpoints.ts +59 -0
package/src/tools/execution.ts +105 -0
package/src/tools/helpers.ts +142 -0
package/src/tools/inspection.ts +173 -0
package/src/tools/lifecycle.ts +129 -0
package/src/tools/preflight.ts +95 -0
package/src/tools/registry.ts +34 -0
package/src/tools/snapshot.ts +132 -0
package/src/tools/source-maps.ts +222 -0
package/src/tools/sync.ts +90 -0
package/src/tools/ui-modal.ts +201 -0

package/dist/src/dap-client.js ADDED Viewed

@@ -0,0 +1,296 @@
+"use strict";
+// Minimal stand-alone Debug Adapter Protocol client.
+//
+// Why we don't reuse @vscode/debugadapter-testsupport:
+//   That package is Microsoft's own test harness — fine for the
+//   adapter author, BUT (a) the name screams "test only" and scares
+//   anyone reading our published package.json, and (b) it's a
+//   *testsupport* artefact: Microsoft do not promise API stability
+//   across minor versions. A breaking change in a 1.69.x → 1.70.x
+//   bump would silently break every npm install of our MCP server.
+//
+//   The wire is just JSON-over-stdio with a `Content-Length: N\r\n
+//   \r\n<body>` framing — too small to justify a runtime dependency
+//   for a public package. Hence: ~250 LOC of our own, tailored to
+//   the surface DapDriver actually needs.
+//
+// Surface (intentionally narrower than DebugClient's):
+//   - `start()` / `stop()` lifecycle.
+//   - `request<T>(command, args?, timeoutMs?)` → resolves with
+//     `response.body` (or rejects with the response.message).
+//   - `waitForEvent<T>(name, timeoutMs?)` → resolves with the next
+//     event of that name.
+//   - EventEmitter semantics for unsolicited events (`output`,
+//     `stopped`, `continued`, `terminated`, `exited`, ...) — callers
+//     attach `.on(name, handler)` like they would on any Node
+//     EventEmitter.
+//
+// Out of scope (versus DebugClient):
+//   - Convenience wrappers like `initializeRequest(args)` —
+//     `dc.request('initialize', args)` is enough.
+//   - Reverse requests (the server's `request` direction, e.g.
+//     `runInTerminal`). The iScope adapter never issues those.
+//   - `hitBreakpoint()` / `assertStoppedLocation()` test helpers.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DapClient = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_events_1 = require("node:events");
+const NO_LOG = (_) => { };
+/**
+ * Stand-alone DAP client. Inherits from EventEmitter for event
+ * subscription. Type-safe `request<T>` and `waitForEvent<T>` give
+ * callers the response body / event payload directly.
+ */
+class DapClient extends node_events_1.EventEmitter {
+    runtime;
+    executable;
+    args;
+    env;
+    cwd;
+    inheritStderr;
+    log;
+    child = null;
+    childExited = false;
+    /** Monotonic outgoing message id. DAP spec: `seq` is per-sender
+     *  and increases by one per message; the OTHER side has its own
+     *  `seq` axis we ignore. */
+    nextSeq = 1;
+    /** Accumulating stdout buffer. We pull complete frames out of
+     *  it as they arrive. Type widened to ArrayBufferLike to match
+     *  what `Buffer.concat` and `Buffer#subarray` return in
+     *  @types/node 22+. */
+    rxBuffer = Buffer.alloc(0);
+    /** Once we see `Content-Length: N\r\n\r\n` we remember N here
+     *  until we've consumed exactly N bytes of body. -1 = "still
+     *  parsing the header". */
+    rxContentLength = -1;
+    /** seq → outstanding request. We never await a response by
+     *  `command` alone — two simultaneous `stackTrace`s would
+     *  collide. `seq` is the only safe key. */
+    pending = new Map();
+    defaultTimeoutMs;
+    constructor(opts) {
+        super();
+        this.runtime = opts.runtime ?? 'node';
+        this.executable = opts.executable;
+        this.args = opts.args ?? [];
+        this.env = opts.env ?? process.env;
+        this.cwd = opts.cwd;
+        this.inheritStderr = opts.inheritStderr ?? true;
+        this.log = opts.log ?? NO_LOG;
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 30_000;
+    }
+    /** Spawn the adapter child. Returns once `spawn()` has been
+     *  called — the child may still be initialising. Callers
+     *  immediately issue `request('initialize', ...)` and the DAP
+     *  request/response framing handles the rest. */
+    async start() {
+        if (this.child) {
+            throw new Error('DapClient.start: already started');
+        }
+        const argv = [this.executable, ...this.args];
+        const child = (0, node_child_process_1.spawn)(this.runtime, argv, {
+            env: this.env,
+            cwd: this.cwd,
+            stdio: ['pipe', 'pipe', this.inheritStderr ? 'inherit' : 'pipe'],
+            windowsHide: true,
+        });
+        this.child = child;
+        this.childExited = false;
+        // Stdout is the DAP wire. Stderr (if piped) is diagnostic
+        // chatter — we forward it via `log` so it doesn't poison the
+        // wire by accident.
+        const stdout = child.stdout;
+        const stdin = child.stdin;
+        if (!stdout || !stdin) {
+            throw new Error('DapClient.start: child has no stdio pipes');
+        }
+        stdout.on('data', (chunk) => this.onStdoutChunk(chunk));
+        stdout.on('error', (e) => this.log(`[dap-client] stdout error: ${e.message}`));
+        stdin.on('error', (e) => this.log(`[dap-client] stdin error: ${e.message}`));
+        if (!this.inheritStderr && child.stderr) {
+            child.stderr.on('data', (chunk) => {
+                this.log(`[dap-child stderr] ${chunk.toString('utf8').replace(/\n$/, '')}`);
+            });
+        }
+        child.on('exit', (code, signal) => {
+            this.childExited = true;
+            this.log(`[dap-client] child exited code=${code} signal=${signal ?? '-'}`);
+            // Fail any in-flight requests. Without this they would
+            // hang on the timeout — bad UX when the child crashed
+            // 200 ms ago.
+            const reason = `child process exited (code=${code} signal=${signal ?? '-'})`;
+            for (const p of this.pending.values()) {
+                clearTimeout(p.timer);
+                p.reject(new Error(`DAP request '${p.command}' failed: ${reason}`));
+            }
+            this.pending.clear();
+            this.emit('exited', { code, signal });
+        });
+        child.on('error', (err) => {
+            this.log(`[dap-client] spawn error: ${err.message}`);
+            this.emit('error', err);
+        });
+    }
+    /** Send a request and resolve with `response.body`. Rejects on
+     *  - timeout (after `timeoutMs ?? this.defaultTimeoutMs`),
+     *  - protocol-level failure (`response.success === false`),
+     *  - child process exit (the exit handler nukes pending). */
+    request(command, args, timeoutMs) {
+        if (!this.child || this.childExited || !this.child.stdin) {
+            return Promise.reject(new Error(`DAP request '${command}': no live child`));
+        }
+        const seq = this.nextSeq++;
+        const message = { seq, type: 'request', command, arguments: args };
+        const json = JSON.stringify(message);
+        const header = `Content-Length: ${Buffer.byteLength(json, 'utf8')}\r\n\r\n`;
+        try {
+            this.child.stdin.write(header + json, 'utf8');
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return Promise.reject(new Error(`DAP request '${command}' write failed: ${msg}`));
+        }
+        const wait = timeoutMs ?? this.defaultTimeoutMs;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(seq);
+                reject(new Error(`DAP request '${command}' timed out after ${wait}ms`));
+            }, wait);
+            this.pending.set(seq, {
+                resolve: (body) => resolve(body),
+                reject,
+                timer,
+                command,
+            });
+        });
+    }
+    /** Resolve with the next event of the given name. Honours a
+     *  timeout to avoid hanging on tests that never fire the event
+     *  they expect. */
+    waitForEvent(name, timeoutMs) {
+        const wait = timeoutMs ?? this.defaultTimeoutMs;
+        return new Promise((resolve, reject) => {
+            const handler = (ev) => {
+                clearTimeout(timer);
+                resolve(ev);
+            };
+            const timer = setTimeout(() => {
+                this.off(name, handler);
+                reject(new Error(`DAP event '${name}' did not arrive within ${wait}ms`));
+            }, wait);
+            this.once(name, handler);
+        });
+    }
+    /** Tear the child down. Graceful path: close stdin → child sees
+     *  EOF → exits → we resolve. Fallback path: after `gracefulMs`,
+     *  SIGTERM; after another second, SIGKILL. Either way the
+     *  Promise always resolves; we never throw from cleanup. */
+    async stop(gracefulMs = 2_000) {
+        const child = this.child;
+        if (!child)
+            return;
+        if (this.childExited) {
+            this.child = null;
+            return;
+        }
+        try {
+            child.stdin?.end();
+        }
+        catch { /* already closed */ }
+        await new Promise((resolve) => {
+            const onExit = () => {
+                clearTimeout(termTimer);
+                clearTimeout(killTimer);
+                resolve();
+            };
+            const termTimer = setTimeout(() => {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* ignore */ }
+            }, gracefulMs);
+            const killTimer = setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* ignore */ }
+                // Whether or not SIGKILL got through, give Node one
+                // more tick to fire 'exit'; otherwise resolve anyway.
+                setTimeout(resolve, 100);
+            }, gracefulMs + 1_000);
+            child.once('exit', onExit);
+        });
+        this.child = null;
+    }
+    // ---- internals --------------------------------------------------
+    onStdoutChunk(chunk) {
+        this.rxBuffer = this.rxBuffer.length === 0
+            ? chunk
+            : Buffer.concat([this.rxBuffer, chunk]);
+        // Drain as many complete frames as fit in the buffer right
+        // now. One stdout chunk can carry many frames (e.g. a flood
+        // of output events after launch); equally one frame can
+        // arrive in several chunks (when the adapter writes a big
+        // variables[] body).
+        while (true) {
+            if (this.rxContentLength < 0) {
+                const headerEnd = this.rxBuffer.indexOf('\r\n\r\n');
+                if (headerEnd < 0)
+                    break;
+                const headers = this.rxBuffer.subarray(0, headerEnd).toString('ascii');
+                let length = -1;
+                for (const line of headers.split('\r\n')) {
+                    const m = /^Content-Length:\s*(\d+)$/i.exec(line);
+                    if (m)
+                        length = parseInt(m[1], 10);
+                }
+                if (length < 0) {
+                    this.log(`[dap-client] missing Content-Length in headers; dropping ${headerEnd + 4} bytes and resyncing`);
+                    this.rxBuffer = this.rxBuffer.subarray(headerEnd + 4);
+                    continue;
+                }
+                this.rxContentLength = length;
+                this.rxBuffer = this.rxBuffer.subarray(headerEnd + 4);
+            }
+            if (this.rxBuffer.length < this.rxContentLength)
+                break;
+            const body = this.rxBuffer.subarray(0, this.rxContentLength).toString('utf8');
+            this.rxBuffer = this.rxBuffer.subarray(this.rxContentLength);
+            this.rxContentLength = -1;
+            try {
+                this.dispatch(JSON.parse(body));
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                this.log(`[dap-client] failed to parse incoming message (${body.length}B): ${msg}`);
+            }
+        }
+    }
+    dispatch(msg) {
+        if (msg.type === 'response') {
+            const seq = msg.request_seq ?? -1;
+            const p = this.pending.get(seq);
+            if (!p)
+                return;
+            this.pending.delete(seq);
+            clearTimeout(p.timer);
+            if (msg.success === false) {
+                p.reject(new Error(msg.message || `DAP request '${p.command}' failed`));
+            }
+            else {
+                p.resolve(msg.body);
+            }
+            return;
+        }
+        if (msg.type === 'event' && typeof msg.event === 'string') {
+            this.emit(msg.event, msg);
+            return;
+        }
+        // type='request' from the server (e.g. runInTerminal) is the
+        // only other DAP message kind. The iScope adapter never sends
+        // those; ignore.
+    }
+}
+exports.DapClient = DapClient;
+//# sourceMappingURL=dap-client.js.map

package/dist/src/dap-driver.d.ts ADDED Viewed

@@ -0,0 +1,162 @@
+import type { DebugProtocol } from '@vscode/debugprotocol';
+import { DapClient } from './dap-client.js';
+import type { FrameInfo, OutputEntry, SessionState, StoppedInfo, ExecutionTransition, TerminationInfo } from './state.js';
+export interface DapDriverOptions {
+    /** Optional bundled-root override forwarded to the spawned DAP
+     *  server as `ISCOPE_EXTENSION_PATH`. Useful only when the caller
+     *  ships its own copy of `iScopeBridge.exe` and wants it to win
+     *  over the npm-installed `@i-scope/iscope-bridge`. Leave undefined
+     *  for the standard "everything via npm" deployment — the
+     *  bridge-client will resolve the binary from the installed
+     *  `@i-scope/iscope-bridge` package automatically. */
+    extensionPath?: string;
+    /** Default per-DAP-request timeout. Defaults to 30 000 ms. */
+    defaultTimeoutMs?: number;
+    /** Maximum buffered Host.ReportOut + console entries before the
+     *  oldest get dropped. Defaults to 2000. */
+    outputBufferSize?: number;
+    /** Optional log function for MCP-server-side diagnostics. Writes
+     *  go to stderr by default (stdout is reserved for the MCP wire).
+     *  Use this if you want to redirect to a file. */
+    log?: (line: string) => void;
+}
+export interface LaunchToolArgs {
+    program: string;
+    mwfFile?: string;
+    autoLaunch?: boolean;
+    openFileBeforeRun?: boolean | null;
+    stopOnEntry?: boolean | 'auto';
+    oscilloscopePath?: string;
+    helperPath?: string;
+    outFiles?: string[];
+    /** Override per-request timeout for this `launch` (covers the
+     *  initial spawn + initialize round-trip). */
+    timeoutMs?: number;
+}
+/** Promise-chain mutex. Each `runExclusive(fn)` waits for the prior
+ *  one to settle, then runs `fn`. No re-entrancy — if a tool handler
+ *  re-enters runExclusive from inside its own callback it WILL
+ *  deadlock. (Tools are designed to never do that.)
+ *
+ *  Exported for unit testing. The MCP server itself doesn't need to
+ *  re-export it.
+ */
+export declare class Mutex {
+    private tail;
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+}
+export declare class DapDriver {
+    private readonly extensionPath;
+    private readonly debugServerJs;
+    private readonly defaultTimeoutMs;
+    private readonly outputBufferSize;
+    private readonly log;
+    private client;
+    private state;
+    /** Source-map manager used to fill `generatedSource`/`generatedLine`
+     *  on mapped frames (and to surface unmapped-fallback warnings).
+     *  Lazily created on first launch and reset on disconnect so a
+     *  fresh session always parses the current `.ajs.map` from disk. */
+    private sourceMaps;
+    /** Absolute path to the generated `.ajs` for the current launch.
+     *  Used by `classifyFrame` to ask the manager for reverse mappings
+     *  without re-resolving the sibling each call. Empty when launch
+     *  was against a `.ajs` (then `generatedAjs === program`). */
+    private generatedAjs;
+    /** Once-per-launch dedup for unmapped-fallback warning messages.
+     *  Without it the same warning would land in the output buffer on
+     *  every stack_trace call. Key: `<source>:<line>:<col>`. */
+    private readonly unmappedWarned;
+    /** Args from the most recent launch. Used to classify
+     *  `sourceOrigin` on frames returned by stackTrace. */
+    private launchArgs;
+    /** Lower-case basename extension of `launchArgs.program`, e.g.
+     *  `.ts` or `.ajs`. Cached so frame-mapping doesn't repeat
+     *  `path.extname()` per frame. */
+    private programIsTs;
+    /** Circular output buffer; oldest entries dropped first when full. */
+    private readonly outputBuffer;
+    private outputNextId;
+    /** Last `stopped` snapshot — refreshed on every StoppedEvent.
+     *  Used by `current_state` tool and by step/continue tools that
+     *  want to read frames straight from cache before calling
+     *  stack_trace explicitly. */
+    private lastStopped;
+    /** Termination metadata captured when DAP emits `terminated`. */
+    private terminationInfo;
+    /** Pending step/continue/wait_for_paused awaiters. Resolved on
+     *  the next state transition. */
+    private pendingWaits;
+    private readonly mutex;
+    constructor(opts: DapDriverOptions);
+    getState(): SessionState;
+    getStoppedSnapshot(): StoppedInfo | null;
+    getTerminationInfo(): TerminationInfo | null;
+    /** Was the most recent launch against a `.ts` file? Tool layer
+     *  uses this to bake `sourceOrigin` into frames without
+     *  re-inspecting `launchArgs`. */
+    isTsLaunch(): boolean;
+    /** Snapshot of buffered Output entries with id > cursor.
+     *  AI passes `nextCursor` from the previous read to get the tail.
+     *  Lock-free; never mutates state. */
+    readOutput(cursor: number, limit?: number): {
+        entries: OutputEntry[];
+        nextCursor: number;
+    };
+    launch(args: LaunchToolArgs): Promise<ExecutionTransition>;
+    disconnect(): Promise<void>;
+    setBreakpoints(source: string, lines: number[]): Promise<DebugProtocol.SetBreakpointsResponse['body']>;
+    /** continue / step_* / wait_for_paused all funnel through this
+     *  helper. `dapCall` returns the DAP response Promise; we await
+     *  the resulting state transition (stopped / terminated / timeout)
+     *  and return it.
+     *
+     *  `dapCall` may be null for `wait_for_paused` (no request to
+     *  send — just observe). */
+    resumeAndWait(dapCall: ((dc: DapClient) => Promise<unknown>) | null, timeoutMs?: number): Promise<ExecutionTransition>;
+    stackTrace(): Promise<DebugProtocol.StackTraceResponse['body']>;
+    scopes(frameId: number): Promise<DebugProtocol.ScopesResponse['body']>;
+    variables(variablesReference: number): Promise<DebugProtocol.VariablesResponse['body']>;
+    evaluate(expression: string, frameId: number | undefined, context: 'watch' | 'hover' | 'repl'): Promise<DebugProtocol.EvaluateResponse['body']>;
+    /** Convert a DAP StackFrame into our richer FrameInfo with
+     *  sourceOrigin annotation AND fully-populated generatedSource/
+     *  generatedLine/generatedColumn fields.
+     *
+     *  Algorithm:
+     *    - launch with `.ajs`  → frame is always `generated`.
+     *      generatedSource = frame.source.
+     *    - launch with `.ts` and frame.source ends in `.ts` →
+     *      `mapped`. Reverse-look the TS coords up in our SourceMap
+     *      Manager to get the corresponding `.ajs` coords (so the AI
+     *      can cross-reference engine offsets even when reading TS).
+     *      If the reverse lookup fails we still classify as mapped
+     *      but leave generatedSource/Line undefined.
+     *    - launch with `.ts` and frame.source ends in `.ajs` →
+     *      `unmapped-fallback` (adapter could not translate this
+     *      specific line; AI sees raw engine position). We also
+     *      buffer ONE console-category OutputEntry per unique
+     *      <source:line:col> tuple so `debug_read_output` surfaces
+     *      the gap as a visible warning. */
+    classifyFrame(f: DebugProtocol.StackFrame): Promise<FrameInfo>;
+    /** Buffer a single console-category warning per unique
+     *  <source:line:col>. AI sees it via `debug_read_output` and can
+     *  decide whether to ignore or to ask the user to rebuild with
+     *  better source-map coverage. */
+    private warnUnmappedFallback;
+    private wireClientEvents;
+    private waitForTransition;
+    private resolvePendingWaits;
+    private failPendingWaits;
+    private removePending;
+    private snapshotTransition;
+    private requireClient;
+    private resetSessionState;
+    /** Resolve and preload `.ajs.map` candidates for this launch.
+     *  Stores the resolved generated `.ajs` path in `generatedAjs` so
+     *  `classifyFrame` can run reverse-mapping lookups without re-
+     *  guessing the sibling each time. */
+    private initSourceMaps;
+    private basename;
+    private errMsg;
+}
+//# sourceMappingURL=dap-driver.d.ts.map