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/archive.ts ADDED
@@ -0,0 +1,164 @@
1
+ /**
2
+ * Durable log archiving.
3
+ *
4
+ * The live console bridge (`devicectl --console`) carries the app's own
5
+ * stdout/stderr, including NSLog/print output that os_log never records. It can
6
+ * drop mid-run, and whatever it did not emit is gone from the live channel.
7
+ *
8
+ * The device keeps its own unified log for hours. `idevicesyslog archive`
9
+ * pulls that archive, and `log show --archive` reads it back for any time
10
+ * window - so a dropped bridge can still be back-filled from the device.
11
+ *
12
+ * Coverage differs by channel and is reported honestly:
13
+ * live console - app stdout/stderr + os_log (MySDK, BLE, print)
14
+ * device archive - os_log only (framework/system messages, errors)
15
+ * MySDK-style NSLog lines appear only in the live channel.
16
+ */
17
+ import { mkdir, readdir, rm, stat } from "node:fs/promises";
18
+ import { dirname, join } from "node:path";
19
+ import { runCommand, timestamp } from "./exec";
20
+
21
+ export interface ArchiveResult {
22
+ ok: boolean;
23
+ /** Path to the .logarchive directory ready for `log show --archive`. */
24
+ archivePath?: string;
25
+ /** Raw .tar as pulled from the device. */
26
+ tarPath: string;
27
+ durationMs: number;
28
+ message: string;
29
+ }
30
+
31
+ /**
32
+ * Delete every pulled archive in `workDir`.
33
+ *
34
+ * Each pull covers the device's last hour, so consecutive snapshots overlap
35
+ * almost entirely and only the newest one is worth keeping. Called when a new
36
+ * build starts: a fresh build means the previous run's archives can no longer
37
+ * explain anything about the run that is about to begin.
38
+ */
39
+ export async function clearArchives(workDir: string): Promise<{ removed: number; freedBytes: number }> {
40
+ let removed = 0;
41
+ let freedBytes = 0;
42
+ let entries: string[];
43
+ try {
44
+ entries = await readdir(workDir);
45
+ } catch {
46
+ return { removed, freedBytes };
47
+ }
48
+ for (const name of entries) {
49
+ const isArchive = name.endsWith(".tar") || name.endsWith(".logarchive");
50
+ if (!isArchive) continue;
51
+ const path = join(workDir, name);
52
+ try {
53
+ // Measure before removing: the directory size is gone afterwards.
54
+ freedBytes += await sizeOf(path);
55
+ await rm(path, { recursive: true, force: true });
56
+ removed += 1;
57
+ } catch {
58
+ // A file already gone, or one we cannot delete, is not worth failing a build.
59
+ }
60
+ }
61
+ return { removed, freedBytes };
62
+ }
63
+
64
+ /** Recursive size of a file or directory, in bytes. */
65
+ async function sizeOf(path: string): Promise<number> {
66
+ const info = await stat(path);
67
+ if (!info.isDirectory()) return info.size;
68
+ let total = 0;
69
+ for (const entry of await readdir(path, { withFileTypes: true })) {
70
+ const child = join(path, entry.name);
71
+ total += entry.isDirectory() ? await sizeOf(child) : (await stat(child)).size;
72
+ }
73
+ return total;
74
+ }
75
+
76
+ export interface ArchiveQueryOptions {
77
+ start?: string;
78
+ end?: string;
79
+ processName?: string;
80
+ grep?: string;
81
+ limit?: number;
82
+ }
83
+
84
+ /** Pull the device's unified log for the last `ageSeconds` into a logarchive. */
85
+ export async function pullArchive(
86
+ deviceUdid: string,
87
+ options: { ageSeconds: number; workDir: string; timeoutMs?: number; signal?: AbortSignal },
88
+ ): Promise<ArchiveResult> {
89
+ const started = Date.now();
90
+ const stamp = timestamp();
91
+ const tarPath = join(options.workDir, `device-log-${stamp}.tar`);
92
+ const archivePath = join(options.workDir, `device-log-${stamp}.logarchive`);
93
+ await mkdir(dirname(tarPath), { recursive: true });
94
+
95
+ const pull = await runCommand(
96
+ "idevicesyslog",
97
+ ["-u", deviceUdid, "archive", tarPath, "--age-limit", String(options.ageSeconds)],
98
+ { timeoutMs: options.timeoutMs ?? 300_000, maxBytes: 2_000_000, signal: options.signal },
99
+ );
100
+ if (pull.code !== 0) {
101
+ return {
102
+ ok: false,
103
+ tarPath,
104
+ durationMs: Date.now() - started,
105
+ message: `archive pull failed (exit ${pull.code}): ${(pull.stderr || pull.stdout).trim().slice(0, 300)}`,
106
+ };
107
+ }
108
+
109
+ await mkdir(archivePath, { recursive: true });
110
+ const untar = await runCommand("tar", ["-xf", tarPath, "-C", archivePath], {
111
+ timeoutMs: 180_000,
112
+ maxBytes: 200_000,
113
+ });
114
+ if (untar.code !== 0) {
115
+ return {
116
+ ok: false,
117
+ tarPath,
118
+ durationMs: Date.now() - started,
119
+ message: `archive extract failed (exit ${untar.code}): ${(untar.stderr || untar.stdout).trim().slice(0, 300)}`,
120
+ };
121
+ }
122
+
123
+ return {
124
+ ok: true,
125
+ archivePath,
126
+ tarPath,
127
+ durationMs: Date.now() - started,
128
+ message: `archive ready (${((Date.now() - started) / 1000).toFixed(1)}s)`,
129
+ };
130
+ }
131
+
132
+ /** Read a window out of a pulled archive. */
133
+ export async function queryArchive(
134
+ archivePath: string,
135
+ options: ArchiveQueryOptions,
136
+ ): Promise<{ ok: boolean; lines: string[]; message: string }> {
137
+ const args = ["show", "--archive", archivePath, "--style", "compact"];
138
+ if (options.start) args.push("--start", options.start);
139
+ if (options.end) args.push("--end", options.end);
140
+ if (options.processName) args.push("--predicate", `process == "${options.processName}"`);
141
+
142
+ const result = await runCommand("log", args, { timeoutMs: 300_000, maxBytes: 20_000_000 });
143
+ if (result.code !== 0) {
144
+ return {
145
+ ok: false,
146
+ lines: [],
147
+ message: `log show failed (exit ${result.code}): ${(result.stderr || result.stdout).trim().slice(0, 300)}`,
148
+ };
149
+ }
150
+
151
+ let lines = result.stdout.split("\n").filter((line) => line.trim().length > 0);
152
+ // Drop the "Timestamp Ty Process[PID:TID]" header line.
153
+ if (lines.length > 0 && lines[0]?.startsWith("Timestamp")) lines = lines.slice(1);
154
+ const grep = options.grep;
155
+ if (grep) lines = lines.filter((line) => line.includes(grep));
156
+ const limit = options.limit ?? 500;
157
+ const total = lines.length;
158
+ const kept = lines.slice(-limit);
159
+ return {
160
+ ok: true,
161
+ lines: kept,
162
+ message: `${kept.length} line(s)${total > kept.length ? ` (${total - kept.length} older omitted)` : ""}`,
163
+ };
164
+ }
package/capture.ts ADDED
@@ -0,0 +1,327 @@
1
+ /**
2
+ * One live log capture: a long-running child process whose stdout/stderr is
3
+ * normalized into an indexed ring buffer, mirrored to a log file, and read
4
+ * back through a cursor so the agent can fetch only what is new.
5
+ */
6
+ import { spawn, type ChildProcess } from "node:child_process";
7
+ import { createWriteStream, type WriteStream } from "node:fs";
8
+ import { mkdir } from "node:fs/promises";
9
+ import { dirname } from "node:path";
10
+ import { timestamp } from "./exec";
11
+
12
+ const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
13
+ const MAX_BUFFER_LINES = 20_000;
14
+ const MAX_FILE_BYTES = 50 * 1024 * 1024;
15
+
16
+ export type CaptureMode = "console" | "syslog";
17
+
18
+ export interface LogLine {
19
+ index: number;
20
+ at: number;
21
+ stream: "out" | "err";
22
+ text: string;
23
+ }
24
+
25
+ export interface CaptureInit {
26
+ mode: CaptureMode;
27
+ deviceId: string;
28
+ deviceLabel: string;
29
+ bundleId: string;
30
+ processName?: string;
31
+ /** App process id when known (launch); never the bridge pid. */
32
+ appPid?: number;
33
+ logDir: string;
34
+ command: string;
35
+ args: string[];
36
+ /** Reuse an existing log file (used when auto-reconnecting a dropped bridge). */
37
+ logFile?: string;
38
+ /** How new lines are mirrored into the session; the reconnect path restarts it. */
39
+ pushMode?: "context" | "wake";
40
+ }
41
+
42
+ export interface CaptureStatus {
43
+ id: string;
44
+ mode: CaptureMode;
45
+ device: string;
46
+ bundleId: string;
47
+ processName?: string;
48
+ /** Bridge process id (devicectl/idevicesyslog). */
49
+ pid?: number;
50
+ /** App process id on the device, when known. */
51
+ appPid?: number;
52
+ running: boolean;
53
+ exitCode?: number;
54
+ signal?: string;
55
+ startedAt: number;
56
+ lineCount: number;
57
+ droppedLines: number;
58
+ cursor: number;
59
+ logFile: string;
60
+ commandLine: string;
61
+ error?: string;
62
+ }
63
+
64
+ function clean(text: string): string {
65
+ return text.replace(ANSI, "").replace(/\r/g, "");
66
+ }
67
+
68
+ export class Capture {
69
+ readonly id: string;
70
+ readonly mode: CaptureMode;
71
+ readonly deviceId: string;
72
+ readonly deviceLabel: string;
73
+ readonly bundleId: string;
74
+ readonly processName?: string;
75
+ /** App pid on the device; filled in once discovery succeeds, never the bridge pid. */
76
+ appPid?: number;
77
+ readonly startedAt = Date.now();
78
+ readonly logFile: string;
79
+
80
+ readonly command: string;
81
+ readonly launchArgs: string[];
82
+ /** Set when the user explicitly stops this capture, so auto-reconnect stays off. */
83
+ stoppedByUser = false;
84
+ /**
85
+ * How this capture mirrors new lines into the session. Kept on the capture so
86
+ * a reconnected bridge resumes the same push mode instead of going silent.
87
+ */
88
+ pushMode?: "context" | "wake";
89
+ /** Log filter the push was started with, so a resume keeps it. */
90
+ pushMatch?: string;
91
+ /**
92
+ * When the bridge last produced a line, in epoch ms.
93
+ *
94
+ * Lives on the capture, not on the push loop: a silence watchdog has to work
95
+ * whether or not lines are being mirrored into the session, and `push=off`
96
+ * never starts that loop. Initialised at construction so a bridge that never
97
+ * emits anything still ages from a sane starting point.
98
+ */
99
+ lastLineAt = Date.now();
100
+ /**
101
+ * Aborted when this capture is stopped, so an in-flight device probe returns
102
+ * at once instead of running out its own timeout first.
103
+ */
104
+ readonly abort = new AbortController();
105
+ private child: ChildProcess | undefined;
106
+ private file: WriteStream | undefined;
107
+ private readonly lines: LogLine[] = [];
108
+ private droppedLines = 0;
109
+ private cursor = 0;
110
+ private buffered: { out: string; err: string } = { out: "", err: "" };
111
+ private exitCode: number | undefined;
112
+ private exitSignal: string | undefined;
113
+ private error: string | undefined;
114
+ private fileBytes = 0;
115
+ private readonly exitListeners = new Set<(code: number | undefined, signal: string | undefined) => void>();
116
+ private readonly lineListeners = new Set<(line: LogLine) => void>();
117
+
118
+ constructor(init: CaptureInit) {
119
+ this.id = `${init.mode}-${Date.now().toString(36)}`;
120
+ this.mode = init.mode;
121
+ this.deviceId = init.deviceId;
122
+ this.deviceLabel = init.deviceLabel;
123
+ this.bundleId = init.bundleId;
124
+ this.processName = init.processName;
125
+ this.appPid = init.appPid;
126
+ this.pushMode = init.pushMode;
127
+ this.command = init.command;
128
+ this.launchArgs = init.args;
129
+ this.logFile =
130
+ init.logFile ?? `${init.logDir}/${init.mode}-${init.bundleId}-${timestamp()}.log`;
131
+ }
132
+
133
+ get running(): boolean {
134
+ return this.child !== undefined && this.child.exitCode === null && this.exitSignal === undefined;
135
+ }
136
+
137
+ /** Clear the terminal state so start() can attach a fresh bridge. */
138
+ resetForReconnect(): void {
139
+ this.exitCode = undefined;
140
+ this.exitSignal = undefined;
141
+ this.error = undefined;
142
+ this.buffered = { out: "", err: "" };
143
+ // A fresh bridge starts its silence clock now, or the watchdog would see the
144
+ // gap it just repaired and immediately restart the new bridge too.
145
+ this.lastLineAt = Date.now();
146
+ }
147
+
148
+ get pid(): number | undefined {
149
+ return this.child?.pid;
150
+ }
151
+
152
+ onExit(listener: (code: number | undefined, signal: string | undefined) => void): () => void {
153
+ this.exitListeners.add(listener);
154
+ return () => this.exitListeners.delete(listener);
155
+ }
156
+
157
+ /** Subscribe to every new line. Used by the wait primitive instead of polling. */
158
+ onLine(listener: (line: LogLine) => void): () => void {
159
+ this.lineListeners.add(listener);
160
+ return () => this.lineListeners.delete(listener);
161
+ }
162
+
163
+ async start(): Promise<void> {
164
+ await mkdir(dirname(this.logFile), { recursive: true });
165
+ this.file = createWriteStream(this.logFile, { flags: "a" });
166
+ this.file.on("error", () => {
167
+ this.file = undefined;
168
+ });
169
+
170
+ const child = spawn(this.command, this.launchArgs, { stdio: ["ignore", "pipe", "pipe"] });
171
+ this.child = child;
172
+ child.stdout?.setEncoding("utf8");
173
+ child.stderr?.setEncoding("utf8");
174
+ child.stdout?.on("data", (chunk: string) => this.consume("out", chunk));
175
+ child.stderr?.on("data", (chunk: string) => this.consume("err", chunk));
176
+ child.on("error", (error: Error) => {
177
+ this.error = error.message;
178
+ this.pushLine("err", `[xcodebug] failed to start: ${error.message}`);
179
+ this.finish(undefined, undefined);
180
+ });
181
+ child.on("exit", (code: number | null, signal: NodeJS.Signals | null) => {
182
+ this.flush("out");
183
+ this.flush("err");
184
+ this.finish(code ?? undefined, signal ?? undefined);
185
+ });
186
+ }
187
+
188
+ private consume(stream: "out" | "err", chunk: string): void {
189
+ const pending = this.buffered[stream] + chunk;
190
+ const parts = pending.split("\n");
191
+ this.buffered[stream] = parts.pop() ?? "";
192
+ for (const part of parts) this.pushLine(stream, part);
193
+ if (this.buffered[stream].length > 64_000) this.flush(stream);
194
+ }
195
+
196
+ private flush(stream: "out" | "err"): void {
197
+ const rest = this.buffered[stream];
198
+ this.buffered[stream] = "";
199
+ if (rest.trim().length > 0) this.pushLine(stream, rest);
200
+ }
201
+
202
+ pushLine(stream: "out" | "err", raw: string): void {
203
+ const text = clean(raw);
204
+ if (text.trim().length === 0) return;
205
+ const line: LogLine = { index: ++this.cursor, at: Date.now(), stream, text };
206
+ // Every line proves the bridge is alive, whether or not it is being pushed.
207
+ this.lastLineAt = line.at;
208
+ this.lines.push(line);
209
+ if (this.lines.length > MAX_BUFFER_LINES) {
210
+ this.lines.shift();
211
+ this.droppedLines += 1;
212
+ }
213
+ for (const listener of this.lineListeners) {
214
+ try {
215
+ listener(line);
216
+ } catch {
217
+ // A listener must never break capture.
218
+ }
219
+ }
220
+ if (this.file && this.fileBytes < MAX_FILE_BYTES) {
221
+ const encoded = `${new Date(line.at).toISOString()} ${line.text}\n`;
222
+ this.fileBytes += Buffer.byteLength(encoded);
223
+ this.file.write(encoded);
224
+ }
225
+ }
226
+
227
+ private finish(code: number | undefined, signal: string | undefined): void {
228
+ if (this.exitCode !== undefined || this.exitSignal !== undefined) return;
229
+ this.exitCode = code;
230
+ this.exitSignal = signal;
231
+ this.child = undefined;
232
+ this.file?.end();
233
+ this.file = undefined;
234
+ for (const listener of this.exitListeners) {
235
+ try {
236
+ listener(code, signal);
237
+ } catch {
238
+ // A listener must never break capture teardown.
239
+ }
240
+ }
241
+ }
242
+
243
+ /** Stop the bridge. SIGKILL keeps the app alive; SIGTERM lets devicectl forward termination. */
244
+ stop(terminateApp: boolean): void {
245
+ this.stoppedByUser = true;
246
+ this.abort.abort();
247
+ const child = this.child;
248
+ if (!child || child.exitCode !== null) return;
249
+ if (terminateApp && this.mode === "console") {
250
+ child.kill("SIGTERM");
251
+ } else {
252
+ child.kill("SIGKILL");
253
+ }
254
+ }
255
+
256
+ /**
257
+ * Kill the bridge for a restart, without touching `stoppedByUser`.
258
+ *
259
+ * `stop()` records the user's intent, so a silence watchdog must not use it:
260
+ * doing so let an internal restart clear a stop the user had just requested.
261
+ * This only tears the process down; the caller reattaches.
262
+ */
263
+ restartBridge(): void {
264
+ const child = this.child;
265
+ if (!child || child.exitCode !== null) return;
266
+ child.kill("SIGKILL");
267
+ }
268
+
269
+ /** A signal that fires when this capture is stopped. */
270
+ get signal(): AbortSignal {
271
+ return this.abort.signal;
272
+ }
273
+
274
+ waitForExit(timeoutMs: number): Promise<boolean> {
275
+ if (!this.running) return Promise.resolve(true);
276
+ return new Promise((resolve) => {
277
+ let settled = false;
278
+ const done = (exited: boolean): void => {
279
+ if (settled) return;
280
+ settled = true;
281
+ clearTimeout(timer);
282
+ unsubscribe();
283
+ resolve(exited);
284
+ };
285
+ const unsubscribe = this.onExit(() => done(true));
286
+ const timer = setTimeout(() => done(false), Math.max(1_000, timeoutMs));
287
+ });
288
+ }
289
+
290
+ read(options: { since?: number; limit?: number; grep?: string; streams?: Array<"out" | "err"> }): {
291
+ lines: LogLine[];
292
+ cursor: number;
293
+ total: number;
294
+ } {
295
+ const since = Math.max(0, options.since ?? 0);
296
+ const limit = Math.min(Math.max(1, options.limit ?? 200), 5_000);
297
+ const grep = options.grep?.trim();
298
+ const streams = options.streams;
299
+ let matched = this.lines.filter((line) => line.index > since);
300
+ if (streams && streams.length > 0) matched = matched.filter((line) => streams.includes(line.stream));
301
+ if (grep) matched = matched.filter((line) => line.text.includes(grep));
302
+ const cursor = this.cursor;
303
+ return { lines: matched.slice(-limit), cursor, total: matched.length };
304
+ }
305
+
306
+ status(): CaptureStatus {
307
+ return {
308
+ id: this.id,
309
+ mode: this.mode,
310
+ device: this.deviceLabel,
311
+ bundleId: this.bundleId,
312
+ processName: this.processName,
313
+ pid: this.pid,
314
+ appPid: this.appPid,
315
+ running: this.running,
316
+ exitCode: this.exitCode,
317
+ signal: this.exitSignal,
318
+ startedAt: this.startedAt,
319
+ lineCount: this.cursor,
320
+ droppedLines: this.droppedLines,
321
+ cursor: this.cursor,
322
+ logFile: this.logFile,
323
+ commandLine: [this.command, ...this.launchArgs].join(" "),
324
+ error: this.error,
325
+ };
326
+ }
327
+ }