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 +9 -2
- package/README.md +109 -15
- package/archive.ts +29 -0
- package/capture.ts +212 -16
- package/changes.ts +113 -15
- package/devices.ts +74 -3
- package/index.ts +508 -104
- package/mcp/server.ts +66 -15
- package/package.json +4 -1
- package/skills/xcodebug/SKILL.md +12 -1
- package/xcode.ts +84 -4
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
|
|
255
|
-
|
|
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
|
|
354
|
-
|
|
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
|
|
461
|
-
|
|
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
|
|
476
|
-
|
|
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.
|
|
689
|
-
|
|
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.
|
|
706
|
-
|
|
707
|
-
-
|
|
708
|
-
|
|
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
|
|
841
|
-
|
|
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
|
-
|
|
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 =
|
|
404
|
-
const grep = options.grep
|
|
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
|
|
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
|
}
|