recovery-probe 0.5.0-preview.7 → 0.5.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 +104 -0
- package/CONTRIBUTING.md +1 -1
- package/README.md +35 -3
- package/bin/recovery-probe.mjs +2 -187
- package/dist/action-report.d.mts +2 -0
- package/dist/action-report.mjs +24 -0
- package/dist/android.d.mts +55 -0
- package/dist/android.mjs +172 -0
- package/dist/cdp-bridge.d.mts +31 -0
- package/dist/cdp-bridge.mjs +237 -0
- package/dist/cli/android.d.mts +1 -0
- package/dist/cli/android.mjs +112 -0
- package/dist/cli/attach.d.mts +1 -0
- package/dist/cli/attach.mjs +85 -0
- package/dist/cli/compare.d.mts +1 -0
- package/dist/cli/compare.mjs +85 -0
- package/dist/cli/core-demo.d.mts +1 -0
- package/dist/cli/core-demo.mjs +8 -0
- package/dist/cli/desktop.d.mts +1 -0
- package/dist/cli/desktop.mjs +124 -0
- package/dist/cli/ipc.d.mts +1 -0
- package/dist/cli/ipc.mjs +120 -0
- package/dist/cli/main.d.mts +1 -0
- package/dist/cli/main.mjs +217 -0
- package/dist/cli/mcp.d.mts +1 -0
- package/dist/cli/mcp.mjs +29 -0
- package/dist/cli/net.d.mts +1 -0
- package/dist/cli/net.mjs +130 -0
- package/dist/cli/observe.d.mts +1 -0
- package/dist/cli/observe.mjs +266 -0
- package/dist/cli/refresh.d.mts +1 -0
- package/dist/cli/refresh.mjs +150 -0
- package/dist/cli/repair.d.mts +1 -0
- package/dist/cli/repair.mjs +90 -0
- package/dist/cli/start.d.mts +1 -0
- package/dist/cli/start.mjs +38 -0
- package/dist/cli/suspects.d.mts +1 -0
- package/dist/cli/suspects.mjs +65 -0
- package/dist/cli/until-stopped.d.mts +3 -0
- package/dist/cli/until-stopped.mjs +17 -0
- package/dist/cli/watch.d.mts +1 -0
- package/dist/cli/watch.mjs +143 -0
- package/dist/cli/web.d.mts +1 -0
- package/dist/cli/web.mjs +107 -0
- package/dist/compare.d.mts +92 -0
- package/dist/compare.mjs +376 -0
- package/dist/desktop.d.mts +67 -61
- package/dist/desktop.mjs +394 -405
- package/dist/file-evidence.d.mts +49 -0
- package/dist/file-evidence.mjs +112 -0
- package/dist/guided-start.d.mts +42 -0
- package/dist/guided-start.mjs +244 -321
- package/dist/http-discover.d.mts +111 -0
- package/dist/http-discover.mjs +310 -343
- package/dist/index.d.mts +49 -0
- package/dist/index.mjs +219 -235
- package/dist/ipc-action.d.mts +74 -0
- package/dist/ipc-action.mjs +314 -0
- package/dist/ipc-check.mjs +2 -21
- package/dist/ipc-control.d.mts +7 -0
- package/dist/ipc-control.mjs +37 -0
- package/dist/ipc-discover.mjs +4 -19
- package/dist/ipc-probe.cjs +14 -3
- package/dist/ipc-probe.d.cts +5 -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-report.d.mts +20 -0
- package/dist/observation-report.mjs +15 -1
- package/dist/observe-network.d.mts +13 -0
- package/dist/observe-network.mjs +57 -0
- package/dist/observe-steps.d.mts +25 -3
- package/dist/observe-steps.mjs +62 -14
- package/dist/pick-marker.d.mts +10 -0
- package/dist/pick-marker.mjs +86 -103
- package/dist/refresh.d.mts +156 -0
- package/dist/refresh.mjs +388 -412
- package/dist/repair-process.d.mts +17 -0
- package/dist/repair-process.mjs +89 -98
- package/dist/repair-provider.d.mts +53 -0
- package/dist/repair-provider.mjs +66 -88
- package/dist/repair.d.mts +72 -0
- package/dist/repair.mjs +412 -519
- 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 +3 -0
- package/dist/visibility.mjs +39 -22
- package/dist/watch.d.mts +99 -0
- package/dist/watch.mjs +315 -0
- package/dist/web.d.mts +19 -22
- package/dist/web.mjs +40 -46
- package/docs/android.md +67 -0
- package/docs/api.md +8 -0
- package/docs/ci.md +1 -1
- package/docs/compare.md +105 -0
- package/docs/desktop.md +2 -2
- package/docs/ipc.md +41 -2
- package/docs/mcp.md +66 -0
- package/docs/net.md +83 -0
- package/docs/observe.md +32 -1
- package/docs/repair.md +1 -1
- package/docs/start.md +2 -2
- package/docs/suspects.md +100 -0
- package/docs/watch.md +59 -0
- package/package.json +31 -12
- package/bin/attach.mjs +0 -79
- package/bin/core-demo.mjs +0 -11
- package/bin/desktop.mjs +0 -157
- package/bin/ipc.mjs +0 -108
- package/bin/observe.mjs +0 -255
- package/bin/refresh.mjs +0 -162
- package/bin/repair.mjs +0 -112
- package/bin/start.mjs +0 -39
- package/bin/web.mjs +0 -120
- package/dist/index.d.ts +0 -54
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,110 @@ 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 (2026-10-21)
|
|
8
|
+
|
|
9
|
+
Promotes previews 1–22 to the stable npm `latest` channel. The preview entries below retain the detailed history.
|
|
10
|
+
|
|
11
|
+
- Synchronize the brief-content observation fixture with completed samples so a slow sampler cannot race its restoration timer. Keep coverage of transitions entirely between samples.
|
|
12
|
+
- Complete the TypeScript migration of the library and CLI. Published JavaScript and declarations are built into `dist/`; public package imports and the `recovery-probe` command remain available.
|
|
13
|
+
- Add IPC action checks for simulated success, failure and double-clicks, delayed injected results, and scripted fill/press steps.
|
|
14
|
+
- Add a host-level HTTPS fault proxy and network steps during observation, plus evidence of local files removed by the app.
|
|
15
|
+
- Add MCP tools for coding agents, experimental source scanning with `suspects`, before/after report comparison, and `watch` to rerun checks after saves.
|
|
16
|
+
- Add experimental Android WebView attachment and Meta Quest keep-awake support, with diagnostics for visible pages that are not rendering.
|
|
17
|
+
|
|
18
|
+
Upgrading from 0.4.0: keep using the public package exports and CLI. If `RECOVERY_PROBE_IPC_MODULE` stores the old `src/ipc-probe.cjs` path, resolve it again with `node -p "require.resolve('recovery-probe/ipc')"`; it now points into `dist/`. Restart the development app after upgrading so its loaded IPC hook matches the CLI. The optional TypeScript peer dependency is needed only for source scanning. Experimental workflows remain experimental in this stable package.
|
|
19
|
+
|
|
20
|
+
## 0.5.0-preview.22 (2026-10-21)
|
|
21
|
+
|
|
22
|
+
- The command line is written in TypeScript under `src/cli` and compiled to `dist/cli`. `bin/recovery-probe.mjs` is now a launcher for it; the `recovery-probe` command, its options and its output are unchanged.
|
|
23
|
+
- `npm run demo` runs `dist/cli/core-demo.mjs`.
|
|
24
|
+
|
|
25
|
+
## 0.5.0-preview.21 (2026-10-21)
|
|
26
|
+
|
|
27
|
+
- The opt-in repair workflow (`recovery-probe repair`) is written in TypeScript. Its files, prompts and checks are unchanged.
|
|
28
|
+
- All of the library source is now TypeScript, and every published declaration is generated from it.
|
|
29
|
+
|
|
30
|
+
## 0.5.0-preview.20 (2026-10-21)
|
|
31
|
+
|
|
32
|
+
- HTTP discovery (`web --attach --discover`), the guided setup (`recovery-probe start`) and its content picker are written in TypeScript. Their reports and prompts are unchanged.
|
|
33
|
+
|
|
34
|
+
## 0.5.0-preview.19 (2026-10-21)
|
|
35
|
+
|
|
36
|
+
- The package root (`withFault`, `probeRecovery`), `recovery-probe/desktop` and `recovery-probe/web` are written in TypeScript. Their reports are unchanged.
|
|
37
|
+
- Their declarations are generated from the source instead of written by hand. They accept everything the old ones did and add `ValidDesktopConfig`, `DesktopDiscovery`, a typed `ProbeError` constructor, and the `baselineTimeoutMs`, `recoveryTimeoutMs` and `times` fields that `DesktopReport` already carried.
|
|
38
|
+
- The root declarations moved from `dist/index.d.ts` to `dist/index.d.mts`. The `types` fields point to the new file.
|
|
39
|
+
|
|
40
|
+
## 0.5.0-preview.18 (2026-10-21)
|
|
41
|
+
|
|
42
|
+
- Refresh experiments (`recovery-probe refresh`) are written in TypeScript. Their reports are unchanged.
|
|
43
|
+
|
|
44
|
+
## 0.5.0-preview.17 (2026-10-21)
|
|
45
|
+
|
|
46
|
+
- **`recovery-probe android --keep-awake`** keeps a Meta Quest's display awake and pauses the Guardian boundary until the forward stops, then restores both. Checks can then run on a headset that nobody wears.
|
|
47
|
+
- `android` warns when the display is asleep or the Guardian dialog has focus. The page then draws no frames, and clicks time out.
|
|
48
|
+
- Checks that record the window state now tell a visible page apart from one that only reports itself visible: `visible-not-rendering` (no frames) or `visible-without-viewport` (no size). They also say so on the terminal.
|
|
49
|
+
- Checked on a Quest 2: discovery and a recovery check on a production app's WebView, and clicks with `--keep-awake`. See docs/android.md.
|
|
50
|
+
|
|
51
|
+
## 0.5.0-preview.16 (2026-10-20)
|
|
52
|
+
|
|
53
|
+
- **`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`.
|
|
54
|
+
- 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.
|
|
55
|
+
- `summary.json` and `summary.md` (the pull request block for the first run against the latest) are rewritten after every run.
|
|
56
|
+
- Without a check, the watch only scans for suspects. See docs/watch.md.
|
|
57
|
+
|
|
58
|
+
## 0.5.0-preview.15 (2026-10-20)
|
|
59
|
+
|
|
60
|
+
- **`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.
|
|
61
|
+
- Each side takes one or more reports, report folders or folders of runs, so repeated runs can be compared.
|
|
62
|
+
- It returns a verdict: `IMPROVED`, `PARTLY_IMPROVED`, `REGRESSED`, `MIXED`, `UNCHANGED`, `INCONCLUSIVE` or `NOT_COMPARABLE`. It exits 1 only for a new suspected defect.
|
|
63
|
+
- `--markdown` prints a block for the pull request. See docs/compare.md.
|
|
64
|
+
- The MCP server adds `compare_reports`, and tells agents to compare reports before they say a change fixed something.
|
|
65
|
+
|
|
66
|
+
## 0.5.0-preview.14 (2026-10-20)
|
|
67
|
+
|
|
68
|
+
- **`recovery-probe suspects`** (experimental) reads JavaScript and TypeScript sources for error handling that loses data:
|
|
69
|
+
- `UNKNOWN_AS_EMPTY`: a failed or unexpected read becomes an empty collection;
|
|
70
|
+
- `FAILURE_ONLY_LOGGED`: a read stores its data when it succeeds, but its failure is only logged.
|
|
71
|
+
- 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.
|
|
72
|
+
- The MCP server adds `find_suspects`.
|
|
73
|
+
- TypeScript is a new optional peer dependency, needed only by the scanner.
|
|
74
|
+
|
|
75
|
+
## 0.5.0-preview.13 (2026-10-20)
|
|
76
|
+
|
|
77
|
+
- **`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.
|
|
78
|
+
|
|
79
|
+
## 0.5.0-preview.12 (2026-10-20)
|
|
80
|
+
|
|
81
|
+
- **`recovery-probe mcp`** serves Recovery Probe to AI coding agents as MCP tools over stdio:
|
|
82
|
+
- `find_page_reads` and `check_read_recovery` for a page's reads;
|
|
83
|
+
- four tools that run the network fault proxy;
|
|
84
|
+
- `run_recovery_probe` for observe, ipc, refresh, desktop and web.
|
|
85
|
+
- 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.
|
|
86
|
+
- A caught fault returns the report folder with `fix-brief.md` and `reproduce.mjs`.
|
|
87
|
+
- No new dependencies. See docs/mcp.md.
|
|
88
|
+
- The package description now says the checks can run from an AI coding agent.
|
|
89
|
+
|
|
90
|
+
## 0.5.0-preview.11 (2026-10-20)
|
|
91
|
+
|
|
92
|
+
- **`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.
|
|
93
|
+
|
|
94
|
+
## 0.5.0-preview.10 (2026-10-20)
|
|
95
|
+
|
|
96
|
+
- **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.
|
|
97
|
+
- `recovery-probe net` runs without `--rules` and answers a loopback control; `recovery-probe/net` adds `connectNetworkFaults` and the `control` option.
|
|
98
|
+
|
|
99
|
+
## 0.5.0-preview.9 (2026-10-20)
|
|
100
|
+
|
|
101
|
+
- **`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.
|
|
102
|
+
- `recovery-probe/net` exports the same proxy as `startNetworkFaultProxy`.
|
|
103
|
+
|
|
104
|
+
## 0.5.0-preview.8 (2026-10-16)
|
|
105
|
+
|
|
106
|
+
- **`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.
|
|
107
|
+
- Steps gain `fill` and `press`, also available to `observe --steps`. Typed values are never written to reports.
|
|
108
|
+
- The IPC hook can delay injected results with `delayMs` to simulate request time; `identify` reports this as `capabilities.faultDelay`.
|
|
109
|
+
- 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.
|
|
110
|
+
|
|
7
111
|
## 0.5.0-preview.7 (2026-10-16)
|
|
8
112
|
|
|
9
113
|
- The IPC check and IPC discovery (`recovery-probe ipc` and `ipc --discover`) are written in TypeScript. Their reports are unchanged.
|
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. The package is
|
|
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 written in TypeScript: modules are `.mts` (or `.cts` for CommonJS), and the command line lives in `src/cli`, with `bin/recovery-probe.mjs` only starting it. `npm run build` compiles them into `dist` with strict checks and generated declarations, and copies the 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 `bin`, `examples` and `scripts` 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)
|
|
@@ -18,7 +20,7 @@ The package includes a deliberately broken app and a corrected one. Both pass th
|
|
|
18
20
|
|
|
19
21
|
```bash
|
|
20
22
|
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
21
|
-
npm install --save-dev --save-exact recovery-probe@0.
|
|
23
|
+
npm install --save-dev --save-exact recovery-probe@0.5.0 playwright@1.62.1
|
|
22
24
|
npx playwright install chromium
|
|
23
25
|
npx recovery-probe --demo
|
|
24
26
|
```
|
|
@@ -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) |
|
|
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) |
|
|
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. On a Meta Quest, `--keep-awake` lets checks run without anyone wearing the headset.
|
|
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
|
|
49
65
|
|
|
50
|
-
|
|
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.
|
|
79
|
+
|
|
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
|
|
|
@@ -77,10 +107,12 @@ If no request matches, `withFault` throws `FAULT_NOT_TRIGGERED` instead of letti
|
|
|
77
107
|
|
|
78
108
|
## Install
|
|
79
109
|
|
|
80
|
-
**0.
|
|
110
|
+
**0.5.0** is the stable release on npm's `latest` channel, and the commands above pin it for reproducible reports. Prereleases use the `next` channel and are opt-in.
|
|
81
111
|
|
|
82
112
|
Use Node.js 22 or newer. A separate tools folder keeps the tester out of your application's production dependencies. Browser and desktop commands need Playwright; attached targets use their existing browser runtime. If a version is not on npm yet, use the [source installation](CONTRIBUTING.md#install-an-unpublished-source-preview): a GitHub merge alone does not publish the package. See [CHANGELOG.md](CHANGELOG.md) for version history.
|
|
83
113
|
|
|
114
|
+
When upgrading from 0.4.0, resolve any stored IPC hook path again with `node -p "require.resolve('recovery-probe/ipc')"` and restart the development app. The hook now ships in `dist/`. The library and CLI are compiled from TypeScript; using the published package does not require a build. Source scanning with `suspects` additionally needs the optional TypeScript peer dependency. Experimental commands retain that status in 0.5.0.
|
|
115
|
+
|
|
84
116
|
## Reports, agents and privacy
|
|
85
117
|
|
|
86
118
|
Reports separate measured facts, such as fault counts, successful reads, timings and UI changes, from suspected defects. A `CONTENT_LOSS` finding needs review. An unconsumed fault, an unstable control or an unsupported path is inconclusive. Observation findings such as `DELAYED_UI_UPDATE` are leads to check against the application logic, not verdicts.
|
package/bin/recovery-probe.mjs
CHANGED
|
@@ -1,188 +1,3 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
import
|
|
4
|
-
import { probeRecovery } from '../dist/index.mjs'
|
|
5
|
-
import { startDemoServer } from '../examples/demo-server.mjs'
|
|
6
|
-
|
|
7
|
-
const { version } = JSON.parse(
|
|
8
|
-
await readFile(new URL('../package.json', import.meta.url), 'utf8'),
|
|
9
|
-
)
|
|
10
|
-
|
|
11
|
-
function printHelp() {
|
|
12
|
-
console.log(`Recovery Probe ${version}
|
|
13
|
-
|
|
14
|
-
Usage:
|
|
15
|
-
recovery-probe --demo [--out report.json] [--json]
|
|
16
|
-
recovery-probe --config scenario.json [--out report.json] [--json]
|
|
17
|
-
recovery-probe start web http://localhost:3000
|
|
18
|
-
recovery-probe start desktop
|
|
19
|
-
recovery-probe refresh --help
|
|
20
|
-
recovery-probe observe --help
|
|
21
|
-
recovery-probe ipc --help
|
|
22
|
-
recovery-probe desktop --help
|
|
23
|
-
recovery-probe web --help
|
|
24
|
-
recovery-probe repair --help
|
|
25
|
-
recovery-probe --version
|
|
26
|
-
|
|
27
|
-
Options:
|
|
28
|
-
--demo Run the included broken-versus-fixed browser demonstration.
|
|
29
|
-
--config <file> Check one JSON-configured recovery scenario.
|
|
30
|
-
--out <file> Save the full machine-readable report.
|
|
31
|
-
--json Print the full JSON report instead of a terminal summary.
|
|
32
|
-
--help Show this help.
|
|
33
|
-
|
|
34
|
-
Use only development or test targets you control.`)
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
function marker(outcome) {
|
|
38
|
-
if (outcome === 'pass') return 'PASS'
|
|
39
|
-
if (outcome === 'fail') return 'CAUGHT'
|
|
40
|
-
return outcome.toUpperCase()
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
function printSummary(report) {
|
|
44
|
-
console.log(`Recovery Probe ${report.version} — ${report.mode}\n`)
|
|
45
|
-
for (const app of report.apps) {
|
|
46
|
-
console.log(app.name)
|
|
47
|
-
for (const row of app.results) {
|
|
48
|
-
const injected = row.applied ? `, injected ${row.applied}` : ''
|
|
49
|
-
console.log(
|
|
50
|
-
` ${marker(row.outcome).padEnd(12)} ${row.scenario} (${row.code}${injected})`,
|
|
51
|
-
)
|
|
52
|
-
}
|
|
53
|
-
console.log('')
|
|
54
|
-
}
|
|
55
|
-
if (report.mode === 'controlled demonstration') {
|
|
56
|
-
console.log(
|
|
57
|
-
report.expectedDemonstrationVerified
|
|
58
|
-
? 'Demo verified: the happy path passes, the broken recovery is caught, and the fixed app recovers.'
|
|
59
|
-
: 'Demo failed: the expected broken-versus-fixed distinction was not observed.',
|
|
60
|
-
)
|
|
61
|
-
} else {
|
|
62
|
-
console.log(
|
|
63
|
-
report.apps.every((app) => app.ok)
|
|
64
|
-
? 'Recovery check passed.'
|
|
65
|
-
: 'Recovery check did not pass.',
|
|
66
|
-
)
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
async function main() {
|
|
71
|
-
const args = process.argv.slice(2)
|
|
72
|
-
if (args[0] === 'observe') {
|
|
73
|
-
const { observeMain } = await import('./observe.mjs')
|
|
74
|
-
return observeMain(args.slice(1))
|
|
75
|
-
}
|
|
76
|
-
if (args[0] === 'refresh') {
|
|
77
|
-
const { refreshMain } = await import('./refresh.mjs')
|
|
78
|
-
return refreshMain(args.slice(1))
|
|
79
|
-
}
|
|
80
|
-
if (args[0] === 'ipc') {
|
|
81
|
-
const { ipcMain } = await import('./ipc.mjs')
|
|
82
|
-
return ipcMain(args.slice(1))
|
|
83
|
-
}
|
|
84
|
-
if (args[0] === 'start') {
|
|
85
|
-
const { startMain } = await import('./start.mjs')
|
|
86
|
-
return startMain(args.slice(1))
|
|
87
|
-
}
|
|
88
|
-
if (args[0] === 'web') {
|
|
89
|
-
const { webMain } = await import('./web.mjs')
|
|
90
|
-
return webMain(args.slice(1))
|
|
91
|
-
}
|
|
92
|
-
if (args[0] === 'repair') {
|
|
93
|
-
const { repairMain } = await import('./repair.mjs')
|
|
94
|
-
return repairMain(args.slice(1))
|
|
95
|
-
}
|
|
96
|
-
if (args[0] === 'desktop') {
|
|
97
|
-
const { desktopMain } = await import('./desktop.mjs')
|
|
98
|
-
return desktopMain(args.slice(1))
|
|
99
|
-
}
|
|
100
|
-
if (args.includes('--help') || !args.length) {
|
|
101
|
-
printHelp()
|
|
102
|
-
return
|
|
103
|
-
}
|
|
104
|
-
if (args.length === 1 && args[0] === '--version') {
|
|
105
|
-
console.log(version)
|
|
106
|
-
return
|
|
107
|
-
}
|
|
108
|
-
let demo = false
|
|
109
|
-
let json = false
|
|
110
|
-
let configPath
|
|
111
|
-
let output
|
|
112
|
-
for (let i = 0; i < args.length; i++) {
|
|
113
|
-
const arg = args[i]
|
|
114
|
-
if (arg === '--demo') demo = true
|
|
115
|
-
else if (arg === '--json') json = true
|
|
116
|
-
else if (arg === '--config' || arg === '--out') {
|
|
117
|
-
const value = args[++i]
|
|
118
|
-
if (!value || value.startsWith('--'))
|
|
119
|
-
throw new Error(`${arg} needs a value`)
|
|
120
|
-
if (arg === '--config') configPath = value
|
|
121
|
-
else output = value
|
|
122
|
-
} else throw new Error(`Unknown argument: ${arg}`)
|
|
123
|
-
}
|
|
124
|
-
if (demo === Boolean(configPath))
|
|
125
|
-
throw new Error('Choose exactly one of --demo or --config')
|
|
126
|
-
|
|
127
|
-
const config = configPath
|
|
128
|
-
? JSON.parse(await readFile(configPath, 'utf8'))
|
|
129
|
-
: null
|
|
130
|
-
const { chromium } = await import('playwright')
|
|
131
|
-
const browser = await chromium.launch({ headless: true })
|
|
132
|
-
let server
|
|
133
|
-
/** @type {Record<string, any>} */
|
|
134
|
-
let report
|
|
135
|
-
try {
|
|
136
|
-
const apps = []
|
|
137
|
-
if (demo) {
|
|
138
|
-
server = await startDemoServer()
|
|
139
|
-
for (const variant of ['broken', 'fixed']) {
|
|
140
|
-
apps.push(
|
|
141
|
-
await probeRecovery(browser, {
|
|
142
|
-
name: `${variant} synthetic fixture`,
|
|
143
|
-
url: `${server.url}/${variant}`,
|
|
144
|
-
requestPattern: '**/api/profile',
|
|
145
|
-
readySelector: '#profile',
|
|
146
|
-
retrySelector: '#retry',
|
|
147
|
-
timeoutMs: 1200,
|
|
148
|
-
}),
|
|
149
|
-
)
|
|
150
|
-
}
|
|
151
|
-
} else apps.push(await probeRecovery(browser, config))
|
|
152
|
-
report = {
|
|
153
|
-
tool: 'Recovery Probe',
|
|
154
|
-
version,
|
|
155
|
-
generatedAt: new Date().toISOString(),
|
|
156
|
-
environment: {
|
|
157
|
-
node: process.version,
|
|
158
|
-
platform: process.platform,
|
|
159
|
-
chromium: browser.version(),
|
|
160
|
-
},
|
|
161
|
-
mode: demo ? 'controlled demonstration' : 'configured recovery check',
|
|
162
|
-
apps,
|
|
163
|
-
}
|
|
164
|
-
if (demo) {
|
|
165
|
-
report.expectedDemonstrationVerified =
|
|
166
|
-
apps[0].results[0].outcome === 'pass' &&
|
|
167
|
-
apps[0].results
|
|
168
|
-
.slice(1)
|
|
169
|
-
.every((row) => row.outcome === 'fail' && row.applied === 1) &&
|
|
170
|
-
apps[1].ok
|
|
171
|
-
process.exitCode = report.expectedDemonstrationVerified ? 0 : 1
|
|
172
|
-
} else process.exitCode = apps.every((app) => app.ok) ? 0 : 1
|
|
173
|
-
} finally {
|
|
174
|
-
await browser.close()
|
|
175
|
-
if (server) await server.close()
|
|
176
|
-
}
|
|
177
|
-
if (json) console.log(JSON.stringify(report, null, 2))
|
|
178
|
-
else printSummary(report)
|
|
179
|
-
if (output) {
|
|
180
|
-
await mkdir(dirname(output), { recursive: true })
|
|
181
|
-
await writeFile(output, JSON.stringify(report, null, 2) + '\n')
|
|
182
|
-
}
|
|
183
|
-
}
|
|
184
|
-
|
|
185
|
-
main().catch((error) => {
|
|
186
|
-
console.error(`Recovery Probe: ${error.message}`)
|
|
187
|
-
process.exitCode = 2
|
|
188
|
-
})
|
|
2
|
+
// The command line is compiled from src/cli; this file only starts it.
|
|
3
|
+
import '../dist/cli/main.mjs'
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { writeFile } from 'node:fs/promises';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { escapeHtml, renderTemplate } from './report-template.mjs';
|
|
4
|
+
export async function writeActionReport(directory, report, config) {
|
|
5
|
+
await writeFile(join(directory, '.gitignore'), '*\n', { mode: 0o600 });
|
|
6
|
+
await writeFile(join(directory, 'scenario.json'), JSON.stringify(config, null, 2), { mode: 0o600 });
|
|
7
|
+
await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
|
|
8
|
+
const findings = report.findings
|
|
9
|
+
.map((f) => `<tr><td>${escapeHtml(f.id)}</td><td>${escapeHtml(f.classification)}</td><td>${escapeHtml(f.kind)}</td><td>${escapeHtml(f.advice)}</td></tr>`)
|
|
10
|
+
.join('');
|
|
11
|
+
const runs = report.runs
|
|
12
|
+
.map((r) => `<tr><td>${escapeHtml(r.kind)}</td><td>${r.requests}</td><td>${r.timeline.length}</td><td>${r.uncaughtErrors + (r.devErrorOverlay ? ' (development error overlay)' : '')}</td></tr>`)
|
|
13
|
+
.join('');
|
|
14
|
+
await writeFile(join(directory, 'report.html'), renderTemplate('action', {
|
|
15
|
+
heading: report.ok
|
|
16
|
+
? 'The action handled success, failure and a double-click'
|
|
17
|
+
: 'The action needs review',
|
|
18
|
+
limitation: report.limitation,
|
|
19
|
+
findings,
|
|
20
|
+
runs,
|
|
21
|
+
finalReset: report.finalReset,
|
|
22
|
+
evidence: JSON.stringify(report, null, 2),
|
|
23
|
+
}), { mode: 0o600 });
|
|
24
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/** Runs adb with the given arguments and resolves with its standard output. */
|
|
2
|
+
export type AdbRunner = (args: string[]) => Promise<string>;
|
|
3
|
+
export interface AndroidDevtoolsTarget {
|
|
4
|
+
/** The abstract socket name, without its leading `@`. */
|
|
5
|
+
socket: string;
|
|
6
|
+
kind: 'webview' | 'chrome' | 'other';
|
|
7
|
+
pid?: number;
|
|
8
|
+
/** The process that owns the socket, which is the app's package for a WebView. */
|
|
9
|
+
package?: string;
|
|
10
|
+
}
|
|
11
|
+
export interface AndroidForward {
|
|
12
|
+
/** A DevTools endpoint for `desktop --cdp` or a config's `cdp`. */
|
|
13
|
+
cdp: string;
|
|
14
|
+
port: number;
|
|
15
|
+
remove(): Promise<void>;
|
|
16
|
+
}
|
|
17
|
+
/** adb from ANDROID_HOME, ANDROID_SDK_ROOT or the default Windows SDK, else from PATH. */
|
|
18
|
+
export declare function defaultAdbPath(env?: NodeJS.ProcessEnv): string;
|
|
19
|
+
export declare function adbRunner({ adb, serial, }?: {
|
|
20
|
+
adb?: string;
|
|
21
|
+
serial?: string;
|
|
22
|
+
}): AdbRunner;
|
|
23
|
+
/** Serial numbers of the devices adb can use. */
|
|
24
|
+
export declare function androidDevices(run: AdbRunner): Promise<string[]>;
|
|
25
|
+
/** DevTools sockets in `/proc/net/unix` output: one per WebView process or browser. */
|
|
26
|
+
export declare function parseDevtoolsSockets(procNetUnix: string): AndroidDevtoolsTarget[];
|
|
27
|
+
/** Process names by process id, from `ps -A -o PID,NAME` output. */
|
|
28
|
+
export declare function parseProcesses(ps: string): Map<number, string>;
|
|
29
|
+
/** The WebViews and browsers on the device that can be inspected. */
|
|
30
|
+
export declare function androidDevtoolsTargets(run: AdbRunner): Promise<AndroidDevtoolsTarget[]>;
|
|
31
|
+
/** Forwards a free local port to the socket and checks that DevTools answers there. */
|
|
32
|
+
export declare function forwardAndroidDevtools(run: AdbRunner, socket: string, { port, fetchVersion }?: {
|
|
33
|
+
port?: number | undefined;
|
|
34
|
+
fetchVersion?: ((url: string) => Promise<Response>) | undefined;
|
|
35
|
+
}): Promise<AndroidForward>;
|
|
36
|
+
export interface AndroidDisplayState {
|
|
37
|
+
/** A Meta Quest headset, recognised by its manufacturer or Guardian. */
|
|
38
|
+
quest: boolean;
|
|
39
|
+
awake: boolean;
|
|
40
|
+
/** The package of the window with input focus, such as com.oculus.guardian. */
|
|
41
|
+
focus?: string;
|
|
42
|
+
}
|
|
43
|
+
/** Whether the display is awake and which app has focus: a page draws no frames otherwise. */
|
|
44
|
+
export declare function androidDisplayState(run: AdbRunner): Promise<AndroidDisplayState>;
|
|
45
|
+
/** Why a page on this display would draw no frames, if it would not. */
|
|
46
|
+
export declare function displayProblems(state: AndroidDisplayState): string[];
|
|
47
|
+
export interface KeptAwake {
|
|
48
|
+
/** Puts Guardian and the display's proximity handling back as they were. */
|
|
49
|
+
restore(): Promise<void>;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Keeps a Quest's display awake without anyone wearing it, and pauses the
|
|
53
|
+
* Guardian boundary dialog that would otherwise take focus from the app.
|
|
54
|
+
*/
|
|
55
|
+
export declare function keepQuestAwake(run: AdbRunner): Promise<KeptAwake>;
|
package/dist/android.mjs
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
import { execFile } from 'node:child_process';
|
|
2
|
+
import { existsSync } from 'node:fs';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
/** adb from ANDROID_HOME, ANDROID_SDK_ROOT or the default Windows SDK, else from PATH. */
|
|
5
|
+
export function defaultAdbPath(env = process.env) {
|
|
6
|
+
const executable = process.platform === 'win32' ? 'adb.exe' : 'adb';
|
|
7
|
+
const roots = [
|
|
8
|
+
env.ANDROID_HOME,
|
|
9
|
+
env.ANDROID_SDK_ROOT,
|
|
10
|
+
env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'Android', 'Sdk'),
|
|
11
|
+
].filter((root) => Boolean(root));
|
|
12
|
+
for (const root of roots) {
|
|
13
|
+
const path = join(root, 'platform-tools', executable);
|
|
14
|
+
if (existsSync(path))
|
|
15
|
+
return path;
|
|
16
|
+
}
|
|
17
|
+
return executable;
|
|
18
|
+
}
|
|
19
|
+
export function adbRunner({ adb = defaultAdbPath(), serial, } = {}) {
|
|
20
|
+
return (args) => new Promise((resolve, reject) => execFile(adb, [...(serial ? ['-s', serial] : []), ...args], { timeout: 15_000, windowsHide: true }, (error, stdout, stderr) => error
|
|
21
|
+
? reject(new Error(`adb ${args.join(' ')} failed: ${stderr.trim() || error.message}`, {
|
|
22
|
+
cause: error,
|
|
23
|
+
}))
|
|
24
|
+
: resolve(stdout)));
|
|
25
|
+
}
|
|
26
|
+
/** Serial numbers of the devices adb can use. */
|
|
27
|
+
export async function androidDevices(run) {
|
|
28
|
+
return (await run(['devices']))
|
|
29
|
+
.split(/\r?\n/)
|
|
30
|
+
.slice(1)
|
|
31
|
+
.map((line) => line.trim().split(/\s+/))
|
|
32
|
+
.filter(([serial, state]) => serial && state === 'device')
|
|
33
|
+
.map(([serial]) => serial);
|
|
34
|
+
}
|
|
35
|
+
/** DevTools sockets in `/proc/net/unix` output: one per WebView process or browser. */
|
|
36
|
+
export function parseDevtoolsSockets(procNetUnix) {
|
|
37
|
+
const sockets = new Set();
|
|
38
|
+
for (const line of procNetUnix.split(/\r?\n/)) {
|
|
39
|
+
const path = line.trim().split(/\s+/).at(-1) ?? '';
|
|
40
|
+
if (/^@[\w.]*devtools_remote(_\d+)?$/.test(path))
|
|
41
|
+
sockets.add(path.slice(1));
|
|
42
|
+
}
|
|
43
|
+
return [...sockets].map((socket) => {
|
|
44
|
+
const webview = /^webview_devtools_remote_(\d+)$/.exec(socket);
|
|
45
|
+
if (webview)
|
|
46
|
+
return { socket, kind: 'webview', pid: Number(webview[1]) };
|
|
47
|
+
if (socket === 'chrome_devtools_remote')
|
|
48
|
+
return { socket, kind: 'chrome', package: 'com.android.chrome' };
|
|
49
|
+
return { socket, kind: 'other' };
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
/** Process names by process id, from `ps -A -o PID,NAME` output. */
|
|
53
|
+
export function parseProcesses(ps) {
|
|
54
|
+
const processes = new Map();
|
|
55
|
+
for (const line of ps.split(/\r?\n/).slice(1)) {
|
|
56
|
+
const [pid, name] = line.trim().split(/\s+/);
|
|
57
|
+
if (/^\d+$/.test(pid ?? '') && name)
|
|
58
|
+
processes.set(Number(pid), name);
|
|
59
|
+
}
|
|
60
|
+
return processes;
|
|
61
|
+
}
|
|
62
|
+
/** The WebViews and browsers on the device that can be inspected. */
|
|
63
|
+
export async function androidDevtoolsTargets(run) {
|
|
64
|
+
const targets = parseDevtoolsSockets(await run(['shell', 'cat', '/proc/net/unix']));
|
|
65
|
+
if (!targets.some((target) => target.pid !== undefined))
|
|
66
|
+
return targets;
|
|
67
|
+
const processes = parseProcesses(await run(['shell', 'ps', '-A', '-o', 'PID,NAME']));
|
|
68
|
+
return targets.map((target) => target.pid === undefined
|
|
69
|
+
? target
|
|
70
|
+
: { ...target, package: processes.get(target.pid) });
|
|
71
|
+
}
|
|
72
|
+
/** Forwards a free local port to the socket and checks that DevTools answers there. */
|
|
73
|
+
export async function forwardAndroidDevtools(run, socket, { port = 0, fetchVersion = (url) => fetch(url) } = {}) {
|
|
74
|
+
const output = await run([
|
|
75
|
+
'forward',
|
|
76
|
+
`tcp:${port}`,
|
|
77
|
+
`localabstract:${socket}`,
|
|
78
|
+
]);
|
|
79
|
+
const forwarded = port || Number(output.trim());
|
|
80
|
+
if (!Number.isInteger(forwarded) || forwarded <= 0)
|
|
81
|
+
throw new Error(`adb did not report the forwarded port: ${output.trim()}`);
|
|
82
|
+
const remove = async () => {
|
|
83
|
+
await run(['forward', '--remove', `tcp:${forwarded}`]);
|
|
84
|
+
};
|
|
85
|
+
const cdp = `http://127.0.0.1:${forwarded}`;
|
|
86
|
+
try {
|
|
87
|
+
const response = await fetchVersion(`${cdp}/json/version`);
|
|
88
|
+
if (!response.ok)
|
|
89
|
+
throw new Error(`DevTools answered ${response.status}`);
|
|
90
|
+
}
|
|
91
|
+
catch (error) {
|
|
92
|
+
await remove().catch(() => { });
|
|
93
|
+
throw new Error(`No DevTools endpoint behind ${socket}: ${error.message}`, {
|
|
94
|
+
cause: error,
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
return { cdp, port: forwarded, remove };
|
|
98
|
+
}
|
|
99
|
+
// A broadcast namespace of the Quest system, not an installed package.
|
|
100
|
+
const QUEST_POWER_MANAGER = 'com.oculus.vrpowermanager';
|
|
101
|
+
const GUARDIAN = 'com.oculus.guardian';
|
|
102
|
+
const GUARDIAN_PAUSE = 'debug.oculus.guardian_pause';
|
|
103
|
+
const isQuest = async (run) => {
|
|
104
|
+
const manufacturer = await run([
|
|
105
|
+
'shell',
|
|
106
|
+
'getprop',
|
|
107
|
+
'ro.product.manufacturer',
|
|
108
|
+
]);
|
|
109
|
+
if (/^(oculus|meta)$/i.test(manufacturer.trim()))
|
|
110
|
+
return true;
|
|
111
|
+
return run(['shell', 'pm', 'path', GUARDIAN]).then((output) => output.includes('package:'), () => false);
|
|
112
|
+
};
|
|
113
|
+
/** Whether the display is awake and which app has focus: a page draws no frames otherwise. */
|
|
114
|
+
export async function androidDisplayState(run) {
|
|
115
|
+
const power = await run(['shell', 'dumpsys', 'power']);
|
|
116
|
+
const window = await run(['shell', 'dumpsys', 'window']);
|
|
117
|
+
const quest = await isQuest(run);
|
|
118
|
+
const focus = /mCurrentFocus=Window\{\S+ \S+ ([\w.]+)\//.exec(window)?.[1];
|
|
119
|
+
return {
|
|
120
|
+
quest,
|
|
121
|
+
awake: /mWakefulness=Awake/.test(power),
|
|
122
|
+
...(focus ? { focus } : {}),
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
/** Why a page on this display would draw no frames, if it would not. */
|
|
126
|
+
export function displayProblems(state) {
|
|
127
|
+
const problems = [];
|
|
128
|
+
if (!state.awake)
|
|
129
|
+
problems.push('The display is asleep, so the page draws no frames: clicks time out and the screen does not update.');
|
|
130
|
+
if (state.focus === GUARDIAN)
|
|
131
|
+
problems.push('The Guardian boundary dialog is in front of the app, so the app draws no frames.');
|
|
132
|
+
return problems;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Keeps a Quest's display awake without anyone wearing it, and pauses the
|
|
136
|
+
* Guardian boundary dialog that would otherwise take focus from the app.
|
|
137
|
+
*/
|
|
138
|
+
export async function keepQuestAwake(run) {
|
|
139
|
+
const previous = (await run(['shell', 'getprop', GUARDIAN_PAUSE])).trim();
|
|
140
|
+
const restoreCommands = [
|
|
141
|
+
['shell', 'setprop', GUARDIAN_PAUSE, previous || '0'],
|
|
142
|
+
[
|
|
143
|
+
'shell',
|
|
144
|
+
'am',
|
|
145
|
+
'broadcast',
|
|
146
|
+
'-a',
|
|
147
|
+
`${QUEST_POWER_MANAGER}.automation_disable`,
|
|
148
|
+
],
|
|
149
|
+
];
|
|
150
|
+
const restore = async () => {
|
|
151
|
+
const failures = [];
|
|
152
|
+
for (const args of restoreCommands)
|
|
153
|
+
await run(args).catch((error) => failures.push(error.message));
|
|
154
|
+
if (failures.length)
|
|
155
|
+
throw new Error(`Could not restore the headset (${failures.join('; ')}); run ${restoreCommands.map((args) => `adb ${args.join(' ')}`).join(' and ')}`);
|
|
156
|
+
};
|
|
157
|
+
try {
|
|
158
|
+
await run([
|
|
159
|
+
'shell',
|
|
160
|
+
'am',
|
|
161
|
+
'broadcast',
|
|
162
|
+
'-a',
|
|
163
|
+
`${QUEST_POWER_MANAGER}.prox_close`,
|
|
164
|
+
]);
|
|
165
|
+
await run(['shell', 'setprop', GUARDIAN_PAUSE, '1']);
|
|
166
|
+
}
|
|
167
|
+
catch (error) {
|
|
168
|
+
await restore().catch(() => { });
|
|
169
|
+
throw error;
|
|
170
|
+
}
|
|
171
|
+
return { restore };
|
|
172
|
+
}
|