recovery-probe 0.2.0 → 0.3.0-preview.12
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/CHANGELOG.md +97 -0
- package/CONTRIBUTING.md +14 -0
- package/README.md +69 -24
- package/SECURITY.md +8 -0
- package/bin/attach.mjs +42 -0
- package/bin/desktop.mjs +82 -0
- package/bin/ipc.mjs +56 -0
- package/bin/observe.mjs +98 -0
- package/bin/recovery-probe.mjs +36 -0
- package/bin/refresh.mjs +45 -0
- package/bin/repair.mjs +66 -0
- package/bin/start.mjs +31 -0
- package/bin/web.mjs +73 -0
- package/docs/desktop.md +201 -0
- package/docs/ipc.md +187 -0
- package/docs/observe.md +110 -0
- package/docs/refresh.md +90 -0
- package/docs/repair.md +208 -0
- package/docs/start.md +82 -0
- package/examples/demo-server.mjs +6 -5
- package/package.json +44 -8
- package/src/desktop-report.mjs +22 -0
- package/src/desktop.d.mts +24 -0
- package/src/desktop.mjs +222 -0
- package/src/discovery-control.mjs +28 -0
- package/src/discovery-report.mjs +11 -0
- package/src/guided-start.mjs +165 -0
- package/src/http-discover.mjs +108 -0
- package/src/http-observer.mjs +67 -0
- package/src/ipc-check.mjs +115 -0
- package/src/ipc-control.mjs +16 -0
- package/src/ipc-discover.mjs +154 -0
- package/src/ipc-inspector.d.mts +13 -0
- package/src/ipc-inspector.mjs +79 -0
- package/src/ipc-observation.mjs +113 -0
- package/src/ipc-probe.cjs +124 -0
- package/src/ipc-probe.d.cts +21 -0
- package/src/observe.mjs +194 -0
- package/src/pick-marker.mjs +66 -0
- package/src/refresh-adapters.mjs +39 -0
- package/src/refresh.mjs +140 -0
- package/src/repair-process.mjs +48 -0
- package/src/repair-provider.mjs +35 -0
- package/src/repair.mjs +249 -0
- package/src/visibility.mjs +56 -0
- package/src/web.d.mts +10 -0
- package/src/web.mjs +29 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,103 @@ All notable changes to Recovery Probe are documented here. The project follows [
|
|
|
4
4
|
|
|
5
5
|
Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
|
|
6
6
|
|
|
7
|
+
## 0.3.0-preview.12 (2026-10-14)
|
|
8
|
+
|
|
9
|
+
- Add `observe --config FILE` for fault-free HTTP/IPC read observation in an existing renderer without reloads, navigation, focus changes or UI cleanup resets. Operator interval markers preserve cumulative read history.
|
|
10
|
+
- Record read starts/completions and sampled content evidence, including `CONTENT_BEFORE_READ` observations. Pre-capture history remains unknown; no identity, ownership or security verdict is inferred.
|
|
11
|
+
- Add bounded, owned IPC observation leases, timestamped snapshots and the documented `recovery-probe/ipc-inspector` subpath. Old hooks fail capability checks before mutation.
|
|
12
|
+
- Validate cache reuse and stale content with synthetic browser/Electron fixtures, alongside a per-identity cache control. Document the session-isolation boundary of reload-based checks.
|
|
13
|
+
|
|
14
|
+
## 0.3.0-preview.11 (2026-10-14)
|
|
15
|
+
|
|
16
|
+
- Extend bounded end-state calibration to HTTP and IPC initial-load discovery: observe three full healthy windows and require matching stable end states before trusting a baseline or injecting faults.
|
|
17
|
+
- Accept genuinely empty selected regions after successful target/dependency reads. Retain calibration evidence and report `readiness.calibrationComplete`; failed calibration cannot claim verified final UI restoration.
|
|
18
|
+
- Use the configured `settleMs` consistently instead of deriving extra stability time from the duration of full calibration windows. Later controls and cleanup may finish early only after matching a trusted baseline.
|
|
19
|
+
- Add browser and real Electron regression cases for delayed image cards, empty regions and inconsistent end states.
|
|
20
|
+
- Align installation guides on the exact preview version, document an unpublished-source fallback, and default preview publishing to npm's `next` tag. This npm release also includes the previously unpublished preview.3–preview.10 changes below.
|
|
21
|
+
|
|
22
|
+
## 0.3.0-preview.10 (GitHub preview; npm publication separate)
|
|
23
|
+
|
|
24
|
+
- Calibrate HTTP/IPC refresh baselines using three full bounded windows and matching stable end states, rather than the first stable intermediate screen.
|
|
25
|
+
- Retain calibration evidence and trust a baseline only after all three reloads agree. Legitimate empty screens are not rejected based on item counts.
|
|
26
|
+
- Add delayed image-card and empty-content regression coverage.
|
|
27
|
+
|
|
28
|
+
## 0.3.0-preview.9 (GitHub preview; npm publication separate)
|
|
29
|
+
|
|
30
|
+
- Refresh the README, setup guides and package description around general web/Electron recovery testing; pin preview installation instructions.
|
|
31
|
+
- Add `refresh --config FILE [--json]` for explicit synthetic window-event experiments on populated screens, using HTTP or IPC fault adapters.
|
|
32
|
+
- Keep fault-free trigger controls, idle attribution checks, spontaneous observations, optional second-trigger recovery and final cleanup separate.
|
|
33
|
+
- Record content preservation independently from freshness, bounded no-subsequent-read observations, partial plans and repeat consistency without confirming inconclusive experiments.
|
|
34
|
+
- Add browser/Electron fixtures and documentation. No real network toggling, lifecycle emulation, token manipulation or generic global-function execution.
|
|
35
|
+
|
|
36
|
+
## 0.3.0-preview.8 (GitHub preview; npm publication separate)
|
|
37
|
+
|
|
38
|
+
- Subsequent healthy controls and final cleanup wait for the established baseline fingerprint within the existing baseline deadline. A stable intermediate screen no longer ends these phases early.
|
|
39
|
+
- Preserve completed runs as `INCOMPLETE_EXPERIMENT` findings when a later control stops an experiment. Show the observed interpretation and completed/planned counts without repeat confirmation.
|
|
40
|
+
- Add browser and Electron fixtures for delayed healthy content, plus bounded persistent mismatch and interrupted experiment checks. Initial baseline discovery still requires representative content and known relevant dependencies.
|
|
41
|
+
|
|
42
|
+
## 0.3.0-preview.7 (GitHub preview; npm publication separate)
|
|
43
|
+
|
|
44
|
+
- Compare rendered groups, image counts and hashed repeated-column distributions, separating observations from suspected interpretations.
|
|
45
|
+
- Retain failed controls and phase-stop evidence; compact reports and change-only bounded timelines.
|
|
46
|
+
- Add bounded repeated HTTP faults (`times`), structural HTTP discovery and `web --attach` with live session reuse.
|
|
47
|
+
- Separate baseline/recovery windows and measure sampled recovery/request completion timing.
|
|
48
|
+
- Add window-state diagnostics and explicit reversible un-minimizing, including a dev-only Electron fallback.
|
|
49
|
+
- Report repeated reads without claiming redundancy, and list observed non-GET/unselected request coverage gaps.
|
|
50
|
+
- Validate with synthetic grids, translated/icon-only states, virtualized DOM lists, explicit errors, empty results, delayed content and backoff; no claim of validation on an independent external app.
|
|
51
|
+
|
|
52
|
+
## 0.3.0-preview.6 (GitHub preview; npm publication separate)
|
|
53
|
+
|
|
54
|
+
- Add bounded `ipc --discover`: three healthy baselines, repeated controls, single/double rejection and null-result experiments, three repetitions by default.
|
|
55
|
+
- Report differential UI leads, repeat consistency, sampled recovery timing, bounded local timelines and coding-agent guidance. No readiness selector or retry-policy input required; the read channel and dev hook remain explicit.
|
|
56
|
+
- Preserve existing IPC verifier and public defaults; repeated hook faults are opt-in, atomically consumed and reset by run ID.
|
|
57
|
+
- English text heuristics and whole-region fingerprints can be inconclusive on changing/localized screens. No new web discovery or autonomous repair claims.
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
## [0.3.0-preview.5] - Unreleased
|
|
61
|
+
|
|
62
|
+
- Use synchronous Node inspector evaluation for synchronous IPC controls, avoiding implicit Promise collection failures in Electron's main process.
|
|
63
|
+
- Retain and explicitly await the asynchronous window-identification Promise, releasing its inspector object group afterward.
|
|
64
|
+
- Treat a lost begin reply as uncertain execution: attempt scoped reset and independently verify disarmed state even when begin/reset replies fail.
|
|
65
|
+
- Add protocol regression tests and real Electron lost-begin-reply fault-cleanup tests; fail closed when cleanup cannot be verified.
|
|
66
|
+
|
|
67
|
+
## [0.3.0-preview.4] - Unreleased
|
|
68
|
+
|
|
69
|
+
- Add an explicitly enabled main-process IPC registration adapter, scoped to allowed read channels and one window's main frame.
|
|
70
|
+
- Preserve normal call arguments, receiver and original return values; use no private Electron handler maps.
|
|
71
|
+
- Add one-shot rejection/null-result plans with IDs, TTL, reset, pending-call isolation and bounded per-channel counters.
|
|
72
|
+
- Add a noninteractive IPC checker over loopback Node inspector and renderer CDP, with measured baseline/deadline, dependency checks, fresh reloads and local reports.
|
|
73
|
+
- Treat extra traffic, missing dependencies and hidden/offline environments as inconclusive. Do not claim HTTP/Rust fault coverage.
|
|
74
|
+
|
|
75
|
+
## [0.3.0-preview.3] - Unreleased
|
|
76
|
+
|
|
77
|
+
- Attach to Electron without overriding download/focus/media defaults; fix older Electron rejecting Browser.setDownloadBehavior and test Electron 29.0.1 alongside 44.5.1.
|
|
78
|
+
|
|
79
|
+
- Add guided `start web` and `start desktop` commands with saved one-command reruns.
|
|
80
|
+
- Download missing Chromium automatically; combine manual login, request discovery, content picking, checks and local reports.
|
|
81
|
+
- Select a single Electron window automatically and show named choices for ambiguous windows/requests.
|
|
82
|
+
- Generate unique selectors from a user-selected content marker, and match Retry buttons by their visible label.
|
|
83
|
+
- Save private login state and configuration in an ignored local folder; no source access or AI upload in guided checks.
|
|
84
|
+
- Cover real browser setup/reruns, real Electron attachment and Windows publishing checks in CI.
|
|
85
|
+
|
|
86
|
+
## [0.3.0-preview.2] - 2026-10-05
|
|
87
|
+
|
|
88
|
+
- Add Chromium web discovery/checks and explicit private login-state saving.
|
|
89
|
+
- Add opt-in OpenAI source-edit proposals from selected source files and reproduced evidence.
|
|
90
|
+
- Reproduce and verify in a separate local clone; preserve the original repository and never push/deploy a candidate.
|
|
91
|
+
- Reject unsafe paths, ambiguous replacements, dirty baselines, preexisting target ports and setup/test mutations.
|
|
92
|
+
- Separate reviewed verification from explicit opt-in execution of unreviewed generated code.
|
|
93
|
+
- Add authenticated web and Electron before/after integration tests with controlled provider responses.
|
|
94
|
+
- Clarify release stages and source-upload/report privacy boundaries. Live model fix quality is not yet validated.
|
|
95
|
+
|
|
96
|
+
## [0.3.0-preview.1] - Unreleased
|
|
97
|
+
|
|
98
|
+
- Add Electron renderer discovery and targeted recovery checks through loopback CDP.
|
|
99
|
+
- Require a successful request after fault injection and a configured healthy UI marker.
|
|
100
|
+
- Add local HTML/JSON reports, executable reproductions, and coding-agent investigation briefs.
|
|
101
|
+
- Test real Electron attachment, preload preservation, recovery failures, automatic retry, stale UI markers, and disconnect behavior.
|
|
102
|
+
- Keep source-code fixes manual and reports local; native SDK/IPC traffic is outside this preview.
|
|
103
|
+
|
|
7
104
|
## [0.2.0] - 2026-09-22
|
|
8
105
|
|
|
9
106
|
### Added
|
package/CONTRIBUTING.md
CHANGED
|
@@ -19,6 +19,20 @@ npx playwright install chromium
|
|
|
19
19
|
npm run test:browser
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
+
## Install an unpublished source preview
|
|
23
|
+
|
|
24
|
+
When the version shown in the README is not on npm yet, install from a local checkout:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
git clone https://github.com/BojanKovachki/recovery-probe.git
|
|
28
|
+
cd recovery-probe
|
|
29
|
+
npm ci
|
|
30
|
+
node bin/recovery-probe.mjs --version
|
|
31
|
+
node bin/recovery-probe.mjs --help
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Record `git rev-parse HEAD` with any report so the source is reproducible. Use `node bin/recovery-probe.mjs` in place of `npx recovery-probe` in the guides when running from this checkout. Installing from source does not imply that the version is published to npm.
|
|
35
|
+
|
|
22
36
|
Run the controlled demonstrations when behavior or output changes:
|
|
23
37
|
|
|
24
38
|
```bash
|
package/README.md
CHANGED
|
@@ -1,39 +1,79 @@
|
|
|
1
1
|
# Recovery Probe
|
|
2
2
|
|
|
3
|
+
**Test how web and desktop applications recover when data reads fail—during loading and refresh.**
|
|
4
|
+
|
|
5
|
+
Recovery Probe injects bounded faults, compares healthy and faulted screens, and records whether content survives or returns. It helps developers and coding agents reproduce recovery problems such as disappearing lists, stuck loading states and missing retries. Installing the package does not add recovery behavior to your application.
|
|
6
|
+
|
|
3
7
|
[](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
|
|
4
8
|
[](https://www.npmjs.com/package/recovery-probe)
|
|
5
|
-
[](https://nodejs.org/)
|
|
6
9
|
[](LICENSE)
|
|
7
10
|
|
|
8
|
-
|
|
11
|
+
## Supported applications
|
|
9
12
|
|
|
10
|
-
|
|
13
|
+
| Application path | What can be tested | Setup |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| Web apps in Chromium-based browsers | Renderer GET fetch/XHR failures, UI recovery and structural content changes | Launch a test browser or attach to an authorized development browser |
|
|
16
|
+
| Electron desktop apps using renderer HTTP | The same request and UI checks | Attach through a loopback debugging endpoint |
|
|
17
|
+
| Electron desktop apps using IPC reads | Renderer behavior after selected IPC rejections or null results | Add a development-only handler-registration hook and enable local inspection |
|
|
18
|
+
| JavaScript code using fetch | Recovery logic around an explicitly supplied fetch wrapper | Import `recovery-probe/fetch`; Playwright is not required |
|
|
11
19
|
|
|
12
|
-
|
|
20
|
+
Desktop support currently means Electron, not arbitrary native applications. IPC faults do not exercise native/Rust networking, HTTP status handling or token refresh. An unsupported data path is inconclusive, never a successful recovery check.
|
|
21
|
+
|
|
22
|
+
## Install the current preview
|
|
23
|
+
|
|
24
|
+
This checkout targets **0.3.0-preview.12**. Preview releases use npm's `next` tag; `latest` is the stable channel. Confirm that the exact version is published before installing it:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
28
|
+
npm view recovery-probe@0.3.0-preview.12 version
|
|
29
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.12 playwright@1.62.1
|
|
30
|
+
npx recovery-probe --version
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
If the version check reports that the version is unavailable, npm publication is still pending; use the [source installation](CONTRIBUTING.md#install-an-unpublished-source-preview). A GitHub merge alone does not publish the package. Use Node.js 22 or newer. A separate tools folder keeps the tester out of your application's production dependencies. Browser/desktop commands require Playwright; attached targets use their existing browser runtime. The guided web flow downloads Chromium when needed. See [CHANGELOG.md](CHANGELOG.md) for version history.
|
|
34
|
+
|
|
35
|
+
## Choose a workflow
|
|
13
36
|
|
|
14
|
-
|
|
37
|
+
**New in preview.12:** [fault-free observation](docs/observe.md) records selected reads and content while you navigate, without reloading or clearing caches. See the guide for updating the development IPC hook before capturing cached state.
|
|
15
38
|
|
|
16
|
-
|
|
39
|
+
| Goal | Entry point | Guide |
|
|
40
|
+
| --- | --- | --- |
|
|
41
|
+
| Set up a first request-recovery check interactively | `recovery-probe start web URL` or `start desktop` | [Guided start](docs/start.md) |
|
|
42
|
+
| Discover and test renderer reads in an existing browser or Electron window | `recovery-probe desktop --cdp URL` | [Attachment and HTTP discovery](docs/desktop.md) |
|
|
43
|
+
| Compare an Electron screen under IPC faults | `recovery-probe ipc --discover --config FILE` | [IPC setup and discovery](docs/ipc.md) |
|
|
44
|
+
| Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
|
|
45
|
+
| Add an explicit recovery assertion to a test | `withFault` or `createFaultFetch` | Examples below |
|
|
46
|
+
| Propose and verify a source change | Opt-in repair workflow | [Repair setup and limits](docs/repair.md) |
|
|
17
47
|
|
|
18
|
-
|
|
48
|
+
`desktop` is also the current command name for attaching to an existing Chromium-based web browser. Use only an authorized test session, with debugging endpoints on loopback. Keep the target window visible and uncovered.
|
|
19
49
|
|
|
20
|
-
|
|
21
|
-
2. Inject a bounded fault without replacing global `fetch`.
|
|
22
|
-
3. Run the real recovery interaction and assertion.
|
|
23
|
-
4. Fail if the fault was never observed, so a wrong route cannot create a false positive.
|
|
24
|
-
5. Remove only its own route handler and preserve existing mocks.
|
|
50
|
+
Guided setup asks you to choose a request and loaded content that proves success; later runs reuse the saved scenario. Structural discovery compares healthy and faulted screens without requiring a hand-written content selector, but still needs a selected read target and a valid baseline. Neither workflow infers your product's intended recovery policy.
|
|
25
51
|
|
|
26
|
-
|
|
52
|
+
HTTP and IPC structural discovery calibrate three healthy reloads for the full `baselineTimeoutMs` window before injecting faults (45 seconds with the default 15-second window). All three stable end states must agree. This avoids treating a briefly stable loading shell as the healthy screen, accepts legitimate empty regions, and keeps an unsuccessful calibration inconclusive. Later controls may finish early once they match the calibrated baseline. Content arriving after the window remains outside the evidence.
|
|
27
53
|
|
|
28
|
-
|
|
54
|
+
**Session-isolation boundary:** recovery/discovery/refresh workflows reload the renderer to establish controls. That clears in-memory caches and can hide state carried between sessions. Those modes cannot prove account isolation; content preservation within one session is not an ownership check. The new observation workflow collects evidence without resetting that state, but does not infer identities or data ownership.
|
|
55
|
+
|
|
56
|
+
## Refresh experiments
|
|
57
|
+
|
|
58
|
+
The preview.9 refresh mode tests an **already populated screen** using an explicitly configured synthetic window event, such as `online`. It first checks the event without a fault, then injects the next selected read failure and observes the screen without reloading. An optional second event tests whether another refresh repairs the screen.
|
|
29
59
|
|
|
30
60
|
```bash
|
|
31
|
-
|
|
61
|
+
npx recovery-probe refresh --config ./refresh.json --out ./refresh-run1 --json
|
|
32
62
|
```
|
|
33
63
|
|
|
34
|
-
|
|
64
|
+
This dispatches an event; it does not disconnect the network, change `navigator.onLine`, simulate sleep/resume or expire authentication. Spontaneous recovery and recovery after the second tool event are reported separately. See the [configuration, results and cleanup contract](docs/refresh.md).
|
|
65
|
+
|
|
66
|
+
## Reports and coding agents
|
|
67
|
+
|
|
68
|
+
Reports separate measured facts—fault counts, successful reads, timings and UI changes—from suspected defects. A `CONTENT_LOSS` finding needs review. An unconsumed fault, unstable control or unsupported path is inconclusive. All non-recovery observations are limited to the configured time window.
|
|
69
|
+
|
|
70
|
+
Agents can run saved scenarios, inspect JSON evidence, propose changes and rerun the same experiment. Recovery Probe supplies repeatable experiments and evidence; it is not a general bug detector or production self-healing system. The optional AI repair workflow requires selected local source files, launch/test commands and your own model credentials. It produces a reviewable candidate, not a guaranteed fix.
|
|
35
71
|
|
|
36
|
-
|
|
72
|
+
Reports remain local. Scenarios, endpoints, channels, selected text and authentication files may contain private information; do not publish them blindly. Tests and discovery do not call an AI service.
|
|
73
|
+
|
|
74
|
+

|
|
75
|
+
|
|
76
|
+
## Use in a Playwright test
|
|
37
77
|
|
|
38
78
|
Use `withFault` inside an existing Playwright test. The callback contains the real user action and the application-specific recovery assertion.
|
|
39
79
|
|
|
@@ -87,7 +127,7 @@ fixed synthetic fixture
|
|
|
87
127
|
|
|
88
128
|
`--demo` exits successfully only when it observes the expected contrast: the happy path passes, the broken recovery is caught, and the corrected flow passes. Add `--json` to print the full report or `--out report.json` to save it.
|
|
89
129
|
|
|
90
|
-
##
|
|
130
|
+
## Library HTTP faults
|
|
91
131
|
|
|
92
132
|
| Kind | Injected behavior |
|
|
93
133
|
| --- | --- |
|
|
@@ -115,7 +155,7 @@ probe.assertApplied();
|
|
|
115
155
|
|
|
116
156
|
`exerciseApplication` represents your own test adapter or application controller. Calling `assertApplied()` is essential: it proves that every requested fault was consumed.
|
|
117
157
|
|
|
118
|
-
## JSON-configured runner
|
|
158
|
+
## Original JSON-configured runner
|
|
119
159
|
|
|
120
160
|
The CLI supports pages that automatically load GET data, expose a visible Retry button after failure, and show a ready element after recovery.
|
|
121
161
|
|
|
@@ -142,7 +182,7 @@ Exit codes:
|
|
|
142
182
|
- `1`: a recovery check failed, was inconclusive, or was skipped.
|
|
143
183
|
- `2`: invalid arguments, configuration, or environment setup.
|
|
144
184
|
|
|
145
|
-
##
|
|
185
|
+
## Original runner result semantics
|
|
146
186
|
|
|
147
187
|
| Code | Meaning |
|
|
148
188
|
| --- | --- |
|
|
@@ -186,20 +226,25 @@ Recovery Probe deliberately focuses on deterministic request-level recovery chec
|
|
|
186
226
|
|
|
187
227
|
Playwright already provides the routing primitives used here. Recovery Probe adds bounded recipes, fault-occurrence verification, cleanup, consistent result codes, a fetch adapter, and a runnable broken-versus-fixed example. If a few direct `page.route()` calls are clearer for your test, use them; this package is most useful when teams want the recovery pattern to be repeatable.
|
|
188
228
|
|
|
189
|
-
The runner requires explicit selectors and endpoint matching. It does not discover an application's recovery policy automatically.
|
|
229
|
+
The original assertion-based runner requires explicit selectors and endpoint matching; structural discovery and refresh modes use healthy-screen comparisons instead. It does not discover an application's recovery policy automatically. Request/response bodies and headers are not collected by the checker. Preview reports include endpoint origin/path, selectors, expected text and configuration; optional screenshots, login state and command logs may be sensitive. Do not commit or share these blindly.
|
|
230
|
+
|
|
231
|
+
Recovery Probe sends no telemetry. Tests/discovery do not call an AI service. Only explicit repair generation with `--allow-source-upload` sends the selected source contents and bounded observations to the configured OpenAI model. Login state and command logs are not part of that upload bundle. `store: false` is set on the API request; this is not a promise of zero provider retention. Review employer policy and provider data terms first.
|
|
190
232
|
|
|
191
233
|
## Development
|
|
192
234
|
|
|
193
235
|
```bash
|
|
194
236
|
npm ci
|
|
195
|
-
npm test #
|
|
237
|
+
npm test # fetch/core tests
|
|
196
238
|
npm run test:package # isolated tarball install + TypeScript + CLI checks
|
|
197
239
|
npx playwright install chromium
|
|
198
|
-
npm run test:browser #
|
|
240
|
+
npm run test:browser # real-browser integration tests
|
|
241
|
+
npm run test:repair # safety, authenticated portal, before/after pipeline
|
|
242
|
+
# After installing the optional Electron test runtime:
|
|
243
|
+
npm run test:repair:electron
|
|
199
244
|
npm run demo:browser
|
|
200
245
|
```
|
|
201
246
|
|
|
202
|
-
CI runs package checks on Node.js 22 and 24,
|
|
247
|
+
CI runs package checks on Node.js 22 and 24, Chromium integration, and real Electron checks. Repair integration tests use a **controlled mock model response** but real apps, fault injection, source changes and reruns. They validate orchestration, not live AI diagnosis quality. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
|
|
203
248
|
|
|
204
249
|
## License
|
|
205
250
|
|
package/SECURITY.md
CHANGED
|
@@ -4,6 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
Security fixes are applied to the latest published version of Recovery Probe.
|
|
6
6
|
|
|
7
|
+
## Preview repair trust boundary
|
|
8
|
+
|
|
9
|
+
Repair operates on a separate local clone, **not an OS/network security sandbox**. Launch scripts, setup/test commands and generated application code execute with your user's filesystem/network privileges. Use trusted configuration and a disposable development container or VM for unreviewed candidates. No production credentials or production mutation targets.
|
|
10
|
+
|
|
11
|
+
Source upload is opt-in and file-allowlisted, but secret detection is not comprehensive: review `repair-request.json` before generation. Provider keys are not passed to child commands; processes can still access credentials on disk outside a sandbox. There is no implicit upload, automatic merge or deployment.
|
|
12
|
+
|
|
13
|
+
Saved browser state, Electron test profiles, source bundles, expected text, command logs and screenshots can contain private data. Output permissions are restrictive on POSIX; verify ACLs yourself on Windows. Never commit these artifacts. Before using an employer's code or services, obtain the required authorization.
|
|
14
|
+
|
|
7
15
|
## Reporting a vulnerability
|
|
8
16
|
|
|
9
17
|
Please do not open a public issue for a suspected vulnerability.
|
package/bin/attach.mjs
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { readFile, mkdir } from 'node:fs/promises';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
3
|
+
import { connectDesktop, selectDesktopPage } from '../src/desktop.mjs';
|
|
4
|
+
import { discoverHttp, httpDiscoveryConfig } from '../src/http-discover.mjs';
|
|
5
|
+
import { writeDiscoveryReport } from '../src/discovery-report.mjs';
|
|
6
|
+
import { prepareVisibility } from '../src/visibility.mjs';
|
|
7
|
+
import { checkDesktop } from '../src/desktop.mjs';
|
|
8
|
+
import { writeDesktopReport } from '../src/desktop-report.mjs';
|
|
9
|
+
export async function attachMain(args) {
|
|
10
|
+
const options = {};
|
|
11
|
+
for (let i = 0; i < args.length; i++) {
|
|
12
|
+
const arg = args[i];
|
|
13
|
+
if (arg === '--discover' || arg === '--restore-window') options[arg.slice(2)] = true;
|
|
14
|
+
else if (['--config', '--cdp', '--out', '--page'].includes(arg) && args[i + 1] && !args[i + 1].startsWith('--')) options[arg.slice(2)] = args[++i];
|
|
15
|
+
else throw new Error('Use web --attach [--discover] --config FILE [--cdp URL] [--page N] [--restore-window] [--out NEW_DIRECTORY]');
|
|
16
|
+
}
|
|
17
|
+
if (!options.config) throw new Error('--config is required');
|
|
18
|
+
let config = JSON.parse(await readFile(options.config, 'utf8'));
|
|
19
|
+
if (options.cdp) config.cdp = options.cdp;
|
|
20
|
+
if (options.page !== undefined) { if (!/^\d+$/.test(options.page)) throw new Error('Invalid page'); config.page = Number(options.page); }
|
|
21
|
+
if (options['restore-window']) config.restoreWindow = true;
|
|
22
|
+
if (options.discover) config = httpDiscoveryConfig(config);
|
|
23
|
+
const directory = resolve(options.out ?? `.recovery-probe/attached-${Date.now()}`);
|
|
24
|
+
await mkdir(resolve(directory, '..'), { recursive: true, mode: 0o700 });
|
|
25
|
+
await mkdir(directory, { mode: 0o700 });
|
|
26
|
+
const browser = await connectDesktop(config.cdp);
|
|
27
|
+
try {
|
|
28
|
+
const page = selectDesktopPage(browser, config);
|
|
29
|
+
let report;
|
|
30
|
+
if (options.discover) { report = await discoverHttp(page, config); await writeDiscoveryReport(directory, report, config); }
|
|
31
|
+
else {
|
|
32
|
+
const visibility = await prepareVisibility(page, config);
|
|
33
|
+
try { report = await checkDesktop(page, config); report.mode = 'attached browser recovery'; }
|
|
34
|
+
finally { await visibility.revert(); }
|
|
35
|
+
await writeDesktopReport(directory, report, config);
|
|
36
|
+
}
|
|
37
|
+
for (const f of report.findings ?? report.results) console.log(`${f.id ?? f.kind}: ${f.classification ?? f.code}${f.partial ? `; runs=${f.completedRuns}/${f.plannedRuns} partial; observed=${f.observedInterpretation.classification}` : ''}`);
|
|
38
|
+
if (report.error) console.error(report.error);
|
|
39
|
+
console.log(`Final reload: ${report.finalReset}\nReport: ${directory}/report.html`);
|
|
40
|
+
process.exitCode = report.ok ? 0 : options.discover ? 2 : report.results.some(r => r.outcome === 'fail') ? 1 : 2;
|
|
41
|
+
} finally { await browser.close(); }
|
|
42
|
+
}
|
package/bin/desktop.mjs
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { readFile, writeFile, mkdir } from 'node:fs/promises';
|
|
2
|
+
import { resolve, join } from 'node:path';
|
|
3
|
+
import { connectDesktop, desktopPages, selectDesktopPage, pageIdentity, discoverDesktop, checkDesktop, validateDesktopConfig } from '../src/desktop.mjs';
|
|
4
|
+
import { writeDesktopReport } from '../src/desktop-report.mjs';
|
|
5
|
+
|
|
6
|
+
export async function desktopMain(args) {
|
|
7
|
+
if (!args.length || args.includes('--help')) {
|
|
8
|
+
console.log(`Recovery Probe desktop preview
|
|
9
|
+
|
|
10
|
+
Attach to an Electron DEVELOPMENT renderer through its loopback debugging port.
|
|
11
|
+
|
|
12
|
+
recovery-probe desktop --list [--cdp http://127.0.0.1:9222]
|
|
13
|
+
recovery-probe desktop --discover --page 0 [--duration 5000] [--out .recovery-probe/discovery]
|
|
14
|
+
recovery-probe desktop --config scenario.json [--out .recovery-probe/run] [--screenshots]
|
|
15
|
+
|
|
16
|
+
Discovery reloads the chosen window and lists successful renderer GET JSON endpoints.
|
|
17
|
+
Checks reload it once per baseline/fault, optionally click the configured Retry button,
|
|
18
|
+
and perform a final reload reset. The app stays open. Use a test account/environment.
|
|
19
|
+
The config selects one endpoint and a data-dependent readySelector; see docs/desktop.md.
|
|
20
|
+
Requests made by native SDKs/IPC and untouched app screens are outside this check.
|
|
21
|
+
Reports stay local. Screenshots are opt-in and may contain private on-screen content.`);
|
|
22
|
+
return;
|
|
23
|
+
}
|
|
24
|
+
const options = {};
|
|
25
|
+
const values = new Set(['--cdp', '--page', '--duration', '--out', '--config']);
|
|
26
|
+
for (let i = 0; i < args.length; i++) {
|
|
27
|
+
const arg = args[i];
|
|
28
|
+
const key = arg.slice(2);
|
|
29
|
+
if (['--list', '--discover', '--screenshots'].includes(arg)) options[key] = true;
|
|
30
|
+
else if (values.has(arg)) {
|
|
31
|
+
if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${arg} needs a value`);
|
|
32
|
+
options[key] = args[++i];
|
|
33
|
+
} else throw new Error(`Unknown desktop option: ${arg}`);
|
|
34
|
+
}
|
|
35
|
+
if ([options.list, options.discover, options.config].filter(Boolean).length !== 1) throw new Error('Choose one of --list, --discover, or --config');
|
|
36
|
+
if (options.page !== undefined) {
|
|
37
|
+
if (!/^\d+$/.test(options.page)) throw new Error('--page must be a non-negative integer');
|
|
38
|
+
options.page = Number(options.page);
|
|
39
|
+
}
|
|
40
|
+
if (options.duration !== undefined && (!/^\d+$/.test(options.duration) || Number(options.duration) < 200 || Number(options.duration) > 30000)) throw new Error('--duration must be 200–30000 ms');
|
|
41
|
+
let config = options.config ? JSON.parse(await readFile(options.config, 'utf8')) : {};
|
|
42
|
+
if (options.page !== undefined) config.page = options.page;
|
|
43
|
+
config.cdp = options.cdp ?? config.cdp ?? 'http://127.0.0.1:9222';
|
|
44
|
+
if (options.config) config = validateDesktopConfig(config);
|
|
45
|
+
const browser = await connectDesktop(config.cdp);
|
|
46
|
+
try {
|
|
47
|
+
if (options.list) {
|
|
48
|
+
const pages = desktopPages(browser);
|
|
49
|
+
if (!pages.length) throw new Error('No renderer pages found');
|
|
50
|
+
pages.forEach((page, index) => console.log(`${index} ${pageIdentity(page.url())}`));
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
const page = selectDesktopPage(browser, config);
|
|
54
|
+
const directory = resolve(options.out ?? `.recovery-probe/${new Date().toISOString().replace(/[:.]/g, '-')}`);
|
|
55
|
+
await mkdir(directory, { recursive: true, mode: 0o700 });
|
|
56
|
+
if (options.discover) {
|
|
57
|
+
const discovery = await discoverDesktop(page, { durationMs: Number(options.duration ?? 5000) });
|
|
58
|
+
await writeFile(join(directory, 'discovery.json'), JSON.stringify(discovery, null, 2) + '\n', { mode: 0o600 });
|
|
59
|
+
const template = { cdp: config.cdp, page: desktopPages(browser).indexOf(page), pageUrl: discovery.pageUrl, endpoint: discovery.endpoints.length === 1 ? discovery.endpoints[0].endpoint : '', readySelector: '', retrySelector: '', recovery: 'retry', timeoutMs: 5000 };
|
|
60
|
+
await writeFile(join(directory, 'scenario.json'), JSON.stringify(template, null, 2) + '\n', { mode: 0o600 });
|
|
61
|
+
discovery.endpoints.forEach((row, index) => console.log(`${index + 1}. GET ${row.endpoint} (${row.observed} response(s), query values omitted)`));
|
|
62
|
+
if (!discovery.endpoints.length) console.log('No matching renderer GET JSON responses observed. The screen may use cached data, native SDK/IPC requests, a service worker, or load after the discovery window. This is not a pass.');
|
|
63
|
+
console.log(`\nDiscovery: ${join(directory, 'discovery.json')}\nFill endpoint (if blank), readySelector and retrySelector in ${join(directory, 'scenario.json')}`);
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
console.log('Checking the current development renderer. It will reload between faults.');
|
|
67
|
+
const report = await checkDesktop(page, config, {
|
|
68
|
+
onFailure: options.screenshots ? async (target, row) => {
|
|
69
|
+
const filename = `${row.kind}.png`;
|
|
70
|
+
await target.screenshot({ path: join(directory, filename), timeout: 5000 });
|
|
71
|
+
row.screenshot = filename;
|
|
72
|
+
} : undefined,
|
|
73
|
+
});
|
|
74
|
+
await writeDesktopReport(directory, report, config);
|
|
75
|
+
for (const row of report.results) console.log(`${row.outcome.toUpperCase().padEnd(12)} ${row.kind}: ${row.code} (injected ${row.applied}, later successful responses ${row.successfulResponsesAfterFault})`);
|
|
76
|
+
console.log(`Final reload reset: ${report.finalReset}\nReport: ${join(directory, 'report.html')}\nReproduce: node ${join(directory, 'reproduce.mjs')}\nFix investigation: ${join(directory, 'fix-brief.md')}`);
|
|
77
|
+
process.exitCode = report.ok ? 0 : report.results.some(row => row.outcome === 'fail') ? 1 : 2;
|
|
78
|
+
} finally {
|
|
79
|
+
// Closing a CDP connection disconnects this client; it does not close the existing app.
|
|
80
|
+
await browser.close();
|
|
81
|
+
}
|
|
82
|
+
}
|
package/bin/ipc.mjs
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { writeDiscoveryReport } from '../src/discovery-report.mjs';
|
|
2
|
+
import { readFile, mkdir, writeFile, mkdtemp } from 'node:fs/promises';
|
|
3
|
+
import { resolve, join } from 'node:path';
|
|
4
|
+
import { discoverIpc, discoveryConfig } from '../src/ipc-discover.mjs';
|
|
5
|
+
import { checkIpc } from '../src/ipc-check.mjs';
|
|
6
|
+
const escape = value => String(value).replace(/[&<>"']/g, c => ({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c]));
|
|
7
|
+
export async function ipcMain(args) {
|
|
8
|
+
if (!args.length || args.includes('--help')) {
|
|
9
|
+
console.log(`Recovery Probe IPC preview
|
|
10
|
+
recovery-probe ipc --config ipc-scenario.json [--out NEW_DIRECTORY] [--discover]
|
|
11
|
+
|
|
12
|
+
Requires a development-only main-process registration hook and two loopback ports:
|
|
13
|
+
Electron CDP (usually 9222) and Node inspector (usually 9229).
|
|
14
|
+
Default: verify one IPC rejection; null-result is explicitly optional.
|
|
15
|
+
--discover: compare healthy controls with single/double rejection and null-result experiments.
|
|
16
|
+
Discovery uses structural comparisons and language hints; findings require review. No readiness selector needed.
|
|
17
|
+
No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and scope.`);
|
|
18
|
+
return;
|
|
19
|
+
}
|
|
20
|
+
const options = {};
|
|
21
|
+
for (let i = 0; i < args.length; i++) {
|
|
22
|
+
if (args[i] === '--restore-window') { options.restoreWindow = true; continue; }
|
|
23
|
+
if (args[i] === '--discover') { options.discover = true; continue; }
|
|
24
|
+
if (!['--config', '--out'].includes(args[i]) || !args[i + 1] || args[i + 1].startsWith('--')) throw new Error('Use ipc --config FILE [--out NEW_DIRECTORY] [--discover]');
|
|
25
|
+
options[args[i].slice(2)] = args[++i];
|
|
26
|
+
}
|
|
27
|
+
if (!options.config) throw new Error('--config is required');
|
|
28
|
+
const rawConfig = JSON.parse(await readFile(options.config, 'utf8'));
|
|
29
|
+
if (options.restoreWindow) rawConfig.restoreWindow = true;
|
|
30
|
+
const config = options.discover ? discoveryConfig(rawConfig) : rawConfig;
|
|
31
|
+
const parent = resolve('.recovery-probe');
|
|
32
|
+
let directory;
|
|
33
|
+
if (options.out) { directory = resolve(options.out); await mkdir(directory, { mode: 0o700 }); }
|
|
34
|
+
else { await mkdir(parent, { recursive: true, mode: 0o700 }); directory = await mkdtemp(join(parent, 'ipc-')); }
|
|
35
|
+
await writeFile(join(directory, '.gitignore'), '*\n', { mode: 0o600 });
|
|
36
|
+
const report = options.discover ? await discoverIpc(config) : await checkIpc(config);
|
|
37
|
+
await writeFile(join(directory, 'scenario.json'), JSON.stringify(config, null, 2), { mode: 0o600 });
|
|
38
|
+
await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
|
|
39
|
+
const html = `<!doctype html><meta charset="utf-8"><title>Recovery Probe IPC report</title><style>body{max-width:1000px;margin:40px auto;font:16px system-ui;padding:20px}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#f4f5f7;padding:20px}</style><h1>${report.ok ? 'Selected IPC experiments completed without findings requiring review' : 'IPC recovery needs investigation'}</h1><p>${escape(report.limitation)}</p><p>Final reload: ${escape(report.finalReset)}. Cleanup cannot turn an earlier failure into a pass.</p><pre>${escape(JSON.stringify(report, null, 2))}</pre>`;
|
|
40
|
+
await writeFile(join(directory, 'report.html'), html, { mode: 0o600 });
|
|
41
|
+
if (options.discover) {
|
|
42
|
+
await writeDiscoveryReport(directory, report, config);
|
|
43
|
+
for (const finding of report.findings) console.log(`${finding.kind.toUpperCase()}: ${finding.id} — ${finding.classification}; runs=${finding.confirmations}${finding.partial ? `/${finding.plannedRuns} partial; observed=${finding.observedInterpretation.classification}` : ''}`);
|
|
44
|
+
if (report.error) console.error(`Discovery stopped: ${report.error}`);
|
|
45
|
+
if (report.cleanupError) console.error(`Cleanup: ${report.cleanupError}`);
|
|
46
|
+
console.log(`Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}\nReplay: recovery-probe ipc --discover --config ${join(directory, 'scenario.json')}`);
|
|
47
|
+
process.exitCode = report.ok ? 0 : 2; // Heuristic findings are never proven test failures.
|
|
48
|
+
return;
|
|
49
|
+
}
|
|
50
|
+
console.log(`Baseline: ${report.baseline?.code ?? report.error ?? 'not established'}`);
|
|
51
|
+
for (const row of report.results) console.log(`${row.outcome.toUpperCase()}: ${row.fault} — ${row.code}; injected=${row.snapshot.injected}; later real successes=${row.snapshot.successfulAfterFault}`);
|
|
52
|
+
if (report.error) console.error(`Check stopped: ${report.error}`);
|
|
53
|
+
if (report.cleanupError) console.error(`Cleanup: ${report.cleanupError}`);
|
|
54
|
+
console.log(`Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}`);
|
|
55
|
+
process.exitCode = report.ok ? 0 : report.results.some(row => row.outcome === 'fail') ? 1 : 2;
|
|
56
|
+
}
|
package/bin/observe.mjs
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { readFile, mkdir, writeFile, mkdtemp } from 'node:fs/promises';
|
|
2
|
+
import { resolve, join } from 'node:path';
|
|
3
|
+
import { randomUUID } from 'node:crypto';
|
|
4
|
+
import { createInterface } from 'node:readline';
|
|
5
|
+
import { connectDesktop, selectDesktopPage, desktopPages } from '../src/desktop.mjs';
|
|
6
|
+
import { connectIpcInspector } from '../src/ipc-inspector.mjs';
|
|
7
|
+
import { observationConfig, runObservation, httpObservationAdapter, ipcObservationAdapter } from '../src/observe.mjs';
|
|
8
|
+
const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c]));
|
|
9
|
+
|
|
10
|
+
export async function observeMain(args) {
|
|
11
|
+
if (!args.length || args.includes('--help')) {
|
|
12
|
+
console.log(`recovery-probe observe --config FILE [--out NEW_DIRECTORY] [--json] [--interactive]
|
|
13
|
+
|
|
14
|
+
Fault-free observation of an existing browser or Electron renderer.
|
|
15
|
+
No reload, navigation, focus change, fault injection or final UI reset.
|
|
16
|
+
Choose transport: http or ipc and explicit regionSelector/contentSelector CSS markers.
|
|
17
|
+
Navigate manually during the bounded capture. Enter marks a new interval in an
|
|
18
|
+
interactive terminal; --interactive also enables newline markers on piped input.
|
|
19
|
+
Ctrl+C saves partial evidence. CONTENT_BEFORE_READ is an observation, not a defect.
|
|
20
|
+
IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
21
|
+
return;
|
|
22
|
+
}
|
|
23
|
+
const options = {};
|
|
24
|
+
for (let i = 0; i < args.length; i++) {
|
|
25
|
+
if (['--json', '--interactive'].includes(args[i])) options[args[i].slice(2)] = true;
|
|
26
|
+
else if (['--config', '--out'].includes(args[i]) && args[i + 1] && !args[i + 1].startsWith('--')) options[args[i].slice(2)] = args[++i];
|
|
27
|
+
else throw Error('Use observe --config FILE [--out NEW_DIRECTORY] [--json] [--interactive]');
|
|
28
|
+
}
|
|
29
|
+
if (!options.config) throw Error('--config is required');
|
|
30
|
+
const config = observationConfig(JSON.parse(await readFile(options.config, 'utf8')));
|
|
31
|
+
let directory;
|
|
32
|
+
if (options.out) { directory = resolve(options.out); await mkdir(directory, { mode: 0o700 }); }
|
|
33
|
+
else { const parent = resolve('.recovery-probe'); await mkdir(parent, { recursive: true, mode: 0o700 }); directory = await mkdtemp(join(parent, 'observe-')); }
|
|
34
|
+
await writeFile(join(directory, '.gitignore'), '*\n', { mode: 0o600 });
|
|
35
|
+
const abort = new AbortController();
|
|
36
|
+
const stop = () => abort.abort();
|
|
37
|
+
process.on('SIGINT', stop); process.on('SIGTERM', stop);
|
|
38
|
+
let browser, control, input, report, pendingMarkers = 0;
|
|
39
|
+
try {
|
|
40
|
+
browser = await connectDesktop(config.cdp);
|
|
41
|
+
let page, adapter;
|
|
42
|
+
if (config.transport === 'ipc') {
|
|
43
|
+
control = await connectIpcInspector(config.inspector);
|
|
44
|
+
const identity = await control.call('identify');
|
|
45
|
+
if (!identity.registered.includes(config.channel)) throw Error('Configured read channel was not registered through the development hook');
|
|
46
|
+
const pages = desktopPages(browser).filter(p => p.url() === identity.pageUrl);
|
|
47
|
+
if (pages.length !== 1) throw Error('Keep exactly one matching IPC target window open');
|
|
48
|
+
page = pages[0];
|
|
49
|
+
const nonce = randomUUID();
|
|
50
|
+
await page.evaluate(value => {
|
|
51
|
+
if (Object.hasOwn(globalThis, '__recoveryProbeWindowNonce')) throw Error('Existing window challenge');
|
|
52
|
+
Object.defineProperty(globalThis, '__recoveryProbeWindowNonce', { value, configurable: true });
|
|
53
|
+
}, nonce);
|
|
54
|
+
try { await control.call('identify', nonce); }
|
|
55
|
+
finally { await page.evaluate(value => { if (globalThis.__recoveryProbeWindowNonce === value) delete globalThis.__recoveryProbeWindowNonce; }, nonce); }
|
|
56
|
+
adapter = ipcObservationAdapter(control, config, identity.senderId);
|
|
57
|
+
} else {
|
|
58
|
+
page = selectDesktopPage(browser, config);
|
|
59
|
+
adapter = httpObservationAdapter(page, config);
|
|
60
|
+
}
|
|
61
|
+
report = await runObservation(page, config, adapter, {
|
|
62
|
+
signal: abort.signal,
|
|
63
|
+
onReady() {
|
|
64
|
+
if (process.stdin.isTTY || options.interactive) {
|
|
65
|
+
input = createInterface({ input: process.stdin, terminal: false });
|
|
66
|
+
input.on('line', () => { pendingMarkers = Math.min(50, pendingMarkers + 1); });
|
|
67
|
+
input.on('SIGINT', stop);
|
|
68
|
+
}
|
|
69
|
+
console.error(`Observing for ${config.observationMs} ms without reloading. Navigate in the app now.${input ? ' Press Enter before each action to mark a new interval.' : ''} Ctrl+C saves partial evidence.`);
|
|
70
|
+
},
|
|
71
|
+
takeMarker() {
|
|
72
|
+
if (!pendingMarkers) return false;
|
|
73
|
+
pendingMarkers--;
|
|
74
|
+
return true;
|
|
75
|
+
},
|
|
76
|
+
onInterval() { console.error('New observation interval.'); },
|
|
77
|
+
});
|
|
78
|
+
} catch (error) {
|
|
79
|
+
report ??= { schemaVersion: 1, mode: 'fault-free observation', status: 'incomplete', captureComplete: false, intervals: [], findings: [], reloads: 0, injected: 0 };
|
|
80
|
+
report.error = error.message;
|
|
81
|
+
} finally {
|
|
82
|
+
if (input) { input.close(); process.stdin.pause(); }
|
|
83
|
+
control?.close();
|
|
84
|
+
try { await browser?.close(); } catch (error) { report.status = 'incomplete'; report.captureComplete = false; report.disconnectError = error.message; }
|
|
85
|
+
process.off('SIGINT', stop); process.off('SIGTERM', stop);
|
|
86
|
+
}
|
|
87
|
+
await writeFile(join(directory, 'scenario.json'), JSON.stringify(config, null, 2), { mode: 0o600 });
|
|
88
|
+
await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
|
|
89
|
+
const rows = report.intervals.map(i => `<tr><td>${i.index}</td><td>${i.reads?.calls ?? 'unknown'}</td><td>${i.reads?.successes ?? 'unknown'}</td><td>${i.reads?.errors ?? 'unknown'}</td><td>${i.firstContent ? i.firstContent.toMs - i.startMs + ' ms' : 'not sampled'}</td></tr>`).join('');
|
|
90
|
+
await writeFile(join(directory, 'report.html'), `<!doctype html><meta charset="utf-8"><title>Recovery Probe observation</title><style>body{font:16px system-ui;max-width:1000px;margin:40px auto;padding:20px}td,th{text-align:left;padding:8px}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style><h1>Fault-free observation</h1><p>Capture: ${escape(report.status)}. This is not a recovery or account-isolation verdict.</p><p>${escape(report.limitation ?? report.error)}</p><table><thead><tr><th>Interval</th><th>Reads started</th><th>Successes</th><th>Errors</th><th>First content sample</th></tr></thead><tbody>${rows}</tbody></table>${report.findings.map(f => `<p>Interval ${f.interval}: <strong>${escape(f.code)}</strong> — ${escape(f.basis)}</p>`).join('')}<details><summary>Evidence and coverage</summary><pre>${escape(JSON.stringify(report, null, 2))}</pre></details>`, { mode: 0o600 });
|
|
91
|
+
if (options.json) console.log(JSON.stringify({ ...report, reportPath: join(directory, 'report.json') }));
|
|
92
|
+
else {
|
|
93
|
+
for (const i of report.intervals) console.log(`Interval ${i.index}: ${i.reads?.calls ?? '?'} reads, ${i.reads?.successes ?? '?'} successes, ${i.reads?.errors ?? '?'} errors${i.findings.length ? '; ' + i.findings.join(', ') : ''}`);
|
|
94
|
+
if (report.error) console.error(report.error);
|
|
95
|
+
console.log(`Capture: ${report.status} (not a health verdict)\nReport: ${join(directory, 'report.html')}`);
|
|
96
|
+
}
|
|
97
|
+
process.exitCode = report.captureComplete ? 0 : report.status === 'interrupted' ? 130 : 2;
|
|
98
|
+
}
|