@slack/radar-mcp 1.19.0 → 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 `/` (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). 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.
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
 
@@ -165,6 +171,8 @@ Mobile debug build (device)
165
171
 
166
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.
167
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
+
168
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.
169
177
 
170
178
  ## Security
@@ -257,3 +265,30 @@ Restart your Claude Code session. MCP servers are registered at session start.
257
265
 
258
266
  **Port already in use (web dashboard)**
259
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.19.0" }, { 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] },
@@ -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,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;
@@ -57,14 +57,105 @@ function webBinPath() {
57
57
  function mcpBinPath() {
58
58
  return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "mcp", "index.js");
59
59
  }
60
+ /**
61
+ * A keg-only formula (`brew install node@22`) is not linked into `<prefix>/bin`, so it has no entry
62
+ * under that name. Homebrew still gives it one version-free path,
63
+ * `<prefix>/opt/node@22/bin/node`, which is exactly the kind of name this file is looking for.
64
+ * Returns nothing when the directory is absent, which is every non-Homebrew machine.
65
+ *
66
+ * Newest formula first. Plain `node` leads: it is the unpinned formula, so it is the one brew keeps
67
+ * current. Major only in the comparator, since a directory may be `node@22.1.2` and Number("22.1.2")
68
+ * is NaN, which would make the comparison meaningless rather than merely wrong.
69
+ */
70
+ function kegOnlyNodePaths(prefix) {
71
+ try {
72
+ return fs
73
+ .readdirSync(path.join(prefix, "opt"))
74
+ .filter((entry) => /^node(@[\d.]+)?$/.test(entry))
75
+ .sort((a, b) => {
76
+ const version = (name) => Number(name.split("@")[1]?.split(".")[0] ?? Infinity);
77
+ return version(b) - version(a);
78
+ })
79
+ .map((entry) => path.join(prefix, "opt", entry, "bin", "node"));
80
+ }
81
+ catch {
82
+ return []; // no <prefix>/opt to read, so no keg-only formulas to find
83
+ }
84
+ }
85
+ /**
86
+ * Where a stable, version-free name for a node interpreter could live. Homebrew keeps one at
87
+ * `<prefix>/bin/node` (`/opt/homebrew` on Apple silicon, `/usr/local` on Intel) pointing into the
88
+ * versioned Cellar directory, plus a `<prefix>/opt/...` name per keg-only formula. HOMEBREW_PREFIX
89
+ * covers a custom prefix when the install runs from a brew-aware shell.
90
+ *
91
+ * Only used to find a stable NAME for the interpreter that is already running this install, never to
92
+ * pick a different one: stableNodePath substitutes a candidate only when realpath proves it is the
93
+ * same binary. Order therefore does not decide anything here.
94
+ */
95
+ export function stableNodeCandidates(env = process.env) {
96
+ // A relative prefix would produce a relative path, and the app resolves its interpreter against
97
+ // whatever directory Finder launched it from, so only an absolute prefix is usable here.
98
+ const brewPrefixes = ["/opt/homebrew"];
99
+ const configured = env.HOMEBREW_PREFIX;
100
+ if (configured && path.isAbsolute(configured))
101
+ brewPrefixes.unshift(configured);
102
+ const namesUnder = (prefix) => [path.join(prefix, "bin", "node"), ...kegOnlyNodePaths(prefix)];
103
+ return [...new Set([...brewPrefixes.flatMap(namesUnder), "/usr/bin/node", ...namesUnder("/usr/local")])];
104
+ }
105
+ /**
106
+ * A stable path for the node running this install, for baking into the app.
107
+ *
108
+ * WHY NOT process.execPath DIRECTLY. execPath reports the interpreter with symlinks resolved, so a
109
+ * Homebrew node comes back as `/opt/homebrew/Cellar/node/26.8.1/bin/node`. The next `brew upgrade
110
+ * node` deletes that directory, and an app holding it can no longer start the dashboard -- nor
111
+ * repair itself, because the self-heal check runs under the same dead interpreter -- so the window
112
+ * shows its failure page on every launch until someone re-runs install-app by hand.
113
+ * `/opt/homebrew/bin/node` names the same binary today and the upgraded one after that.
114
+ *
115
+ * The trade this makes: `brew unlink node`, or pinning to a keg-only formula later, invalidates the
116
+ * symlink in a case where the versioned Cellar path would still have worked. Worth it, since an
117
+ * upgrade is far more common than an unlink and the failure page now names the exact repair either
118
+ * way, but it is a new way to end up on that page.
119
+ *
120
+ * Substitutes ONLY when a candidate resolves to the exact same executable, so this never bakes in a
121
+ * different node than the one that ran the install: an nvm or system interpreter keeps its own path
122
+ * because no candidate points at it. When nothing matches, the answer is execPath, unchanged.
123
+ *
124
+ * Exported for testing.
125
+ */
126
+ export function stableNodePath(execPath = process.execPath, candidates = stableNodeCandidates()) {
127
+ let real;
128
+ try {
129
+ real = fs.realpathSync(execPath);
130
+ }
131
+ catch {
132
+ return execPath; // cannot resolve it, so cannot prove a candidate is the same binary
133
+ }
134
+ for (const candidate of candidates) {
135
+ if (candidate === real)
136
+ continue; // already the stable name; an indirection would add nothing
137
+ try {
138
+ if (fs.realpathSync(candidate) === real)
139
+ return candidate;
140
+ }
141
+ catch {
142
+ // This candidate could not be resolved: usually absent, sometimes an unreadable parent
143
+ // directory or a symlink cycle. Either way it cannot be proven to be the same binary.
144
+ }
145
+ }
146
+ return execPath;
147
+ }
60
148
  /**
61
149
  * Resolve npx's absolute path, same reasoning as the baked-in node path: a Finder-launched dock
62
150
  * app gets a minimal PATH with no shell config, so a bare `npx` would not resolve. npm ships npx
63
151
  * alongside node in most installs, so check there first; `which` covers the rest. Returns null
64
152
  * (never throws) so a machine with no npx just does not get the self-heal capability.
153
+ *
154
+ * Looks alongside the STABLE node path rather than execPath for the same upgrade reason: the npx next
155
+ * to a Cellar interpreter disappears with it.
65
156
  */
66
157
  export function resolveNpxPath() {
67
- const alongsideNode = path.join(path.dirname(process.execPath), "npx");
158
+ const alongsideNode = path.join(path.dirname(stableNodePath()), "npx");
68
159
  if (fs.existsSync(alongsideNode))
69
160
  return alongsideNode;
70
161
  try {
@@ -131,6 +222,28 @@ alive() {
131
222
  }
132
223
 
133
224
  if ! alive; then
225
+ # Checked here rather than at the top: a dashboard that is already serving needs no interpreter, so
226
+ # a moved node only matters on the path that has to start one.
227
+ #
228
+ # A dialog because there is nowhere else to say it. This script only exists on a Mac with no Swift
229
+ # toolchain, so there is no native window to render a failure page, and a Finder-launched script's
230
+ # stderr goes nowhere the user will ever look. Without this they get a browser connection error that
231
+ # says nothing about node. The wording matches the native window's own node-missing page.
232
+ if [ ! -x "$NODE" ]; then
233
+ MSG="Slack Radar cannot run the node it was built with.
234
+
235
+ $NODE
236
+
237
+ A node upgrade usually moves it. Run this in a terminal, then reopen this app:
238
+
239
+ npx -y @slack/radar-mcp@latest install-app"
240
+ # The message goes in as an ARGUMENT, not interpolated into the AppleScript: a path can contain
241
+ # a quote or a backslash, and building the script text around one is how that turns into a
242
+ # syntax error instead of a dialog.
243
+ osascript -e 'on run {msg}' -e 'display dialog msg with title "Slack Radar" buttons {"OK"} default button "OK" with icon caution' -e 'end run' "$MSG" >/dev/null 2>&1
244
+ exit 1
245
+ fi
246
+
134
247
  # SLACK_RADAR_NO_OPEN stops the server from racing us to open a BROWSER TAB: this app wants the
135
248
  # standalone window it opens below, not a tab. Fully detached (setsid-style via nohup + &, stdio
136
249
  # to a log) so the server outlives this launcher script -- otherwise the app "quitting" would
@@ -189,17 +302,49 @@ open "$URL"
189
302
  * Exported like launcherScript, for the same reason: a test can assert on the generated text
190
303
  * without touching ~/Applications.
191
304
  */
192
- export function swiftInstallConfig(radarUrl, node, webBin, npx, mcpBin) {
305
+ export function swiftInstallConfig(radarUrl, node, webBin, mcpBin) {
193
306
  return [
194
307
  "// --- BEGIN INSTALL CONFIG (substituted by install-app) ---",
195
308
  `let RADAR_URL = ${JSON.stringify(radarUrl)}`,
196
309
  `let RADAR_NODE = ${JSON.stringify(node)}`,
197
310
  `let RADAR_WEB_BIN = ${JSON.stringify(webBin)}`,
198
- `let RADAR_NPX = ${JSON.stringify(npx)}`,
199
311
  `let RADAR_MCP_BIN = ${JSON.stringify(mcpBin)}`,
312
+ // Not a parameter: the package doing the install IS the version the app is built from, so taking
313
+ // it from anywhere else would only create a way for the two to disagree.
314
+ `let RADAR_APP_VERSION = ${JSON.stringify(RADAR_VERSION)}`,
200
315
  "// --- END INSTALL CONFIG ---",
201
316
  ].join("\n");
202
317
  }
318
+ /**
319
+ * Everything the app needs to know about THIS machine.
320
+ *
321
+ * Takes the same overrides stableNodePath() does, for one reason: without them, a test can only assert
322
+ * against whatever the host happens to be, and on a machine with no version-free name for its node
323
+ * (a Linux CI box) the two sides of that assertion converge and the check passes against code that
324
+ * bakes execPath. With them, a synthetic Homebrew layout proves the wiring anywhere.
325
+ */
326
+ export function installConfigValues(execPath, candidates) {
327
+ return {
328
+ node: stableNodePath(execPath ?? process.execPath, candidates ?? stableNodeCandidates()),
329
+ webBin: webBinPath(),
330
+ mcpBin: mcpBinPath(),
331
+ };
332
+ }
333
+ /**
334
+ * RadarApp.swift with its install-config block replaced by this machine's real values. Returns null
335
+ * when the markers no longer match, which must never compile: an app built from the file's own
336
+ * defaults would point at nothing useful.
337
+ *
338
+ * Separate from buildSwiftApp so the values that reach the app can be asserted without a Swift
339
+ * toolchain, which is the only way a Linux CI box can see this wiring at all. Takes those values
340
+ * rather than resolving them, so it stays a pure text substitution: a caller (or a test) can hand it
341
+ * a synthetic machine layout, and nothing here executes an interpreter.
342
+ */
343
+ export function patchedSwiftSource(source, values) {
344
+ const config = swiftInstallConfig(`http://localhost:${WEB_PORT}`, values.node, values.webBin, values.mcpBin);
345
+ const patched = source.replace(/\/\/ --- BEGIN INSTALL CONFIG ---[\s\S]*?\/\/ --- END INSTALL CONFIG ---/, config);
346
+ return patched === source ? null : patched;
347
+ }
203
348
  /**
204
349
  * Compile the WKWebView app into `dest`. Returns false if the machine cannot build it, so install
205
350
  * falls back to the shell launcher rather than failing outright.
@@ -209,7 +354,7 @@ export function swiftInstallConfig(radarUrl, node, webBin, npx, mcpBin) {
209
354
  * two architectures, and would mean shipping an opaque executable through npm. Compiling locally
210
355
  * sidesteps all three: the output is a local build, which Gatekeeper treats as such.
211
356
  */
212
- function buildSwiftApp(dest) {
357
+ function buildSwiftApp(dest, values) {
213
358
  const src = path.join(path.dirname(fileURLToPath(import.meta.url)), "macapp", "RadarApp.swift");
214
359
  if (!fs.existsSync(src))
215
360
  return false;
@@ -219,13 +364,8 @@ function buildSwiftApp(dest) {
219
364
  catch {
220
365
  return false; // no Swift toolchain (no Xcode or Command Line Tools)
221
366
  }
222
- const webBin = webBinPath();
223
- // Substitute the install-time config block. Anchored to the markers so the replacement cannot
224
- // silently miss and compile an app pointing at the defaults.
225
- const source = fs.readFileSync(src, "utf8");
226
- const config = swiftInstallConfig(`http://localhost:${WEB_PORT}`, process.execPath, webBin, resolveNpxPath() ?? "", mcpBinPath());
227
- const patched = source.replace(/\/\/ --- BEGIN INSTALL CONFIG ---[\s\S]*?\/\/ --- END INSTALL CONFIG ---/, config);
228
- if (patched === source)
367
+ const patched = patchedSwiftSource(fs.readFileSync(src, "utf8"), values);
368
+ if (patched === null)
229
369
  return false; // markers moved; do not ship a misconfigured binary
230
370
  const tmpSrc = path.join(os.tmpdir(), `radar-app-${process.pid}.swift`);
231
371
  try {
@@ -352,7 +492,9 @@ export function installMacApp() {
352
492
  const app = path.join(dir, `${APP_NAME}.app`);
353
493
  const staging = `${app}.new`;
354
494
  const backup = `${app}.old`;
355
- const webBin = webBinPath();
495
+ // Resolved once, since both build paths below need the same answer.
496
+ const values = installConfigValues();
497
+ const webBin = values.webBin;
356
498
  if (!fs.existsSync(webBin)) {
357
499
  throw new Error(`cannot find the dashboard entrypoint at ${webBin}`);
358
500
  }
@@ -361,12 +503,12 @@ export function installMacApp() {
361
503
  // staging path -- for the self-heal caller that just means trying again next launch.
362
504
  fs.mkdirSync(dir, { recursive: true });
363
505
  const lockPath = path.join(dir, ".install.lock");
364
- // buildSwiftApp()'s compile step is bounded to 60s (see its execFileSync timeout) specifically
365
- // so this threshold is an actual upper bound on install duration, not an assumption -- icon
366
- // generation and everything else here is fast in comparison. A lock older than this can only be
367
- // a crash leftover, the process that made it died before reaching the finally below. Without
368
- // this, one crashed install would wedge every self-heal check forever, since nothing else ever
369
- // removes the lock file.
506
+ // buildSwiftApp()'s compile is the one step in here that can be slow for a structural reason, and it
507
+ // is bounded at 60s by its own execFileSync timeout, which leaves about 60s of slack against this
508
+ // threshold. The rest is unbounded but local and sub-second in practice (sips, iconutil, lsregister).
509
+ // A lock older than this can only be a crash leftover, the process that made it died before reaching
510
+ // the finally below. Without this, one crashed install would wedge every self-heal check forever,
511
+ // since nothing else ever removes the lock file.
370
512
  const STALE_LOCK_MS = 2 * 60 * 1000;
371
513
  let lockFd;
372
514
  try {
@@ -401,11 +543,12 @@ export function installMacApp() {
401
543
  fs.mkdirSync(resources, { recursive: true });
402
544
  // Prefer the native window; fall back to the shell launcher (opens a browser) if Swift is absent.
403
545
  const nativeExe = path.join(macos, "SlackRadar");
404
- const native = buildSwiftApp(nativeExe);
546
+ const native = buildSwiftApp(nativeExe, values);
405
547
  if (!native) {
406
- // process.execPath is the node running THIS install, the one known-good interpreter on the
407
- // machine. Under npx that is the same node the dashboard would run under anyway.
408
- fs.writeFileSync(path.join(macos, "radar-launcher"), launcherScript(process.execPath, webBin, WEB_PORT), {
548
+ // The node running THIS install, under its most stable name, is the one known-good
549
+ // interpreter on the machine. Under npx that is the same node the dashboard would run under
550
+ // anyway. See stableNodePath() for why the name matters more than the exact path.
551
+ fs.writeFileSync(path.join(macos, "radar-launcher"), launcherScript(values.node, webBin, WEB_PORT), {
409
552
  mode: 0o755,
410
553
  });
411
554
  }
@@ -441,7 +584,7 @@ export function installMacApp() {
441
584
  if (!icon) {
442
585
  console.log("Note: could not build the app icon, so macOS will show a generic one.");
443
586
  }
444
- return { app, native };
587
+ return { app, native, node: values.node };
445
588
  }
446
589
  finally {
447
590
  fs.closeSync(lockFd);
@@ -470,10 +613,17 @@ export function runInstallApp() {
470
613
  "window. Install Xcode Command Line Tools (xcode-select --install) and re-run this for\n" +
471
614
  "a real app window.";
472
615
  console.log(`Installed ${result.app}\n\n` +
616
+ `Dashboard interpreter: ${result.node}\n\n` +
473
617
  `${how}\n\n` +
474
618
  `To keep it in your dock: open it once, then right-click its dock icon and choose\n` +
475
619
  `Options > Keep in Dock.\n\n` +
476
- `Clicking it starts the dashboard if it is not already running.`);
620
+ `Clicking it starts the dashboard if it is not already running.\n\n` +
621
+ // Said outright because the obvious move does not work. This replaced the app bundle, and a
622
+ // copy that is already running neither reloads itself nor re-checks the port, so clicking its
623
+ // dock icon only brings the old window forward with the old dashboard still behind it. That is
624
+ // the whole reported failure, and one sentence closes it.
625
+ `If Radar is already running, quit it and open it again. Clicking a running app only brings\n` +
626
+ `its window forward, so it would keep serving the version you just replaced.`);
477
627
  // Open the containing folder so the user can drag it to the dock without hunting for it.
478
628
  try {
479
629
  spawn("open", [appDir()], { detached: true, stdio: "ignore" }).unref();