xcodebug 1.2.1 → 1.2.2

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 CHANGED
@@ -215,6 +215,7 @@ xcodebug action=restart # after editing: rebuild + relaunch +
215
215
  xcodebug action=logs limit=200
216
216
  xcodebug action=logs grep=MySDK
217
217
  xcodebug action=wait match="DataPacket" timeoutSeconds=30
218
+ xcodebug action=wait match="sync (done|failed)" regex=true # either outcome, one wait
218
219
 
219
220
  # wrap up
220
221
  xcodebug action=status
@@ -244,6 +245,10 @@ pending writes; a drain timeout can truncate logs. Neither memory nor disk is
244
245
  a lossless archive of the whole run. See [retention](README.md#reading-logs-from-a-cursor)
245
246
  and [disk files](README.md#files) for details and the `logFiles` path list.
246
247
 
248
+ A filtered read (`logs grep=`, `wait`) looks in those files for the lines memory
249
+ has dropped and says in its reply that it did. Logs are deleted 30 days after
250
+ their last write.
251
+
247
252
  ## Three rules of use
248
253
 
249
254
  1. **Stop once the log has answered the question.** A capture left running keeps
@@ -251,5 +256,7 @@ and [disk files](README.md#files) for details and the `logFiles` path list.
251
256
  2. **Do not stop while the user has not acted yet.** Silence there means "not
252
257
  tried yet", not "finished" — say what to tap and keep listening.
253
258
  3. **A console capture ends when the app process is confirmed gone.** Its syslog
254
- companion is stopped too. A standalone `syslog` capture is not bound to the
255
- app's lifetime and keeps reconnecting; stop it explicitly when finished.
259
+ companion is stopped too, and `status` says why it ended and where the crash
260
+ report is, if the device wrote one. A standalone `syslog` capture is not
261
+ bound to the app's lifetime and keeps reconnecting; stop it explicitly when
262
+ finished.
package/README.md CHANGED
@@ -92,6 +92,30 @@ codex mcp list # xcodebug bun …
92
92
  claude mcp list # xcodebug: … ✔ Connected
93
93
  ```
94
94
 
95
+ Set Codex's MCP timeout high enough for the stages your calls use. For example,
96
+ 4200 seconds leaves room for the default 15-minute pod install, 15-minute build
97
+ and 30-minute command budgets, plus device operations. Increase it if you pass
98
+ larger timeouts; the client can still cancel before xcodebug's own deadline.
99
+
100
+ ```toml
101
+ [mcp_servers.xcodebug]
102
+ tool_timeout_sec = 4200
103
+ ```
104
+
105
+ Claude Code needs no setting for this. Its default limit on a tool call is about
106
+ 28 hours. It also ends a call to a stdio server that has sent neither a reply
107
+ nor a progress notification for 30 minutes; this server sends progress once a
108
+ second to a client that asks for it.
109
+
110
+ Cancelling an MCP request aborts that request. On SIGINT, SIGTERM or detected
111
+ stdout loss, the server stops accepting work, cancels admitted requests and
112
+ then cleans up captures. Closing only stdin lets admitted requests finish and
113
+ sends their replies; a silent lost reader cannot be distinguished from this
114
+ until stdout closes or a write fails.
115
+
116
+ To run `npm test` from a checkout, use Node.js 22.18 or later and put Bun on PATH
117
+ for the stdio integration tests.
118
+
95
119
  ### Install the manual entry point
96
120
 
97
121
  Connecting MCP makes the tool available to the model; it does not register a
@@ -350,8 +374,10 @@ remain available without the display.
350
374
  `action=wait`; these pull reads are separate from the Claude Mod's user-visible
351
375
  display. Cursor reads exclude earlier indices, but a limited read can omit
352
376
  lines; see [Reading logs from a cursor](#reading-logs-from-a-cursor).
353
- - **Captures end with the client.** The server is a child of Codex/Claude, so
354
- quitting the client stops the bridges. Relaunch next session.
377
+ - **Captures end with the client.** The server is a child of Codex/Claude. When
378
+ the client closes the connection, the server finishes the call in progress,
379
+ stops its captures and exits. On SIGINT or SIGTERM it stops at once, a build
380
+ still running included. Relaunch next session.
355
381
 
356
382
  Logs land in `~/.xcodebug/logs/xcodebug/`, or under `XCODEBUG_AGENT_DIR` when set.
357
383
  Every response also reports the exact path, so the model can read the file once a
@@ -452,13 +478,23 @@ rather than writing logs to a guessed path.
452
478
  `device` may be a name, UDID, ECID or CoreDevice uuid. With one physical device
453
479
  connected it can be omitted.
454
480
 
481
+ A file that is not valid JSON is an error, not an absent config: `doctor` reports
482
+ it, and every action that would read it refuses to run rather than use the
483
+ defaults the file was written to override. The actions that never read it -
484
+ `devices`, `logs`, `wait`, `status`, `stop` and `await` - still work.
485
+
455
486
  ## Change detection and pod install
456
487
 
457
488
  Every `build` and `launch` first inspects the working tree with
458
489
  `git status --porcelain -uall`:
459
490
 
460
- 1. **Any build-relevant change** (sources, resources, Podfile, podspec, project
461
- files) forces a rebuild + relaunch.
491
+ 1. **Any change git reports** forces a rebuild + relaunch, tracked or not and
492
+ whatever its type (`Podfile.rb`, an `.xcconfig`, a new image): a build that
493
+ is reused must not be older than what it was built from. The exceptions are
494
+ the types no build reads - notes, logs, crash reports and patches (`.md`,
495
+ `.log`, `.ips`, `.patch`, `.diff`) - so what a run leaves in the tree does
496
+ not trigger a build. A run that writes files of other types into the
497
+ repository, such as JSON results, does.
462
498
  2. **A new file inside a pod** forces `pod install --no-repo-update` first,
463
499
  because the generated Pods project enumerates pod sources and will not
464
500
  compile a file it has never seen. Pod membership comes from the repo's own
@@ -472,10 +508,24 @@ Every `build` and `launch` first inspects the working tree with
472
508
  `Podfile` (the workspace's parent). If there is none, the step is skipped and
473
509
  the reason is reported - it never searches elsewhere, because that could
474
510
  reinstall a different project's pods.
475
- 4. **No change** since the last successful build in this session reuses that
476
- build instead of rebuilding for minutes. Pass `force=true` to override.
511
+ 4. **No change** since this session last built the same scheme, configuration
512
+ and device reuses that build, for `launch` as well as `build`, instead of
513
+ rebuilding for minutes. The app is still installed and launched. Pass
514
+ `force=true` to rebuild. "No change" means all of:
515
+ - the same committed code and the same uncommitted changes. A commit, pull or
516
+ checkout rebuilds even though `git status` is clean again; `git add` alone
517
+ does not;
518
+ - the same files in every pod the workspace installs from a path outside the
519
+ repository (`:path` in `Podfile.lock`), which `git status` cannot see;
520
+ - the built `.app` is as that build left it. Xcode, or an `xcodebuild` in
521
+ another terminal, writes the same product path.
522
+
523
+ A build during which the tree changed is not reused, and its reply says so.
477
524
 
478
525
  Inspect the decision without building:
526
+ Use the same target and device options as the intended build. If the target
527
+ cannot be resolved, the report cannot identify a reusable build. If pod install
528
+ is needed, the preview assumes a rebuild until the updated tree is available.
479
529
 
480
530
  ```text
481
531
  xcodebug action=changes
@@ -485,6 +535,7 @@ xcodebug action=changes
485
535
  2 build-relevant change(s)
486
536
  M Packages/FeatureX/Classes/Weather/AddCityController.swift
487
537
  fingerprint: 963e92a4
538
+ last build for this target: (none)
488
539
  rebuild needed: yes
489
540
  pod install needed: no
490
541
  ```
@@ -632,7 +683,10 @@ nothing about any test framework. Two consequences worth knowing:
632
683
  What it reports: exit code, elapsed time, how many new lines the capture gained,
633
684
  the log path, and the `action=logs` call (with the right `since`) that returns
634
685
  the app side of that run. A non-zero exit is surfaced as an error, not as a
635
- successful "run finished".
686
+ successful "run finished". Two things about the capture are reported when they
687
+ happened, because either one changes what the log means: that it was no longer
688
+ capturing when the command finished (with the reason, or the last line logged),
689
+ and that a console reattach relaunched the app during the run.
636
690
 
637
691
  ### What the model does with it
638
692
 
@@ -685,8 +739,10 @@ Boundaries that keep it out of every other workflow:
685
739
  **Prerequisite when the command drives the UI:** the runner must not relaunch the
686
740
  app. Many UI-test fixtures terminate and relaunch the app before every test
687
741
  unless `autoAppLaunch: false` is set, which kills the very launch xcodebug is
688
- capturing. Set it in the config the run uses. A command that does not touch the
689
- app (a curl, a fixture import, a codegen step) has no such constraint.
742
+ capturing. Set it in the config the run uses. When it happens anyway, the capture
743
+ ends there and says the app was restarted outside it; it does not relaunch over
744
+ the runner's instance. A command that does not touch the app (a curl, a fixture
745
+ import, a codegen step) has no such constraint.
690
746
 
691
747
  ### Run semantics
692
748
 
@@ -702,10 +758,25 @@ session.
702
758
  has been tried, not that the run is over: say what to do on the phone and keep
703
759
  listening.
704
760
  - A console capture ends when the app process is confirmed gone, and its syslog
705
- companion is stopped too. A standalone `syslog` capture is not bound to the
706
- app's lifetime and keeps reconnecting; stop it explicitly when finished.
707
- - A dropped console bridge otherwise reconnects indefinitely. An inconclusive
708
- probe (USB unplugged, `devicectl` timeout) is **not** treated as "the app exited".
761
+ companion is stopped too. It records why - `the app exited`, with the last
762
+ line logged, which is devicectl's own `App terminated due to signal 9.` when
763
+ the app was killed - in the log file, in `status`, and under later `logs`
764
+ reads. If the device wrote a crash report for the app, it is copied next to
765
+ the log and its path is reported the same way. A standalone `syslog` capture
766
+ is not bound to the app's lifetime and keeps reconnecting; stop it explicitly
767
+ when finished.
768
+ - A dropped console bridge whose app is still running is reattached, retrying
769
+ for as long as it takes. devicectl attaches a console only by launching, so
770
+ with the default `terminateExisting` **a reattach restarts the app** and its
771
+ state is gone: the log says so and `status` counts the relaunches. An
772
+ inconclusive probe (USB unplugged, `devicectl` timeout) is retried without
773
+ relaunching. If the current PID is known but capture ownership cannot be
774
+ verified, a reattach that would terminate the running app is skipped.
775
+ - If the instance running is not the one this capture launched - another
776
+ session, a test runner or the user relaunched the app - the capture ends and
777
+ leaves that instance alone. Reattaching would terminate it. The session that
778
+ did the relaunching is told as well: its `launch` reply notes that the app was
779
+ already running and not started by it.
709
780
  - `idevicesyslog` can go silent with its process still alive; a 30s watchdog kills
710
781
  it and the exit hook reattaches. Reattachment has exactly one owner, so the
711
782
  watchdog and the exit hook can never both assume the other is handling it.
@@ -746,7 +817,9 @@ xcodebug action=syslog processName=MyApp
746
817
  # incremental reads (cursor-based)
747
818
  xcodebug action=logs limit=200
748
819
  xcodebug action=logs grep=MySDK
820
+ xcodebug action=logs grep=MySDK times=true
749
821
  xcodebug action=wait match="DataPacket" timeoutSeconds=30
822
+ xcodebug action=wait match="sync (done|failed)" regex=true timeoutSeconds=30
750
823
 
751
824
  xcodebug action=status
752
825
  xcodebug action=stop keepApp=true
@@ -790,6 +863,19 @@ is written to disk and delivered to live subscribers but not retained for
790
863
  and captures reconnecting after a bridge failure are not evicted. Older capture
791
864
  IDs leave `logs`/`status`, while their retained disk segments remain available.
792
865
 
866
+ A busy app fills that buffer in seconds, so a filtered read does not stop at it.
867
+ `logs grep=...` and `wait` also search for lines missing from memory, including
868
+ oversized lines between retained entries. They wait for writes through the
869
+ scan's cursor before reading disk; cancellation interrupts that work. The reply
870
+ reports how many lines were searched on disk and how many are unavailable.
871
+ An unfiltered `logs` returns the newest lines as before and
872
+ names the log file for the rest.
873
+
874
+ `regex=true` makes `grep` and `match` regular expressions, so one `wait` can
875
+ cover both outcomes of a step: `match="sync (done|failed)"`. `times=true`
876
+ prefixes each returned line with the host time it arrived, for lining the log
877
+ up with a test runner's own output.
878
+
793
879
  ### `syslog`: attach without relaunching
794
880
 
795
881
  `launch` restarts the app because `devicectl --console` has to start it. When the
@@ -837,8 +923,16 @@ drain-timeout error in capture status, and completes shutdown; pending logs may
837
923
  be truncated.
838
924
 
839
925
  The bundle id separates apps, and the timestamp includes milliseconds to
840
- separate runs. Segment limits apply per capture: old runs are not automatically
841
- deleted from disk when their capture IDs leave the in-memory history.
926
+ separate runs. Segment limits apply per capture. What xcodebug itself says while
927
+ a bridge is down - why the capture ended, each reattach - is appended to the same
928
+ file, so a log that stops also says why. A crash report copied from the device
929
+ lands beside the logs as `crash-<unique-id>-<name>.ips`. When the app PID is
930
+ known, a report without that PID is not retained.
931
+
932
+ Logs are kept for 30 days after their last write. The first `build`, `launch` or
933
+ `syslog` of a session deletes older `build-`, `console-`, `syslog-` and
934
+ `pod-install-` logs and `crash-*.ips` reports from this directory, and nothing
935
+ else in it.
842
936
 
843
937
  A successful build clears `<agentDir>/logs/xcodebug/archive/` first, so snapshots
844
938
  from a previous binary cannot be mistaken for the run that is starting.
package/archive.ts CHANGED
@@ -61,6 +61,35 @@ export async function clearArchives(workDir: string): Promise<{ removed: number;
61
61
  return { removed, freedBytes };
62
62
  }
63
63
 
64
+ /** The files this extension writes: build, capture and pod install logs, and pulled crash reports. */
65
+ const OWN_LOG = /^(?:build|console|syslog|pod-install|crash)-.+\.(?:log(?:\.\d+)?|ips)$/;
66
+
67
+ /**
68
+ * Delete this extension's logs that nothing has written to for `maxAgeMs`.
69
+ *
70
+ * Nothing else ever removes them, and they add up to hundreds of megabytes in
71
+ * a few weeks. Age since the last write is the whole test: a capture still
72
+ * running keeps its log fresh, and a file xcodebug did not name is left alone.
73
+ */
74
+ export async function pruneLogs(logDir: string, maxAgeMs: number): Promise<void> {
75
+ let entries: string[];
76
+ try {
77
+ entries = await readdir(logDir);
78
+ } catch {
79
+ return;
80
+ }
81
+ const cutoff = Date.now() - maxAgeMs;
82
+ for (const name of entries) {
83
+ if (!OWN_LOG.test(name)) continue;
84
+ const path = join(logDir, name);
85
+ try {
86
+ if ((await stat(path)).mtimeMs < cutoff) await rm(path, { force: true });
87
+ } catch {
88
+ // A log that cannot be removed is not worth failing a run over.
89
+ }
90
+ }
91
+ }
92
+
64
93
  /** Recursive size of a file or directory, in bytes. */
65
94
  async function sizeOf(path: string): Promise<number> {
66
95
  const info = await stat(path);
package/capture.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * back through a cursor so the agent can fetch only what is new.
5
5
  */
6
6
  import { spawn, type ChildProcess } from "node:child_process";
7
- import { createWriteStream, type WriteStream } from "node:fs";
7
+ import { appendFileSync, createReadStream, createWriteStream, statSync, type WriteStream } from "node:fs";
8
8
  import { mkdir } from "node:fs/promises";
9
9
  import { dirname } from "node:path";
10
10
  import { finished } from "node:stream/promises";
@@ -26,6 +26,9 @@ export interface LogLine {
26
26
  text: string;
27
27
  }
28
28
 
29
+ /** A line as a search returns it: one read back from disk has no stream. */
30
+ export type FoundLine = Pick<LogLine, "index" | "at" | "text"> & Partial<Pick<LogLine, "stream">>;
31
+
29
32
  export interface CaptureInit {
30
33
  mode: CaptureMode;
31
34
  deviceId: string;
@@ -65,12 +68,32 @@ export interface CaptureStatus {
65
68
  logFiles: string[];
66
69
  commandLine: string;
67
70
  error?: string;
71
+ relaunches: number;
72
+ endReason?: string;
73
+ crashReport?: string;
68
74
  }
69
75
 
70
76
  function clean(text: string): string {
71
77
  return text.replace(ANSI, "").replace(/\r/g, "");
72
78
  }
73
79
 
80
+ function clampLimit(limit: number | undefined): number {
81
+ return Math.trunc(Math.min(Math.max(1, limit ?? 200), 5_000));
82
+ }
83
+
84
+ /** A filter is a substring, or a pattern when the caller asked for one. */
85
+ export function matchesFilter(text: string, filter: string | RegExp): boolean {
86
+ return typeof filter === "string" ? text.includes(filter) : filter.test(text);
87
+ }
88
+
89
+ function sizeOnDisk(path: string): number {
90
+ try {
91
+ return statSync(path).size;
92
+ } catch {
93
+ return 0;
94
+ }
95
+ }
96
+
74
97
  export class Capture {
75
98
  readonly id: string;
76
99
  readonly mode: CaptureMode;
@@ -103,6 +126,15 @@ export class Capture {
103
126
  * emits anything still ages from a sane starting point.
104
127
  */
105
128
  lastLineAt = Date.now();
129
+ /**
130
+ * Times the console bridge was reattached. devicectl attaches a console only
131
+ * by launching, so each one restarted the app and dropped its state.
132
+ */
133
+ relaunches = 0;
134
+ /** Why the capture ended without being asked to. */
135
+ endReason?: string;
136
+ /** The crash report pulled from the device after the app died, if it left one. */
137
+ crashReport?: string;
106
138
  /**
107
139
  * Aborted when this capture is stopped, so an in-flight device probe returns
108
140
  * at once instead of running out its own timeout first.
@@ -124,6 +156,20 @@ export class Capture {
124
156
  private fileNumber = 0;
125
157
  private fileOrder = 0;
126
158
  private readonly logFiles = new Map<string, number>();
159
+ /** Only overwriting an existing segment invalidates an in-flight disk scan. */
160
+ private readonly fileVersions = new Map<string, number>();
161
+ /**
162
+ * Where each run of consecutively indexed lines starts on disk. The files
163
+ * carry no index and have holes - a rotated segment is overwritten, and a
164
+ * write that fails takes its lines with it - so a line's index is only
165
+ * recoverable per run.
166
+ */
167
+ private runs: Array<{ path: string; offset: number; index: number }> = [];
168
+ /** The segment being written, and where its next run starts once a line arrives. */
169
+ private segment = "";
170
+ private opened: { path: string; offset: number } | undefined;
171
+ /** True while lines are appended with the bridge down, which is one run. */
172
+ private appending = false;
127
173
  private readonly files = new Set<WriteStream>();
128
174
  private readonly blockedFiles = new Set<WriteStream>();
129
175
  private readonly exitListeners = new Set<(code: number | undefined, signal: string | undefined) => void>();
@@ -175,8 +221,10 @@ export class Capture {
175
221
  return () => this.lineListeners.delete(listener);
176
222
  }
177
223
 
178
- async start(): Promise<void> {
224
+ async start(signal?: AbortSignal): Promise<void> {
179
225
  await mkdir(dirname(this.logFile), { recursive: true });
226
+ signal?.throwIfAborted();
227
+ if (this.stoppedByUser) return;
180
228
  this.openFile(true);
181
229
 
182
230
  const child = spawn(this.command, this.launchArgs, { stdio: ["ignore", "pipe", "pipe"] });
@@ -253,6 +301,13 @@ export class Capture {
253
301
 
254
302
  private openFile(append: boolean): void {
255
303
  const path = this.fileNumber === 0 ? this.logFile : `${this.logFile}.${this.fileNumber}`;
304
+ if (!append && this.runs.some((run) => run.path === path)) {
305
+ this.runs = this.runs.filter((run) => run.path !== path);
306
+ this.fileVersions.set(path, (this.fileVersions.get(path) ?? 0) + 1);
307
+ }
308
+ this.segment = path;
309
+ this.opened = { path, offset: append ? sizeOnDisk(path) : 0 };
310
+ this.appending = false;
256
311
  const file = createWriteStream(path, { flags: append ? "a" : "w" });
257
312
  this.file = file;
258
313
  this.files.add(file);
@@ -321,15 +376,8 @@ export class Capture {
321
376
  // Still deliver and write an oversized line, without retaining it in memory.
322
377
  this.droppedLines += 1;
323
378
  }
324
- for (const listener of this.lineListeners) {
325
- try {
326
- listener(line);
327
- } catch {
328
- // A listener must never break capture.
329
- }
330
- }
379
+ const encoded = `${new Date(line.at).toISOString()} ${line.text}\n`;
331
380
  if (this.file) {
332
- const encoded = `${new Date(line.at).toISOString()} ${line.text}\n`;
333
381
  const size = Buffer.byteLength(encoded);
334
382
  if (this.fileBytes > 0 && this.fileBytes + size > MAX_FILE_BYTES) {
335
383
  this.file.end();
@@ -337,6 +385,10 @@ export class Capture {
337
385
  this.fileBytes = 0;
338
386
  this.openFile(false);
339
387
  }
388
+ if (this.opened) {
389
+ this.runs.push({ ...this.opened, index: line.index });
390
+ this.opened = undefined;
391
+ }
340
392
  this.fileBytes += size;
341
393
  const file = this.file;
342
394
  if (!file.write(encoded)) {
@@ -344,6 +396,26 @@ export class Capture {
344
396
  this.child?.stdout?.pause();
345
397
  this.child?.stderr?.pause();
346
398
  }
399
+ } else if (!this.child && this.segment) {
400
+ // The bridge is down and its file is closed. What is said meanwhile - why
401
+ // it ended, each reattach - is what explains the rest of the log, so it
402
+ // goes to disk too. Only a few lines arrive in this state.
403
+ try {
404
+ const offset = this.appending ? undefined : sizeOnDisk(this.segment);
405
+ appendFileSync(this.segment, encoded);
406
+ if (offset !== undefined) this.runs.push({ path: this.segment, offset, index: line.index });
407
+ this.appending = true;
408
+ } catch {
409
+ // The log could not be written before either; the line is still in memory.
410
+ this.appending = false;
411
+ }
412
+ }
413
+ for (const listener of this.lineListeners) {
414
+ try {
415
+ listener(line);
416
+ } catch {
417
+ // A listener must never break capture.
418
+ }
347
419
  }
348
420
  }
349
421
 
@@ -394,14 +466,16 @@ export class Capture {
394
466
  });
395
467
  }
396
468
 
397
- read(options: { since?: number; limit?: number; grep?: string; streams?: Array<"out" | "err"> }): {
469
+ read(options: { since?: number; limit?: number; grep?: string | RegExp; streams?: Array<"out" | "err"> }): {
398
470
  lines: LogLine[];
399
471
  cursor: number;
400
472
  total: number;
473
+ /** Lines after `since` that the buffer has already dropped. */
474
+ evicted: number;
401
475
  } {
402
476
  const since = Math.max(0, options.since ?? 0);
403
- const limit = Math.trunc(Math.min(Math.max(1, options.limit ?? 200), 5_000));
404
- const grep = options.grep?.trim();
477
+ const limit = clampLimit(options.limit);
478
+ const grep = typeof options.grep === "string" ? options.grep.trim() : options.grep;
405
479
  const streams = options.streams;
406
480
  // Locate the first eligible index without scanning or copying the buffer.
407
481
  let first = 0;
@@ -411,23 +485,142 @@ export class Capture {
411
485
  if (this.lines[(this.head + middle) % MAX_BUFFER_LINES]!.index <= since) first = middle + 1;
412
486
  else end = middle;
413
487
  }
488
+ // Oversized lines can leave holes inside the ring, not just before it.
489
+ const evicted = Math.max(0, this.cursor - since - (this.lineCount - first));
414
490
  const lines: LogLine[] = [];
415
491
  if (!grep && (!streams || streams.length === 0)) {
416
492
  for (let i = Math.max(first, this.lineCount - limit); i < this.lineCount; i++) {
417
493
  lines.push(this.lines[(this.head + i) % MAX_BUFFER_LINES]!);
418
494
  }
419
- return { lines, cursor: this.cursor, total: this.lineCount - first };
495
+ return { lines, cursor: this.cursor, total: this.lineCount - first, evicted };
420
496
  }
421
497
  let total = 0;
422
498
  for (let i = this.lineCount - 1; i >= first; i--) {
423
499
  const line = this.lines[(this.head + i) % MAX_BUFFER_LINES]!;
424
500
  if (streams && streams.length > 0 && !streams.includes(line.stream)) continue;
425
- if (grep && !line.text.includes(grep)) continue;
501
+ if (grep && !matchesFilter(line.text, grep)) continue;
426
502
  total += 1;
427
503
  if (lines.length < limit) lines.push(line);
428
504
  }
429
505
  lines.reverse();
430
- return { lines, cursor: this.cursor, total };
506
+ return { lines, cursor: this.cursor, total, evicted };
507
+ }
508
+
509
+ /**
510
+ * `read` with a filter, extended to disk for every hole in the ring, including
511
+ * oversized lines between retained entries. `missing` counts lines neither
512
+ * memory nor any retained file holds any more.
513
+ */
514
+ async search(options: { since?: number; limit?: number; grep: string | RegExp; signal?: AbortSignal }, retry = true): Promise<{
515
+ lines: FoundLine[];
516
+ cursor: number;
517
+ total: number;
518
+ evicted: number;
519
+ missing: number;
520
+ }> {
521
+ const signal = options.signal;
522
+ signal?.throwIfAborted();
523
+ const read = this.read(options);
524
+ if (read.evicted === 0) return { ...read, missing: 0 };
525
+ const since = Math.max(0, options.since ?? 0);
526
+ const holes: Array<{ first: number; last: number }> = [];
527
+ let first = since + 1;
528
+ for (let i = 0; i < this.lineCount; i++) {
529
+ const index = this.lines[(this.head + i) % MAX_BUFFER_LINES]!.index;
530
+ if (index <= since) continue;
531
+ if (index > first) holes.push({ first, last: index - 1 });
532
+ first = index + 1;
533
+ }
534
+ if (first <= read.cursor) holes.push({ first, last: read.cursor });
535
+ const grep = typeof options.grep === "string" ? options.grep.trim() : options.grep;
536
+ const limit = clampLimit(options.limit);
537
+ let older: FoundLine[] = [];
538
+ let total = read.total;
539
+ let covered = 0;
540
+ const runs = [...this.runs];
541
+ const versions = new Map(runs.map((run) => [run.path, this.fileVersions.get(run.path) ?? 0]));
542
+ // A reader reaching EOF before queued writes finish must not advance the
543
+ // cursor past those matches. Flush a barrier after this snapshot's writes;
544
+ // later producer output does not extend the snapshot or delay the barrier.
545
+ const clearBarriers: Array<() => void> = [];
546
+ const writes = [...this.files].map((file) => {
547
+ if (file.destroyed || file.writableFinished) return Promise.resolve();
548
+ if (file.writableEnded) return finished(file, { cleanup: true, signal }).catch(() => {});
549
+ return new Promise<void>((resolve) => {
550
+ const done = (): void => { file.off("close", done); resolve(); };
551
+ file.once("close", done);
552
+ clearBarriers.push(() => { file.off("close", done); });
553
+ file.write("", done);
554
+ });
555
+ });
556
+ let onAbort: (() => void) | undefined;
557
+ try {
558
+ await Promise.race([
559
+ Promise.all(writes),
560
+ new Promise<never>((_, reject) => {
561
+ if (!signal) return;
562
+ onAbort = () => reject(signal.reason);
563
+ signal.addEventListener("abort", onAbort, { once: true });
564
+ if (signal.aborted) onAbort();
565
+ }),
566
+ ]);
567
+ } finally {
568
+ if (onAbort) signal!.removeEventListener("abort", onAbort);
569
+ for (const clear of clearBarriers) clear();
570
+ }
571
+ let hole = 0;
572
+ for (const [position, run] of runs.entries()) {
573
+ signal?.throwIfAborted();
574
+ if (run.index > read.cursor) break;
575
+ const next = runs[position + 1];
576
+ let index = run.index;
577
+ let pending = "";
578
+ try {
579
+ const stream = createReadStream(run.path, {
580
+ encoding: "utf8",
581
+ start: run.offset,
582
+ ...(next?.path === run.path ? { end: next.offset - 1 } : {}),
583
+ signal,
584
+ });
585
+ for await (const chunk of stream) {
586
+ signal?.throwIfAborted();
587
+ const parts = (pending + chunk).split("\n");
588
+ pending = parts.pop() ?? "";
589
+ for (const raw of parts) {
590
+ if (index > read.cursor) break;
591
+ while (hole < holes.length && holes[hole].last < index) hole++;
592
+ if (hole < holes.length && index >= holes[hole].first) {
593
+ covered += 1;
594
+ const space = raw.indexOf(" ");
595
+ const text = raw.slice(space + 1);
596
+ if (matchesFilter(text, grep)) {
597
+ total += 1;
598
+ older.push({ index, at: Date.parse(raw.slice(0, space)), text });
599
+ if (older.length >= limit * 2 + 64) older = older.slice(-limit);
600
+ }
601
+ }
602
+ index += 1;
603
+ }
604
+ if (index > read.cursor || hole === holes.length) break;
605
+ }
606
+ } catch {
607
+ signal?.throwIfAborted();
608
+ // A run that cannot be read back stays counted in `missing`.
609
+ }
610
+ }
611
+ signal?.throwIfAborted();
612
+ // Opening a new segment is harmless; only replacement of a file actually
613
+ // included in this snapshot can relabel bytes with the wrong indices.
614
+ if ([...versions].some(([path, version]) => (this.fileVersions.get(path) ?? 0) !== version)) {
615
+ return retry ? this.search(options, false) : { ...read, missing: read.evicted };
616
+ }
617
+ return {
618
+ lines: [...older, ...read.lines].sort((a, b) => a.index - b.index).slice(-limit),
619
+ cursor: read.cursor,
620
+ total,
621
+ evicted: read.evicted,
622
+ missing: read.evicted - covered,
623
+ };
431
624
  }
432
625
 
433
626
  status(): CaptureStatus {
@@ -450,6 +643,9 @@ export class Capture {
450
643
  logFiles: [...this.logFiles].sort((a, b) => a[1] - b[1]).map(([path]) => path),
451
644
  commandLine: [this.command, ...this.launchArgs].join(" "),
452
645
  error: this.error,
646
+ relaunches: this.relaunches,
647
+ endReason: this.endReason,
648
+ crashReport: this.crashReport,
453
649
  };
454
650
  }
455
651
  }