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
|
@@ -0,0 +1,321 @@
|
|
|
1
|
+
import { expect, mock, test } from 'claude-code/testing'
|
|
2
|
+
|
|
3
|
+
const BAND = {
|
|
4
|
+
plugin: 'xcodebug-live', component: 'AbovePrompt', surface: 'terminal',
|
|
5
|
+
viewport: { columns: 120, rows: 40 }, props: {},
|
|
6
|
+
} as const
|
|
7
|
+
|
|
8
|
+
const TOOL = 'mcp__xcodebug__xcodebug'
|
|
9
|
+
const LAUNCH = { tool: TOOL, action: 'launch' } as const
|
|
10
|
+
const QUIET_ACTIONS = ['doctor', 'devices', 'changes', 'status', 'logs', 'wait', 'stop', 'terminate']
|
|
11
|
+
const START = { surface: 'terminal', isInteractive: true, cwd: '/work' } as const
|
|
12
|
+
|
|
13
|
+
const reply = (snapshot: unknown) => ({ value: { content: [{ type: 'text', text: JSON.stringify(snapshot) }] } })
|
|
14
|
+
const failure = { value: { isError: true, content: [{ type: 'text', text: 'server unavailable' }] } }
|
|
15
|
+
|
|
16
|
+
test('an idle session reads the display once, then never again', async ($, on) => {
|
|
17
|
+
const clock = mock.clock(on)
|
|
18
|
+
let reads = 0
|
|
19
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
20
|
+
on('mcp.call', () => {
|
|
21
|
+
reads += 1
|
|
22
|
+
return reply({ rows: [] })
|
|
23
|
+
})
|
|
24
|
+
await $.session.start(START)
|
|
25
|
+
await clock.advance(5000)
|
|
26
|
+
expect(reads).toBe(1)
|
|
27
|
+
})
|
|
28
|
+
|
|
29
|
+
test('a capture already running when the session starts is shown', async ($, on) => {
|
|
30
|
+
const clock = mock.clock(on)
|
|
31
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
32
|
+
on('mcp.call', () => reply({ rows: ['capturing · 9 lines', 'earlier log'] }))
|
|
33
|
+
await $.session.start(START)
|
|
34
|
+
const ui = await $.ui.mount(BAND)
|
|
35
|
+
await clock.advance(1000)
|
|
36
|
+
expect(await ui.find({ type: 'Text', text: 'earlier log' })).toBeDefined()
|
|
37
|
+
})
|
|
38
|
+
|
|
39
|
+
test('an xcodebug call starts the display, and an empty snapshot ends it', async ($, on) => {
|
|
40
|
+
const clock = mock.clock(on)
|
|
41
|
+
let snapshot: { rows: string[] } = { rows: [] }
|
|
42
|
+
let reads = 0
|
|
43
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
44
|
+
on('tool.call', () => ({ result: {} }))
|
|
45
|
+
on('mcp.call', ($, e) => {
|
|
46
|
+
expect(e.server).toBe('xcodebug')
|
|
47
|
+
expect(e.tool).toBe('xcodebug_ui')
|
|
48
|
+
reads += 1
|
|
49
|
+
return reply(snapshot)
|
|
50
|
+
})
|
|
51
|
+
await $.session.start(START)
|
|
52
|
+
await clock.advance(1000)
|
|
53
|
+
reads = 0
|
|
54
|
+
|
|
55
|
+
snapshot = { rows: ['capturing · 1 line', 'first log'] }
|
|
56
|
+
await $.tool.call(LAUNCH)
|
|
57
|
+
const ui = await $.ui.mount(BAND)
|
|
58
|
+
await clock.advance(1000)
|
|
59
|
+
expect(await ui.find({ type: 'Text', text: 'first log' })).toBeDefined()
|
|
60
|
+
snapshot = { rows: ['capturing · 2 lines', 'second log'] }
|
|
61
|
+
await clock.advance(1000)
|
|
62
|
+
expect(await ui.find({ type: 'Text', text: 'second log' })).toBeDefined()
|
|
63
|
+
expect(await ui.find({ type: 'Text', text: 'first log' })).toBeUndefined()
|
|
64
|
+
snapshot = { rows: [] }
|
|
65
|
+
await clock.advance(1000)
|
|
66
|
+
expect(await ui.find({ type: 'Text', text: /capturing/ })).toBeUndefined()
|
|
67
|
+
expect(reads).toBe(3)
|
|
68
|
+
await clock.advance(5000)
|
|
69
|
+
expect(reads).toBe(3)
|
|
70
|
+
|
|
71
|
+
snapshot = { rows: ['capturing · 1 line', 'relaunched'] }
|
|
72
|
+
await $.tool.call(LAUNCH)
|
|
73
|
+
await clock.advance(1000)
|
|
74
|
+
expect(await ui.find({ type: 'Text', text: 'relaunched' })).toBeDefined()
|
|
75
|
+
})
|
|
76
|
+
|
|
77
|
+
test('a call still running keeps the display reading an empty snapshot', async ($, on) => {
|
|
78
|
+
const clock = mock.clock(on)
|
|
79
|
+
let reads = 0
|
|
80
|
+
let finish: (result: unknown) => void = () => {}
|
|
81
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
82
|
+
on('tool.call', () => new Promise(resolve => { finish = resolve }))
|
|
83
|
+
on('mcp.call', () => {
|
|
84
|
+
reads += 1
|
|
85
|
+
return reply({ rows: [] })
|
|
86
|
+
})
|
|
87
|
+
await $.session.start(START)
|
|
88
|
+
await clock.advance(1000)
|
|
89
|
+
reads = 0
|
|
90
|
+
|
|
91
|
+
const call = $.tool.call(LAUNCH)
|
|
92
|
+
await clock.advance(4000)
|
|
93
|
+
expect(reads).toBe(4)
|
|
94
|
+
finish({ result: {} })
|
|
95
|
+
await call
|
|
96
|
+
await clock.advance(5000)
|
|
97
|
+
expect(reads).toBe(5)
|
|
98
|
+
})
|
|
99
|
+
|
|
100
|
+
test('actions that paint nothing do not start the display', async ($, on) => {
|
|
101
|
+
const clock = mock.clock(on)
|
|
102
|
+
let reads = 0
|
|
103
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
104
|
+
on('tool.call', () => ({ result: {} }))
|
|
105
|
+
on('mcp.call', () => {
|
|
106
|
+
reads += 1
|
|
107
|
+
return reply({ rows: [] })
|
|
108
|
+
})
|
|
109
|
+
await $.session.start(START)
|
|
110
|
+
await clock.advance(1000)
|
|
111
|
+
reads = 0
|
|
112
|
+
|
|
113
|
+
for (const action of QUIET_ACTIONS) {
|
|
114
|
+
await $.tool.call({ tool: TOOL, action })
|
|
115
|
+
await clock.advance(2000)
|
|
116
|
+
}
|
|
117
|
+
expect(reads).toBe(0)
|
|
118
|
+
})
|
|
119
|
+
|
|
120
|
+
test('a quiet action that carries a command shows its phase, then stops', async ($, on) => {
|
|
121
|
+
const clock = mock.clock(on)
|
|
122
|
+
let snapshot: { rows: string[] } = { rows: [] }
|
|
123
|
+
let reads = 0
|
|
124
|
+
let finish: (result: unknown) => void = () => {}
|
|
125
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
126
|
+
on('tool.call', () => new Promise(resolve => { finish = resolve }))
|
|
127
|
+
on('mcp.call', () => {
|
|
128
|
+
reads += 1
|
|
129
|
+
return reply(snapshot)
|
|
130
|
+
})
|
|
131
|
+
await $.session.start(START)
|
|
132
|
+
await clock.advance(1000)
|
|
133
|
+
reads = 0
|
|
134
|
+
|
|
135
|
+
snapshot = { rows: ['Xcodebug · running', ' command: sleep 3'] }
|
|
136
|
+
const call = $.tool.call({ tool: TOOL, action: 'changes', command: 'sleep 3' })
|
|
137
|
+
const ui = await $.ui.mount(BAND)
|
|
138
|
+
await clock.advance(1000)
|
|
139
|
+
expect(await ui.find({ type: 'Text', text: /command: sleep 3/ })).toBeDefined()
|
|
140
|
+
snapshot = { rows: [] }
|
|
141
|
+
finish({ result: {} })
|
|
142
|
+
await call
|
|
143
|
+
await clock.advance(1000)
|
|
144
|
+
expect(await ui.find({ type: 'Text', text: /command: sleep 3/ })).toBeUndefined()
|
|
145
|
+
expect(reads).toBe(2)
|
|
146
|
+
await clock.advance(5000)
|
|
147
|
+
expect(reads).toBe(2)
|
|
148
|
+
})
|
|
149
|
+
|
|
150
|
+
test('a failed UI read removes stale logs and recovers on the next timer', async ($, on) => {
|
|
151
|
+
const clock = mock.clock(on)
|
|
152
|
+
let failed = false
|
|
153
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
154
|
+
on('tool.call', () => ({ result: {} }))
|
|
155
|
+
on('mcp.call', () => failed ? failure : reply({ rows: ['current log'] }))
|
|
156
|
+
await $.session.start(START)
|
|
157
|
+
await $.tool.call(LAUNCH)
|
|
158
|
+
const ui = await $.ui.mount(BAND)
|
|
159
|
+
await clock.advance(1000)
|
|
160
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeDefined()
|
|
161
|
+
failed = true
|
|
162
|
+
await clock.advance(1000)
|
|
163
|
+
expect(await ui.find({ type: 'Text', text: /live display unavailable/ })).toBeDefined()
|
|
164
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeUndefined()
|
|
165
|
+
failed = false
|
|
166
|
+
await clock.advance(1000)
|
|
167
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeDefined()
|
|
168
|
+
expect(await ui.find({ type: 'Text', text: /unavailable/ })).toBeUndefined()
|
|
169
|
+
// Failures apart from each other never add up to giving up.
|
|
170
|
+
failed = true
|
|
171
|
+
await clock.advance(2000)
|
|
172
|
+
failed = false
|
|
173
|
+
await clock.advance(1000)
|
|
174
|
+
expect(await ui.find({ type: 'Text', text: 'current log' })).toBeDefined()
|
|
175
|
+
})
|
|
176
|
+
|
|
177
|
+
test('a server that stays down is given up on, and the band clears', async ($, on) => {
|
|
178
|
+
const clock = mock.clock(on)
|
|
179
|
+
let reads = 0
|
|
180
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
181
|
+
on('tool.call', () => ({ result: {} }))
|
|
182
|
+
on('mcp.call', () => {
|
|
183
|
+
reads += 1
|
|
184
|
+
return failure
|
|
185
|
+
})
|
|
186
|
+
await $.session.start(START)
|
|
187
|
+
await $.tool.call(LAUNCH)
|
|
188
|
+
const ui = await $.ui.mount(BAND)
|
|
189
|
+
await clock.advance(1000)
|
|
190
|
+
expect(await ui.find({ type: 'Text', text: /live display unavailable/ })).toBeDefined()
|
|
191
|
+
await clock.advance(30000)
|
|
192
|
+
expect(reads).toBe(3)
|
|
193
|
+
expect(await ui.find({ type: 'Text', text: /unavailable/ })).toBeUndefined()
|
|
194
|
+
})
|
|
195
|
+
|
|
196
|
+
const FILE = '/agent/ui/42.json'
|
|
197
|
+
|
|
198
|
+
test('one tool call per activity: later reads come from the snapshot file', async ($, on) => {
|
|
199
|
+
const clock = mock.clock(on)
|
|
200
|
+
let snapshot = { rows: [] as string[], seq: 0 }
|
|
201
|
+
let toolReads = 0
|
|
202
|
+
let fileReads = 0
|
|
203
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
204
|
+
on('tool.call', () => ({ result: {} }))
|
|
205
|
+
on('mcp.call', () => {
|
|
206
|
+
toolReads += 1
|
|
207
|
+
return reply({ ...snapshot, file: FILE })
|
|
208
|
+
})
|
|
209
|
+
on('fs.read', ($, e) => {
|
|
210
|
+
expect(e.path).toBe(FILE)
|
|
211
|
+
fileReads += 1
|
|
212
|
+
return { value: JSON.stringify(snapshot) }
|
|
213
|
+
})
|
|
214
|
+
await $.session.start(START)
|
|
215
|
+
await clock.advance(1000)
|
|
216
|
+
toolReads = 0
|
|
217
|
+
fileReads = 0
|
|
218
|
+
|
|
219
|
+
const ui = await $.ui.mount(BAND)
|
|
220
|
+
for (const round of ['first', 'second']) {
|
|
221
|
+
snapshot = { rows: [`capturing · ${round}`], seq: snapshot.seq + 1 }
|
|
222
|
+
await $.tool.call(LAUNCH)
|
|
223
|
+
await clock.advance(1000)
|
|
224
|
+
expect(await ui.find({ type: 'Text', text: `capturing · ${round}` })).toBeDefined()
|
|
225
|
+
for (let tick = 0; tick < 10; tick++) {
|
|
226
|
+
snapshot = { rows: [`capturing · ${round} · ${tick}`], seq: snapshot.seq + 1 }
|
|
227
|
+
await clock.advance(1000)
|
|
228
|
+
expect(await ui.find({ type: 'Text', text: `capturing · ${round} · ${tick}` })).toBeDefined()
|
|
229
|
+
}
|
|
230
|
+
snapshot = { rows: [], seq: snapshot.seq + 1 }
|
|
231
|
+
await clock.advance(1000)
|
|
232
|
+
expect(await ui.find({ type: 'Text', text: /capturing/ })).toBeUndefined()
|
|
233
|
+
await clock.advance(5000)
|
|
234
|
+
}
|
|
235
|
+
expect(toolReads).toBe(2)
|
|
236
|
+
expect(fileReads).toBe(22)
|
|
237
|
+
})
|
|
238
|
+
|
|
239
|
+
test('a snapshot file that stops changing sends the next read to the server', async ($, on) => {
|
|
240
|
+
const clock = mock.clock(on)
|
|
241
|
+
let toolReads = 0
|
|
242
|
+
let down = false
|
|
243
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
244
|
+
on('tool.call', () => ({ result: {} }))
|
|
245
|
+
on('mcp.call', () => {
|
|
246
|
+
toolReads += 1
|
|
247
|
+
return down ? failure : reply({ rows: ['capturing · stuck'], seq: 7, file: FILE })
|
|
248
|
+
})
|
|
249
|
+
// The server died without clearing its file: same seq on every read.
|
|
250
|
+
on('fs.read', () => ({ value: JSON.stringify({ rows: ['capturing · stuck'], seq: 7 }) }))
|
|
251
|
+
await $.session.start(START)
|
|
252
|
+
await $.tool.call(LAUNCH)
|
|
253
|
+
const ui = await $.ui.mount(BAND)
|
|
254
|
+
await clock.advance(1000)
|
|
255
|
+
toolReads = 0
|
|
256
|
+
down = true
|
|
257
|
+
await clock.advance(4000)
|
|
258
|
+
expect(toolReads).toBe(0)
|
|
259
|
+
expect(await ui.find({ type: 'Text', text: 'capturing · stuck' })).toBeDefined()
|
|
260
|
+
await clock.advance(30000)
|
|
261
|
+
expect(toolReads).toBe(3)
|
|
262
|
+
expect(await ui.find({ type: 'Text', text: /stuck|unavailable/ })).toBeUndefined()
|
|
263
|
+
})
|
|
264
|
+
|
|
265
|
+
test('a snapshot file that cannot be read sends that read to the server', async ($, on) => {
|
|
266
|
+
const clock = mock.clock(on)
|
|
267
|
+
let toolReads = 0
|
|
268
|
+
let gone = false
|
|
269
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
270
|
+
on('tool.call', () => ({ result: {} }))
|
|
271
|
+
on('mcp.call', () => {
|
|
272
|
+
toolReads += 1
|
|
273
|
+
return reply({ rows: [`from the server · ${toolReads}`], seq: toolReads, file: FILE })
|
|
274
|
+
})
|
|
275
|
+
on('fs.read', () => {
|
|
276
|
+
if (gone) throw new Error('ENOENT')
|
|
277
|
+
return { value: JSON.stringify({ rows: ['from the file'], seq: 100 }) }
|
|
278
|
+
})
|
|
279
|
+
await $.session.start(START)
|
|
280
|
+
await $.tool.call(LAUNCH)
|
|
281
|
+
const ui = await $.ui.mount(BAND)
|
|
282
|
+
await clock.advance(2000)
|
|
283
|
+
expect(await ui.find({ type: 'Text', text: 'from the file' })).toBeDefined()
|
|
284
|
+
gone = true
|
|
285
|
+
toolReads = 0
|
|
286
|
+
await clock.advance(1000)
|
|
287
|
+
expect(toolReads).toBe(1)
|
|
288
|
+
expect(await ui.find({ type: 'Text', text: /from the server/ })).toBeDefined()
|
|
289
|
+
expect(await ui.find({ type: 'Text', text: /unavailable/ })).toBeUndefined()
|
|
290
|
+
})
|
|
291
|
+
|
|
292
|
+
test('a call while the display runs asks the server again, in case it was replaced', async ($, on) => {
|
|
293
|
+
const clock = mock.clock(on)
|
|
294
|
+
const OLD = '/agent/ui/1.json'
|
|
295
|
+
const NEW = '/agent/ui/2.json'
|
|
296
|
+
let server = { rows: ['old capture'], seq: 1, file: OLD }
|
|
297
|
+
let oldSeq = 1
|
|
298
|
+
let oldServerRuns = true
|
|
299
|
+
let newSeq = 1
|
|
300
|
+
on('session.start', () => ({ cwd: '/work' }))
|
|
301
|
+
on('tool.call', () => ({ result: {} }))
|
|
302
|
+
on('mcp.call', () => reply(server))
|
|
303
|
+
on('fs.read', ($, e) => ({
|
|
304
|
+
value: JSON.stringify(e.path === OLD
|
|
305
|
+
? { rows: ['old capture'], seq: oldServerRuns ? ++oldSeq : oldSeq }
|
|
306
|
+
: { rows: ['new build'], seq: ++newSeq }),
|
|
307
|
+
}))
|
|
308
|
+
await $.session.start(START)
|
|
309
|
+
await $.tool.call(LAUNCH)
|
|
310
|
+
const ui = await $.ui.mount(BAND)
|
|
311
|
+
await clock.advance(3000)
|
|
312
|
+
expect(await ui.find({ type: 'Text', text: 'old capture' })).toBeDefined()
|
|
313
|
+
|
|
314
|
+
// The old server was killed and left its file; the connection now reaches a new one.
|
|
315
|
+
oldServerRuns = false
|
|
316
|
+
server = { rows: ['new build'], seq: 1, file: NEW }
|
|
317
|
+
await $.tool.call(LAUNCH)
|
|
318
|
+
await clock.advance(1000)
|
|
319
|
+
expect(await ui.find({ type: 'Text', text: 'new build' })).toBeDefined()
|
|
320
|
+
expect(await ui.find({ type: 'Text', text: 'old capture' })).toBeUndefined()
|
|
321
|
+
})
|
package/index.ts
CHANGED
|
@@ -26,6 +26,7 @@ import { clearArchives } from "./archive.ts";
|
|
|
26
26
|
const CAPTURE_PREFIX = "xcodebug";
|
|
27
27
|
const PUSH_INTERVAL_MS = 4_000;
|
|
28
28
|
const PUSH_MAX_LINES = 80;
|
|
29
|
+
const MAX_ENDED_CAPTURES = 10;
|
|
29
30
|
/** How long a verification run may go quiet before we ask the user about it. */
|
|
30
31
|
const SILENCE_NOTICE_MS = 60_000;
|
|
31
32
|
/**
|
|
@@ -51,6 +52,8 @@ interface ProjectConfig {
|
|
|
51
52
|
|
|
52
53
|
interface SessionState {
|
|
53
54
|
captures: Map<string, Capture>;
|
|
55
|
+
/** Permanently ended captures, ordered by completion time for bounded history. */
|
|
56
|
+
endedCaptures: Set<string>;
|
|
54
57
|
activeCaptureId?: string;
|
|
55
58
|
pushTimers: Map<string, ReturnType<typeof setInterval>>;
|
|
56
59
|
pushCursors: Map<string, number>;
|
|
@@ -751,6 +754,7 @@ type ToolParams = {
|
|
|
751
754
|
export default function xcodebug(pi: ExtensionAPI): void {
|
|
752
755
|
const state: SessionState = {
|
|
753
756
|
captures: new Map(),
|
|
757
|
+
endedCaptures: new Set(),
|
|
754
758
|
pushTimers: new Map(),
|
|
755
759
|
pushCursors: new Map(),
|
|
756
760
|
companions: new Map(),
|
|
@@ -763,19 +767,13 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
763
767
|
/**
|
|
764
768
|
* Paint the live verification state: a footer line that is always visible and
|
|
765
769
|
* a widget above the editor with the most recent log lines. Both are cleared
|
|
766
|
-
* when no capture is running, so a finished task leaves no stale chrome.
|
|
770
|
+
* when no operation or capture is running, so a finished task leaves no stale chrome.
|
|
767
771
|
*/
|
|
768
772
|
const refreshStatus = (): void => {
|
|
769
773
|
const ctx = state.uiCtx;
|
|
770
774
|
if (!ctx?.hasUI) return;
|
|
771
|
-
const
|
|
772
|
-
if (
|
|
773
|
-
const phase = state.runPhase;
|
|
774
|
-
if (!phase) {
|
|
775
|
-
ctx.ui.setStatus("xcodebug", undefined);
|
|
776
|
-
ctx.ui.setWidget("xcodebug", undefined);
|
|
777
|
-
return;
|
|
778
|
-
}
|
|
775
|
+
const phase = state.runPhase;
|
|
776
|
+
if (phase) {
|
|
779
777
|
const secs = Math.round((Date.now() - phase.startedAt) / 1000);
|
|
780
778
|
ctx.ui.setStatus("xcodebug", `🔨 xcodebug · ${phase.label} · ${secs}s`);
|
|
781
779
|
ctx.ui.setWidget("xcodebug", ["Xcodebug · running", ` ${phase.label}`, ` ${secs}s`], {
|
|
@@ -783,6 +781,12 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
783
781
|
});
|
|
784
782
|
return;
|
|
785
783
|
}
|
|
784
|
+
const running = [...state.captures.values()].filter((c) => c.running);
|
|
785
|
+
if (running.length === 0) {
|
|
786
|
+
ctx.ui.setStatus("xcodebug", undefined);
|
|
787
|
+
ctx.ui.setWidget("xcodebug", undefined);
|
|
788
|
+
return;
|
|
789
|
+
}
|
|
786
790
|
|
|
787
791
|
// Prefer a channel that is actually pushing: a push=off capture shows no
|
|
788
792
|
// lines in the widget, so featuring it would misreport the run as silent.
|
|
@@ -870,11 +874,7 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
870
874
|
refreshStatus();
|
|
871
875
|
};
|
|
872
876
|
|
|
873
|
-
/**
|
|
874
|
-
* Release everything tied to a capture. Called from every path that ends one
|
|
875
|
-
* (explicit stop, app exit, shutdown) so per-capture bookkeeping cannot pile
|
|
876
|
-
* up across repeated launches in one session.
|
|
877
|
-
*/
|
|
877
|
+
/** Release live bookkeeping and retain only the most recent ended captures. */
|
|
878
878
|
const releaseCapture = (capture: Capture): void => {
|
|
879
879
|
stopPush(capture.id);
|
|
880
880
|
stopWatchdog(capture.id);
|
|
@@ -883,8 +883,12 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
883
883
|
state.lastLineAt.delete(capture.id);
|
|
884
884
|
state.silenceNotified.delete(capture.id);
|
|
885
885
|
state.pushCursors.delete(capture.id);
|
|
886
|
-
|
|
887
|
-
|
|
886
|
+
state.endedCaptures.add(capture.id);
|
|
887
|
+
while (state.endedCaptures.size > MAX_ENDED_CAPTURES) {
|
|
888
|
+
const oldest = state.endedCaptures.values().next().value!;
|
|
889
|
+
state.endedCaptures.delete(oldest);
|
|
890
|
+
state.captures.delete(oldest);
|
|
891
|
+
}
|
|
888
892
|
if (state.activeCaptureId === capture.id) state.activeCaptureId = undefined;
|
|
889
893
|
if (![...state.captures.values()].some((c) => c.running)) stopStatusTicker();
|
|
890
894
|
refreshStatus();
|
|
@@ -936,8 +940,7 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
936
940
|
// The syslog channel is a companion of the console capture; stop it too so
|
|
937
941
|
// one "stop" does not leave a second bridge running.
|
|
938
942
|
unlinkCompanion(capture);
|
|
939
|
-
//
|
|
940
|
-
// but the push bookkeeping is finished and must not linger.
|
|
943
|
+
// Recent ended captures remain readable, but their live bookkeeping must stop.
|
|
941
944
|
state.recentLines.delete(capture.id);
|
|
942
945
|
state.lastLineAt.delete(capture.id);
|
|
943
946
|
state.silenceNotified.delete(capture.id);
|
|
@@ -1135,7 +1138,7 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
1135
1138
|
// healthy, and losing it silently would leave the console channel with no
|
|
1136
1139
|
// backup - exactly the gap dual-channel exists to cover.
|
|
1137
1140
|
if (capture.stoppedByUser) {
|
|
1138
|
-
|
|
1141
|
+
releaseCapture(capture);
|
|
1139
1142
|
return;
|
|
1140
1143
|
}
|
|
1141
1144
|
// Always hand off. If a reconnect loop is already running it returns at
|
|
@@ -1557,6 +1560,7 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
1557
1560
|
const device = await resolveDeviceParam(params.device, projectRoot);
|
|
1558
1561
|
const appPath = params.appPath;
|
|
1559
1562
|
if (!appPath) throw new Error("install requires appPath (or use action=build first).");
|
|
1563
|
+
setRunPhase(`installing on ${device.name}`);
|
|
1560
1564
|
const outcome = await installApp(device, appPath, { timeoutMs: (params.timeoutSeconds ?? 180) * 1000, signal });
|
|
1561
1565
|
return {
|
|
1562
1566
|
content: [{ type: "text", text: `${outcome.message}\napp: ${appPath}\ndevice: ${device.name}` }],
|
|
@@ -2278,6 +2282,7 @@ export default function xcodebug(pi: ExtensionAPI): void {
|
|
|
2278
2282
|
capture.stop(false);
|
|
2279
2283
|
}
|
|
2280
2284
|
state.captures.clear();
|
|
2285
|
+
state.endedCaptures.clear();
|
|
2281
2286
|
state.activeCaptureId = undefined;
|
|
2282
2287
|
});
|
|
2283
2288
|
}
|
package/mcp/server.ts
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
* needed (initialize, tools/list, tools/call); the official SDK would add ~97
|
|
19
19
|
* transitive packages to every install, including the pi users who never run MCP.
|
|
20
20
|
*/
|
|
21
|
-
import { readFileSync } from "node:fs";
|
|
21
|
+
import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
22
22
|
import { homedir } from "node:os";
|
|
23
23
|
import { join } from "node:path";
|
|
24
24
|
import { createInterface } from "node:readline";
|
|
@@ -29,7 +29,7 @@ interface ExtensionContextLike {
|
|
|
29
29
|
agentDir: string;
|
|
30
30
|
/** The status ticker in index.ts only runs when this is set. */
|
|
31
31
|
hasUI?: boolean;
|
|
32
|
-
ui: { notify(): void; setStatus(key: string, text?: string): void; setWidget(): void };
|
|
32
|
+
ui: { notify(): void; setStatus(key: string, text?: string): void; setWidget(key: string, rows?: string[]): void };
|
|
33
33
|
}
|
|
34
34
|
|
|
35
35
|
interface ToolResult {
|
|
@@ -96,6 +96,63 @@ if (!registered) {
|
|
|
96
96
|
}
|
|
97
97
|
const tool = registered;
|
|
98
98
|
|
|
99
|
+
// The native Claude mod reads this without joining the mutating action queue.
|
|
100
|
+
// Keep the last repaint alive after tools/call ends; only progress is request-scoped.
|
|
101
|
+
const uiSnapshot: { status?: string; rows: string[] } = { rows: [] };
|
|
102
|
+
|
|
103
|
+
// Every xcodebug_ui call runs the client's tool hooks, so a mod that polled it
|
|
104
|
+
// once a second ran them once a second for as long as a capture lived. The same
|
|
105
|
+
// snapshot goes to a file the mod reads between calls. One file per process:
|
|
106
|
+
// several sessions each run their own server.
|
|
107
|
+
const UI_DIR = join(AGENT_DIR, "ui");
|
|
108
|
+
let uiFile: string | undefined = join(UI_DIR, `${process.pid}.json`);
|
|
109
|
+
// Advances on every repaint, which happens once a second while anything is
|
|
110
|
+
// shown; a reader that sees it stand still knows this process stopped painting.
|
|
111
|
+
let uiSeq = 0;
|
|
112
|
+
|
|
113
|
+
function publishUi(): void {
|
|
114
|
+
if (!uiFile) return;
|
|
115
|
+
uiSeq += 1;
|
|
116
|
+
try {
|
|
117
|
+
mkdirSync(UI_DIR, { recursive: true });
|
|
118
|
+
// Renamed into place so a reader never sees half a snapshot.
|
|
119
|
+
writeFileSync(`${uiFile}.tmp`, JSON.stringify({ ...uiSnapshot, seq: uiSeq }));
|
|
120
|
+
renameSync(`${uiFile}.tmp`, uiFile);
|
|
121
|
+
} catch (error) {
|
|
122
|
+
// A repaint must not take the action down with it. Without the file the
|
|
123
|
+
// mod is told nothing about it and keeps calling xcodebug_ui.
|
|
124
|
+
console.error("xcodebug-mcp: live display file unavailable:", (error as Error).message);
|
|
125
|
+
uiFile = undefined;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
publishUi();
|
|
129
|
+
process.on("exit", () => {
|
|
130
|
+
if (uiFile) rmSync(uiFile, { force: true });
|
|
131
|
+
});
|
|
132
|
+
// Claude Code ends a stdio server with SIGINT. Left to the default, a signal
|
|
133
|
+
// ends the process without the handler above; the exit codes are the shell's.
|
|
134
|
+
process.on("SIGINT", () => process.exit(130));
|
|
135
|
+
process.on("SIGTERM", () => process.exit(143));
|
|
136
|
+
// A server that was killed outright never ran it either. Its file is named after
|
|
137
|
+
// a process that no longer exists, which is how the next server to start finds it.
|
|
138
|
+
try {
|
|
139
|
+
for (const name of readdirSync(UI_DIR)) {
|
|
140
|
+
try {
|
|
141
|
+
process.kill(Number.parseInt(name, 10), 0);
|
|
142
|
+
} catch (error) {
|
|
143
|
+
if ((error as NodeJS.ErrnoException).code === "ESRCH") rmSync(join(UI_DIR, name), { force: true });
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
} catch {
|
|
147
|
+
// No directory to sweep: publishUi() could not create it and said so.
|
|
148
|
+
}
|
|
149
|
+
const uiTool = {
|
|
150
|
+
name: "xcodebug_ui",
|
|
151
|
+
description: "Read the current display snapshot for the xcodebug Claude Code mod. For capture details or log analysis use xcodebug with action=status or action=logs.",
|
|
152
|
+
inputSchema: { type: "object", properties: {}, additionalProperties: false },
|
|
153
|
+
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
|
|
154
|
+
};
|
|
155
|
+
|
|
99
156
|
function sendNotification(method: string, params: unknown): void {
|
|
100
157
|
process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
|
|
101
158
|
}
|
|
@@ -121,9 +178,14 @@ function makeCtx(progressToken: unknown): { ctx: ExtensionContextLike; close():
|
|
|
121
178
|
ui: {
|
|
122
179
|
notify() {},
|
|
123
180
|
setStatus(_key, text) {
|
|
181
|
+
uiSnapshot.status = text;
|
|
182
|
+
publishUi();
|
|
124
183
|
report(text);
|
|
125
184
|
},
|
|
126
|
-
setWidget() {
|
|
185
|
+
setWidget(_key, rows) {
|
|
186
|
+
uiSnapshot.rows = rows ?? [];
|
|
187
|
+
publishUi();
|
|
188
|
+
},
|
|
127
189
|
},
|
|
128
190
|
},
|
|
129
191
|
// The status ticker keeps running while a capture is alive, which outlives
|
|
@@ -187,7 +249,7 @@ async function handle(message: Record<string, unknown>): Promise<void> {
|
|
|
187
249
|
return;
|
|
188
250
|
}
|
|
189
251
|
if (method === "tools/list") {
|
|
190
|
-
reply(id, { tools: [{ name: "xcodebug", description: tool.description, inputSchema }] });
|
|
252
|
+
reply(id, { tools: [{ name: "xcodebug", description: tool.description, inputSchema }, uiTool] });
|
|
191
253
|
return;
|
|
192
254
|
}
|
|
193
255
|
if (method === "tools/call") {
|
|
@@ -231,6 +293,17 @@ createInterface({ input: process.stdin }).on("line", (line) => {
|
|
|
231
293
|
replyError(null, -32700, "Parse error");
|
|
232
294
|
return;
|
|
233
295
|
}
|
|
296
|
+
// UI reads must remain responsive during a build/install/wait and must never
|
|
297
|
+
// replace state.uiCtx with the context of a polling call.
|
|
298
|
+
if (message.method === "tools/call" &&
|
|
299
|
+
(message.params as { name?: string } | undefined)?.name === uiTool.name) {
|
|
300
|
+
if (message.id !== undefined) {
|
|
301
|
+
reply(message.id, {
|
|
302
|
+
content: [{ type: "text", text: JSON.stringify({ ...uiSnapshot, seq: uiSeq, file: uiFile }) }],
|
|
303
|
+
});
|
|
304
|
+
}
|
|
305
|
+
return;
|
|
306
|
+
}
|
|
234
307
|
// Handled here rather than in handle(): the queue serializes calls, so a
|
|
235
308
|
// cancellation queued behind the very call it targets could never arrive in
|
|
236
309
|
// time. It is a notification, so nothing is sent back.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xcodebug",
|
|
3
|
-
"version": "1.1
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Build, install and launch an iOS app on a physical device and read its console inside the agent session (pi / omp extension)",
|
|
6
6
|
"keywords": [
|
|
@@ -28,6 +28,8 @@
|
|
|
28
28
|
"files": [
|
|
29
29
|
"*.ts",
|
|
30
30
|
"mcp/",
|
|
31
|
+
"skills/",
|
|
32
|
+
"claude/",
|
|
31
33
|
"README.md",
|
|
32
34
|
"GUIDE.md",
|
|
33
35
|
"LICENSE"
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: xcodebug
|
|
3
|
+
description: "Builds, launches, and captures console logs from physical iOS devices through the xcodebug MCP server. Use when the user invokes xcodebug, requests its doctor/devices/status/logs/wait/stop/restart actions, or wants to verify an iOS app on a real device using its console."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# xcodebug
|
|
7
|
+
|
|
8
|
+
Use the **existing xcodebug MCP connection**. Its tool is named `xcodebug`
|
|
9
|
+
(Claude Code: `mcp__xcodebug__xcodebug`; Codex may display `xcodebug.xcodebug`).
|
|
10
|
+
Do not run an `xcodebug` shell command or start another MCP server: captures and
|
|
11
|
+
restart settings belong to the connected server process. If the tool is absent,
|
|
12
|
+
report that the xcodebug MCP connection must be configured first.
|
|
13
|
+
|
|
14
|
+
## Dispatch the request
|
|
15
|
+
|
|
16
|
+
Read the request following `/xcodebug` in Claude Code or `$xcodebug` in Codex.
|
|
17
|
+
Both explicit invocation and a matching natural-language request can use this skill.
|
|
18
|
+
|
|
19
|
+
- With no arguments, call `{"action":"launch"}` once to build as needed, install,
|
|
20
|
+
launch and start capturing with the server's defaults. Keep the capture running;
|
|
21
|
+
report a launch error without substituting a status query or another action.
|
|
22
|
+
- For `status`, call `{"action":"status"}` to inspect captures without launching.
|
|
23
|
+
- For an explicit action, call the MCP tool with that action and the supplied
|
|
24
|
+
parameters immediately. Do not replace execution with instructions for the user.
|
|
25
|
+
- Accept `action [key=value ...]`, `action=... [key=value ...]`, or a JSON parameter
|
|
26
|
+
object. Actions: `doctor`, `devices`, `changes`, `build`, `install`, `launch`,
|
|
27
|
+
`syslog`, `logs`, `wait`, `status`, `stop`, `terminate`, `restart`, `await`.
|
|
28
|
+
- Use the live tool schema for parameter names and types. Preserve quoted strings,
|
|
29
|
+
numeric `since`/`limit`/`timeoutSeconds`, booleans, JSON `args` arrays and
|
|
30
|
+
`environment` objects. Keep a supplied `command` shell line intact.
|
|
31
|
+
- Omit unspecified parameters so the server can apply its project configuration.
|
|
32
|
+
MCP supports pull reads: omit `push` or use `push="off"`; `context` and `wake`
|
|
33
|
+
are unsupported. Explain an unsupported explicit value instead of changing it silently.
|
|
34
|
+
- For an explicit action, make exactly one xcodebug MCP call, report its result,
|
|
35
|
+
and stop, including on error. Do not add diagnostic `status` calls or retry
|
|
36
|
+
with another action unless the user asks. `logs` never authorizes launching
|
|
37
|
+
an app, and `launch` does not imply an immediate `stop`.
|
|
38
|
+
- For a natural-language verification goal, use `launch` with known project/device
|
|
39
|
+
parameters, then collect evidence for that goal. The goal describes what to
|
|
40
|
+
verify; do not use the entire sentence as a literal log filter. If the app must
|
|
41
|
+
keep running, use `syslog` with its known process name instead of `launch`.
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
| Request after the skill name | MCP arguments |
|
|
46
|
+
|---|---|
|
|
47
|
+
| *(no arguments)* | `{"action":"launch"}` |
|
|
48
|
+
| `status` | `{"action":"status"}` |
|
|
49
|
+
| `doctor` | `{"action":"doctor"}` |
|
|
50
|
+
| `launch scheme=MyApp device="My iPhone"` | `{"action":"launch","scheme":"MyApp","device":"My iPhone"}` |
|
|
51
|
+
| `logs captureId=console-123 since=42 limit=100 grep="Weather Sync"` | `{"action":"logs","captureId":"console-123","since":42,"limit":100,"grep":"Weather Sync"}` |
|
|
52
|
+
| `wait match="sync complete" timeoutSeconds=30` | `{"action":"wait","match":"sync complete","timeoutSeconds":30}` |
|
|
53
|
+
| `stop captureId=console-123 keepApp=true` | `{"action":"stop","captureId":"console-123","keepApp":true}` |
|
|
54
|
+
| `restart` | `{"action":"restart"}` |
|
|
55
|
+
|
|
56
|
+
## Follow a capture
|
|
57
|
+
|
|
58
|
+
- `launch` restarts the app and captures stdout/stderr plus os_log. `syslog`
|
|
59
|
+
attaches without restarting. `stop` leaves the app running by default;
|
|
60
|
+
`terminate` explicitly terminates it. `restart` reuses this server's last launch
|
|
61
|
+
and forces a rebuild; a saved `command` runs again.
|
|
62
|
+
- Track `captureId` and the returned cursor **per capture**. Pass that cursor as
|
|
63
|
+
`since` on the next incremental read; never reuse another capture's cursor.
|
|
64
|
+
`logs` returns the newest matching lines up to `limit` and advances to the
|
|
65
|
+
latest capture cursor, so omitted or evicted lines will not reappear merely
|
|
66
|
+
by advancing `since`. Report omissions instead of claiming a lossless stream.
|
|
67
|
+
- Use bounded `wait` for an expected line. An empty read or quiet log is not proof
|
|
68
|
+
that a test finished. While waiting for the user to operate the phone, tell them
|
|
69
|
+
the required action and keep the capture running.
|
|
70
|
+
- For an automated scenario, pass the user's `command` to `launch`, or use `await`
|
|
71
|
+
with the current capture. The command must not relaunch the app itself, since
|
|
72
|
+
that would break the console bridge. Use the returned exit code and logs as evidence.
|
|
73
|
+
- When a verification goal is answered, stop the capture started for that goal.
|
|
74
|
+
Include its `captureId` so other captures are not stopped. An explicit `stop`
|
|
75
|
+
without an ID intentionally stops all running captures in this server.
|
|
76
|
+
- Report the operation's result, relevant log evidence, capture ID/cursor or log
|
|
77
|
+
path when returned, and whether capture remains active. Do not invent device
|
|
78
|
+
activity, successful builds, or test outcomes.
|