@slack/radar-mcp 1.5.0 → 1.7.0

package/dist/shared/screen.d.ts

@@ -49,9 +49,32 @@ export declare function cleanupRecordings(): void;
 export declare function resolveFfmpeg(): string | null;
 /** Whether scrcpy is installed (the no-ffmpeg fallback hint). Cached. */
 export declare function hasScrcpy(): boolean;
-/** The platform-specific copy-paste command to install ffmpeg. Never run automatically. */
+/**
+ * Re-probe ffmpeg/scrcpy ASYNCHRONOUSLY and update the cache, so the overlay can
+ * recover after a user installs ffmpeg mid-session without restarting the server.
+ *
+ * Why async (not a force flag on the sync probes): the sync `execFileSync` probes are
+ * safe only BECAUSE they are cached and run at most once (see the same rule in db.ts).
+ * Re-running them synchronously on every panel reopen would block the single event loop
+ * (the live MJPEG stream, /health, every tab) for the spawn duration. This path uses
+ * execFile (non-blocking) instead. It also ONLY re-probes a binary that is currently
+ * cached as absent: if ffmpeg was already found there is nothing to recover, so the
+ * common case does no work.
+ */
+export declare function refreshScreenCapabilities(): Promise<void>;
+/**
+ * A single runnable command to install ffmpeg on this platform. Never run
+ * automatically. This is presented as a copy-paste command, so it must be ONE
+ * runnable line: no parentheticals or alternatives, which would error if pasted
+ * into a shell. Alternative package managers belong in surrounding prose, not here.
+ */
 export declare function ffmpegInstallHint(): string;
-/** Capability summary for /health: what the screen overlay can do on this machine. */
+/**
+ * Capability summary for /health and /screen/caps: what the screen overlay can do
+ * on this machine. Reads the cached probe result. To recover after a mid-session
+ * ffmpeg install, call refreshScreenCapabilities() first (the /screen/caps?refresh=1
+ * path does this), then read here.
+ */
 export declare function screenCapabilities(): {
     screenshot: boolean;
     liveCast: boolean;
@@ -107,6 +130,16 @@ export declare function startLive(fps: number): LiveCast | null;
 /** Attach an HTTP response as a viewer of the live cast (after the multipart headers are written). */
 export declare function addViewer(L: LiveCast, res: NodeJS.WritableStream): void;
 export declare function removeViewer(res: NodeJS.WritableStream): void;
+/**
+ * Tear down the live cast when nothing is keeping it alive: no viewers AND no active
+ * recording. Either a viewer leaving or a recording stopping can be the last thing
+ * holding the cast, so both paths call this. The close-while-recording case needs it:
+ * the browser aborts the <img> (dropping the last viewer) BEFORE its record/stop POST
+ * resolves, so the viewer-leave finds recording still set and cannot reap; the cast
+ * would then run forever (screenrecord + ffmpeg) once the recording ends. Reaping again
+ * after stopRecording closes that gap.
+ */
+export declare function reapLiveIfIdle(): void;
 export declare function getLive(): LiveCast | null;
 export declare function lastFrame(): Buffer | null;
 export declare function primeIfNeeded(): Promise<void>;

package/dist/shared/screen.js

@@ -40,6 +40,7 @@ import { spawn, execFile, execFileSync } from "child_process";
 import fs from "fs";
 import os from "os";
 import path from "path";
+import { promisify } from "util";
 import { resolveAdbPath } from "./android.js";
 const SC_TMP = path.join(os.homedir(), ".slack-radar", "screen");
 /**
@@ -76,8 +77,10 @@ function adb() {
     return resolveAdbPath() ?? "adb";
 }
 // ---- host-binary detection (for the degrade tiers) --------------------------
+const execFileP = promisify(execFile);
 let ffmpegPath; // undefined = not probed, null = absent
 let scrcpyPresent;
+const FFMPEG_CANDIDATES = ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"];
 /** Resolve an ffmpeg binary, or null if none is installed. Cached. */
 export function resolveFfmpeg() {
     // Test hook: simulate a machine with no ffmpeg so the degrade path can be exercised
@@ -86,7 +89,7 @@ export function resolveFfmpeg() {
         return null;
     if (ffmpegPath !== undefined)
         return ffmpegPath;
-    for (const c of ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"]) {
+    for (const c of FFMPEG_CANDIDATES) {
         try {
             execFileSync(c, ["-version"], { timeout: 3000, stdio: "ignore" });
             ffmpegPath = c;
@@ -112,18 +115,72 @@ export function hasScrcpy() {
     }
     return scrcpyPresent;
 }
-/** The platform-specific copy-paste command to install ffmpeg. Never run automatically. */
+/**
+ * Re-probe ffmpeg/scrcpy ASYNCHRONOUSLY and update the cache, so the overlay can
+ * recover after a user installs ffmpeg mid-session without restarting the server.
+ *
+ * Why async (not a force flag on the sync probes): the sync `execFileSync` probes are
+ * safe only BECAUSE they are cached and run at most once (see the same rule in db.ts).
+ * Re-running them synchronously on every panel reopen would block the single event loop
+ * (the live MJPEG stream, /health, every tab) for the spawn duration. This path uses
+ * execFile (non-blocking) instead. It also ONLY re-probes a binary that is currently
+ * cached as absent: if ffmpeg was already found there is nothing to recover, so the
+ * common case does no work.
+ */
+export async function refreshScreenCapabilities() {
+    if (process.env.SLACK_RADAR_NO_FFMPEG === "1") {
+        ffmpegPath = null;
+    }
+    else if (ffmpegPath === undefined || ffmpegPath === null) {
+        // Not yet probed, or last probe found nothing: (re-)check now. Probe into a local
+        // and assign the cache only once, at the end, so a concurrent reader (a second tab,
+        // /health) keeps seeing the prior value during the probe instead of a transient
+        // null. Recovery only moves absent -> present, never the reverse.
+        let found = null;
+        for (const c of FFMPEG_CANDIDATES) {
+            try {
+                await execFileP(c, ["-version"], { timeout: 3000 });
+                found = c;
+                break;
+            }
+            catch {
+                // try next candidate
+            }
+        }
+        ffmpegPath = found;
+    }
+    if (scrcpyPresent === undefined || scrcpyPresent === false) {
+        try {
+            await execFileP("scrcpy", ["--version"], { timeout: 3000 });
+            scrcpyPresent = true;
+        }
+        catch {
+            scrcpyPresent = false;
+        }
+    }
+}
+/**
+ * A single runnable command to install ffmpeg on this platform. Never run
+ * automatically. This is presented as a copy-paste command, so it must be ONE
+ * runnable line: no parentheticals or alternatives, which would error if pasted
+ * into a shell. Alternative package managers belong in surrounding prose, not here.
+ */
 export function ffmpegInstallHint() {
     switch (process.platform) {
         case "darwin":
             return "brew install ffmpeg";
         case "win32":
-            return "winget install ffmpeg   (or: choco install ffmpeg)";
+            return "winget install ffmpeg";
         default:
-            return "sudo apt install ffmpeg   (or your distro's package manager)";
+            return "sudo apt install ffmpeg";
     }
 }
-/** Capability summary for /health: what the screen overlay can do on this machine. */
+/**
+ * Capability summary for /health and /screen/caps: what the screen overlay can do
+ * on this machine. Reads the cached probe result. To recover after a mid-session
+ * ffmpeg install, call refreshScreenCapabilities() first (the /screen/caps?refresh=1
+ * path does this), then read here.
+ */
 export function screenCapabilities() {
     const ffmpeg = resolveFfmpeg() !== null;
     return {
@@ -404,7 +461,19 @@ export function removeViewer(res) {
     if (!scLive)
         return;
     scLive.viewers.delete(res);
-    if (!scLive.viewers.size && !scLive.recording) {
+    reapLiveIfIdle();
+}
+/**
+ * Tear down the live cast when nothing is keeping it alive: no viewers AND no active
+ * recording. Either a viewer leaving or a recording stopping can be the last thing
+ * holding the cast, so both paths call this. The close-while-recording case needs it:
+ * the browser aborts the <img> (dropping the last viewer) BEFORE its record/stop POST
+ * resolves, so the viewer-leave finds recording still set and cannot reap; the cast
+ * would then run forever (screenrecord + ffmpeg) once the recording ends. Reaping again
+ * after stopRecording closes that gap.
+ */
+export function reapLiveIfIdle() {
+    if (scLive && !scLive.viewers.size && !scLive.recording) {
         cleanupLive(scLive);
         scLive = null;
     }

package/dist/shared/stream.d.ts

@@ -6,7 +6,7 @@ export interface RadarEvent {
     [key: string]: unknown;
 }
 export interface ParsedSSE {
-    type: "network" | "rtm";
+    type: "network" | "rtm" | "clog" | "log" | "trace";
     event: RadarEvent;
 }
 export declare const localNetworkBuffer: RadarEvent[];

package/dist/shared/transport.d.ts

@@ -6,6 +6,13 @@
  * device-specific operations. The MCP server and tool handlers
  * interact only through this interface.
  */
+/** Which underlying source served a getRecentLogs result. */
+export type LogSource = "app_buffer" | "logcat_capture" | "logcat_ring";
+/** Lines plus the source that produced them. */
+export interface LogResult {
+    lines: string[];
+    source: LogSource;
+}
 export interface DeviceTransport {
     /** Human-readable platform name (e.g. "android", "ios"). */
     readonly platform: string;
@@ -47,14 +54,15 @@ export interface DeviceTransport {
      */
     getAppState(): string;
     /**
-     * Get recent log entries filtered by tag.
+     * Get recent log entries, optionally filtered by tag.
      *
-     * @param tag Log tag to filter by
+     * @param tag Log tag to filter by. Empty string returns every line (no tag filter).
      * @param limit Max number of lines
      * @param grep Optional text to further filter
-     * @returns Array of matching log lines
+     * @returns The matching lines plus which source served them, so the caller can tell a
+     *   true-empty result from a silent fallback to an inferior source.
      */
-    getRecentLogs(tag: string, limit: number, grep?: string): string[];
+    getRecentLogs(tag: string, limit: number, grep?: string): LogResult;
     /**
      * Returns the currently active user ID, or null if none is set. On Android
      * this is the profile (e.g. "0" for personal, "10" for work); on iOS it
@@ -64,6 +72,16 @@ export interface DeviceTransport {
      * unchecked casts when asking "which profile did this capture?".
      */
     getActiveUserId(): string | null;
+    /**
+     * Resolve the user the debug build is actually running as, never null. Unlike
+     * getActiveUserId() (which returns null when nothing has been detected), this always
+     * resolves to a concrete profile, preferring the non-zero/secondary profile the work
+     * build runs under rather than blindly defaulting to user 0. Callers that need a definite
+     * target (the on-device DB browser) use this so list/pull/query never silently disagree
+     * on which profile's store they touch. On a single-user platform (iOS) this returns the
+     * sole user or an empty string.
+     */
+    resolveActiveUser(): string;
     /**
      * Returns the last error message from an `ensureForward()` failure, or null
      * if the last attempt succeeded or has not happened. Lets callers surface

package/dist/web/bin.d.ts

@@ -1,2 +1,17 @@
 #!/usr/bin/env node
-export {};
+/**
+ * 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 declare function isRadarSpecBody(statusCode: number | undefined, body: string): boolean;
+/**
+ * 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. 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.
+ */
+export declare function startWebServer(): void;

package/dist/web/bin.js

@@ -1,12 +1,113 @@
 #!/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;
@@ -20,10 +121,10 @@ function startWebServer() {
     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;
     });
@@ -37,6 +138,12 @@ function startWebServer() {
     // 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`),
@@ -46,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…");
@@ -66,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();
+}