xcodebug 0.0.0-stage → 1.1.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/GUIDE.md +213 -0
- package/LICENSE +21 -0
- package/README.md +540 -2
- package/archive.ts +164 -0
- package/capture.ts +327 -0
- package/changes.ts +371 -0
- package/devices.ts +278 -0
- package/exec.ts +141 -0
- package/index.ts +2281 -0
- package/mcp/server.ts +196 -0
- package/package.json +54 -4
- package/progress.ts +171 -0
- package/xcode.ts +225 -0
package/README.md
CHANGED
|
@@ -1,3 +1,541 @@
|
|
|
1
|
-
#
|
|
1
|
+
# xcodebug
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Drive a **physical iOS device** from the agent session: build/install/launch with
|
|
4
|
+
Xcode, then read the app's console output (stdout/stderr + os_log) inside the
|
|
5
|
+
session.
|
|
6
|
+
|
|
7
|
+
No jailbreak, no LLDB attach, no paid account. It uses the tooling Xcode itself
|
|
8
|
+
ships with:
|
|
9
|
+
|
|
10
|
+
| What Xcode's console shows | How xcodebug gets it |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `print` / `NSLog` / `os_log` | `xcrun devicectl device process launch --console` |
|
|
13
|
+
| os_log in the console | `OS_ACTIVITY_DT_MODE=YES` on that launch |
|
|
14
|
+
| an app you don't want to restart | `idevicesyslog -p <ProcessName>` (optional) |
|
|
15
|
+
| build + install | `xcodebuild` + `xcrun devicectl device install app` |
|
|
16
|
+
|
|
17
|
+
`devicectl --console` needs the app to be launched *by* it, so `launch` restarts
|
|
18
|
+
the app. `syslog` attaches to an already-running process instead.
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
The extension is a directory with `index.ts` plus a `pi` manifest; either install
|
|
23
|
+
it as a package or drop the directory in place.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# from npm (writes to ~/.pi/agent/settings.json)
|
|
27
|
+
pi install npm:xcodebug
|
|
28
|
+
pi install npm:xcodebug -l # project scope: .pi/settings.json
|
|
29
|
+
|
|
30
|
+
# pin a version, or install from a checkout
|
|
31
|
+
pi install npm:xcodebug@1.0.0
|
|
32
|
+
pi install /path/to/xcodebug
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Upgrading from `xcodebug-extension`:** the package was renamed, so both names
|
|
36
|
+
register the same `xcodebug` tool and the loader refuses to start the second one
|
|
37
|
+
(`Tool "xcodebug" conflicts with ...`). Remove the old package first:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pi remove npm:xcodebug-extension
|
|
41
|
+
pi install npm:xcodebug
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Or copy the directory into the global extensions dir, which the engine discovers
|
|
45
|
+
on startup:
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
<agentDir>/extensions/xcodebug/index.ts
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`<agentDir>` is whatever the host resolves (`~/.omo/agent` under OmO,
|
|
52
|
+
`~/.omp/agent` under omp, `~/.senpi/agent` under senpi, `~/.pi/agent` under
|
|
53
|
+
upstream pi): xcodebug is a generic pi extension and names no brand.
|
|
54
|
+
|
|
55
|
+
**Restart the session** afterwards. Neither pi nor omp reloads an already-loaded
|
|
56
|
+
extension: pi has no reload command at all, and omp's `/reload-plugins` only
|
|
57
|
+
clears plugin discovery, not the imported module graph. Editing `index.ts` while
|
|
58
|
+
a session is running therefore has no effect on that session.
|
|
59
|
+
|
|
60
|
+
## Claude Code and Codex (MCP)
|
|
61
|
+
|
|
62
|
+
Neither client has an in-process extension API - tools reach them as MCP servers.
|
|
63
|
+
`mcp/server.ts` is that adapter: it loads `index.ts` with a stub host and serves
|
|
64
|
+
the tool it registers, so it exposes the same actions and arguments as the pi
|
|
65
|
+
extension rather than a parallel implementation.
|
|
66
|
+
|
|
67
|
+
### Set up (once per machine)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm i -g xcodebug # >= 1.1.0, the first release that ships mcp/
|
|
71
|
+
codex mcp add xcodebug -- node "$(npm root -g)/xcodebug/mcp/server.ts"
|
|
72
|
+
claude mcp add xcodebug -- node "$(npm root -g)/xcodebug/mcp/server.ts"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Working from a checkout instead? Point both at `mcp/server.ts` in the repo:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
codex mcp add xcodebug -- node /path/to/xcodebug/mcp/server.ts
|
|
79
|
+
claude mcp add xcodebug -- node /path/to/xcodebug/mcp/server.ts
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`node` >= 22.18 is enough: the imports carry explicit `.ts` extensions and the
|
|
83
|
+
package declares `"type": "module"`, so there is no build step and no Bun.
|
|
84
|
+
|
|
85
|
+
Check that the client picked it up:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
codex mcp list # xcodebug node …
|
|
89
|
+
claude mcp list # xcodebug: … ✔ Connected
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Use
|
|
93
|
+
|
|
94
|
+
Start the client **in the project directory**. The server inherits its cwd, and
|
|
95
|
+
that directory is the project root every action resolves against.
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
cd ~/myapp # holds the .xcworkspace or .xcodeproj
|
|
99
|
+
codex # or: claude
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Then ask for the outcome; the model calls the tool:
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
Build and launch on my device, then show me the console.
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The actions that matter in this mode:
|
|
109
|
+
|
|
110
|
+
```text
|
|
111
|
+
action=launch device=<udid> build + install + launch; the capture starts
|
|
112
|
+
action=logs since=0 incremental read - the cursor is per capture
|
|
113
|
+
action=logs grep=Weather narrow to one subsystem
|
|
114
|
+
action=wait match="..." block until a line appears
|
|
115
|
+
action=status captures, line counts, log paths
|
|
116
|
+
action=stop close every running capture
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### What differs from pi
|
|
120
|
+
|
|
121
|
+
| | pi / omp / omo | Claude Code / Codex |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| how the tool is exposed | registered in-process | MCP server process |
|
|
124
|
+
| status line, widget | yes | none |
|
|
125
|
+
| `push` | mirrors new lines into the session | refused |
|
|
126
|
+
| capture state | in the session | in the server process |
|
|
127
|
+
| lifetime | the session | the client process |
|
|
128
|
+
|
|
129
|
+
- **`push` is refused on purpose.** MCP has no channel that injects content into a
|
|
130
|
+
running turn, and neither client renders `notifications/message` - measured on
|
|
131
|
+
both, where the model reported that nothing arrived on its own between two tool
|
|
132
|
+
calls. Read with `action=logs` or `action=wait`; both are pull-based, and the
|
|
133
|
+
cursor means you only pay for new lines.
|
|
134
|
+
- **Captures end with the client.** The server is a child of Codex/Claude, so
|
|
135
|
+
quitting the client stops the bridges. Relaunch next session.
|
|
136
|
+
|
|
137
|
+
Logs land in `~/.xcodebug/logs/xcodebug/`, or under `XCODEBUG_AGENT_DIR` when set.
|
|
138
|
+
Every response also reports the exact path, so the model can read the file once a
|
|
139
|
+
run is over.
|
|
140
|
+
|
|
141
|
+
## Requirements
|
|
142
|
+
|
|
143
|
+
| Need | Why |
|
|
144
|
+
|---|---|
|
|
145
|
+
| macOS + Xcode (command-line tools) | `xcodebuild`, `xcrun devicectl` |
|
|
146
|
+
| `idevicesyslog` from libimobiledevice | optional; only `syslog` and the dual-channel safety net |
|
|
147
|
+
| git | change detection; without a repo every run rebuilds |
|
|
148
|
+
| CocoaPods | optional; only projects with a `Podfile` |
|
|
149
|
+
| Node >= 22.18 | only for the MCP clients (Claude Code, Codex); pi runs the extension itself |
|
|
150
|
+
|
|
151
|
+
`xcodebug action=doctor` reports which of these are present.
|
|
152
|
+
|
|
153
|
+
## Imports
|
|
154
|
+
|
|
155
|
+
The only engine import is a type import, erased at compile time:
|
|
156
|
+
|
|
157
|
+
```typescript
|
|
158
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
That is the official specifier; loaders also alias `@code-yeongyu/senpi` and the
|
|
162
|
+
`@mariozechner/*` names to the same module. `typebox` is the other dependency,
|
|
163
|
+
for tool parameter schemas. Everything else is `node:` built-ins.
|
|
164
|
+
|
|
165
|
+
The extension is written against the **published** types, and that is enforced:
|
|
166
|
+
it typechecks against `@earendil-works/pi-coding-agent@1.4.0`, whose
|
|
167
|
+
`ExtensionContext` carries only `cwd` and `sessionManager` and whose
|
|
168
|
+
`ExtensionAPI` has no `cwd`. Hosts that add more - `ctx.agentDir`, `pi.cwd`,
|
|
169
|
+
`argumentHint` on a command - are supported without depending on them:
|
|
170
|
+
|
|
171
|
+
```typescript
|
|
172
|
+
if ("agentDir" in ctx) { /* host supplies it */ }
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
So the same file runs unchanged on every distribution, and a host that omits
|
|
176
|
+
those fields loses nothing: the project root falls back to `ctx.cwd`, and the
|
|
177
|
+
agent directory to the session directory's parent (every brand stores sessions at
|
|
178
|
+
`<agentDir>/sessions/<encoded-cwd>`), then to a `*_CODING_AGENT_DIR` environment
|
|
179
|
+
override. If none of those exist the extension fails naming what was missing
|
|
180
|
+
rather than writing logs to a guessed path.
|
|
181
|
+
|
|
182
|
+
## Configure (optional)
|
|
183
|
+
|
|
184
|
+
`.xcodebug.json` in the project root:
|
|
185
|
+
|
|
186
|
+
```json
|
|
187
|
+
{
|
|
188
|
+
"workspace": "MyApp.xcworkspace",
|
|
189
|
+
"scheme": "MyApp",
|
|
190
|
+
"configuration": "Debug",
|
|
191
|
+
"bundleId": "com.example.myapp",
|
|
192
|
+
"device": "My-iPhone",
|
|
193
|
+
"args": [],
|
|
194
|
+
"environment": {}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`device` may be a name, UDID, ECID or CoreDevice uuid. With one physical device
|
|
199
|
+
connected it can be omitted.
|
|
200
|
+
|
|
201
|
+
## Change detection and pod install
|
|
202
|
+
|
|
203
|
+
Every `build` and `launch` first inspects the working tree with
|
|
204
|
+
`git status --porcelain -uall`:
|
|
205
|
+
|
|
206
|
+
1. **Any build-relevant change** (sources, resources, Podfile, podspec, project
|
|
207
|
+
files) forces a rebuild + relaunch.
|
|
208
|
+
2. **A new file inside a pod** forces `pod install --no-repo-update` first,
|
|
209
|
+
because the generated Pods project enumerates pod sources and will not
|
|
210
|
+
compile a file it has never seen. Pod membership comes from the repo's own
|
|
211
|
+
podspec `source_files` globs, so `Packages/FeatureX/Classes/**` maps to
|
|
212
|
+
`FeatureX`, etc.
|
|
213
|
+
3. **`Podfile.lock` out of step with `Pods/Manifest.lock`** also forces
|
|
214
|
+
`pod install`. That mismatch fails every target's "[CP] Check Pods
|
|
215
|
+
Manifest.lock" phase with an error the user cannot act on from a build log.
|
|
216
|
+
|
|
217
|
+
`pod install` only ever runs in the directory that holds the container's own
|
|
218
|
+
`Podfile` (the workspace's parent). If there is none, the step is skipped and
|
|
219
|
+
the reason is reported - it never searches elsewhere, because that could
|
|
220
|
+
reinstall a different project's pods.
|
|
221
|
+
4. **No change** since the last successful build in this session reuses that
|
|
222
|
+
build instead of rebuilding for minutes. Pass `force=true` to override.
|
|
223
|
+
|
|
224
|
+
Inspect the decision without building:
|
|
225
|
+
|
|
226
|
+
```text
|
|
227
|
+
xcodebug action=changes
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
```text
|
|
231
|
+
2 build-relevant change(s)
|
|
232
|
+
M Packages/FeatureX/Classes/Weather/AddCityController.swift
|
|
233
|
+
fingerprint: 963e92a4
|
|
234
|
+
rebuild needed: yes
|
|
235
|
+
pod install needed: no
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`pod install` runs once per change set (tracked by fingerprint), not on every
|
|
239
|
+
run. Set `installPods=false` to skip it deliberately.
|
|
240
|
+
|
|
241
|
+
## One-shot: `/xcodebug <what to verify>`
|
|
242
|
+
|
|
243
|
+
```text
|
|
244
|
+
/xcodebug 验证天气添加城市
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Detects the workspace from the current directory (walking up, so a nested cwd
|
|
248
|
+
works), rebuilds when the tree changed, installs, launches, and streams the
|
|
249
|
+
console into this session. The phrase is a goal for the model, not a log filter.
|
|
250
|
+
|
|
251
|
+
- **CocoaPods vs plain project** is decided by `Podfile`/`Podfile.lock`: a
|
|
252
|
+
CocoaPods project uses its `.xcworkspace`, a plain project its `.xcodeproj`.
|
|
253
|
+
- **The scheme** defaults to the container's own name (`MyApp.xcworkspace`
|
|
254
|
+
-> `MyApp`). That guess is checked once with `xcodebuild -list`; when it
|
|
255
|
+
does not exist, the scheme files are read for the one declaring
|
|
256
|
+
`BuildableName = "*.app"` (a workspace usually keeps its schemes in the
|
|
257
|
+
sibling `.xcodeproj`).
|
|
258
|
+
- **The outcome reaches the session**, including a failed build or install - not
|
|
259
|
+
just a UI toast.
|
|
260
|
+
|
|
261
|
+
A leading action word is still honoured: `/xcodebug logs`, `/xcodebug stop`.
|
|
262
|
+
|
|
263
|
+
`/xcodebug restart` is the mid-run answer to "I just changed the code": it
|
|
264
|
+
rebuilds, reinstalls, relaunches and reattaches by replaying the last launch in
|
|
265
|
+
this session, so the phrase, device and scheme do not have to be retyped. It
|
|
266
|
+
forces the rebuild even though nothing about the invocation changed - the edited
|
|
267
|
+
code is the whole point - and it retires the previous capture for that app
|
|
268
|
+
through the same path as `launch`. The app identity parameters it remembers -
|
|
269
|
+
goal, bundleId, processName, device, scheme/workspace/project, configuration,
|
|
270
|
+
derivedDataPath, args, environment, push, match, dualChannel - are each
|
|
271
|
+
overridden by an explicit one (`/xcodebug restart device=My-iPhone`), so an
|
|
272
|
+
override is never silently ignored. `installPods` and `timeoutSeconds` are
|
|
273
|
+
per-invocation and always pass through. It remembers one launch - the most
|
|
274
|
+
recent - so after launching a second app, `restart` targets that second app.
|
|
275
|
+
The shell line a launch carried with `command=` is remembered too, and `restart`
|
|
276
|
+
runs it again after the relaunch - that is what closes the edit → restart → test
|
|
277
|
+
loop. Pass a new `command="..."` to override it, or `command=""` to clear it so
|
|
278
|
+
the next restart only rebuilds and relaunches.
|
|
279
|
+
|
|
280
|
+
## `command=`: run a shell line alongside a capture
|
|
281
|
+
|
|
282
|
+
`command=` is a general primitive, not a test-runner hook: **any** shell line,
|
|
283
|
+
run to completion after the app is up, with the capture recording the whole time.
|
|
284
|
+
When it exits, the capture is stopped and you get the exit code plus the
|
|
285
|
+
app-side log for exactly that window. xcodebug knows nothing about the command's
|
|
286
|
+
contents - it never parses it, never assumes a framework.
|
|
287
|
+
|
|
288
|
+
That makes it the way to *provoke* something on the device and watch what the app
|
|
289
|
+
does in response:
|
|
290
|
+
|
|
291
|
+
| You want to see... | `command=` runs |
|
|
292
|
+
|---|---|
|
|
293
|
+
| an automated case tapping through a flow | `cd /repo && npm run test:weather` |
|
|
294
|
+
| a backend event reaching the app | `curl -X POST .../push -d @event.json` |
|
|
295
|
+
| a file/dataset the app then consumes | `./scripts/import-fixtures.sh` |
|
|
296
|
+
| a CLI driving the phone (deep link, locale, permission) | `xcrun simctl ...` / `idevice* ...` |
|
|
297
|
+
| a codegen or asset step whose output the app reloads | `npm run codegen` |
|
|
298
|
+
| a benchmark, then the log of that run | `./bench.sh --iterations 100` |
|
|
299
|
+
|
|
300
|
+
The app must already be running for this to mean anything, so `command=` is a
|
|
301
|
+
**second phase appended to the main action** - `/xcodebug command="..."` on its
|
|
302
|
+
own still launches first. Use `action=await` when the app is already up.
|
|
303
|
+
|
|
304
|
+
### Worked case: the automation stands in for the user
|
|
305
|
+
|
|
306
|
+
The most common use is replacing a human's taps. A capture alone only records
|
|
307
|
+
what the app does while **a person** drives the phone: slow to reproduce and
|
|
308
|
+
never quite identical twice.
|
|
309
|
+
|
|
310
|
+
```text
|
|
311
|
+
/xcodebug 分析天气添加城市 command="cd /repo && npm run test:weather"
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
| Without `command=` | With `command=` |
|
|
315
|
+
|---|---|
|
|
316
|
+
| a person opens the weather page and adds a city | the case taps the same path |
|
|
317
|
+
| the log records whatever they happened to do | the log records exactly that path, every run |
|
|
318
|
+
| the agent waits for a human, then reads | the agent reads as soon as the case exits |
|
|
319
|
+
| "it worked when I tried it" | exit code + app-side log for the same run |
|
|
320
|
+
|
|
321
|
+
So the shape of a verification run is: **goal** (what to prove) + **command**
|
|
322
|
+
(how to provoke it) + **capture** (what the app did). The exit code says whether
|
|
323
|
+
the UI reached the expected state; the log says what the app did to get there -
|
|
324
|
+
which is the part a test assertion cannot see.
|
|
325
|
+
|
|
326
|
+
### The mechanics
|
|
327
|
+
|
|
328
|
+
That single line does the whole linkage run:
|
|
329
|
+
|
|
330
|
+
1. build + install + launch the app, start the console capture;
|
|
331
|
+
2. run the shell line to completion (blocking);
|
|
332
|
+
3. stop the capture it was watching;
|
|
333
|
+
4. report the exit code, the app-side cursor, and the log path - with the
|
|
334
|
+
phrase `分析天气添加城市` attached as the goal the analysis must answer.
|
|
335
|
+
|
|
336
|
+
`command=` is a **second phase appended to the main action**, never an action of
|
|
337
|
+
its own. That ordering is the point: a command is only meaningful when the app is
|
|
338
|
+
already built, launched and being captured, so `/xcodebug command="..."` on its
|
|
339
|
+
own still launches first.
|
|
340
|
+
|
|
341
|
+
The two-step form remains available when the app is already up:
|
|
342
|
+
|
|
343
|
+
```text
|
|
344
|
+
/xcodebug launch scheme=MyApp
|
|
345
|
+
/xcodebug await command="cd /repo && npm run test:weather"
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
```text
|
|
349
|
+
# equivalent spellings
|
|
350
|
+
xcodebug action=launch command="cd /repo && npm run test:weather"
|
|
351
|
+
xcodebug action=await command="cd /repo && npm run test:weather"
|
|
352
|
+
/xcodebug await command="cd /repo && npm run test:weather" timeoutSeconds=900
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
A bare `/xcodebug` (or `/xcodebug 分析xxx`) has **no deadline**: it launches,
|
|
356
|
+
streams, and waits for you. Nothing stops it except `stop`, a new launch of the
|
|
357
|
+
same app, or the app exiting.
|
|
358
|
+
|
|
359
|
+
`command` is an opaque **shell line** handed to `/bin/sh -lc`; xcodebug knows
|
|
360
|
+
nothing about any test framework. Two consequences worth knowing:
|
|
361
|
+
|
|
362
|
+
- **Quote the whole line.** `command="cd /repo && npm run test"`. Unquoted, the
|
|
363
|
+
slash command splits on whitespace before it reads the value and only `cd`
|
|
364
|
+
reaches the shell, so the run "succeeds" having run nothing - xcodebug now
|
|
365
|
+
refuses that shape outright rather than guess.
|
|
366
|
+
- **Write `cd /repo && npm run test`, never `cd /repo npm run test`.** `cd`
|
|
367
|
+
treats the trailing words as extra arguments and returns 0 without running
|
|
368
|
+
anything, so the run looks like a pass. This one is inside a correctly quoted
|
|
369
|
+
line, so xcodebug cannot detect it for you.
|
|
370
|
+
- **Let the repo pick its own config.** A repo with several test configs will
|
|
371
|
+
fail with "No tests found" (exit 1) when run against the wrong one, which reads
|
|
372
|
+
exactly like a failing test. An npm script
|
|
373
|
+
(`"test:weather": "myrunner test --config myrunner-weather.config.ts"`)
|
|
374
|
+
pins the right config once, where the repo already declares it.
|
|
375
|
+
|
|
376
|
+
What it reports: exit code, elapsed time, how many new lines the capture gained,
|
|
377
|
+
the log path, and the `action=logs` call (with the right `since`) that returns
|
|
378
|
+
the app side of that run. A non-zero exit is surfaced as an error, not as a
|
|
379
|
+
successful "run finished".
|
|
380
|
+
|
|
381
|
+
### What the model does with it
|
|
382
|
+
|
|
383
|
+
The command's exit code answers "did the UI reach the expected state". The log
|
|
384
|
+
answers "what did the app actually do", which no assertion can see. The cursor in
|
|
385
|
+
the report is what makes the second half cheap:
|
|
386
|
+
|
|
387
|
+
```text
|
|
388
|
+
awaited cd /repo && npm test · exit 0 · 125s
|
|
389
|
+
stopped console-mvq1bclw · 5568 new line(s) · <agentDir>/logs/xcodebug/console-...log
|
|
390
|
+
next: xcodebug action=logs captureId=console-mvq1bclw since=12428
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
That `since=` starts exactly where the case began, so the next call returns only
|
|
394
|
+
this run's app-side lines, not the 12k from launch:
|
|
395
|
+
|
|
396
|
+
```text
|
|
397
|
+
xcodebug action=logs captureId=console-mvq1bclw since=12428 grep=Weather
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
```text
|
|
401
|
+
14572 MySDK: Net | WeatherService pushCities(payload) count=4
|
|
402
|
+
14588 MySDK: Net | WeatherService pushCurrent(city="...") ok
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
Which is how "the case tapped add-city" becomes "the app pushed four cities".
|
|
406
|
+
Two patterns that keep it small:
|
|
407
|
+
|
|
408
|
+
- `grep=` narrows to the subsystem under test (a class name, a log prefix).
|
|
409
|
+
- `wait match="..."` blocks until an expected line appears, for the case where
|
|
410
|
+
the assertion passes but the app's own path is what you need to see.
|
|
411
|
+
|
|
412
|
+
If the case fails, the same cursor still returns the app side, so the failure can
|
|
413
|
+
be read from both ends: the assertion says where the UI stopped, the log says why.
|
|
414
|
+
|
|
415
|
+
Boundaries that keep it out of every other workflow:
|
|
416
|
+
|
|
417
|
+
- `await` only stops **the capture it targets** (`captureId` > the active
|
|
418
|
+
capture). A second app under debug keeps streaming.
|
|
419
|
+
- It never terminates the app (`stop keepApp=true` semantics), so the screen
|
|
420
|
+
stays where the run left it.
|
|
421
|
+
- It writes no capture state, so a later `launch`/`stop`/`logs` is unaffected.
|
|
422
|
+
- No timer or silence heuristic is involved: the process exiting is the only
|
|
423
|
+
automatic finish. `timeoutSeconds` (default 1800) bounds the child process
|
|
424
|
+
only; on timeout the child is killed and the capture is still stopped, and
|
|
425
|
+
the result is reported as an error.
|
|
426
|
+
- With no capture running, `await` still runs the command and reports the exit
|
|
427
|
+
code instead of failing.
|
|
428
|
+
|
|
429
|
+
**Prerequisite when the command drives the UI:** the runner must not relaunch the
|
|
430
|
+
app. Many UI-test fixtures terminate and relaunch the app before every test
|
|
431
|
+
unless `autoAppLaunch: false` is set, which kills the very launch xcodebug is
|
|
432
|
+
capturing. Set it in the config the run uses. A command that does not touch the
|
|
433
|
+
app (a curl, a fixture import, a codegen step) has no such constraint.
|
|
434
|
+
|
|
435
|
+
### Run semantics
|
|
436
|
+
|
|
437
|
+
Verification is a loop: run, read the log, conclude, stop, edit the code, run
|
|
438
|
+
again. Each `launch` or `syslog` retires the previous cycle's capture for that same
|
|
439
|
+
app **before** the new bridge starts, so the two never push the same app's lines
|
|
440
|
+
into one conversation; other apps keep streaming, so several apps can be
|
|
441
|
+
debugged in one session.
|
|
442
|
+
|
|
443
|
+
- **Stop once the log has answered the question.** Keeping a capture alive after
|
|
444
|
+
the conclusion only floods the session.
|
|
445
|
+
- **Do not stop while the user has not acted yet.** Silence there means nothing
|
|
446
|
+
has been tried, not that the run is over: say what to do on the phone and keep
|
|
447
|
+
listening.
|
|
448
|
+
- A capture ends on its own when the app process exits. A run whose app the user
|
|
449
|
+
deliberately closed is not reconnected.
|
|
450
|
+
- A dropped console bridge otherwise reconnects indefinitely. An inconclusive
|
|
451
|
+
probe (USB unplugged, `devicectl` timeout) is **not** treated as "the app exited".
|
|
452
|
+
- `idevicesyslog` can go silent with its process still alive; a 30s watchdog kills
|
|
453
|
+
it and the exit hook reattaches. Reattachment has exactly one owner, so the
|
|
454
|
+
watchdog and the exit hook can never both assume the other is handling it.
|
|
455
|
+
- After 60s with no new lines the run says so once and keeps capturing.
|
|
456
|
+
- A footer line and a widget above the editor show the live state, e.g.
|
|
457
|
+
`📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus the
|
|
458
|
+
last few log lines and how many channels are streaming.
|
|
459
|
+
- Pushed log batches are **hidden from the transcript** (`display: false`) but
|
|
460
|
+
still delivered to the model, which is the only consumer that needs every
|
|
461
|
+
line. The screen keeps one status line instead of a wall of log frames.
|
|
462
|
+
- `/xcodebug stop` (or `action=stop`) closes **every running capture** - the
|
|
463
|
+
console bridge and its syslog companion, plus any other app still streaming.
|
|
464
|
+
Pass `captureId=` to close one. `keepApp=false` also terminates the app.
|
|
465
|
+
|
|
466
|
+
## Usage
|
|
467
|
+
|
|
468
|
+
```text
|
|
469
|
+
xcodebug action=devices
|
|
470
|
+
xcodebug action=doctor
|
|
471
|
+
xcodebug action=changes
|
|
472
|
+
xcodebug action=changes force=true
|
|
473
|
+
|
|
474
|
+
# build + install + launch, then stream the console
|
|
475
|
+
xcodebug action=launch scheme=MyApp
|
|
476
|
+
|
|
477
|
+
# build only
|
|
478
|
+
xcodebug action=build scheme=MyApp
|
|
479
|
+
|
|
480
|
+
# install an already-built .app without rebuilding
|
|
481
|
+
xcodebug action=install appPath=/path/to/App.app
|
|
482
|
+
|
|
483
|
+
# already-running app, no restart
|
|
484
|
+
xcodebug action=syslog processName=MyApp
|
|
485
|
+
|
|
486
|
+
# incremental reads (cursor-based)
|
|
487
|
+
xcodebug action=logs limit=200
|
|
488
|
+
xcodebug action=logs grep=MySDK
|
|
489
|
+
xcodebug action=wait match="DataPacket" timeoutSeconds=30
|
|
490
|
+
|
|
491
|
+
xcodebug action=status
|
|
492
|
+
xcodebug action=stop keepApp=true
|
|
493
|
+
xcodebug action=terminate
|
|
494
|
+
|
|
495
|
+
# force a rebuild even when the tree is unchanged
|
|
496
|
+
xcodebug action=launch force=true
|
|
497
|
+
# skip the automatic pod install deliberately
|
|
498
|
+
xcodebug action=launch installPods=false
|
|
499
|
+
|
|
500
|
+
# edited the code mid-run: rebuild + relaunch the same app, same device, same goal
|
|
501
|
+
xcodebug action=restart
|
|
502
|
+
|
|
503
|
+
# run any shell line to completion, then stop the capture and hand back the log
|
|
504
|
+
xcodebug action=await command="cd /repo && npm run test:weather"
|
|
505
|
+
/xcodebug await command="cd /repo && npm run test:weather"
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
### Pushing logs into the conversation
|
|
509
|
+
|
|
510
|
+
`push` controls whether new lines are mirrored into the session:
|
|
511
|
+
|
|
512
|
+
- `context` (default) — new lines are queued for the next turn (does not start one).
|
|
513
|
+
- `off` — pull with `logs`/`wait` only.
|
|
514
|
+
- `wake` — new lines start a turn.
|
|
515
|
+
|
|
516
|
+
A device console is a firehose; the push carries at most 80 lines per tick and
|
|
517
|
+
reports how many older lines it dropped. Combine it with `match` to keep it
|
|
518
|
+
useful, e.g. `xcodebug action=launch match=MySDK push=wake`.
|
|
519
|
+
|
|
520
|
+
### Files
|
|
521
|
+
|
|
522
|
+
Every capture also writes a full log to
|
|
523
|
+
`<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`, so
|
|
524
|
+
nothing is lost when the in-memory ring buffer (20k lines) rolls over.
|
|
525
|
+
|
|
526
|
+
The app's bundle id is part of the name because several apps are debugged in
|
|
527
|
+
one session; the timestamp carries milliseconds so a relaunch of the same app
|
|
528
|
+
cannot reuse the previous run's file (files are opened in append mode, so a
|
|
529
|
+
collision would interleave two runs with no way to tell them apart).
|
|
530
|
+
|
|
531
|
+
A successful build clears `<agentDir>/logs/xcodebug/archive/` first, so snapshots
|
|
532
|
+
from a previous binary cannot be mistaken for the run that is starting.
|
|
533
|
+
|
|
534
|
+
### Device archiving is off
|
|
535
|
+
|
|
536
|
+
Pulling the device unified log on a timer is disabled. Measured on an 18-minute
|
|
537
|
+
run it cost ~208 MB per snapshot (each covers the whole previous hour) with no
|
|
538
|
+
reader, and it cannot serve its stated purpose: `log show --archive ... | grep
|
|
539
|
+
MySDK` returns nothing, because `NSLog`/`print` never enters the unified log.
|
|
540
|
+
Only framework records (RunningBoard, CFNetwork, WebKit) come back, so a dropped
|
|
541
|
+
console bridge is recovered by reconnecting, not by replaying an archive.
|