recovery-probe 0.4.0 → 0.5.0-preview.16
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 +93 -0
- package/CONTRIBUTING.md +1 -1
- package/README.md +31 -1
- package/bin/android.mjs +110 -0
- package/bin/attach.mjs +15 -11
- package/bin/compare.mjs +98 -0
- package/bin/desktop.mjs +2 -2
- package/bin/ipc.mjs +36 -10
- package/bin/mcp.mjs +35 -0
- package/bin/net.mjs +149 -0
- package/bin/observe.mjs +96 -18
- package/bin/recovery-probe.mjs +32 -1
- package/bin/refresh.mjs +9 -7
- package/bin/repair.mjs +1 -1
- package/bin/start.mjs +2 -1
- package/bin/suspects.mjs +71 -0
- package/bin/until-stopped.mjs +15 -0
- package/bin/watch.mjs +163 -0
- package/bin/web.mjs +2 -2
- package/dist/action-report.d.mts +2 -0
- package/dist/action-report.mjs +24 -0
- package/dist/android.d.mts +35 -0
- package/dist/android.mjs +98 -0
- package/dist/cdp-bridge.d.mts +31 -0
- package/dist/cdp-bridge.mjs +237 -0
- package/dist/compare.d.mts +92 -0
- package/dist/compare.mjs +376 -0
- package/dist/desktop-report.d.mts +5 -0
- package/dist/desktop-report.mjs +52 -0
- package/dist/discovery-control.d.mts +16 -0
- package/dist/discovery-control.mjs +39 -0
- package/dist/discovery-report.d.mts +40 -0
- package/dist/discovery-report.mjs +31 -0
- package/dist/fetch-fault.d.mts +21 -0
- package/dist/fetch-fault.mjs +84 -0
- package/dist/file-evidence.d.mts +49 -0
- package/dist/file-evidence.mjs +112 -0
- package/dist/http-observer.d.mts +45 -0
- package/dist/http-observer.mjs +186 -0
- package/dist/ipc-action.d.mts +74 -0
- package/dist/ipc-action.mjs +314 -0
- package/dist/ipc-check.d.mts +45 -0
- package/dist/ipc-check.mjs +242 -0
- package/dist/ipc-control.d.mts +19 -0
- package/dist/ipc-control.mjs +64 -0
- package/dist/ipc-discover.d.mts +119 -0
- package/dist/ipc-discover.mjs +371 -0
- package/dist/ipc-inspector.d.mts +19 -0
- package/dist/ipc-inspector.mjs +144 -0
- package/dist/ipc-observation.d.mts +111 -0
- package/dist/ipc-observation.mjs +302 -0
- package/dist/ipc-probe.cjs +393 -0
- package/dist/ipc-probe.d.cts +122 -0
- package/dist/mcp-server.d.mts +30 -0
- package/dist/mcp-server.mjs +131 -0
- package/dist/mcp-tools.d.mts +5 -0
- package/dist/mcp-tools.mjs +468 -0
- package/dist/net-fault.d.mts +80 -0
- package/dist/net-fault.mjs +307 -0
- package/dist/observation-kit.d.mts +35 -0
- package/dist/observation-kit.mjs +160 -0
- package/dist/observation-report.d.mts +309 -0
- package/dist/observation-report.mjs +343 -0
- package/dist/observe-network.d.mts +13 -0
- package/dist/observe-network.mjs +57 -0
- package/dist/observe-steps.d.mts +58 -0
- package/dist/observe-steps.mjs +191 -0
- package/dist/observe.d.mts +104 -0
- package/dist/observe.mjs +892 -0
- package/dist/refresh-adapters.d.mts +40 -0
- package/dist/refresh-adapters.mjs +74 -0
- package/dist/report-template.d.mts +7 -0
- package/dist/report-template.mjs +23 -0
- package/dist/report-templates/action.html +51 -0
- package/dist/suspects.d.mts +45 -0
- package/dist/suspects.mjs +395 -0
- package/dist/visibility.d.mts +25 -0
- package/dist/visibility.mjs +127 -0
- package/dist/watch.d.mts +99 -0
- package/dist/watch.mjs +315 -0
- package/docs/android.md +37 -0
- package/docs/api.md +8 -0
- package/docs/compare.md +105 -0
- package/docs/ipc.md +39 -0
- package/docs/mcp.md +66 -0
- package/docs/net.md +83 -0
- package/docs/observe.md +32 -1
- package/docs/suspects.md +100 -0
- package/docs/watch.md +59 -0
- package/examples/core-demo.mjs +1 -1
- package/package.json +63 -41
- package/src/desktop-report.mjs +0 -67
- package/src/discovery-control.mjs +0 -45
- package/src/discovery-report.mjs +0 -47
- package/src/fetch-fault.d.mts +0 -22
- package/src/fetch-fault.mjs +0 -96
- package/src/http-observer.mjs +0 -197
- package/src/ipc-check.mjs +0 -279
- package/src/ipc-control.mjs +0 -32
- package/src/ipc-discover.mjs +0 -413
- package/src/ipc-inspector.d.mts +0 -34
- package/src/ipc-inspector.mjs +0 -166
- package/src/ipc-observation.mjs +0 -332
- package/src/ipc-probe.cjs +0 -399
- package/src/ipc-probe.d.cts +0 -107
- package/src/observation-kit.mjs +0 -176
- package/src/observation-report.mjs +0 -385
- package/src/observe-steps.mjs +0 -164
- package/src/observe.mjs +0 -1025
- package/src/refresh-adapters.mjs +0 -68
- package/src/report-template.mjs +0 -33
- package/src/visibility.mjs +0 -130
- /package/{src → dist}/desktop.d.mts +0 -0
- /package/{src → dist}/desktop.mjs +0 -0
- /package/{src → dist}/guided-start.mjs +0 -0
- /package/{src → dist}/http-discover.mjs +0 -0
- /package/{src → dist}/index.d.ts +0 -0
- /package/{src → dist}/index.mjs +0 -0
- /package/{src → dist}/pick-marker.mjs +0 -0
- /package/{src → dist}/refresh.mjs +0 -0
- /package/{src → dist}/repair-process.mjs +0 -0
- /package/{src → dist}/repair-provider.mjs +0 -0
- /package/{src → dist}/repair.mjs +0 -0
- /package/{src → dist}/report-templates/desktop.html +0 -0
- /package/{src → dist}/report-templates/discovery.html +0 -0
- /package/{src → dist}/report-templates/ipc.html +0 -0
- /package/{src → dist}/report-templates/observation.html +0 -0
- /package/{src → dist}/report-templates/refresh.html +0 -0
- /package/{src → dist}/web.d.mts +0 -0
- /package/{src → dist}/web.mjs +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,99 @@ 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.5.0-preview.16 (2026-10-20)
|
|
8
|
+
|
|
9
|
+
- **`recovery-probe watch [PATH...] [-- CHECK]`** watches source files while you work. After each save it scans the changed files for suspects and reruns the check against the running development app. It compares the run with the first one and the one before, by the rules of `compare`.
|
|
10
|
+
- The check runs once at the start for the starting point. `--settle` waits for the dev server to reload, and each run gets its own folder and log.
|
|
11
|
+
- `summary.json` and `summary.md` (the pull request block for the first run against the latest) are rewritten after every run.
|
|
12
|
+
- Without a check, the watch only scans for suspects. See docs/watch.md.
|
|
13
|
+
|
|
14
|
+
## 0.5.0-preview.15 (2026-10-20)
|
|
15
|
+
|
|
16
|
+
- **`recovery-probe compare`** compares reports of the same check from before and after a change and says what happened to each problem: gone, new, still there, or not checked to the end. A problem counts as gone only when a complete run after the change checked it, so a run that stopped early never reads as a fix.
|
|
17
|
+
- Each side takes one or more reports, report folders or folders of runs, so repeated runs can be compared.
|
|
18
|
+
- It returns a verdict: `IMPROVED`, `PARTLY_IMPROVED`, `REGRESSED`, `MIXED`, `UNCHANGED`, `INCONCLUSIVE` or `NOT_COMPARABLE`. It exits 1 only for a new suspected defect.
|
|
19
|
+
- `--markdown` prints a block for the pull request. See docs/compare.md.
|
|
20
|
+
- The MCP server adds `compare_reports`, and tells agents to compare reports before they say a change fixed something.
|
|
21
|
+
|
|
22
|
+
## 0.5.0-preview.14 (2026-10-20)
|
|
23
|
+
|
|
24
|
+
- **`recovery-probe suspects`** (experimental) reads JavaScript and TypeScript sources for error handling that loses data:
|
|
25
|
+
- `UNKNOWN_AS_EMPTY`: a failed or unexpected read becomes an empty collection;
|
|
26
|
+
- `FAILURE_ONLY_LOGGED`: a read stores its data when it succeeds, but its failure is only logged.
|
|
27
|
+
- Each suspect names the read to fail and the check that proves or dismisses it. `--changed-since main` scans only what a branch changed, and `// recovery-probe-ignore` marks a reviewed line. It exits 2 when there are suspects to review. See docs/suspects.md.
|
|
28
|
+
- The MCP server adds `find_suspects`.
|
|
29
|
+
- TypeScript is a new optional peer dependency, needed only by the scanner.
|
|
30
|
+
|
|
31
|
+
## 0.5.0-preview.13 (2026-10-20)
|
|
32
|
+
|
|
33
|
+
- **`recovery-probe android`** (experimental) makes an Android app's WebView, or Chrome, inspectable like a desktop debugging endpoint. It finds the DevTools socket over adb, forwards a local port, checks that DevTools answers and removes the forward on exit. The printed URL works with `desktop --cdp` and as `cdp` in configs. It is served through a small bridge that hides blank WebViews, which Android pauses and which never answer, so a client does not wait on them. Checked on a Quest 2. See docs/android.md.
|
|
34
|
+
|
|
35
|
+
## 0.5.0-preview.12 (2026-10-20)
|
|
36
|
+
|
|
37
|
+
- **`recovery-probe mcp`** serves Recovery Probe to AI coding agents as MCP tools over stdio:
|
|
38
|
+
- `find_page_reads` and `check_read_recovery` for a page's reads;
|
|
39
|
+
- four tools that run the network fault proxy;
|
|
40
|
+
- `run_recovery_probe` for observe, ipc, refresh, desktop and web.
|
|
41
|
+
- When an agent connects, the server tells it how to report results: a pass covers only what was checked, and inconclusive codes are not passes.
|
|
42
|
+
- A caught fault returns the report folder with `fix-brief.md` and `reproduce.mjs`.
|
|
43
|
+
- No new dependencies. See docs/mcp.md.
|
|
44
|
+
- The package description now says the checks can run from an AI coding agent.
|
|
45
|
+
|
|
46
|
+
## 0.5.0-preview.11 (2026-10-20)
|
|
47
|
+
|
|
48
|
+
- **`observe --files DIR`** compares the files under a directory at each interval and reports `LOCAL_FILES_REMOVED` when an interval lost files, with counts and bytes in the report and the paths in a private `files.json`. It catches a failed read that made the app delete installed content, which the screen alone does not show. See docs/observe.md.
|
|
49
|
+
|
|
50
|
+
## 0.5.0-preview.10 (2026-10-20)
|
|
51
|
+
|
|
52
|
+
- **Network steps** for `observe --steps`: with `--network URL`, a step can take hosts away from the app's own HTTPS connections through a running `recovery-probe net`, and `"restore"` brings them back. The capture always removes the faults at the end. The report records what each step faulted, adds `NETWORK_FAULT_NOT_TRIGGERED` or `NETWORK_FAULTS_NOT_RESTORED` coverage gaps, and labels the mode `observation with network faults`. See docs/observe.md.
|
|
53
|
+
- `recovery-probe net` runs without `--rules` and answers a loopback control; `recovery-probe/net` adds `connectNetworkFaults` and the `control` option.
|
|
54
|
+
|
|
55
|
+
## 0.5.0-preview.9 (2026-10-20)
|
|
56
|
+
|
|
57
|
+
- **`recovery-probe net`** fails an app's own HTTPS connections, for requests made outside the page by an SDK, a main process or a command-line tool. It runs a loopback proxy for the app's `HTTPS_PROXY` and refuses, resets, stalls or delays connections to the hosts you name, in time windows counted from the app's first connection. It can close open connections so clients have to reconnect. It sees only hosts and ports: HTTPS stays end to end. See docs/net.md.
|
|
58
|
+
- `recovery-probe/net` exports the same proxy as `startNetworkFaultProxy`.
|
|
59
|
+
|
|
60
|
+
## 0.5.0-preview.8 (2026-10-16)
|
|
61
|
+
|
|
62
|
+
- **`ipc --action`** checks what the user sees after an action that writes. It runs scripted setup steps, clicks the action while the hook answers its write channel, and compares a simulated success, a simulated failure and a double-click. It reports `SILENT_FAILURE`, `FALSE_SUCCESS`, `UNCLEAR_FEEDBACK`, `UNCAUGHT_ERROR` and `DUPLICATE_SUBMIT`. Nothing is written. See docs/ipc.md.
|
|
63
|
+
- Steps gain `fill` and `press`, also available to `observe --steps`. Typed values are never written to reports.
|
|
64
|
+
- The IPC hook can delay injected results with `delayMs` to simulate request time; `identify` reports this as `capabilities.faultDelay`.
|
|
65
|
+
- Discovery waits for the app's pending calls before each run, so its cleanup no longer fails when an app retry is still in flight.
|
|
66
|
+
|
|
67
|
+
## 0.5.0-preview.7 (2026-10-16)
|
|
68
|
+
|
|
69
|
+
- The IPC check and IPC discovery (`recovery-probe ipc` and `ipc --discover`) are written in TypeScript. Their reports are unchanged.
|
|
70
|
+
|
|
71
|
+
## 0.5.0-preview.6 (2026-10-16)
|
|
72
|
+
|
|
73
|
+
- The IPC development hook (`recovery-probe/ipc`) is written in TypeScript and still ships as the CommonJS file `dist/ipc-probe.cjs`. Its declarations are generated from the source and match the previous ones; `ProbeWebContents` gains the optional `getOwnerBrowserWindow` that the window controls use.
|
|
74
|
+
|
|
75
|
+
## 0.5.0-preview.5 (2026-10-16)
|
|
76
|
+
|
|
77
|
+
- The IPC control modules and `recovery-probe/ipc-inspector` are written in TypeScript. The inspector's declarations are now generated from its source and match the previous ones.
|
|
78
|
+
|
|
79
|
+
## 0.5.0-preview.4 (2026-10-16)
|
|
80
|
+
|
|
81
|
+
- `observe` is written in TypeScript, and the observation report has a complete schema type. Captures and reports are unchanged.
|
|
82
|
+
|
|
83
|
+
## 0.5.0-preview.3 (2026-10-16)
|
|
84
|
+
|
|
85
|
+
- The observation helpers are written in TypeScript: the in-page observation kit, scripted steps, the region reader and the HTTP observer. Their results are unchanged.
|
|
86
|
+
|
|
87
|
+
## 0.5.0-preview.2 (2026-10-16)
|
|
88
|
+
|
|
89
|
+
- The report modules are written in TypeScript: the HTML template renderer and the desktop, discovery and observation reports. The reports they write are byte-identical to before.
|
|
90
|
+
|
|
91
|
+
## 0.5.0-preview.1 (2026-10-16)
|
|
92
|
+
|
|
93
|
+
The first step of moving the package to TypeScript.
|
|
94
|
+
|
|
95
|
+
- The package is compiled into `dist/` and published from there. Package exports are unchanged, but `require.resolve('recovery-probe/ipc')` now returns a path ending in `dist/ipc-probe.cjs`. If you stored the old `src/ipc-probe.cjs` path in `RECOVERY_PROBE_IPC_MODULE`, run the command again after upgrading.
|
|
96
|
+
- `createFaultFetch` is written in TypeScript with strict checks, and its declarations are generated from the source. Its return type is exported as `FaultFetch`.
|
|
97
|
+
- TypeScript files are linted with typescript-eslint, so TypeScript is pinned to 6.0, the newest version typescript-eslint supports.
|
|
98
|
+
- A source checkout builds `dist/` during `npm ci`; test, demo and type-check scripts build first.
|
|
99
|
+
|
|
7
100
|
## 0.4.0 (2026-10-16)
|
|
8
101
|
|
|
9
102
|
The first stable release since 0.3.0. It contains 0.4.0-preview.1 to preview.5; their entries below have the details.
|
package/CONTRIBUTING.md
CHANGED
|
@@ -27,7 +27,7 @@ npm run test:repair:electron
|
|
|
27
27
|
|
|
28
28
|
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.
|
|
29
29
|
|
|
30
|
-
Code and JSON are formatted with Prettier (`npm run format`) and linted with ESLint (`npm run lint`); CI fails on either. Functions passed to `page.evaluate` run in the browser: keep them self-contained, and list new in-page modules in `eslint.config.mjs` so they get browser globals. TypeScript checks the JavaScript
|
|
30
|
+
Code and JSON are formatted with Prettier (`npm run format`) and linted with ESLint (`npm run lint`); CI fails on either. Functions passed to `page.evaluate` run in the browser: keep them self-contained, and list new in-page modules in `eslint.config.mjs` so they get browser globals. The package is moving from JavaScript to TypeScript, one module at a time; write new modules as `.mts` (or `.cts` for CommonJS). `npm run build` compiles them into `dist` with strict checks and generated declarations, and copies the remaining JavaScript, hand-written declarations and report templates unchanged. `npm ci` builds once, and every script that runs code builds first, so tests never use a stale `dist`. `npm run typecheck` also checks the JavaScript in `src`, `bin` and `examples` with strict mode off; add JSDoc types where inference is not enough. TypeScript is pinned to 6.0 because typescript-eslint, which lints the TypeScript files, does not support 7 yet. Markdown, HTML fixtures, report templates and workflow files are left as written. Report markup lives in `src/report-templates`: `{{slot}}` takes text and escapes it, `{{{slot}}}` takes markup built with `escapeHtml`. `.gitattributes` keeps LF line endings on every platform so local checks match CI. The repository-wide reformat is listed in `.git-blame-ignore-revs`; run `git config blame.ignoreRevsFile .git-blame-ignore-revs` to skip it in local blame.
|
|
31
31
|
|
|
32
32
|
## Install an unpublished source preview
|
|
33
33
|
|
package/README.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
Apps can show the wrong data without any error: a list that disappears after one failed read, a cached screen that never picks up a change, or a row whose state lags behind data the app already received. Recovery Probe reproduces these cases on demand. It injects bounded faults into data reads and compares the screen with a healthy run, or it watches reads and the screen without any fault. Each run writes a local report that separates what it measured from what it suspects.
|
|
6
6
|
|
|
7
|
+
Use it while you build, not only after. An AI coding agent can call it [over MCP](#use-it-from-an-ai-coding-agent) to see what the screen does when a read fails before it claims the code handles that. `recovery-probe suspects` reads the code a branch changed for error handling that turns a failed read into "no data", and names the read to fail to prove it. `recovery-probe compare` turns the same check, run before and after a change, into evidence for the pull request, and `recovery-probe watch` reruns the check and the scan on every save.
|
|
8
|
+
|
|
7
9
|
Installing the package does not add recovery behavior to your application.
|
|
8
10
|
|
|
9
11
|
[](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
|
|
@@ -32,6 +34,14 @@ npx recovery-probe --demo
|
|
|
32
34
|
| Set up a first recovery check interactively | `recovery-probe start web URL` or `start desktop` | [Guided start](docs/start.md) |
|
|
33
35
|
| Discover and test the reads behind a screen in a browser or Electron window | `recovery-probe desktop --cdp URL` | [Attachment and HTTP discovery](docs/desktop.md) |
|
|
34
36
|
| Compare an Electron screen under IPC faults | `recovery-probe ipc --discover --config FILE` | [IPC setup and discovery](docs/ipc.md) |
|
|
37
|
+
| Check what users see when a save or send fails in Electron | `recovery-probe ipc --action --config FILE` | [IPC action check](docs/ipc.md#action-check-050-preview8) |
|
|
38
|
+
| Fail an SDK's or main process's own HTTPS connections | `recovery-probe net --rules FILE`, or network steps in `observe --network URL` | [Network faults](docs/net.md) |
|
|
39
|
+
| Let an AI coding agent check what the screen does when a read fails | `recovery-probe mcp` | [AI coding agents (MCP)](docs/mcp.md) |
|
|
40
|
+
| Find error handling that turns a failed read into "no data", before running anything | `recovery-probe suspects --changed-since main` | [Suspect scanner](docs/suspects.md) |
|
|
41
|
+
| Show in a pull request that a change fixed what a check found | `recovery-probe compare --before DIR --after DIR --markdown` | [Before and after](docs/compare.md) |
|
|
42
|
+
| See after every save whether an edit fixed or broke what a check found | `recovery-probe watch src -- CHECK` | [Watch mode](docs/watch.md) |
|
|
43
|
+
| See whether a failure made the app delete local content | `recovery-probe observe --config FILE --files DIR` | [Local files](docs/observe.md#local-files-050-preview11) |
|
|
44
|
+
| Inspect an Android app's WebView (experimental) | `recovery-probe android --package NAME` | [Android WebViews](docs/android.md) |
|
|
35
45
|
| Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
|
|
36
46
|
| Watch cached content and row states after user actions, without faults | `recovery-probe observe --config FILE [--steps FILE]` | [Observation](docs/observe.md) |
|
|
37
47
|
| Run a repeatable recovery check in CI | `npm run test:ci-example` (source checkout) | [CI example](docs/ci.md) |
|
|
@@ -46,8 +56,28 @@ npx recovery-probe --demo
|
|
|
46
56
|
- **Electron apps that read over HTTP** in the renderer: attach through a loopback debugging endpoint.
|
|
47
57
|
- **Electron apps that read over IPC**: add a development-only hook to the main process.
|
|
48
58
|
- **JavaScript code that takes a fetch function**: use `recovery-probe/fetch`, without Playwright.
|
|
59
|
+
- **Native HTTPS clients that use `HTTPS_PROXY`**, such as an SDK in the main process: fail whole connections per host with `recovery-probe net`.
|
|
60
|
+
- **Android WebViews** with WebView debugging enabled (experimental): `recovery-probe android` makes them inspectable like a desktop page.
|
|
61
|
+
|
|
62
|
+
Desktop support means Electron, not arbitrary native applications. IPC faults do not exercise native networking, HTTP status handling or token refresh. Network faults reach native networking, but only whole connections: they cannot return an HTTP status inside HTTPS. An unsupported data path is inconclusive, never a successful recovery check.
|
|
63
|
+
|
|
64
|
+
## Use it from an AI coding agent
|
|
65
|
+
|
|
66
|
+
`recovery-probe mcp` serves the checks as MCP tools, so an agent can verify its own error handling instead of assuming it:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
claude mcp add recovery-probe -- npx recovery-probe mcp
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The agent can then:
|
|
73
|
+
- list the reads behind a page;
|
|
74
|
+
- fail one of them and see whether the screen recovers;
|
|
75
|
+
- run a network fault proxy for an SDK or a main process;
|
|
76
|
+
- find error handling in the changed code that can lose data;
|
|
77
|
+
- compare the same check before and after its change;
|
|
78
|
+
- run the other commands.
|
|
49
79
|
|
|
50
|
-
|
|
80
|
+
A caught fault comes with a fix brief and a script to reproduce it. The server tells the agent to report outcomes as they are: a pass covers only what was checked, and an inconclusive run is never a pass. See [AI coding agents (MCP)](docs/mcp.md).
|
|
51
81
|
|
|
52
82
|
## Add a recovery check to a Playwright test
|
|
53
83
|
|
package/bin/android.mjs
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import {
|
|
2
|
+
adbRunner,
|
|
3
|
+
androidDevices,
|
|
4
|
+
androidDevtoolsTargets,
|
|
5
|
+
forwardAndroidDevtools,
|
|
6
|
+
} from '../dist/android.mjs'
|
|
7
|
+
import { startCdpBridge } from '../dist/cdp-bridge.mjs'
|
|
8
|
+
import { untilStopped } from './until-stopped.mjs'
|
|
9
|
+
|
|
10
|
+
const USAGE =
|
|
11
|
+
'recovery-probe android [--list] [--serial SERIAL] [--package NAME] [--port N] [--duration MS] [--adb PATH]'
|
|
12
|
+
|
|
13
|
+
const HELP = `${USAGE}
|
|
14
|
+
|
|
15
|
+
Makes an Android WebView or Chrome inspectable like a desktop debugging endpoint.
|
|
16
|
+
It finds the app's DevTools socket over adb, forwards a local port to it and keeps
|
|
17
|
+
the forward until Ctrl+C or --duration. Use the printed URL with desktop --cdp, or as
|
|
18
|
+
"cdp" in an observe or desktop config. The app must enable WebView debugging, and the
|
|
19
|
+
device needs USB debugging. --list shows what can be inspected. See docs/android.md.`
|
|
20
|
+
|
|
21
|
+
function parseArgs(args) {
|
|
22
|
+
const options = {}
|
|
23
|
+
for (let i = 0; i < args.length; i++) {
|
|
24
|
+
const arg = args[i]
|
|
25
|
+
const value = args[i + 1]
|
|
26
|
+
if (arg === '--list') options.list = true
|
|
27
|
+
else if (
|
|
28
|
+
['--serial', '--package', '--port', '--duration', '--adb'].includes(
|
|
29
|
+
arg,
|
|
30
|
+
) &&
|
|
31
|
+
value &&
|
|
32
|
+
!value.startsWith('--')
|
|
33
|
+
) {
|
|
34
|
+
options[arg.slice(2)] = value
|
|
35
|
+
i++
|
|
36
|
+
} else throw Error(`Use ${USAGE}`)
|
|
37
|
+
}
|
|
38
|
+
for (const key of ['port', 'duration'])
|
|
39
|
+
if (options[key] !== undefined) {
|
|
40
|
+
options[key] = Number(options[key])
|
|
41
|
+
if (!Number.isInteger(options[key]) || options[key] < 0)
|
|
42
|
+
throw Error(`--${key} must be a whole number`)
|
|
43
|
+
}
|
|
44
|
+
return options
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const describe = (target) =>
|
|
48
|
+
`${target.kind.padEnd(7)} ${target.package ?? 'unknown app'}${target.pid ? ` (pid ${target.pid})` : ''}`
|
|
49
|
+
|
|
50
|
+
export async function androidMain(args) {
|
|
51
|
+
if (args.includes('--help')) {
|
|
52
|
+
console.log(HELP)
|
|
53
|
+
return
|
|
54
|
+
}
|
|
55
|
+
const options = parseArgs(args)
|
|
56
|
+
let serial = options.serial
|
|
57
|
+
if (!serial) {
|
|
58
|
+
const devices = await androidDevices(adbRunner({ adb: options.adb }))
|
|
59
|
+
if (devices.length !== 1)
|
|
60
|
+
throw Error(
|
|
61
|
+
devices.length
|
|
62
|
+
? `Several devices are connected (${devices.join(', ')}); choose one with --serial`
|
|
63
|
+
: 'No device is connected over adb; enable USB debugging and check adb devices',
|
|
64
|
+
)
|
|
65
|
+
serial = devices[0]
|
|
66
|
+
}
|
|
67
|
+
const run = adbRunner({ adb: options.adb, serial })
|
|
68
|
+
const targets = await androidDevtoolsTargets(run)
|
|
69
|
+
|
|
70
|
+
if (options.list) {
|
|
71
|
+
console.log(
|
|
72
|
+
targets.length
|
|
73
|
+
? targets.map(describe).join('\n')
|
|
74
|
+
: 'Nothing to inspect: no app with WebView debugging enabled is running.',
|
|
75
|
+
)
|
|
76
|
+
return
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const matching = options.package
|
|
80
|
+
? targets.filter((target) => target.package === options.package)
|
|
81
|
+
: targets
|
|
82
|
+
if (matching.length !== 1)
|
|
83
|
+
throw Error(
|
|
84
|
+
matching.length
|
|
85
|
+
? `Several targets can be inspected; choose one with --package:\n${matching.map(describe).join('\n')}`
|
|
86
|
+
: options.package
|
|
87
|
+
? `${options.package} has no WebView to inspect; is it running with WebView debugging enabled?`
|
|
88
|
+
: 'Nothing to inspect: no app with WebView debugging enabled is running.',
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
const [target] = matching
|
|
92
|
+
const forward = await forwardAndroidDevtools(run, target.socket)
|
|
93
|
+
let bridge
|
|
94
|
+
try {
|
|
95
|
+
// Android keeps blank WebViews without a window that never answer DevTools; a
|
|
96
|
+
// client attaching to them all would wait forever, so the bridge hides them.
|
|
97
|
+
bridge = await startCdpBridge({ upstream: forward.cdp, port: options.port })
|
|
98
|
+
console.log(`Android ${describe(target).trim()} on ${bridge.url}
|
|
99
|
+
|
|
100
|
+
Use it like a desktop debugging endpoint:
|
|
101
|
+
recovery-probe desktop --cdp ${bridge.url} --list
|
|
102
|
+
"cdp": "${bridge.url}" in an observe or desktop config
|
|
103
|
+
|
|
104
|
+
Keep the app on screen while a check runs. Press Ctrl+C to remove the forward.`)
|
|
105
|
+
await untilStopped(options.duration)
|
|
106
|
+
} finally {
|
|
107
|
+
await bridge?.close()
|
|
108
|
+
await forward.remove()
|
|
109
|
+
}
|
|
110
|
+
}
|
package/bin/attach.mjs
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { readFile, mkdir } from 'node:fs/promises'
|
|
2
2
|
import { resolve } from 'node:path'
|
|
3
|
-
import { connectDesktop, selectDesktopPage } from '../
|
|
4
|
-
import { discoverHttp, httpDiscoveryConfig } from '../
|
|
5
|
-
import { writeDiscoveryReport } from '../
|
|
6
|
-
import { prepareVisibility } from '../
|
|
7
|
-
import { checkDesktop } from '../
|
|
8
|
-
import { writeDesktopReport } from '../
|
|
3
|
+
import { connectDesktop, selectDesktopPage } from '../dist/desktop.mjs'
|
|
4
|
+
import { discoverHttp, httpDiscoveryConfig } from '../dist/http-discover.mjs'
|
|
5
|
+
import { writeDiscoveryReport } from '../dist/discovery-report.mjs'
|
|
6
|
+
import { prepareVisibility } from '../dist/visibility.mjs'
|
|
7
|
+
import { checkDesktop } from '../dist/desktop.mjs'
|
|
8
|
+
import { writeDesktopReport } from '../dist/desktop-report.mjs'
|
|
9
9
|
export async function attachMain(args) {
|
|
10
10
|
const options = {}
|
|
11
11
|
for (let i = 0; i < args.length; i++) {
|
|
@@ -40,19 +40,23 @@ export async function attachMain(args) {
|
|
|
40
40
|
const browser = await connectDesktop(config.cdp)
|
|
41
41
|
try {
|
|
42
42
|
const page = selectDesktopPage(browser, config)
|
|
43
|
+
/** @type {Record<string, any>} */
|
|
43
44
|
let report
|
|
44
45
|
if (options.discover) {
|
|
45
|
-
|
|
46
|
-
await writeDiscoveryReport(directory,
|
|
46
|
+
const discovery = await discoverHttp(page, config)
|
|
47
|
+
await writeDiscoveryReport(directory, discovery, config)
|
|
48
|
+
report = discovery
|
|
47
49
|
} else {
|
|
48
50
|
const visibility = await prepareVisibility(page, config)
|
|
51
|
+
let check
|
|
49
52
|
try {
|
|
50
|
-
|
|
51
|
-
|
|
53
|
+
check = await checkDesktop(page, config)
|
|
54
|
+
check.mode = 'attached browser recovery'
|
|
52
55
|
} finally {
|
|
53
56
|
await visibility.revert()
|
|
54
57
|
}
|
|
55
|
-
await writeDesktopReport(directory,
|
|
58
|
+
await writeDesktopReport(directory, check, config)
|
|
59
|
+
report = check
|
|
56
60
|
}
|
|
57
61
|
for (const f of report.findings ?? report.results)
|
|
58
62
|
console.log(
|
package/bin/compare.mjs
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { compareReports, describeRuns, describeSide } from '../dist/compare.mjs'
|
|
2
|
+
|
|
3
|
+
const USAGE =
|
|
4
|
+
'recovery-probe compare --before REPORT... --after REPORT... [--before-label TEXT] [--after-label TEXT] [--markdown | --json]'
|
|
5
|
+
|
|
6
|
+
const HELP = `${USAGE}
|
|
7
|
+
|
|
8
|
+
Compares reports of the same check from before and after a change, such as
|
|
9
|
+
main and a pull request branch. REPORT is a report.json or its folder; give
|
|
10
|
+
several runs per side to compare repeated runs. A problem counts as found from
|
|
11
|
+
any run, but as gone only when a complete run after the change checked it, so a
|
|
12
|
+
run that stopped early never reads as a fix. --markdown prints a block for a
|
|
13
|
+
pull request. Exit 0: improved, or no problem on either side; 1: a new suspected
|
|
14
|
+
defect or failed check; 2: anything else to review. See docs/compare.md.`
|
|
15
|
+
|
|
16
|
+
const STATUS = {
|
|
17
|
+
NEW: 'new',
|
|
18
|
+
STILL: 'still there',
|
|
19
|
+
GONE: 'gone',
|
|
20
|
+
UNVERIFIED: 'not checked to the end',
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function parseArgs(args) {
|
|
24
|
+
const options = { before: [], after: [], labels: {} }
|
|
25
|
+
let side
|
|
26
|
+
for (let i = 0; i < args.length; i++) {
|
|
27
|
+
const arg = args[i]
|
|
28
|
+
if (arg === '--before' || arg === '--after') side = arg.slice(2)
|
|
29
|
+
else if (arg === '--json' || arg === '--markdown') {
|
|
30
|
+
options.format = arg.slice(2)
|
|
31
|
+
side = undefined
|
|
32
|
+
} else if (arg === '--before-label' || arg === '--after-label') {
|
|
33
|
+
if (!args[i + 1] || args[i + 1].startsWith('--'))
|
|
34
|
+
throw Error(`${arg} needs a text, such as main`)
|
|
35
|
+
options.labels[arg.slice(2, -'-label'.length)] = args[++i]
|
|
36
|
+
side = undefined
|
|
37
|
+
} else if (arg.startsWith('--') || !side) throw Error(`Use ${USAGE}`)
|
|
38
|
+
else options[side].push(arg)
|
|
39
|
+
}
|
|
40
|
+
if (!options.before.length || !options.after.length)
|
|
41
|
+
throw Error(`Give reports on both sides: ${USAGE}`)
|
|
42
|
+
return options
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function printText(comparison) {
|
|
46
|
+
const { labels } = comparison
|
|
47
|
+
console.log(
|
|
48
|
+
`Recovery Probe comparison${comparison.mode ? `: ${comparison.mode}` : ''}${comparison.target ? `, ${comparison.target}` : ''}`,
|
|
49
|
+
)
|
|
50
|
+
console.log(` ${labels.before}: ${describeRuns(comparison.before)}`)
|
|
51
|
+
console.log(` ${labels.after}: ${describeRuns(comparison.after)}`)
|
|
52
|
+
if (comparison.changes.length) console.log('')
|
|
53
|
+
for (const change of comparison.changes) {
|
|
54
|
+
const problem = `${change.code}${change.scope ? ` (${change.scope})` : ''}`
|
|
55
|
+
console.log(
|
|
56
|
+
` ${STATUS[change.status].padEnd(22)} ${problem.padEnd(36)} ${change.severity === 'defect' ? 'suspected defect' : 'lead'}`,
|
|
57
|
+
)
|
|
58
|
+
console.log(
|
|
59
|
+
` ${''.padEnd(22)} ${labels.before}: ${describeSide(change.before)}; ${labels.after}: ${describeSide(change.after)}`,
|
|
60
|
+
)
|
|
61
|
+
}
|
|
62
|
+
const { outcomes } = comparison
|
|
63
|
+
if (outcomes.before.length || outcomes.after.length)
|
|
64
|
+
console.log(
|
|
65
|
+
`\n Other outcomes: ${labels.before} ${outcomes.before.join(', ') || 'none'}; ${labels.after} ${outcomes.after.join(', ') || 'none'}`,
|
|
66
|
+
)
|
|
67
|
+
for (const [label, runs] of [
|
|
68
|
+
[labels.before, comparison.before],
|
|
69
|
+
[labels.after, comparison.after],
|
|
70
|
+
])
|
|
71
|
+
for (const run of runs)
|
|
72
|
+
if (run.gaps.length)
|
|
73
|
+
console.log(
|
|
74
|
+
`\n ${label} ${run.complete ? 'partial' : 'incomplete'}, ${run.path}:\n ${run.gaps.join('\n ')}`,
|
|
75
|
+
)
|
|
76
|
+
console.log(`\n${comparison.verdict}: ${comparison.summary}`)
|
|
77
|
+
if (comparison.limitation)
|
|
78
|
+
console.log(`Covers only this check. ${comparison.limitation}`)
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export async function compareMain(args) {
|
|
82
|
+
if (args.includes('--help')) {
|
|
83
|
+
console.log(HELP)
|
|
84
|
+
return
|
|
85
|
+
}
|
|
86
|
+
const options = parseArgs(args)
|
|
87
|
+
const comparison = await compareReports(
|
|
88
|
+
options.before,
|
|
89
|
+
options.after,
|
|
90
|
+
options.labels,
|
|
91
|
+
)
|
|
92
|
+
if (options.format === 'json')
|
|
93
|
+
console.log(JSON.stringify(comparison, null, 2))
|
|
94
|
+
else if (options.format === 'markdown')
|
|
95
|
+
process.stdout.write(comparison.markdown)
|
|
96
|
+
else printText(comparison)
|
|
97
|
+
process.exitCode = comparison.exitCode
|
|
98
|
+
}
|
package/bin/desktop.mjs
CHANGED
|
@@ -8,8 +8,8 @@ import {
|
|
|
8
8
|
discoverDesktop,
|
|
9
9
|
checkDesktop,
|
|
10
10
|
validateDesktopConfig,
|
|
11
|
-
} from '../
|
|
12
|
-
import { writeDesktopReport } from '../
|
|
11
|
+
} from '../dist/desktop.mjs'
|
|
12
|
+
import { writeDesktopReport } from '../dist/desktop-report.mjs'
|
|
13
13
|
|
|
14
14
|
export async function desktopMain(args) {
|
|
15
15
|
if (!args.length || args.includes('--help')) {
|
package/bin/ipc.mjs
CHANGED
|
@@ -1,20 +1,24 @@
|
|
|
1
|
-
import { writeDiscoveryReport } from '../
|
|
1
|
+
import { writeDiscoveryReport } from '../dist/discovery-report.mjs'
|
|
2
|
+
import { writeActionReport } from '../dist/action-report.mjs'
|
|
3
|
+
import { actionConfig, checkAction } from '../dist/ipc-action.mjs'
|
|
2
4
|
import { readFile, mkdir, writeFile, mkdtemp } from 'node:fs/promises'
|
|
3
5
|
import { resolve, join } from 'node:path'
|
|
4
|
-
import { discoverIpc, discoveryConfig } from '../
|
|
5
|
-
import { checkIpc } from '../
|
|
6
|
-
import { renderTemplate } from '../
|
|
6
|
+
import { discoverIpc, discoveryConfig } from '../dist/ipc-discover.mjs'
|
|
7
|
+
import { checkIpc } from '../dist/ipc-check.mjs'
|
|
8
|
+
import { renderTemplate } from '../dist/report-template.mjs'
|
|
7
9
|
|
|
8
10
|
export async function ipcMain(args) {
|
|
9
11
|
if (!args.length || args.includes('--help')) {
|
|
10
12
|
console.log(`Recovery Probe IPC preview
|
|
11
|
-
recovery-probe ipc --config ipc-scenario.json [--out NEW_DIRECTORY] [--discover]
|
|
13
|
+
recovery-probe ipc --config ipc-scenario.json [--out NEW_DIRECTORY] [--discover | --action]
|
|
12
14
|
|
|
13
15
|
Requires a development-only main-process registration hook and two loopback ports:
|
|
14
16
|
Electron CDP (usually 9222) and Node inspector (usually 9229).
|
|
15
17
|
Default: verify one IPC rejection; null-result is explicitly optional.
|
|
16
18
|
--discover: compare healthy controls with single/double rejection and null-result experiments.
|
|
17
19
|
Discovery uses structural comparisons and language hints; findings require review. No readiness selector needed.
|
|
20
|
+
--action: run scripted setup steps, then click the action while the hook answers its write channel:
|
|
21
|
+
a simulated success, a simulated failure and a double-click. Nothing is written.
|
|
18
22
|
No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and scope.`)
|
|
19
23
|
return
|
|
20
24
|
}
|
|
@@ -24,8 +28,8 @@ No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and
|
|
|
24
28
|
options.restoreWindow = true
|
|
25
29
|
continue
|
|
26
30
|
}
|
|
27
|
-
if (args[i] === '--discover') {
|
|
28
|
-
options.
|
|
31
|
+
if (args[i] === '--discover' || args[i] === '--action') {
|
|
32
|
+
options[args[i].slice(2)] = true
|
|
29
33
|
continue
|
|
30
34
|
}
|
|
31
35
|
if (
|
|
@@ -34,14 +38,20 @@ No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and
|
|
|
34
38
|
args[i + 1].startsWith('--')
|
|
35
39
|
)
|
|
36
40
|
throw new Error(
|
|
37
|
-
'Use ipc --config FILE [--out NEW_DIRECTORY] [--discover]',
|
|
41
|
+
'Use ipc --config FILE [--out NEW_DIRECTORY] [--discover | --action]',
|
|
38
42
|
)
|
|
39
43
|
options[args[i].slice(2)] = args[++i]
|
|
40
44
|
}
|
|
41
45
|
if (!options.config) throw new Error('--config is required')
|
|
46
|
+
if (options.discover && options.action)
|
|
47
|
+
throw new Error('Use either --discover or --action')
|
|
42
48
|
const rawConfig = JSON.parse(await readFile(options.config, 'utf8'))
|
|
43
49
|
if (options.restoreWindow) rawConfig.restoreWindow = true
|
|
44
|
-
const config = options.discover
|
|
50
|
+
const config = options.discover
|
|
51
|
+
? discoveryConfig(rawConfig)
|
|
52
|
+
: options.action
|
|
53
|
+
? actionConfig(rawConfig)
|
|
54
|
+
: rawConfig
|
|
45
55
|
const parent = resolve('.recovery-probe')
|
|
46
56
|
let directory
|
|
47
57
|
if (options.out) {
|
|
@@ -51,6 +61,22 @@ No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and
|
|
|
51
61
|
await mkdir(parent, { recursive: true, mode: 0o700 })
|
|
52
62
|
directory = await mkdtemp(join(parent, 'ipc-'))
|
|
53
63
|
}
|
|
64
|
+
if (options.action) {
|
|
65
|
+
// checkAction validates the raw config itself; the early validation above only fails fast.
|
|
66
|
+
const report = await checkAction(rawConfig)
|
|
67
|
+
await writeActionReport(directory, report, rawConfig)
|
|
68
|
+
for (const finding of report.findings)
|
|
69
|
+
console.log(
|
|
70
|
+
`${finding.kind.toUpperCase()}: ${finding.id} — ${finding.classification}`,
|
|
71
|
+
)
|
|
72
|
+
if (report.error) console.error(`Action check stopped: ${report.error}`)
|
|
73
|
+
if (report.cleanupError) console.error(`Cleanup: ${report.cleanupError}`)
|
|
74
|
+
console.log(
|
|
75
|
+
`Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}`,
|
|
76
|
+
)
|
|
77
|
+
process.exitCode = report.ok ? 0 : 2 // Heuristic findings are leads, not proven failures.
|
|
78
|
+
return
|
|
79
|
+
}
|
|
54
80
|
await writeFile(join(directory, '.gitignore'), '*\n', { mode: 0o600 })
|
|
55
81
|
const report = options.discover
|
|
56
82
|
? await discoverIpc(config)
|
|
@@ -74,7 +100,7 @@ No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and
|
|
|
74
100
|
evidence: JSON.stringify(report, null, 2),
|
|
75
101
|
})
|
|
76
102
|
await writeFile(join(directory, 'report.html'), html, { mode: 0o600 })
|
|
77
|
-
if (
|
|
103
|
+
if ('findings' in report) {
|
|
78
104
|
await writeDiscoveryReport(directory, report, config)
|
|
79
105
|
for (const finding of report.findings)
|
|
80
106
|
console.log(
|
package/bin/mcp.mjs
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises'
|
|
2
|
+
import { serveMcp } from '../dist/mcp-server.mjs'
|
|
3
|
+
import {
|
|
4
|
+
recoveryProbeTools,
|
|
5
|
+
closeRecoveryProbeTools,
|
|
6
|
+
MCP_INSTRUCTIONS,
|
|
7
|
+
} from '../dist/mcp-tools.mjs'
|
|
8
|
+
|
|
9
|
+
const HELP = `recovery-probe mcp
|
|
10
|
+
|
|
11
|
+
Serves Recovery Probe to AI coding agents as MCP tools over stdio, so an agent can
|
|
12
|
+
check what an app shows when a read fails before it claims the app handles it.
|
|
13
|
+
Add it to an agent, for example: claude mcp add recovery-probe -- npx recovery-probe mcp
|
|
14
|
+
See docs/mcp.md.`
|
|
15
|
+
|
|
16
|
+
export async function mcpMain(args) {
|
|
17
|
+
if (args.includes('--help')) {
|
|
18
|
+
console.log(HELP)
|
|
19
|
+
return
|
|
20
|
+
}
|
|
21
|
+
if (args.length) throw Error('Use recovery-probe mcp')
|
|
22
|
+
const { version } = JSON.parse(
|
|
23
|
+
await readFile(new URL('../package.json', import.meta.url), 'utf8'),
|
|
24
|
+
)
|
|
25
|
+
try {
|
|
26
|
+
await serveMcp({
|
|
27
|
+
name: 'recovery-probe',
|
|
28
|
+
version,
|
|
29
|
+
instructions: MCP_INSTRUCTIONS,
|
|
30
|
+
tools: recoveryProbeTools,
|
|
31
|
+
})
|
|
32
|
+
} finally {
|
|
33
|
+
await closeRecoveryProbeTools()
|
|
34
|
+
}
|
|
35
|
+
}
|