recovery-probe 0.3.0-preview.2 → 0.3.0
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 +139 -36
- package/CONTRIBUTING.md +59 -39
- package/LICENSE +21 -21
- package/README.md +255 -233
- package/SECURITY.md +26 -26
- package/bin/attach.mjs +42 -0
- package/bin/core-demo.mjs +8 -8
- package/bin/desktop.mjs +82 -82
- package/bin/ipc.mjs +56 -0
- package/bin/observe.mjs +103 -0
- package/bin/recovery-probe.mjs +156 -135
- package/bin/refresh.mjs +45 -0
- package/bin/repair.mjs +66 -66
- package/bin/start.mjs +31 -0
- package/bin/web.mjs +73 -66
- package/docs/ci.md +65 -0
- package/docs/demo.svg +70 -70
- package/docs/desktop.md +201 -133
- package/docs/ipc.md +187 -0
- package/docs/observe.md +152 -0
- package/docs/refresh.md +90 -0
- package/docs/repair.md +208 -208
- package/docs/start.md +82 -0
- package/examples/ci/run.mjs +70 -0
- package/examples/ci/scenario.json +8 -0
- package/examples/ci/verify.mjs +26 -0
- package/examples/core-demo.mjs +39 -39
- package/examples/demo-server.mjs +57 -57
- package/examples/profile-controller.mjs +26 -26
- package/package.json +123 -100
- package/src/desktop-report.mjs +22 -22
- package/src/desktop.d.mts +24 -23
- package/src/desktop.mjs +222 -213
- package/src/discovery-control.mjs +28 -0
- package/src/discovery-report.mjs +11 -0
- package/src/fetch-fault.d.mts +19 -19
- package/src/fetch-fault.mjs +54 -54
- package/src/guided-start.mjs +165 -0
- package/src/http-discover.mjs +108 -0
- package/src/http-observer.mjs +67 -0
- package/src/index.d.ts +26 -26
- package/src/index.mjs +159 -159
- package/src/ipc-check.mjs +115 -0
- package/src/ipc-control.mjs +16 -0
- package/src/ipc-discover.mjs +154 -0
- package/src/ipc-inspector.d.mts +13 -0
- package/src/ipc-inspector.mjs +79 -0
- package/src/ipc-observation.mjs +142 -0
- package/src/ipc-probe.cjs +125 -0
- package/src/ipc-probe.d.cts +21 -0
- package/src/observation-report.mjs +126 -0
- package/src/observe.mjs +215 -0
- package/src/pick-marker.mjs +66 -0
- package/src/refresh-adapters.mjs +39 -0
- package/src/refresh.mjs +140 -0
- package/src/repair-process.mjs +48 -48
- package/src/repair-provider.mjs +35 -35
- package/src/repair.mjs +249 -249
- package/src/visibility.mjs +56 -0
- package/src/web.d.mts +10 -10
- package/src/web.mjs +29 -29
package/README.md
CHANGED
|
@@ -1,233 +1,255 @@
|
|
|
1
|
-
# Recovery Probe
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
npm
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
`
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
1
|
+
# Recovery Probe
|
|
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
|
+
|
|
7
|
+
[](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
|
|
8
|
+
[](https://www.npmjs.com/package/recovery-probe)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
|
|
11
|
+
## Supported applications
|
|
12
|
+
|
|
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 |
|
|
19
|
+
|
|
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
|
|
23
|
+
|
|
24
|
+
**0.3.0** is the stable release target on npm's `latest` channel. The commands below pin the version for reproducible reports. Prereleases use `next` and are opt-in.
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
28
|
+
npm view recovery-probe@0.3.0 version
|
|
29
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0 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
|
|
36
|
+
|
|
37
|
+
**New in 0.3.0:** guided setup, HTTP/IPC discovery, refresh experiments and [fault-free observation](docs/observe.md) extend the original recovery helpers. Observation records selected reads and content while you navigate without reloading or clearing caches. Lightweight sampling, phase timings and separate cleanup evidence make capture cost and scope explicit. Use `"detail": "region"` for full DOM diagnostics.
|
|
38
|
+
|
|
39
|
+
Content comparisons preserve the first observed result and summarize later samples: a temporary difference can subsequently match the baseline, or diverge again. These are observations, not ownership, freshness or stability verdicts. See the guide for updating the development IPC hook before capturing cached state; see the changelog for upgrading from 0.2.0.
|
|
40
|
+
|
|
41
|
+
| Goal | Entry point | Guide |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| Set up a first request-recovery check interactively | `recovery-probe start web URL` or `start desktop` | [Guided start](docs/start.md) |
|
|
44
|
+
| Discover and test renderer reads in an existing browser or Electron window | `recovery-probe desktop --cdp URL` | [Attachment and HTTP discovery](docs/desktop.md) |
|
|
45
|
+
| Compare an Electron screen under IPC faults | `recovery-probe ipc --discover --config FILE` | [IPC setup and discovery](docs/ipc.md) |
|
|
46
|
+
| Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
|
|
47
|
+
| Observe cached content without a reload | `recovery-probe observe --config FILE` | [Observation](docs/observe.md) |
|
|
48
|
+
| Run a repeatable synthetic recovery check in CI | `npm run test:ci-example` (source checkout) | [CI example](docs/ci.md) |
|
|
49
|
+
| Add an explicit recovery assertion to a test | `withFault` or `createFaultFetch` | Examples below |
|
|
50
|
+
| Propose and verify a source change | Opt-in repair workflow | [Repair setup and limits](docs/repair.md) |
|
|
51
|
+
|
|
52
|
+
`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.
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
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.
|
|
57
|
+
|
|
58
|
+
**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.
|
|
59
|
+
|
|
60
|
+
## Refresh experiments
|
|
61
|
+
|
|
62
|
+
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.
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npx recovery-probe refresh --config ./refresh.json --out ./refresh-run1 --json
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
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).
|
|
69
|
+
|
|
70
|
+
## Reports and coding agents
|
|
71
|
+
|
|
72
|
+
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.
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+

|
|
79
|
+
|
|
80
|
+
## Use in a Playwright test
|
|
81
|
+
|
|
82
|
+
Use `withFault` inside an existing Playwright test. The callback contains the real user action and the application-specific recovery assertion.
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
import { test, expect } from '@playwright/test';
|
|
86
|
+
import { withFault } from 'recovery-probe';
|
|
87
|
+
|
|
88
|
+
test('profile recovers after a transient 503', async ({ page }) => {
|
|
89
|
+
const stats = await withFault(page, {
|
|
90
|
+
match: '**/api/profile',
|
|
91
|
+
kind: 'http-error',
|
|
92
|
+
status: 503,
|
|
93
|
+
count: 1,
|
|
94
|
+
}, async () => {
|
|
95
|
+
await page.goto('http://127.0.0.1:3000/profile');
|
|
96
|
+
await page.getByRole('button', { name: 'Retry' }).click();
|
|
97
|
+
await expect(page.getByTestId('profile-name')).toHaveText('Test User');
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
expect(stats.applied).toBe(1);
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
If the endpoint does not match, Recovery Probe throws `FAULT_NOT_TRIGGERED` instead of allowing the test to pass silently. If the fault is applied but the recovery assertion fails, it throws `RECOVERY_ASSERTION_FAILED` and retains the original assertion error as `cause`.
|
|
105
|
+
|
|
106
|
+
## Run the demonstration
|
|
107
|
+
|
|
108
|
+
The repository includes deliberately broken and corrected applications. Both pass their normal loading check; only the corrected application recovers from all three faults.
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npm install
|
|
112
|
+
npx playwright install chromium
|
|
113
|
+
npx recovery-probe --demo
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
The command prints a concise comparison:
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
broken synthetic fixture
|
|
120
|
+
PASS Normal connection (OK)
|
|
121
|
+
CAUGHT HTTP 503 once (RECOVERY_ASSERTION_FAILED, injected 1)
|
|
122
|
+
CAUGHT Interrupted request once (RECOVERY_ASSERTION_FAILED, injected 1)
|
|
123
|
+
CAUGHT Malformed JSON once (RECOVERY_ASSERTION_FAILED, injected 1)
|
|
124
|
+
|
|
125
|
+
fixed synthetic fixture
|
|
126
|
+
PASS Normal connection (OK)
|
|
127
|
+
PASS HTTP 503 once (OK, injected 1)
|
|
128
|
+
PASS Interrupted request once (OK, injected 1)
|
|
129
|
+
PASS Malformed JSON once (OK, injected 1)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`--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.
|
|
133
|
+
|
|
134
|
+
## Library HTTP faults
|
|
135
|
+
|
|
136
|
+
| Kind | Injected behavior |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| `http-error` | Fulfils the matched request with an HTTP error status; defaults to `503`. |
|
|
139
|
+
| `connection-failure` | Aborts the matched Playwright request with `connectionfailed`, or throws from the fetch adapter. |
|
|
140
|
+
| `invalid-json` | Returns status `200` with a deliberately malformed JSON body. |
|
|
141
|
+
|
|
142
|
+
Faults are bounded by `count` (default `1`, maximum `20`). The count is reserved synchronously, so concurrent matching requests cannot over-inject.
|
|
143
|
+
|
|
144
|
+
## Fetch-only tests
|
|
145
|
+
|
|
146
|
+
The lightweight `recovery-probe/fetch` entry point has no runtime dependencies and does not require Playwright. It matches one exact absolute URL, including its query string, and never patches global `fetch`.
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
import { createFaultFetch } from 'recovery-probe/fetch';
|
|
150
|
+
|
|
151
|
+
const probe = createFaultFetch(fetch, {
|
|
152
|
+
url: 'http://127.0.0.1:3000/api/profile',
|
|
153
|
+
kind: 'connection-failure',
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
await exerciseApplication(probe.fetch);
|
|
157
|
+
probe.assertApplied();
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`exerciseApplication` represents your own test adapter or application controller. Calling `assertApplied()` is essential: it proves that every requested fault was consumed.
|
|
161
|
+
|
|
162
|
+
## Original JSON-configured runner
|
|
163
|
+
|
|
164
|
+
The CLI supports pages that automatically load GET data, expose a visible Retry button after failure, and show a ready element after recovery.
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"name": "Profile recovery",
|
|
169
|
+
"url": "http://127.0.0.1:3000/profile",
|
|
170
|
+
"requestPattern": "**/api/profile",
|
|
171
|
+
"readySelector": "[data-testid=profile-ready]",
|
|
172
|
+
"retrySelector": "[data-testid=profile-retry]",
|
|
173
|
+
"timeoutMs": 3000
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
npx recovery-probe --config recovery-probe.json --out artifacts/profile-recovery.json
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
The runner first checks the normal baseline in a fresh browser context. If that baseline fails, fault comparisons are skipped and reported as inconclusive. Each fault then receives its own fresh context with service workers blocked so Playwright can intercept the request.
|
|
182
|
+
|
|
183
|
+
Exit codes:
|
|
184
|
+
|
|
185
|
+
- `0`: every configured check passed, or the controlled demo observed its expected broken-versus-fixed result.
|
|
186
|
+
- `1`: a recovery check failed, was inconclusive, or was skipped.
|
|
187
|
+
- `2`: invalid arguments, configuration, or environment setup.
|
|
188
|
+
|
|
189
|
+
## Original runner result semantics
|
|
190
|
+
|
|
191
|
+
| Code | Meaning |
|
|
192
|
+
| --- | --- |
|
|
193
|
+
| `OK` | The configured assertion completed and the expected fault count was observed. |
|
|
194
|
+
| `RECOVERY_ASSERTION_FAILED` | The fault occurred, but the recovery assertion did not pass. |
|
|
195
|
+
| `FAULT_NOT_TRIGGERED` | The requested fault count was not observed. Check the route, method, cache, and service worker. |
|
|
196
|
+
| `BASELINE_FAILED` | The ordinary flow failed, so the runner could not make a useful fault comparison. |
|
|
197
|
+
| `INJECTION_ERROR` | Playwright could not apply or clean up the route reliably. |
|
|
198
|
+
|
|
199
|
+
A passing result proves the configured recovery behavior for that test. It is not a certification of overall application resilience.
|
|
200
|
+
|
|
201
|
+
## API
|
|
202
|
+
|
|
203
|
+
### `withFault(page, options, exercise)`
|
|
204
|
+
|
|
205
|
+
Installs one temporary Playwright route, runs `exercise`, verifies the requested fault count, and removes only that route handler.
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
interface FaultOptions {
|
|
209
|
+
match: string | RegExp;
|
|
210
|
+
kind: 'http-error' | 'connection-failure' | 'invalid-json';
|
|
211
|
+
status?: number;
|
|
212
|
+
count?: number;
|
|
213
|
+
method?: string;
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Register the fault after your own route mocks. The helper uses `route.fallback()` for requests it does not inject, allowing earlier handlers to continue processing them.
|
|
218
|
+
|
|
219
|
+
### `createFaultFetch(baseFetch, options)`
|
|
220
|
+
|
|
221
|
+
Creates an isolated fetch wrapper for one exact URL and method. It returns `{ fetch, summary, assertApplied }` and leaves the supplied fetch function unchanged.
|
|
222
|
+
|
|
223
|
+
### `probeRecovery(browser, config)`
|
|
224
|
+
|
|
225
|
+
Runs the baseline and the three default recovery checks used by the JSON CLI. For custom interactions or stronger assertions, prefer `withFault` inside your own test.
|
|
226
|
+
|
|
227
|
+
## Scope
|
|
228
|
+
|
|
229
|
+
Recovery Probe deliberately focuses on deterministic request-level recovery checks. It does not simulate whole-device offline states, WebSocket interruptions, token expiry, browser sleep, slow-network profiles, or duplicate-submission safety.
|
|
230
|
+
|
|
231
|
+
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.
|
|
232
|
+
|
|
233
|
+
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.
|
|
234
|
+
|
|
235
|
+
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.
|
|
236
|
+
|
|
237
|
+
## Development
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
npm ci
|
|
241
|
+
npm test # fetch/core tests
|
|
242
|
+
npm run test:package # isolated tarball install + TypeScript + CLI checks
|
|
243
|
+
npx playwright install chromium
|
|
244
|
+
npm run test:browser # real-browser integration tests
|
|
245
|
+
npm run test:repair # safety, authenticated portal, before/after pipeline
|
|
246
|
+
# After installing the optional Electron test runtime:
|
|
247
|
+
npm run test:repair:electron
|
|
248
|
+
npm run demo:browser
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
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).
|
|
252
|
+
|
|
253
|
+
## License
|
|
254
|
+
|
|
255
|
+
[MIT](LICENSE) © 2026 Bojan Kovachki
|
package/SECURITY.md
CHANGED
|
@@ -1,26 +1,26 @@
|
|
|
1
|
-
# Security
|
|
2
|
-
|
|
3
|
-
## Supported versions
|
|
4
|
-
|
|
5
|
-
Security fixes are applied to the latest published version of Recovery Probe.
|
|
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
|
-
|
|
15
|
-
## Reporting a vulnerability
|
|
16
|
-
|
|
17
|
-
Please do not open a public issue for a suspected vulnerability.
|
|
18
|
-
|
|
19
|
-
Use [GitHub's private vulnerability reporting](https://github.com/BojanKovachki/recovery-probe/security/advisories/new) and include:
|
|
20
|
-
|
|
21
|
-
- the affected version;
|
|
22
|
-
- a minimal reproduction;
|
|
23
|
-
- the expected and observed behavior;
|
|
24
|
-
- any known impact.
|
|
25
|
-
|
|
26
|
-
Reports should not contain real credentials, production request data, or other sensitive application information. I aim to acknowledge reports within seven days.
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
Security fixes are applied to the latest published version of Recovery Probe.
|
|
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
|
+
|
|
15
|
+
## Reporting a vulnerability
|
|
16
|
+
|
|
17
|
+
Please do not open a public issue for a suspected vulnerability.
|
|
18
|
+
|
|
19
|
+
Use [GitHub's private vulnerability reporting](https://github.com/BojanKovachki/recovery-probe/security/advisories/new) and include:
|
|
20
|
+
|
|
21
|
+
- the affected version;
|
|
22
|
+
- a minimal reproduction;
|
|
23
|
+
- the expected and observed behavior;
|
|
24
|
+
- any known impact.
|
|
25
|
+
|
|
26
|
+
Reports should not contain real credentials, production request data, or other sensitive application information. I aim to acknowledge reports within seven days.
|
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
|
+
}
|