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.
Files changed (47) hide show
  1. package/CHANGELOG.md +97 -0
  2. package/CONTRIBUTING.md +14 -0
  3. package/README.md +69 -24
  4. package/SECURITY.md +8 -0
  5. package/bin/attach.mjs +42 -0
  6. package/bin/desktop.mjs +82 -0
  7. package/bin/ipc.mjs +56 -0
  8. package/bin/observe.mjs +98 -0
  9. package/bin/recovery-probe.mjs +36 -0
  10. package/bin/refresh.mjs +45 -0
  11. package/bin/repair.mjs +66 -0
  12. package/bin/start.mjs +31 -0
  13. package/bin/web.mjs +73 -0
  14. package/docs/desktop.md +201 -0
  15. package/docs/ipc.md +187 -0
  16. package/docs/observe.md +110 -0
  17. package/docs/refresh.md +90 -0
  18. package/docs/repair.md +208 -0
  19. package/docs/start.md +82 -0
  20. package/examples/demo-server.mjs +6 -5
  21. package/package.json +44 -8
  22. package/src/desktop-report.mjs +22 -0
  23. package/src/desktop.d.mts +24 -0
  24. package/src/desktop.mjs +222 -0
  25. package/src/discovery-control.mjs +28 -0
  26. package/src/discovery-report.mjs +11 -0
  27. package/src/guided-start.mjs +165 -0
  28. package/src/http-discover.mjs +108 -0
  29. package/src/http-observer.mjs +67 -0
  30. package/src/ipc-check.mjs +115 -0
  31. package/src/ipc-control.mjs +16 -0
  32. package/src/ipc-discover.mjs +154 -0
  33. package/src/ipc-inspector.d.mts +13 -0
  34. package/src/ipc-inspector.mjs +79 -0
  35. package/src/ipc-observation.mjs +113 -0
  36. package/src/ipc-probe.cjs +124 -0
  37. package/src/ipc-probe.d.cts +21 -0
  38. package/src/observe.mjs +194 -0
  39. package/src/pick-marker.mjs +66 -0
  40. package/src/refresh-adapters.mjs +39 -0
  41. package/src/refresh.mjs +140 -0
  42. package/src/repair-process.mjs +48 -0
  43. package/src/repair-provider.mjs +35 -0
  44. package/src/repair.mjs +249 -0
  45. package/src/visibility.mjs +56 -0
  46. package/src/web.d.mts +10 -0
  47. 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
  [![CI](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml/badge.svg)](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
4
8
  [![npm](https://img.shields.io/npm/v/recovery-probe.svg)](https://www.npmjs.com/package/recovery-probe)
5
- [![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
6
9
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
10
 
8
- **Deterministic fault injection for testing whether web applications actually recover after failed requests.**
11
+ ## Supported applications
9
12
 
10
- A happy-path test can pass while a Retry button is completely broken. Recovery Probe adds a small, explicit workflow around Playwright routing and `fetch`: inject one controlled failure, exercise the application's recovery path, and prove that the intended fault really occurred.
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
- ![Recovery Probe catches a broken retry flow and verifies the corrected flow](docs/demo.svg)
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
- ## What it catches
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
- Consider an application that loads normally, but forgets to clear its loading state after an error. Its ordinary end-to-end test stays green. After a transient `503`, interrupted request, or malformed response, Retry does nothing.
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
- Recovery Probe makes that failure deterministic:
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
- 1. Match one endpoint and request method.
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
- ## Install
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
- Recovery Probe is designed to be added to an existing Playwright project:
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
- npm install --save-dev recovery-probe
61
+ npx recovery-probe refresh --config ./refresh.json --out ./refresh-run1 --json
32
62
  ```
33
63
 
34
- Node.js 22 or newer is required. Playwright is an optional peer dependency: the fetch-only API works without it, while the browser helper and CLI require Playwright 1.62.1 or newer.
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
- ## Quick start
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
+ ![Recovery Probe catches a broken retry flow and verifies the corrected flow](docs/demo.svg)
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
- ## Supported faults
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
- ## Result semantics
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. Reports contain structural outcomes and environment versions, not request bodies, response bodies, headers, or full target URLs. Recovery Probe sends no telemetry.
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 # 9 fetch/core tests
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 # 7 real-browser integration tests
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, then runs the integration suite and controlled demo in Chromium. See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and [SECURITY.md](SECURITY.md) for private vulnerability reporting.
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
+ }
@@ -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 => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[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
+ }
@@ -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 => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[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
+ }