recovery-probe 0.2.0 → 0.3.0-preview.11

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 CHANGED
@@ -4,6 +4,96 @@ 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.11 (release candidate; npm publication separate)
8
+
9
+ - 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.
10
+ - 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.
11
+ - 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.
12
+ - Add browser and real Electron regression cases for delayed image cards, empty regions and inconsistent end states.
13
+ - Align installation guides on the exact preview version, document an unpublished-source fallback, and default preview publishing to npm's `next` tag. This candidate also includes the previously unpublished preview.3–preview.10 changes below.
14
+
15
+ ## 0.3.0-preview.10 (GitHub preview; npm publication separate)
16
+
17
+ - Calibrate HTTP/IPC refresh baselines using three full bounded windows and matching stable end states, rather than the first stable intermediate screen.
18
+ - Retain calibration evidence and trust a baseline only after all three reloads agree. Legitimate empty screens are not rejected based on item counts.
19
+ - Add delayed image-card and empty-content regression coverage.
20
+
21
+ ## 0.3.0-preview.9 (GitHub preview; npm publication separate)
22
+
23
+ - Refresh the README, setup guides and package description around general web/Electron recovery testing; pin preview installation instructions.
24
+ - Add `refresh --config FILE [--json]` for explicit synthetic window-event experiments on populated screens, using HTTP or IPC fault adapters.
25
+ - Keep fault-free trigger controls, idle attribution checks, spontaneous observations, optional second-trigger recovery and final cleanup separate.
26
+ - Record content preservation independently from freshness, bounded no-subsequent-read observations, partial plans and repeat consistency without confirming inconclusive experiments.
27
+ - Add browser/Electron fixtures and documentation. No real network toggling, lifecycle emulation, token manipulation or generic global-function execution.
28
+
29
+ ## 0.3.0-preview.8 (GitHub preview; npm publication separate)
30
+
31
+ - 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.
32
+ - 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.
33
+ - 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.
34
+
35
+ ## 0.3.0-preview.7 (GitHub preview; npm publication separate)
36
+
37
+ - Compare rendered groups, image counts and hashed repeated-column distributions, separating observations from suspected interpretations.
38
+ - Retain failed controls and phase-stop evidence; compact reports and change-only bounded timelines.
39
+ - Add bounded repeated HTTP faults (`times`), structural HTTP discovery and `web --attach` with live session reuse.
40
+ - Separate baseline/recovery windows and measure sampled recovery/request completion timing.
41
+ - Add window-state diagnostics and explicit reversible un-minimizing, including a dev-only Electron fallback.
42
+ - Report repeated reads without claiming redundancy, and list observed non-GET/unselected request coverage gaps.
43
+ - 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.
44
+
45
+ ## 0.3.0-preview.6 (GitHub preview; npm publication separate)
46
+
47
+ - Add bounded `ipc --discover`: three healthy baselines, repeated controls, single/double rejection and null-result experiments, three repetitions by default.
48
+ - 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.
49
+ - Preserve existing IPC verifier and public defaults; repeated hook faults are opt-in, atomically consumed and reset by run ID.
50
+ - English text heuristics and whole-region fingerprints can be inconclusive on changing/localized screens. No new web discovery or autonomous repair claims.
51
+
52
+
53
+ ## [0.3.0-preview.5] - Unreleased
54
+
55
+ - Use synchronous Node inspector evaluation for synchronous IPC controls, avoiding implicit Promise collection failures in Electron's main process.
56
+ - Retain and explicitly await the asynchronous window-identification Promise, releasing its inspector object group afterward.
57
+ - Treat a lost begin reply as uncertain execution: attempt scoped reset and independently verify disarmed state even when begin/reset replies fail.
58
+ - Add protocol regression tests and real Electron lost-begin-reply fault-cleanup tests; fail closed when cleanup cannot be verified.
59
+
60
+ ## [0.3.0-preview.4] - Unreleased
61
+
62
+ - Add an explicitly enabled main-process IPC registration adapter, scoped to allowed read channels and one window's main frame.
63
+ - Preserve normal call arguments, receiver and original return values; use no private Electron handler maps.
64
+ - Add one-shot rejection/null-result plans with IDs, TTL, reset, pending-call isolation and bounded per-channel counters.
65
+ - Add a noninteractive IPC checker over loopback Node inspector and renderer CDP, with measured baseline/deadline, dependency checks, fresh reloads and local reports.
66
+ - Treat extra traffic, missing dependencies and hidden/offline environments as inconclusive. Do not claim HTTP/Rust fault coverage.
67
+
68
+ ## [0.3.0-preview.3] - Unreleased
69
+
70
+ - 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.
71
+
72
+ - Add guided `start web` and `start desktop` commands with saved one-command reruns.
73
+ - Download missing Chromium automatically; combine manual login, request discovery, content picking, checks and local reports.
74
+ - Select a single Electron window automatically and show named choices for ambiguous windows/requests.
75
+ - Generate unique selectors from a user-selected content marker, and match Retry buttons by their visible label.
76
+ - Save private login state and configuration in an ignored local folder; no source access or AI upload in guided checks.
77
+ - Cover real browser setup/reruns, real Electron attachment and Windows publishing checks in CI.
78
+
79
+ ## [0.3.0-preview.2] - 2026-10-05
80
+
81
+ - Add Chromium web discovery/checks and explicit private login-state saving.
82
+ - Add opt-in OpenAI source-edit proposals from selected source files and reproduced evidence.
83
+ - Reproduce and verify in a separate local clone; preserve the original repository and never push/deploy a candidate.
84
+ - Reject unsafe paths, ambiguous replacements, dirty baselines, preexisting target ports and setup/test mutations.
85
+ - Separate reviewed verification from explicit opt-in execution of unreviewed generated code.
86
+ - Add authenticated web and Electron before/after integration tests with controlled provider responses.
87
+ - Clarify release stages and source-upload/report privacy boundaries. Live model fix quality is not yet validated.
88
+
89
+ ## [0.3.0-preview.1] - Unreleased
90
+
91
+ - Add Electron renderer discovery and targeted recovery checks through loopback CDP.
92
+ - Require a successful request after fault injection and a configured healthy UI marker.
93
+ - Add local HTML/JSON reports, executable reproductions, and coding-agent investigation briefs.
94
+ - Test real Electron attachment, preload preservation, recovery failures, automatic retry, stale UI markers, and disconnect behavior.
95
+ - Keep source-code fixes manual and reports local; native SDK/IPC traffic is outside this preview.
96
+
7
97
  ## [0.2.0] - 2026-09-22
8
98
 
9
99
  ### 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,75 @@
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.11**. 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.11 version
29
+ npm install --save-dev --save-exact recovery-probe@0.3.0-preview.11 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.
13
34
 
14
- ## What it catches
35
+ ## Choose a workflow
15
36
 
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.
37
+ | Goal | Entry point | Guide |
38
+ | --- | --- | --- |
39
+ | Set up a first request-recovery check interactively | `recovery-probe start web URL` or `start desktop` | [Guided start](docs/start.md) |
40
+ | Discover and test renderer reads in an existing browser or Electron window | `recovery-probe desktop --cdp URL` | [Attachment and HTTP discovery](docs/desktop.md) |
41
+ | Compare an Electron screen under IPC faults | `recovery-probe ipc --discover --config FILE` | [IPC setup and discovery](docs/ipc.md) |
42
+ | Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
43
+ | Add an explicit recovery assertion to a test | `withFault` or `createFaultFetch` | Examples below |
44
+ | Propose and verify a source change | Opt-in repair workflow | [Repair setup and limits](docs/repair.md) |
17
45
 
18
- Recovery Probe makes that failure deterministic:
46
+ `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
47
 
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.
48
+ 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
49
 
26
- ## Install
50
+ 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
51
 
28
- Recovery Probe is designed to be added to an existing Playwright project:
52
+ ## Refresh experiments
53
+
54
+ 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
55
 
30
56
  ```bash
31
- npm install --save-dev recovery-probe
57
+ npx recovery-probe refresh --config ./refresh.json --out ./refresh-run1 --json
32
58
  ```
33
59
 
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.
60
+ 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).
61
+
62
+ ## Reports and coding agents
63
+
64
+ 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.
65
+
66
+ 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
67
 
36
- ## Quick start
68
+ 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.
69
+
70
+ ![Recovery Probe catches a broken retry flow and verifies the corrected flow](docs/demo.svg)
71
+
72
+ ## Use in a Playwright test
37
73
 
38
74
  Use `withFault` inside an existing Playwright test. The callback contains the real user action and the application-specific recovery assertion.
39
75
 
@@ -87,7 +123,7 @@ fixed synthetic fixture
87
123
 
88
124
  `--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
125
 
90
- ## Supported faults
126
+ ## Library HTTP faults
91
127
 
92
128
  | Kind | Injected behavior |
93
129
  | --- | --- |
@@ -115,7 +151,7 @@ probe.assertApplied();
115
151
 
116
152
  `exerciseApplication` represents your own test adapter or application controller. Calling `assertApplied()` is essential: it proves that every requested fault was consumed.
117
153
 
118
- ## JSON-configured runner
154
+ ## Original JSON-configured runner
119
155
 
120
156
  The CLI supports pages that automatically load GET data, expose a visible Retry button after failure, and show a ready element after recovery.
121
157
 
@@ -142,7 +178,7 @@ Exit codes:
142
178
  - `1`: a recovery check failed, was inconclusive, or was skipped.
143
179
  - `2`: invalid arguments, configuration, or environment setup.
144
180
 
145
- ## Result semantics
181
+ ## Original runner result semantics
146
182
 
147
183
  | Code | Meaning |
148
184
  | --- | --- |
@@ -186,20 +222,25 @@ Recovery Probe deliberately focuses on deterministic request-level recovery chec
186
222
 
187
223
  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
224
 
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.
225
+ 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.
226
+
227
+ 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
228
 
191
229
  ## Development
192
230
 
193
231
  ```bash
194
232
  npm ci
195
- npm test # 9 fetch/core tests
233
+ npm test # fetch/core tests
196
234
  npm run test:package # isolated tarball install + TypeScript + CLI checks
197
235
  npx playwright install chromium
198
- npm run test:browser # 7 real-browser integration tests
236
+ npm run test:browser # real-browser integration tests
237
+ npm run test:repair # safety, authenticated portal, before/after pipeline
238
+ # After installing the optional Electron test runtime:
239
+ npm run test:repair:electron
199
240
  npm run demo:browser
200
241
  ```
201
242
 
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.
243
+ 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
244
 
204
245
  ## License
205
246
 
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
+ }
@@ -12,6 +12,13 @@ function printHelp() {
12
12
  Usage:
13
13
  recovery-probe --demo [--out report.json] [--json]
14
14
  recovery-probe --config scenario.json [--out report.json] [--json]
15
+ recovery-probe start web http://localhost:3000
16
+ recovery-probe start desktop
17
+ recovery-probe refresh --help
18
+ recovery-probe ipc --help
19
+ recovery-probe desktop --help
20
+ recovery-probe web --help
21
+ recovery-probe repair --help
15
22
  recovery-probe --version
16
23
 
17
24
  Options:
@@ -51,6 +58,30 @@ function printSummary(report) {
51
58
 
52
59
  async function main() {
53
60
  const args = process.argv.slice(2);
61
+ if (args[0] === 'refresh') {
62
+ const { refreshMain } = await import('./refresh.mjs');
63
+ return refreshMain(args.slice(1));
64
+ }
65
+ if (args[0] === 'ipc') {
66
+ const { ipcMain } = await import('./ipc.mjs');
67
+ return ipcMain(args.slice(1));
68
+ }
69
+ if (args[0] === 'start') {
70
+ const { startMain } = await import('./start.mjs');
71
+ return startMain(args.slice(1));
72
+ }
73
+ if (args[0] === 'web') {
74
+ const { webMain } = await import('./web.mjs');
75
+ return webMain(args.slice(1));
76
+ }
77
+ if (args[0] === 'repair') {
78
+ const { repairMain } = await import('./repair.mjs');
79
+ return repairMain(args.slice(1));
80
+ }
81
+ if (args[0] === 'desktop') {
82
+ const { desktopMain } = await import('./desktop.mjs');
83
+ return desktopMain(args.slice(1));
84
+ }
54
85
  if (args.includes('--help') || !args.length) {
55
86
  printHelp();
56
87
  return;
@@ -0,0 +1,45 @@
1
+ import { readFile, mkdir, writeFile } from 'node:fs/promises';
2
+ import { resolve } from 'node:path';
3
+ import { randomUUID } from 'node:crypto';
4
+ import { connectDesktop, selectDesktopPage, desktopPages } from '../src/desktop.mjs';
5
+ import { connectIpcInspector } from '../src/ipc-inspector.mjs';
6
+ import { prepareVisibility } from '../src/visibility.mjs';
7
+ import { refreshConfig, runRefresh } from '../src/refresh.mjs';
8
+ import { httpRefreshAdapter, ipcRefreshAdapter } from '../src/refresh-adapters.mjs';
9
+ const escape=value=>String(value).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
10
+ export async function refreshMain(args) {
11
+ if(args.includes('--help')){console.log('recovery-probe refresh --config FILE [--out NEW_DIRECTORY] [--json]\nOpt-in synthetic window-event refresh experiments. No network outage or OS resume. See docs/refresh.md.');return;}
12
+ const options={};for(let i=0;i<args.length;i++){if(args[i]==='--json')options.json=true;else if(['--config','--out'].includes(args[i])&&args[i+1]&&!args[i+1].startsWith('--'))options[args[i].slice(2)]=args[++i];else throw Error('Use refresh --config FILE [--out NEW_DIRECTORY] [--json]');}
13
+ if(!options.config)throw Error('--config required');
14
+ const c=refreshConfig(JSON.parse(await readFile(options.config,'utf8')));
15
+ const directory=resolve(options.out??`.recovery-probe/refresh-${Date.now()}`);
16
+ await mkdir(resolve(directory,'..'),{recursive:true,mode:0o700});await mkdir(directory,{mode:0o700});
17
+ await writeFile(resolve(directory,'.gitignore'),'*\n',{mode:0o600});
18
+ const abort=new AbortController();const onSignal=()=>abort.abort();process.on('SIGINT',onSignal);process.on('SIGTERM',onSignal);
19
+ let browser,control,visibility,report;
20
+ try {
21
+ browser=await connectDesktop(c.cdp);let page,adapter;
22
+ if(c.transport==='ipc') {
23
+ control=await connectIpcInspector(c.inspector);const identity=await control.call('identify');
24
+ if(c.times>identity.capabilities?.maxFaultCount)throw Error('IPC hook does not support requested fault count');
25
+ for(const channel of [c.channel,...c.requiredChannels])if(!identity.registered.includes(channel))throw Error('Configured channel was not captured');
26
+ const pages=desktopPages(browser).filter(p=>p.url()===identity.pageUrl);if(pages.length!==1)throw Error('Keep one matching IPC target open');page=pages[0];
27
+ const nonce=randomUUID();await page.evaluate(value=>{if(Object.hasOwn(globalThis,'__recoveryProbeWindowNonce'))throw Error('Existing challenge');Object.defineProperty(globalThis,'__recoveryProbeWindowNonce',{value,configurable:true});},nonce);
28
+ try{await control.call('identify',nonce);}finally{await page.evaluate(()=>delete globalThis.__recoveryProbeWindowNonce);}
29
+ adapter=ipcRefreshAdapter(control,c,identity.senderId);
30
+ } else {page=selectDesktopPage(browser,c);adapter=httpRefreshAdapter(page,c);}
31
+ visibility=await prepareVisibility(page,{...c,control,announce:console.error});
32
+ report=await runRefresh(page,c,adapter,{signal:abort.signal});report.window={initial:visibility.initial};
33
+ } catch(error) {report??={schemaVersion:1,mode:'refresh experiment',ok:false,finalReset:'not-verified',results:[],findings:[]};report.error=error.message;}
34
+ finally {
35
+ try{if(visibility){report.window??={initial:visibility.initial};report.window.restoration=await visibility.revert();}}catch(error){report.ok=false;report.windowRestoreError=error.message;}
36
+ control?.close();try{if(browser)await browser.close();}catch(error){report.ok=false;report.disconnectError=error.message;}
37
+ process.off('SIGINT',onSignal);process.off('SIGTERM',onSignal);
38
+ }
39
+ await writeFile(resolve(directory,'scenario.json'),JSON.stringify(c,null,2),{mode:0o600});
40
+ await writeFile(resolve(directory,'report.json'),JSON.stringify(report,null,2),{mode:0o600});
41
+ await writeFile(resolve(directory,'report.html'),`<!doctype html><meta charset="utf-8"><title>Recovery Probe refresh</title><style>body{font:16px system-ui;max-width:1000px;margin:40px auto;padding:20px}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style><h1>Refresh experiment</h1><p>${escape(report.limitation??report.error)}</p>${report.results.map(r=>`<p>${escape(r.summary??r.code??r.stage)}</p>`).join('')}<details><summary>Evidence</summary><pre>${escape(JSON.stringify(report,null,2))}</pre></details>`,{mode:0o600});
42
+ const summary={ok:report.ok,error:report.error,findings:report.findings,finalReset:report.finalReset,faultReset:report.faultReset,report:resolve(directory,'report.json')};
43
+ if(options.json)console.log(JSON.stringify(summary));else{for(const row of report.results)console.log(row.summary??row.code??row.stage);if(report.error)console.error(report.error);console.log(`Final reload: ${report.finalReset}\nReport: ${directory}/report.html`);}
44
+ process.exitCode=report.ok?0:2;
45
+ }