@slack/radar-mcp 1.5.0 → 1.7.0

package/dist/mcp/tools.js

@@ -20,9 +20,10 @@ export const SERVER_INSTRUCTIONS = [
     '- "why isn\'t this loading" / "this is broken" -> screenshot + get_recent_network_calls(status_code=400 or 500)',
     '- "watch what happens when I..." -> clear_buffers then wait_for_events (DO NOT filter unless the user specifies a type)',
     '- "did that clog fire" / "check analytics" -> get_recent_clogs(name="...")',
+    '- "why is this slow" / "how long did X take" / "show me the traces" / "check performance" -> get_recent_traces(name="...") then get_trace_detail',
     '- "what API call was that" -> get_recent_network_calls then get_network_call_detail',
     '- "did I get X" / "did X happen" -> search(query="X") across ALL buffers, not just one',
-    '- "check the debug logs" -> get_recent_logs(tag="...")',
+    '- "check the debug logs" -> get_recent_logs (tag is OPTIONAL: pass tag="FKDebug" to filter, or omit it for all recent lines)',
     '- "save this" / "file this as a bug" / "share this" / "bundle this" / "attach to ticket" / "give me a repro" / "snapshot this" / "preserve this" / "hold this state" / "save what you just saw" -> capture_snapshot',
     "",
     "Key behaviors:",
@@ -203,6 +204,30 @@ export const TOOL_DEFINITIONS = [
         },
         annotations: { readOnlyHint: true },
     },
+    {
+        name: "get_recent_traces",
+        description: "Get recent performance trace summaries (one row per completed span from the app's telemetry pipeline). Returns trace name, span name, and duration. Use get_trace_detail for the full span, including its tags and the parent/trace ids.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max number of traces to return (default: 50)" },
+                name: { type: "string", description: "Filter by trace name or span name substring" },
+            },
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "get_trace_detail",
+        description: "Get full details of a specific performance trace by ID: trace and span names, the trace and parent ids, start/end/duration, and the span tags.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "The trace ID from get_recent_traces" },
+            },
+            required: ["id"],
+        },
+        annotations: { readOnlyHint: true },
+    },
     {
         name: "wait_for_events",
         description: "Wait for matching events to arrive in real-time via the SSE stream.",
@@ -211,7 +236,7 @@ export const TOOL_DEFINITIONS = [
             properties: {
                 event_type: { type: "string", description: "RTM event type to wait for" },
                 channel: { type: "string", description: "Filter by channel ID" },
-                source: { type: "string", description: "Wait for network calls or RTM events (default: both)" },
+                source: { type: "string", description: "Limit to one stream: network, rtm, clog, log, or trace (default: all)" },
                 timeout_ms: { type: "number", description: "Max time to wait in ms (default: 30000)" },
                 idle_timeout_ms: { type: "number", description: "Resolve after this many ms of silence (default: 3000)" },
             },
@@ -220,7 +245,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "search",
-        description: "Search across all captured network calls and RTM events.",
+        description: "Search across all captured network calls, RTM events, clogs, and performance traces.",
         inputSchema: {
             type: "object",
             properties: {
@@ -239,15 +264,14 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "get_recent_logs",
-        description: "Get recent logcat entries from the connected device, filtered by tag.",
+        description: "Get recent device logs for the Slack debug build. Reads the app's own log buffer first (the DEBUG-and-above Timber lines the in-app Log Viewer shows, this app only), and falls back to an adb logcat snapshot when that buffer cannot be read. The result includes a `source` field (app_buffer / logcat_capture / logcat_ring) so you can tell a real empty result from a fallback. Leave `tag` out to get all recent lines. For native crashes, VERBOSE lines, or non-Slack processes, use adb logcat directly.",
         inputSchema: {
             type: "object",
             properties: {
-                tag: { type: "string", description: "Logcat tag to filter by" },
-                limit: { type: "number", description: "Max number of lines to return (default: 50)" },
+                tag: { type: "string", description: "Optional substring to filter log lines by (matched anywhere in the line, not an exact tag-column match). Omit to return all recent lines." },
+                limit: { type: "number", description: "Max number of lines to return (default: 50, capped at 1000)" },
                 grep: { type: "string", description: "Optional text to grep within the filtered output" },
             },
-            required: ["tag"],
         },
         annotations: { readOnlyHint: true },
     },
@@ -418,6 +442,45 @@ export const TOOL_DEFINITIONS = [
         // Not read-only: it starts a local web server and pushes a spec to it.
         annotations: { readOnlyHint: false, idempotentHint: true },
     },
+    {
+        name: "list_databases",
+        description: "List the app's on-device SQLite databases (the message store, telemetry, etc.) for the bound profile.",
+        inputSchema: { type: "object", properties: {} },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "list_tables",
+        description: "List the tables (with row counts) in one on-device database. Pass a name from list_databases.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                db: { type: "string", description: "Database name from list_databases" },
+                refresh: {
+                    type: "boolean",
+                    description: "Re-pull a fresh copy from the device instead of reusing the cached pull (default false)",
+                },
+            },
+            required: ["db"],
+        },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "query_database",
+        description: "Run a read-only SQL query against an on-device database and get the rows back. SELECT/PRAGMA/WITH only (writes and file access are blocked). Use it to answer 'is this row actually in the DB?' during a debug session. Results are capped by row count and total size (the store is plaintext PII); when trimmed the response sets truncated:true with total_rows, so narrow with WHERE/LIMIT and avoid group_concat/blob dumps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                db: { type: "string", description: "Database name from list_databases" },
+                sql: { type: "string", description: "A single read-only statement (SELECT, WITH, PRAGMA, EXPLAIN)" },
+                refresh: {
+                    type: "boolean",
+                    description: "Re-pull a fresh copy from the device before querying (default false reuses this session's cached pull)",
+                },
+            },
+            required: ["db", "sql"],
+        },
+        annotations: { readOnlyHint: true },
+    },
 ];
 /**
  * Check whether a tool call should be blocked by the session gate.

package/dist/shared/android.d.ts

@@ -1,4 +1,4 @@
-import type { DeviceTransport } from "./transport.js";
+import type { DeviceTransport, LogResult } from "./transport.js";
 /**
  * Resolve the adb binary. MCP servers spawned from GUI launchers (Spotlight,
  * Raycast, Dock) do not inherit the user's shell PATH, so a bare `adb` call
@@ -44,7 +44,7 @@ export declare class AndroidTransport implements DeviceTransport {
     screenshot(fullRes: boolean): string;
     recordScreen(durationS: number): string;
     getAppState(): string;
-    getRecentLogs(tag: string, limit: number, grep?: string): string[];
+    getRecentLogs(tag: string, limit: number, grep?: string): LogResult;
     listProfiles(): {
         userId: string;
         label: string;

package/dist/shared/android.js

@@ -1,8 +1,9 @@
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { getCaptureFilePath, isCapturing, readRecentLogs, registerCleanup, rotateCaptureIfNeeded, startCapture, stopCapture, } from "./logcat-capture.js";
+import { readDebugLogBuffer } from "./debug-log.js";
+import { filterLogLines, getCaptureFilePath, isCapturing, readRecentLogs, registerCleanup, rotateCaptureIfNeeded, startCapture, stopCapture, } from "./logcat-capture.js";
 const RADAR_PORT = 8099;
 const SOCKET_NAME = "slack-radar";
 const ENABLE_ACTION = "slack.debug.ENABLE_RADAR";
@@ -199,8 +200,19 @@ export class AndroidTransport {
     getRecentLogs(tag, limit, grep) {
         if (!ADB)
             throw new Error("adb not found on PATH or common SDK locations");
-        // Preferred path: read from the session capture file so lines cannot
-        // have been evicted from the device ring buffer between enable and now.
+        // Primary source: the app's own DebugLogger buffer, read off the sandbox via
+        // run-as. This is the app's structured log (exact tags, no logcat column
+        // padding) and survives the radar enable/disable cycle, so it does not lose
+        // lines to device-logcat ring eviction between enable and read. Target the
+        // profile Radar is bound to (resolveActiveUser prefers the non-zero/work
+        // profile), not a blind user 0, so a dual-profile device reads the right
+        // sandbox -- matching how the DB browser threads its user.
+        const appLog = readDebugLogBuffer(ADB, this.resolveActiveUser());
+        if (appLog !== null) {
+            return { lines: filterLogLines(appLog, tag, limit, grep), source: "app_buffer" };
+        }
+        // Fallback: read from the session capture file so lines cannot have been
+        // evicted from the device ring buffer between enable and now.
         if (isCapturing()) {
             // Opportunistic rotation. Stop+rename+restart when the file grows
             // past the threshold so the child never writes past a truncated EOF.
@@ -208,20 +220,25 @@ export class AndroidTransport {
             rotateCaptureIfNeeded(ADB);
             const lines = readRecentLogs(tag, limit, grep);
             if (lines !== null)
-                return lines;
+                return { lines, source: "logcat_capture" };
         }
         // Fallback: device ring buffer snapshot. Used when capture is not running
-        // (activate() was skipped, child died, or the file was deleted).
-        let cmd = `${ADB} logcat -d | grep -F "${tag}" | tail -${limit}`;
-        if (grep) {
-            cmd = `${ADB} logcat -d | grep -F "${tag}" | grep -i "${grep.replace(/"/g, '\\"')}" | tail -${limit}`;
-        }
-        const output = execSync(cmd, {
+        // (activate() was skipped, child died, or the file was deleted). No shell:
+        // dump the ring with execFileSync (argv, so a tag/grep with a backtick,
+        // $(...), or trailing backslash cannot break out of a command string) and do
+        // the tag/grep/limit filtering in pure JS via the same filterLogLines the
+        // other two sources use. An empty tag means "no filter" (includes("") is
+        // true), so the whole tail is returned.
+        const output = execFileSync(ADB, ["logcat", "-d"], {
             timeout: 10000,
-            shell: "/bin/zsh",
             encoding: "utf-8",
+            maxBuffer: 64 * 1024 * 1024,
         });
-        return output.trim().split("\n").filter(Boolean);
+        const lines = output.split("\n").filter(Boolean);
+        return {
+            lines: filterLogLines(lines, tag, limit, grep),
+            source: "logcat_ring",
+        };
     }
     listProfiles() {
         if (!ADB)

package/dist/shared/constants.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Package version, read once from package.json at load — NOT a hardcoded copy, so it cannot
+ * drift from the published version. Surfaced as the `X-Radar-Version` header on /spec so a
+ * second launcher can tell whether the dashboard already holding the port is a different
+ * Radar version than itself (the adopt path notices a mismatch; it still adopts, never kills).
+ * Falls back to "unknown" if package.json cannot be read (should not happen in a real install).
+ */
+export declare const RADAR_VERSION: string;
 /** Port used to reach the on-device radar HTTP server via forwarding. */
 export declare const RADAR_PORT = 8099;
 /** Host address for the forwarded connection. */
@@ -24,3 +32,10 @@ export declare const MAX_LOG_SESSION_BUFFER = 20000;
  * `SLACK_RADAR_WEB_PORT` env override.
  */
 export declare const WEB_PORT_DEFAULT = 8100;
+/**
+ * The Slack debug build whose sandbox the host can `run-as` into. Both the
+ * on-device SQLite browser (db.ts) and the app log-buffer reader (debug-log.ts)
+ * read sandbox files through `adb exec-out "run-as <pkg> ..."`, which only works
+ * on a debuggable build. Defined once here so the two readers cannot drift.
+ */
+export declare const SLACK_DEBUG_PKG = "com.Slack.internal.debug";

package/dist/shared/constants.js

@@ -1,3 +1,20 @@
+import { createRequire } from "module";
+/**
+ * Package version, read once from package.json at load — NOT a hardcoded copy, so it cannot
+ * drift from the published version. Surfaced as the `X-Radar-Version` header on /spec so a
+ * second launcher can tell whether the dashboard already holding the port is a different
+ * Radar version than itself (the adopt path notices a mismatch; it still adopts, never kills).
+ * Falls back to "unknown" if package.json cannot be read (should not happen in a real install).
+ */
+export const RADAR_VERSION = (() => {
+    try {
+        const require = createRequire(import.meta.url);
+        return require("../../package.json").version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
 /** Port used to reach the on-device radar HTTP server via forwarding. */
 export const RADAR_PORT = 8099;
 /** Host address for the forwarded connection. */
@@ -24,3 +41,10 @@ export const MAX_LOG_SESSION_BUFFER = 20000;
  * `SLACK_RADAR_WEB_PORT` env override.
  */
 export const WEB_PORT_DEFAULT = 8100;
+/**
+ * The Slack debug build whose sandbox the host can `run-as` into. Both the
+ * on-device SQLite browser (db.ts) and the app log-buffer reader (debug-log.ts)
+ * read sandbox files through `adb exec-out "run-as <pkg> ..."`, which only works
+ * on a debuggable build. Defined once here so the two readers cannot drift.
+ */
+export const SLACK_DEBUG_PKG = "com.Slack.internal.debug";

package/dist/shared/db.d.ts

@@ -13,8 +13,12 @@
  * cleaned on server start/stop (see `cleanupPulledDatabases`). The DB names are learned
  * live from the device (`listDatabases`); none are baked into this file.
  */
-/** Initialize DB_TMP with a port-scoped path. Call from the web server on startup. */
-export declare function initializeDatabasePath(port: number): void;
+/**
+ * Initialize DB_TMP with a per-process-unique path. Call on startup. The web server scopes
+ * by its port; the MCP server scopes by process.pid (every MCP shares one fixed port, so a
+ * port key would collide between two concurrent MCP servers).
+ */
+export declare function initializeDatabasePath(scopeKey: number): void;
 export declare function availableUsers(): string[];
 /**
  * Reset cached device state. Clears the sqlite-binary path so a device swap
@@ -50,20 +54,33 @@ export declare function listDatabases(user?: string | null): {
  */
 export declare function pullDatabase(name: string, user?: string | null, force?: boolean): Promise<string>;
 /**
- * Run a read-only query against a (lazily pulled) local copy.
+ * Read-only SQL gate. Throws on anything that is not a single read-only statement.
+ *
+ * Exported so a caller (the MCP query handler) can reject a bad query BEFORE pulling a
+ * multi-MB DB copy off the device. queryDatabase calls it too, so the boundary holds even
+ * if a caller forgets the pre-check.
  *
- * Read-only is NOT just about blocking writes. `sqlite3 -readonly` forbids writes to the
- * opened DB, but a single SELECT can still READ any host file the process can open, via
- * `ATTACH '/path' AS x; SELECT * FROM x.t` or `SELECT readfile('/path')` — a confidentiality
- * bypass (the other plaintext Slack DBs, any file on disk), reachable through the query box
- * or a pushed db-spec's `sql`. Three layers close this:
- *   1. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
- *      load_extension while still allowing ordinary SELECT/PRAGMA. This is the load-bearing
+ * What actually keeps this safe (the boundary does NOT rest on this gate alone):
+ *   1. copy-based design — we only ever READ the device file (`exec-out cat`) and query a
+ *      throwaway local copy; nothing is ever written back, so no query can mutate device
+ *      state no matter what it does to the copy.
+ *   2. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
+ *      load_extension while still allowing ordinary SELECT/PRAGMA. The load-bearing exfil
  *      control; a keyword denylist alone is whack-a-mole.
- *   2. the guard below: only a SINGLE SELECT/PRAGMA statement (no `;`-chaining), and an
- *      explicit reject of attach/readfile/writefile names as defense in depth.
- *   3. `-readonly` still blocks writes to the opened DB.
- * Surfaces sqlite's own error message on failure.
+ *   3. this gate — a single SELECT/PRAGMA/WITH/EXPLAIN/VALUES statement (no `;`-chaining),
+ *      a write-PRAGMA reject, and an explicit reject of file-access primitive names as
+ *      defense in depth.
+ * NOTE: the copy is opened NORMALLY (not `-readonly`, not `immutable`) on purpose, so SQLite
+ * replays the `-wal` sidecar and recently-committed rows stay visible. `-readonly`/immutable
+ * would read the main file alone and silently drop them; writes to the throwaway copy are
+ * harmless. So `-readonly` is intentionally NOT passed — the read-only guarantee comes from
+ * (1) and (2), not from the open mode.
+ */
+export declare function assertReadOnlyQuery(sql: string): void;
+/**
+ * Run a read-only query against a (lazily pulled) local copy. The query is gated by
+ * assertReadOnlyQuery (see there for the full read-only/exfil rationale). Surfaces sqlite's
+ * own error message on failure.
  */
 export declare function queryDatabase(name: string, sql: string, user?: string | null): Promise<unknown[]>;
 /** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */

package/dist/shared/db.js

@@ -19,13 +19,18 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { resolveAdbPath } from "./android.js";
+import { SLACK_DEBUG_PKG } from "./constants.js";
 /** The debug build whose sandbox we can `run-as` into. */
-const DB_PKG = "com.Slack.internal.debug";
-/** Dedicated tmp dir for pulled DB copies. Cleaned on start/stop; files written 0600. Port-scoped so concurrent dashboards do not collide. */
+const DB_PKG = SLACK_DEBUG_PKG;
+/** Dedicated tmp dir for pulled DB copies. Cleaned on start/stop; files written 0600. Scoped by a per-process key so concurrent readers do not collide. */
 let DB_TMP = path.join(os.tmpdir(), "slack-radar-db");
-/** Initialize DB_TMP with a port-scoped path. Call from the web server on startup. */
-export function initializeDatabasePath(port) {
-    DB_TMP = path.join(os.tmpdir(), `slack-radar-db-${port}`);
+/**
+ * Initialize DB_TMP with a per-process-unique path. Call on startup. The web server scopes
+ * by its port; the MCP server scopes by process.pid (every MCP shares one fixed port, so a
+ * port key would collide between two concurrent MCP servers).
+ */
+export function initializeDatabasePath(scopeKey) {
+    DB_TMP = path.join(os.tmpdir(), `slack-radar-db-${scopeKey}`);
 }
 /** Every valid SQLite file begins with these 16 bytes. */
 const SQLITE_MAGIC = Buffer.from("SQLite format 3\0", "binary");
@@ -302,31 +307,32 @@ export async function pullDatabase(name, user, force = false) {
     return local;
 }
 /**
- * Run a read-only query against a (lazily pulled) local copy.
+ * Read-only SQL gate. Throws on anything that is not a single read-only statement.
+ *
+ * Exported so a caller (the MCP query handler) can reject a bad query BEFORE pulling a
+ * multi-MB DB copy off the device. queryDatabase calls it too, so the boundary holds even
+ * if a caller forgets the pre-check.
  *
- * Read-only is NOT just about blocking writes. `sqlite3 -readonly` forbids writes to the
- * opened DB, but a single SELECT can still READ any host file the process can open, via
- * `ATTACH '/path' AS x; SELECT * FROM x.t` or `SELECT readfile('/path')` — a confidentiality
- * bypass (the other plaintext Slack DBs, any file on disk), reachable through the query box
- * or a pushed db-spec's `sql`. Three layers close this:
- *   1. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
- *      load_extension while still allowing ordinary SELECT/PRAGMA. This is the load-bearing
+ * What actually keeps this safe (the boundary does NOT rest on this gate alone):
+ *   1. copy-based design — we only ever READ the device file (`exec-out cat`) and query a
+ *      throwaway local copy; nothing is ever written back, so no query can mutate device
+ *      state no matter what it does to the copy.
+ *   2. `sqlite3 -safe` — engine-level: forbids ATTACH, readfile/writefile/edit, and
+ *      load_extension while still allowing ordinary SELECT/PRAGMA. The load-bearing exfil
  *      control; a keyword denylist alone is whack-a-mole.
- *   2. the guard below: only a SINGLE SELECT/PRAGMA statement (no `;`-chaining), and an
- *      explicit reject of attach/readfile/writefile names as defense in depth.
- *   3. `-readonly` still blocks writes to the opened DB.
- * Surfaces sqlite's own error message on failure.
+ *   3. this gate — a single SELECT/PRAGMA/WITH/EXPLAIN/VALUES statement (no `;`-chaining),
+ *      a write-PRAGMA reject, and an explicit reject of file-access primitive names as
+ *      defense in depth.
+ * NOTE: the copy is opened NORMALLY (not `-readonly`, not `immutable`) on purpose, so SQLite
+ * replays the `-wal` sidecar and recently-committed rows stay visible. `-readonly`/immutable
+ * would read the main file alone and silently drop them; writes to the throwaway copy are
+ * harmless. So `-readonly` is intentionally NOT passed — the read-only guarantee comes from
+ * (1) and (2), not from the open mode.
  */
-export async function queryDatabase(name, sql, user) {
-    assertSafeName(name);
-    // Leading-keyword gate over the common read-query entry forms: SELECT, WITH
-    // (CTEs, common against the message store), EXPLAIN, VALUES, PRAGMA. This shapes
-    // UX; it is NOT the security boundary. A `WITH ... DELETE` would slip the gate,
-    // but the device-safety property does not rest here — it rests on the copy-based
-    // design (the device file is `cat`'d to a throwaway and never written back), plus
-    // `-safe` (blocks file access), the single-statement gate, the write-PRAGMA
-    // reject, and the file-primitive denylist below. Worst case a smuggled write
-    // mutates the disposable copy; the device store is untouched.
+export function assertReadOnlyQuery(sql) {
+    // Leading-keyword gate over the common read-query entry forms. This shapes UX; it is NOT
+    // the security boundary (a `WITH ... DELETE` would slip it, but that can only touch the
+    // throwaway copy). The boundary is the copy-based design + `-safe` above.
     if (!/^\s*(select|pragma|with|explain|values)\b/i.test(sql)) {
         throw new Error("only read-only statements are allowed (SELECT, WITH, EXPLAIN, VALUES, PRAGMA)");
     }
@@ -337,11 +343,8 @@ export async function queryDatabase(name, sql, user) {
     }
     // Reject the common write PRAGMAs: an assigning form (`PRAGMA user_version=5`,
     // `PRAGMA journal_mode=DELETE`) or a checkpoint (`PRAGMA wal_checkpoint(...)`).
-    // This is not exhaustive — a few argless mutating PRAGMAs (`incremental_vacuum`,
-    // `optimize`, `shrink_memory`) still pass. That is acceptable: the device-safety
-    // guarantee comes from the copy-based design (we only ever read the device file
-    // and write a throwaway local copy), not from this gate. Worst case such a PRAGMA
-    // mutates the disposable copy; the device store is never written back.
+    // Not exhaustive — a few argless mutating PRAGMAs (`incremental_vacuum`, `optimize`,
+    // `shrink_memory`) still pass. Acceptable: worst case they mutate the disposable copy.
     if (/^\s*pragma\b/i.test(sql) && (/=/.test(sql) || /\bwal_checkpoint\b/i.test(sql))) {
         throw new Error("that PRAGMA writes; only read-only PRAGMAs are allowed");
     }
@@ -349,6 +352,15 @@ export async function queryDatabase(name, sql, user) {
     if (/\b(attach|readfile|writefile|edit|load_extension|fts3_tokenizer)\b/i.test(sql)) {
         throw new Error("that function/statement is not allowed (read-only, no file access)");
     }
+}
+/**
+ * Run a read-only query against a (lazily pulled) local copy. The query is gated by
+ * assertReadOnlyQuery (see there for the full read-only/exfil rationale). Surfaces sqlite's
+ * own error message on failure.
+ */
+export async function queryDatabase(name, sql, user) {
+    assertSafeName(name);
+    assertReadOnlyQuery(sql);
     const u = resolveUser(user);
     const local = localPath(name, u);
     if (!fs.existsSync(local))

package/dist/shared/debug-log.d.ts

@@ -0,0 +1,50 @@
+/**
+ * On-device app log buffer reader (host-side, read-only).
+ *
+ * The Slack app plants a Timber tree (`DebugMenuLoggingTree`) on debug builds that
+ * captures every DEBUG-and-above log line into a rolling on-disk buffer
+ * (`slack.commons.logger.DebugLogger`): six files `debug.log0`..`debug.log5` in the
+ * app sandbox `files/` dir, ~256KB each. `debug.log0` is the newest file; on rotation
+ * files shift up and the oldest is dropped. Within a file, the oldest line is at the top.
+ * Each line is formatted `[timestamp] TAG : message` with NO logcat column padding.
+ *
+ * This is the app's own structured log buffer, which is strictly better than scraping
+ * `adb logcat`: it survives the radar enable/disable cycle, is not subject to the device
+ * logcat ring being evicted, and carries the exact tag the app logged with. We read it the
+ * same way the DB browser reads the message store: `adb exec-out "run-as <pkg> cat ..."`,
+ * which works because debug builds are `run-as`-able. Nothing is written on the device.
+ *
+ * SECURITY: app logs can contain user/channel IDs and message fragments. This reader only
+ * returns lines to the caller (no host-side file is written), and the tag/grep filter is
+ * applied before return.
+ */
+/**
+ * Build the oldest-to-newest list of sandbox-relative log file paths. DebugLogger keeps
+ * `debug.log0` newest, so chronological order is log5, log4, ..., log0.
+ */
+export declare function debugLogFileOrder(count?: number): string[];
+/**
+ * Concatenate raw file contents (passed oldest-file-first) into a single chronological
+ * line array. Each file is already oldest-line-first, so a flat concat preserves order.
+ * Blank lines are dropped. Pure: no device access, unit-testable against fixtures.
+ */
+export declare function flattenDebugLogFiles(contentsOldestFirst: string[]): string[];
+/**
+ * A `run-as` denial does NOT fail the adb command: `adb exec-out` exits 0 and the helper's
+ * error ("run-as: unknown package: ...", "run-as: ... not debuggable", "run-as: couldn't
+ * stat ...") is written to stdout, where it would otherwise be mistaken for a log line.
+ * So failure must be detected by inspecting the output, not by catching an exception. This
+ * returns the run-as error message when the output is a denial, else null. Pure and testable.
+ */
+export declare function detectRunAsError(output: string): string | null;
+/**
+ * Read the app's DebugLogger buffer off the device via `run-as` and return its lines in
+ * chronological order (oldest first). Returns null when the buffer cannot be read so the
+ * caller can fall back to a logcat snapshot. Two distinct null cases, deliberately kept
+ * apart: a `run-as` failure (no device, the debug build is not installed, or it is not
+ * debuggable on this profile) is a condition the user likely wants to know about, so it is
+ * logged to stderr before falling back; an empty buffer (debug build present, nothing logged
+ * yet) is benign and silent. A specific `user` (Android multi-user id) is forwarded to
+ * run-as when provided.
+ */
+export declare function readDebugLogBuffer(adbPath: string, user?: string): string[] | null;

package/dist/shared/debug-log.js

@@ -0,0 +1,108 @@
+/**
+ * On-device app log buffer reader (host-side, read-only).
+ *
+ * The Slack app plants a Timber tree (`DebugMenuLoggingTree`) on debug builds that
+ * captures every DEBUG-and-above log line into a rolling on-disk buffer
+ * (`slack.commons.logger.DebugLogger`): six files `debug.log0`..`debug.log5` in the
+ * app sandbox `files/` dir, ~256KB each. `debug.log0` is the newest file; on rotation
+ * files shift up and the oldest is dropped. Within a file, the oldest line is at the top.
+ * Each line is formatted `[timestamp] TAG : message` with NO logcat column padding.
+ *
+ * This is the app's own structured log buffer, which is strictly better than scraping
+ * `adb logcat`: it survives the radar enable/disable cycle, is not subject to the device
+ * logcat ring being evicted, and carries the exact tag the app logged with. We read it the
+ * same way the DB browser reads the message store: `adb exec-out "run-as <pkg> cat ..."`,
+ * which works because debug builds are `run-as`-able. Nothing is written on the device.
+ *
+ * SECURITY: app logs can contain user/channel IDs and message fragments. This reader only
+ * returns lines to the caller (no host-side file is written), and the tag/grep filter is
+ * applied before return.
+ */
+import { execFileSync } from "child_process";
+import { SLACK_DEBUG_PKG } from "./constants.js";
+/** The debug build whose sandbox we can `run-as` into. */
+const LOG_PKG = SLACK_DEBUG_PKG;
+/** Number of rolling log files DebugLogger maintains (debug.log0..debug.log5). */
+const LOG_FILE_COUNT = 6;
+const ADB_MAX_BUFFER = 16 * 1024 * 1024; // total buffer is ~1.5MB; headroom for safety.
+/**
+ * Build the oldest-to-newest list of sandbox-relative log file paths. DebugLogger keeps
+ * `debug.log0` newest, so chronological order is log5, log4, ..., log0.
+ */
+export function debugLogFileOrder(count = LOG_FILE_COUNT) {
+    const files = [];
+    for (let i = count - 1; i >= 0; i--)
+        files.push(`files/debug.log${i}`);
+    return files;
+}
+/**
+ * Concatenate raw file contents (passed oldest-file-first) into a single chronological
+ * line array. Each file is already oldest-line-first, so a flat concat preserves order.
+ * Blank lines are dropped. Pure: no device access, unit-testable against fixtures.
+ */
+export function flattenDebugLogFiles(contentsOldestFirst) {
+    return contentsOldestFirst
+        .join("\n")
+        .split("\n")
+        .filter((line) => line.length > 0);
+}
+/**
+ * A `run-as` denial does NOT fail the adb command: `adb exec-out` exits 0 and the helper's
+ * error ("run-as: unknown package: ...", "run-as: ... not debuggable", "run-as: couldn't
+ * stat ...") is written to stdout, where it would otherwise be mistaken for a log line.
+ * So failure must be detected by inspecting the output, not by catching an exception. This
+ * returns the run-as error message when the output is a denial, else null. Pure and testable.
+ */
+export function detectRunAsError(output) {
+    const first = output.trimStart().split("\n")[0] ?? "";
+    return first.startsWith("run-as:") ? first.trim() : null;
+}
+/**
+ * Read the app's DebugLogger buffer off the device via `run-as` and return its lines in
+ * chronological order (oldest first). Returns null when the buffer cannot be read so the
+ * caller can fall back to a logcat snapshot. Two distinct null cases, deliberately kept
+ * apart: a `run-as` failure (no device, the debug build is not installed, or it is not
+ * debuggable on this profile) is a condition the user likely wants to know about, so it is
+ * logged to stderr before falling back; an empty buffer (debug build present, nothing logged
+ * yet) is benign and silent. A specific `user` (Android multi-user id) is forwarded to
+ * run-as when provided.
+ */
+export function readDebugLogBuffer(adbPath, user) {
+    const catList = debugLogFileOrder().join(" ");
+    // One run-as invocation with the given user flag; cats every file oldest-first. Missing files
+    // are tolerated (2>/dev/null) so a not-yet-rotated buffer with only debug.log0 reads cleanly.
+    // Returns the raw stdout, or an Error if adb itself failed (distinct from a run-as denial,
+    // which exits 0 with the helper error in stdout).
+    const runAs = (userFlag) => {
+        try {
+            return execFileSync(adbPath, ["exec-out", `run-as ${LOG_PKG} ${userFlag}sh -c 'cat ${catList} 2>/dev/null'`], { timeout: 10000, maxBuffer: ADB_MAX_BUFFER, encoding: "utf-8" });
+        }
+        catch (err) {
+            return err instanceof Error ? err : new Error(String(err));
+        }
+    };
+    let output = runAs(user ? `--user ${user} ` : "");
+    if (output instanceof Error) {
+        // adb itself failed (no device, adb not running). Surface and fall back.
+        console.error(`[slack-radar] app log buffer unavailable (adb error: ${output.message.split("\n")[0]}); falling back to logcat`);
+        return null;
+    }
+    // run-as denial: adb exited 0 but the helper error is in stdout. On old adb the `--user N`
+    // form can be the denial while the no-flag form works (db.ts resolves users with the same
+    // no-flag fallback). So before giving up to logcat, retry once with no user flag — but only
+    // when a flag was actually used, else we would just repeat the identical call.
+    let runAsError = detectRunAsError(output);
+    if (runAsError && user) {
+        const retry = runAs("");
+        if (!(retry instanceof Error) && !detectRunAsError(retry)) {
+            output = retry;
+            runAsError = null;
+        }
+    }
+    if (runAsError) {
+        console.error(`[slack-radar] app log buffer unavailable (${runAsError}); falling back to logcat`);
+        return null;
+    }
+    const lines = flattenDebugLogFiles([output]);
+    return lines.length > 0 ? lines : null;
+}