@slack/radar-mcp 1.4.0 → 1.6.0

package/dist/web/bin.js

@@ -1,23 +1,149 @@
 #!/usr/bin/env node
 import { execSync } from "child_process";
-import { createServer, WEB_PORT } from "./server.js";
+import { realpathSync } from "fs";
+import http from "http";
+import { fileURLToPath } from "url";
+import { cleanupOnBind, createServer, seedInitialSpec, WEB_PORT } from "./server.js";
+import { RADAR_VERSION } from "../shared/constants.js";
+/**
+ * One loopback GET against the dashboard's own port, used by the adopt path. Resolves with the
+ * status, body, and headers, or null on error/timeout. Centralizes the timeout + 127.0.0.1
+ * binding the probes share (the MCP side has its own copy in mcp/index.ts; this is the web
+ * bin's). Never throws.
+ */
+function loopbackGet(path, timeoutMs) {
+    return new Promise((resolve) => {
+        const req = http.request({ host: "127.0.0.1", port: WEB_PORT, path, method: "GET", timeout: timeoutMs }, (res) => {
+            let body = "";
+            res.on("data", (c) => (body += c));
+            res.on("end", () => resolve({ status: res.statusCode, body, headers: res.headers }));
+        });
+        req.on("error", () => resolve(null));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(null);
+        });
+        req.end();
+    });
+}
+/**
+ * Decide whether a /spec response body identifies a Radar dashboard. A Radar /spec
+ * is always a plain object carrying a `viz` array (even a blank spec is
+ * { title, blank, viz: [] }). Requiring both excludes a foreign service that happens
+ * to 200 with arbitrary JSON (a bare array, a string, an unrelated object). Exported
+ * for unit testing. statusCode must be 200.
+ */
+export function isRadarSpecBody(statusCode, body) {
+    if (statusCode !== 200)
+        return false;
+    let spec;
+    try {
+        spec = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    // typeof [] is "object" in JS, hence the explicit Array.isArray exclusion.
+    return (spec !== null &&
+        typeof spec === "object" &&
+        !Array.isArray(spec) &&
+        Array.isArray(spec.viz));
+}
+/** Open the dashboard in the default browser. Best-effort; never throws. */
+function openBrowser(url) {
+    try {
+        if (process.platform === "darwin") {
+            execSync(`open ${url}`, { stdio: "ignore" });
+        }
+        else if (process.platform === "linux") {
+            execSync(`xdg-open ${url}`, { stdio: "ignore" });
+        }
+    }
+    catch {
+        // Browser open is best-effort
+    }
+}
+/**
+ * The port is busy. Decide whether the thing holding it is an existing Radar
+ * dashboard (adopt it: open the browser and exit cleanly) or something else
+ * (print the manual options and exit non-zero). We do NOT kill the holder:
+ * `lsof -ti :PORT` could be a browser, a teammate's server, or any unrelated
+ * process, and killing by port from a published tool is a footgun.
+ *
+ * Detection probes GET /spec on the loopback port. /spec is instant (it returns
+ * the current dashboard spec, no device round-trip) and is unique to a Radar
+ * dashboard, so a 200 with a JSON body is a reliable fingerprint. The response's
+ * X-Radar-Version header lets us notice when the running dashboard is a DIFFERENT
+ * Radar version than this launcher and say so — we still adopt it (never kill the
+ * holder), the note just explains why a feature you expect might be missing.
+ */
+function handlePortInUse() {
+    const url = `http://localhost:${WEB_PORT}`;
+    void loopbackGet("/spec", 2000).then((r) => {
+        if (r && isRadarSpecBody(r.status, r.body)) {
+            const running = r.headers["x-radar-version"];
+            if (typeof running === "string" && running !== RADAR_VERSION) {
+                console.log(`Note: the running dashboard is Radar ${running}, this launcher is ${RADAR_VERSION}. ` +
+                    `Adopting the running one as-is (it owns the port). Restart it to pick up ${RADAR_VERSION}.`);
+            }
+            console.log(`Slack Radar is already running at ${url}. Opening it.`);
+            if (!process.env.SLACK_RADAR_NO_OPEN)
+                openBrowser(url);
+            process.exit(0);
+        }
+        reportForeignPort();
+    });
+}
+/** Port is held by something that is not a Radar dashboard. Never kill it for the user. */
+function reportForeignPort() {
+    console.error(`Port ${WEB_PORT} is already in use by another program (not a Radar dashboard).\n` +
+        `Free it, or run Radar on another port: SLACK_RADAR_WEB_PORT=8101 slack-radar web`);
+    process.exit(1);
+}
 /**
  * Start the web dashboard server, open the browser, and wire shutdown signals.
  * Extracted so both the dedicated `slack-radar-web` bin and the default bin's
- * `web` subcommand dispatcher launch the dashboard the same way.
+ * `web` subcommand dispatcher launch the dashboard the same way. Exported so the
+ * dispatcher (mcp/index.ts) calls it explicitly rather than relying on an import
+ * side-effect, which keeps importing this module (e.g. in a test) side-effect-free.
  */
-function startWebServer() {
+export function startWebServer() {
+    // Safety net: a single route handler must never take the whole dashboard down. An async
+    // callback (e.g. a device-probe that both ends and errors) can otherwise throw
+    // ERR_HTTP_HEADERS_SENT outside any try/catch and kill the process. Log and keep serving;
+    // handlers still guard their own writes, this is the backstop for anything they miss.
+    process.on("uncaughtException", (err) => {
+        console.error("uncaughtException (kept alive):", err);
+    });
+    process.on("unhandledRejection", (err) => {
+        console.error("unhandledRejection (kept alive):", err);
+    });
     const server = createServer();
     server.on("error", (err) => {
         if (err.code === "EADDRINUSE") {
-            console.error(`Port ${WEB_PORT} is already in use. Another instance may be running.\n` +
-                `Kill it with: lsof -ti :${WEB_PORT} | xargs kill\n` +
-                `Or set a different port: SLACK_RADAR_WEB_PORT=8101 slack-radar web`);
-            process.exit(1);
+            // Likely our own dashboard from an earlier launch. Adopt it if so; only error
+            // if the port is held by something else. Never kill the holder for the user.
+            handlePortInUse();
+            return;
         }
         throw err;
     });
-    server.listen(WEB_PORT, () => {
+    // Bind loopback-only. The dashboard serves sensitive device data with no auth:
+    // live ring buffers, the on-device message store via the DB browser, and the live
+    // screen mirror (open DMs, notifications). Omitting the host arg binds all
+    // interfaces (0.0.0.0/::), which would let any same-network peer hit /dbquery or
+    // grant screen consent (a single unauthenticated process boolean) and watch the
+    // device. The consent gate only raises the bar for the local user; 127.0.0.1 is
+    // what actually closes the network. The device-side connection is already
+    // loopback-scoped (constants.ts); the dashboard's own listener must match. Remote
+    // access, if ever needed, belongs in a separate token-gated feature.
+    server.listen(WEB_PORT, "127.0.0.1", () => {
+        // Seed the starting spec AND wipe stale pulled DBs only now that THIS process owns the
+        // port. Doing both here (not at server.js import) means a second launcher that loses the
+        // bind never touches the running dashboard's spec file or its port-scoped pulled-DB cache,
+        // so adopting it leaves its view and open DB-browser tab intact.
+        seedInitialSpec();
+        cleanupOnBind();
         const url = `http://localhost:${WEB_PORT}`;
         console.log(`Slack Radar Web running at ${url}`);
         // Auto-open the browser for the HUMAN launcher (`slack-radar web` / `slack-radar-web`),
@@ -27,17 +153,7 @@ function startWebServer() {
         // /radar-ui. The tool returns the URL instead, for the Claude Code session to surface.
         if (process.env.SLACK_RADAR_NO_OPEN)
             return;
-        try {
-            if (process.platform === "darwin") {
-                execSync(`open ${url}`, { stdio: "ignore" });
-            }
-            else if (process.platform === "linux") {
-                execSync(`xdg-open ${url}`, { stdio: "ignore" });
-            }
-        }
-        catch {
-            // Browser open is best-effort
-        }
+        openBrowser(url);
     });
     const shutdown = () => {
         console.log("\nShutting down…");
@@ -47,4 +163,21 @@ function startWebServer() {
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
 }
-startWebServer();
+// Only launch when run as the bin (`slack-radar-web` / `slack-radar web`), not when
+// imported (e.g. by a test that exercises isRadarSpecBody). argv[1] is the script path
+// node was invoked with; compare it to this module's own path. realpathSync resolves the
+// npm bin symlink (node_modules/.bin) to the real dist path so the comparison holds.
+function invokedDirectly() {
+    const arg = process.argv[1];
+    if (!arg)
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(arg);
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    startWebServer();
+}

package/dist/web/log-session.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Session-long host-side logcat capture for the web dashboard.
+ *
+ * The device does not buffer logcat for us (the on-device radar server captures
+ * network/RTM/clog into ring buffers, but logcat is a host-side `adb logcat`
+ * stream with no replayable device buffer). So when a browser switches dashboard
+ * tabs, the SSE `/stream` connection is torn down and reopened, and anything that
+ * used to drive logcat off the per-connection lifecycle would lose every line
+ * emitted while no stream was attached — the user sees their log count shrink on
+ * a tab switch.
+ *
+ * This module fixes that the way Android Studio does: ONE logcat process per
+ * device for the whole server session, feeding a bounded session ring buffer.
+ * Each `/stream` connection subscribes as a listener and is first replayed the
+ * entire retained buffer, then receives live lines. Switching tabs only
+ * adds/removes a listener; the underlying capture and its history are untouched.
+ *
+ * The class takes its spawn and parse functions by injection so it is unit
+ * testable without spawning a real `adb logcat` (the integration path is covered
+ * by the smoke test on a real device).
+ */
+import type { ChildProcess } from "child_process";
+/** A parsed logcat frame, as delivered to the dashboard over SSE. */
+export interface LogFrame {
+    id: number;
+    timestamp: number;
+    log_ts: string;
+    pid: number;
+    tid: number;
+    level: string;
+    tag: string;
+    message: string;
+    package?: string;
+}
+/** Spawn a process producing logcat lines on stdout. Injectable for tests. */
+export type SpawnLogcat = () => ChildProcess;
+/** Parse one raw logcat line into a frame, or null if it is not a log line. */
+export type ParseLine = (line: string) => LogFrame | null;
+/** Receives one frame. `replay` is true for buffered history, false for live. */
+export type LogListener = (frame: LogFrame, replay: boolean) => void;
+/**
+ * A single session-long logcat capture with a bounded ring buffer and listener
+ * fan-out. One instance is shared across every dashboard stream connection.
+ */
+export declare class LogSession {
+    private readonly spawnLogcat;
+    private readonly parseLine;
+    private readonly cap;
+    private child;
+    private lineBuf;
+    private readonly ring;
+    private readonly listeners;
+    private cleanupRegistered;
+    constructor(spawnLogcat: SpawnLogcat, parseLine: ParseLine, cap?: number);
+    /** True while a logcat child is running. */
+    isRunning(): boolean;
+    /** Number of frames currently retained (for tests / diagnostics). */
+    bufferSize(): number;
+    /** Number of attached stream listeners (for tests / diagnostics). */
+    listenerCount(): number;
+    /**
+     * Start the capture if it is not already running. Idempotent: a second call
+     * while a child is alive is a no-op, so concurrent tab opens cannot fan out
+     * duplicate logcat processes. Returns true if a capture is running after the
+     * call (already-running counts as success), false if the spawn failed.
+     */
+    start(): boolean;
+    /** Stop the capture and drop the child. The ring buffer is preserved. */
+    stop(): void;
+    /**
+     * Install process-exit handlers (once) so the persistent `adb logcat` child is
+     * killed when the server process exits. Without this, the capture orphans when
+     * the server is terminated by signal — notably when `open_radar_dashboard`
+     * spawns the dashboard as a child and later kills it by PID — and orphaned adb
+     * logcat readers accumulate across dashboard open/close cycles, holding the
+     * device's logcat stream. Mirrors logcat-capture.ts's registerCleanup().
+     */
+    registerCleanup(): void;
+    /**
+     * Subscribe a stream to the session. The listener is FIRST replayed the entire
+     * retained ring (replay=true) so a freshly opened tab shows full history, then
+     * receives every subsequent live frame (replay=false). Returns an unsubscribe
+     * function; call it when the stream closes (this does NOT stop the capture).
+     */
+    subscribe(listener: LogListener): () => void;
+    private onChildGone;
+    private onData;
+    private push;
+}

package/dist/web/log-session.js

@@ -0,0 +1,144 @@
+import { MAX_LOG_SESSION_BUFFER } from "../shared/constants.js";
+/**
+ * A single session-long logcat capture with a bounded ring buffer and listener
+ * fan-out. One instance is shared across every dashboard stream connection.
+ */
+export class LogSession {
+    spawnLogcat;
+    parseLine;
+    cap;
+    child = null;
+    lineBuf = "";
+    ring = [];
+    listeners = new Set();
+    cleanupRegistered = false;
+    constructor(spawnLogcat, parseLine, cap = MAX_LOG_SESSION_BUFFER) {
+        this.spawnLogcat = spawnLogcat;
+        this.parseLine = parseLine;
+        this.cap = cap > 0 ? cap : MAX_LOG_SESSION_BUFFER;
+    }
+    /** True while a logcat child is running. */
+    isRunning() {
+        return this.child !== null;
+    }
+    /** Number of frames currently retained (for tests / diagnostics). */
+    bufferSize() {
+        return this.ring.length;
+    }
+    /** Number of attached stream listeners (for tests / diagnostics). */
+    listenerCount() {
+        return this.listeners.size;
+    }
+    /**
+     * Start the capture if it is not already running. Idempotent: a second call
+     * while a child is alive is a no-op, so concurrent tab opens cannot fan out
+     * duplicate logcat processes. Returns true if a capture is running after the
+     * call (already-running counts as success), false if the spawn failed.
+     */
+    start() {
+        if (this.child)
+            return true;
+        let child;
+        try {
+            child = this.spawnLogcat();
+        }
+        catch {
+            return false;
+        }
+        this.child = child;
+        this.lineBuf = "";
+        child.stdout?.on("data", (c) => this.onData(c));
+        // A crashed/killed logcat (device unplugged, adb server restart) clears the
+        // child so the next connect() can restart it. The retained ring survives so
+        // history is not lost across a transient device drop.
+        child.on("error", () => this.onChildGone(child));
+        child.on("exit", () => this.onChildGone(child));
+        return true;
+    }
+    /** Stop the capture and drop the child. The ring buffer is preserved. */
+    stop() {
+        const child = this.child;
+        this.child = null;
+        this.lineBuf = "";
+        if (child) {
+            try {
+                child.kill();
+            }
+            catch {
+                // already dead
+            }
+        }
+    }
+    /**
+     * Install process-exit handlers (once) so the persistent `adb logcat` child is
+     * killed when the server process exits. Without this, the capture orphans when
+     * the server is terminated by signal — notably when `open_radar_dashboard`
+     * spawns the dashboard as a child and later kills it by PID — and orphaned adb
+     * logcat readers accumulate across dashboard open/close cycles, holding the
+     * device's logcat stream. Mirrors logcat-capture.ts's registerCleanup().
+     */
+    registerCleanup() {
+        if (this.cleanupRegistered)
+            return;
+        this.cleanupRegistered = true;
+        process.on("exit", () => this.stop());
+        process.on("SIGINT", () => {
+            this.stop();
+            process.exit(130);
+        });
+        process.on("SIGTERM", () => {
+            this.stop();
+            process.exit(143);
+        });
+    }
+    /**
+     * Subscribe a stream to the session. The listener is FIRST replayed the entire
+     * retained ring (replay=true) so a freshly opened tab shows full history, then
+     * receives every subsequent live frame (replay=false). Returns an unsubscribe
+     * function; call it when the stream closes (this does NOT stop the capture).
+     */
+    subscribe(listener) {
+        // Replay a snapshot of the current ring. Snapshot first so a frame arriving
+        // mid-replay is not delivered twice (once via replay, once live).
+        const snapshot = this.ring.slice();
+        for (const frame of snapshot)
+            listener(frame, true);
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    onChildGone(child) {
+        // Guard against a late event from an already-replaced child.
+        if (this.child === child) {
+            this.child = null;
+            this.lineBuf = "";
+        }
+    }
+    onData(chunk) {
+        this.lineBuf += chunk.toString();
+        let nl;
+        while ((nl = this.lineBuf.indexOf("\n")) >= 0) {
+            const line = this.lineBuf.slice(0, nl);
+            this.lineBuf = this.lineBuf.slice(nl + 1);
+            const frame = this.parseLine(line);
+            if (frame)
+                this.push(frame);
+        }
+    }
+    push(frame) {
+        this.ring.push(frame);
+        if (this.ring.length > this.cap)
+            this.ring.shift();
+        for (const listener of this.listeners) {
+            // A throwing listener (e.g. a closed response) must not kill the capture
+            // or starve the other listeners.
+            try {
+                listener(frame, false);
+            }
+            catch {
+                // best-effort fan-out
+            }
+        }
+    }
+}