@slack/radar-mcp 1.3.0 → 1.5.0

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
+            }
+        }
+    }
+}