@slack/radar-mcp 1.14.0 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +15 -3
  2. package/dist/mcp/db-tools.js +23 -0
  3. package/dist/mcp/dispatch.d.ts +4 -0
  4. package/dist/mcp/dispatch.js +26 -0
  5. package/dist/mcp/index.js +104 -32
  6. package/dist/mcp/platform-detect.d.ts +110 -0
  7. package/dist/mcp/platform-detect.js +246 -0
  8. package/dist/mcp/prefs-tools.d.ts +4 -3
  9. package/dist/mcp/prefs-tools.js +26 -3
  10. package/dist/mcp/session-enable.js +19 -1
  11. package/dist/mcp/snapshot.js +4 -1
  12. package/dist/mcp/sources-gate.js +6 -3
  13. package/dist/mcp/tools.d.ts +11 -0
  14. package/dist/mcp/tools.js +38 -0
  15. package/dist/shared/android.d.ts +40 -1
  16. package/dist/shared/android.js +114 -51
  17. package/dist/shared/constants.d.ts +25 -1
  18. package/dist/shared/constants.js +27 -1
  19. package/dist/shared/db.js +11 -2
  20. package/dist/shared/debug-log.js +6 -1
  21. package/dist/shared/enable-diagnosis.d.ts +28 -0
  22. package/dist/shared/enable-diagnosis.js +41 -0
  23. package/dist/shared/prefs.d.ts +0 -5
  24. package/dist/shared/prefs.js +6 -2
  25. package/dist/shared/screen.d.ts +46 -9
  26. package/dist/shared/screen.js +74 -11
  27. package/dist/shared/transport.d.ts +62 -5
  28. package/dist/shared/webapp.d.ts +50 -0
  29. package/dist/shared/webapp.js +65 -0
  30. package/dist/web/install-app.d.ts +87 -0
  31. package/dist/web/install-app.js +703 -0
  32. package/dist/web/macapp/RadarApp.swift +466 -0
  33. package/dist/web/public/icons/radar-1024.png +0 -0
  34. package/dist/web/public/icons/radar.svg +40 -0
  35. package/dist/web/public/index.html +41 -1
  36. package/dist/web/public/next/app.js +3 -0
  37. package/dist/web/public/next/db.js +145 -5
  38. package/dist/web/public/next/feed.js +18 -0
  39. package/dist/web/public/next/hooks.js +10 -1
  40. package/dist/web/public/next/screen.js +147 -43
  41. package/dist/web/public/next/store.js +114 -16
  42. package/dist/web/public/next/toast.js +134 -0
  43. package/dist/web/server.d.ts +2 -1
  44. package/dist/web/server.js +117 -12
  45. package/package.json +2 -2
@@ -36,10 +36,13 @@ export const MODES = [
36
36
  { key: "flags", label: "Feature Flags", spec: { title: "Feature Flags", summary: "Every feature flag the Slack app knows about, with its current effective value and whether it is locally overridden. Live-updates as flags change on the device. Filter by name.", source: "flags" } },
37
37
  ];
38
38
  // Dashboard mode key -> the ping `sources` name that must be present for the tab to work. Only
39
- // sources the device ships as plugins are gateable; the rest (network/rtm/clog/db/prefs/...)
40
- // always show, and each joins this map when its device-side migration lands. Lives here next to
41
- // MODES (the thing it keys off) so the two cannot drift apart in separate files.
39
+ // sources the device ships as plugins are gateable; the rest (network/db/prefs/...) always show,
40
+ // and each joins this map when its device-side migration lands. Note the mode key is singular
41
+ // while the plugin's source name is plural (clog -> "clogs", trace -> "traces"); the value must
42
+ // be the device's name or the tab hides forever. Lives here next to MODES (the thing it keys
43
+ // off) so the two cannot drift apart in separate files.
42
44
  export const MODE_SOURCE = {
45
+ clog: "clogs",
43
46
  trace: "traces",
44
47
  flags: "feature_flags",
45
48
  };
@@ -90,6 +93,9 @@ export function specMatchesMode(spec) {
90
93
  class Store {
91
94
  spec = { blank: true, viz: [] };
92
95
  conn = { state: "waiting", msg: "connecting…" };
96
+ // Last self-heal check's outcome, fetched once at boot (see fetchSelfHeal). null until that
97
+ // fetch resolves. Drives the header's passive "self-healed to a newer version" indicator.
98
+ selfHeal = null;
93
99
  // Set true once the kill button has shut the server down. The header swaps to a "dashboard
94
100
  // stopped" state, and the poll loops are torn down so a now-dead server does not spam the
95
101
  // console with failed fetches. Emitted as "stopped".
@@ -159,6 +165,10 @@ class Store {
159
165
  // first non-null serial just records it and does NOT clear (nothing stale to drop yet).
160
166
  _lastSerial = null;
161
167
  _rafPending = false;
168
+ // The pending rAF's id, so a clear can cancel a feed emit queued by a frame that arrived just
169
+ // before the clear. Left uncancelled, it fires after clearRecords() with the now-empty state
170
+ // and reads as a genuine new frame to a paused/frozen feed subscriber.
171
+ _rafHandle = null;
162
172
  _intervals = [];
163
173
  // Per-tab presence id, generated once when this Store is constructed. Rides pollProfile's 5s
164
174
  // /health fetch (below) so the server can tell how many tabs are live and auto-close when the
@@ -245,6 +255,7 @@ class Store {
245
255
  _resetForTest() {
246
256
  this.spec = { blank: true, viz: [] };
247
257
  this.conn = { state: "waiting", msg: "connecting…" };
258
+ this.selfHeal = null;
248
259
  this.stopped = false;
249
260
  this.profileLabel = "detecting…";
250
261
  this.serverVersion = "";
@@ -280,6 +291,7 @@ class Store {
280
291
  this._dropped = false;
281
292
  this._lastSerial = null;
282
293
  this._rafPending = false;
294
+ this._rafHandle = null;
283
295
  }
284
296
  // Build the graph aggregate structure for the current spec: one zero-filled series per
285
297
  // spec.series entry, or null when the spec has no graph. Shared by applySpec (fresh spec) and
@@ -290,16 +302,32 @@ class Store {
290
302
  }
291
303
  return { N: GRAPH_N, series: this.spec.series.map((s) => ({ def: s, buckets: new Array(GRAPH_N).fill(0), counts: new Array(GRAPH_N).fill(0) })) };
292
304
  }
293
- // Drop every device-scoped cache when the dashboard switches to different hardware. The old
294
- // device's records, dedup keys, learned field values, and detail bodies belong to the wrong
295
- // phone. The live aggregates (counter, rate, graph) reset too: backfill re-ACCUMULATES into
296
- // them rather than rebuilding them, so leaving them would layer the new device's counts on
297
- // top of the old device's totals. The graph is REBUILT zero-filled (not nulled): nothing else
298
- // reconstructs it after a switch, so nulling it would blank the Network/Trace charts until the
299
- // next tab change. Timers and spec are left running.
300
- clearDeviceCaches() {
301
- this.cache = [];
302
- this.cacheKeys = new Set();
305
+ // Wipe locally held records and the aggregates derived from them. Shared by the device switch
306
+ // (clearDeviceCaches) and the feed's clear button (clearView) so the two cannot drift: both mean
307
+ // "forget the records we are holding", and a field added to the store belongs here once rather
308
+ // than in two hand-maintained lists.
309
+ //
310
+ // scopeToSource: undefined wipes the entire shared cache (device switch -- every record belongs
311
+ // to the wrong phone). A source string keeps every OTHER source's cache entries: the raw cache
312
+ // is shared across every tab (applySpec deliberately leaves it intact on a tab switch), so a
313
+ // button scoped to "the view you are looking at" must only drop that source's entries, not the
314
+ // history other tabs are still holding.
315
+ //
316
+ // The live aggregates (counter, rate, graph) always reset in full regardless of scope: they
317
+ // already track only the CURRENT tab's matches (applySpec zeroes them on every tab switch), so
318
+ // there is nothing of another tab's to preserve here. Backfill re-ACCUMULATES into them rather
319
+ // than rebuilding them, so leaving them would layer new counts on top of totals whose records
320
+ // are gone. The graph is REBUILT zero-filled (not nulled): nothing else reconstructs it, so
321
+ // nulling it would blank the Network/Trace charts until the next tab change.
322
+ clearRecords(scopeToSource) {
323
+ if (scopeToSource !== undefined && scopeToSource !== "all") {
324
+ this.cache = this.cache.filter((c) => c.type !== scopeToSource);
325
+ this.cacheKeys = new Set(this.cache.map((c) => this.frameKey(c.type, c.ev)));
326
+ }
327
+ else {
328
+ this.cache = [];
329
+ this.cacheKeys = new Set();
330
+ }
303
331
  this.seen = {};
304
332
  this.detailCache = new Map();
305
333
  this._capSeen = new Set();
@@ -309,15 +337,65 @@ class Store {
309
337
  this.times = [];
310
338
  this.perSec = new Array(PERSEC_N).fill(0);
311
339
  this.graph = this.buildGraph();
340
+ // A frame that arrived just before this clear may have already queued a rAF-batched "feed"
341
+ // emit (bumpFeed). Left to fire, it lands after the records are gone and reads to a paused
342
+ // feed subscriber as a genuine new row -- cancel it, the clear's own synchronous emit below
343
+ // (or the device switch's next real frame) is what should drive the next render instead.
344
+ if (this._rafHandle != null) {
345
+ cancelAnimationFrame(this._rafHandle);
346
+ this._rafHandle = null;
347
+ this._rafPending = false;
348
+ }
349
+ }
350
+ // Drop every device-scoped cache when the dashboard switches to different hardware. The old
351
+ // device's records, dedup keys, learned field values, and detail bodies belong to the wrong
352
+ // phone. Timers and spec are left running.
353
+ clearDeviceCaches() {
354
+ this.clearRecords();
312
355
  // The old device's declared sources do not describe the new one; null until its next poll.
313
356
  this.updateSources(null);
314
357
  // Best-effort latency win: age the fresh-frame stamp so the next pollHealth really fetches.
315
358
  // Backfill frames can re-freshen it within ms; pollProfile's 5s read is the backstop.
316
359
  this._lastEventTs = 0;
317
360
  }
361
+ /**
362
+ * Empty the dashboard's own view: the records this tab is holding and the aggregates over them.
363
+ * Backs the feed's clear button.
364
+ *
365
+ * SCOPED to the active source: other tabs' already-buffered records survive (see clearRecords).
366
+ * The "all" tab has no other scope to preserve, so it still empties the whole shared cache.
367
+ *
368
+ * LOCAL ONLY, on purpose. The device keeps its ring buffers, so a reconnect or a source switch
369
+ * backfills up to 200 records straight back into an emptied feed. The alternative (GET
370
+ * /api/clear) is not scoped to the visible source either: the device's handleClear loops EVERY
371
+ * plugin, so clearing the Network feed would also wipe clogs, traces, RTM, and flags. A button
372
+ * that discards unrelated capture is the worse surprise, and the device buffers stay reachable
373
+ * via the clear_buffers MCP tool for anyone who does want them gone.
374
+ *
375
+ * Deliberately does NOT touch the stream, timers, spec, or device identity: this is a view
376
+ * reset, not a disconnect, so the next frame arrives normally.
377
+ *
378
+ * Emits "feed" synchronously rather than through bumpFeed's rAF batch. A clear is a direct
379
+ * response to a click and must land on THIS frame; the batch exists to coalesce stream floods.
380
+ * Note the feed's own "feed" handler is incremental (it diffs against store.cache.length, which
381
+ * does not necessarily shrink to 0 -- other tabs' entries can remain) -- the caller re-snapshots
382
+ * its view via viewFrames(), which filters by source and is what actually guarantees zero rows.
383
+ */
384
+ clearView() {
385
+ this.clearRecords(this.spec.source || "all");
386
+ this.feedVersion++;
387
+ this.emit("feed", this.feedVersion);
388
+ }
318
389
  // ---- start everything ----
319
- start() {
320
- this.bootDefault();
390
+ async start() {
391
+ // Awaited so the first pollSpec() below always runs AFTER bootDefault's own POST (when it
392
+ // fires one) has landed server-side. Firing both at once used to race: pollSpec's GET is a
393
+ // single fast round trip against bootDefault's slower GET-then-POST, so it almost always won
394
+ // and applied the still-blank spec bootDefault was in the middle of replacing, undoing the
395
+ // local default bootDefault had just set and stranding the page on the blank placeholder
396
+ // until the next 700ms tick happened to read the corrected value.
397
+ await this.bootDefault();
398
+ this.fetchSelfHeal();
321
399
  this.pollSpec();
322
400
  this._intervals.push(setInterval(() => this.pollSpec(), POLL_SPEC_MS));
323
401
  this.pollHealth();
@@ -385,6 +463,13 @@ class Store {
385
463
  try {
386
464
  const cur = await (await fetch("/spec")).json();
387
465
  if (!cur || cur.blank) {
466
+ // Apply the default locally right away, rather than waiting on the POST plus a
467
+ // future pollSpec tick to notice it landed. Without this, a fresh page load flashes
468
+ // "pick a dashboard above" with no tab highlighted for however long that round trip
469
+ // takes, even though the intent is always to land on Live. start() awaits this method
470
+ // before its own first pollSpec() runs, so that later read confirms the same spec
471
+ // rather than racing this one and overwriting it back to blank.
472
+ this.applySpec(MODES[0].spec);
388
473
  await fetch("/setspec", { method: "POST", headers: { "Content-Type": "application/json", "X-Radar-Dashboard": "1" }, body: JSON.stringify(MODES[0].spec) }).catch(() => { });
389
474
  }
390
475
  }
@@ -392,6 +477,18 @@ class Store {
392
477
  /* ignore */
393
478
  }
394
479
  }
480
+ // Fetch-once: the last self-heal check only changes once per app launch (the dock launcher
481
+ // runs it in the background on startup), so this is not folded into any polling loop.
482
+ async fetchSelfHeal() {
483
+ try {
484
+ const state = await (await fetch("/self-heal")).json();
485
+ this.selfHeal = state;
486
+ this.emit("self-heal", state);
487
+ }
488
+ catch {
489
+ /* leave selfHeal null; the header just renders nothing */
490
+ }
491
+ }
395
492
  markLocalPush(spec) {
396
493
  this._localPushKey = JSON.stringify(spec);
397
494
  }
@@ -652,8 +749,9 @@ class Store {
652
749
  if (this._rafPending)
653
750
  return;
654
751
  this._rafPending = true;
655
- requestAnimationFrame(() => {
752
+ this._rafHandle = requestAnimationFrame(() => {
656
753
  this._rafPending = false;
754
+ this._rafHandle = null;
657
755
  this.feedVersion++;
658
756
  this.emit("feed", this.feedVersion);
659
757
  });
@@ -0,0 +1,134 @@
1
+ // A small floating confirmation, shown for anything the user needs a moment to notice and then
2
+ // forget (a save, e.g.). Deliberately plain DOM, not a Preact component: the whole point is that
3
+ // it survives regardless of what any particular panel is doing, including a panel that unmounts
4
+ // itself right after triggering the action (the screen overlay returns null when closed, so a
5
+ // confirmation living inside it can never render at the one moment auto-save needs it most).
6
+ const finishListeners = new Set();
7
+ /**
8
+ * Called from the packaged dock app's native side (RadarApp.swift) once a WKDownload actually
9
+ * finishes, with the REAL on-disk path. The filename Radar guesses client-side before the
10
+ * download even starts is not necessarily final -- the app uniquifies a colliding name -- so
11
+ * "where did it save" can only be answered after the fact, from the native side that chose the
12
+ * destination. Never invoked in a plain browser tab: there is no bridge there, so this global is
13
+ * simply never called, and every listener below just never fires, which is correct -- a web page
14
+ * cannot reveal a file in Finder no matter what UI it draws.
15
+ *
16
+ * Uses globalThis, not the bare `window` identifier: this line runs at module load, and Node's
17
+ * test harness for this file installs a stand-in `window` by CALLING a setup function after
18
+ * imports resolve, not before -- referencing `window` directly here would throw before that
19
+ * setup ever runs. globalThis always exists in both Node and a real browser, and in a real
20
+ * browser globalThis IS window, so Swift's `window.__radarDownloadFinished(...)` call still
21
+ * finds this unchanged.
22
+ */
23
+ globalThis.__radarDownloadFinished = (path) => {
24
+ finishListeners.forEach((cb) => cb(path));
25
+ };
26
+ /** Subscribe to native download-finished notifications. Returns an unsubscribe function. */
27
+ export function onDownloadFinished(cb) {
28
+ finishListeners.add(cb);
29
+ return () => finishListeners.delete(cb);
30
+ }
31
+ export function revealInFinder(path) {
32
+ const w = globalThis;
33
+ w.webkit?.messageHandlers?.radarReveal?.postMessage(path);
34
+ }
35
+ /**
36
+ * Does `downloadedPath` hold the capture the server named as `expectedFile`?
37
+ *
38
+ * The two names are usually equal -- /screen/download sends the capture's own basename as its
39
+ * Content-Disposition filename, and that is what the native side receives as the suggested name.
40
+ * They differ when ~/Downloads already holds that name: decideDestinationUsing in RadarApp.swift
41
+ * uniquifies as "<stem>-N.<ext>" rather than overwriting. So exact equality alone would drop the
42
+ * reveal offer on exactly the re-download it was added for, and a bare "any path will do" accepts
43
+ * an earlier save's file. Accepting the name plus its uniquified forms is the narrow middle.
44
+ *
45
+ * Capture names are `radar_screen_<ISO timestamp>.<ext>` with a fixed-width timestamp, so no
46
+ * capture's stem can be another's stem followed by "-N": the suffix cannot collide with a real
47
+ * name.
48
+ */
49
+ export function isCaptureDownloadMatch(downloadedPath, expectedFile) {
50
+ const base = downloadedPath.split("/").pop() ?? "";
51
+ if (!base || !expectedFile)
52
+ return false;
53
+ if (base === expectedFile)
54
+ return true;
55
+ const dot = expectedFile.lastIndexOf(".");
56
+ if (dot <= 0)
57
+ return false;
58
+ const stem = expectedFile.slice(0, dot);
59
+ const ext = expectedFile.slice(dot);
60
+ if (!base.startsWith(stem) || !base.endsWith(ext))
61
+ return false;
62
+ const middle = base.slice(stem.length, base.length - ext.length);
63
+ return /^-\d+$/.test(middle);
64
+ }
65
+ let toastTimer = null;
66
+ // The capture the toast on screen is waiting on, or null when it is not waiting on one. Holding
67
+ // the FILE rather than a boolean is what lets the listener below tell "this save's download
68
+ // landed" from "some earlier save's download landed while this toast happens to be up".
69
+ let awaitedFile = null;
70
+ /**
71
+ * Show a confirmation with no file behind it: a failure, or any plain status line. Leaves the
72
+ * toast unclickable and shuts the reveal gate, so a late download-finished path from an earlier
73
+ * save cannot attach itself to this message.
74
+ */
75
+ export function showToast(message) {
76
+ paint(message);
77
+ awaitedFile = null;
78
+ }
79
+ /**
80
+ * Show a save confirmation and accept a reveal offer for `file` specifically -- the name the
81
+ * server reported for THIS save.
82
+ */
83
+ export function showSaveToast(message, file) {
84
+ paint(message);
85
+ awaitedFile = file;
86
+ }
87
+ function paint(message) {
88
+ let el = document.getElementById("radartoast");
89
+ if (!el) {
90
+ el = document.createElement("div");
91
+ el.id = "radartoast";
92
+ document.body.appendChild(el);
93
+ }
94
+ el.textContent = message;
95
+ // "clickable" is dropped along with the reveal wiring: this toast has no file yet, and the
96
+ // class is what lets it take clicks at all (the base rule is pointer-events:none so a toast
97
+ // never swallows a click meant for a row underneath it).
98
+ el.className = "on";
99
+ // Clear any reveal wiring from a PREVIOUS save so this toast cannot end up pointing at the
100
+ // wrong file if this save's own confirmation is still in flight.
101
+ el.onclick = null;
102
+ el.title = "";
103
+ if (toastTimer)
104
+ clearTimeout(toastTimer);
105
+ const target = el;
106
+ toastTimer = setTimeout(() => {
107
+ target.className = "";
108
+ // A toast that has faded is no longer waiting on anything, so a path arriving after it must
109
+ // not re-arm a toast a later message has since taken over.
110
+ awaitedFile = null;
111
+ }, 4000);
112
+ }
113
+ // Single persistent listener: the toast on screen becomes clickable once the download IT is
114
+ // waiting on actually finishes. Registered once at module load rather than per paint() call, since
115
+ // a toast's own lifetime (4s) can easily be shorter than the round trip to the native side and
116
+ // back for a real recording.
117
+ //
118
+ // Both guards are load-bearing. Without the awaitedFile check this wired reveal onto whichever
119
+ // toast merely had class "on", so a failure toast could offer to reveal an earlier capture; the
120
+ // base rule's pointer-events:none hid that until the clickable state made the handler reachable.
121
+ // Matching the path as well as checking for one keeps a slow first download from attaching itself
122
+ // to the second save's confirmation.
123
+ onDownloadFinished((path) => {
124
+ const el = document.getElementById("radartoast");
125
+ if (!el || !el.classList.contains("on"))
126
+ return;
127
+ if (!awaitedFile || !isCaptureDownloadMatch(path, awaitedFile))
128
+ return;
129
+ // Adding the class is what makes the handler reachable. Setting onclick alone did nothing:
130
+ // the base rule's pointer-events:none meant the element never received the click.
131
+ el.classList.add("clickable");
132
+ el.title = "Click to show in Finder";
133
+ el.onclick = () => revealInFinder(path);
134
+ });
@@ -1,4 +1,5 @@
1
1
  import http from "http";
2
+ import type { ProcessState } from "../shared/transport.js";
2
3
  import { type LogFrame } from "./log-session.js";
3
4
  import { stopRecording, getLive } from "../shared/screen.js";
4
5
  declare const WEB_PORT: number;
@@ -175,7 +176,7 @@ export declare function isOpenToAnyCaller(urlPath: string, method: string | unde
175
176
  * would just get a 403 with nothing to do about it.
176
177
  */
177
178
  export declare function isLocalHostHeader(host: string | string[] | undefined, allowedHosts?: string | undefined): boolean;
178
- export declare function enableResultBody(enabled: boolean, onEnabled?: () => void): {
179
+ export declare function enableResultBody(enabled: boolean, onEnabled?: () => void, processState?: ProcessState): {
179
180
  enabled: boolean;
180
181
  error?: string;
181
182
  };
@@ -8,14 +8,22 @@ import { AndroidTransport, resolveAdbPath } from "../shared/android.js";
8
8
  import { planReconnect } from "../shared/stream.js";
9
9
  import { RADAR_HOST, RADAR_PORT, RADAR_VERSION, WEB_PORT_DEFAULT } from "../shared/constants.js";
10
10
  import { friendlyFeatureFlagError } from "../shared/feature-flags.js";
11
+ import { deviceServerSilentError, readProcessState, } from "../shared/enable-diagnosis.js";
11
12
  import { cleanupPulledDatabases, initializeDatabasePath, listDatabases, pullDatabase, pulledSize, queryDatabase, resetDbState, availableUsers, } from "../shared/db.js";
12
13
  import { listPrefsFiles, readPrefsFile, parsePrefsXml, searchPrefs, } from "../shared/prefs.js";
13
14
  import { LogSession } from "./log-session.js";
14
15
  import { BLANK_SPEC, coerceSpec, validateSpec } from "./spec.js";
15
- import { screenCapabilities, refreshScreenCapabilities, grantScreenConsent, hasScreenConsent, detectDisplay, displayNote, captureScreenshot, startLive, addViewer, removeViewer, reapLiveIfIdle, primeIfNeeded, startRecording, stopRecording, getLive, recordingPath, resetScreenState, registerScreenCleanup, resolveFfmpeg, ffmpegInstallHint, SCREEN_BOUNDARY, } from "../shared/screen.js";
16
+ import { screenCapabilities, refreshScreenCapabilities, grantScreenConsent, hasScreenConsent, detectDisplay, displayNote, captureScreenshot, startLive, addViewer, removeViewer, reapLiveIfIdle, primeIfNeeded, startRecording, stopRecording, getLive, capturePath, saveScreenshot, screenshotSaveErrorMessage, resetScreenState, registerScreenCleanup, resolveFfmpeg, ffmpegInstallHint, SCREEN_BOUNDARY, } from "../shared/screen.js";
16
17
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
17
18
  const WEB_PORT = Number(process.env.SLACK_RADAR_WEB_PORT ?? WEB_PORT_DEFAULT);
18
19
  const INDEX_PATH = path.join(__dirname, "public", "index.html");
20
+ /**
21
+ * Ceiling for the diagnostic `ps` probe on the dashboard's failed-enable path. Deliberately
22
+ * shorter than the transport's default: /enable has already spent its own ping timeout
23
+ * proving the device server is unreachable, and this request blocks the dashboard's SSE
24
+ * tabs while it runs, so a fast "unknown" beats a slow confirmed answer here.
25
+ */
26
+ const DIAGNOSTIC_PS_TIMEOUT_MS = 1500;
19
27
  // Backpressure ceiling for an SSE connection's unwritten log frames. If a
20
28
  // client's socket buffer is already this deep (slow/backgrounded tab), new log
21
29
  // frames are dropped for that connection rather than queued without bound. ~4 MB
@@ -47,6 +55,12 @@ export function shouldDropLogFrame(replay, writableLength, cap = MAX_SSE_WRITABL
47
55
  // Each server start resets its own file to blank.
48
56
  const SPEC_DIR = path.join(os.homedir(), ".slack-radar");
49
57
  const SPEC_PATH = path.join(SPEC_DIR, `web-spec-${WEB_PORT}.json`);
58
+ // install-app.ts's runSelfHealCheck() writes this on every dock launch, regardless of port -- it
59
+ // is a per-machine install check, not per-dashboard-instance. A dedicated route rather than a
60
+ // field on /spec's body: /spec's JSON is a change-detection fingerprint the client diffs
61
+ // (JSON.stringify of the body) on every poll, and adding fields here would perturb that
62
+ // fingerprint every launch for a reason unrelated to the actual spec.
63
+ const SELF_HEAL_PATH = path.join(SPEC_DIR, "self-heal.json");
50
64
  const transport = new AndroidTransport();
51
65
  // Reassert the shared adb forward before every HTTP-based device read. Mirrors
52
66
  // mcp/index.ts's forwardForRead(): this process's own portForwarded cache cannot see a
@@ -95,6 +109,16 @@ function loadSpec() {
95
109
  return BLANK_SPEC;
96
110
  }
97
111
  }
112
+ // {} (never missing/malformed) is a normal "never checked yet" state, not an error: a fresh
113
+ // install with no self-heal.json yet must not read as a failure.
114
+ function loadSelfHeal() {
115
+ try {
116
+ return JSON.parse(fs.readFileSync(SELF_HEAL_PATH, "utf8"));
117
+ }
118
+ catch {
119
+ return {};
120
+ }
121
+ }
98
122
  // Start every run from a clean slate so a refresh/restart opens blank — UNLESS the
99
123
  // process was spawned with an initial spec (SLACK_RADAR_INITIAL_SPEC). The MCP
100
124
  // open_radar_dashboard handler sets that env on a cold spawn so the spec file is
@@ -408,6 +432,10 @@ export function createServer(onShutdown) {
408
432
  sendJson(res, 200, loadSpec());
409
433
  return;
410
434
  }
435
+ if (url === "/self-heal" && req.method === "GET") {
436
+ sendJson(res, 200, loadSelfHeal());
437
+ return;
438
+ }
411
439
  if (url === "/setspec" && req.method === "POST") {
412
440
  handleSetSpec(req, res, isAuthoredRequest(req.headers));
413
441
  return;
@@ -807,6 +835,7 @@ const READ_ONLY_EXACT = new Set([
807
835
  "/index.html",
808
836
  "/health",
809
837
  "/spec",
838
+ "/self-heal",
810
839
  "/stream", // EventSource cannot set headers, so this must stay open
811
840
  "/backfill",
812
841
  "/detail",
@@ -929,15 +958,15 @@ export function isLocalHostHeader(host, allowedHosts = process.env.SLACK_RADAR_A
929
958
  }
930
959
  return false;
931
960
  }
932
- export function enableResultBody(enabled, onEnabled) {
961
+ export function enableResultBody(enabled, onEnabled,
962
+ // Defaults to "unknown" so a caller that cannot probe keeps the generic message,
963
+ // which is also what every pre-existing two-argument call site gets.
964
+ processState = "unknown") {
933
965
  if (enabled) {
934
966
  onEnabled?.();
935
967
  return { enabled };
936
968
  }
937
- return {
938
- enabled,
939
- error: "Radar broadcast sent but the device server did not respond. Is a debug build with the slack-radar modules running on the active profile?",
940
- };
969
+ return { enabled, error: deviceServerSilentError(processState) };
941
970
  }
942
971
  /**
943
972
  * Re-arm Radar from the dashboard. Mirrors the recovery sequence: reset cached
@@ -1017,7 +1046,13 @@ function handleEnable(res, deviceSerial, authored) {
1017
1046
  if (replied)
1018
1047
  return;
1019
1048
  replied = true;
1020
- sendJson(res, 200, enableResultBody(enabled, keepAliveHookFor(authored)));
1049
+ // Probe only on the failure path: a successful enable needs no diagnosis, and the
1050
+ // probe is a real adb round trip. Capped short, because by this point the failure is
1051
+ // already established and the user is watching a request that has stalled their SSE
1052
+ // tabs; an explanation must not cost more than the operation it explains. The MCP path
1053
+ // keeps the patient default, where seconds of ping retries have already elapsed and a
1054
+ // real answer beats a fast "unknown".
1055
+ sendJson(res, 200, enableResultBody(enabled, keepAliveHookFor(authored), enabled ? "unknown" : readProcessState(transport, DIAGNOSTIC_PS_TIMEOUT_MS)));
1021
1056
  };
1022
1057
  const probe = http.request({
1023
1058
  host: RADAR_HOST,
@@ -1393,9 +1428,10 @@ async function handlePrefsSearch(req, res) {
1393
1428
  * /screen/caps capabilities (ffmpeg/scrcpy present, install hint, consent state)
1394
1429
  * /screen/consent POST: grant consent for this server process
1395
1430
  * /screen/shot full-resolution PNG screenshot (pure screencap; works without ffmpeg)
1431
+ * /screen/shot/save capture a screenshot to disk and report the outcome (two-phase)
1396
1432
  * /screen/stream multipart/x-mixed-replace MJPEG live cast (needs ffmpeg + consent)
1397
1433
  * /screen/record/start|stop record the live cast to mp4 (needs ffmpeg + consent)
1398
- * /screen/download download a finished recording
1434
+ * /screen/download download a finished recording or screenshot
1399
1435
  * /screen/redetect re-detect the active display
1400
1436
  */
1401
1437
  function handleScreen(req, res) {
@@ -1431,7 +1467,55 @@ function handleScreen(req, res) {
1431
1467
  sendJson(res, 200, { consent: true });
1432
1468
  return;
1433
1469
  }
1470
+ // Screenshot, two-phase: capture to disk and report the outcome as JSON, exactly like
1471
+ // /screen/record/stop. The dashboard uses this rather than GET /screen/shot because a
1472
+ // Content-Disposition response is invisible to the page that asked for it -- it cannot
1473
+ // tell a saved PNG from a 403 or a 502, so it used to say "screenshot saved" either way.
1474
+ // The client downloads the file it names in a second step, once it knows there is one.
1475
+ if (url === "/screen/shot/save" && req.method === "POST") {
1476
+ if (!hasScreenConsent()) {
1477
+ sendJson(res, 403, { ok: false, error: "screen consent required" });
1478
+ return;
1479
+ }
1480
+ void (async () => {
1481
+ // Same guard as the /screen/caps refresh branch above, and for the same reason: an escaping
1482
+ // rejection would leave this request hanging until the client times out, and a route whose
1483
+ // whole purpose is reporting the outcome must not have a silent way to report nothing.
1484
+ try {
1485
+ await detectDisplay();
1486
+ const shot = await saveScreenshot();
1487
+ if (!shot.ok) {
1488
+ // Name the half that failed. A write failure is a host problem (no space, a dir mode the
1489
+ // process cannot write); calling it a capture failure would send the user to check a
1490
+ // phone that answered perfectly well.
1491
+ sendJson(res, 502, { ok: false, error: screenshotSaveErrorMessage(shot) });
1492
+ return;
1493
+ }
1494
+ const p = shot.path;
1495
+ let sizeBytes = 0;
1496
+ try {
1497
+ sizeBytes = fs.statSync(p).size;
1498
+ }
1499
+ catch {
1500
+ sizeBytes = 0;
1501
+ }
1502
+ const file = path.basename(p);
1503
+ sendJson(res, 200, {
1504
+ ok: true,
1505
+ file,
1506
+ sizeBytes,
1507
+ download: "/screen/download?f=" + encodeURIComponent(file),
1508
+ });
1509
+ }
1510
+ catch (e) {
1511
+ sendJson(res, 502, { ok: false, error: "screenshot failed: " + e.message });
1512
+ }
1513
+ })();
1514
+ return;
1515
+ }
1434
1516
  // Screenshot: pure screencap, no ffmpeg. Still consent-gated — it is the live screen.
1517
+ // Kept as a direct PNG for anyone hitting the URL by hand; the dashboard uses the
1518
+ // two-phase route above so it can actually see whether the capture worked.
1435
1519
  if (url.startsWith("/screen/shot")) {
1436
1520
  if (!hasScreenConsent()) {
1437
1521
  sendJson(res, 403, { error: "screen consent required" });
@@ -1538,24 +1622,45 @@ function handleScreen(req, res) {
1538
1622
  return;
1539
1623
  }
1540
1624
  if (url.startsWith("/screen/download")) {
1541
- // A recording is device-screen content, so gate download on consent too — a fresh
1542
- // (unconsented) process must not serve a prior session's screen recording.
1625
+ // A capture is device-screen content, so gate download on consent too — a fresh
1626
+ // (unconsented) process must not serve a prior session's screen recording or screenshot.
1543
1627
  if (!hasScreenConsent()) {
1544
1628
  sendJson(res, 403, { error: "screen consent required" });
1545
1629
  return;
1546
1630
  }
1547
1631
  const f = new URL(url, `http://localhost:${WEB_PORT}`).searchParams.get("f") ?? "";
1548
- const p = recordingPath(f);
1632
+ const p = capturePath(f);
1549
1633
  if (!p) {
1550
1634
  res.writeHead(404);
1551
1635
  res.end("Not found");
1552
1636
  return;
1553
1637
  }
1554
1638
  res.writeHead(200, {
1555
- "Content-Type": "video/mp4",
1639
+ // capturePath admits exactly two extensions, so the type follows from the name. It used to
1640
+ // be a hardcoded video/mp4, which served a screenshot as an mp4 once this route started
1641
+ // carrying them.
1642
+ "Content-Type": p.endsWith(".png") ? "image/png" : "video/mp4",
1556
1643
  "Content-Disposition": `attachment; filename="${path.basename(p)}"`,
1557
1644
  });
1558
1645
  fs.createReadStream(p).pipe(res);
1646
+ // Drop the server-side copy once it has been handed over. A capture is a full frame of
1647
+ // whatever is on the phone, and the download is the point of making it, so keeping it after
1648
+ // delivery just leaves device-screen content sitting in the tmp dir for the rest of the
1649
+ // session -- cleanupRecordings only runs on re-enable and exit. The user's own copy is
1650
+ // untouched, and reveal in the packaged app points at that copy in ~/Downloads, not at this
1651
+ // one. Unlinking a file mid-read is safe, this stream keeps its descriptor.
1652
+ //
1653
+ // Hung off "close" rather than "finish" so an ABORTED transfer drops the file too. Nothing
1654
+ // retries a download, so keeping it after an abort just leaves a full frame of the device
1655
+ // screen in the tmp dir until re-enable or exit, which is the leftover this removes.
1656
+ res.on("close", () => {
1657
+ try {
1658
+ fs.unlinkSync(p);
1659
+ }
1660
+ catch {
1661
+ // Already gone, or a reset cleaned the dir first. Nothing to report either way.
1662
+ }
1663
+ });
1559
1664
  return;
1560
1665
  }
1561
1666
  if (url === "/screen/redetect") {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@slack/radar-mcp",
3
- "version": "1.14.0",
3
+ "version": "1.17.0",
4
4
  "description": "MCP server and web dashboard for on-device debugging of the Slack Android app via ADB",
5
5
  "type": "module",
6
6
  "main": "dist/mcp/index.js",
@@ -23,7 +23,7 @@
23
23
  "start:web": "node dist/web/bin.js",
24
24
  "watch": "tsc --watch",
25
25
  "test": "npm run build && node tests/run.mjs",
26
- "test:tap": "npm run build && node --test --test-force-exit tests/*.test.mjs",
26
+ "test:tap": "npm run build && node --test tests/*.test.mjs",
27
27
  "test:smoke": "npm run build && bash tests/smoke.sh",
28
28
  "test:all": "npm run test && npm run test:smoke",
29
29
  "prepare": "npm run build"