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/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.
|