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 +213 -0
- package/LICENSE +21 -0
- package/README.md +449 -2
- package/archive.ts +164 -0
- package/capture.ts +327 -0
- package/changes.ts +368 -0
- package/devices.ts +278 -0
- package/exec.ts +122 -0
- package/index.ts +2274 -0
- package/package.json +52 -4
- package/progress.ts +171 -0
- package/xcode.ts +220 -0
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
|
-
#
|
|
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
|
+
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.
|