@slack/radar-mcp 1.18.0 → 1.19.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
@@ -8,20 +8,24 @@ Gives Claude Code direct access to network calls, RTM events, analytics (clogs),
8
8
 
9
9
  ## Installation
10
10
 
11
- The recommended path is via the marketplace plugin:
11
+ The dashboard and the agent tools are set up separately. `install-app` gives you the dock app (see [Install it to your dock](#install-it-to-your-dock-macos) below); the tools need registering in every client you use.
12
+
13
+ For Claude Code, the recommended path is the marketplace plugin:
12
14
 
13
15
  ```bash
14
16
  /plugin install slack-radar@slack-android-marketplace
15
17
  /slack-radar-setup
16
18
  ```
17
19
 
18
- Or register manually:
20
+ Or register it in Claude Code manually:
19
21
 
20
22
  ```bash
21
23
  slack claude mcp add -s user slack-radar-mcp -- npx -y @slack/radar-mcp@latest
22
24
  ```
23
25
 
24
- Restart your Claude Code session for the tools to appear.
26
+ Every other MCP client registers servers its own way, in its own config format, but the entry is the same shape everywhere: a command of `npx`, with the arguments `-y` and `@slack/radar-mcp@latest`. Check your client's own documentation for which file that entry belongs in and what syntax it expects.
27
+
28
+ Restart the client for the tools to appear, whichever one you registered with.
25
29
 
26
30
  ## Web Dashboard
27
31
 
@@ -50,7 +54,7 @@ Opens `http://localhost:8100` automatically. Set `SLACK_RADAR_WEB_PORT` to use a
50
54
  * **Preferences** — read-only browser for the on-device SharedPreferences files (pick a file, browse its keys, or search across every file at once).
51
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.
52
56
 
53
- 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). 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.
54
58
 
55
59
  ### Install it to your dock (macOS)
56
60
 
@@ -88,6 +92,7 @@ All optional. Set them on the process that runs the MCP server or the dashboard.
88
92
  | `SLACK_RADAR_DEVICE_PORT` | Host port forwarded to the device-side server. Default `8099`. |
89
93
  | `SLACK_RADAR_NO_AUTO_CLOSE=1` | Keep the dashboard running forever instead of closing it once every tab is gone. |
90
94
  | `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. |
95
+ | `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. |
91
96
  | `SLACK_RADAR_NO_OPEN=1` | Do not open a browser window on launch. Set automatically when an MCP tool spawns the dashboard. |
92
97
  | `SLACK_RADAR_NO_FFMPEG=1` | Pretend ffmpeg is absent, so screen recording degrades to screenshots. |
93
98
  | `SLACK_RADAR_PLATFORM` | Transport to use: `android` (the default) or `ios`. Radar does not probe or infer a different platform. |
package/dist/mcp/index.js CHANGED
@@ -5,6 +5,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
5
5
  import { spawn } from "child_process";
6
6
  import fs from "fs";
7
7
  import http from "http";
8
+ import os from "os";
8
9
  import path from "path";
9
10
  import { fileURLToPath } from "url";
10
11
  import { AndroidTransport } from "../shared/android.js";
@@ -204,7 +205,23 @@ else if (wantsWeb) {
204
205
  else {
205
206
  await runMcpServer();
206
207
  }
208
+ // Same ~/.slack-radar dir + overwrite convention as install-app.ts's writeSelfHealState. What this
209
+ // records is narrower than "the tools are registered": it means an MCP server process booted here
210
+ // at least once, which is all the dashboard's /setup-hint route claims.
211
+ function writeMcpSeenMarker() {
212
+ const file = path.join(os.homedir(), ".slack-radar", "mcp-last-seen.json");
213
+ try {
214
+ fs.mkdirSync(path.dirname(file), { recursive: true });
215
+ fs.writeFileSync(file, JSON.stringify({ seenAt: new Date().toISOString(), version: RADAR_VERSION }));
216
+ }
217
+ catch {
218
+ // Best-effort: the marker only feeds a dashboard hint, never worth failing boot over.
219
+ }
220
+ }
207
221
  async function runMcpServer() {
222
+ // Only real MCP server boots write the marker; the install-app and web dispatch branches above
223
+ // never reach this, so the dock launcher and its self-heal child cannot forge it.
224
+ writeMcpSeenMarker();
208
225
  // --- Platform selection ---
209
226
  //
210
227
  // No-flag auto-detect probes, in order: an attached adb device wins (android, exactly like today);
@@ -793,7 +810,7 @@ async function runMcpServer() {
793
810
  }
794
811
  }
795
812
  // --- MCP Server ---
796
- const server = new Server({ name: "slack-radar", version: "1.18.0" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
813
+ const server = new Server({ name: "slack-radar", version: "1.19.0" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
797
814
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
798
815
  tools: TOOL_DEFINITIONS,
799
816
  }));
@@ -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;
@@ -14,6 +14,15 @@ const ENABLE_ACTION = "slack.debug.ENABLE_RADAR";
14
14
  * to get a real answer rather than an "unknown".
15
15
  */
16
16
  const PS_PROBE_TIMEOUT_MS = 5000;
17
+ /**
18
+ * Ceiling for `adb devices -l`. Overridable because a test that deliberately parks a fake adb
19
+ * inside a listing (to pin what happens when a request lands mid-chain) otherwise races this
20
+ * timeout, and a loaded CI box turns it red for a reason unrelated to what the test asserts.
21
+ * Production never sets the env var and keeps the 5s default.
22
+ */
23
+ const LIST_DEVICES_TIMEOUT_MS = Number(process.env.SLACK_RADAR_ADB_LIST_TIMEOUT_MS) > 0
24
+ ? Number(process.env.SLACK_RADAR_ADB_LIST_TIMEOUT_MS)
25
+ : 5000;
17
26
  /**
18
27
  * Resolve the adb binary. MCP servers spawned from GUI launchers (Spotlight,
19
28
  * Raycast, Dock) do not inherit the user's shell PATH, so a bare `adb` call
@@ -597,7 +606,7 @@ export class AndroidTransport {
597
606
  return [];
598
607
  try {
599
608
  const { stdout } = await execFileAsync(ADB, ["devices", "-l"], {
600
- timeout: 5000,
609
+ timeout: LIST_DEVICES_TIMEOUT_MS,
601
610
  encoding: "utf-8",
602
611
  });
603
612
  const devices = parseAdbDevicesOutput(stdout);
@@ -622,7 +631,16 @@ export class AndroidTransport {
622
631
  this.selectedDevice = null;
623
632
  }
624
633
  selectDevice(serial) {
625
- 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);
626
644
  }
627
645
  /**
628
646
  * selectDevice, off the event loop. The listing runs through execFileAsync; the pick
@@ -630,14 +648,18 @@ export class AndroidTransport {
630
648
  * disagree about which device wins.
631
649
  */
632
650
  async selectDeviceAsync(serial) {
633
- return this.pickFromListing(await this.listDevicesAsync(), serial);
651
+ return this.pickFromListing(await this.listDevicesAsync(), serial, true);
634
652
  }
635
653
  // Everything selectDevice decides once a listing (or its failure, null) is in hand.
636
- 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) {
637
658
  if (devices === null) {
638
659
  return {
639
660
  ok: false,
640
661
  error: "Could not list devices (adb devices failed). Check adb and retry.",
662
+ instructs: true,
641
663
  devices: [],
642
664
  };
643
665
  }
@@ -655,13 +677,15 @@ export class AndroidTransport {
655
677
  if (serial) {
656
678
  const match = attached.find((d) => d.serial === serial);
657
679
  if (match) {
658
- this.pin(match.serial, match.label);
680
+ if (commit)
681
+ this.pin(match.serial, match.label);
659
682
  return { ok: true, serial: match.serial, switched: switchedTo(match.serial), devices };
660
683
  }
661
684
  const list = attached.length > 0 ? listAttached() : "none";
662
685
  return {
663
686
  ok: false,
664
687
  error: `Device ${serial} is not attached (or not authorized). Attached: ${list}`,
688
+ instructs: false,
665
689
  devices,
666
690
  };
667
691
  }
@@ -671,17 +695,21 @@ export class AndroidTransport {
671
695
  if (pinned) {
672
696
  const stillAttached = attached.find((d) => d.serial === pinned);
673
697
  if (stillAttached) {
674
- this.pin(stillAttached.serial, stillAttached.label);
698
+ if (commit)
699
+ this.pin(stillAttached.serial, stillAttached.label);
675
700
  return { ok: true, serial: stillAttached.serial, switched: switchedTo(stillAttached.serial), devices };
676
701
  }
677
702
  // The pinned device detached. Drop the stale env pin AND the recorded selection so
678
703
  // /health does not keep claiming a device that is gone.
679
- delete process.env.ANDROID_SERIAL;
680
- this.selectedDevice = null;
704
+ if (commit) {
705
+ delete process.env.ANDROID_SERIAL;
706
+ this.selectedDevice = null;
707
+ }
681
708
  }
682
709
  // (c) Exactly one attached device: auto-pin it.
683
710
  if (attached.length === 1) {
684
- this.pin(attached[0].serial, attached[0].label);
711
+ if (commit)
712
+ this.pin(attached[0].serial, attached[0].label);
685
713
  return { ok: true, serial: attached[0].serial, switched: switchedTo(attached[0].serial), devices };
686
714
  }
687
715
  // (d) Zero devices (or a fake adb that does not answer `devices -l`): no-op. The
@@ -689,7 +717,8 @@ export class AndroidTransport {
689
717
  // ok/null keeps every flow that fakes adb without a listing green.
690
718
  if (attached.length === 0) {
691
719
  // Nothing attached: clear any recorded selection so /health reports no device.
692
- this.selectedDevice = null;
720
+ if (commit)
721
+ this.selectedDevice = null;
693
722
  return { ok: true, serial: null, devices };
694
723
  }
695
724
  // (e) 2+ attached devices with no explicit choice: ambiguous. The transport error stays a
@@ -697,6 +726,7 @@ export class AndroidTransport {
697
726
  return {
698
727
  ok: false,
699
728
  error: `Multiple devices attached; specify which one. Attached: ${listAttached()}.`,
729
+ instructs: true,
700
730
  devices,
701
731
  };
702
732
  }
@@ -25,8 +25,8 @@ export interface DashboardScreenController {
25
25
  /**
26
26
  * The safe subset of reset(): drop cached detection/capability state so the next capture
27
27
  * re-detects, WITHOUT stopping recordings or deleting artifacts. This is what a same-device
28
- * re-arm needs; reset() is reserved for real session boundaries (device swap, first enable
29
- * of the process).
28
+ * re-arm needs; reset() is reserved for real session boundaries (device swap, dashboard boot, a
29
+ * first enable that boot could not reap for, a deliberate re-detect).
30
30
  */
31
31
  resetDetection(): void;
32
32
  resolveRecording(file: string): string | null;
@@ -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
  }
@@ -1,10 +1,27 @@
1
+ /**
2
+ * The one definition of where screen captures live. Exported so screen.ts shares this exact
3
+ * directory rather than rebuilding the same path: two independent joins can be tightened on one
4
+ * side and not the other, and cleanup that scans a different directory than capture writes to
5
+ * deletes nothing.
6
+ */
7
+ export declare const SCREEN_DIRECTORY: string;
1
8
  /** Allocate an owner-only path for a recording containing sensitive screen content. */
2
9
  export declare function createRecordingPath(): string;
3
10
  /** Restrict a completed recording to its owner. */
4
11
  export declare function secureRecording(recording: string): void;
5
12
  /** Remove a failed or cancelled recording without surfacing cleanup errors. */
6
13
  export declare function removeRecording(recording: string): void;
7
- /** Remove every Radar-owned screen recording at a session boundary. */
14
+ /**
15
+ * Remove every Radar-owned capture at a session boundary: a dashboard boot, a device change, a first
16
+ * enable that boot could not reap for, a deliberate re-detect, or process exit. Recordings and
17
+ * screenshots both hold sensitive live screen content and must not linger across sessions on disk.
18
+ * NOT run on a plain re-arm of the same device, which leaves the user's own clips alone. The name
19
+ * check keeps an unrelated file that landed in the dir out of reach.
20
+ *
21
+ * The one implementation on purpose: screen.ts re-exports this rather than keeping the copy it used
22
+ * to have, so the dir and the name pattern cannot be tightened on one session-boundary cleanup and
23
+ * not the other.
24
+ */
8
25
  export declare function cleanupRecordings(): void;
9
26
  /** Resolve a safe recording download without allowing traversal or unrelated files. */
10
27
  export declare function recordingPath(file: string): string | null;
@@ -1,7 +1,13 @@
1
1
  import fs from "node:fs";
2
2
  import os from "node:os";
3
3
  import path from "node:path";
4
- const SCREEN_DIRECTORY = path.join(os.homedir(), ".slack-radar", "screen");
4
+ /**
5
+ * The one definition of where screen captures live. Exported so screen.ts shares this exact
6
+ * directory rather than rebuilding the same path: two independent joins can be tightened on one
7
+ * side and not the other, and cleanup that scans a different directory than capture writes to
8
+ * deletes nothing.
9
+ */
10
+ export const SCREEN_DIRECTORY = path.join(os.homedir(), ".slack-radar", "screen");
5
11
  const RECORDING_NAME = /^radar_screen_[\w-]+\.(mp4|png)$/;
6
12
  /** Allocate an owner-only path for a recording containing sensitive screen content. */
7
13
  export function createRecordingPath() {
@@ -35,7 +41,17 @@ export function removeRecording(recording) {
35
41
  // The file may not have been created yet.
36
42
  }
37
43
  }
38
- /** Remove every Radar-owned screen recording at a session boundary. */
44
+ /**
45
+ * Remove every Radar-owned capture at a session boundary: a dashboard boot, a device change, a first
46
+ * enable that boot could not reap for, a deliberate re-detect, or process exit. Recordings and
47
+ * screenshots both hold sensitive live screen content and must not linger across sessions on disk.
48
+ * NOT run on a plain re-arm of the same device, which leaves the user's own clips alone. The name
49
+ * check keeps an unrelated file that landed in the dir out of reach.
50
+ *
51
+ * The one implementation on purpose: screen.ts re-exports this rather than keeping the copy it used
52
+ * to have, so the dir and the name pattern cannot be tightened on one session-boundary cleanup and
53
+ * not the other.
54
+ */
39
55
  export function cleanupRecordings() {
40
56
  try {
41
57
  for (const file of fs.readdirSync(SCREEN_DIRECTORY)) {
@@ -37,15 +37,8 @@
37
37
  * explicitly on cleanup.
38
38
  */
39
39
  import { type ChildProcess } from "child_process";
40
- /**
41
- * Remove all captures from the screen tmp dir. Recordings and screenshots both hold
42
- * sensitive live screen content and must not linger across sessions on disk. Called from
43
- * resetScreenState(), so it runs on a session boundary (a device change, the first enable of
44
- * the process, or a deliberate re-detect) and on process exit. It is NOT run on every device
45
- * re-enable: a plain re-arm of the same device leaves the user's clips alone. Scoped to the
46
- * names this module writes so it never deletes an unrelated file that landed in the dir.
47
- */
48
- export declare function cleanupRecordings(): void;
40
+ import { cleanupRecordings } from "./screen-artifacts.js";
41
+ export { cleanupRecordings };
49
42
  /** Resolve an ffmpeg binary, or null if none is installed. Cached. */
50
43
  export declare function resolveFfmpeg(): string | null;
51
44
  /** Whether scrcpy is installed (the no-ffmpeg fallback hint). Cached. */
@@ -250,16 +243,17 @@ export declare function saveScreenshot(): Promise<ScreenshotSaveResult>;
250
243
  export declare function resetScreenDetection(): void;
251
244
  /**
252
245
  * Reset detection AND tear everything down: this process's live cast, the recorded mp4s, and any
253
- * orphaned device-side screenrecord radar left behind. Only for a real session boundary (different
254
- * hardware, a deliberate re-detect, or process exit): the recordings and the live cast are work a
255
- * user may be in the middle of, so calling this when nothing actually changed destroys it.
246
+ * orphaned device-side screenrecord radar left behind. Only for a real session boundary (dashboard
247
+ * boot, different hardware, a first enable that boot could not reap for, a deliberate re-detect, or
248
+ * process exit): the recordings and the live cast are work a user may be in the middle of, so
249
+ * calling this when nothing actually changed destroys it.
256
250
  */
257
251
  export declare function resetScreenState(): void;
258
252
  /**
259
253
  * Kill any live cast (and orphaned device-side screenrecord) on process exit. Mirrors
260
254
  * logcat-capture.registerCleanup(); without it, Ctrl-C on an open mirror orphans the
261
255
  * screenrecord + ffmpeg children and leaves the device transport congested for the
262
- * next session. Called from createServer().
256
+ * next session. Called once the port bind is won (see registerScreenCleanupOnBind), so a launcher
257
+ * that loses the bind never arms a handler that would delete the winner's captures.
263
258
  */
264
259
  export declare function registerScreenCleanup(): void;
265
- export {};