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