recovery-probe 0.0.0-stage → 0.3.0-preview.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +36 -0
- package/CONTRIBUTING.md +39 -0
- package/LICENSE +21 -0
- package/README.md +233 -3
- package/SECURITY.md +26 -0
- package/bin/core-demo.mjs +8 -0
- package/bin/desktop.mjs +82 -0
- package/bin/recovery-probe.mjs +135 -0
- package/bin/repair.mjs +66 -0
- package/bin/web.mjs +66 -0
- package/docs/demo.svg +70 -0
- package/docs/desktop.md +133 -0
- package/docs/repair.md +208 -0
- package/examples/core-demo.mjs +39 -0
- package/examples/demo-server.mjs +57 -0
- package/examples/profile-controller.mjs +26 -0
- package/package.json +100 -6
- package/src/desktop-report.mjs +22 -0
- package/src/desktop.d.mts +23 -0
- package/src/desktop.mjs +213 -0
- package/src/fetch-fault.d.mts +19 -0
- package/src/fetch-fault.mjs +54 -0
- package/src/index.d.ts +26 -0
- package/src/index.mjs +159 -0
- package/src/repair-process.mjs +48 -0
- package/src/repair-provider.mjs +35 -0
- package/src/repair.mjs +249 -0
- package/src/web.d.mts +10 -0
- package/src/web.mjs +29 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to Recovery Probe are documented here. The project follows [Semantic Versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
|
|
6
|
+
|
|
7
|
+
## [0.3.0-preview.2] - Unreleased
|
|
8
|
+
|
|
9
|
+
- Add Chromium web discovery/checks and explicit private login-state saving.
|
|
10
|
+
- Add opt-in OpenAI source-edit proposals from selected source files and reproduced evidence.
|
|
11
|
+
- Reproduce and verify in a separate local clone; preserve the original repository and never push/deploy a candidate.
|
|
12
|
+
- Reject unsafe paths, ambiguous replacements, dirty baselines, preexisting target ports and setup/test mutations.
|
|
13
|
+
- Separate reviewed verification from explicit opt-in execution of unreviewed generated code.
|
|
14
|
+
- Add authenticated web and Electron before/after integration tests with controlled provider responses.
|
|
15
|
+
- Clarify release stages and source-upload/report privacy boundaries. Live model fix quality is not yet validated.
|
|
16
|
+
|
|
17
|
+
## [0.3.0-preview.1] - Unreleased
|
|
18
|
+
|
|
19
|
+
- Add Electron renderer discovery and targeted recovery checks through loopback CDP.
|
|
20
|
+
- Require a successful request after fault injection and a configured healthy UI marker.
|
|
21
|
+
- Add local HTML/JSON reports, executable reproductions, and coding-agent investigation briefs.
|
|
22
|
+
- Test real Electron attachment, preload preservation, recovery failures, automatic retry, stale UI markers, and disconnect behavior.
|
|
23
|
+
- Keep source-code fixes manual and reports local; native SDK/IPC traffic is outside this preview.
|
|
24
|
+
|
|
25
|
+
## [0.2.0] - 2026-09-22
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
- Deterministic HTTP error, connection failure, and invalid JSON injection.
|
|
30
|
+
- Playwright `withFault` helper with bounded counts and route cleanup.
|
|
31
|
+
- Browser-independent `createFaultFetch` adapter.
|
|
32
|
+
- JSON-configured CLI runner with human-readable and machine-readable output.
|
|
33
|
+
- Broken-versus-fixed browser demonstration.
|
|
34
|
+
- Core, real-browser, package-installation, and TypeScript integration tests.
|
|
35
|
+
|
|
36
|
+
[0.2.0]: https://github.com/BojanKovachki/recovery-probe/releases/tag/v0.2.0
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thanks for helping make recovery checks easier to trust.
|
|
4
|
+
|
|
5
|
+
## Before opening a change
|
|
6
|
+
|
|
7
|
+
- Use Node.js 22 or newer.
|
|
8
|
+
- Keep changes focused on deterministic request-level recovery testing.
|
|
9
|
+
- Open an issue first for new fault models or public API changes.
|
|
10
|
+
- Do not include real credentials, production URLs, request bodies, or response bodies in fixtures or reports.
|
|
11
|
+
|
|
12
|
+
## Development setup
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm ci
|
|
16
|
+
npm test
|
|
17
|
+
npm run test:package
|
|
18
|
+
npx playwright install chromium
|
|
19
|
+
npm run test:browser
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Run the controlled demonstrations when behavior or output changes:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm run demo
|
|
26
|
+
npm run demo:browser
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Pull requests
|
|
30
|
+
|
|
31
|
+
A useful pull request:
|
|
32
|
+
|
|
33
|
+
- explains the recovery behavior it covers;
|
|
34
|
+
- includes a failing test for a bug fix;
|
|
35
|
+
- preserves the distinction between failed, inconclusive, and skipped results;
|
|
36
|
+
- keeps fault injection bounded and verifies that the fault occurred;
|
|
37
|
+
- updates the README and changelog when the public interface changes.
|
|
38
|
+
|
|
39
|
+
By submitting a contribution, you agree that it is licensed under the project's MIT license.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bojan Kovachki
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,233 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# Recovery Probe
|
|
2
|
+
|
|
3
|
+
[](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/recovery-probe)
|
|
5
|
+
[](https://nodejs.org/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
**Find reproducible request-recovery bugs in web and Electron apps. Propose a source fix, then test the candidate.**
|
|
9
|
+
|
|
10
|
+
A happy-path test can pass while a transient failed request leaves an app permanently loading. Recovery Probe injects controlled failures and checks what happens next. Recovery may be automatic; a Retry button or special recovery screen is not required.
|
|
11
|
+
|
|
12
|
+
## Release status
|
|
13
|
+
|
|
14
|
+
| Version | Available functionality |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| npm `0.2.0` | Playwright/fetch fault helpers and the original configured CLI. No source investigation or automatic fixes. |
|
|
17
|
+
| GitHub `0.3.0-preview.2`, `feat/repair-workflow` | Web and Electron discovery/checks; browser login-state support; opt-in AI source-edit proposals; isolated-checkout before/after verification. Not yet a stable npm release. |
|
|
18
|
+
| Not implemented | General discovery/fixing of arbitrary bugs, production self-healing, autonomous deployment, native/IPC request interception. |
|
|
19
|
+
|
|
20
|
+
The repair preview needs a local source repository, explicit source-file selection, one expected outcome, app launch/test commands, and your own API key/model for generation. It does **not** obtain these from installing an npm dependency. It returns a reviewable candidate, not a guaranteed fix. [Full setup and safety guide](docs/repair.md).
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# Preview only; pin the commit when sharing a reproducible installation.
|
|
24
|
+
npm install --save-dev github:BojanKovachki/recovery-probe#feat/repair-workflow playwright
|
|
25
|
+
npx playwright install chromium
|
|
26
|
+
npx recovery-probe web --help
|
|
27
|
+
npx recovery-probe repair --help
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
|
|
32
|
+
## What it catches
|
|
33
|
+
|
|
34
|
+
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.
|
|
35
|
+
|
|
36
|
+
Recovery Probe makes that failure deterministic:
|
|
37
|
+
|
|
38
|
+
1. Match one endpoint and request method.
|
|
39
|
+
2. Inject a bounded fault without replacing global `fetch`.
|
|
40
|
+
3. Run the real recovery interaction and assertion.
|
|
41
|
+
4. Fail if the fault was never observed, so a wrong route cannot create a false positive.
|
|
42
|
+
5. Remove only its own route handler and preserve existing mocks.
|
|
43
|
+
|
|
44
|
+
## Web and Electron preview
|
|
45
|
+
|
|
46
|
+
Use `web` for a Chromium portal and `desktop` to attach to an existing development Electron renderer. Both use the same Page-level checking engine. Checks discover GET JSON endpoints, inject selected faults, and produce local evidence. Use the separate `repair` command to reproduce in a clean checkout, request an AI proposal with explicit upload consent, and rerun the scenario after applying the candidate only to that copy. See [web/repair setup](docs/repair.md) and [desktop attachment](docs/desktop.md). npm 0.2.0 includes neither workflow.
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
Recovery Probe is designed to be added to an existing Playwright project:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npm install --save-dev recovery-probe
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Node.js 22 or newer is required. Playwright is an optional peer dependency: the fetch-only API works without it, while browser/desktop commands require Playwright `^1.62.1` (1.x).
|
|
57
|
+
|
|
58
|
+
## Quick start
|
|
59
|
+
|
|
60
|
+
Use `withFault` inside an existing Playwright test. The callback contains the real user action and the application-specific recovery assertion.
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
import { test, expect } from '@playwright/test';
|
|
64
|
+
import { withFault } from 'recovery-probe';
|
|
65
|
+
|
|
66
|
+
test('profile recovers after a transient 503', async ({ page }) => {
|
|
67
|
+
const stats = await withFault(page, {
|
|
68
|
+
match: '**/api/profile',
|
|
69
|
+
kind: 'http-error',
|
|
70
|
+
status: 503,
|
|
71
|
+
count: 1,
|
|
72
|
+
}, async () => {
|
|
73
|
+
await page.goto('http://127.0.0.1:3000/profile');
|
|
74
|
+
await page.getByRole('button', { name: 'Retry' }).click();
|
|
75
|
+
await expect(page.getByTestId('profile-name')).toHaveText('Test User');
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
expect(stats.applied).toBe(1);
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
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`.
|
|
83
|
+
|
|
84
|
+
## Run the demonstration
|
|
85
|
+
|
|
86
|
+
The repository includes deliberately broken and corrected applications. Both pass their normal loading check; only the corrected application recovers from all three faults.
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npm install
|
|
90
|
+
npx playwright install chromium
|
|
91
|
+
npx recovery-probe --demo
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The command prints a concise comparison:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
broken synthetic fixture
|
|
98
|
+
PASS Normal connection (OK)
|
|
99
|
+
CAUGHT HTTP 503 once (RECOVERY_ASSERTION_FAILED, injected 1)
|
|
100
|
+
CAUGHT Interrupted request once (RECOVERY_ASSERTION_FAILED, injected 1)
|
|
101
|
+
CAUGHT Malformed JSON once (RECOVERY_ASSERTION_FAILED, injected 1)
|
|
102
|
+
|
|
103
|
+
fixed synthetic fixture
|
|
104
|
+
PASS Normal connection (OK)
|
|
105
|
+
PASS HTTP 503 once (OK, injected 1)
|
|
106
|
+
PASS Interrupted request once (OK, injected 1)
|
|
107
|
+
PASS Malformed JSON once (OK, injected 1)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`--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.
|
|
111
|
+
|
|
112
|
+
## Supported faults
|
|
113
|
+
|
|
114
|
+
| Kind | Injected behavior |
|
|
115
|
+
| --- | --- |
|
|
116
|
+
| `http-error` | Fulfils the matched request with an HTTP error status; defaults to `503`. |
|
|
117
|
+
| `connection-failure` | Aborts the matched Playwright request with `connectionfailed`, or throws from the fetch adapter. |
|
|
118
|
+
| `invalid-json` | Returns status `200` with a deliberately malformed JSON body. |
|
|
119
|
+
|
|
120
|
+
Faults are bounded by `count` (default `1`, maximum `20`). The count is reserved synchronously, so concurrent matching requests cannot over-inject.
|
|
121
|
+
|
|
122
|
+
## Fetch-only tests
|
|
123
|
+
|
|
124
|
+
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`.
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
import { createFaultFetch } from 'recovery-probe/fetch';
|
|
128
|
+
|
|
129
|
+
const probe = createFaultFetch(fetch, {
|
|
130
|
+
url: 'http://127.0.0.1:3000/api/profile',
|
|
131
|
+
kind: 'connection-failure',
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
await exerciseApplication(probe.fetch);
|
|
135
|
+
probe.assertApplied();
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`exerciseApplication` represents your own test adapter or application controller. Calling `assertApplied()` is essential: it proves that every requested fault was consumed.
|
|
139
|
+
|
|
140
|
+
## JSON-configured runner
|
|
141
|
+
|
|
142
|
+
The CLI supports pages that automatically load GET data, expose a visible Retry button after failure, and show a ready element after recovery.
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"name": "Profile recovery",
|
|
147
|
+
"url": "http://127.0.0.1:3000/profile",
|
|
148
|
+
"requestPattern": "**/api/profile",
|
|
149
|
+
"readySelector": "[data-testid=profile-ready]",
|
|
150
|
+
"retrySelector": "[data-testid=profile-retry]",
|
|
151
|
+
"timeoutMs": 3000
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
npx recovery-probe --config recovery-probe.json --out artifacts/profile-recovery.json
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
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.
|
|
160
|
+
|
|
161
|
+
Exit codes:
|
|
162
|
+
|
|
163
|
+
- `0`: every configured check passed, or the controlled demo observed its expected broken-versus-fixed result.
|
|
164
|
+
- `1`: a recovery check failed, was inconclusive, or was skipped.
|
|
165
|
+
- `2`: invalid arguments, configuration, or environment setup.
|
|
166
|
+
|
|
167
|
+
## Result semantics
|
|
168
|
+
|
|
169
|
+
| Code | Meaning |
|
|
170
|
+
| --- | --- |
|
|
171
|
+
| `OK` | The configured assertion completed and the expected fault count was observed. |
|
|
172
|
+
| `RECOVERY_ASSERTION_FAILED` | The fault occurred, but the recovery assertion did not pass. |
|
|
173
|
+
| `FAULT_NOT_TRIGGERED` | The requested fault count was not observed. Check the route, method, cache, and service worker. |
|
|
174
|
+
| `BASELINE_FAILED` | The ordinary flow failed, so the runner could not make a useful fault comparison. |
|
|
175
|
+
| `INJECTION_ERROR` | Playwright could not apply or clean up the route reliably. |
|
|
176
|
+
|
|
177
|
+
A passing result proves the configured recovery behavior for that test. It is not a certification of overall application resilience.
|
|
178
|
+
|
|
179
|
+
## API
|
|
180
|
+
|
|
181
|
+
### `withFault(page, options, exercise)`
|
|
182
|
+
|
|
183
|
+
Installs one temporary Playwright route, runs `exercise`, verifies the requested fault count, and removes only that route handler.
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
interface FaultOptions {
|
|
187
|
+
match: string | RegExp;
|
|
188
|
+
kind: 'http-error' | 'connection-failure' | 'invalid-json';
|
|
189
|
+
status?: number;
|
|
190
|
+
count?: number;
|
|
191
|
+
method?: string;
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
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.
|
|
196
|
+
|
|
197
|
+
### `createFaultFetch(baseFetch, options)`
|
|
198
|
+
|
|
199
|
+
Creates an isolated fetch wrapper for one exact URL and method. It returns `{ fetch, summary, assertApplied }` and leaves the supplied fetch function unchanged.
|
|
200
|
+
|
|
201
|
+
### `probeRecovery(browser, config)`
|
|
202
|
+
|
|
203
|
+
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.
|
|
204
|
+
|
|
205
|
+
## Scope
|
|
206
|
+
|
|
207
|
+
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.
|
|
208
|
+
|
|
209
|
+
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.
|
|
210
|
+
|
|
211
|
+
The runner requires explicit selectors and endpoint matching. 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.
|
|
212
|
+
|
|
213
|
+
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.
|
|
214
|
+
|
|
215
|
+
## Development
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
npm ci
|
|
219
|
+
npm test # 9 fetch/core tests
|
|
220
|
+
npm run test:package # isolated tarball install + TypeScript + CLI checks
|
|
221
|
+
npx playwright install chromium
|
|
222
|
+
npm run test:browser # 7 real-browser integration tests
|
|
223
|
+
npm run test:repair # safety, authenticated portal, before/after pipeline
|
|
224
|
+
# After installing the optional Electron test runtime:
|
|
225
|
+
npm run test:repair:electron
|
|
226
|
+
npm run demo:browser
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
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).
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
[MIT](LICENSE) © 2026 Bojan Kovachki
|
package/SECURITY.md
ADDED
|
@@ -0,0 +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.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { mkdir, writeFile } from 'node:fs/promises';
|
|
3
|
+
import { runCoreDemo } from '../examples/core-demo.mjs';
|
|
4
|
+
const report = await runCoreDemo();
|
|
5
|
+
await mkdir('artifacts', { recursive: true });
|
|
6
|
+
await writeFile('artifacts/core-demo.json', JSON.stringify(report, null, 2) + '\n');
|
|
7
|
+
console.log(JSON.stringify(report, null, 2));
|
|
8
|
+
process.exitCode = report.expectedDemonstrationVerified ? 0 : 1;
|
package/bin/desktop.mjs
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { readFile, writeFile, mkdir } from 'node:fs/promises';
|
|
2
|
+
import { resolve, join } from 'node:path';
|
|
3
|
+
import { connectDesktop, desktopPages, selectDesktopPage, pageIdentity, discoverDesktop, checkDesktop, validateDesktopConfig } from '../src/desktop.mjs';
|
|
4
|
+
import { writeDesktopReport } from '../src/desktop-report.mjs';
|
|
5
|
+
|
|
6
|
+
export async function desktopMain(args) {
|
|
7
|
+
if (!args.length || args.includes('--help')) {
|
|
8
|
+
console.log(`Recovery Probe desktop preview
|
|
9
|
+
|
|
10
|
+
Attach to an Electron DEVELOPMENT renderer through its loopback debugging port.
|
|
11
|
+
|
|
12
|
+
recovery-probe desktop --list [--cdp http://127.0.0.1:9222]
|
|
13
|
+
recovery-probe desktop --discover --page 0 [--duration 5000] [--out .recovery-probe/discovery]
|
|
14
|
+
recovery-probe desktop --config scenario.json [--out .recovery-probe/run] [--screenshots]
|
|
15
|
+
|
|
16
|
+
Discovery reloads the chosen window and lists successful renderer GET JSON endpoints.
|
|
17
|
+
Checks reload it once per baseline/fault, optionally click the configured Retry button,
|
|
18
|
+
and perform a final reload reset. The app stays open. Use a test account/environment.
|
|
19
|
+
The config selects one endpoint and a data-dependent readySelector; see docs/desktop.md.
|
|
20
|
+
Requests made by native SDKs/IPC and untouched app screens are outside this check.
|
|
21
|
+
Reports stay local. Screenshots are opt-in and may contain private on-screen content.`);
|
|
22
|
+
return;
|
|
23
|
+
}
|
|
24
|
+
const options = {};
|
|
25
|
+
const values = new Set(['--cdp', '--page', '--duration', '--out', '--config']);
|
|
26
|
+
for (let i = 0; i < args.length; i++) {
|
|
27
|
+
const arg = args[i];
|
|
28
|
+
const key = arg.slice(2);
|
|
29
|
+
if (['--list', '--discover', '--screenshots'].includes(arg)) options[key] = true;
|
|
30
|
+
else if (values.has(arg)) {
|
|
31
|
+
if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${arg} needs a value`);
|
|
32
|
+
options[key] = args[++i];
|
|
33
|
+
} else throw new Error(`Unknown desktop option: ${arg}`);
|
|
34
|
+
}
|
|
35
|
+
if ([options.list, options.discover, options.config].filter(Boolean).length !== 1) throw new Error('Choose one of --list, --discover, or --config');
|
|
36
|
+
if (options.page !== undefined) {
|
|
37
|
+
if (!/^\d+$/.test(options.page)) throw new Error('--page must be a non-negative integer');
|
|
38
|
+
options.page = Number(options.page);
|
|
39
|
+
}
|
|
40
|
+
if (options.duration !== undefined && (!/^\d+$/.test(options.duration) || Number(options.duration) < 200 || Number(options.duration) > 30000)) throw new Error('--duration must be 200–30000 ms');
|
|
41
|
+
let config = options.config ? JSON.parse(await readFile(options.config, 'utf8')) : {};
|
|
42
|
+
if (options.page !== undefined) config.page = options.page;
|
|
43
|
+
config.cdp = options.cdp ?? config.cdp ?? 'http://127.0.0.1:9222';
|
|
44
|
+
if (options.config) config = validateDesktopConfig(config);
|
|
45
|
+
const browser = await connectDesktop(config.cdp);
|
|
46
|
+
try {
|
|
47
|
+
if (options.list) {
|
|
48
|
+
const pages = desktopPages(browser);
|
|
49
|
+
if (!pages.length) throw new Error('No renderer pages found');
|
|
50
|
+
pages.forEach((page, index) => console.log(`${index} ${pageIdentity(page.url())}`));
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
const page = selectDesktopPage(browser, config);
|
|
54
|
+
const directory = resolve(options.out ?? `.recovery-probe/${new Date().toISOString().replace(/[:.]/g, '-')}`);
|
|
55
|
+
await mkdir(directory, { recursive: true, mode: 0o700 });
|
|
56
|
+
if (options.discover) {
|
|
57
|
+
const discovery = await discoverDesktop(page, { durationMs: Number(options.duration ?? 5000) });
|
|
58
|
+
await writeFile(join(directory, 'discovery.json'), JSON.stringify(discovery, null, 2) + '\n', { mode: 0o600 });
|
|
59
|
+
const template = { cdp: config.cdp, page: desktopPages(browser).indexOf(page), pageUrl: discovery.pageUrl, endpoint: discovery.endpoints.length === 1 ? discovery.endpoints[0].endpoint : '', readySelector: '', retrySelector: '', recovery: 'retry', timeoutMs: 5000 };
|
|
60
|
+
await writeFile(join(directory, 'scenario.json'), JSON.stringify(template, null, 2) + '\n', { mode: 0o600 });
|
|
61
|
+
discovery.endpoints.forEach((row, index) => console.log(`${index + 1}. GET ${row.endpoint} (${row.observed} response(s), query values omitted)`));
|
|
62
|
+
if (!discovery.endpoints.length) console.log('No matching renderer GET JSON responses observed. The screen may use cached data, native SDK/IPC requests, a service worker, or load after the discovery window. This is not a pass.');
|
|
63
|
+
console.log(`\nDiscovery: ${join(directory, 'discovery.json')}\nFill endpoint (if blank), readySelector and retrySelector in ${join(directory, 'scenario.json')}`);
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
console.log('Checking the current development renderer. It will reload between faults.');
|
|
67
|
+
const report = await checkDesktop(page, config, {
|
|
68
|
+
onFailure: options.screenshots ? async (target, row) => {
|
|
69
|
+
const filename = `${row.kind}.png`;
|
|
70
|
+
await target.screenshot({ path: join(directory, filename), timeout: 5000 });
|
|
71
|
+
row.screenshot = filename;
|
|
72
|
+
} : undefined,
|
|
73
|
+
});
|
|
74
|
+
await writeDesktopReport(directory, report, config);
|
|
75
|
+
for (const row of report.results) console.log(`${row.outcome.toUpperCase().padEnd(12)} ${row.kind}: ${row.code} (injected ${row.applied}, later successful responses ${row.successfulResponsesAfterFault})`);
|
|
76
|
+
console.log(`Final reload reset: ${report.finalReset}\nReport: ${join(directory, 'report.html')}\nReproduce: node ${join(directory, 'reproduce.mjs')}\nFix investigation: ${join(directory, 'fix-brief.md')}`);
|
|
77
|
+
process.exitCode = report.ok ? 0 : report.results.some(row => row.outcome === 'fail') ? 1 : 2;
|
|
78
|
+
} finally {
|
|
79
|
+
// Closing a CDP connection disconnects this client; it does not close the existing app.
|
|
80
|
+
await browser.close();
|
|
81
|
+
}
|
|
82
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { readFile, writeFile, mkdir } from 'node:fs/promises';
|
|
3
|
+
import { dirname } from 'node:path';
|
|
4
|
+
import { probeRecovery } from '../src/index.mjs';
|
|
5
|
+
import { startDemoServer } from '../examples/demo-server.mjs';
|
|
6
|
+
|
|
7
|
+
const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
|
|
8
|
+
|
|
9
|
+
function printHelp() {
|
|
10
|
+
console.log(`Recovery Probe ${version}
|
|
11
|
+
|
|
12
|
+
Usage:
|
|
13
|
+
recovery-probe --demo [--out report.json] [--json]
|
|
14
|
+
recovery-probe --config scenario.json [--out report.json] [--json]
|
|
15
|
+
recovery-probe desktop --help
|
|
16
|
+
recovery-probe web --help
|
|
17
|
+
recovery-probe repair --help
|
|
18
|
+
recovery-probe --version
|
|
19
|
+
|
|
20
|
+
Options:
|
|
21
|
+
--demo Run the included broken-versus-fixed browser demonstration.
|
|
22
|
+
--config <file> Check one JSON-configured recovery scenario.
|
|
23
|
+
--out <file> Save the full machine-readable report.
|
|
24
|
+
--json Print the full JSON report instead of a terminal summary.
|
|
25
|
+
--help Show this help.
|
|
26
|
+
|
|
27
|
+
Use only development or test targets you control.`);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function marker(outcome) {
|
|
31
|
+
if (outcome === 'pass') return 'PASS';
|
|
32
|
+
if (outcome === 'fail') return 'CAUGHT';
|
|
33
|
+
return outcome.toUpperCase();
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
function printSummary(report) {
|
|
37
|
+
console.log(`Recovery Probe ${report.version} — ${report.mode}\n`);
|
|
38
|
+
for (const app of report.apps) {
|
|
39
|
+
console.log(app.name);
|
|
40
|
+
for (const row of app.results) {
|
|
41
|
+
const injected = row.applied ? `, injected ${row.applied}` : '';
|
|
42
|
+
console.log(` ${marker(row.outcome).padEnd(12)} ${row.scenario} (${row.code}${injected})`);
|
|
43
|
+
}
|
|
44
|
+
console.log('');
|
|
45
|
+
}
|
|
46
|
+
if (report.mode === 'controlled demonstration') {
|
|
47
|
+
console.log(report.expectedDemonstrationVerified
|
|
48
|
+
? 'Demo verified: the happy path passes, the broken recovery is caught, and the fixed app recovers.'
|
|
49
|
+
: 'Demo failed: the expected broken-versus-fixed distinction was not observed.');
|
|
50
|
+
} else {
|
|
51
|
+
console.log(report.apps.every(app => app.ok) ? 'Recovery check passed.' : 'Recovery check did not pass.');
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
async function main() {
|
|
56
|
+
const args = process.argv.slice(2);
|
|
57
|
+
if (args[0] === 'web') {
|
|
58
|
+
const { webMain } = await import('./web.mjs');
|
|
59
|
+
return webMain(args.slice(1));
|
|
60
|
+
}
|
|
61
|
+
if (args[0] === 'repair') {
|
|
62
|
+
const { repairMain } = await import('./repair.mjs');
|
|
63
|
+
return repairMain(args.slice(1));
|
|
64
|
+
}
|
|
65
|
+
if (args[0] === 'desktop') {
|
|
66
|
+
const { desktopMain } = await import('./desktop.mjs');
|
|
67
|
+
return desktopMain(args.slice(1));
|
|
68
|
+
}
|
|
69
|
+
if (args.includes('--help') || !args.length) {
|
|
70
|
+
printHelp();
|
|
71
|
+
return;
|
|
72
|
+
}
|
|
73
|
+
if (args.length === 1 && args[0] === '--version') {
|
|
74
|
+
console.log(version);
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
let demo = false;
|
|
78
|
+
let json = false;
|
|
79
|
+
let configPath;
|
|
80
|
+
let output;
|
|
81
|
+
for (let i = 0; i < args.length; i++) {
|
|
82
|
+
const arg = args[i];
|
|
83
|
+
if (arg === '--demo') demo = true;
|
|
84
|
+
else if (arg === '--json') json = true;
|
|
85
|
+
else if (arg === '--config' || arg === '--out') {
|
|
86
|
+
const value = args[++i];
|
|
87
|
+
if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value`);
|
|
88
|
+
if (arg === '--config') configPath = value; else output = value;
|
|
89
|
+
} else throw new Error(`Unknown argument: ${arg}`);
|
|
90
|
+
}
|
|
91
|
+
if (demo === Boolean(configPath)) throw new Error('Choose exactly one of --demo or --config');
|
|
92
|
+
|
|
93
|
+
const config = configPath ? JSON.parse(await readFile(configPath, 'utf8')) : null;
|
|
94
|
+
const { chromium } = await import('playwright');
|
|
95
|
+
const browser = await chromium.launch({ headless: true });
|
|
96
|
+
let server;
|
|
97
|
+
let report;
|
|
98
|
+
try {
|
|
99
|
+
const apps = [];
|
|
100
|
+
if (demo) {
|
|
101
|
+
server = await startDemoServer();
|
|
102
|
+
for (const variant of ['broken', 'fixed']) {
|
|
103
|
+
apps.push(await probeRecovery(browser, {
|
|
104
|
+
name: `${variant} synthetic fixture`, url: `${server.url}/${variant}`,
|
|
105
|
+
requestPattern: '**/api/profile', readySelector: '#profile', retrySelector: '#retry', timeoutMs: 1200,
|
|
106
|
+
}));
|
|
107
|
+
}
|
|
108
|
+
} else apps.push(await probeRecovery(browser, config));
|
|
109
|
+
report = {
|
|
110
|
+
tool: 'Recovery Probe', version, generatedAt: new Date().toISOString(),
|
|
111
|
+
environment: { node: process.version, platform: process.platform, chromium: browser.version() },
|
|
112
|
+
mode: demo ? 'controlled demonstration' : 'configured recovery check', apps,
|
|
113
|
+
};
|
|
114
|
+
if (demo) {
|
|
115
|
+
report.expectedDemonstrationVerified = apps[0].results[0].outcome === 'pass'
|
|
116
|
+
&& apps[0].results.slice(1).every(row => row.outcome === 'fail' && row.applied === 1)
|
|
117
|
+
&& apps[1].ok;
|
|
118
|
+
process.exitCode = report.expectedDemonstrationVerified ? 0 : 1;
|
|
119
|
+
} else process.exitCode = apps.every(app => app.ok) ? 0 : 1;
|
|
120
|
+
} finally {
|
|
121
|
+
await browser.close();
|
|
122
|
+
if (server) await server.close();
|
|
123
|
+
}
|
|
124
|
+
if (json) console.log(JSON.stringify(report, null, 2));
|
|
125
|
+
else printSummary(report);
|
|
126
|
+
if (output) {
|
|
127
|
+
await mkdir(dirname(output), { recursive: true });
|
|
128
|
+
await writeFile(output, JSON.stringify(report, null, 2) + '\n');
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
main().catch(error => {
|
|
133
|
+
console.error(`Recovery Probe: ${error.message}`);
|
|
134
|
+
process.exitCode = 2;
|
|
135
|
+
});
|
package/bin/repair.mjs
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import { resolve, dirname } from 'node:path';
|
|
3
|
+
import { prepareRepair, generateRepair, verifyRepair } from '../src/repair.mjs';
|
|
4
|
+
|
|
5
|
+
export async function repairMain(args) {
|
|
6
|
+
if (!args.length || args.includes('--help')) {
|
|
7
|
+
console.log(`Recovery Probe repair preview — local development only
|
|
8
|
+
recovery-probe repair --config repair.json --out NEW_DIRECTORY --allow-execution
|
|
9
|
+
recovery-probe repair --generate RUN_DIRECTORY --allow-source-upload
|
|
10
|
+
recovery-probe repair --verify RUN_DIRECTORY --allow-execution
|
|
11
|
+
|
|
12
|
+
Optional single run: --config ... --out ... --allow-execution --allow-source-upload --auto-verify
|
|
13
|
+
|
|
14
|
+
Config: target (web/desktop), repo, sourceFiles, scenario, launch, setup, tests, provider.model.
|
|
15
|
+
Paths resolve relative to the config. Output must be outside your clean source repository.
|
|
16
|
+
Step 1 clones the committed source locally, starts that copy and reproduces a failure.
|
|
17
|
+
Step 2 sends only repair-request.json to OpenAI, using your local OPENAI_API_KEY.
|
|
18
|
+
Step 3 applies proposal.json only to the copy and reruns the same scenario and your tests.
|
|
19
|
+
Review proposal.json before verification. --auto-verify explicitly executes unreviewed AI code.
|
|
20
|
+
A checkout is NOT a security sandbox: use a disposable dev container/VM and test accounts.
|
|
21
|
+
There is no implicit source upload, production deployment, commit, merge or original-repo edit.
|
|
22
|
+
See docs/repair.md for complete web and Electron examples and Windows commands.`);
|
|
23
|
+
return;
|
|
24
|
+
}
|
|
25
|
+
const options = {};
|
|
26
|
+
for (let i = 0; i < args.length; i++) {
|
|
27
|
+
const arg = args[i];
|
|
28
|
+
if (['--allow-execution', '--allow-source-upload', '--auto-verify'].includes(arg)) options[arg.slice(2)] = true;
|
|
29
|
+
else if (['--config', '--out', '--generate', '--verify'].includes(arg)) {
|
|
30
|
+
if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${arg} needs a value`);
|
|
31
|
+
options[arg.slice(2)] = args[++i];
|
|
32
|
+
} else throw new Error(`Unknown repair option: ${arg}`);
|
|
33
|
+
}
|
|
34
|
+
if ([options.config, options.generate, options.verify].filter(Boolean).length !== 1) throw new Error('Choose --config, --generate, or --verify');
|
|
35
|
+
if (options['auto-verify'] && (!options.config || !options['allow-execution'] || !options['allow-source-upload'])) throw new Error('--auto-verify requires --config, --allow-execution and --allow-source-upload');
|
|
36
|
+
let directory = resolve(options.generate ?? options.verify ?? options.out ?? `../recovery-probe-run-${Date.now()}`);
|
|
37
|
+
if (options.verify) {
|
|
38
|
+
const result = await verifyRepair(directory, { allowExecution: options['allow-execution'] });
|
|
39
|
+
console.log(JSON.stringify(result, null, 2));
|
|
40
|
+
console.log(`Review ${directory}/candidate.patch. Your original repository was not modified.`);
|
|
41
|
+
process.exitCode = result.status === 'verified-candidate' ? 0 : 1;
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
44
|
+
if (options.config) {
|
|
45
|
+
const configPath = resolve(options.config);
|
|
46
|
+
const config = JSON.parse(await readFile(configPath, 'utf8'));
|
|
47
|
+
config.repo = resolve(dirname(configPath), config.repo ?? '.');
|
|
48
|
+
if (config.scenario?.storageState) config.scenario.storageState = resolve(dirname(configPath), config.scenario.storageState);
|
|
49
|
+
console.log('Reproducing in a separate checkout; running only the commands you configured.');
|
|
50
|
+
const prepared = await prepareRepair(config, directory, { allowExecution: options['allow-execution'] });
|
|
51
|
+
if (!prepared.reproduced) {
|
|
52
|
+
console.log(`No repairable failure reproduced. Inspect ${directory}/before.json; no model called.`);
|
|
53
|
+
process.exitCode = prepared.before.ok ? 0 : 2;
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
console.log(`Failure reproduced. Inspect ${directory}/repair-request.json before authorizing source upload.`);
|
|
57
|
+
if (!options['allow-source-upload']) return;
|
|
58
|
+
}
|
|
59
|
+
const proposal = await generateRepair(directory, { allowSourceUpload: options['allow-source-upload'] });
|
|
60
|
+
console.log(`Proposal: ${directory}/proposal.json (${proposal.edits.length} edit(s)). No source changes applied yet.`);
|
|
61
|
+
if (options['auto-verify'] && proposal.edits.length) {
|
|
62
|
+
const result = await verifyRepair(directory, { allowExecution: true });
|
|
63
|
+
console.log(JSON.stringify(result, null, 2));
|
|
64
|
+
process.exitCode = result.status === 'verified-candidate' ? 0 : 1;
|
|
65
|
+
} else console.log('Review the proposal, then run repair --verify RUN_DIRECTORY --allow-execution.');
|
|
66
|
+
}
|