xcodebug 1.1.2 → 1.2.1
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 +58 -16
- package/README.md +357 -49
- package/capture.ts +166 -38
- package/claude/.claude-plugin/plugin.json +6 -0
- package/claude/hooks/hooks.json +3 -0
- package/claude/hooks/register.js +113 -0
- package/claude/tests/live.test.ts +321 -0
- package/index.ts +24 -19
- package/mcp/server.ts +77 -4
- package/package.json +3 -1
- package/skills/xcodebug/SKILL.md +78 -0
package/capture.ts
CHANGED
|
@@ -7,11 +7,15 @@ import { spawn, type ChildProcess } from "node:child_process";
|
|
|
7
7
|
import { createWriteStream, type WriteStream } from "node:fs";
|
|
8
8
|
import { mkdir } from "node:fs/promises";
|
|
9
9
|
import { dirname } from "node:path";
|
|
10
|
+
import { finished } from "node:stream/promises";
|
|
10
11
|
import { timestamp } from "./exec.ts";
|
|
11
12
|
|
|
12
13
|
const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
|
|
13
14
|
const MAX_BUFFER_LINES = 20_000;
|
|
15
|
+
const MAX_BUFFER_BYTES = 4 * 1024 * 1024;
|
|
14
16
|
const MAX_FILE_BYTES = 50 * 1024 * 1024;
|
|
17
|
+
const MAX_LOG_FILES = 3;
|
|
18
|
+
const MAX_DRAIN_MS = 2_000;
|
|
15
19
|
|
|
16
20
|
export type CaptureMode = "console" | "syslog";
|
|
17
21
|
|
|
@@ -57,6 +61,8 @@ export interface CaptureStatus {
|
|
|
57
61
|
droppedLines: number;
|
|
58
62
|
cursor: number;
|
|
59
63
|
logFile: string;
|
|
64
|
+
/** Retained segments in chronological order; logFile is their stable base path. */
|
|
65
|
+
logFiles: string[];
|
|
60
66
|
commandLine: string;
|
|
61
67
|
error?: string;
|
|
62
68
|
}
|
|
@@ -104,7 +110,10 @@ export class Capture {
|
|
|
104
110
|
readonly abort = new AbortController();
|
|
105
111
|
private child: ChildProcess | undefined;
|
|
106
112
|
private file: WriteStream | undefined;
|
|
107
|
-
private readonly lines: LogLine
|
|
113
|
+
private readonly lines: Array<LogLine | undefined> = new Array(MAX_BUFFER_LINES);
|
|
114
|
+
private head = 0;
|
|
115
|
+
private lineCount = 0;
|
|
116
|
+
private bufferBytes = 0;
|
|
108
117
|
private droppedLines = 0;
|
|
109
118
|
private cursor = 0;
|
|
110
119
|
private buffered: { out: string; err: string } = { out: "", err: "" };
|
|
@@ -112,6 +121,11 @@ export class Capture {
|
|
|
112
121
|
private exitSignal: string | undefined;
|
|
113
122
|
private error: string | undefined;
|
|
114
123
|
private fileBytes = 0;
|
|
124
|
+
private fileNumber = 0;
|
|
125
|
+
private fileOrder = 0;
|
|
126
|
+
private readonly logFiles = new Map<string, number>();
|
|
127
|
+
private readonly files = new Set<WriteStream>();
|
|
128
|
+
private readonly blockedFiles = new Set<WriteStream>();
|
|
115
129
|
private readonly exitListeners = new Set<(code: number | undefined, signal: string | undefined) => void>();
|
|
116
130
|
private readonly lineListeners = new Set<(line: LogLine) => void>();
|
|
117
131
|
|
|
@@ -130,8 +144,9 @@ export class Capture {
|
|
|
130
144
|
init.logFile ?? `${init.logDir}/${init.mode}-${init.bundleId}-${timestamp()}.log`;
|
|
131
145
|
}
|
|
132
146
|
|
|
147
|
+
/** Remain live until the pipes and file writes drain, or their deadline expires. */
|
|
133
148
|
get running(): boolean {
|
|
134
|
-
return this.child !== undefined
|
|
149
|
+
return this.child !== undefined;
|
|
135
150
|
}
|
|
136
151
|
|
|
137
152
|
/** Clear the terminal state so start() can attach a fresh bridge. */
|
|
@@ -162,29 +177,112 @@ export class Capture {
|
|
|
162
177
|
|
|
163
178
|
async start(): Promise<void> {
|
|
164
179
|
await mkdir(dirname(this.logFile), { recursive: true });
|
|
165
|
-
this.
|
|
166
|
-
this.file.on("error", () => {
|
|
167
|
-
this.file = undefined;
|
|
168
|
-
});
|
|
180
|
+
this.openFile(true);
|
|
169
181
|
|
|
170
182
|
const child = spawn(this.command, this.launchArgs, { stdio: ["ignore", "pipe", "pipe"] });
|
|
171
183
|
this.child = child;
|
|
184
|
+
let finishing = false;
|
|
185
|
+
let drainTimer: NodeJS.Timeout | undefined;
|
|
186
|
+
const drainAbort = new AbortController();
|
|
187
|
+
const complete = (code: number | undefined, signal: string | undefined): void => {
|
|
188
|
+
if (this.child !== child) return;
|
|
189
|
+
clearTimeout(drainTimer);
|
|
190
|
+
this.exitCode = code;
|
|
191
|
+
this.exitSignal = signal;
|
|
192
|
+
this.child = undefined;
|
|
193
|
+
for (const listener of this.exitListeners) {
|
|
194
|
+
try {
|
|
195
|
+
listener(code, signal);
|
|
196
|
+
} catch {
|
|
197
|
+
// A listener must never break capture teardown.
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
};
|
|
201
|
+
const beginDrain = (code: number | undefined, signal: string | undefined): void => {
|
|
202
|
+
if (this.child !== child || drainTimer) return;
|
|
203
|
+
drainTimer = setTimeout(() => {
|
|
204
|
+
this.error = `log drain timed out after ${MAX_DRAIN_MS}ms; pending logs may be truncated`;
|
|
205
|
+
finishing = true;
|
|
206
|
+
this.file = undefined;
|
|
207
|
+
for (const file of this.files) file.destroy();
|
|
208
|
+
this.files.clear();
|
|
209
|
+
this.blockedFiles.clear();
|
|
210
|
+
child.stdout?.destroy();
|
|
211
|
+
child.stderr?.destroy();
|
|
212
|
+
this.flush("out");
|
|
213
|
+
this.flush("err");
|
|
214
|
+
drainAbort.abort();
|
|
215
|
+
complete(code, signal);
|
|
216
|
+
}, MAX_DRAIN_MS);
|
|
217
|
+
};
|
|
218
|
+
const finish = (code: number | undefined, signal: string | undefined): void => {
|
|
219
|
+
if (this.child !== child || finishing) return;
|
|
220
|
+
finishing = true;
|
|
221
|
+
beginDrain(code, signal);
|
|
222
|
+
const writes = [...this.files].map((file) => {
|
|
223
|
+
const done = finished(file, { cleanup: true, signal: drainAbort.signal }).catch(() => {});
|
|
224
|
+
if (!file.writableEnded) file.end();
|
|
225
|
+
return done;
|
|
226
|
+
});
|
|
227
|
+
this.file = undefined;
|
|
228
|
+
void Promise.all(writes).then(() => complete(code, signal));
|
|
229
|
+
};
|
|
172
230
|
child.stdout?.setEncoding("utf8");
|
|
173
231
|
child.stderr?.setEncoding("utf8");
|
|
174
|
-
child.stdout?.on("data", (chunk: string) =>
|
|
175
|
-
|
|
232
|
+
child.stdout?.on("data", (chunk: string) => {
|
|
233
|
+
if (this.child === child) this.consume("out", chunk);
|
|
234
|
+
});
|
|
235
|
+
child.stderr?.on("data", (chunk: string) => {
|
|
236
|
+
if (this.child === child) this.consume("err", chunk);
|
|
237
|
+
});
|
|
176
238
|
child.on("error", (error: Error) => {
|
|
239
|
+
if (this.child !== child) return;
|
|
177
240
|
this.error = error.message;
|
|
178
241
|
this.pushLine("err", `[xcodebug] failed to start: ${error.message}`);
|
|
179
|
-
|
|
242
|
+
finish(undefined, undefined);
|
|
180
243
|
});
|
|
181
|
-
|
|
244
|
+
// `close` can itself wait forever while a backed-up writer pauses the pipes.
|
|
245
|
+
child.on("exit", (code, signal) => beginDrain(code ?? undefined, signal ?? undefined));
|
|
246
|
+
child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
|
|
247
|
+
if (this.child !== child) return;
|
|
182
248
|
this.flush("out");
|
|
183
249
|
this.flush("err");
|
|
184
|
-
|
|
250
|
+
finish(code ?? undefined, signal ?? undefined);
|
|
251
|
+
});
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
private openFile(append: boolean): void {
|
|
255
|
+
const path = this.fileNumber === 0 ? this.logFile : `${this.logFile}.${this.fileNumber}`;
|
|
256
|
+
const file = createWriteStream(path, { flags: append ? "a" : "w" });
|
|
257
|
+
this.file = file;
|
|
258
|
+
this.files.add(file);
|
|
259
|
+
const order = ++this.fileOrder;
|
|
260
|
+
file.once("open", () => {
|
|
261
|
+
if (!this.files.has(file) || file.destroyed) return;
|
|
262
|
+
if (order > (this.logFiles.get(path) ?? -1)) this.logFiles.set(path, order);
|
|
263
|
+
});
|
|
264
|
+
file.on("error", (error: Error) => {
|
|
265
|
+
if (!this.files.has(file)) return;
|
|
266
|
+
this.error = `log write failed: ${error.message}`;
|
|
267
|
+
if (this.file === file) this.file = undefined;
|
|
268
|
+
});
|
|
269
|
+
file.on("drain", () => {
|
|
270
|
+
this.blockedFiles.delete(file);
|
|
271
|
+
this.resume();
|
|
272
|
+
});
|
|
273
|
+
file.on("close", () => {
|
|
274
|
+
this.files.delete(file);
|
|
275
|
+
this.blockedFiles.delete(file);
|
|
276
|
+
this.resume();
|
|
185
277
|
});
|
|
186
278
|
}
|
|
187
279
|
|
|
280
|
+
private resume(): void {
|
|
281
|
+
if (this.blockedFiles.size > 0) return;
|
|
282
|
+
this.child?.stdout?.resume();
|
|
283
|
+
this.child?.stderr?.resume();
|
|
284
|
+
}
|
|
285
|
+
|
|
188
286
|
private consume(stream: "out" | "err", chunk: string): void {
|
|
189
287
|
const pending = this.buffered[stream] + chunk;
|
|
190
288
|
const parts = pending.split("\n");
|
|
@@ -205,9 +303,22 @@ export class Capture {
|
|
|
205
303
|
const line: LogLine = { index: ++this.cursor, at: Date.now(), stream, text };
|
|
206
304
|
// Every line proves the bridge is alive, whether or not it is being pushed.
|
|
207
305
|
this.lastLineAt = line.at;
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
306
|
+
// UTF-16 size is a conservative text bound even on engines storing Latin-1.
|
|
307
|
+
const bytes = text.length * 2;
|
|
308
|
+
if (bytes <= MAX_BUFFER_BYTES) {
|
|
309
|
+
while (this.lineCount === MAX_BUFFER_LINES || this.bufferBytes + bytes > MAX_BUFFER_BYTES) {
|
|
310
|
+
const oldest = this.lines[this.head]!;
|
|
311
|
+
this.bufferBytes -= oldest.text.length * 2;
|
|
312
|
+
this.lines[this.head] = undefined;
|
|
313
|
+
this.head = (this.head + 1) % MAX_BUFFER_LINES;
|
|
314
|
+
this.lineCount -= 1;
|
|
315
|
+
this.droppedLines += 1;
|
|
316
|
+
}
|
|
317
|
+
this.lines[(this.head + this.lineCount) % MAX_BUFFER_LINES] = line;
|
|
318
|
+
this.lineCount += 1;
|
|
319
|
+
this.bufferBytes += bytes;
|
|
320
|
+
} else {
|
|
321
|
+
// Still deliver and write an oversized line, without retaining it in memory.
|
|
211
322
|
this.droppedLines += 1;
|
|
212
323
|
}
|
|
213
324
|
for (const listener of this.lineListeners) {
|
|
@@ -217,25 +328,21 @@ export class Capture {
|
|
|
217
328
|
// A listener must never break capture.
|
|
218
329
|
}
|
|
219
330
|
}
|
|
220
|
-
if (this.file
|
|
331
|
+
if (this.file) {
|
|
221
332
|
const encoded = `${new Date(line.at).toISOString()} ${line.text}\n`;
|
|
222
|
-
|
|
223
|
-
this.
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
try {
|
|
236
|
-
listener(code, signal);
|
|
237
|
-
} catch {
|
|
238
|
-
// A listener must never break capture teardown.
|
|
333
|
+
const size = Buffer.byteLength(encoded);
|
|
334
|
+
if (this.fileBytes > 0 && this.fileBytes + size > MAX_FILE_BYTES) {
|
|
335
|
+
this.file.end();
|
|
336
|
+
this.fileNumber = (this.fileNumber + 1) % MAX_LOG_FILES;
|
|
337
|
+
this.fileBytes = 0;
|
|
338
|
+
this.openFile(false);
|
|
339
|
+
}
|
|
340
|
+
this.fileBytes += size;
|
|
341
|
+
const file = this.file;
|
|
342
|
+
if (!file.write(encoded)) {
|
|
343
|
+
this.blockedFiles.add(file);
|
|
344
|
+
this.child?.stdout?.pause();
|
|
345
|
+
this.child?.stderr?.pause();
|
|
239
346
|
}
|
|
240
347
|
}
|
|
241
348
|
}
|
|
@@ -293,14 +400,34 @@ export class Capture {
|
|
|
293
400
|
total: number;
|
|
294
401
|
} {
|
|
295
402
|
const since = Math.max(0, options.since ?? 0);
|
|
296
|
-
const limit = Math.min(Math.max(1, options.limit ?? 200), 5_000);
|
|
403
|
+
const limit = Math.trunc(Math.min(Math.max(1, options.limit ?? 200), 5_000));
|
|
297
404
|
const grep = options.grep?.trim();
|
|
298
405
|
const streams = options.streams;
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
406
|
+
// Locate the first eligible index without scanning or copying the buffer.
|
|
407
|
+
let first = 0;
|
|
408
|
+
let end = this.lineCount;
|
|
409
|
+
while (first < end) {
|
|
410
|
+
const middle = Math.floor((first + end) / 2);
|
|
411
|
+
if (this.lines[(this.head + middle) % MAX_BUFFER_LINES]!.index <= since) first = middle + 1;
|
|
412
|
+
else end = middle;
|
|
413
|
+
}
|
|
414
|
+
const lines: LogLine[] = [];
|
|
415
|
+
if (!grep && (!streams || streams.length === 0)) {
|
|
416
|
+
for (let i = Math.max(first, this.lineCount - limit); i < this.lineCount; i++) {
|
|
417
|
+
lines.push(this.lines[(this.head + i) % MAX_BUFFER_LINES]!);
|
|
418
|
+
}
|
|
419
|
+
return { lines, cursor: this.cursor, total: this.lineCount - first };
|
|
420
|
+
}
|
|
421
|
+
let total = 0;
|
|
422
|
+
for (let i = this.lineCount - 1; i >= first; i--) {
|
|
423
|
+
const line = this.lines[(this.head + i) % MAX_BUFFER_LINES]!;
|
|
424
|
+
if (streams && streams.length > 0 && !streams.includes(line.stream)) continue;
|
|
425
|
+
if (grep && !line.text.includes(grep)) continue;
|
|
426
|
+
total += 1;
|
|
427
|
+
if (lines.length < limit) lines.push(line);
|
|
428
|
+
}
|
|
429
|
+
lines.reverse();
|
|
430
|
+
return { lines, cursor: this.cursor, total };
|
|
304
431
|
}
|
|
305
432
|
|
|
306
433
|
status(): CaptureStatus {
|
|
@@ -320,6 +447,7 @@ export class Capture {
|
|
|
320
447
|
droppedLines: this.droppedLines,
|
|
321
448
|
cursor: this.cursor,
|
|
322
449
|
logFile: this.logFile,
|
|
450
|
+
logFiles: [...this.logFiles].sort((a, b) => a[1] - b[1]).map(([path]) => path),
|
|
323
451
|
commandLine: [this.command, ...this.launchArgs].join(" "),
|
|
324
452
|
error: this.error,
|
|
325
453
|
};
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
// Poll the existing connection, not a second server with different captures.
|
|
2
|
+
const SERVER = 'xcodebug';
|
|
3
|
+
// A literal, not built from SERVER: `claude plugin validate` reads the matcher statically.
|
|
4
|
+
const ACTION_TOOL = 'mcp__xcodebug__xcodebug';
|
|
5
|
+
const UI_TOOL = 'xcodebug_ui';
|
|
6
|
+
const POLL_MS = 1000;
|
|
7
|
+
// One failed read may be a blip; a server that stays down is not polled forever.
|
|
8
|
+
const MAX_FAILURES = 3;
|
|
9
|
+
const MAX_ERROR_CHARS = 160;
|
|
10
|
+
// The server repaints once a second while it shows anything, so a file whose
|
|
11
|
+
// `seq` stands still this many reads running belongs to a server that is gone.
|
|
12
|
+
const MAX_STALE_READS = 5;
|
|
13
|
+
// Actions that neither build nor start a capture, so they paint nothing new
|
|
14
|
+
// unless they carry a `command`, which runs as a phase of its own.
|
|
15
|
+
// Listed as exclusions so that an action added later shows by default.
|
|
16
|
+
const QUIET_ACTIONS = new Set(['doctor', 'devices', 'changes', 'status', 'logs', 'wait', 'stop', 'terminate']);
|
|
17
|
+
|
|
18
|
+
let rows = [];
|
|
19
|
+
let polling = false;
|
|
20
|
+
let timer;
|
|
21
|
+
let calls = 0;
|
|
22
|
+
let failures = 0;
|
|
23
|
+
let file;
|
|
24
|
+
let seq;
|
|
25
|
+
let stale = 0;
|
|
26
|
+
|
|
27
|
+
// A tool call runs the session's tool hooks, so only the first read of an
|
|
28
|
+
// activity asks the server; it names the file the server keeps the same
|
|
29
|
+
// snapshot in, and the reads after that come from there.
|
|
30
|
+
async function readServer($) {
|
|
31
|
+
const result = await $.mcp.call(SERVER, UI_TOOL, {});
|
|
32
|
+
if (result.isError) throw new Error(result.content.find(c => c.type === 'text')?.text ?? 'UI read failed');
|
|
33
|
+
const snapshot = JSON.parse(result.content.find(c => c.type === 'text')?.text ?? '{}');
|
|
34
|
+
// A server from before the file existed names none, and is asked every time.
|
|
35
|
+
file = snapshot.file;
|
|
36
|
+
seq = snapshot.seq;
|
|
37
|
+
stale = 0;
|
|
38
|
+
return snapshot;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async function readFile($) {
|
|
42
|
+
if (!file) return undefined;
|
|
43
|
+
try {
|
|
44
|
+
const snapshot = JSON.parse(await $.fs.read(file));
|
|
45
|
+
stale = snapshot.seq === seq ? stale + 1 : 0;
|
|
46
|
+
seq = snapshot.seq;
|
|
47
|
+
if (stale < MAX_STALE_READS) return snapshot;
|
|
48
|
+
} catch {
|
|
49
|
+
// Removed when its server exited; the server is asked instead, below.
|
|
50
|
+
}
|
|
51
|
+
file = undefined;
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
// The timer lives only while there is something to show: it ends once the
|
|
56
|
+
// server empties its snapshot (no build, no capture) or keeps failing.
|
|
57
|
+
function watch($) {
|
|
58
|
+
timer ??= $.clock.every(POLL_MS, async () => {
|
|
59
|
+
if (polling) return;
|
|
60
|
+
polling = true;
|
|
61
|
+
try {
|
|
62
|
+
const snapshot = await readFile($) ?? await readServer($);
|
|
63
|
+
rows = snapshot.rows?.length ? snapshot.rows : snapshot.status ? [snapshot.status] : [];
|
|
64
|
+
failures = 0;
|
|
65
|
+
} catch (error) {
|
|
66
|
+
rows = ['Xcodebug · live display unavailable', String(error.message ?? error).slice(0, MAX_ERROR_CHARS)];
|
|
67
|
+
failures += 1;
|
|
68
|
+
} finally {
|
|
69
|
+
polling = false;
|
|
70
|
+
}
|
|
71
|
+
// A call still in flight may not have painted its first status yet.
|
|
72
|
+
if (calls === 0 && (rows.length === 0 || failures >= MAX_FAILURES)) {
|
|
73
|
+
timer?.cancel();
|
|
74
|
+
timer = undefined;
|
|
75
|
+
rows = [];
|
|
76
|
+
failures = 0;
|
|
77
|
+
// The next activity may meet a restarted server, with a file of its own.
|
|
78
|
+
file = undefined;
|
|
79
|
+
}
|
|
80
|
+
$.ui.invalidate('ui.render');
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function register(on) {
|
|
85
|
+
// A capture outlives the module: a reload or a resumed session finds it here.
|
|
86
|
+
on('session.start', async ($, e, next) => {
|
|
87
|
+
watch($);
|
|
88
|
+
return next(e);
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
on('tool.call', { tool: ACTION_TOOL }, async ($, e, next) => {
|
|
92
|
+
if (QUIET_ACTIONS.has(e.action) && !e.command) return next(e);
|
|
93
|
+
// The server may have been replaced since the file was named; one killed
|
|
94
|
+
// while it showed something leaves that file behind, still naming it.
|
|
95
|
+
file = undefined;
|
|
96
|
+
watch($);
|
|
97
|
+
calls += 1;
|
|
98
|
+
try {
|
|
99
|
+
return await next(e);
|
|
100
|
+
} finally {
|
|
101
|
+
calls -= 1;
|
|
102
|
+
}
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
|
|
106
|
+
if (rows.length === 0) return next(e);
|
|
107
|
+
const { Box, Text } = $.ui.resolve(e);
|
|
108
|
+
return Box({
|
|
109
|
+
flexDirection: 'column',
|
|
110
|
+
children: rows.map(text => Text({ children: [text] })),
|
|
111
|
+
});
|
|
112
|
+
});
|
|
113
|
+
}
|