@slack/radar-mcp 1.2.0 → 1.4.0

package/dist/web/server.d.ts

@@ -1,4 +1,31 @@
 import http from "http";
 declare const WEB_PORT: number;
 export declare function createServer(): http.Server;
+/**
+ * Finish a /detail proxy response after an upstream error or timeout. The success
+ * callback streams the upstream response, so headers may already be sent when a later
+ * "error"/"timeout" fires (a partial response then the device drops the socket mid-stream,
+ * common when the device idle-shuts). Calling writeHead a second time throws
+ * ERR_HTTP_HEADERS_SENT and crashes the whole process, so only write a status when headers
+ * have not gone out yet; otherwise just end the already-started response. Exported for tests.
+ */
+export declare function failDetailResponse(res: Pick<http.ServerResponse, "headersSent" | "writeHead" | "end">, status: number): void;
+interface ParsedLog {
+    id: number;
+    timestamp: number;
+    log_ts: string;
+    pid: number;
+    tid: number;
+    level: string;
+    tag: string;
+    message: string;
+    package?: string;
+}
+/**
+ * Parse one `adb logcat -v threadtime` line into a structured event, or null if it does
+ * not match the format. `resolvePkg` maps a pid to its package name (defaults to the
+ * live adb-backed resolver); injectable so this stays a pure, unit-testable function.
+ * Exported for tests.
+ */
+export declare function parseLogcat(line: string, resolvePkg?: (pid: number) => string | undefined): ParsedLog | null;
 export { WEB_PORT };

package/dist/web/server.js

@@ -1,38 +1,110 @@
 import http from "http";
 import fs from "fs";
+import os from "os";
 import path from "path";
+import { spawn } from "child_process";
 import { fileURLToPath } from "url";
-import { AndroidTransport } from "../shared/android.js";
-import { RADAR_HOST, RADAR_PORT } from "../shared/constants.js";
+import { AndroidTransport, resolveAdbPath } from "../shared/android.js";
+import { RADAR_HOST, RADAR_PORT, WEB_PORT_DEFAULT } from "../shared/constants.js";
+import { BLANK_SPEC, coerceSpec, validateSpec } from "./spec.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const WEB_PORT = Number(process.env.SLACK_RADAR_WEB_PORT ?? 8100);
+const WEB_PORT = Number(process.env.SLACK_RADAR_WEB_PORT ?? WEB_PORT_DEFAULT);
 const INDEX_PATH = path.join(__dirname, "public", "index.html");
+// The active dashboard spec is session-scoped runtime state, NOT source. It lives
+// under the user's home data dir (never inside the repo / published tarball) so it
+// cannot be accidentally committed. The path is scoped by port so two dashboards
+// running on different ports do not stomp each other's spec (a browser attached to
+// one instance polls /spec and would otherwise overwrite the shared file for all).
+// Each server start resets its own file to blank.
+const SPEC_DIR = path.join(os.homedir(), ".slack-radar");
+const SPEC_PATH = path.join(SPEC_DIR, `web-spec-${WEB_PORT}.json`);
 const transport = new AndroidTransport();
+function writeSpec(spec) {
+    try {
+        fs.mkdirSync(SPEC_DIR, { recursive: true });
+        fs.writeFileSync(SPEC_PATH, JSON.stringify(spec, null, 2));
+    }
+    catch {
+        // Best-effort; a failed write just means the next /spec read falls back to blank.
+    }
+}
+function loadSpec() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(SPEC_PATH, "utf8"));
+        const spec = coerceSpec(parsed);
+        return validateSpec(spec) ? BLANK_SPEC : spec;
+    }
+    catch {
+        return BLANK_SPEC;
+    }
+}
+// Start every run from a clean slate so a refresh/restart opens blank — UNLESS the
+// process was spawned with an initial spec (SLACK_RADAR_INITIAL_SPEC). The MCP
+// open_radar_dashboard handler sets that env on a cold spawn so the spec file is
+// already the custom spec BEFORE the browser loads and runs bootDefault(); without
+// this seed the browser's bootDefault (fires only on a blank spec) and the handler's
+// /setspec POST race, and a lost race leaves the Live preset showing while the tool
+// already reported the custom dashboard is live. Seeding makes the handler the sole
+// startup writer and removes the race deterministically. Invalid seed falls back to blank.
+function initialSpec() {
+    const raw = process.env.SLACK_RADAR_INITIAL_SPEC;
+    if (!raw)
+        return BLANK_SPEC;
+    try {
+        const spec = coerceSpec(JSON.parse(raw));
+        return validateSpec(spec) ? BLANK_SPEC : spec;
+    }
+    catch {
+        return BLANK_SPEC;
+    }
+}
+writeSpec(initialSpec());
 export function createServer() {
     const server = http.createServer((req, res) => {
-        if (req.url === "/" || req.url === "/index.html") {
-            try {
-                const html = fs.readFileSync(INDEX_PATH);
-                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-                res.end(html);
-            }
-            catch (e) {
-                res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
-                res.end(`Failed to read ${INDEX_PATH}: ${e.message}`);
-            }
+        const url = req.url ?? "";
+        if (url === "/" || url === "/index.html") {
+            serveIndex(res);
+            return;
+        }
+        if (url === "/spec" && req.method === "GET") {
+            sendJson(res, 200, loadSpec());
             return;
         }
-        if (req.url === "/_control/profiles" && req.method === "GET") {
+        if (url === "/setspec" && req.method === "POST") {
+            handleSetSpec(req, res);
+            return;
+        }
+        if (url === "/health" && req.method === "GET") {
+            handleHealth(res);
+            return;
+        }
+        if (url === "/enable" && req.method === "POST") {
+            handleEnable(res);
+            return;
+        }
+        if (url === "/stream" && req.method === "GET") {
+            handleStream(req, res);
+            return;
+        }
+        if (url.startsWith("/backfill")) {
+            handleBackfill(req, res);
+            return;
+        }
+        if (url.startsWith("/detail")) {
+            handleDetail(req, res);
+            return;
+        }
+        if (url === "/_control/profiles" && req.method === "GET") {
             listProfiles(res);
             return;
         }
-        if (req.url?.startsWith("/_control/activate") && req.method === "POST") {
-            const url = new URL(req.url, `http://localhost:${WEB_PORT}`);
-            const userId = url.searchParams.get("user_id") ?? undefined;
+        if (url.startsWith("/_control/activate") && req.method === "POST") {
+            const parsed = new URL(url, `http://localhost:${WEB_PORT}`);
+            const userId = parsed.searchParams.get("user_id") ?? undefined;
             activateRadar(res, userId);
             return;
         }
-        if (req.url?.startsWith("/api/")) {
+        if (url.startsWith("/api/")) {
             proxyToRadar(req, res);
             return;
         }
@@ -41,11 +113,460 @@ export function createServer() {
     });
     return server;
 }
+function serveIndex(res) {
+    try {
+        const html = fs.readFileSync(INDEX_PATH);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end(`Failed to read ${INDEX_PATH}: ${e.message}`);
+    }
+}
+function sendJson(res, status, payload) {
+    // A device probe can fire both "end" and "error"/"timeout" for one request, so its
+    // callbacks may call sendJson twice. The second writeHead would throw
+    // ERR_HTTP_HEADERS_SENT and crash the whole process. Swallow the duplicate.
+    if (res.headersSent || res.writableEnded)
+        return;
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(payload));
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => resolve(body));
+        req.on("error", () => resolve(body));
+    });
+}
+/**
+ * Persist a spec pushed by the client (a pre-built tab, a filter edit, a chip
+ * cancel) or by an MCP caller. Coerce + validate before writing; a bad spec is
+ * rejected with its reason so the UI can surface it rather than render zeros.
+ */
+async function handleSetSpec(req, res) {
+    const body = await readBody(req);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        sendJson(res, 400, { error: "bad json" });
+        return;
+    }
+    const spec = coerceSpec(parsed);
+    const err = validateSpec(spec);
+    if (err) {
+        sendJson(res, 400, { error: err });
+        return;
+    }
+    writeSpec(spec);
+    sendJson(res, 200, {
+        ok: true,
+        url: `http://localhost:${WEB_PORT}`,
+        title: spec.title ?? "",
+    });
+}
+/**
+ * Always-available device-reachability probe, independent of whether a dashboard
+ * is built. Drives the connection dot even on a blank dashboard. Reuses the same
+ * forward/proxy base as the rest of the server.
+ */
+function handleHealth(res) {
+    const probe = http.request({
+        host: RADAR_HOST,
+        port: RADAR_PORT,
+        path: "/api/ping",
+        method: "GET",
+        timeout: 2500,
+    }, (up) => {
+        up.resume();
+        up.on("end", () => sendJson(res, 200, { device: up.statusCode === 200 }));
+    });
+    probe.on("error", () => sendJson(res, 200, { device: false }));
+    probe.on("timeout", () => {
+        probe.destroy();
+        sendJson(res, 200, { device: false });
+    });
+    probe.end();
+}
+/**
+ * Re-arm Radar from the dashboard. Mirrors the recovery sequence: reset cached
+ * forward state, rebuild a clean adb forward, and re-broadcast activation, so the
+ * user never has to drop to a terminal. Delegates entirely to AndroidTransport;
+ * no adb shelling here.
+ */
+function handleEnable(res) {
+    transport.resetState();
+    const forwarded = transport.ensureForward();
+    if (!forwarded) {
+        const reason = transport.getLastForwardError?.() ?? null;
+        sendJson(res, 200, {
+            enabled: false,
+            error: reason ?? "ADB forward failed. Is a device connected?",
+        });
+        return;
+    }
+    try {
+        transport.activate(transport.getTimeoutMinutes());
+    }
+    catch (e) {
+        sendJson(res, 200, {
+            enabled: false,
+            error: `Broadcast failed: ${e.message}. Debug build not running?`,
+        });
+        return;
+    }
+    // Verify by pinging the device the same way /health does.
+    const probe = http.request({
+        host: RADAR_HOST,
+        port: RADAR_PORT,
+        path: "/api/ping",
+        method: "GET",
+        timeout: 2500,
+    }, (up) => {
+        up.resume();
+        up.on("end", () => sendJson(res, 200, { enabled: up.statusCode === 200 }));
+    });
+    probe.on("error", () => sendJson(res, 200, { enabled: false }));
+    probe.on("timeout", () => {
+        probe.destroy();
+        sendJson(res, 200, { enabled: false });
+    });
+    probe.end();
+}
+const SOURCE_ARRAY_KEY = {
+    network: "calls",
+    rtm: "events",
+    clog: "clogs",
+};
+/**
+ * Replay the device's recent ring buffers for a source so a freshly-built tab
+ * shows history immediately instead of filling only going forward. The device is
+ * the source of truth. "all" pulls network+rtm+clog and merges them oldest->newest;
+ * "log" is host-side (no device buffer) and so has nothing to replay. Returns
+ * `[{type, event}]` frames mirroring the stream shape.
+ */
+function handleBackfill(req, res) {
+    const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
+    const src = u.searchParams.get("source") ?? "network";
+    const limit = Math.min(500, Number(u.searchParams.get("limit")) || 200);
+    const kinds = src === "all"
+        ? ["network", "rtm", "clog"]
+        : [src].filter((k) => k !== "log" && k in SOURCE_ARRAY_KEY);
+    const fetchKind = (kind) => new Promise((resolve) => {
+        const apiPath = `/api/${kind === "clog" ? "clogs" : kind}?limit=${limit}`;
+        const rq = http.request({
+            host: RADAR_HOST,
+            port: RADAR_PORT,
+            path: apiPath,
+            method: "GET",
+            timeout: 4000,
+        }, (up) => {
+            let b = "";
+            up.on("data", (c) => (b += c));
+            up.on("end", () => {
+                try {
+                    const j = JSON.parse(b);
+                    const arr = j[SOURCE_ARRAY_KEY[kind]] ?? [];
+                    resolve(arr.map((e) => ({ type: kind, event: e })));
+                }
+                catch {
+                    resolve([]);
+                }
+            });
+        });
+        rq.on("error", () => resolve([]));
+        rq.on("timeout", () => {
+            rq.destroy();
+            resolve([]);
+        });
+        rq.end();
+    });
+    Promise.all(kinds.map(fetchKind))
+        .then((lists) => {
+        const merged = lists
+            .flat()
+            .sort((a, b) => (Number(a.event.timestamp) || 0) - (Number(b.event.timestamp) || 0));
+        sendJson(res, 200, { frames: merged });
+    })
+        .catch(() => sendJson(res, 200, { frames: [] }));
+}
+// Detail kinds the inspector may request, mapped to their device route segment. The
+// device serves clog detail at /api/clogs/ (plural); the rest match the kind name.
+const DETAIL_ROUTES = {
+    network: "network",
+    rtm: "rtm",
+    clog: "clogs",
+};
+/**
+ * Finish a /detail proxy response after an upstream error or timeout. The success
+ * callback streams the upstream response, so headers may already be sent when a later
+ * "error"/"timeout" fires (a partial response then the device drops the socket mid-stream,
+ * common when the device idle-shuts). Calling writeHead a second time throws
+ * ERR_HTTP_HEADERS_SENT and crashes the whole process, so only write a status when headers
+ * have not gone out yet; otherwise just end the already-started response. Exported for tests.
+ */
+export function failDetailResponse(res, status) {
+    if (!res.headersSent) {
+        res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+        res.end("{}");
+    }
+    else {
+        res.end();
+    }
+}
+/**
+ * Proxy a single record's full detail from the device ring buffer. Thin pass-through
+ * to `/api/<kind>/<id>` so the inspector can fetch a clicked row's payload.
+ */
+function handleDetail(req, res) {
+    const u = new URL(req.url ?? "", `http://localhost:${WEB_PORT}`);
+    const id = u.searchParams.get("id");
+    const kind = u.searchParams.get("kind") ?? "network";
+    const route = DETAIL_ROUTES[kind];
+    if (!id || !route) {
+        res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+        res.end("{}");
+        return;
+    }
+    const upstream = http.request({
+        host: RADAR_HOST,
+        port: RADAR_PORT,
+        path: `/api/${route}/${encodeURIComponent(id)}`,
+        method: "GET",
+        timeout: 4000,
+    }, (up) => {
+        res.writeHead(up.statusCode ?? 502, {
+            "Content-Type": "application/json; charset=utf-8",
+        });
+        up.on("data", (c) => res.write(c));
+        up.on("end", () => res.end());
+    });
+    upstream.on("error", () => failDetailResponse(res, 502));
+    upstream.on("timeout", () => {
+        upstream.destroy();
+        failDetailResponse(res, 504);
+    });
+    upstream.end();
+}
+// Logcat line parsing for the host-side log merge. Format:
+// "MM-DD HH:MM:SS.mmm  PID  TID  L Tag: message"
+const LOG_LINE_RE = /^(\d\d-\d\d \d\d:\d\d:\d\d\.\d+)\s+(\d+)\s+(\d+)\s+([VDIWEF])\s+([^:]*?):\s?(.*)$/;
+const LOG_LEVELS = {
+    V: "VERBOSE",
+    D: "DEBUG",
+    I: "INFO",
+    W: "WARN",
+    E: "ERROR",
+    F: "FATAL",
+};
+// A logcat line carries a PID, not a package, but the dashboard filters logs by
+// package (e.g. "Slack app only"). Resolve PID -> process name from
+// `adb shell ps -A -o PID,NAME`, cached and refreshed on a miss (rate-limited), so
+// log rows get a readable `package` and the package filter works. Without this the
+// Live/Logs presets (match {package: ...}) drop every log line.
+const pidToPackage = new Map();
+let pidRefreshing = false;
+let lastPidRefresh = 0;
+function refreshPidMap() {
+    if (pidRefreshing)
+        return;
+    const adb = resolveAdbPath();
+    if (!adb)
+        return;
+    pidRefreshing = true;
+    lastPidRefresh = Date.now();
+    const ps = spawn(adb, ["shell", "ps", "-A", "-o", "PID,NAME"]);
+    let out = "";
+    ps.stdout?.on("data", (c) => (out += c.toString()));
+    ps.on("error", () => {
+        pidRefreshing = false;
+    });
+    ps.on("close", () => {
+        pidRefreshing = false;
+        for (const line of out.split("\n")) {
+            const m = line.trim().match(/^(\d+)\s+(\S+)$/);
+            if (m)
+                pidToPackage.set(Number(m[1]), m[2]);
+        }
+    });
+}
+function packageForPid(pid) {
+    const hit = pidToPackage.get(pid);
+    if (hit)
+        return hit;
+    // Unknown pid: trigger a rate-limited refresh so the NEXT line resolves.
+    if (Date.now() - lastPidRefresh > 3000)
+        refreshPidMap();
+    return undefined;
+}
+let logIdSeq = 0;
+/**
+ * Parse one `adb logcat -v threadtime` line into a structured event, or null if it does
+ * not match the format. `resolvePkg` maps a pid to its package name (defaults to the
+ * live adb-backed resolver); injectable so this stays a pure, unit-testable function.
+ * Exported for tests.
+ */
+export function parseLogcat(line, resolvePkg = packageForPid) {
+    const m = line.match(LOG_LINE_RE);
+    if (!m)
+        return null;
+    const [, ts, pid, tid, level, tag, message] = m;
+    const pidN = Number(pid);
+    return {
+        id: ++logIdSeq,
+        timestamp: Date.now(),
+        log_ts: ts,
+        pid: pidN,
+        tid: Number(tid),
+        level: LOG_LEVELS[level] ?? level,
+        tag: tag.trim(),
+        message,
+        package: resolvePkg(pidN),
+    };
+}
+/**
+ * Self-healing SSE proxy. Keeps ONE long-lived response open to the browser and
+ * internally (re)connects to the device `/api/stream` every couple seconds while
+ * it is down, so the browser's EventSource never sees a close and never gives up.
+ * Every other retry it rebuilds the adb forward (the real cause of recurring
+ * "unreachable"), reusing AndroidTransport rather than shelling adb directly.
+ *
+ * When the active spec wants logs (source "log" or "all"), it also spawns a
+ * host-side `adb logcat -v threadtime -T 1` and merges parsed lines as
+ * `type: "log"` frames. The adb binary is resolved via resolveAdbPath() so GUI
+ * launchers without the user's PATH still work.
+ */
+function handleStream(req, res) {
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    let upstream = null;
+    let closed = false;
+    let lastState = "";
+    const announce = (state, msg) => {
+        if (state === lastState)
+            return;
+        lastState = state;
+        res.write(`data: ${JSON.stringify({ type: "_status", event: { state, msg } })}\n\n`);
+    };
+    let retries = 0;
+    // One scheduled reconnect per attempt. up.on("end"), up.on("error"), and
+    // upstream.on("error") can all fire for the same attempt; without this guard each
+    // would schedule its own connect(), fanning out duplicate streams (and re-spawning
+    // logcat on the rebuild path). Reset at the top of connect() so the next attempt
+    // can retry again.
+    let settled = false;
+    const retry = () => {
+        if (closed)
+            return;
+        if (settled)
+            return;
+        settled = true;
+        retries++;
+        // Every other retry, rebuild a clean forward before reconnecting. resetState()
+        // drops the cached forward flag so ensureForward() actually re-runs adb forward.
+        if (retries % 2 === 0) {
+            transport.resetState();
+            transport.ensureForward();
+            setTimeout(connect, 1500);
+        }
+        else {
+            setTimeout(connect, 2000);
+        }
+    };
+    const connect = () => {
+        if (closed)
+            return;
+        settled = false;
+        upstream = http.request({
+            host: RADAR_HOST,
+            port: RADAR_PORT,
+            path: "/api/stream",
+            method: "GET",
+        }, (up) => {
+            announce("connected", "device stream connected");
+            up.on("data", (c) => res.write(c));
+            up.on("end", () => {
+                announce("waiting", "device stream ended, retrying…");
+                retry();
+            });
+            up.on("error", () => {
+                announce("waiting", "device stream error, retrying…");
+                retry();
+            });
+        });
+        upstream.on("error", () => {
+            announce("waiting", "device unreachable, retrying…");
+            retry();
+        });
+        upstream.end();
+    };
+    connect();
+    const heartbeat = setInterval(() => {
+        if (!closed)
+            res.write(": hb\n\n");
+    }, 15000);
+    // Host-side logcat merge for log/all sources. -T 1 streams only NEW lines;
+    // without it logcat replays the entire existing buffer on connect and floods
+    // the browser.
+    let logcat = null;
+    const spec = loadSpec();
+    const wantsLogs = spec.source === "log" || spec.source === "all";
+    const adb = resolveAdbPath();
+    if (wantsLogs && adb) {
+        try {
+            refreshPidMap(); // warm PID->package so the first log rows resolve their app
+            logcat = spawn(adb, ["logcat", "-v", "threadtime", "-T", "1"], {
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            let lineBuf = "";
+            logcat.stdout?.on("data", (c) => {
+                lineBuf += c.toString();
+                let nl;
+                while ((nl = lineBuf.indexOf("\n")) >= 0) {
+                    const line = lineBuf.slice(0, nl);
+                    lineBuf = lineBuf.slice(nl + 1);
+                    const ev = parseLogcat(line);
+                    if (ev && !closed) {
+                        res.write(`data: ${JSON.stringify({ type: "log", event: ev })}\n\n`);
+                    }
+                }
+            });
+            logcat.on("error", () => { });
+        }
+        catch {
+            logcat = null;
+        }
+    }
+    req.on("close", () => {
+        closed = true;
+        clearInterval(heartbeat);
+        try {
+            upstream?.destroy();
+        }
+        catch {
+            // already torn down
+        }
+        try {
+            logcat?.kill();
+        }
+        catch {
+            // already dead
+        }
+    });
+}
 function listProfiles(res) {
     const profiles = transport.listProfiles();
     const activeUserId = transport.getActiveUserId();
-    res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-    res.end(JSON.stringify({ profiles, active_user_id: activeUserId }));
+    sendJson(res, 200, { profiles, active_user_id: activeUserId });
 }
 function activateRadar(res, userId) {
     // Reset cached state so ensureForward() re-runs adb forward. This handles
@@ -53,11 +574,10 @@ function activateRadar(res, userId) {
     transport.resetState();
     const forwarded = transport.ensureForward();
     if (!forwarded) {
-        res.writeHead(502, { "Content-Type": "application/json; charset=utf-8" });
-        res.end(JSON.stringify({
+        sendJson(res, 502, {
             ok: false,
             error: "ADB forward failed. Is a device connected?",
-        }));
+        });
         return;
     }
     try {
@@ -69,15 +589,16 @@ function activateRadar(res, userId) {
         }
     }
     catch (e) {
-        res.writeHead(502, { "Content-Type": "application/json; charset=utf-8" });
-        res.end(JSON.stringify({
+        sendJson(res, 502, {
             ok: false,
             error: `Broadcast failed: ${e.message}. Debug build not running?`,
-        }));
+        });
         return;
     }
-    res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-    res.end(JSON.stringify({ ok: true, user_id: userId ?? transport.getActiveUserId() ?? "auto" }));
+    sendJson(res, 200, {
+        ok: true,
+        user_id: userId ?? transport.getActiveUserId() ?? "auto",
+    });
 }
 function proxyToRadar(req, res) {
     const upstream = http.request({