xcodebug 0.0.0-stage → 1.0.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 ADDED
@@ -0,0 +1,213 @@
1
+ # xcodebug — practical guide
2
+
3
+ Task-oriented walkthrough. [README.md](README.md) is the authoritative reference
4
+ for every parameter, the change-detection rules and the capture internals; this
5
+ file only shows the flows you will actually type.
6
+
7
+ Debug a real iOS device: build, install, launch, and read the app's console
8
+ (stdout/stderr + os_log) inside the agent session. No jailbreak, no LLDB attach,
9
+ no paid account.
10
+
11
+ ## The one-liner
12
+
13
+ ```text
14
+ /xcodebug verify adding a weather city
15
+ ```
16
+
17
+ From the current directory it finds the workspace, rebuilds if the tree changed,
18
+ installs, launches, and starts capturing. The trailing phrase is the goal the
19
+ model must answer — not a log filter.
20
+
21
+ ## Two surfaces
22
+
23
+ **Slash command** (for humans)
24
+
25
+ ```text
26
+ /xcodebug launch scheme=MyApp
27
+ /xcodebug logs grep=MySDK
28
+ /xcodebug stop
29
+ /xcodebug analyse weather command="cd /repo && npm run test:xxx"
30
+ ```
31
+
32
+ **Tool call** (for the model)
33
+
34
+ ```text
35
+ xcodebug action=launch scheme=MyApp
36
+ xcodebug action=logs limit=200
37
+ ```
38
+
39
+ The 14 actions and their parameters are tabulated in
40
+ [README.md § Usage](README.md#usage). Two of them differ from what the name
41
+ suggests, so they are repeated here:
42
+
43
+ - `stop` closes **every running capture** (the console bridge and its syslog
44
+ companion, plus any other app still streaming). Pass `captureId=` to close one.
45
+ `keepApp=true` is the default and leaves the app running.
46
+ - `restart` replays the last launch of this session — device, scheme, goal and
47
+ the `command=` it carried — and forces a rebuild.
48
+
49
+ ## How logs reach the conversation
50
+
51
+ `push` decides whether new lines are mirrored into the session: `context`
52
+ (default, queued for the next turn), `off` (pull with `logs`/`wait`), `wake`
53
+ (starts a turn). A device console is a firehose; each push carries at most 80
54
+ lines and reports how many older lines it dropped. Narrow it with `match`, e.g.
55
+ `action=launch match=MySDK push=wake`.
56
+
57
+ ## Running a command alongside a capture
58
+
59
+ ### What it is for
60
+
61
+ `command=` is a general primitive: any shell line, run to completion after the app
62
+ is up, with the capture recording the whole time. When it exits you get the exit
63
+ code plus the app-side log for exactly that window. xcodebug never parses the
64
+ line and assumes no framework.
65
+
66
+ That makes it how you *provoke* something and watch the app react — an automated
67
+ case tapping through a flow, a backend push, a fixture import, a CLI driving the
68
+ phone, a codegen step the app reloads, a benchmark.
69
+
70
+ The most common use is replacing a human's taps: a capture alone only records
71
+ what the app does while **a person** drives the phone — slow to reproduce and
72
+ never quite identical twice. `command=` hands the driving to an automated case:
73
+ the case performs the taps, the capture records the app's response, and the model
74
+ reads that delta.
75
+
76
+ ```text
77
+ without command= with command=
78
+ a person opens the weather page the case taps the same path
79
+ the log holds whatever they did the log holds exactly that path, every run
80
+ the agent waits, then reads the agent reads as soon as the case exits
81
+ "it worked when I tried it" exit code + app-side log for one run
82
+ ```
83
+
84
+ So a verification run is **goal** (what to prove) + **command** (how to provoke
85
+ it) + **capture** (what the app did). The exit code says the UI reached the
86
+ expected state; the log says what the app did to get there.
87
+
88
+ ### The shape of it
89
+
90
+ Scenario: bring the app up under capture, run an automated case, then read the
91
+ app side of that run. xcodebug knows nothing about any test framework — you put
92
+ the command in `command`.
93
+
94
+ ```text
95
+ # one line: build + install + launch -> run the case -> stop the capture -> hand back the log
96
+ /xcodebug analyse weather city command="cd /repo && npm run test:weather"
97
+ ```
98
+
99
+ ```text
100
+ # or in two steps, when the app is already up
101
+ /xcodebug launch scheme=MyApp
102
+ /xcodebug await command="cd /repo && npm run test:weather"
103
+ ```
104
+
105
+ What happens after `command`:
106
+
107
+ 1. `/bin/sh -lc` runs the whole line, with the project root as the working
108
+ directory (`pi.cwd` → `ctx.cwd` → process cwd).
109
+ 2. It waits for the process to exit.
110
+ 3. It stops **the capture it targeted** — other apps' captures keep streaming.
111
+ 4. It hands back the exit code, elapsed time, how many new lines arrived, the
112
+ log path, and the `logs` call (with the right `since`) for the app side.
113
+
114
+ **Quote the whole line.** `command="cd /repo && npm run test"`. Unquoted, the
115
+ slash command splits on whitespace before it reads the value, so only `cd`
116
+ reaches the shell and the run "succeeds" having executed nothing — xcodebug now
117
+ rejects that shape instead of guessing.
118
+
119
+ **Always join `cd` with `&&`.** `command="cd /repo npm run test"` makes `cd`
120
+ swallow the remaining words as arguments and exit 0 without running anything,
121
+ which looks like a pass. This one is inside a correctly quoted line, so xcodebug
122
+ cannot detect it for you.
123
+
124
+ Let the repo pick its own config through an npm script
125
+ (`"test:weather": "myrunner test --config myrunner-weather.config.ts"`).
126
+ Running `myrunner test <file>` against the wrong config exits 1 with
127
+ `No tests found`, which is indistinguishable from a failing case.
128
+
129
+ ### Why this does not disturb other debugging
130
+
131
+ `await` is not a mode, just an explicit call. Nothing changes for runs that do
132
+ not pass `command=` or `action=await`.
133
+
134
+ - It stops only the capture it targeted (`captureId` > active capture); a second
135
+ app's capture keeps streaming.
136
+ - It never kills the app (`stop keepApp=true` semantics), so the screen stays
137
+ where the run left it.
138
+ - It writes no capture state, so a later `launch`/`stop`/`logs` is unaffected.
139
+ - No timer and no "quiet for N seconds means done" heuristic: process exit is the
140
+ only automatic finish.
141
+ - `timeoutSeconds` (default 1800) bounds the child process only; on timeout the
142
+ child is killed, the capture is still stopped, and the result is reported as an
143
+ error.
144
+ - With no capture running it still runs the case and reports the exit code.
145
+
146
+ ### Prerequisite: the test must not relaunch the app
147
+
148
+ Many UI-test fixtures terminate and relaunch the app before every test unless
149
+ `autoAppLaunch: false` is set. That kills the very launch xcodebug is capturing,
150
+ so the log stops there. Commands that do not drive the UI have no such
151
+ constraint.
152
+
153
+ Set this in the config the run uses:
154
+
155
+ ```ts
156
+ use: {
157
+ autoAppLaunch: false,
158
+ }
159
+ ```
160
+
161
+ A cold launch can also restore a child page instead of the tab bar. If a case
162
+ starts by tapping a tab, it has to handle that state itself — xcodebug launches
163
+ the app and nothing more.
164
+
165
+ ## Everyday commands
166
+
167
+ ```text
168
+ # environment
169
+ xcodebug action=devices
170
+ xcodebug action=doctor
171
+ xcodebug action=changes
172
+
173
+ # launch and relaunch
174
+ xcodebug action=launch scheme=MyApp
175
+ xcodebug action=launch force=true # rebuild even with no changes
176
+ xcodebug action=launch installPods=false # skip the automatic pod install
177
+ xcodebug action=restart # after editing: rebuild + relaunch + reuse params
178
+
179
+ # read logs
180
+ xcodebug action=logs limit=200
181
+ xcodebug action=logs grep=MySDK
182
+ xcodebug action=wait match="DataPacket" timeoutSeconds=30
183
+
184
+ # wrap up
185
+ xcodebug action=status
186
+ xcodebug action=stop keepApp=true
187
+ xcodebug action=terminate
188
+
189
+ # run a command alongside the capture
190
+ xcodebug action=await command="cd /repo && npm run test:weather"
191
+ ```
192
+
193
+ ## Where files land
194
+
195
+ Every capture is mirrored to
196
+ `<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`.
197
+
198
+ `agentDir` comes from the host (`ctx.agentDir`, else the parent of the session
199
+ directory), so each brand writes under its own prefix (`.pi` / `.omp` / `.omo` /
200
+ `.senpi`); the extension hardcodes none of them. The bundle id is in the name
201
+ because several apps are debugged in one session, and the timestamp carries
202
+ milliseconds because relaunching the same app within a second would otherwise
203
+ interleave two runs in one file. The in-memory ring buffer keeps the last 20k
204
+ lines; the file on disk is complete.
205
+
206
+ ## Three rules of use
207
+
208
+ 1. **Stop once the log has answered the question.** A capture left running only
209
+ keeps flooding the session.
210
+ 2. **Do not stop while the user has not acted yet.** Silence there means "not
211
+ tried yet", not "finished" — say what to tap and keep listening.
212
+ 3. **A capture ends on its own when the app process exits.** Do not reconnect a
213
+ run whose app the user deliberately closed.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CodeBaby
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,450 @@
1
- # Temporary Holding Version
1
+ # xcodebug
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ Or copy the directory into the global extensions dir, which the engine discovers
36
+ on startup:
37
+
38
+ ```text
39
+ <agentDir>/extensions/xcodebug/index.ts
40
+ ```
41
+
42
+ `<agentDir>` is whatever the host resolves (`~/.omo/agent` under OmO,
43
+ `~/.omp/agent` under omp, `~/.senpi/agent` under senpi, `~/.pi/agent` under
44
+ upstream pi): xcodebug is a generic pi extension and names no brand.
45
+
46
+ **Restart the session** afterwards. Neither pi nor omp reloads an already-loaded
47
+ extension: pi has no reload command at all, and omp's `/reload-plugins` only
48
+ clears plugin discovery, not the imported module graph. Editing `index.ts` while
49
+ a session is running therefore has no effect on that session.
50
+
51
+ ## Requirements
52
+
53
+ | Need | Why |
54
+ |---|---|
55
+ | macOS + Xcode (command-line tools) | `xcodebuild`, `xcrun devicectl` |
56
+ | `idevicesyslog` from libimobiledevice | optional; only `syslog` and the dual-channel safety net |
57
+ | git | change detection; without a repo every run rebuilds |
58
+ | CocoaPods | optional; only projects with a `Podfile` |
59
+
60
+ `xcodebug action=doctor` reports which of these are present.
61
+
62
+ ## Imports
63
+
64
+ The only engine import is a type import, erased at compile time:
65
+
66
+ ```typescript
67
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
68
+ ```
69
+
70
+ That is the official specifier; loaders also alias `@code-yeongyu/senpi` and the
71
+ `@mariozechner/*` names to the same module. `typebox` is the other dependency,
72
+ for tool parameter schemas. Everything else is `node:` built-ins.
73
+
74
+ The extension is written against the **published** types, and that is enforced:
75
+ it typechecks against `@earendil-works/pi-coding-agent@1.4.0`, whose
76
+ `ExtensionContext` carries only `cwd` and `sessionManager` and whose
77
+ `ExtensionAPI` has no `cwd`. Hosts that add more - `ctx.agentDir`, `pi.cwd`,
78
+ `argumentHint` on a command - are supported without depending on them:
79
+
80
+ ```typescript
81
+ if ("agentDir" in ctx) { /* host supplies it */ }
82
+ ```
83
+
84
+ So the same file runs unchanged on every distribution, and a host that omits
85
+ those fields loses nothing: the project root falls back to `ctx.cwd`, and the
86
+ agent directory to the session directory's parent (every brand stores sessions at
87
+ `<agentDir>/sessions/<encoded-cwd>`), then to a `*_CODING_AGENT_DIR` environment
88
+ override. If none of those exist the extension fails naming what was missing
89
+ rather than writing logs to a guessed path.
90
+
91
+ ## Configure (optional)
92
+
93
+ `.xcodebug.json` in the project root:
94
+
95
+ ```json
96
+ {
97
+ "workspace": "MyApp.xcworkspace",
98
+ "scheme": "MyApp",
99
+ "configuration": "Debug",
100
+ "bundleId": "com.example.myapp",
101
+ "device": "My-iPhone",
102
+ "args": [],
103
+ "environment": {}
104
+ }
105
+ ```
106
+
107
+ `device` may be a name, UDID, ECID or CoreDevice uuid. With one physical device
108
+ connected it can be omitted.
109
+
110
+ ## Change detection and pod install
111
+
112
+ Every `build` and `launch` first inspects the working tree with
113
+ `git status --porcelain -uall`:
114
+
115
+ 1. **Any build-relevant change** (sources, resources, Podfile, podspec, project
116
+ files) forces a rebuild + relaunch.
117
+ 2. **A new file inside a pod** forces `pod install --no-repo-update` first,
118
+ because the generated Pods project enumerates pod sources and will not
119
+ compile a file it has never seen. Pod membership comes from the repo's own
120
+ podspec `source_files` globs, so `Packages/FeatureX/Classes/**` maps to
121
+ `FeatureX`, etc.
122
+ 3. **`Podfile.lock` out of step with `Pods/Manifest.lock`** also forces
123
+ `pod install`. That mismatch fails every target's "[CP] Check Pods
124
+ Manifest.lock" phase with an error the user cannot act on from a build log.
125
+
126
+ `pod install` only ever runs in the directory that holds the container's own
127
+ `Podfile` (the workspace's parent). If there is none, the step is skipped and
128
+ the reason is reported - it never searches elsewhere, because that could
129
+ reinstall a different project's pods.
130
+ 4. **No change** since the last successful build in this session reuses that
131
+ build instead of rebuilding for minutes. Pass `force=true` to override.
132
+
133
+ Inspect the decision without building:
134
+
135
+ ```text
136
+ xcodebug action=changes
137
+ ```
138
+
139
+ ```text
140
+ 2 build-relevant change(s)
141
+ M Packages/FeatureX/Classes/Weather/AddCityController.swift
142
+ fingerprint: 963e92a4
143
+ rebuild needed: yes
144
+ pod install needed: no
145
+ ```
146
+
147
+ `pod install` runs once per change set (tracked by fingerprint), not on every
148
+ run. Set `installPods=false` to skip it deliberately.
149
+
150
+ ## One-shot: `/xcodebug <what to verify>`
151
+
152
+ ```text
153
+ /xcodebug 验证天气添加城市
154
+ ```
155
+
156
+ Detects the workspace from the current directory (walking up, so a nested cwd
157
+ works), rebuilds when the tree changed, installs, launches, and streams the
158
+ console into this session. The phrase is a goal for the model, not a log filter.
159
+
160
+ - **CocoaPods vs plain project** is decided by `Podfile`/`Podfile.lock`: a
161
+ CocoaPods project uses its `.xcworkspace`, a plain project its `.xcodeproj`.
162
+ - **The scheme** defaults to the container's own name (`MyApp.xcworkspace`
163
+ -> `MyApp`). That guess is checked once with `xcodebuild -list`; when it
164
+ does not exist, the scheme files are read for the one declaring
165
+ `BuildableName = "*.app"` (a workspace usually keeps its schemes in the
166
+ sibling `.xcodeproj`).
167
+ - **The outcome reaches the session**, including a failed build or install - not
168
+ just a UI toast.
169
+
170
+ A leading action word is still honoured: `/xcodebug logs`, `/xcodebug stop`.
171
+
172
+ `/xcodebug restart` is the mid-run answer to "I just changed the code": it
173
+ rebuilds, reinstalls, relaunches and reattaches by replaying the last launch in
174
+ this session, so the phrase, device and scheme do not have to be retyped. It
175
+ forces the rebuild even though nothing about the invocation changed - the edited
176
+ code is the whole point - and it retires the previous capture for that app
177
+ through the same path as `launch`. The app identity parameters it remembers -
178
+ goal, bundleId, processName, device, scheme/workspace/project, configuration,
179
+ derivedDataPath, args, environment, push, match, dualChannel - are each
180
+ overridden by an explicit one (`/xcodebug restart device=My-iPhone`), so an
181
+ override is never silently ignored. `installPods` and `timeoutSeconds` are
182
+ per-invocation and always pass through. It remembers one launch - the most
183
+ recent - so after launching a second app, `restart` targets that second app.
184
+ The shell line a launch carried with `command=` is remembered too, and `restart`
185
+ runs it again after the relaunch - that is what closes the edit → restart → test
186
+ loop. Pass a new `command="..."` to override it, or `command=""` to clear it so
187
+ the next restart only rebuilds and relaunches.
188
+
189
+ ## `command=`: run a shell line alongside a capture
190
+
191
+ `command=` is a general primitive, not a test-runner hook: **any** shell line,
192
+ run to completion after the app is up, with the capture recording the whole time.
193
+ When it exits, the capture is stopped and you get the exit code plus the
194
+ app-side log for exactly that window. xcodebug knows nothing about the command's
195
+ contents - it never parses it, never assumes a framework.
196
+
197
+ That makes it the way to *provoke* something on the device and watch what the app
198
+ does in response:
199
+
200
+ | You want to see... | `command=` runs |
201
+ |---|---|
202
+ | an automated case tapping through a flow | `cd /repo && npm run test:weather` |
203
+ | a backend event reaching the app | `curl -X POST .../push -d @event.json` |
204
+ | a file/dataset the app then consumes | `./scripts/import-fixtures.sh` |
205
+ | a CLI driving the phone (deep link, locale, permission) | `xcrun simctl ...` / `idevice* ...` |
206
+ | a codegen or asset step whose output the app reloads | `npm run codegen` |
207
+ | a benchmark, then the log of that run | `./bench.sh --iterations 100` |
208
+
209
+ The app must already be running for this to mean anything, so `command=` is a
210
+ **second phase appended to the main action** - `/xcodebug command="..."` on its
211
+ own still launches first. Use `action=await` when the app is already up.
212
+
213
+ ### Worked case: the automation stands in for the user
214
+
215
+ The most common use is replacing a human's taps. A capture alone only records
216
+ what the app does while **a person** drives the phone: slow to reproduce and
217
+ never quite identical twice.
218
+
219
+ ```text
220
+ /xcodebug 分析天气添加城市 command="cd /repo && npm run test:weather"
221
+ ```
222
+
223
+ | Without `command=` | With `command=` |
224
+ |---|---|
225
+ | a person opens the weather page and adds a city | the case taps the same path |
226
+ | the log records whatever they happened to do | the log records exactly that path, every run |
227
+ | the agent waits for a human, then reads | the agent reads as soon as the case exits |
228
+ | "it worked when I tried it" | exit code + app-side log for the same run |
229
+
230
+ So the shape of a verification run is: **goal** (what to prove) + **command**
231
+ (how to provoke it) + **capture** (what the app did). The exit code says whether
232
+ the UI reached the expected state; the log says what the app did to get there -
233
+ which is the part a test assertion cannot see.
234
+
235
+ ### The mechanics
236
+
237
+ That single line does the whole linkage run:
238
+
239
+ 1. build + install + launch the app, start the console capture;
240
+ 2. run the shell line to completion (blocking);
241
+ 3. stop the capture it was watching;
242
+ 4. report the exit code, the app-side cursor, and the log path - with the
243
+ phrase `分析天气添加城市` attached as the goal the analysis must answer.
244
+
245
+ `command=` is a **second phase appended to the main action**, never an action of
246
+ its own. That ordering is the point: a command is only meaningful when the app is
247
+ already built, launched and being captured, so `/xcodebug command="..."` on its
248
+ own still launches first.
249
+
250
+ The two-step form remains available when the app is already up:
251
+
252
+ ```text
253
+ /xcodebug launch scheme=MyApp
254
+ /xcodebug await command="cd /repo && npm run test:weather"
255
+ ```
256
+
257
+ ```text
258
+ # equivalent spellings
259
+ xcodebug action=launch command="cd /repo && npm run test:weather"
260
+ xcodebug action=await command="cd /repo && npm run test:weather"
261
+ /xcodebug await command="cd /repo && npm run test:weather" timeoutSeconds=900
262
+ ```
263
+
264
+ A bare `/xcodebug` (or `/xcodebug 分析xxx`) has **no deadline**: it launches,
265
+ streams, and waits for you. Nothing stops it except `stop`, a new launch of the
266
+ same app, or the app exiting.
267
+
268
+ `command` is an opaque **shell line** handed to `/bin/sh -lc`; xcodebug knows
269
+ nothing about any test framework. Two consequences worth knowing:
270
+
271
+ - **Quote the whole line.** `command="cd /repo && npm run test"`. Unquoted, the
272
+ slash command splits on whitespace before it reads the value and only `cd`
273
+ reaches the shell, so the run "succeeds" having run nothing - xcodebug now
274
+ refuses that shape outright rather than guess.
275
+ - **Write `cd /repo && npm run test`, never `cd /repo npm run test`.** `cd`
276
+ treats the trailing words as extra arguments and returns 0 without running
277
+ anything, so the run looks like a pass. This one is inside a correctly quoted
278
+ line, so xcodebug cannot detect it for you.
279
+ - **Let the repo pick its own config.** A repo with several test configs will
280
+ fail with "No tests found" (exit 1) when run against the wrong one, which reads
281
+ exactly like a failing test. An npm script
282
+ (`"test:weather": "myrunner test --config myrunner-weather.config.ts"`)
283
+ pins the right config once, where the repo already declares it.
284
+
285
+ What it reports: exit code, elapsed time, how many new lines the capture gained,
286
+ the log path, and the `action=logs` call (with the right `since`) that returns
287
+ the app side of that run. A non-zero exit is surfaced as an error, not as a
288
+ successful "run finished".
289
+
290
+ ### What the model does with it
291
+
292
+ The command's exit code answers "did the UI reach the expected state". The log
293
+ answers "what did the app actually do", which no assertion can see. The cursor in
294
+ the report is what makes the second half cheap:
295
+
296
+ ```text
297
+ awaited cd /repo && npm test · exit 0 · 125s
298
+ stopped console-mvq1bclw · 5568 new line(s) · <agentDir>/logs/xcodebug/console-...log
299
+ next: xcodebug action=logs captureId=console-mvq1bclw since=12428
300
+ ```
301
+
302
+ That `since=` starts exactly where the case began, so the next call returns only
303
+ this run's app-side lines, not the 12k from launch:
304
+
305
+ ```text
306
+ xcodebug action=logs captureId=console-mvq1bclw since=12428 grep=Weather
307
+ ```
308
+
309
+ ```text
310
+ 14572 MySDK: Net | WeatherService pushCities(payload) count=4
311
+ 14588 MySDK: Net | WeatherService pushCurrent(city="...") ok
312
+ ```
313
+
314
+ Which is how "the case tapped add-city" becomes "the app pushed four cities".
315
+ Two patterns that keep it small:
316
+
317
+ - `grep=` narrows to the subsystem under test (a class name, a log prefix).
318
+ - `wait match="..."` blocks until an expected line appears, for the case where
319
+ the assertion passes but the app's own path is what you need to see.
320
+
321
+ If the case fails, the same cursor still returns the app side, so the failure can
322
+ be read from both ends: the assertion says where the UI stopped, the log says why.
323
+
324
+ Boundaries that keep it out of every other workflow:
325
+
326
+ - `await` only stops **the capture it targets** (`captureId` > the active
327
+ capture). A second app under debug keeps streaming.
328
+ - It never terminates the app (`stop keepApp=true` semantics), so the screen
329
+ stays where the run left it.
330
+ - It writes no capture state, so a later `launch`/`stop`/`logs` is unaffected.
331
+ - No timer or silence heuristic is involved: the process exiting is the only
332
+ automatic finish. `timeoutSeconds` (default 1800) bounds the child process
333
+ only; on timeout the child is killed and the capture is still stopped, and
334
+ the result is reported as an error.
335
+ - With no capture running, `await` still runs the command and reports the exit
336
+ code instead of failing.
337
+
338
+ **Prerequisite when the command drives the UI:** the runner must not relaunch the
339
+ app. Many UI-test fixtures terminate and relaunch the app before every test
340
+ unless `autoAppLaunch: false` is set, which kills the very launch xcodebug is
341
+ capturing. Set it in the config the run uses. A command that does not touch the
342
+ app (a curl, a fixture import, a codegen step) has no such constraint.
343
+
344
+ ### Run semantics
345
+
346
+ Verification is a loop: run, read the log, conclude, stop, edit the code, run
347
+ again. Each `launch` or `syslog` retires the previous cycle's capture for that same
348
+ app **before** the new bridge starts, so the two never push the same app's lines
349
+ into one conversation; other apps keep streaming, so several apps can be
350
+ debugged in one session.
351
+
352
+ - **Stop once the log has answered the question.** Keeping a capture alive after
353
+ the conclusion only floods the session.
354
+ - **Do not stop while the user has not acted yet.** Silence there means nothing
355
+ has been tried, not that the run is over: say what to do on the phone and keep
356
+ listening.
357
+ - A capture ends on its own when the app process exits. A run whose app the user
358
+ deliberately closed is not reconnected.
359
+ - A dropped console bridge otherwise reconnects indefinitely. An inconclusive
360
+ probe (USB unplugged, `devicectl` timeout) is **not** treated as "the app exited".
361
+ - `idevicesyslog` can go silent with its process still alive; a 30s watchdog kills
362
+ it and the exit hook reattaches. Reattachment has exactly one owner, so the
363
+ watchdog and the exit hook can never both assume the other is handling it.
364
+ - After 60s with no new lines the run says so once and keeps capturing.
365
+ - A footer line and a widget above the editor show the live state, e.g.
366
+ `📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus the
367
+ last few log lines and how many channels are streaming.
368
+ - Pushed log batches are **hidden from the transcript** (`display: false`) but
369
+ still delivered to the model, which is the only consumer that needs every
370
+ line. The screen keeps one status line instead of a wall of log frames.
371
+ - `/xcodebug stop` (or `action=stop`) closes **every running capture** - the
372
+ console bridge and its syslog companion, plus any other app still streaming.
373
+ Pass `captureId=` to close one. `keepApp=false` also terminates the app.
374
+
375
+ ## Usage
376
+
377
+ ```text
378
+ xcodebug action=devices
379
+ xcodebug action=doctor
380
+ xcodebug action=changes
381
+ xcodebug action=changes force=true
382
+
383
+ # build + install + launch, then stream the console
384
+ xcodebug action=launch scheme=MyApp
385
+
386
+ # build only
387
+ xcodebug action=build scheme=MyApp
388
+
389
+ # install an already-built .app without rebuilding
390
+ xcodebug action=install appPath=/path/to/App.app
391
+
392
+ # already-running app, no restart
393
+ xcodebug action=syslog processName=MyApp
394
+
395
+ # incremental reads (cursor-based)
396
+ xcodebug action=logs limit=200
397
+ xcodebug action=logs grep=MySDK
398
+ xcodebug action=wait match="DataPacket" timeoutSeconds=30
399
+
400
+ xcodebug action=status
401
+ xcodebug action=stop keepApp=true
402
+ xcodebug action=terminate
403
+
404
+ # force a rebuild even when the tree is unchanged
405
+ xcodebug action=launch force=true
406
+ # skip the automatic pod install deliberately
407
+ xcodebug action=launch installPods=false
408
+
409
+ # edited the code mid-run: rebuild + relaunch the same app, same device, same goal
410
+ xcodebug action=restart
411
+
412
+ # run any shell line to completion, then stop the capture and hand back the log
413
+ xcodebug action=await command="cd /repo && npm run test:weather"
414
+ /xcodebug await command="cd /repo && npm run test:weather"
415
+ ```
416
+
417
+ ### Pushing logs into the conversation
418
+
419
+ `push` controls whether new lines are mirrored into the session:
420
+
421
+ - `context` (default) — new lines are queued for the next turn (does not start one).
422
+ - `off` — pull with `logs`/`wait` only.
423
+ - `wake` — new lines start a turn.
424
+
425
+ A device console is a firehose; the push carries at most 80 lines per tick and
426
+ reports how many older lines it dropped. Combine it with `match` to keep it
427
+ useful, e.g. `xcodebug action=launch match=MySDK push=wake`.
428
+
429
+ ### Files
430
+
431
+ Every capture also writes a full log to
432
+ `<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`, so
433
+ nothing is lost when the in-memory ring buffer (20k lines) rolls over.
434
+
435
+ The app's bundle id is part of the name because several apps are debugged in
436
+ one session; the timestamp carries milliseconds so a relaunch of the same app
437
+ cannot reuse the previous run's file (files are opened in append mode, so a
438
+ collision would interleave two runs with no way to tell them apart).
439
+
440
+ A successful build clears `<agentDir>/logs/xcodebug/archive/` first, so snapshots
441
+ from a previous binary cannot be mistaken for the run that is starting.
442
+
443
+ ### Device archiving is off
444
+
445
+ Pulling the device unified log on a timer is disabled. Measured on an 18-minute
446
+ run it cost ~208 MB per snapshot (each covers the whole previous hour) with no
447
+ reader, and it cannot serve its stated purpose: `log show --archive ... | grep
448
+ MySDK` returns nothing, because `NSLog`/`print` never enters the unified log.
449
+ Only framework records (RunningBoard, CFNetwork, WebKit) come back, so a dropped
450
+ console bridge is recovered by reconnecting, not by replaying an archive.