crosspad-mcp-server 8.1.2 → 9.0.0

package/dist/tools/trace-session.js

@@ -0,0 +1,346 @@
+import { spawn } from "child_process";
+import path from "path";
+import fs from "fs";
+import { TraceBuffer } from "./trace-buffer.js";
+import { daemonPath, resolvedPython, resolvedElf } from "./trace-symbols.js";
+import { resolveConfigValue } from "../utils/userConfig.js";
+import { TRACE_DIR_DEFAULT } from "../config.js";
+/** Pure: parse one NDJSON line from the daemon into a Frame, or null. */
+export function parseFrame(line) {
+    const s = line.trim();
+    if (!s.startsWith("{"))
+        return null;
+    try {
+        const o = JSON.parse(s);
+        if (o.type === "sample" && o.values)
+            return o;
+        if (o.type === "status" && o.device_state)
+            return o;
+        if (o.type === "error" && o.error)
+            return o;
+        if (o.type === "signals" && Array.isArray(o.signals)) {
+            if (!Array.isArray(o.unresolved))
+                o.unresolved = [];
+            return o;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export class TraceSession {
+    opts;
+    proc = null;
+    buffer;
+    deviceState = "starting";
+    startedAt = 0;
+    filePath = null;
+    stdoutBuf = "";
+    onFrameExtra = null;
+    // Pending add/remove resolvers, fired (FIFO) on the next "signals" frame so
+    // the MCP/UI sees the POST-reconcile set (PROTOCOL §4). Each carries a timeout
+    // handle so a missing frame can't hang the caller forever.
+    pendingReconcile = [];
+    // ── §11.5 guaranteed teardown ──────────────────────────────────────────
+    // stop() escalates {cmd:stop} → SIGTERM → SIGKILL. These hold the pending
+    // escalation timers so a clean exit can cancel them (no stray kill) and so a
+    // second stop() is idempotent.
+    termTimer = null;
+    killTimer = null;
+    // ── §11.6 daemon stderr ring + start truthfulness ──────────────────────
+    // Ring of the last STDERR_RING lines of daemon stderr (human logs + any
+    // libusb noise) so a non-zero exit can surface *why* via stderrTail().
+    static STDERR_RING = 30;
+    stderrLines = [];
+    stderrBuf = "";
+    // Did we ever ingest an `error` frame? a non-zero exit with no error frame
+    // means the daemon died unexpectedly → synthesize device_state from stderr.
+    sawErrorFrame = false;
+    // Resolvers for waitForFirstFrame(), fired on the first ingested frame.
+    firstFrameSeen = false;
+    firstFrameWaiters = [];
+    constructor(opts) {
+        this.opts = opts;
+        this.buffer = new TraceBuffer(opts.signals, opts.capacity ?? 200_000);
+    }
+    onFrame(cb) { this.onFrameExtra = cb; }
+    /** Detach the frame sink so late `sample`/`status` frames during a shutdown
+     *  race aren't rebroadcast after `trace_end`, and the consumer (Dashboard)
+     *  doesn't hold this session longer than necessary. */
+    offFrame() { this.onFrameExtra = null; }
+    // Fired once when the daemon process is truly gone (clean exit, kill, or
+    // spawn error). Lets callers defer teardown (dashboard unbind, clearing the
+    // active session) until the probe is actually free — see §11.5.
+    stoppedCbs = [];
+    /** Register a callback for when the daemon process has fully exited. If the
+     *  process is already gone, fires synchronously. */
+    onStopped(cb) {
+        if (this.proc === null) {
+            cb();
+            return;
+        }
+        this.stoppedCbs.push(cb);
+    }
+    fireStopped() {
+        const cbs = this.stoppedCbs;
+        this.stoppedCbs = [];
+        for (const cb of cbs) {
+            try {
+                cb();
+            }
+            catch { /* */ }
+        }
+    }
+    /** The ELF this session traces against (explicit opt or the configured default).
+     *  Used by the web UI's /symbols endpoint so autocomplete matches the trace. */
+    elfPath() { return this.opts.elf ?? resolvedElf(); }
+    start() {
+        const traceDir = resolveConfigValue("trace_dir", "CROSSPAD_TRACE_DIR", process.env.CROSSPAD_TRACE_DIR, TRACE_DIR_DEFAULT);
+        fs.mkdirSync(traceDir, { recursive: true });
+        this.filePath = this.opts.outFile ?? path.join(traceDir, `trace-${process.pid}.cptrace`);
+        const argv = [daemonPath(), "trace", "--elf", this.opts.elf ?? resolvedElf(),
+            "--signals", this.opts.signals.join(","), "--rate", String(this.opts.rateHz), "--out", this.filePath];
+        const probe = resolveConfigValue("probe_serial", "CROSSPAD_PROBE_SERIAL", process.env.CROSSPAD_PROBE_SERIAL, "");
+        if (probe)
+            argv.push("--probe", probe);
+        // EXPERIMENTAL: SWO/ITM channel decode (opt-in; fail-soft in daemon).
+        if (this.opts.swo && this.opts.swo.length > 0) {
+            argv.push("--swo", this.opts.swo.join(","));
+        }
+        this.proc = spawn(resolvedPython(), argv, { stdio: ["pipe", "pipe", "pipe"] });
+        this.startedAt = performance.now();
+        // §11.4: honest pre-first-frame state. start() upgrades this to "running"
+        // only once a real signals/sample frame lands (see waitForFirstFrame).
+        this.deviceState = "connecting";
+        this.proc.stdout?.on("data", (c) => this.ingest(c.toString()));
+        // §11.6: capture daemon stderr into a bounded ring so a non-zero exit can
+        // explain itself (the daemon's human logs + any libusb noise go here).
+        this.proc.stderr?.on("data", (c) => this.ingestStderr(c.toString()));
+        this.proc.on("exit", (code) => this.onExit(code));
+        // A bad interpreter path (race after doctor) emits 'error' — handle it so it
+        // never bubbles up as an uncaught exception that crashes the MCP server.
+        this.proc.on("error", (e) => {
+            this.deviceState = "spawn_failed: " + e.message;
+            this.proc = null;
+            this.clearKillTimers();
+            this.resolveFirstFrame(null);
+            this.fireStopped();
+        });
+    }
+    /** §11.6: fold daemon stderr into a bounded ring (last STDERR_RING lines). */
+    ingestStderr(text) {
+        this.stderrBuf += text;
+        const parts = this.stderrBuf.split("\n");
+        this.stderrBuf = parts.pop() ?? "";
+        for (const line of parts) {
+            const s = line.replace(/\r$/, "");
+            if (s.length === 0)
+                continue;
+            this.stderrLines.push(s);
+        }
+        if (this.stderrLines.length > TraceSession.STDERR_RING) {
+            this.stderrLines.splice(0, this.stderrLines.length - TraceSession.STDERR_RING);
+        }
+    }
+    /** §11.6: the last `n` captured daemon stderr lines, newest last. */
+    stderrTail(n = TraceSession.STDERR_RING) {
+        return this.stderrLines.slice(-n).join("\n");
+    }
+    /** Daemon exited. §11.6: if it died non-zero WITHOUT emitting an error frame,
+     *  synthesize an `error: <stderr tail>` device_state so status/start never
+     *  reports a stale "running" for a process that's actually dead. */
+    onExit(code) {
+        if (code && code !== 0 && !this.sawErrorFrame) {
+            const last = this.stderrLines[this.stderrLines.length - 1];
+            this.deviceState = "error: " + (last && last.length > 0 ? last : `daemon exited code ${code}`);
+        }
+        else if (this.deviceState === "connecting" || this.deviceState === "running") {
+            // Clean (or already-error) exit with no lingering fault → mark exited.
+            this.deviceState = "exited";
+        }
+        this.proc = null;
+        this.clearKillTimers();
+        // Unblock any start() still waiting — the process is gone.
+        this.resolveFirstFrame(null);
+        this.fireStopped();
+    }
+    ingest(text) {
+        this.stdoutBuf += text;
+        const parts = this.stdoutBuf.split("\n");
+        this.stdoutBuf = parts.pop() ?? "";
+        for (const line of parts) {
+            const f = parseFrame(line);
+            if (!f)
+                continue;
+            // §11.6: the first machine frame (signals|sample|error) unblocks start().
+            this.resolveFirstFrame(f);
+            if (f.type === "sample") {
+                this.buffer.push({ t: f.t, values: f.values });
+                this.deviceState = "running";
+            }
+            else if (f.type === "status")
+                this.deviceState = f.device_state;
+            else if (f.type === "error") {
+                this.deviceState = "error: " + f.error;
+                this.sawErrorFrame = true;
+            }
+            else if (f.type === "signals") {
+                this.reconcileSignals(f.signals.map((s) => s.name));
+                // Resolve the oldest pending add/remove with the now-reconciled set.
+                const pend = this.pendingReconcile.shift();
+                if (pend) {
+                    clearTimeout(pend.timer);
+                    pend.resolve(this.buffer.signalNames());
+                }
+            }
+            this.onFrameExtra?.(f);
+        }
+    }
+    /** Reconcile the buffer's watched-signal set to match the daemon's authoritative
+     *  list (from a "signals" frame): add any new names, drop any no longer present. */
+    reconcileSignals(names) {
+        const want = new Set(names);
+        for (const have of this.buffer.signalNames()) {
+            if (!want.has(have))
+                this.buffer.removeSignal(have);
+        }
+        for (const n of names)
+            this.buffer.addSignal(n);
+    }
+    /** Add signals to the live poll set (NDJSON `add` to daemon stdin).
+     *  Resolves with the POST-reconcile signal-name set once the daemon's next
+     *  "signals" frame is ingested (PROTOCOL §4); ~2 s timeout → resolves with the
+     *  current `buffer.signalNames()` so a missing frame never hangs the caller. */
+    addSignals(specs) {
+        if (!this.proc?.stdin)
+            throw new Error("No running trace to add signals to.");
+        this.proc.stdin.write(JSON.stringify({ cmd: "add", signals: specs }) + "\n");
+        return this.awaitReconcile();
+    }
+    /** Remove signals from the live poll set (NDJSON `remove` to daemon stdin).
+     *  Same post-reconcile / timeout contract as addSignals. */
+    removeSignals(specs) {
+        if (!this.proc?.stdin)
+            throw new Error("No running trace to remove signals from.");
+        this.proc.stdin.write(JSON.stringify({ cmd: "remove", signals: specs }) + "\n");
+        return this.awaitReconcile();
+    }
+    /** Queue a resolver fired by the next "signals" frame; falls back to the
+     *  current signal set after ~2 s so callers can't hang on a silent daemon. */
+    awaitReconcile(timeoutMs = 2000) {
+        return new Promise((resolve) => {
+            const entry = {
+                resolve,
+                timer: setTimeout(() => {
+                    const i = this.pendingReconcile.indexOf(entry);
+                    if (i >= 0)
+                        this.pendingReconcile.splice(i, 1);
+                    resolve(this.buffer.signalNames());
+                }, timeoutMs),
+            };
+            this.pendingReconcile.push(entry);
+        });
+    }
+    /** §11.6: resolve on the FIRST ingested frame (signals|sample|error), or
+     *  `null` on timeout / if the daemon exits first. Lets MCP `start` report a
+     *  truthful device_state instead of an optimistic "running". Idempotent:
+     *  if a frame was already seen before the call, resolves immediately. */
+    waitForFirstFrame(timeoutMs = 3000) {
+        // Already exited with nothing, or a frame already arrived → settle now.
+        if (this.firstFrameSeen || this.proc === null) {
+            return Promise.resolve(this.lastFirstFrame);
+        }
+        return new Promise((resolve) => {
+            const entry = {
+                resolve,
+                timer: setTimeout(() => {
+                    const i = this.firstFrameWaiters.indexOf(entry);
+                    if (i >= 0)
+                        this.firstFrameWaiters.splice(i, 1);
+                    resolve(null);
+                }, timeoutMs),
+            };
+            this.firstFrameWaiters.push(entry);
+        });
+    }
+    // Remember the first frame so a waitForFirstFrame() called *after* it arrived
+    // still gets it (start() awaits right after spawn, but be robust to ordering).
+    lastFirstFrame = null;
+    /** Fire all pending first-frame waiters once. `f` is the triggering frame
+     *  (or null when the daemon exited / spawn-errored before any frame). */
+    resolveFirstFrame(f) {
+        if (f && !this.firstFrameSeen) {
+            this.firstFrameSeen = true;
+            this.lastFirstFrame = f;
+        }
+        if (this.firstFrameWaiters.length === 0)
+            return;
+        const waiters = this.firstFrameWaiters;
+        this.firstFrameWaiters = [];
+        for (const w of waiters) {
+            clearTimeout(w.timer);
+            w.resolve(f ?? this.lastFirstFrame);
+        }
+    }
+    /** Cancel any pending SIGTERM/SIGKILL escalation timers (clean exit). */
+    clearKillTimers() {
+        if (this.termTimer) {
+            clearTimeout(this.termTimer);
+            this.termTimer = null;
+        }
+        if (this.killTimer) {
+            clearTimeout(this.killTimer);
+            this.killTimer = null;
+        }
+    }
+    /** §11.5 guaranteed teardown — escalate {cmd:stop} → SIGTERM → SIGKILL.
+     *  Idempotent and safe to call when `proc` is already null (the daemon may
+     *  have self-exited on a connect failure / crash / target reset). A wedged
+     *  daemon blocked in uninterruptible libusb ignores SIGTERM, so the SIGKILL
+     *  fallback is the ONLY thing that guarantees no `pkill -9` is ever needed.
+     *  The escalation timers are cleared on real exit (see onExit) so a clean
+     *  shutdown never fires a stray kill at a recycled PID.
+     *
+     *  §12.1: stop() ONLY ends the daemon now. The web UI is owned by the
+     *  persistent Dashboard singleton (see trace-webui.ts), which OUTLIVES the
+     *  session — the MCP `stop` handler calls dashboard.unbind() so the server
+     *  keeps listening and the dashboard tab survives across traces. */
+    stop() {
+        const p = this.proc;
+        if (!p) {
+            this.clearKillTimers();
+            return;
+        } // already gone → nothing to kill
+        if (this.termTimer || this.killTimer)
+            return; // a stop() is already in flight (idempotent)
+        try {
+            p.stdin?.write(JSON.stringify({ cmd: "stop" }) + "\n");
+        }
+        catch { /* */ }
+        // 1) polite SIGTERM after ~1.5 s if {cmd:stop} didn't already end it.
+        this.termTimer = setTimeout(() => {
+            this.termTimer = null;
+            try {
+                p.kill("SIGTERM");
+            }
+            catch { /* */ }
+        }, 1500);
+        // 2) hard SIGKILL ~3 s later if the process is STILL alive (wedged libusb).
+        this.killTimer = setTimeout(() => {
+            this.killTimer = null;
+            if (this.proc) {
+                try {
+                    p.kill("SIGKILL");
+                }
+                catch { /* */ }
+            }
+        }, 4500);
+    }
+    isRunning() { return this.proc !== null; }
+}
+// Module-level singleton — one active trace session per server.
+let active = null;
+export function getActiveSession() { return active; }
+export function setActiveSession(s) { active = s; }
+//# sourceMappingURL=trace-session.js.map

package/dist/tools/trace-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-session.js","sourceRoot":"","sources":["../../src/tools/trace-session.ts"],"names":[],"mappings":"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"}

package/dist/tools/trace-symbols.d.ts

@@ -0,0 +1,24 @@
+export interface TraceSymbol {
+    name: string;
+    address: number;
+    encoding: string;
+    size: number;
+    kind?: "scalar" | "array" | "struct" | "union" | "other";
+    dims?: number[];
+    count?: number;
+    elem_size?: number;
+    elem_encoding?: string;
+    members?: string[];
+}
+export interface SymbolsResult {
+    success: boolean;
+    symbols: TraceSymbol[];
+    error?: string;
+}
+/** tracer/swd_tracer.py — resolved relative to the dist/ or src/ tree → repo root /tracer. */
+export declare function daemonPath(): string;
+export declare function resolvedPython(): string;
+export declare function resolvedElf(): string;
+/** Pure: extract the symbols JSON from mixed daemon output. */
+export declare function parseSymbolsOutput(out: string): SymbolsResult;
+export declare function listSymbols(query?: string, elf?: string, signal?: AbortSignal): Promise<SymbolsResult>;

package/dist/tools/trace-symbols.js

@@ -0,0 +1,44 @@
+// src/tools/trace-symbols.ts
+import path from "path";
+import { fileURLToPath } from "url";
+import { runArgvStream } from "../utils/exec.js";
+import { resolveConfigValue } from "../utils/userConfig.js";
+import { STM_ELF_DEFAULT } from "../config.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/** tracer/swd_tracer.py — resolved relative to the dist/ or src/ tree → repo root /tracer. */
+export function daemonPath() {
+    // dist/tools/trace-symbols.js → ../../tracer ; src/tools/*.ts → ../../tracer
+    return path.resolve(__dirname, "..", "..", "tracer", "swd_tracer.py");
+}
+export function resolvedPython() {
+    return resolveConfigValue("pyocd_python", "CROSSPAD_TRACE_PYTHON", process.env.CROSSPAD_TRACE_PYTHON, "python3");
+}
+export function resolvedElf() {
+    return resolveConfigValue("stm_elf_path", "CROSSPAD_STM_ELF", process.env.CROSSPAD_STM_ELF, STM_ELF_DEFAULT);
+}
+/** Pure: extract the symbols JSON from mixed daemon output. */
+export function parseSymbolsOutput(out) {
+    const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const l = lines[i];
+        if (l.startsWith("{") && l.includes('"symbols"')) {
+            try {
+                const obj = JSON.parse(l);
+                if (Array.isArray(obj.symbols))
+                    return { success: true, symbols: obj.symbols };
+            }
+            catch { /* keep scanning */ }
+        }
+    }
+    return { success: false, symbols: [], error: out.split("\n").filter(Boolean).slice(-3).join(" | ") || "no output" };
+}
+export async function listSymbols(query, elf, signal) {
+    const argv = ["symbols", "--elf", elf ?? resolvedElf()];
+    if (query)
+        argv.push("--query", query);
+    let out = "";
+    await runArgvStream(resolvedPython(), [daemonPath(), ...argv], process.cwd(), (s, line) => { if (s === "stdout")
+        out += line + "\n"; }, 30_000, signal);
+    return parseSymbolsOutput(out);
+}
+//# sourceMappingURL=trace-symbols.js.map

package/dist/tools/trace-symbols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-symbols.js","sourceRoot":"","sources":["../../src/tools/trace-symbols.ts"],"names":[],"mappings":"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"}

package/dist/tools/trace-webui.d.ts

@@ -0,0 +1,53 @@
+import type { TraceSession } from "./trace-session.js";
+export declare function buildUiUrl(port: number): string;
+/** Allow a WS upgrade only from a loopback Origin, or when no Origin is sent
+ *  (native/non-browser clients). Defends against cross-site WebSocket hijacking. */
+export declare function originIsLoopback(info: {
+    origin?: string;
+}): boolean;
+/** §12.4 best-effort browser opener. Spawns the platform opener detached so the
+ *  MCP server never owns the browser process, swallows every failure (a missing
+ *  opener / headless box must never throw), and SKIPS when:
+ *   - CROSSPAD_TRACE_NO_BROWSER is set (explicit opt-out), or
+ *   - on linux when neither DISPLAY nor WAYLAND_DISPLAY is set (headless — no GUI
+ *     to pop, so xdg-open would just error).
+ *  Returns true if an opener was actually spawned, false if skipped. */
+export declare function openInBrowser(url: string): boolean;
+/**
+ * §12.1 Persistent dashboard singleton. ONE http+ws server that OUTLIVES trace
+ * sessions for the MCP server's whole lifetime. `currentSession` is mutable:
+ * `bind` attaches a new trace (subscribes to its frames + broadcasts a
+ * `trace_start`); `unbind` detaches it (broadcasts `trace_end`) WITHOUT tearing
+ * the server down, so a browser / VS Code Simple Browser tab stays connected
+ * across start→stop→start cycles. The port (7373) is therefore stable.
+ */
+export declare class Dashboard {
+    private server;
+    private wss;
+    private clients;
+    private url;
+    private currentSession;
+    port: number;
+    /** §12.1 start listening once; idempotent — a second call reuses the running
+     *  server and resolves with the same url. The server keeps listening across
+     *  every trace, so the dashboard tab never goes dead. */
+    ensureStarted(preferredPort?: number): Promise<string>;
+    /** §12.1 attach a new trace: become its frame sink, broadcast trace_start. */
+    bind(session: TraceSession): void;
+    /** §12.1 detach the current trace: broadcast trace_end, go idle. The server
+     *  KEEPS listening (clients stay connected, ready for the next trace). */
+    unbind(): void;
+    /** §12.4: any WS client connected right now? `start` uses this to auto-open
+     *  the browser ONLY when the dashboard isn't already open in some tab. */
+    hasClients(): boolean;
+    /** §9/§12.3 GET /symbols handler: resolve symbols against the active session's
+     *  ELF, or — when idle — the configured DEFAULT ELF so autocomplete keeps
+     *  working between traces. Failures reply 500 rather than crashing the server. */
+    private serveSymbols;
+    /** Parse a browser → server WS message and forward `add`/`remove` to the bound
+     *  session. Ignored when idle (no currentSession) or when malformed (bad JSON,
+     *  wrong shape) — silently, per §5. */
+    private handleInbound;
+    private broadcast;
+}
+export declare function getDashboard(): Dashboard;