@slack/radar-mcp 1.18.1 → 1.20.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.
package/README.md CHANGED
@@ -44,17 +44,17 @@ slack-radar
44
44
 
45
45
  Opens `http://localhost:8100` automatically. Set `SLACK_RADAR_WEB_PORT` to use a different port. (`slack-radar-web` still works as a direct alias.) Tabs:
46
46
 
47
- * **Live** — network, RTM, analytics clogs, traces, and Slack-app logcat in one timeline
47
+ * **Live** — network, RTM, analytics clogs, traces, and Slack-app logcat in one timeline (**level ≥** applies to the logcat lines)
48
48
  * **Network** — calls per second vs response time, every call listed, slow ones flagged
49
49
  * **RTM** — real-time websocket events
50
50
  * **Clogs** — analytics events, click one to see its payload
51
51
  * **Traces** — performance trace spans with durations, click one for its timing and tags
52
- * **Logs** — device logcat, filtered to the Slack app (switch app or clear the filter)
52
+ * **Logs** — device logcat, filtered to the Slack app. **app** switches app or shows all apps; **level ≥** sets the lowest level to show (VERBOSE shows everything; the choice follows you between Logs and Live and waits while you visit another tab)
53
53
  * **Database** — read-only browser for the on-device SQLite stores (pick a database, then a table, or run a read-only query). See the data-handling note below.
54
54
  * **Preferences** — read-only browser for the on-device SharedPreferences files (pick a file, browse its keys, or search across every file at once).
55
55
  * **Custom** — a tab Claude builds on request. Ask a Claude Code session in your terminal for a view the pre-built tabs do not cover (e.g. "graph calls per second and flag the slow ones"); it authors the view via the `open_radar_dashboard` tool and it appears here. Persists until you refresh the page.
56
56
 
57
- Each tab has a rate, sparkline, graph, a filter / sort / pause / clear feed, and a payload inspector. **Clear** empties the dashboard's own view only, so the device keeps its buffers and a reconnect or a source switch backfills recent records again (ask a Claude Code session for `clear_buffers` to wipe the device too). The filter box takes space-separated terms that must all match, `-term` to exclude, `/pattern/` for regex, and `"quoted phrases"` for spaces or a literal `-` or `/`. Committed terms turn into removable pills; a leading `-` is now the exclude operator (the old box matched it as plain text), and quoting restores the literal. Regex flags are optional and short (i/m/s/g, 1-2 letters only, so an ambiguous tail like `/api/im` reads as flags, noted in the tooltip); typos like `/error/x` become part of the pattern and match literally, and quoting any `/…/` term matches it literally. Invalid regexes and incomplete typing (e.g. `/foo(`) are ignored (the term turns amber) instead of blanking the feed. On the Live tab a kind name (`log`, `clog`, `trace`, `rtm`, `network`) also matches rows of that type, and its `-kind` form excludes by row type only, so `-log` hides logcat lines without touching a `logout` clog (quote it, `-"log"`, to exclude by text instead). Switching tabs replays what you have already seen this session (the browser caches it, bounded by count and age) so the view does not reset to empty. ADB forwarding and device activation are handled for you; a reconnect control re-arms after a device sleep. The dashboard follows your system light/dark setting by default; the theme toggle in the header overrides it and is remembered.
57
+ Each tab has a rate, sparkline, graph, a filter / sort / pause / clear feed, and a payload inspector. **Clear** empties the dashboard's own view only, so the device keeps its buffers and a reconnect or a source switch backfills recent records again (ask a Claude Code session for `clear_buffers` to wipe the device too). The filter box takes space-separated terms that must all match, `-term` to exclude, `/pattern/` for regex, and `"quoted phrases"` for spaces or a literal `-` or `/` (curly quotes count too, and pasting text with spaces quotes it for you, unless you are mid-word or the text starts in filter syntax). The `?` at the right edge of the box opens a short legend under it. A phrase that itself contains a quote character goes in `/regex/` form instead, where quotes are plain text. Committed terms turn into removable pills; a leading `-` is now the exclude operator (the old box matched it as plain text), and quoting restores the literal. Regex flags are optional and short (i/m/s/g, 1-2 letters only, so an ambiguous tail like `/api/im` reads as flags, noted in the tooltip); typos like `/error/x` become part of the pattern and match literally, and quoting any `/…/` term matches it literally. Invalid regexes and incomplete typing (e.g. `/foo(`) are ignored (the term turns amber) instead of blanking the feed. On the Live tab a kind name (`log`, `clog`, `trace`, `rtm`, `network`) also matches rows of that type, and its `-kind` form excludes by row type only, so `-log` hides logcat lines without touching a `logout` clog (quote it, `-"log"`, to exclude by text instead). Switching tabs replays what you have already seen this session (the browser caches it, bounded by count and age) so the view does not reset to empty. ADB forwarding and device activation are handled for you; a reconnect control re-arms after a device sleep. The device-side session shuts down after its idle timeout, and an open dashboard tab now recovers that on its own: the header says there is no radar session on the device and re-enables it, once right away (or on the minute, if the session just came back and died again) and then at most once a minute, giving up after three failed attempts (a session that dies again within a minute of coming back counts as a failed attempt), or at once if the attached device changed, so the next press is yours. Only a tab you are looking at does this (a background tab never arms a device you let idle out), never a dashboard an agent opened, and **✋ stop auto re-enable** in the header turns it off for dashboards at this address if you would rather do it by hand (`SLACK_RADAR_NO_ARM=1` on the process turns it off for that process, along with the arm at launch). The dashboard follows your system light/dark setting by default; the theme toggle in the header overrides it and is remembered.
58
58
 
59
59
  ### Install it to your dock (macOS)
60
60
 
@@ -66,7 +66,13 @@ npx @slack/radar-mcp install-app
66
66
 
67
67
  That writes `~/Applications/Slack Radar.app`. Open it once, then right-click its dock icon and choose **Options > Keep in Dock**.
68
68
 
69
- Clicking it starts the dashboard if it is not already running (the server auto-closes 5 minutes after the last tab closes, so this is the usual case), waits for the port, then shows it. If Xcode's command line tools are installed (`xcode-select --install`), `install-app` compiles a small native window for this — its own dock icon, its own process, no browser tab, no tab bar. Without a Swift toolchain it falls back to opening your default browser instead.
69
+ Clicking it starts the dashboard if it is not already running (the server auto-closes 5 minutes after the last tab closes, so this is the usual case), waits for the port, then shows it. If an older dashboard is still holding the port and nobody is using it, the app asks that one to stop first, so an upgrade does not leave you looking at the version you replaced. Quitting the app stops the dashboard it started, unless a Claude Code session or another window is still using it; a dashboard that was already running when the app launched is never stopped. If Xcode's command line tools are installed (`xcode-select --install`), `install-app` compiles a small native window for this — its own dock icon, its own process, no browser tab, no tab bar. Without a Swift toolchain it falls back to opening your default browser instead.
70
+
71
+ If the window cannot start the dashboard after a node upgrade, the app is holding a node path that the upgrade moved. Run this, then quit and reopen the app:
72
+
73
+ ```bash
74
+ npx -y @slack/radar-mcp@latest install-app
75
+ ```
70
76
 
71
77
  ### Screen overlay
72
78
 
@@ -92,6 +98,7 @@ All optional. Set them on the process that runs the MCP server or the dashboard.
92
98
  | `SLACK_RADAR_DEVICE_PORT` | Host port forwarded to the device-side server. Default `8099`. |
93
99
  | `SLACK_RADAR_NO_AUTO_CLOSE=1` | Keep the dashboard running forever instead of closing it once every tab is gone. |
94
100
  | `SLACK_RADAR_ALLOWED_HOSTS` | Extra `Host` values the dashboard will answer, comma-separated (`radar.local,myhost:8100`). Only needed when you reach it by a name other than localhost. See Security. |
101
+ | `SLACK_RADAR_NO_ARM=1` | Never arm the device without a press: skips the arm at launch and turns off a tab's automatic re-enable. A Reconnect press still arms. |
95
102
  | `SLACK_RADAR_NO_OPEN=1` | Do not open a browser window on launch. Set automatically when an MCP tool spawns the dashboard. |
96
103
  | `SLACK_RADAR_NO_FFMPEG=1` | Pretend ffmpeg is absent, so screen recording degrades to screenshots. |
97
104
  | `SLACK_RADAR_PLATFORM` | Transport to use: `android` (the default) or `ios`. Radar does not probe or infer a different platform. |
@@ -164,6 +171,8 @@ Mobile debug build (device)
164
171
 
165
172
  All device-specific logic lives behind the `DeviceTransport` interface (`src/shared/transport.ts`). Buffers, SSE streaming, session management, and the HTTP wire protocol are platform-agnostic: the wire format is plain `GET /api/<resource>` with JSON, and adb appears only in the transport.
166
173
 
174
+ **Consuming the wire from your own tooling**: the dashboard's HTTP+SSE surface is documented as a read contract in [docs/wire-contract.md](docs/wire-contract.md) (Oracle Surface v1) — named routes, SSE frame grammar, backfill/dedupe recipe, the auto-close trap, and an executable preflight (`scripts/preflight.mjs`, which lives in this repo rather than the published package, and is meant to be copied into your own harness).
175
+
167
176
  **Adding a new platform**: implement `DeviceTransport` in `src/shared/<platform>.ts` and add a case to `createTransport()` in `src/mcp/index.ts`. The device-shaped operations (screenshot, screen recording, app state, device logs) are optional members, so implement what the platform supports and leave the rest absent; callers report each absent capability as "not supported on platform X". Two things stay Android-only for now and are guarded rather than abstracted: the dashboard (its flow assumes a device to arm) and adb port forwarding.
168
177
 
169
178
  ## Security
@@ -256,3 +265,30 @@ Restart your Claude Code session. MCP servers are registered at session start.
256
265
 
257
266
  **Port already in use (web dashboard)**
258
267
  If a Radar dashboard is already running on the port, launching again just opens it. If the port is held by another program, run Radar on a different port with `SLACK_RADAR_WEB_PORT=8101 npx @slack/radar-mcp web`.
268
+
269
+ **The dashboard shows the version you just replaced**
270
+ That badge reports the version of the process serving the port, not the app or package you installed. Installing does not touch a server that is already running, so an older dashboard can keep serving after an upgrade.
271
+
272
+ The app also leaves an older dashboard alone on purpose when somebody else is using it, either a Claude Code session or another window with it open. A refresh (⌘R in the app window, or Retry on its failure page) tries to take it from a window, and never from a session; taking it costs that window its page, and everyone the server's pulled databases, device pin and logcat ring. `~/Library/Logs/slack-radar-dashboard.log` names which one it found, and what a refresh will do about it.
273
+
274
+ Ask the two surfaces separately. The installed dock app:
275
+
276
+ ```bash
277
+ defaults read ~/Applications/Slack\ Radar.app/Contents/Info.plist CFBundleShortVersionString
278
+ ```
279
+
280
+ And whatever is actually serving, with the dashboard open. A GET with the headers printed, not `curl -sI`: a HEAD only answers on the release that carries this change and later, and the dashboard you are diagnosing is an older one by definition.
281
+
282
+ ```bash
283
+ curl -s -D - -o /dev/null http://127.0.0.1:8100/spec | grep -i x-radar-version
284
+ ```
285
+
286
+ Use your own port if you set `SLACK_RADAR_WEB_PORT`. Against the wrong port both commands print nothing, which looks the same as a dashboard that is not there.
287
+
288
+ Two different versions is the answer. Stop the old dashboard, then quit the app and open it again:
289
+
290
+ ```bash
291
+ curl -s -X POST -H 'X-Radar-Dashboard: 1' http://127.0.0.1:8100/shutdown
292
+ ```
293
+
294
+ If it comes back older, the dashboard is being started by your Claude Code session, so restart that to reload its MCP server. Where npm enforces a minimum release age, `@latest` will not resolve to a release for its first week; pin the version in your MCP registration to get it sooner.
package/dist/mcp/index.js CHANGED
@@ -810,7 +810,7 @@ async function runMcpServer() {
810
810
  }
811
811
  }
812
812
  // --- MCP Server ---
813
- const server = new Server({ name: "slack-radar", version: "1.18.1" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
813
+ const server = new Server({ name: "slack-radar", version: "1.20.0" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
814
814
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
815
815
  tools: TOOL_DEFINITIONS,
816
816
  }));
package/dist/mcp/tools.js CHANGED
@@ -1,4 +1,4 @@
1
- import { SOURCES, VIZ, SERIES_METRICS } from "../web/spec.js";
1
+ import { SOURCES, VIZ, SERIES_METRICS, LOG_LEVELS } from "../web/spec.js";
2
2
  export const SERVER_INSTRUCTIONS = [
3
3
  "Slack Radar provides on-device debugging tools for the Slack Android app via ADB.",
4
4
  "",
@@ -449,12 +449,17 @@ export const TOOL_DEFINITIONS = [
449
449
  type: "object",
450
450
  description: "Case-insensitive substring filter on SUMMARY fields, keyed by source. network: url/method/status_code; " +
451
451
  "rtm: event_type/direction/channel; clog: event_name; trace: trace_name/span_name; log: tag/level/package. NEVER invent a field " +
452
- "(a match on an absent field silently matches nothing). For body text use bodyContains instead.",
452
+ "(a match on an absent field silently matches nothing). For body text use bodyContains instead; for a log level floor use minLevel, not match.level.",
453
453
  },
454
454
  bodyContains: {
455
455
  type: "string",
456
456
  description: "network/all only: keep calls whose request/response BODY contains this substring (fetches each call's detail).",
457
457
  },
458
+ minLevel: {
459
+ type: "string",
460
+ enum: [...LOG_LEVELS],
461
+ description: "log/all only: show log lines at this level or above (WARN keeps WARN, ERROR and FATAL). Rows of other kinds are unaffected. Omit to show every line; VERBOSE means the same and is stored as omitted.",
462
+ },
458
463
  viz: {
459
464
  type: "array",
460
465
  items: { type: "string", enum: [...VIZ] },
@@ -12,13 +12,16 @@ export function webChildEnv(initialSpec) {
12
12
  // A bridge-spawned dashboard must not pop a window unbidden: the Claude Code session returns the
13
13
  // URL instead, which is what the /radar-ui server instructions promise.
14
14
  SLACK_RADAR_NO_OPEN: "1",
15
- // Suppress the dashboard's boot-arm. open_radar_dashboard is deliberately EXEMPT from the MCP
16
- // session gate, and the stated reason for that exemption is that opening the dashboard cannot by
17
- // itself reach the device, because arming needs a human to press its Reconnect button. Boot arming
18
- // would silently invalidate that reasoning: an agent call would arm a real device and start logcat
19
- // capture to disk with no human in the loop and, since this child is detached with stdio ignored,
20
- // no visible output either. A HUMAN launch, a terminal `slack-radar web` or the dock app, does not
21
- // set this and does arm.
15
+ // Suppress every path by which this dashboard could arm the device on its own: the boot-arm
16
+ // (armOnBoot returns on this flag) AND the automatic re-enable of a diagnosed-dead session
17
+ // (the dashboard reads the flag back off /health's self_arm_blocked and refuses, and the
18
+ // server refuses an unattended /enable?auto=1 itself).
19
+ // open_radar_dashboard is deliberately EXEMPT from the MCP session gate, and the stated reason
20
+ // for that exemption is that opening the dashboard cannot by itself reach the device. Either
21
+ // path would silently invalidate that reasoning: an agent call would arm a real device and start
22
+ // logcat capture to disk with no human in the loop and, since this child is detached with stdio
23
+ // ignored, no visible output either. A HUMAN launch, a terminal `slack-radar web` or the dock
24
+ // app, does not set this: it arms at boot and may recover a dead session unattended.
22
25
  SLACK_RADAR_AGENT_LAUNCH: "1",
23
26
  // Passed explicitly rather than inherited. RADAR_PORT is a mutable binding, so a setRadarPort()
24
27
  // call in this process is invisible to a child that re-evaluates the same expression from env: it
@@ -1,4 +1,4 @@
1
- import type { DeviceInfo, DeviceTransport, LogResult, ProcessState } from "./transport.js";
1
+ import type { DeviceInfo, DeviceTransport, LogResult, ProcessState, DevicePick } from "./transport.js";
2
2
  /**
3
3
  * Resolve the adb binary. MCP servers spawned from GUI launchers (Spotlight,
4
4
  * Raycast, Dock) do not inherit the user's shell PATH, so a bare `adb` call
@@ -103,31 +103,20 @@ export declare class AndroidTransport implements DeviceTransport {
103
103
  listDevices(): DeviceInfo[] | null;
104
104
  listDevicesAsync(): Promise<DeviceInfo[] | null>;
105
105
  private reconcileSelectedDevice;
106
- selectDevice(serial: string | null): {
107
- ok: true;
108
- serial: string | null;
109
- switched?: boolean;
110
- devices: DeviceInfo[];
111
- } | {
112
- ok: false;
113
- error: string;
114
- devices: DeviceInfo[];
115
- };
106
+ selectDevice(serial: string | null): DevicePick;
107
+ /**
108
+ * The pick selectDevice WOULD make, with nothing recorded: the listing still runs (and still
109
+ * reconciles a pinned device that vanished, as every listing does), but no pin is set, no
110
+ * stale env pin is dropped, and no selection is cleared. Same code as the real pick, so the
111
+ * two cannot disagree about which device wins.
112
+ */
113
+ resolveDevice(serial: string | null): DevicePick;
116
114
  /**
117
115
  * selectDevice, off the event loop. The listing runs through execFileAsync; the pick
118
116
  * itself is the exact code the sync twin runs (pickFromListing), so the two cannot
119
117
  * disagree about which device wins.
120
118
  */
121
- selectDeviceAsync(serial: string | null): Promise<{
122
- ok: true;
123
- serial: string | null;
124
- switched?: boolean;
125
- devices: DeviceInfo[];
126
- } | {
127
- ok: false;
128
- error: string;
129
- devices: DeviceInfo[];
130
- }>;
119
+ selectDeviceAsync(serial: string | null): Promise<DevicePick>;
131
120
  private pickFromListing;
132
121
  getSelectedDevice(): {
133
122
  serial: string;
@@ -631,7 +631,16 @@ export class AndroidTransport {
631
631
  this.selectedDevice = null;
632
632
  }
633
633
  selectDevice(serial) {
634
- return this.pickFromListing(this.listDevices(), serial);
634
+ return this.pickFromListing(this.listDevices(), serial, true);
635
+ }
636
+ /**
637
+ * The pick selectDevice WOULD make, with nothing recorded: the listing still runs (and still
638
+ * reconciles a pinned device that vanished, as every listing does), but no pin is set, no
639
+ * stale env pin is dropped, and no selection is cleared. Same code as the real pick, so the
640
+ * two cannot disagree about which device wins.
641
+ */
642
+ resolveDevice(serial) {
643
+ return this.pickFromListing(this.listDevices(), serial, false);
635
644
  }
636
645
  /**
637
646
  * selectDevice, off the event loop. The listing runs through execFileAsync; the pick
@@ -639,14 +648,18 @@ export class AndroidTransport {
639
648
  * disagree about which device wins.
640
649
  */
641
650
  async selectDeviceAsync(serial) {
642
- return this.pickFromListing(await this.listDevicesAsync(), serial);
651
+ return this.pickFromListing(await this.listDevicesAsync(), serial, true);
643
652
  }
644
653
  // Everything selectDevice decides once a listing (or its failure, null) is in hand.
645
- pickFromListing(devices, serial) {
654
+ pickFromListing(devices, serial,
655
+ // false = report the pick without making it (resolveDevice): every `this.pin` and every
656
+ // clearing of a stale selection or env pin below is skipped.
657
+ commit) {
646
658
  if (devices === null) {
647
659
  return {
648
660
  ok: false,
649
661
  error: "Could not list devices (adb devices failed). Check adb and retry.",
662
+ instructs: true,
650
663
  devices: [],
651
664
  };
652
665
  }
@@ -664,13 +677,15 @@ export class AndroidTransport {
664
677
  if (serial) {
665
678
  const match = attached.find((d) => d.serial === serial);
666
679
  if (match) {
667
- this.pin(match.serial, match.label);
680
+ if (commit)
681
+ this.pin(match.serial, match.label);
668
682
  return { ok: true, serial: match.serial, switched: switchedTo(match.serial), devices };
669
683
  }
670
684
  const list = attached.length > 0 ? listAttached() : "none";
671
685
  return {
672
686
  ok: false,
673
687
  error: `Device ${serial} is not attached (or not authorized). Attached: ${list}`,
688
+ instructs: false,
674
689
  devices,
675
690
  };
676
691
  }
@@ -680,17 +695,21 @@ export class AndroidTransport {
680
695
  if (pinned) {
681
696
  const stillAttached = attached.find((d) => d.serial === pinned);
682
697
  if (stillAttached) {
683
- this.pin(stillAttached.serial, stillAttached.label);
698
+ if (commit)
699
+ this.pin(stillAttached.serial, stillAttached.label);
684
700
  return { ok: true, serial: stillAttached.serial, switched: switchedTo(stillAttached.serial), devices };
685
701
  }
686
702
  // The pinned device detached. Drop the stale env pin AND the recorded selection so
687
703
  // /health does not keep claiming a device that is gone.
688
- delete process.env.ANDROID_SERIAL;
689
- this.selectedDevice = null;
704
+ if (commit) {
705
+ delete process.env.ANDROID_SERIAL;
706
+ this.selectedDevice = null;
707
+ }
690
708
  }
691
709
  // (c) Exactly one attached device: auto-pin it.
692
710
  if (attached.length === 1) {
693
- this.pin(attached[0].serial, attached[0].label);
711
+ if (commit)
712
+ this.pin(attached[0].serial, attached[0].label);
694
713
  return { ok: true, serial: attached[0].serial, switched: switchedTo(attached[0].serial), devices };
695
714
  }
696
715
  // (d) Zero devices (or a fake adb that does not answer `devices -l`): no-op. The
@@ -698,7 +717,8 @@ export class AndroidTransport {
698
717
  // ok/null keeps every flow that fakes adb without a listing green.
699
718
  if (attached.length === 0) {
700
719
  // Nothing attached: clear any recorded selection so /health reports no device.
701
- this.selectedDevice = null;
720
+ if (commit)
721
+ this.selectedDevice = null;
702
722
  return { ok: true, serial: null, devices };
703
723
  }
704
724
  // (e) 2+ attached devices with no explicit choice: ambiguous. The transport error stays a
@@ -706,6 +726,7 @@ export class AndroidTransport {
706
726
  return {
707
727
  ok: false,
708
728
  error: `Multiple devices attached; specify which one. Attached: ${listAttached()}.`,
729
+ instructs: true,
709
730
  devices,
710
731
  };
711
732
  }
@@ -1,8 +1,9 @@
1
1
  /**
2
2
  * Package version, read once from package.json at load — NOT a hardcoded copy, so it cannot
3
- * drift from the published version. Surfaced as the `X-Radar-Version` header on /spec so a
4
- * second launcher can tell whether the dashboard already holding the port is a different
5
- * Radar version than itself (the adopt path notices a mismatch; it still adopts, never kills).
3
+ * drift from the published version. Surfaced as the `X-Radar-Version` header on every dashboard
4
+ * response past the Host gate (docs/wire-contract.md §7) so a second launcher can tell whether the dashboard
5
+ * already holding the port is a different Radar version than itself (the adopt path notices a
6
+ * mismatch; it still adopts, never kills), and a machine consumer can detect version skew.
6
7
  * Falls back to "unknown" if package.json cannot be read (should not happen in a real install).
7
8
  */
8
9
  export declare const RADAR_VERSION: string;
@@ -1,9 +1,10 @@
1
1
  import { createRequire } from "module";
2
2
  /**
3
3
  * Package version, read once from package.json at load — NOT a hardcoded copy, so it cannot
4
- * drift from the published version. Surfaced as the `X-Radar-Version` header on /spec so a
5
- * second launcher can tell whether the dashboard already holding the port is a different
6
- * Radar version than itself (the adopt path notices a mismatch; it still adopts, never kills).
4
+ * drift from the published version. Surfaced as the `X-Radar-Version` header on every dashboard
5
+ * response past the Host gate (docs/wire-contract.md §7) so a second launcher can tell whether the dashboard
6
+ * already holding the port is a different Radar version than itself (the adopt path notices a
7
+ * mismatch; it still adopts, never kills), and a machine consumer can detect version skew.
7
8
  * Falls back to "unknown" if package.json cannot be read (should not happen in a real install).
8
9
  */
9
10
  export const RADAR_VERSION = (() => {
@@ -1,4 +1,4 @@
1
- import type { DeviceInfo, DeviceTransport } from "./transport.js";
1
+ import type { DeviceInfo, DevicePick, DeviceTransport } from "./transport.js";
2
2
  export type IosScreenshotCapturer = (simulatorUdid: string, outputPath: string) => void;
3
3
  export type IosScreenRecorder = (simulatorUdid: string, outputPath: string, durationSeconds: number) => void;
4
4
  export interface IosSimulatorTransportDependencies {
@@ -41,15 +41,10 @@ export declare class IosSimulatorTransport implements DeviceTransport {
41
41
  private readonly recordSimulatorScreen;
42
42
  constructor(dependencies?: IosSimulatorTransportDependencies);
43
43
  listDevices(): DeviceInfo[] | null;
44
- selectDevice(serial: string | null): {
45
- ok: true;
46
- serial: string | null;
47
- switched?: boolean;
48
- } | {
49
- ok: false;
50
- error: string;
51
- devices: DeviceInfo[];
52
- };
44
+ selectDevice(serial: string | null): DevicePick;
45
+ /** selectDevice's answer without the pin (see DeviceTransport.resolveDevice). */
46
+ resolveDevice(serial: string | null): DevicePick;
47
+ private pick;
53
48
  getSelectedDevice(): {
54
49
  serial: string;
55
50
  label: string;
@@ -125,20 +125,33 @@ export class IosSimulatorTransport {
125
125
  }
126
126
  }
127
127
  selectDevice(serial) {
128
+ return this.pick(serial, true);
129
+ }
130
+ /** selectDevice's answer without the pin (see DeviceTransport.resolveDevice). */
131
+ resolveDevice(serial) {
132
+ return this.pick(serial, false);
133
+ }
134
+ pick(serial,
135
+ // false = report the choice without recording it: no selection set or cleared, no forward
136
+ // invalidated.
137
+ commit) {
128
138
  const devices = this.listDevices();
129
139
  if (devices === null) {
130
140
  return {
131
141
  ok: false,
132
142
  error: "Could not list iOS simulators (xcrun simctl failed). Check Xcode and retry.",
143
+ instructs: true,
133
144
  devices: [],
134
145
  };
135
146
  }
136
147
  const prior = this.selectedDevice?.serial ?? null;
137
148
  const pin = (device) => {
138
- if (this.selectedDevice && this.selectedDevice.serial !== device.serial) {
139
- this.forwarded = false;
149
+ if (commit) {
150
+ if (this.selectedDevice && this.selectedDevice.serial !== device.serial) {
151
+ this.forwarded = false;
152
+ }
153
+ this.selectedDevice = { serial: device.serial, label: device.label };
140
154
  }
141
- this.selectedDevice = { serial: device.serial, label: device.label };
142
155
  return {
143
156
  ok: true,
144
157
  serial: device.serial,
@@ -152,6 +165,7 @@ export class IosSimulatorTransport {
152
165
  return {
153
166
  ok: false,
154
167
  error: `iOS Simulator ${serial} is not booted. Booted: ${this.describeDevices(devices)}`,
168
+ instructs: false,
155
169
  devices,
156
170
  };
157
171
  }
@@ -164,6 +178,7 @@ export class IosSimulatorTransport {
164
178
  return {
165
179
  ok: false,
166
180
  error: `SLACK_RADAR_IOS_SIMULATOR_UDID=${envUdid} is not booted. Booted: ${this.describeDevices(devices)}`,
181
+ instructs: false,
167
182
  devices,
168
183
  };
169
184
  }
@@ -172,17 +187,20 @@ export class IosSimulatorTransport {
172
187
  const match = devices.find((device) => device.serial === this.selectedDevice.serial);
173
188
  if (match)
174
189
  return pin(match);
175
- this.clearSelectedDevice();
190
+ if (commit)
191
+ this.clearSelectedDevice();
176
192
  }
177
193
  if (devices.length === 1)
178
194
  return pin(devices[0]);
179
195
  if (devices.length === 0) {
180
- this.clearSelectedDevice();
196
+ if (commit)
197
+ this.clearSelectedDevice();
181
198
  return { ok: true, serial: null };
182
199
  }
183
200
  return {
184
201
  ok: false,
185
202
  error: `Multiple iOS simulators are booted; specify which one. Booted: ${this.describeDevices(devices)}.`,
203
+ instructs: true,
186
204
  devices,
187
205
  };
188
206
  }
@@ -38,6 +38,25 @@ export interface DeviceInfo {
38
38
  /** Platform discriminator for mixed or platform-specific device UIs. */
39
39
  platform?: string;
40
40
  }
41
+ /**
42
+ * The outcome of choosing a device (selectDevice / resolveDevice). On success `serial` is null
43
+ * when nothing is attached (the caller's forward path reports no-device on its own); `switched`
44
+ * is true when the pick differs from the session's prior device; `devices` is the listing the
45
+ * pick was made from where the transport has one. On failure `error` is human-readable and
46
+ * `instructs` says whether that wording tells the user what to do next (set here, where the
47
+ * wording is written, so no client has to guess it from the prose).
48
+ */
49
+ export type DevicePick = {
50
+ ok: true;
51
+ serial: string | null;
52
+ switched?: boolean;
53
+ devices?: DeviceInfo[];
54
+ } | {
55
+ ok: false;
56
+ error: string;
57
+ instructs: boolean;
58
+ devices: DeviceInfo[];
59
+ };
41
60
  export interface DeviceTransport {
42
61
  /**
43
62
  * Human-readable platform name (e.g. "android", "ios").
@@ -251,15 +270,17 @@ export interface DeviceTransport {
251
270
  * session's prior device: a switch invalidates device-scoped session state, and the
252
271
  * orchestrator owns the reset.
253
272
  */
254
- selectDevice?(serial: string | null): {
255
- ok: true;
256
- serial: string | null;
257
- switched?: boolean;
258
- } | {
259
- ok: false;
260
- error: string;
261
- devices: DeviceInfo[];
262
- };
273
+ selectDevice?(serial: string | null): DevicePick;
274
+ /**
275
+ * selectDevice's answer WITHOUT the pin: the same choice and the same errors, from the same
276
+ * code, so the two cannot disagree about which device wins. Records no new selection, drops no
277
+ * env pin, invalidates no forward. The listing itself still runs, and a pin whose device has
278
+ * vanished is reconciled away exactly as any listing reconciles it, so getSelectedDevice() can
279
+ * go from a serial to null across this call; it can never go to a NEW serial. For a caller that
280
+ * must decide whether to proceed at all before it touches anything, such as an unattended
281
+ * re-arm that refuses to adopt different hardware. Required wherever selectDevice is.
282
+ */
283
+ resolveDevice?(serial: string | null): DevicePick;
263
284
  /**
264
285
  * The device pinned by the last successful selectDevice, or null when none is pinned.
265
286
  * The enable body and the web /health response surface this so a user can see which
@@ -273,16 +294,7 @@ export interface DeviceTransport {
273
294
  * Async variant of selectDevice for non-blocking boot/enable flows. Optional; platforms
274
295
  * without an async device-listing path may omit it (the dashboard guards on presence).
275
296
  */
276
- selectDeviceAsync?(serial: string | null): Promise<{
277
- ok: true;
278
- serial: string | null;
279
- switched?: boolean;
280
- devices: DeviceInfo[];
281
- } | {
282
- ok: false;
283
- error: string;
284
- devices: DeviceInfo[];
285
- }>;
297
+ selectDeviceAsync?(serial: string | null): Promise<DevicePick>;
286
298
  /**
287
299
  * Async variant of reassertForward for non-blocking boot/enable flows. Optional.
288
300
  */
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Wire vocabulary shared by the dashboard server and its browser client. Types only, no runtime
3
+ * code and no imports, so both tsconfigs can `import type` it and the browser bundle is unchanged.
4
+ * docs/wire-contract.md is the prose half; this file is the machine-readable one.
5
+ */
6
+ /**
7
+ * A refusal marker on a failed /enable reply: the route will answer every later UNATTENDED
8
+ * attempt the same way, so the client's automation stops and hands the next press to the user.
9
+ * - self_arm_blocked: this process may not arm the device on its own (agent-spawned, or
10
+ * SLACK_RADAR_NO_ARM).
11
+ * - device_changed: the attached hardware differs from what this process last armed; adopting
12
+ * it is a human decision.
13
+ */
14
+ export type EnableRefusal = "self_arm_blocked" | "device_changed";
15
+ /**
16
+ * The stream proxy's CURRENT diagnosis of an outage, stamped on `_status` frames. Not a log of
17
+ * what was diagnosed: a later frame's reason replaces an earlier one.
18
+ * - no_session: the device-side radar session has ended (socket absent); only a re-enable fixes
19
+ * this, so a client may act on it.
20
+ * - undiagnosed: an earlier diagnosis no longer holds (a later probe did not find the session
21
+ * absent). It is not a diagnosis and carries no cause; a client drops whatever it latched
22
+ * from the earlier reason. A frame with NO reason says nothing about the diagnosis.
23
+ */
24
+ export type StatusReason = "no_session" | "undiagnosed";
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Wire vocabulary shared by the dashboard server and its browser client. Types only, no runtime
3
+ * code and no imports, so both tsconfigs can `import type` it and the browser bundle is unchanged.
4
+ * docs/wire-contract.md is the prose half; this file is the machine-readable one.
5
+ */
6
+ export {};
@@ -1,9 +1,45 @@
1
1
  import { spawn } from "child_process";
2
+ /**
3
+ * Where a stable, version-free name for a node interpreter could live. Homebrew keeps one at
4
+ * `<prefix>/bin/node` (`/opt/homebrew` on Apple silicon, `/usr/local` on Intel) pointing into the
5
+ * versioned Cellar directory, plus a `<prefix>/opt/...` name per keg-only formula. HOMEBREW_PREFIX
6
+ * covers a custom prefix when the install runs from a brew-aware shell.
7
+ *
8
+ * Only used to find a stable NAME for the interpreter that is already running this install, never to
9
+ * pick a different one: stableNodePath substitutes a candidate only when realpath proves it is the
10
+ * same binary. Order therefore does not decide anything here.
11
+ */
12
+ export declare function stableNodeCandidates(env?: NodeJS.ProcessEnv): string[];
13
+ /**
14
+ * A stable path for the node running this install, for baking into the app.
15
+ *
16
+ * WHY NOT process.execPath DIRECTLY. execPath reports the interpreter with symlinks resolved, so a
17
+ * Homebrew node comes back as `/opt/homebrew/Cellar/node/26.8.1/bin/node`. The next `brew upgrade
18
+ * node` deletes that directory, and an app holding it can no longer start the dashboard -- nor
19
+ * repair itself, because the self-heal check runs under the same dead interpreter -- so the window
20
+ * shows its failure page on every launch until someone re-runs install-app by hand.
21
+ * `/opt/homebrew/bin/node` names the same binary today and the upgraded one after that.
22
+ *
23
+ * The trade this makes: `brew unlink node`, or pinning to a keg-only formula later, invalidates the
24
+ * symlink in a case where the versioned Cellar path would still have worked. Worth it, since an
25
+ * upgrade is far more common than an unlink and the failure page now names the exact repair either
26
+ * way, but it is a new way to end up on that page.
27
+ *
28
+ * Substitutes ONLY when a candidate resolves to the exact same executable, so this never bakes in a
29
+ * different node than the one that ran the install: an nvm or system interpreter keeps its own path
30
+ * because no candidate points at it. When nothing matches, the answer is execPath, unchanged.
31
+ *
32
+ * Exported for testing.
33
+ */
34
+ export declare function stableNodePath(execPath?: string, candidates?: string[]): string;
2
35
  /**
3
36
  * Resolve npx's absolute path, same reasoning as the baked-in node path: a Finder-launched dock
4
37
  * app gets a minimal PATH with no shell config, so a bare `npx` would not resolve. npm ships npx
5
38
  * alongside node in most installs, so check there first; `which` covers the rest. Returns null
6
39
  * (never throws) so a machine with no npx just does not get the self-heal capability.
40
+ *
41
+ * Looks alongside the STABLE node path rather than execPath for the same upgrade reason: the npx next
42
+ * to a Cellar interpreter disappears with it.
7
43
  */
8
44
  export declare function resolveNpxPath(): string | null;
9
45
  /**
@@ -26,7 +62,33 @@ export declare function launcherScript(nodeBin: string, webBin: string, port: nu
26
62
  * Exported like launcherScript, for the same reason: a test can assert on the generated text
27
63
  * without touching ~/Applications.
28
64
  */
29
- export declare function swiftInstallConfig(radarUrl: string, node: string, webBin: string, npx: string, mcpBin: string): string;
65
+ export declare function swiftInstallConfig(radarUrl: string, node: string, webBin: string, mcpBin: string): string;
66
+ /** The values install-app bakes into the app, resolved once so the substitution stays pure. */
67
+ export interface InstallConfigValues {
68
+ node: string;
69
+ webBin: string;
70
+ mcpBin: string;
71
+ }
72
+ /**
73
+ * Everything the app needs to know about THIS machine.
74
+ *
75
+ * Takes the same overrides stableNodePath() does, for one reason: without them, a test can only assert
76
+ * against whatever the host happens to be, and on a machine with no version-free name for its node
77
+ * (a Linux CI box) the two sides of that assertion converge and the check passes against code that
78
+ * bakes execPath. With them, a synthetic Homebrew layout proves the wiring anywhere.
79
+ */
80
+ export declare function installConfigValues(execPath?: string, candidates?: string[]): InstallConfigValues;
81
+ /**
82
+ * RadarApp.swift with its install-config block replaced by this machine's real values. Returns null
83
+ * when the markers no longer match, which must never compile: an app built from the file's own
84
+ * defaults would point at nothing useful.
85
+ *
86
+ * Separate from buildSwiftApp so the values that reach the app can be asserted without a Swift
87
+ * toolchain, which is the only way a Linux CI box can see this wiring at all. Takes those values
88
+ * rather than resolving them, so it stays a pure text substitution: a caller (or a test) can hand it
89
+ * a synthetic machine layout, and nothing here executes an interpreter.
90
+ */
91
+ export declare function patchedSwiftSource(source: string, values: InstallConfigValues): string | null;
30
92
  /**
31
93
  * Create (or replace) the launcher app. Returns its path.
32
94
  *
@@ -39,6 +101,7 @@ export declare function swiftInstallConfig(radarUrl: string, node: string, webBi
39
101
  export declare function installMacApp(): {
40
102
  app: string;
41
103
  native: boolean;
104
+ node: string;
42
105
  };
43
106
  /** Entry point for the `install-app` subcommand. Prints what to do next, then reveals the app. */
44
107
  export declare function runInstallApp(): void;