xcodebug 1.2.0 → 1.2.1
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/GUIDE.md +58 -16
- package/README.md +257 -34
- package/claude/.claude-plugin/plugin.json +6 -0
- package/claude/hooks/hooks.json +3 -0
- package/claude/hooks/register.js +113 -0
- package/claude/tests/live.test.ts +321 -0
- package/index.ts +10 -9
- package/mcp/server.ts +77 -4
- package/package.json +3 -1
- package/skills/xcodebug/SKILL.md +78 -0
package/GUIDE.md
CHANGED
|
@@ -4,6 +4,14 @@ Task-oriented walkthrough. [README.md](README.md) is the authoritative reference
|
|
|
4
4
|
for every parameter, the change-detection rules and the capture internals; this
|
|
5
5
|
file only shows the flows you will actually type.
|
|
6
6
|
|
|
7
|
+
The `/xcodebug` examples use the native pi/omp command or the installed Claude
|
|
8
|
+
Code skill. In Codex, replace `/xcodebug` with `$xcodebug`. Claude Code and Codex
|
|
9
|
+
need both the MCP connection and the shared skill; follow
|
|
10
|
+
[README.md § Install the manual entry point](README.md#install-the-manual-entry-point).
|
|
11
|
+
Enter these commands in the client's chat input. A bare `/xcodebug` (`$xcodebug`
|
|
12
|
+
in Codex) builds as needed, installs, launches and starts capturing with defaults.
|
|
13
|
+
Use `/xcodebug status` (`$xcodebug status` in Codex) to inspect current captures.
|
|
14
|
+
|
|
7
15
|
Debug a real iOS device: build, install, launch, and read the app's console
|
|
8
16
|
(stdout/stderr + os_log) inside the agent session. No jailbreak, no LLDB attach,
|
|
9
17
|
no paid account.
|
|
@@ -20,9 +28,11 @@ model must answer — not a log filter.
|
|
|
20
28
|
|
|
21
29
|
## Two surfaces
|
|
22
30
|
|
|
23
|
-
**
|
|
31
|
+
**User entry point** (native command in pi/omp; installed skill in Claude Code/Codex)
|
|
24
32
|
|
|
25
33
|
```text
|
|
34
|
+
/xcodebug
|
|
35
|
+
/xcodebug status
|
|
26
36
|
/xcodebug launch scheme=MyApp
|
|
27
37
|
/xcodebug logs grep=MySDK
|
|
28
38
|
/xcodebug stop
|
|
@@ -40,20 +50,45 @@ The 14 actions and their parameters are tabulated in
|
|
|
40
50
|
[README.md § Usage](README.md#usage). Two of them differ from what the name
|
|
41
51
|
suggests, so they are repeated here:
|
|
42
52
|
|
|
43
|
-
- `stop` closes **every running capture
|
|
44
|
-
|
|
45
|
-
`keepApp=true` is the
|
|
53
|
+
- `stop` without `captureId` closes **every running capture**. With an ID, it
|
|
54
|
+
stops that target; stopping a console primary also stops its syslog companion.
|
|
55
|
+
Other apps' captures are unaffected by a targeted stop. `keepApp=true` is the
|
|
56
|
+
default and leaves the app running.
|
|
46
57
|
- `restart` replays the last launch of this session — device, scheme, goal and
|
|
47
58
|
the `command=` it carried — and forces a rebuild.
|
|
48
59
|
|
|
49
60
|
## How logs reach the conversation
|
|
50
61
|
|
|
51
|
-
`push` decides whether new lines are mirrored into the session: `context`
|
|
62
|
+
In pi/omp, `push` decides whether new lines are mirrored into the session: `context`
|
|
52
63
|
(default, queued for the next turn), `off` (pull with `logs`/`wait`), `wake`
|
|
53
64
|
(starts a turn). A device console is a firehose; each push carries at most 80
|
|
54
65
|
lines and reports how many older lines it dropped. Narrow it with `match`, e.g.
|
|
55
66
|
`action=launch match=MySDK push=wake`.
|
|
56
67
|
|
|
68
|
+
Claude Code and Codex use pull reads through MCP: `logs` for an incremental read,
|
|
69
|
+
or `wait` for an expected line. `push=context` and `push=wake` are refused there;
|
|
70
|
+
installing the skill does not add background log delivery.
|
|
71
|
+
|
|
72
|
+
For a live display in Claude Code, install the **separate** `xcodebug-live` Mod
|
|
73
|
+
using [the one-time installation recipe](README.md#install-once-for-ordinary-claude-sessions).
|
|
74
|
+
It then loads with ordinary `claude` startup. The MCP connection and shared
|
|
75
|
+
skill alone do not load it. Confirm `xcodebug-live@skills-dir` in
|
|
76
|
+
`claude plugin list`, then restart Claude and check `/plugin` and `/mcp`.
|
|
77
|
+
|
|
78
|
+
Keep the `xcodebug` MCP server pointed at the same updated checkout or installed
|
|
79
|
+
package as the Mod.
|
|
80
|
+
|
|
81
|
+
The band shows build/install/launch phases, including the rebuild within
|
|
82
|
+
`restart`, even when a capture is already running. Capture continues in the
|
|
83
|
+
background; after the operation finishes, fails, or is cancelled, the band
|
|
84
|
+
returns to the running capture's line count and latest four console lines.
|
|
85
|
+
It refreshes once a second, between turns too, while an operation or capture is
|
|
86
|
+
running, then clears and stops reading; an idle session makes no reads. It does
|
|
87
|
+
not send those lines to the model; use `logs`/`wait`
|
|
88
|
+
for analysis.
|
|
89
|
+
See [Claude Code live display](README.md#claude-code-live-display) for version
|
|
90
|
+
requirements, upgrade/disable steps and missing-display troubleshooting.
|
|
91
|
+
|
|
57
92
|
## Running a command alongside a capture
|
|
58
93
|
|
|
59
94
|
### What it is for
|
|
@@ -195,19 +230,26 @@ xcodebug action=await command="cd /repo && npm run test:weather"
|
|
|
195
230
|
Every capture is mirrored to
|
|
196
231
|
`<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`.
|
|
197
232
|
|
|
198
|
-
`agentDir` comes from the host (`ctx.agentDir`, else the parent of the
|
|
199
|
-
directory), so each brand writes under its own prefix (`.pi` / `.omp` /
|
|
200
|
-
`.senpi`)
|
|
201
|
-
|
|
202
|
-
milliseconds
|
|
203
|
-
|
|
204
|
-
lines
|
|
233
|
+
In pi/omp, `agentDir` comes from the host (`ctx.agentDir`, else the parent of the
|
|
234
|
+
session directory), so each brand writes under its own prefix (`.pi` / `.omp` /
|
|
235
|
+
`.omo` / `.senpi`). MCP defaults to `~/.xcodebug`, overridden by
|
|
236
|
+
`XCODEBUG_AGENT_DIR`. The bundle id separates apps, and the timestamp includes
|
|
237
|
+
milliseconds to separate runs.
|
|
238
|
+
|
|
239
|
+
Memory retains at most 20k lines and 4 MiB of text. Disk logging rotates through
|
|
240
|
+
the base path plus `.1` and `.2`, retaining three segments targeting 50 MiB each;
|
|
241
|
+
older segments are overwritten. Complete lines are kept, so a single oversized
|
|
242
|
+
line can exceed a segment's target size. Shutdown allows two seconds to drain
|
|
243
|
+
pending writes; a drain timeout can truncate logs. Neither memory nor disk is
|
|
244
|
+
a lossless archive of the whole run. See [retention](README.md#reading-logs-from-a-cursor)
|
|
245
|
+
and [disk files](README.md#files) for details and the `logFiles` path list.
|
|
205
246
|
|
|
206
247
|
## Three rules of use
|
|
207
248
|
|
|
208
|
-
1. **Stop once the log has answered the question.** A capture left running
|
|
209
|
-
|
|
249
|
+
1. **Stop once the log has answered the question.** A capture left running keeps
|
|
250
|
+
consuming capture resources; native push modes also keep sending log batches.
|
|
210
251
|
2. **Do not stop while the user has not acted yet.** Silence there means "not
|
|
211
252
|
tried yet", not "finished" — say what to tap and keep listening.
|
|
212
|
-
3. **A capture ends
|
|
213
|
-
|
|
253
|
+
3. **A console capture ends when the app process is confirmed gone.** Its syslog
|
|
254
|
+
companion is stopped too. A standalone `syslog` capture is not bound to the
|
|
255
|
+
app's lifetime and keeps reconnecting; stop it explicitly when finished.
|
package/README.md
CHANGED
|
@@ -59,24 +59,24 @@ a session is running therefore has no effect on that session.
|
|
|
59
59
|
|
|
60
60
|
## Claude Code and Codex (MCP)
|
|
61
61
|
|
|
62
|
-
|
|
63
|
-
`
|
|
64
|
-
|
|
65
|
-
|
|
62
|
+
The shared actions reach both clients through MCP. `mcp/server.ts` loads
|
|
63
|
+
`index.ts` with a stub host and serves the tool it registers, so it exposes the
|
|
64
|
+
same actions and arguments as the pi extension rather than a parallel
|
|
65
|
+
implementation. Claude Code can also load the optional native display below.
|
|
66
66
|
|
|
67
67
|
### Set up (once per machine)
|
|
68
68
|
|
|
69
69
|
```bash
|
|
70
70
|
npm i -g xcodebug@latest # installs the latest published release
|
|
71
71
|
codex mcp add xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
|
|
72
|
-
claude mcp add xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
|
|
72
|
+
claude mcp add --scope user xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
|
|
73
73
|
```
|
|
74
74
|
|
|
75
75
|
Working from a checkout instead? Point both at `mcp/server.ts` in the repo:
|
|
76
76
|
|
|
77
77
|
```bash
|
|
78
78
|
codex mcp add xcodebug -- bun /path/to/xcodebug/mcp/server.ts
|
|
79
|
-
claude mcp add xcodebug -- bun /path/to/xcodebug/mcp/server.ts
|
|
79
|
+
claude mcp add --scope user xcodebug -- bun /path/to/xcodebug/mcp/server.ts
|
|
80
80
|
```
|
|
81
81
|
|
|
82
82
|
Bun is required ([bun.sh](https://bun.sh)). The sources are TypeScript, and Node
|
|
@@ -92,6 +92,51 @@ codex mcp list # xcodebug bun …
|
|
|
92
92
|
claude mcp list # xcodebug: … ✔ Connected
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
+
### Install the manual entry point
|
|
96
|
+
|
|
97
|
+
Connecting MCP makes the tool available to the model; it does not register a
|
|
98
|
+
`/xcodebug` command in either client. The shared
|
|
99
|
+
[xcodebug skill](skills/xcodebug/SKILL.md) adds an explicit entry point:
|
|
100
|
+
`/xcodebug` in Claude Code, `$xcodebug` in Codex, or Codex's `/skills` picker.
|
|
101
|
+
|
|
102
|
+
Both clients can read the same skill directory through user-level symlinks:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
XCODEBUG_DIR="/absolute/path/to/xcodebug" # a checkout containing the skill
|
|
106
|
+
# For an npm package that includes the skill, use this instead:
|
|
107
|
+
# XCODEBUG_DIR="$(npm root -g)/xcodebug"
|
|
108
|
+
|
|
109
|
+
(
|
|
110
|
+
source="$XCODEBUG_DIR/skills/xcodebug"
|
|
111
|
+
test -f "$source/SKILL.md" || { printf 'Skill not found: %s\n' "$source/SKILL.md" >&2; exit 1; }
|
|
112
|
+
for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
|
|
113
|
+
if test -e "$dest" || test -L "$dest"; then
|
|
114
|
+
if ! test -L "$dest" || ! test "$dest" -ef "$source"; then
|
|
115
|
+
printf 'Existing skill path: %s; inspect it before installing.\n' "$dest" >&2
|
|
116
|
+
exit 1
|
|
117
|
+
fi
|
|
118
|
+
fi
|
|
119
|
+
done
|
|
120
|
+
mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills" || exit 1
|
|
121
|
+
for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
|
|
122
|
+
test -L "$dest" || ln -s "$source" "$dest" || exit 1
|
|
123
|
+
done
|
|
124
|
+
)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
If the installed package does not contain `skills/xcodebug/SKILL.md`, use a
|
|
128
|
+
checkout that contains it. The commands check both target paths before installing,
|
|
129
|
+
skip symlinks already pointing to this skill, and stop on other existing files,
|
|
130
|
+
directories or symlinks, including broken links.
|
|
131
|
+
Keep the checkout or npm package at the linked path. Updating that source updates
|
|
132
|
+
the shared skill for both clients.
|
|
133
|
+
|
|
134
|
+
Start a new Claude Code or Codex session after installing. The skill uses the
|
|
135
|
+
MCP connection already configured above; it does not start a separate server or
|
|
136
|
+
replace the native pi command. Both manual and model-selected invocation remain
|
|
137
|
+
available. See the clients' [Claude Code skill documentation](https://code.claude.com/docs/en/skills)
|
|
138
|
+
and [Codex skill documentation](https://learn.chatgpt.com/docs/build-skills).
|
|
139
|
+
|
|
95
140
|
### Use
|
|
96
141
|
|
|
97
142
|
Start the client **in the project directory**. The server inherits its cwd, and
|
|
@@ -102,7 +147,32 @@ cd ~/myapp # holds the .xcworkspace or .xcodeproj
|
|
|
102
147
|
codex # or: claude
|
|
103
148
|
```
|
|
104
149
|
|
|
105
|
-
|
|
150
|
+
Enter these in the client's chat input, not in your shell, after installing the skill:
|
|
151
|
+
|
|
152
|
+
| Operation | Claude Code | Codex |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| Build, install and launch with defaults | `/xcodebug` | `$xcodebug` |
|
|
155
|
+
| Show capture status | `/xcodebug status` | `$xcodebug status` |
|
|
156
|
+
| Check the toolchain | `/xcodebug doctor` | `$xcodebug doctor` |
|
|
157
|
+
| List devices | `/xcodebug devices` | `$xcodebug devices` |
|
|
158
|
+
| Build, install and launch | `/xcodebug launch scheme=MyApp` | `$xcodebug launch scheme=MyApp` |
|
|
159
|
+
| Read filtered logs | `/xcodebug logs grep="Weather Sync" limit=100` | `$xcodebug logs grep="Weather Sync" limit=100` |
|
|
160
|
+
| Wait for an event | `/xcodebug wait match="sync complete" timeoutSeconds=30` | `$xcodebug wait match="sync complete" timeoutSeconds=30` |
|
|
161
|
+
| Rebuild and rerun the last launch | `/xcodebug restart` | `$xcodebug restart` |
|
|
162
|
+
| Stop capture, leave the app running | `/xcodebug stop` | `$xcodebug stop` |
|
|
163
|
+
|
|
164
|
+
A bare skill invocation calls `{"action":"launch"}`: it builds as needed, installs,
|
|
165
|
+
launches and starts capturing using the server's project/device defaults. Use
|
|
166
|
+
`status` to inspect captures without launching. An explicit action maps directly
|
|
167
|
+
to MCP arguments: `logs grep="Weather Sync" limit=100`
|
|
168
|
+
becomes `{"action":"logs","grep":"Weather Sync","limit":100}`. The skill keeps
|
|
169
|
+
quoted strings, numeric and boolean parameters, and JSON arrays/objects in their
|
|
170
|
+
tool-schema types. Add `captureId=...` to read or stop a specific capture.
|
|
171
|
+
|
|
172
|
+
The skill is a model instruction, not a direct RPC command: the model makes the
|
|
173
|
+
tool call and the client's permission rules still apply. It should execute the
|
|
174
|
+
requested action and report its result, rather than just explain how to do it.
|
|
175
|
+
Natural-language goals can also select the skill:
|
|
106
176
|
|
|
107
177
|
```text
|
|
108
178
|
Build and launch on my device, then show me the console.
|
|
@@ -119,21 +189,167 @@ action=status captures, line counts, log paths
|
|
|
119
189
|
action=stop close every running capture
|
|
120
190
|
```
|
|
121
191
|
|
|
192
|
+
If the entry point is missing, check the symlink and restart the client. If the
|
|
193
|
+
skill is found but the MCP tool is missing, check `claude mcp list` or Codex's
|
|
194
|
+
`/mcp`; installing the skill alone does not connect MCP. A `Called
|
|
195
|
+
xcodebug.xcodebug` line is a tool-call record, not a command to type.
|
|
196
|
+
|
|
197
|
+
Capture IDs, cursors and the last launch belong to one MCP server process.
|
|
198
|
+
Claude Code and Codex each start their own server, so a capture created in one
|
|
199
|
+
client cannot be read or stopped in the other. Stay in the same client session
|
|
200
|
+
for `launch` → `logs`/`wait` → `restart`/`stop`.
|
|
201
|
+
|
|
202
|
+
### Claude Code live display
|
|
203
|
+
|
|
204
|
+
The live band needs three separate components: the `xcodebug` MCP server runs
|
|
205
|
+
the actions, the [shared skill](#install-the-manual-entry-point) provides
|
|
206
|
+
`/xcodebug`, and the `xcodebug-live` Mod draws above the prompt. Connecting MCP
|
|
207
|
+
or installing the skill alone does **not** load the Mod.
|
|
208
|
+
|
|
209
|
+
#### Prerequisites
|
|
210
|
+
|
|
211
|
+
Use Claude Code **2.1.323 or later** in an interactive terminal. Choose a checkout
|
|
212
|
+
or installed package that contains both the Mod and the updated MCP adapter:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
XCODEBUG_DIR=/path/to/xcodebug
|
|
216
|
+
# For an npm package containing this feature:
|
|
217
|
+
# XCODEBUG_DIR="$(npm root -g)/xcodebug"
|
|
218
|
+
claude --version
|
|
219
|
+
test -f "$XCODEBUG_DIR/claude/.claude-plugin/plugin.json"
|
|
220
|
+
test -f "$XCODEBUG_DIR/mcp/server.ts"
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
If either file check fails, use a checkout containing the Mod and its updated
|
|
224
|
+
MCP adapter. Keep the MCP registration named `xcodebug` and point it at
|
|
225
|
+
`mcp/server.ts` from this same
|
|
226
|
+
root, using Bun. Follow [Set up](#set-up-once-per-machine) to register it, or
|
|
227
|
+
inspect an existing registration with `claude mcp get xcodebug`.
|
|
228
|
+
|
|
229
|
+
#### Install once for ordinary Claude sessions
|
|
230
|
+
|
|
231
|
+
Claude loads personal skills-directory plugins on startup. The display plugin
|
|
232
|
+
uses its own path, separate from the `xcodebug` skill. Run this in your shell
|
|
233
|
+
after setting `XCODEBUG_DIR` above:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
(
|
|
237
|
+
source="$XCODEBUG_DIR/claude"
|
|
238
|
+
dest="$HOME/.claude/skills/xcodebug-live"
|
|
239
|
+
test -f "$source/.claude-plugin/plugin.json" || {
|
|
240
|
+
printf 'Missing Mod manifest: %s\n' "$source" >&2
|
|
241
|
+
exit 1
|
|
242
|
+
}
|
|
243
|
+
if test -e "$dest" || test -L "$dest"; then
|
|
244
|
+
test -L "$dest" && test "$dest" -ef "$source" || {
|
|
245
|
+
printf 'Existing plugin path: %s\n' "$dest" >&2
|
|
246
|
+
exit 1
|
|
247
|
+
}
|
|
248
|
+
else
|
|
249
|
+
mkdir -p "$(dirname "$dest")" && ln -s "$source" "$dest" || exit 1
|
|
250
|
+
fi
|
|
251
|
+
)
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
This skips a correct existing link and refuses to overwrite another file,
|
|
255
|
+
directory, wrong link or broken link. Keep the source directory in place.
|
|
256
|
+
Check discovery, then start a new session normally:
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
claude plugin list # xcodebug-live@skills-dir, enabled
|
|
260
|
+
claude
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
If this plugin was previously disabled, enable it with
|
|
264
|
+
`claude plugin enable xcodebug-live@skills-dir`. In the new session, `/plugin`
|
|
265
|
+
should list it and `/mcp` should show `xcodebug` connected. The official
|
|
266
|
+
[personal plugin loading rules](https://code.claude.com/docs/en/plugins/create#make-a-plugin-load-in-every-session)
|
|
267
|
+
describe this installation mechanism.
|
|
268
|
+
|
|
269
|
+
#### Use and expected display
|
|
270
|
+
|
|
271
|
+
From your app's working directory, use the installed skill in the same Claude
|
|
272
|
+
session:
|
|
273
|
+
|
|
274
|
+
```text
|
|
275
|
+
/xcodebug launch scheme=MyApp
|
|
276
|
+
/xcodebug status
|
|
277
|
+
/xcodebug logs limit=100
|
|
278
|
+
/xcodebug stop
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
During build, install, launch, and the rebuild within `restart`, the band shows
|
|
282
|
+
the current phase and elapsed time. An operation's phase takes priority over
|
|
283
|
+
an existing capture; capture continues in the background. When the operation
|
|
284
|
+
finishes, fails, or is cancelled, the band returns to the running capture's
|
|
285
|
+
line count and latest four log lines.
|
|
286
|
+
|
|
287
|
+
It refreshes every second, between turns too, from a build, install, launch,
|
|
288
|
+
restart, syslog or await call until no operation or capture is running, then
|
|
289
|
+
clears and stops reading. A session that starts or reloads the Mod reads once
|
|
290
|
+
and resumes a capture already running. Calls that only read or end something
|
|
291
|
+
(`doctor`, `devices`, `changes`, `status`, `logs`, `wait`, `stop`, `terminate`)
|
|
292
|
+
do not start it unless they carry a `command`, and an idle session makes no
|
|
293
|
+
reads. An empty band is normal in
|
|
294
|
+
that idle state. Build
|
|
295
|
+
percentages are estimates; installation shows elapsed time, not an installation
|
|
296
|
+
percentage. These lines are displayed to you without entering model context
|
|
297
|
+
or starting model turns; use `logs`/`wait` when Claude needs to analyze them.
|
|
298
|
+
|
|
299
|
+
The Mod calls the read-only `xcodebug_ui` tool on the existing connection once
|
|
300
|
+
when a display starts. That in-memory read bypasses the action queue, so a
|
|
301
|
+
build or `wait` cannot block it. A tool call runs the session's `PreToolUse`
|
|
302
|
+
and `PostToolUse` hooks, so the reads after it come from a file instead: the
|
|
303
|
+
server keeps the same snapshot in `~/.xcodebug/ui/<pid>.json`, names it in the
|
|
304
|
+
`xcodebug_ui` answer and removes it when it exits; one left by a server that
|
|
305
|
+
was killed is removed by the next server to start. Each call that starts a
|
|
306
|
+
display asks the server again, as does a file that is missing or stops
|
|
307
|
+
changing; with an older server that names no file the Mod calls the tool on
|
|
308
|
+
every read. After three failed reads in a row it
|
|
309
|
+
stops and clears the band until the next such call. Reading does not change the
|
|
310
|
+
active capture or log cursors, and request progress still stops when its
|
|
311
|
+
originating call returns. No second server is started. The Mod leaves an
|
|
312
|
+
existing statusLine alone;
|
|
313
|
+
Codex does not load this Claude-only Mod.
|
|
314
|
+
|
|
315
|
+
#### If the band is missing
|
|
316
|
+
|
|
317
|
+
1. Run `claude plugin list` and check `/plugin` in the affected session.
|
|
318
|
+
`xcodebug-live` must be loaded; seeing the `/xcodebug` skill or a connected
|
|
319
|
+
MCP server does not establish that. Check `/plugin`'s Errors tab if loading
|
|
320
|
+
failed. Safe mode, disabled Mods/hooks or managed settings can prevent it.
|
|
321
|
+
2. Check `/mcp` for the server named exactly `xcodebug`. An unavailable band or
|
|
322
|
+
unknown `xcodebug_ui` tool usually means a missing connection or an older
|
|
323
|
+
adapter. Inspect `claude mcp get xcodebug` to check the path.
|
|
324
|
+
3. Use `/xcodebug status` to check that a capture is running in this session.
|
|
325
|
+
Captures in another client/session cannot populate this band's snapshot.
|
|
326
|
+
With no running capture or published phase, the band is intentionally empty.
|
|
327
|
+
4. After updating the package, changing the server path or installing the Mod,
|
|
328
|
+
restart Claude so both components load together. `/reload-plugins` can reload
|
|
329
|
+
the Mod's files but does not restart the existing MCP server. `-p` sessions
|
|
330
|
+
do not draw the band.
|
|
331
|
+
|
|
332
|
+
To disable the persistent display, run
|
|
333
|
+
`claude plugin disable xcodebug-live@skills-dir` and restart Claude; enable it
|
|
334
|
+
again with the matching `enable` command. Capturing and the shared skill
|
|
335
|
+
remain available without the display.
|
|
336
|
+
|
|
122
337
|
### What differs from pi
|
|
123
338
|
|
|
124
339
|
| | pi / omp / omo | Claude Code / Codex |
|
|
125
340
|
|---|---|---|
|
|
126
341
|
| how the tool is exposed | registered in-process | MCP server process |
|
|
127
|
-
|
|
|
128
|
-
|
|
|
342
|
+
| manual entry point | native `/xcodebug` | shared skill: `/xcodebug` in Claude, `$xcodebug` in Codex |
|
|
343
|
+
| status line, widget | yes | Claude: optional live Mod above; otherwise request progress when rendered |
|
|
344
|
+
| `push` | mirrors new lines into the session | `off` only; `context` and `wake` refused |
|
|
129
345
|
| capture state | in the session | in the server process |
|
|
130
346
|
| lifetime | the session | the client process |
|
|
131
347
|
|
|
132
|
-
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
348
|
+
- **The adapter refuses `push=context` and `push=wake`.** It does not implement
|
|
349
|
+
background log delivery into model context. Read with `action=logs` or
|
|
350
|
+
`action=wait`; these pull reads are separate from the Claude Mod's user-visible
|
|
351
|
+
display. Cursor reads exclude earlier indices, but a limited read can omit
|
|
352
|
+
lines; see [Reading logs from a cursor](#reading-logs-from-a-cursor).
|
|
137
353
|
- **Captures end with the client.** The server is a child of Codex/Claude, so
|
|
138
354
|
quitting the client stops the bridges. Relaunch next session.
|
|
139
355
|
|
|
@@ -283,8 +499,10 @@ run. Set `installPods=false` to skip it deliberately.
|
|
|
283
499
|
```
|
|
284
500
|
|
|
285
501
|
Detects the workspace from the current directory (walking up, so a nested cwd
|
|
286
|
-
works), rebuilds when the tree changed, installs, launches, and
|
|
287
|
-
|
|
502
|
+
works), rebuilds when the tree changed, installs, launches, and starts capturing.
|
|
503
|
+
Native pi/omp can push logs into the conversation; Claude Code and Codex use
|
|
504
|
+
`logs`/`wait` pull reads through MCP. The optional Claude Mod displays a console
|
|
505
|
+
tail to the user, not to the model. The phrase is a goal, not a log filter.
|
|
288
506
|
|
|
289
507
|
- **CocoaPods vs plain project** is decided by `Podfile`/`Podfile.lock`: a
|
|
290
508
|
CocoaPods project uses its `.xcworkspace`, a plain project its `.xcodeproj`.
|
|
@@ -474,32 +692,36 @@ app (a curl, a fixture import, a codegen step) has no such constraint.
|
|
|
474
692
|
|
|
475
693
|
Verification is a loop: run, read the log, conclude, stop, edit the code, run
|
|
476
694
|
again. Each `launch` or `syslog` retires the previous cycle's capture for that same
|
|
477
|
-
app **before** the new bridge starts,
|
|
478
|
-
|
|
479
|
-
|
|
695
|
+
app **before** the new bridge starts, avoiding duplicate capture streams for that
|
|
696
|
+
app; other apps' captures are preserved, so several apps can be debugged in one
|
|
697
|
+
session.
|
|
480
698
|
|
|
481
|
-
- **Stop once the log has answered the question.** Keeping a capture alive
|
|
482
|
-
|
|
699
|
+
- **Stop once the log has answered the question.** Keeping a capture alive consumes
|
|
700
|
+
resources; with native push enabled, it also keeps sending log batches.
|
|
483
701
|
- **Do not stop while the user has not acted yet.** Silence there means nothing
|
|
484
702
|
has been tried, not that the run is over: say what to do on the phone and keep
|
|
485
703
|
listening.
|
|
486
|
-
- A capture ends
|
|
487
|
-
|
|
704
|
+
- A console capture ends when the app process is confirmed gone, and its syslog
|
|
705
|
+
companion is stopped too. A standalone `syslog` capture is not bound to the
|
|
706
|
+
app's lifetime and keeps reconnecting; stop it explicitly when finished.
|
|
488
707
|
- A dropped console bridge otherwise reconnects indefinitely. An inconclusive
|
|
489
708
|
probe (USB unplugged, `devicectl` timeout) is **not** treated as "the app exited".
|
|
490
709
|
- `idevicesyslog` can go silent with its process still alive; a 30s watchdog kills
|
|
491
710
|
it and the exit hook reattaches. Reattachment has exactly one owner, so the
|
|
492
711
|
watchdog and the exit hook can never both assume the other is handling it.
|
|
493
|
-
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
712
|
+
- In native pi/omp push modes, after 60s with no new lines the run says so once
|
|
713
|
+
and keeps capturing. MCP users use `logs`/`wait` to inspect quiet captures.
|
|
714
|
+
- In pi/omp, a footer line and a widget above the editor show the live state,
|
|
715
|
+
e.g. `📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus
|
|
716
|
+
recent log lines and the number of streaming channels. Claude Code can instead
|
|
717
|
+
load the [live display Mod](#claude-code-live-display).
|
|
718
|
+
- Native pushed log batches are **hidden from the transcript** (`display: false`)
|
|
719
|
+
but delivered to the model, subject to the per-batch limit. MCP does not push
|
|
720
|
+
batches; the Claude Mod's display does not add logs to model context.
|
|
721
|
+
- `/xcodebug stop` (or `action=stop`) without `captureId` closes **every running
|
|
722
|
+
capture**. An ID scopes the stop to that target; a console primary's syslog
|
|
723
|
+
companion is stopped too. Other apps' captures are unaffected by a targeted
|
|
724
|
+
stop. `keepApp=false` also terminates the app.
|
|
503
725
|
|
|
504
726
|
## Usage
|
|
505
727
|
|
|
@@ -585,7 +807,8 @@ only comes from the console bridge, per the table at the top.
|
|
|
585
807
|
|
|
586
808
|
### Pushing logs into the conversation
|
|
587
809
|
|
|
588
|
-
`push` controls whether new lines are mirrored into the session
|
|
810
|
+
In native pi/omp, `push` controls whether new lines are mirrored into the session.
|
|
811
|
+
The MCP adapter accepts only `off`; Claude Code and Codex use `logs`/`wait`.
|
|
589
812
|
|
|
590
813
|
- `context` (default) — new lines are queued for the next turn (does not start one).
|
|
591
814
|
- `off` — pull with `logs`/`wait` only.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
// Poll the existing connection, not a second server with different captures.
|
|
2
|
+
const SERVER = 'xcodebug';
|
|
3
|
+
// A literal, not built from SERVER: `claude plugin validate` reads the matcher statically.
|
|
4
|
+
const ACTION_TOOL = 'mcp__xcodebug__xcodebug';
|
|
5
|
+
const UI_TOOL = 'xcodebug_ui';
|
|
6
|
+
const POLL_MS = 1000;
|
|
7
|
+
// One failed read may be a blip; a server that stays down is not polled forever.
|
|
8
|
+
const MAX_FAILURES = 3;
|
|
9
|
+
const MAX_ERROR_CHARS = 160;
|
|
10
|
+
// The server repaints once a second while it shows anything, so a file whose
|
|
11
|
+
// `seq` stands still this many reads running belongs to a server that is gone.
|
|
12
|
+
const MAX_STALE_READS = 5;
|
|
13
|
+
// Actions that neither build nor start a capture, so they paint nothing new
|
|
14
|
+
// unless they carry a `command`, which runs as a phase of its own.
|
|
15
|
+
// Listed as exclusions so that an action added later shows by default.
|
|
16
|
+
const QUIET_ACTIONS = new Set(['doctor', 'devices', 'changes', 'status', 'logs', 'wait', 'stop', 'terminate']);
|
|
17
|
+
|
|
18
|
+
let rows = [];
|
|
19
|
+
let polling = false;
|
|
20
|
+
let timer;
|
|
21
|
+
let calls = 0;
|
|
22
|
+
let failures = 0;
|
|
23
|
+
let file;
|
|
24
|
+
let seq;
|
|
25
|
+
let stale = 0;
|
|
26
|
+
|
|
27
|
+
// A tool call runs the session's tool hooks, so only the first read of an
|
|
28
|
+
// activity asks the server; it names the file the server keeps the same
|
|
29
|
+
// snapshot in, and the reads after that come from there.
|
|
30
|
+
async function readServer($) {
|
|
31
|
+
const result = await $.mcp.call(SERVER, UI_TOOL, {});
|
|
32
|
+
if (result.isError) throw new Error(result.content.find(c => c.type === 'text')?.text ?? 'UI read failed');
|
|
33
|
+
const snapshot = JSON.parse(result.content.find(c => c.type === 'text')?.text ?? '{}');
|
|
34
|
+
// A server from before the file existed names none, and is asked every time.
|
|
35
|
+
file = snapshot.file;
|
|
36
|
+
seq = snapshot.seq;
|
|
37
|
+
stale = 0;
|
|
38
|
+
return snapshot;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async function readFile($) {
|
|
42
|
+
if (!file) return undefined;
|
|
43
|
+
try {
|
|
44
|
+
const snapshot = JSON.parse(await $.fs.read(file));
|
|
45
|
+
stale = snapshot.seq === seq ? stale + 1 : 0;
|
|
46
|
+
seq = snapshot.seq;
|
|
47
|
+
if (stale < MAX_STALE_READS) return snapshot;
|
|
48
|
+
} catch {
|
|
49
|
+
// Removed when its server exited; the server is asked instead, below.
|
|
50
|
+
}
|
|
51
|
+
file = undefined;
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
// The timer lives only while there is something to show: it ends once the
|
|
56
|
+
// server empties its snapshot (no build, no capture) or keeps failing.
|
|
57
|
+
function watch($) {
|
|
58
|
+
timer ??= $.clock.every(POLL_MS, async () => {
|
|
59
|
+
if (polling) return;
|
|
60
|
+
polling = true;
|
|
61
|
+
try {
|
|
62
|
+
const snapshot = await readFile($) ?? await readServer($);
|
|
63
|
+
rows = snapshot.rows?.length ? snapshot.rows : snapshot.status ? [snapshot.status] : [];
|
|
64
|
+
failures = 0;
|
|
65
|
+
} catch (error) {
|
|
66
|
+
rows = ['Xcodebug · live display unavailable', String(error.message ?? error).slice(0, MAX_ERROR_CHARS)];
|
|
67
|
+
failures += 1;
|
|
68
|
+
} finally {
|
|
69
|
+
polling = false;
|
|
70
|
+
}
|
|
71
|
+
// A call still in flight may not have painted its first status yet.
|
|
72
|
+
if (calls === 0 && (rows.length === 0 || failures >= MAX_FAILURES)) {
|
|
73
|
+
timer?.cancel();
|
|
74
|
+
timer = undefined;
|
|
75
|
+
rows = [];
|
|
76
|
+
failures = 0;
|
|
77
|
+
// The next activity may meet a restarted server, with a file of its own.
|
|
78
|
+
file = undefined;
|
|
79
|
+
}
|
|
80
|
+
$.ui.invalidate('ui.render');
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function register(on) {
|
|
85
|
+
// A capture outlives the module: a reload or a resumed session finds it here.
|
|
86
|
+
on('session.start', async ($, e, next) => {
|
|
87
|
+
watch($);
|
|
88
|
+
return next(e);
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
on('tool.call', { tool: ACTION_TOOL }, async ($, e, next) => {
|
|
92
|
+
if (QUIET_ACTIONS.has(e.action) && !e.command) return next(e);
|
|
93
|
+
// The server may have been replaced since the file was named; one killed
|
|
94
|
+
// while it showed something leaves that file behind, still naming it.
|
|
95
|
+
file = undefined;
|
|
96
|
+
watch($);
|
|
97
|
+
calls += 1;
|
|
98
|
+
try {
|
|
99
|
+
return await next(e);
|
|
100
|
+
} finally {
|
|
101
|
+
calls -= 1;
|
|
102
|
+
}
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
|
|
106
|
+
if (rows.length === 0) return next(e);
|
|
107
|
+
const { Box, Text } = $.ui.resolve(e);
|
|
108
|
+
return Box({
|
|
109
|
+
flexDirection: 'column',
|
|
110
|
+
children: rows.map(text => Text({ children: [text] })),
|
|
111
|
+
});
|
|
112
|
+
});
|
|
113
|
+
}
|
|
@@ -0,0 +1,321 @@
|
|
|
1
|
+
import { expect, mock, test } from 'claude-code/testing'
|
|
2
|
+
|
|
3
|
+
const BAND = {
|
|
4
|
+
plugin: 'xcodebug-live', component: 'AbovePrompt', surface: 'terminal',
|
|
5
|
+
viewport: { columns: 120, rows: 40 }, props: {},
|
|
6
|
+
} as const
|
|
7
|
+
|
|
8
|
+
const TOOL = 'mcp__xcodebug__xcodebug'
|
|
9
|
+
const LAUNCH = { tool: TOOL, action: 'launch' } as const
|
|
10
|
+
const QUIET_ACTIONS = ['doctor', 'devices', 'changes', 'status', 'logs', 'wait', 'stop', 'terminate']
|
|
11
|
+
const START = { surface: 'terminal', isInteractive: true, cwd: '/work' } as const
|
|
12
|
+
|
|
13
|
+
const reply = (snapshot: unknown) => ({ value: { content: [{ type: 'text', text: JSON.stringify(snapshot) }] } })
|
|
14
|
+
const failure = { value: { isError: true, content: [{ type: 'text', text: 'server unavailable' }] } }
|
|
15
|
+
|
|
16
|
+
test('an idle session reads the display once, then never again', async ($, on) => {
|
|
17
|
+
const clock = mock.clock(on)
|
|
18
|
+
let reads = 0
|
|
19
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
20
|
+
on('mcp.call', () => {
|
|
21
|
+
reads += 1
|
|
22
|
+
return reply({ rows: [] })
|
|
23
|
+
})
|
|
24
|
+
await $.session.start(START)
|
|
25
|
+
await clock.advance(5000)
|
|
26
|
+
expect(reads).toBe(1)
|
|
27
|
+
})
|
|
28
|
+
|
|
29
|
+
test('a capture already running when the session starts is shown', async ($, on) => {
|
|
30
|
+
const clock = mock.clock(on)
|
|
31
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
32
|
+
on('mcp.call', () => reply({ rows: ['capturing · 9 lines', 'earlier log'] }))
|
|
33
|
+
await $.session.start(START)
|
|
34
|
+
const ui = await $.ui.mount(BAND)
|
|
35
|
+
await clock.advance(1000)
|
|
36
|
+
expect(await ui.find({ type: 'Text', text: 'earlier log' })).toBeDefined()
|
|
37
|
+
})
|
|
38
|
+
|
|
39
|
+
test('an xcodebug call starts the display, and an empty snapshot ends it', async ($, on) => {
|
|
40
|
+
const clock = mock.clock(on)
|
|
41
|
+
let snapshot: { rows: string[] } = { rows: [] }
|
|
42
|
+
let reads = 0
|
|
43
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
44
|
+
on('tool.call', () => ({ result: {} }))
|
|
45
|
+
on('mcp.call', ($, e) => {
|
|
46
|
+
expect(e.server).toBe('xcodebug')
|
|
47
|
+
expect(e.tool).toBe('xcodebug_ui')
|
|
48
|
+
reads += 1
|
|
49
|
+
return reply(snapshot)
|
|
50
|
+
})
|
|
51
|
+
await $.session.start(START)
|
|
52
|
+
await clock.advance(1000)
|
|
53
|
+
reads = 0
|
|
54
|
+
|
|
55
|
+
snapshot = { rows: ['capturing · 1 line', 'first log'] }
|
|
56
|
+
await $.tool.call(LAUNCH)
|
|
57
|
+
const ui = await $.ui.mount(BAND)
|
|
58
|
+
await clock.advance(1000)
|
|
59
|
+
expect(await ui.find({ type: 'Text', text: 'first log' })).toBeDefined()
|
|
60
|
+
snapshot = { rows: ['capturing · 2 lines', 'second log'] }
|
|
61
|
+
await clock.advance(1000)
|
|
62
|
+
expect(await ui.find({ type: 'Text', text: 'second log' })).toBeDefined()
|
|
63
|
+
expect(await ui.find({ type: 'Text', text: 'first log' })).toBeUndefined()
|
|
64
|
+
snapshot = { rows: [] }
|
|
65
|
+
await clock.advance(1000)
|
|
66
|
+
expect(await ui.find({ type: 'Text', text: /capturing/ })).toBeUndefined()
|
|
67
|
+
expect(reads).toBe(3)
|
|
68
|
+
await clock.advance(5000)
|
|
69
|
+
expect(reads).toBe(3)
|
|
70
|
+
|
|
71
|
+
snapshot = { rows: ['capturing · 1 line', 'relaunched'] }
|
|
72
|
+
await $.tool.call(LAUNCH)
|
|
73
|
+
await clock.advance(1000)
|
|
74
|
+
expect(await ui.find({ type: 'Text', text: 'relaunched' })).toBeDefined()
|
|
75
|
+
})
|
|
76
|
+
|
|
77
|
+
test('a call still running keeps the display reading an empty snapshot', async ($, on) => {
|
|
78
|
+
const clock = mock.clock(on)
|
|
79
|
+
let reads = 0
|
|
80
|
+
let finish: (result: unknown) => void = () => {}
|
|
81
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
82
|
+
on('tool.call', () => new Promise(resolve => { finish = resolve }))
|
|
83
|
+
on('mcp.call', () => {
|
|
84
|
+
reads += 1
|
|
85
|
+
return reply({ rows: [] })
|
|
86
|
+
})
|
|
87
|
+
await $.session.start(START)
|
|
88
|
+
await clock.advance(1000)
|
|
89
|
+
reads = 0
|
|
90
|
+
|
|
91
|
+
const call = $.tool.call(LAUNCH)
|
|
92
|
+
await clock.advance(4000)
|
|
93
|
+
expect(reads).toBe(4)
|
|
94
|
+
finish({ result: {} })
|
|
95
|
+
await call
|
|
96
|
+
await clock.advance(5000)
|
|
97
|
+
expect(reads).toBe(5)
|
|
98
|
+
})
|
|
99
|
+
|
|
100
|
+
test('actions that paint nothing do not start the display', async ($, on) => {
|
|
101
|
+
const clock = mock.clock(on)
|
|
102
|
+
let reads = 0
|
|
103
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
104
|
+
on('tool.call', () => ({ result: {} }))
|
|
105
|
+
on('mcp.call', () => {
|
|
106
|
+
reads += 1
|
|
107
|
+
return reply({ rows: [] })
|
|
108
|
+
})
|
|
109
|
+
await $.session.start(START)
|
|
110
|
+
await clock.advance(1000)
|
|
111
|
+
reads = 0
|
|
112
|
+
|
|
113
|
+
for (const action of QUIET_ACTIONS) {
|
|
114
|
+
await $.tool.call({ tool: TOOL, action })
|
|
115
|
+
await clock.advance(2000)
|
|
116
|
+
}
|
|
117
|
+
expect(reads).toBe(0)
|
|
118
|
+
})
|
|
119
|
+
|
|
120
|
+
test('a quiet action that carries a command shows its phase, then stops', async ($, on) => {
|
|
121
|
+
const clock = mock.clock(on)
|
|
122
|
+
let snapshot: { rows: string[] } = { rows: [] }
|
|
123
|
+
let reads = 0
|
|
124
|
+
let finish: (result: unknown) => void = () => {}
|
|
125
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
126
|
+
on('tool.call', () => new Promise(resolve => { finish = resolve }))
|
|
127
|
+
on('mcp.call', () => {
|
|
128
|
+
reads += 1
|
|
129
|
+
return reply(snapshot)
|
|
130
|
+
})
|
|
131
|
+
await $.session.start(START)
|
|
132
|
+
await clock.advance(1000)
|
|
133
|
+
reads = 0
|
|
134
|
+
|
|
135
|
+
snapshot = { rows: ['Xcodebug · running', ' command: sleep 3'] }
|
|
136
|
+
const call = $.tool.call({ tool: TOOL, action: 'changes', command: 'sleep 3' })
|
|
137
|
+
const ui = await $.ui.mount(BAND)
|
|
138
|
+
await clock.advance(1000)
|
|
139
|
+
expect(await ui.find({ type: 'Text', text: /command: sleep 3/ })).toBeDefined()
|
|
140
|
+
snapshot = { rows: [] }
|
|
141
|
+
finish({ result: {} })
|
|
142
|
+
await call
|
|
143
|
+
await clock.advance(1000)
|
|
144
|
+
expect(await ui.find({ type: 'Text', text: /command: sleep 3/ })).toBeUndefined()
|
|
145
|
+
expect(reads).toBe(2)
|
|
146
|
+
await clock.advance(5000)
|
|
147
|
+
expect(reads).toBe(2)
|
|
148
|
+
})
|
|
149
|
+
|
|
150
|
+
test('a failed UI read removes stale logs and recovers on the next timer', async ($, on) => {
|
|
151
|
+
const clock = mock.clock(on)
|
|
152
|
+
let failed = false
|
|
153
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
154
|
+
on('tool.call', () => ({ result: {} }))
|
|
155
|
+
on('mcp.call', () => failed ? failure : reply({ rows: ['current log'] }))
|
|
156
|
+
await $.session.start(START)
|
|
157
|
+
await $.tool.call(LAUNCH)
|
|
158
|
+
const ui = await $.ui.mount(BAND)
|
|
159
|
+
await clock.advance(1000)
|
|
160
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeDefined()
|
|
161
|
+
failed = true
|
|
162
|
+
await clock.advance(1000)
|
|
163
|
+
expect(await ui.find({ type: 'Text', text: /live display unavailable/ })).toBeDefined()
|
|
164
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeUndefined()
|
|
165
|
+
failed = false
|
|
166
|
+
await clock.advance(1000)
|
|
167
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeDefined()
|
|
168
|
+
expect(await ui.find({ type: 'Text', text: /unavailable/ })).toBeUndefined()
|
|
169
|
+
// Failures apart from each other never add up to giving up.
|
|
170
|
+
failed = true
|
|
171
|
+
await clock.advance(2000)
|
|
172
|
+
failed = false
|
|
173
|
+
await clock.advance(1000)
|
|
174
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeDefined()
|
|
175
|
+
})
|
|
176
|
+
|
|
177
|
+
test('a server that stays down is given up on, and the band clears', async ($, on) => {
|
|
178
|
+
const clock = mock.clock(on)
|
|
179
|
+
let reads = 0
|
|
180
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
181
|
+
on('tool.call', () => ({ result: {} }))
|
|
182
|
+
on('mcp.call', () => {
|
|
183
|
+
reads += 1
|
|
184
|
+
return failure
|
|
185
|
+
})
|
|
186
|
+
await $.session.start(START)
|
|
187
|
+
await $.tool.call(LAUNCH)
|
|
188
|
+
const ui = await $.ui.mount(BAND)
|
|
189
|
+
await clock.advance(1000)
|
|
190
|
+
expect(await ui.find({ type: 'Text', text: /live display unavailable/ })).toBeDefined()
|
|
191
|
+
await clock.advance(30000)
|
|
192
|
+
expect(reads).toBe(3)
|
|
193
|
+
expect(await ui.find({ type: 'Text', text: /unavailable/ })).toBeUndefined()
|
|
194
|
+
})
|
|
195
|
+
|
|
196
|
+
const FILE = '/agent/ui/42.json'
|
|
197
|
+
|
|
198
|
+
test('one tool call per activity: later reads come from the snapshot file', async ($, on) => {
|
|
199
|
+
const clock = mock.clock(on)
|
|
200
|
+
let snapshot = { rows: [] as string[], seq: 0 }
|
|
201
|
+
let toolReads = 0
|
|
202
|
+
let fileReads = 0
|
|
203
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
204
|
+
on('tool.call', () => ({ result: {} }))
|
|
205
|
+
on('mcp.call', () => {
|
|
206
|
+
toolReads += 1
|
|
207
|
+
return reply({ ...snapshot, file: FILE })
|
|
208
|
+
})
|
|
209
|
+
on('fs.read', ($, e) => {
|
|
210
|
+
expect(e.path).toBe(FILE)
|
|
211
|
+
fileReads += 1
|
|
212
|
+
return { value: JSON.stringify(snapshot) }
|
|
213
|
+
})
|
|
214
|
+
await $.session.start(START)
|
|
215
|
+
await clock.advance(1000)
|
|
216
|
+
toolReads = 0
|
|
217
|
+
fileReads = 0
|
|
218
|
+
|
|
219
|
+
const ui = await $.ui.mount(BAND)
|
|
220
|
+
for (const round of ['first', 'second']) {
|
|
221
|
+
snapshot = { rows: [`capturing · ${round}`], seq: snapshot.seq + 1 }
|
|
222
|
+
await $.tool.call(LAUNCH)
|
|
223
|
+
await clock.advance(1000)
|
|
224
|
+
expect(await ui.find({ type: 'Text', text: `capturing · ${round}` })).toBeDefined()
|
|
225
|
+
for (let tick = 0; tick < 10; tick++) {
|
|
226
|
+
snapshot = { rows: [`capturing · ${round} · ${tick}`], seq: snapshot.seq + 1 }
|
|
227
|
+
await clock.advance(1000)
|
|
228
|
+
expect(await ui.find({ type: 'Text', text: `capturing · ${round} · ${tick}` })).toBeDefined()
|
|
229
|
+
}
|
|
230
|
+
snapshot = { rows: [], seq: snapshot.seq + 1 }
|
|
231
|
+
await clock.advance(1000)
|
|
232
|
+
expect(await ui.find({ type: 'Text', text: /capturing/ })).toBeUndefined()
|
|
233
|
+
await clock.advance(5000)
|
|
234
|
+
}
|
|
235
|
+
expect(toolReads).toBe(2)
|
|
236
|
+
expect(fileReads).toBe(22)
|
|
237
|
+
})
|
|
238
|
+
|
|
239
|
+
test('a snapshot file that stops changing sends the next read to the server', async ($, on) => {
|
|
240
|
+
const clock = mock.clock(on)
|
|
241
|
+
let toolReads = 0
|
|
242
|
+
let down = false
|
|
243
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
244
|
+
on('tool.call', () => ({ result: {} }))
|
|
245
|
+
on('mcp.call', () => {
|
|
246
|
+
toolReads += 1
|
|
247
|
+
return down ? failure : reply({ rows: ['capturing · stuck'], seq: 7, file: FILE })
|
|
248
|
+
})
|
|
249
|
+
// The server died without clearing its file: same seq on every read.
|
|
250
|
+
on('fs.read', () => ({ value: JSON.stringify({ rows: ['capturing · stuck'], seq: 7 }) }))
|
|
251
|
+
await $.session.start(START)
|
|
252
|
+
await $.tool.call(LAUNCH)
|
|
253
|
+
const ui = await $.ui.mount(BAND)
|
|
254
|
+
await clock.advance(1000)
|
|
255
|
+
toolReads = 0
|
|
256
|
+
down = true
|
|
257
|
+
await clock.advance(4000)
|
|
258
|
+
expect(toolReads).toBe(0)
|
|
259
|
+
expect(await ui.find({ type: 'Text', text: 'capturing · stuck' })).toBeDefined()
|
|
260
|
+
await clock.advance(30000)
|
|
261
|
+
expect(toolReads).toBe(3)
|
|
262
|
+
expect(await ui.find({ type: 'Text', text: /stuck|unavailable/ })).toBeUndefined()
|
|
263
|
+
})
|
|
264
|
+
|
|
265
|
+
test('a snapshot file that cannot be read sends that read to the server', async ($, on) => {
|
|
266
|
+
const clock = mock.clock(on)
|
|
267
|
+
let toolReads = 0
|
|
268
|
+
let gone = false
|
|
269
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
270
|
+
on('tool.call', () => ({ result: {} }))
|
|
271
|
+
on('mcp.call', () => {
|
|
272
|
+
toolReads += 1
|
|
273
|
+
return reply({ rows: [`from the server · ${toolReads}`], seq: toolReads, file: FILE })
|
|
274
|
+
})
|
|
275
|
+
on('fs.read', () => {
|
|
276
|
+
if (gone) throw new Error('ENOENT')
|
|
277
|
+
return { value: JSON.stringify({ rows: ['from the file'], seq: 100 }) }
|
|
278
|
+
})
|
|
279
|
+
await $.session.start(START)
|
|
280
|
+
await $.tool.call(LAUNCH)
|
|
281
|
+
const ui = await $.ui.mount(BAND)
|
|
282
|
+
await clock.advance(2000)
|
|
283
|
+
expect(await ui.find({ type: 'Text', text: 'from the file' })).toBeDefined()
|
|
284
|
+
gone = true
|
|
285
|
+
toolReads = 0
|
|
286
|
+
await clock.advance(1000)
|
|
287
|
+
expect(toolReads).toBe(1)
|
|
288
|
+
expect(await ui.find({ type: 'Text', text: /from the server/ })).toBeDefined()
|
|
289
|
+
expect(await ui.find({ type: 'Text', text: /unavailable/ })).toBeUndefined()
|
|
290
|
+
})
|
|
291
|
+
|
|
292
|
+
test('a call while the display runs asks the server again, in case it was replaced', async ($, on) => {
|
|
293
|
+
const clock = mock.clock(on)
|
|
294
|
+
const OLD = '/agent/ui/1.json'
|
|
295
|
+
const NEW = '/agent/ui/2.json'
|
|
296
|
+
let server = { rows: ['old capture'], seq: 1, file: OLD }
|
|
297
|
+
let oldSeq = 1
|
|
298
|
+
let oldServerRuns = true
|
|
299
|
+
let newSeq = 1
|
|
300
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
301
|
+
on('tool.call', () => ({ result: {} }))
|
|
302
|
+
on('mcp.call', () => reply(server))
|
|
303
|
+
on('fs.read', ($, e) => ({
|
|
304
|
+
value: JSON.stringify(e.path === OLD
|
|
305
|
+
? { rows: ['old capture'], seq: oldServerRuns ? ++oldSeq : oldSeq }
|
|
306
|
+
: { rows: ['new build'], seq: ++newSeq }),
|
|
307
|
+
}))
|
|
308
|
+
await $.session.start(START)
|
|
309
|
+
await $.tool.call(LAUNCH)
|
|
310
|
+
const ui = await $.ui.mount(BAND)
|
|
311
|
+
await clock.advance(3000)
|
|
312
|
+
expect(await ui.find({ type: 'Text', text: 'old capture' })).toBeDefined()
|
|
313
|
+
|
|
314
|
+
// The old server was killed and left its file; the connection now reaches a new one.
|
|
315
|
+
oldServerRuns = false
|
|
316
|
+
server = { rows: ['new build'], seq: 1, file: NEW }
|
|
317
|
+
await $.tool.call(LAUNCH)
|
|
318
|
+
await clock.advance(1000)
|
|
319
|
+
expect(await ui.find({ type: 'Text', text: 'new build' })).toBeDefined()
|
|
320
|
+
expect(await ui.find({ type: 'Text', text: 'old capture' })).toBeUndefined()
|
|
321
|
+
})
|
package/index.ts
CHANGED
|
@@ -767,19 +767,13 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
767
767
|
/**
|
|
768
768
|
* Paint the live verification state: a footer line that is always visible and
|
|
769
769
|
* a widget above the editor with the most recent log lines. Both are cleared
|
|
770
|
-
* when no capture is running, so a finished task leaves no stale chrome.
|
|
770
|
+
* when no operation or capture is running, so a finished task leaves no stale chrome.
|
|
771
771
|
*/
|
|
772
772
|
const refreshStatus = (): void => {
|
|
773
773
|
const ctx = state.uiCtx;
|
|
774
774
|
if (!ctx?.hasUI) return;
|
|
775
|
-
const
|
|
776
|
-
if (
|
|
777
|
-
const phase = state.runPhase;
|
|
778
|
-
if (!phase) {
|
|
779
|
-
ctx.ui.setStatus("xcodebug", undefined);
|
|
780
|
-
ctx.ui.setWidget("xcodebug", undefined);
|
|
781
|
-
return;
|
|
782
|
-
}
|
|
775
|
+
const phase = state.runPhase;
|
|
776
|
+
if (phase) {
|
|
783
777
|
const secs = Math.round((Date.now() - phase.startedAt) / 1000);
|
|
784
778
|
ctx.ui.setStatus("xcodebug", `🔨 xcodebug · ${phase.label} · ${secs}s`);
|
|
785
779
|
ctx.ui.setWidget("xcodebug", ["Xcodebug · running", ` ${phase.label}`, ` ${secs}s`], {
|
|
@@ -787,6 +781,12 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
787
781
|
});
|
|
788
782
|
return;
|
|
789
783
|
}
|
|
784
|
+
const running = [...state.captures.values()].filter((c) => c.running);
|
|
785
|
+
if (running.length === 0) {
|
|
786
|
+
ctx.ui.setStatus("xcodebug", undefined);
|
|
787
|
+
ctx.ui.setWidget("xcodebug", undefined);
|
|
788
|
+
return;
|
|
789
|
+
}
|
|
790
790
|
|
|
791
791
|
// Prefer a channel that is actually pushing: a push=off capture shows no
|
|
792
792
|
// lines in the widget, so featuring it would misreport the run as silent.
|
|
@@ -1560,6 +1560,7 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
1560
1560
|
const device = await resolveDeviceParam(params.device, projectRoot);
|
|
1561
1561
|
const appPath = params.appPath;
|
|
1562
1562
|
if (!appPath) throw new Error("install requires appPath (or use action=build first).");
|
|
1563
|
+
setRunPhase(`installing on ${device.name}`);
|
|
1563
1564
|
const outcome = await installApp(device, appPath, { timeoutMs: (params.timeoutSeconds ?? 180) * 1000, signal });
|
|
1564
1565
|
return {
|
|
1565
1566
|
content: [{ type: "text", text: `${outcome.message}\napp: ${appPath}\ndevice: ${device.name}` }],
|
package/mcp/server.ts
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
* needed (initialize, tools/list, tools/call); the official SDK would add ~97
|
|
19
19
|
* transitive packages to every install, including the pi users who never run MCP.
|
|
20
20
|
*/
|
|
21
|
-
import { readFileSync } from "node:fs";
|
|
21
|
+
import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
22
22
|
import { homedir } from "node:os";
|
|
23
23
|
import { join } from "node:path";
|
|
24
24
|
import { createInterface } from "node:readline";
|
|
@@ -29,7 +29,7 @@ interface ExtensionContextLike {
|
|
|
29
29
|
agentDir: string;
|
|
30
30
|
/** The status ticker in index.ts only runs when this is set. */
|
|
31
31
|
hasUI?: boolean;
|
|
32
|
-
ui: { notify(): void; setStatus(key: string, text?: string): void; setWidget(): void };
|
|
32
|
+
ui: { notify(): void; setStatus(key: string, text?: string): void; setWidget(key: string, rows?: string[]): void };
|
|
33
33
|
}
|
|
34
34
|
|
|
35
35
|
interface ToolResult {
|
|
@@ -96,6 +96,63 @@ if (!registered) {
|
|
|
96
96
|
}
|
|
97
97
|
const tool = registered;
|
|
98
98
|
|
|
99
|
+
// The native Claude mod reads this without joining the mutating action queue.
|
|
100
|
+
// Keep the last repaint alive after tools/call ends; only progress is request-scoped.
|
|
101
|
+
const uiSnapshot: { status?: string; rows: string[] } = { rows: [] };
|
|
102
|
+
|
|
103
|
+
// Every xcodebug_ui call runs the client's tool hooks, so a mod that polled it
|
|
104
|
+
// once a second ran them once a second for as long as a capture lived. The same
|
|
105
|
+
// snapshot goes to a file the mod reads between calls. One file per process:
|
|
106
|
+
// several sessions each run their own server.
|
|
107
|
+
const UI_DIR = join(AGENT_DIR, "ui");
|
|
108
|
+
let uiFile: string | undefined = join(UI_DIR, `${process.pid}.json`);
|
|
109
|
+
// Advances on every repaint, which happens once a second while anything is
|
|
110
|
+
// shown; a reader that sees it stand still knows this process stopped painting.
|
|
111
|
+
let uiSeq = 0;
|
|
112
|
+
|
|
113
|
+
function publishUi(): void {
|
|
114
|
+
if (!uiFile) return;
|
|
115
|
+
uiSeq += 1;
|
|
116
|
+
try {
|
|
117
|
+
mkdirSync(UI_DIR, { recursive: true });
|
|
118
|
+
// Renamed into place so a reader never sees half a snapshot.
|
|
119
|
+
writeFileSync(`${uiFile}.tmp`, JSON.stringify({ ...uiSnapshot, seq: uiSeq }));
|
|
120
|
+
renameSync(`${uiFile}.tmp`, uiFile);
|
|
121
|
+
} catch (error) {
|
|
122
|
+
// A repaint must not take the action down with it. Without the file the
|
|
123
|
+
// mod is told nothing about it and keeps calling xcodebug_ui.
|
|
124
|
+
console.error("xcodebug-mcp: live display file unavailable:", (error as Error).message);
|
|
125
|
+
uiFile = undefined;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
publishUi();
|
|
129
|
+
process.on("exit", () => {
|
|
130
|
+
if (uiFile) rmSync(uiFile, { force: true });
|
|
131
|
+
});
|
|
132
|
+
// Claude Code ends a stdio server with SIGINT. Left to the default, a signal
|
|
133
|
+
// ends the process without the handler above; the exit codes are the shell's.
|
|
134
|
+
process.on("SIGINT", () => process.exit(130));
|
|
135
|
+
process.on("SIGTERM", () => process.exit(143));
|
|
136
|
+
// A server that was killed outright never ran it either. Its file is named after
|
|
137
|
+
// a process that no longer exists, which is how the next server to start finds it.
|
|
138
|
+
try {
|
|
139
|
+
for (const name of readdirSync(UI_DIR)) {
|
|
140
|
+
try {
|
|
141
|
+
process.kill(Number.parseInt(name, 10), 0);
|
|
142
|
+
} catch (error) {
|
|
143
|
+
if ((error as NodeJS.ErrnoException).code === "ESRCH") rmSync(join(UI_DIR, name), { force: true });
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
} catch {
|
|
147
|
+
// No directory to sweep: publishUi() could not create it and said so.
|
|
148
|
+
}
|
|
149
|
+
const uiTool = {
|
|
150
|
+
name: "xcodebug_ui",
|
|
151
|
+
description: "Read the current display snapshot for the xcodebug Claude Code mod. For capture details or log analysis use xcodebug with action=status or action=logs.",
|
|
152
|
+
inputSchema: { type: "object", properties: {}, additionalProperties: false },
|
|
153
|
+
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
|
|
154
|
+
};
|
|
155
|
+
|
|
99
156
|
function sendNotification(method: string, params: unknown): void {
|
|
100
157
|
process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
|
|
101
158
|
}
|
|
@@ -121,9 +178,14 @@ function makeCtx(progressToken: unknown): { ctx: ExtensionContextLike; close():
|
|
|
121
178
|
ui: {
|
|
122
179
|
notify() {},
|
|
123
180
|
setStatus(_key, text) {
|
|
181
|
+
uiSnapshot.status = text;
|
|
182
|
+
publishUi();
|
|
124
183
|
report(text);
|
|
125
184
|
},
|
|
126
|
-
setWidget() {
|
|
185
|
+
setWidget(_key, rows) {
|
|
186
|
+
uiSnapshot.rows = rows ?? [];
|
|
187
|
+
publishUi();
|
|
188
|
+
},
|
|
127
189
|
},
|
|
128
190
|
},
|
|
129
191
|
// The status ticker keeps running while a capture is alive, which outlives
|
|
@@ -187,7 +249,7 @@ async function handle(message: Record<string, unknown>): Promise<void> {
|
|
|
187
249
|
return;
|
|
188
250
|
}
|
|
189
251
|
if (method === "tools/list") {
|
|
190
|
-
reply(id, { tools: [{ name: "xcodebug", description: tool.description, inputSchema }] });
|
|
252
|
+
reply(id, { tools: [{ name: "xcodebug", description: tool.description, inputSchema }, uiTool] });
|
|
191
253
|
return;
|
|
192
254
|
}
|
|
193
255
|
if (method === "tools/call") {
|
|
@@ -231,6 +293,17 @@ createInterface({ input: process.stdin }).on("line", (line) => {
|
|
|
231
293
|
replyError(null, -32700, "Parse error");
|
|
232
294
|
return;
|
|
233
295
|
}
|
|
296
|
+
// UI reads must remain responsive during a build/install/wait and must never
|
|
297
|
+
// replace state.uiCtx with the context of a polling call.
|
|
298
|
+
if (message.method === "tools/call" &&
|
|
299
|
+
(message.params as { name?: string } | undefined)?.name === uiTool.name) {
|
|
300
|
+
if (message.id !== undefined) {
|
|
301
|
+
reply(message.id, {
|
|
302
|
+
content: [{ type: "text", text: JSON.stringify({ ...uiSnapshot, seq: uiSeq, file: uiFile }) }],
|
|
303
|
+
});
|
|
304
|
+
}
|
|
305
|
+
return;
|
|
306
|
+
}
|
|
234
307
|
// Handled here rather than in handle(): the queue serializes calls, so a
|
|
235
308
|
// cancellation queued behind the very call it targets could never arrive in
|
|
236
309
|
// time. It is a notification, so nothing is sent back.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xcodebug",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Build, install and launch an iOS app on a physical device and read its console inside the agent session (pi / omp extension)",
|
|
6
6
|
"keywords": [
|
|
@@ -28,6 +28,8 @@
|
|
|
28
28
|
"files": [
|
|
29
29
|
"*.ts",
|
|
30
30
|
"mcp/",
|
|
31
|
+
"skills/",
|
|
32
|
+
"claude/",
|
|
31
33
|
"README.md",
|
|
32
34
|
"GUIDE.md",
|
|
33
35
|
"LICENSE"
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: xcodebug
|
|
3
|
+
description: "Builds, launches, and captures console logs from physical iOS devices through the xcodebug MCP server. Use when the user invokes xcodebug, requests its doctor/devices/status/logs/wait/stop/restart actions, or wants to verify an iOS app on a real device using its console."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# xcodebug
|
|
7
|
+
|
|
8
|
+
Use the **existing xcodebug MCP connection**. Its tool is named `xcodebug`
|
|
9
|
+
(Claude Code: `mcp__xcodebug__xcodebug`; Codex may display `xcodebug.xcodebug`).
|
|
10
|
+
Do not run an `xcodebug` shell command or start another MCP server: captures and
|
|
11
|
+
restart settings belong to the connected server process. If the tool is absent,
|
|
12
|
+
report that the xcodebug MCP connection must be configured first.
|
|
13
|
+
|
|
14
|
+
## Dispatch the request
|
|
15
|
+
|
|
16
|
+
Read the request following `/xcodebug` in Claude Code or `$xcodebug` in Codex.
|
|
17
|
+
Both explicit invocation and a matching natural-language request can use this skill.
|
|
18
|
+
|
|
19
|
+
- With no arguments, call `{"action":"launch"}` once to build as needed, install,
|
|
20
|
+
launch and start capturing with the server's defaults. Keep the capture running;
|
|
21
|
+
report a launch error without substituting a status query or another action.
|
|
22
|
+
- For `status`, call `{"action":"status"}` to inspect captures without launching.
|
|
23
|
+
- For an explicit action, call the MCP tool with that action and the supplied
|
|
24
|
+
parameters immediately. Do not replace execution with instructions for the user.
|
|
25
|
+
- Accept `action [key=value ...]`, `action=... [key=value ...]`, or a JSON parameter
|
|
26
|
+
object. Actions: `doctor`, `devices`, `changes`, `build`, `install`, `launch`,
|
|
27
|
+
`syslog`, `logs`, `wait`, `status`, `stop`, `terminate`, `restart`, `await`.
|
|
28
|
+
- Use the live tool schema for parameter names and types. Preserve quoted strings,
|
|
29
|
+
numeric `since`/`limit`/`timeoutSeconds`, booleans, JSON `args` arrays and
|
|
30
|
+
`environment` objects. Keep a supplied `command` shell line intact.
|
|
31
|
+
- Omit unspecified parameters so the server can apply its project configuration.
|
|
32
|
+
MCP supports pull reads: omit `push` or use `push="off"`; `context` and `wake`
|
|
33
|
+
are unsupported. Explain an unsupported explicit value instead of changing it silently.
|
|
34
|
+
- For an explicit action, make exactly one xcodebug MCP call, report its result,
|
|
35
|
+
and stop, including on error. Do not add diagnostic `status` calls or retry
|
|
36
|
+
with another action unless the user asks. `logs` never authorizes launching
|
|
37
|
+
an app, and `launch` does not imply an immediate `stop`.
|
|
38
|
+
- For a natural-language verification goal, use `launch` with known project/device
|
|
39
|
+
parameters, then collect evidence for that goal. The goal describes what to
|
|
40
|
+
verify; do not use the entire sentence as a literal log filter. If the app must
|
|
41
|
+
keep running, use `syslog` with its known process name instead of `launch`.
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
| Request after the skill name | MCP arguments |
|
|
46
|
+
|---|---|
|
|
47
|
+
| *(no arguments)* | `{"action":"launch"}` |
|
|
48
|
+
| `status` | `{"action":"status"}` |
|
|
49
|
+
| `doctor` | `{"action":"doctor"}` |
|
|
50
|
+
| `launch scheme=MyApp device="My iPhone"` | `{"action":"launch","scheme":"MyApp","device":"My iPhone"}` |
|
|
51
|
+
| `logs captureId=console-123 since=42 limit=100 grep="Weather Sync"` | `{"action":"logs","captureId":"console-123","since":42,"limit":100,"grep":"Weather Sync"}` |
|
|
52
|
+
| `wait match="sync complete" timeoutSeconds=30` | `{"action":"wait","match":"sync complete","timeoutSeconds":30}` |
|
|
53
|
+
| `stop captureId=console-123 keepApp=true` | `{"action":"stop","captureId":"console-123","keepApp":true}` |
|
|
54
|
+
| `restart` | `{"action":"restart"}` |
|
|
55
|
+
|
|
56
|
+
## Follow a capture
|
|
57
|
+
|
|
58
|
+
- `launch` restarts the app and captures stdout/stderr plus os_log. `syslog`
|
|
59
|
+
attaches without restarting. `stop` leaves the app running by default;
|
|
60
|
+
`terminate` explicitly terminates it. `restart` reuses this server's last launch
|
|
61
|
+
and forces a rebuild; a saved `command` runs again.
|
|
62
|
+
- Track `captureId` and the returned cursor **per capture**. Pass that cursor as
|
|
63
|
+
`since` on the next incremental read; never reuse another capture's cursor.
|
|
64
|
+
`logs` returns the newest matching lines up to `limit` and advances to the
|
|
65
|
+
latest capture cursor, so omitted or evicted lines will not reappear merely
|
|
66
|
+
by advancing `since`. Report omissions instead of claiming a lossless stream.
|
|
67
|
+
- Use bounded `wait` for an expected line. An empty read or quiet log is not proof
|
|
68
|
+
that a test finished. While waiting for the user to operate the phone, tell them
|
|
69
|
+
the required action and keep the capture running.
|
|
70
|
+
- For an automated scenario, pass the user's `command` to `launch`, or use `await`
|
|
71
|
+
with the current capture. The command must not relaunch the app itself, since
|
|
72
|
+
that would break the console bridge. Use the returned exit code and logs as evidence.
|
|
73
|
+
- When a verification goal is answered, stop the capture started for that goal.
|
|
74
|
+
Include its `captureId` so other captures are not stopped. An explicit `stop`
|
|
75
|
+
without an ID intentionally stops all running captures in this server.
|
|
76
|
+
- Report the operation's result, relevant log evidence, capture ID/cursor or log
|
|
77
|
+
path when returned, and whether capture remains active. Do not invent device
|
|
78
|
+
activity, successful builds, or test outcomes.
|