@slack/radar-mcp 1.4.0 → 1.6.0

package/dist/shared/db.js

@@ -0,0 +1,415 @@
+/**
+ * On-device SQLite browser (host-side, read-only).
+ *
+ * Slack's on-device databases are plaintext SQLite (not SQLCipher) on a debug build,
+ * which is what makes host-side reading possible at all: `adb exec-out "run-as <pkg>
+ * cat databases/<db>"` streams the file to the host, where the platform-tools `sqlite3`
+ * binary runs read-only SELECT/PRAGMA against a local copy. Nothing is written on the
+ * device; no app rebuild is needed. If a future build encrypts these DBs, the magic-header
+ * check in `pullDatabase` fails fast with a clear message rather than producing garbage.
+ *
+ * SECURITY: a pulled DB is the full message store in plaintext (request bodies, message
+ * text, user/channel IDs). Pulled copies are written 0600 under a dedicated tmp dir and
+ * cleaned on server start/stop (see `cleanupPulledDatabases`). The DB names are learned
+ * live from the device (`listDatabases`); none are baked into this file.
+ */
+import { execFile, execFileSync } from "child_process";
+import { promisify } from "util";
+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 = 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 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");
+const ADB_MAX_BUFFER = 256 * 1024 * 1024; // an org message DB can be several MB
+const SQLITE_MAX_BUFFER = 64 * 1024 * 1024;
+// No cached user preference: the target user is passed explicitly to every call (sourced
+// from the dashboard's bound profile / the operator's profile switcher), never guessed.
+// Caching the sqlite binary path is safe because the binary does not change during a session.
+let cachedSqlite = null;
+function adbBin() {
+    const p = resolveAdbPath();
+    if (!p)
+        throw new Error("adb not found. Ensure platform-tools is installed and on PATH.");
+    return p;
+}
+function runAdb(args, opts = {}) {
+    return execFileSync(adbBin(), args, {
+        timeout: 15000,
+        maxBuffer: ADB_MAX_BUFFER,
+        ...opts,
+    });
+}
+const execFileP = promisify(execFile);
+// Async adb/exec — used for the HEAVY operations (the multi-MB device pull and the sqlite
+// query over it). These must NOT use execFileSync: Node is single-threaded, so a blocking
+// 62MB exec-out or a sqlite read freezes the whole event loop (every tab, the stream, and
+// /health hang until it returns). The light, cached probes (ls, pm list users) stay sync.
+function runAdbAsync(args) {
+    // buffer encoding: the pull streams raw SQLite bytes, not text.
+    return execFileP(adbBin(), args, {
+        timeout: 30000,
+        maxBuffer: ADB_MAX_BUFFER,
+        encoding: "buffer",
+    }).then((r) => r.stdout);
+}
+/**
+ * Locate a host `sqlite3`. The Slack on-device DBs use FTS5 virtual tables (search index),
+ * so a binary WITHOUT the fts5 module fails with "no such module: fts5" on those tables —
+ * including the per-table COUNT the browser runs. Android platform-tools' bundled sqlite3 is
+ * built without fts5; the macOS system /usr/bin/sqlite3 has it. So prefer an fts5-capable
+ * binary, and only fall back to a working-but-fts5-less one if none has it (non-FTS DBs still
+ * work there). Cached after first success.
+ */
+function hasSqlite(bin) {
+    try {
+        execFileSync(bin, ["--version"], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasFts5(bin) {
+    try {
+        // throws "no such module: fts5" on a binary built without it
+        execFileSync(bin, [":memory:", "CREATE VIRTUAL TABLE t USING fts5(x);"], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sqliteBin() {
+    if (cachedSqlite)
+        return cachedSqlite;
+    const candidates = [
+        "/usr/bin/sqlite3", // macOS system build: has fts5
+        "/opt/homebrew/bin/sqlite3",
+        "/usr/local/bin/sqlite3",
+        path.join(process.env.HOME ?? "", "Library/Android/sdk/platform-tools/sqlite3"),
+        "sqlite3",
+    ];
+    const working = candidates.filter(hasSqlite);
+    // Prefer one with fts5; else any working sqlite3 (non-FTS DBs still query fine).
+    cachedSqlite = working.find(hasFts5) ?? working[0] ?? "sqlite3";
+    return cachedSqlite;
+}
+/**
+ * Enumerate the Android user IDs present on the device from `pm list users`, whose lines
+ * read `UserInfo{<id>:<name>:<flags>} ...`. Returns the numeric ids as strings, in device
+ * order (personal 0 first, then profiles 10/11/12/... — NOT a hardcoded guess, so a second
+ * work profile or a cloned profile is covered). Empty on parse/adb failure.
+ */
+function deviceUserIds() {
+    try {
+        const out = runAdb(["shell", "pm list users"]).toString();
+        const ids = [];
+        for (const m of out.matchAll(/UserInfo\{(\d+):/g))
+            ids.push(m[1]);
+        return ids;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Probe whether the debug build is runnable for an Android user. Used to filter the
+ * device's users down to the profiles that actually have the build (a multi-profile device
+ * may have it on personal=0 and a work profile=10/11/..., each holding a DIFFERENT org's store).
+ */
+function userHasBuild(user) {
+    try {
+        runAdb([
+            "shell",
+            `run-as ${DB_PKG} ${user ? "--user " + user : ""} ls databases >/dev/null 2>&1 && echo ok`,
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Android users that actually have the debug build, enumerated from the device (not a
+ * fixed list). "" means a single-user device (no --user flag). Empty array => build not
+ * installed/debuggable anywhere.
+ *
+ * CACHED: this runs `pm list users` + a `run-as` probe per user — several blocking adb
+ * round-trips. The set of profiles does not change during a session, so probing it on every
+ * /dbs request froze the (single-threaded) event loop and hung the whole dashboard. Resolve
+ * it once and reuse; resetDbState() clears it for a device/profile change.
+ */
+let cachedUsers = null;
+export function availableUsers() {
+    if (cachedUsers)
+        return cachedUsers;
+    const ids = deviceUserIds();
+    const found = ids.filter(userHasBuild);
+    // Fallback for an older adb / odd `pm` output: try the no-flag form.
+    const resolved = found.length ? found : userHasBuild("") ? [""] : [];
+    if (resolved.length)
+        cachedUsers = resolved; // only cache a successful probe
+    return resolved;
+}
+/** `--user N` flag for a resolved user, or "" for the single-user case. */
+function userFlag(user) {
+    return user ? `--user ${user}` : "";
+}
+/**
+ * Reset cached device state. Clears the sqlite-binary path so a device swap
+ * re-detects it. The targeted Android user is passed explicitly to every call
+ * (sourced from the dashboard's bound profile) rather than guessed, so list / pull /
+ * query can never silently disagree on which profile's store they touch.
+ */
+export function resetDbState() {
+    cachedSqlite = null;
+    cachedUsers = null;
+}
+/** A DB name from the device. Reject anything that is not a bare filename. */
+function assertSafeName(name) {
+    if (!name || !/^[A-Za-z0-9._-]+$/.test(name)) {
+        throw new Error("invalid database name");
+    }
+}
+/**
+ * Local copy path, scoped by Android user. A work + personal profile can each hold a
+ * databases/<same-name> with DIFFERENT contents; without the user in the path, pulling
+ * one would overwrite the other's copy and queries would read the wrong profile's store.
+ */
+function localPath(name, user) {
+    const safeName = name.replace(/[^A-Za-z0-9._-]/g, "_");
+    const safeUser = (user || "single").replace(/[^A-Za-z0-9._-]/g, "_");
+    return path.join(DB_TMP, `u${safeUser}-${safeName}.sqlite`);
+}
+/**
+ * Resolve the Android user to target. The dashboard passes the profile it is bound to
+ * (transport.getActiveUserId()); if that user does not have the build (or none was
+ * passed), fall back to the first available profile. Throws if none is available.
+ */
+function resolveUser(user) {
+    const available = availableUsers();
+    if (!available.length) {
+        throw new Error(`cannot run-as ${DB_PKG}. Is the debug build installed and is a device connected?`);
+    }
+    if (user != null && available.includes(user))
+        return user;
+    return available[0];
+}
+/**
+ * List the on-device databases for the given Android user (the dashboard's bound
+ * profile). Filters out WAL/SHM/journal sidecar files. Returns the resolved user and
+ * the full set of profiles that have the build, so the UI can show which profile this
+ * store belongs to and offer a switch when more than one exists.
+ */
+export function listDatabases(user) {
+    // NOTE: do not resetDbState() here — that would re-run the multi-call user probe on every
+    // /dbs and freeze the event loop. The profile set is cached for the session; a device or
+    // profile change clears it via resetDbState() (wired to /enable / reconnect).
+    const available = availableUsers();
+    if (!available.length) {
+        throw new Error(`cannot run-as ${DB_PKG}. Is the debug build installed and is a device connected?`);
+    }
+    const u = user != null && available.includes(user) ? user : available[0];
+    const out = runAdb([
+        "shell",
+        `run-as ${DB_PKG} ${userFlag(u)} ls -1 databases`,
+    ]).toString();
+    const names = out
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .filter((n) => !/-(wal|shm|journal)$/.test(n));
+    return { user: u, availableUsers: available, names };
+}
+/**
+ * Stream a database off the device to a local 0600 copy (scoped to the target user) and
+ * return its path. `run-as ... cp` into shared storage fails silently (sandbox), so the
+ * working path is `exec-out cat` piped to a host file. Validates the SQLite magic header
+ * so a missing DB (whose `cat` emits an error string, not file bytes) fails with a clear
+ * message instead of being written as a junk file that later trips an opaque parse error.
+ *
+ * WAL: Slack's on-device DBs are WAL-mode and the live app holds write connections open,
+ * so recently-committed rows live in the `-wal` sidecar, NOT yet in the main file. Pulling
+ * the main file alone (and reading it `immutable`) silently drops those recent rows — the
+ * exact data a debugger wants. So we also pull the `-wal` and `-shm` sidecars next to the
+ * main copy (best-effort; absent if the DB was checkpointed), and queryDatabase opens the
+ * copy NORMALLY (not immutable) so SQLite replays the WAL into the view.
+ */
+export async function pullDatabase(name, user, force = false) {
+    assertSafeName(name);
+    const u = resolveUser(user);
+    // DB_TMP lives under os.tmpdir(), which the OS (or a manual cleanup) can wipe
+    // mid-session; recreate it every pull so writeFileSync cannot ENOENT on a gone dir.
+    // mode 0700: the pulled copies are the plaintext message store; even though each file is
+    // 0600, a world-traversable dir would leak the DB filenames to other local users.
+    fs.mkdirSync(DB_TMP, { recursive: true, mode: 0o700 });
+    const local = localPath(name, u);
+    // Pull-once: an on-device DB can be several MB and writes a plaintext copy to disk, so
+    // reuse the existing local copy across db-switches. The UI's Refresh control passes
+    // force=true to re-stream when the user wants the current device state.
+    if (!force && fs.existsSync(local))
+        return local;
+    let bytes;
+    try {
+        // Async exec-out so a multi-MB pull does not block the event loop (which would hang
+        // every other tab, the stream, and /health for the duration of the pull).
+        bytes = await runAdbAsync([
+            "exec-out",
+            `run-as ${DB_PKG} ${userFlag(u)} cat databases/${name}`,
+        ]);
+    }
+    catch {
+        throw new Error(`"${name}" is not readable on the device (not present for this profile, or run-as failed). List databases to see what is there.`);
+    }
+    if (!bytes ||
+        bytes.length < SQLITE_MAGIC.length ||
+        !bytes.subarray(0, SQLITE_MAGIC.length).equals(SQLITE_MAGIC)) {
+        throw new Error(`"${name}" did not come back as a valid SQLite file (${bytes ? bytes.length : 0} bytes). It may not exist on the device, the org may not be loaded on this profile, or the database may be encrypted.`);
+    }
+    fs.writeFileSync(local, bytes, { mode: 0o600 });
+    // Pull the WAL sidecars alongside the main file so the normal (non-immutable) open below
+    // replays recently-committed rows. Best-effort: a checkpointed DB has none; a `cat` of a
+    // missing sidecar returns empty, which we simply skip. Stale local sidecars from a prior
+    // pull are removed first so they cannot be mis-applied to a freshly-pulled main file.
+    // The main file and the sidecars are separate `cat` round-trips against a DB the app may
+    // be writing, so the snapshot is best-effort, not atomic: if the app checkpoints between
+    // the cats, SQLite finds a mismatched -wal salt and ignores it (a partial, not corrupt,
+    // view). Unavoidable without a device-side read lock; the normal-open choice still stands.
+    for (const ext of ["-wal", "-shm"]) {
+        const sidecar = local + ext;
+        try {
+            fs.rmSync(sidecar, { force: true });
+            const sb = await runAdbAsync([
+                "exec-out",
+                `run-as ${DB_PKG} ${userFlag(u)} cat databases/${name}${ext}`,
+            ]);
+            if (sb && sb.length > 0)
+                fs.writeFileSync(sidecar, sb, { mode: 0o600 });
+        }
+        catch {
+            // sidecar absent or unreadable — fine, the main file stands alone
+        }
+    }
+    return local;
+}
+/**
+ * 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.
+ *
+ * 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.
+ *   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 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)");
+    }
+    // Single statement only: a trailing `;` is fine, but no statement chaining (which is how
+    // `select 1; ATTACH ...; select * from s.t` smuggles a read past the leading-keyword check).
+    if (/;\s*\S/.test(sql)) {
+        throw new Error("only a single statement is allowed (no ';'-separated statements)");
+    }
+    // Reject the common write PRAGMAs: an assigning form (`PRAGMA user_version=5`,
+    // `PRAGMA journal_mode=DELETE`) or a checkpoint (`PRAGMA wal_checkpoint(...)`).
+    // 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");
+    }
+    // Belt-and-suspenders over -safe: reject the file-access primitives by name too.
+    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))
+        await pullDatabase(name, u);
+    let out;
+    try {
+        // Open the pulled copy NORMALLY (not `immutable`, not `-readonly`): pullDatabase brought
+        // the -wal/-shm sidecars along, and only a normal open replays the WAL so recently-
+        // committed rows (which live in -wal until the app checkpoints) are visible. immutable=1
+        // / -readonly would read the main file alone and silently drop those rows. The copy is in
+        // our own writable temp dir, so SQLite can do its WAL replay there; nothing on the device
+        // is touched. `-safe` is the load-bearing read-only/exfil control (blocks ATTACH/readfile/
+        // writefile/load_extension at the engine level) and holds in normal mode too. The path is
+        // URI-encoded so spaces/specials are safe. Async exec so a large query does not block the
+        // event loop.
+        const uri = `file:${encodeURI(local)}`;
+        const r = await execFileP(sqliteBin(), ["-safe", "-json", uri, sql], {
+            timeout: 15000,
+            maxBuffer: SQLITE_MAX_BUFFER,
+            encoding: "utf8",
+        });
+        out = String(r.stdout) || "[]";
+    }
+    catch (e) {
+        const err = e;
+        const stderr = (err.stderr && err.stderr.toString().trim()) || "";
+        const m = stderr.match(/(no such table:.*|no such column:.*|near ".*|syntax error.*|.*error.*)/i);
+        throw new Error(m ? m[0].trim() : stderr.split("\n")[0] || "query failed");
+    }
+    return JSON.parse(out);
+}
+/** Size in bytes of a pulled local copy for the given user, or 0 if not pulled. */
+export function pulledSize(name, user) {
+    try {
+        return fs.statSync(localPath(name, resolveUser(user))).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Remove all pulled database copies. Pulled DBs are plaintext message stores, so they
+ * must not linger; call on server start and stop. Best-effort.
+ */
+export function cleanupPulledDatabases() {
+    try {
+        fs.rmSync(DB_TMP, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort
+    }
+}

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