recovery-probe 0.6.0 → 1.0.1
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 +186 -0
- package/CONTRIBUTING.md +12 -2
- package/README.md +10 -2
- package/dist/cli/action.mjs +2 -1
- package/dist/cli/android.mjs +47 -34
- package/dist/cli/check.mjs +26 -33
- package/dist/cli/compare.mjs +38 -20
- package/dist/cli/discover.mjs +39 -33
- package/dist/cli/init.mjs +1 -1
- package/dist/cli/main.mjs +13 -20
- package/dist/cli/net.mjs +46 -31
- package/dist/cli/observe.mjs +156 -191
- package/dist/cli/reads.mjs +45 -38
- package/dist/cli/refresh.mjs +36 -87
- package/dist/cli/repair.mjs +60 -46
- package/dist/cli/runner.mjs +42 -36
- package/dist/cli/start.mjs +2 -1
- package/dist/cli/suspects.mjs +1 -1
- package/dist/cli/terminal.d.mts +1 -1
- package/dist/cli/watch.mjs +57 -55
- package/dist/core/faults.d.mts +4 -0
- package/dist/core/faults.mjs +6 -0
- package/dist/core/region-read.d.mts +57 -0
- package/dist/core/region-read.mjs +222 -0
- package/dist/core/screen.d.mts +3 -53
- package/dist/core/screen.mjs +51 -253
- package/dist/core/selector.d.mts +9 -0
- package/dist/core/selector.mjs +22 -0
- package/dist/core/server.d.mts +7 -0
- package/dist/core/server.mjs +22 -0
- package/dist/core/validate.d.mts +19 -0
- package/dist/core/validate.mjs +39 -0
- package/dist/desktop.d.mts +3 -1
- package/dist/desktop.mjs +2 -1
- package/dist/hook/calls.cjs +54 -0
- package/dist/hook/calls.d.cts +14 -0
- package/dist/hook/checks.cjs +69 -0
- package/dist/hook/checks.d.cts +48 -0
- package/dist/hook/probe.cjs +253 -0
- package/dist/hook/probe.d.cts +16 -0
- package/dist/hook/pushes.cjs +75 -0
- package/dist/hook/pushes.d.cts +10 -0
- package/dist/hook/state.cjs +76 -0
- package/dist/hook/state.d.cts +13 -0
- package/dist/hook/stats.cjs +38 -0
- package/dist/hook/stats.d.cts +9 -0
- package/dist/hook/types.cjs +4 -0
- package/dist/hook/types.d.cts +119 -0
- package/dist/ipc-probe.cjs +3 -402
- package/dist/ipc-probe.d.cts +2 -129
- package/dist/net-fault.d.mts +4 -1
- package/dist/net-fault.mjs +3 -1
- package/dist/reports/action.d.mts +1 -1
- package/dist/reports/check.d.mts +9 -1
- package/dist/reports/check.mjs +39 -3
- package/dist/reports/discovery.mjs +28 -25
- package/dist/reports/evidence.mjs +25 -18
- package/dist/reports/folder.d.mts +3 -6
- package/dist/reports/folder.mjs +4 -5
- package/dist/reports/templates/desktop.html +3 -3
- package/dist/targets/{cdp-bridge.d.mts → cdp-bridge/bridge.d.mts} +1 -14
- package/dist/targets/cdp-bridge/bridge.mjs +106 -0
- package/dist/targets/cdp-bridge/filter.d.mts +19 -0
- package/dist/targets/cdp-bridge/filter.mjs +75 -0
- package/dist/targets/cdp-bridge/websocket.d.mts +14 -0
- package/dist/targets/cdp-bridge/websocket.mjs +140 -0
- package/dist/targets/visibility.d.mts +6 -0
- package/dist/targets/visibility.mjs +92 -87
- package/dist/tools/ask.d.mts +17 -0
- package/dist/tools/ask.mjs +37 -0
- package/dist/tools/compare/markdown.d.mts +5 -0
- package/dist/tools/compare/markdown.mjs +58 -0
- package/dist/tools/compare/reports.d.mts +12 -0
- package/dist/tools/compare/reports.mjs +53 -0
- package/dist/tools/compare/run.d.mts +15 -0
- package/dist/tools/compare/run.mjs +96 -0
- package/dist/tools/compare/types.d.mts +49 -0
- package/dist/tools/compare/types.mjs +1 -0
- package/dist/tools/compare/verdict.d.mts +4 -0
- package/dist/tools/compare/verdict.mjs +74 -0
- package/dist/tools/doctor.mjs +29 -29
- package/dist/tools/init.d.mts +1 -1
- package/dist/tools/init.mjs +1 -1
- package/dist/tools/mcp/args.d.mts +6 -0
- package/dist/tools/mcp/args.mjs +41 -0
- package/dist/tools/mcp/browser-tools.d.mts +3 -0
- package/dist/tools/mcp/browser-tools.mjs +144 -0
- package/dist/tools/mcp/change-tools.d.mts +4 -0
- package/dist/tools/mcp/change-tools.mjs +152 -0
- package/dist/tools/mcp/cli-tool.d.mts +2 -0
- package/dist/tools/mcp/cli-tool.mjs +80 -0
- package/dist/tools/mcp/network-tools.d.mts +4 -0
- package/dist/tools/mcp/network-tools.mjs +112 -0
- package/dist/tools/mcp/server.mjs +124 -104
- package/dist/tools/mcp/tools.d.mts +1 -1
- package/dist/tools/mcp/tools.mjs +6 -521
- package/dist/tools/pick-marker.mjs +8 -2
- package/dist/tools/repair/config.d.mts +17 -0
- package/dist/tools/repair/config.mjs +61 -0
- package/dist/tools/repair/process.mjs +23 -25
- package/dist/tools/repair/provider.mjs +21 -17
- package/dist/tools/repair/run.d.mts +5 -31
- package/dist/tools/repair/run.mjs +91 -370
- package/dist/tools/repair/sources.d.mts +14 -0
- package/dist/tools/repair/sources.mjs +89 -0
- package/dist/tools/repair/target.d.mts +6 -0
- package/dist/tools/repair/target.mjs +89 -0
- package/dist/tools/repair/workspace.d.mts +17 -0
- package/dist/tools/repair/workspace.mjs +90 -0
- package/dist/tools/start/args.d.mts +9 -0
- package/dist/tools/start/args.mjs +29 -0
- package/dist/tools/start/browser.d.mts +5 -0
- package/dist/tools/start/browser.mjs +39 -0
- package/dist/tools/start/configure.d.mts +15 -0
- package/dist/tools/start/configure.mjs +63 -0
- package/dist/tools/start/run.d.mts +17 -0
- package/dist/tools/start/run.mjs +199 -0
- package/dist/tools/suspects/files.d.mts +18 -0
- package/dist/tools/suspects/files.mjs +104 -0
- package/dist/tools/suspects/paths.d.mts +8 -0
- package/dist/tools/suspects/paths.mjs +55 -0
- package/dist/tools/suspects/rules.d.mts +10 -0
- package/dist/tools/suspects/rules.mjs +69 -0
- package/dist/tools/suspects/scan.d.mts +21 -0
- package/dist/tools/suspects/scan.mjs +38 -0
- package/dist/tools/suspects/source.d.mts +18 -0
- package/dist/tools/suspects/source.mjs +77 -0
- package/dist/tools/suspects/tree.d.mts +31 -0
- package/dist/tools/suspects/tree.mjs +174 -0
- package/dist/tools/verify.d.mts +3 -3
- package/dist/tools/verify.mjs +62 -70
- package/dist/tools/watch/checks.d.mts +19 -0
- package/dist/tools/watch/checks.mjs +62 -0
- package/dist/tools/{watch.d.mts → watch/run.d.mts} +3 -33
- package/dist/tools/watch/run.mjs +163 -0
- package/dist/tools/watch/sources.d.mts +13 -0
- package/dist/tools/watch/sources.mjs +110 -0
- package/dist/tools/watch/summary.d.mts +4 -0
- package/dist/tools/watch/summary.mjs +38 -0
- package/dist/transports/fetch.mjs +55 -45
- package/dist/transports/http/observer.d.mts +20 -10
- package/dist/transports/http/observer.mjs +171 -131
- package/dist/transports/http/route.mjs +66 -59
- package/dist/transports/ipc/control.d.mts +9 -2
- package/dist/transports/ipc/control.mjs +16 -3
- package/dist/transports/ipc/inspector.mjs +27 -101
- package/dist/transports/ipc/socket.d.mts +12 -0
- package/dist/transports/ipc/socket.mjs +104 -0
- package/dist/transports/net/client.d.mts +5 -0
- package/dist/transports/net/client.mjs +25 -0
- package/dist/transports/net/control.d.mts +13 -0
- package/dist/transports/net/control.mjs +62 -0
- package/dist/transports/net/proxy.d.mts +13 -0
- package/dist/transports/net/proxy.mjs +122 -0
- package/dist/transports/net/rules.d.mts +21 -0
- package/dist/transports/net/rules.mjs +76 -0
- package/dist/transports/net/tunnels.d.mts +35 -0
- package/dist/transports/net/tunnels.mjs +99 -0
- package/dist/transports/{net.d.mts → net/types.d.mts} +0 -16
- package/dist/transports/net/types.mjs +3 -0
- package/dist/transports/session.d.mts +2 -7
- package/dist/transports/session.mjs +5 -14
- package/dist/workflows/action/classify.d.mts +3 -0
- package/dist/workflows/action/classify.mjs +60 -0
- package/dist/workflows/action/config.d.mts +21 -0
- package/dist/workflows/action/config.mjs +35 -0
- package/dist/workflows/action/run.d.mts +5 -0
- package/dist/workflows/action/run.mjs +194 -0
- package/dist/workflows/action/screen.d.mts +18 -0
- package/dist/workflows/action/screen.mjs +67 -0
- package/dist/workflows/action/types.d.mts +46 -0
- package/dist/workflows/action/types.mjs +1 -0
- package/dist/workflows/check/browser.d.mts +4 -0
- package/dist/workflows/check/browser.mjs +81 -65
- package/dist/workflows/check/http/config.d.mts +20 -0
- package/dist/workflows/check/http/config.mjs +47 -0
- package/dist/workflows/check/http/fault.d.mts +25 -0
- package/dist/workflows/check/http/fault.mjs +113 -0
- package/dist/workflows/check/http/health.d.mts +8 -0
- package/dist/workflows/check/http/health.mjs +45 -0
- package/dist/workflows/check/http/run.d.mts +22 -0
- package/dist/workflows/check/http/run.mjs +95 -0
- package/dist/workflows/check/ipc/config.d.mts +18 -0
- package/dist/workflows/check/ipc/config.mjs +35 -0
- package/dist/workflows/check/ipc/run.d.mts +30 -0
- package/dist/workflows/check/ipc/run.mjs +223 -0
- package/dist/workflows/check/ipc/verdict.d.mts +23 -0
- package/dist/workflows/check/ipc/verdict.mjs +49 -0
- package/dist/workflows/check/screen.d.mts +16 -0
- package/dist/workflows/check/screen.mjs +39 -0
- package/dist/workflows/discover/http.d.mts +2 -2
- package/dist/workflows/discover/http.mjs +56 -65
- package/dist/workflows/discover/ipc.d.mts +1 -1
- package/dist/workflows/discover/ipc.mjs +89 -95
- package/dist/workflows/discover/load.d.mts +22 -0
- package/dist/workflows/discover/load.mjs +174 -0
- package/dist/workflows/discover/run.d.mts +1 -145
- package/dist/workflows/discover/run.mjs +167 -208
- package/dist/workflows/discover/types.d.mts +140 -0
- package/dist/workflows/discover/types.mjs +1 -0
- package/dist/workflows/observe/action-effects.d.mts +24 -0
- package/dist/workflows/observe/action-effects.mjs +33 -0
- package/dist/workflows/observe/adapters.d.mts +13 -0
- package/dist/workflows/observe/adapters.mjs +107 -0
- package/dist/workflows/observe/capture.d.mts +22 -0
- package/dist/workflows/observe/capture.mjs +253 -0
- package/dist/workflows/observe/comparisons.d.mts +55 -0
- package/dist/workflows/observe/comparisons.mjs +160 -0
- package/dist/workflows/observe/config.d.mts +40 -0
- package/dist/workflows/observe/config.mjs +185 -0
- package/dist/workflows/observe/file-faults.d.mts +33 -0
- package/dist/workflows/observe/file-faults.mjs +178 -0
- package/dist/workflows/observe/files.d.mts +4 -3
- package/dist/workflows/observe/files.mjs +8 -5
- package/dist/workflows/observe/initial-report.d.mts +6 -0
- package/dist/workflows/observe/initial-report.mjs +35 -0
- package/dist/workflows/observe/kit.d.mts +1 -9
- package/dist/workflows/observe/kit.mjs +22 -49
- package/dist/workflows/observe/network.d.mts +1 -1
- package/dist/workflows/observe/page-input.d.mts +6 -0
- package/dist/workflows/observe/page-input.mjs +33 -0
- package/dist/workflows/observe/reads.d.mts +34 -0
- package/dist/workflows/observe/reads.mjs +68 -0
- package/dist/workflows/observe/recorder.d.mts +39 -0
- package/dist/workflows/observe/recorder.mjs +225 -0
- package/dist/workflows/observe/render.d.mts +2 -0
- package/dist/workflows/observe/render.mjs +101 -0
- package/dist/workflows/observe/report.d.mts +30 -98
- package/dist/workflows/observe/report.mjs +22 -341
- package/dist/workflows/observe/rows.d.mts +35 -0
- package/dist/workflows/observe/rows.mjs +231 -0
- package/dist/workflows/observe/sample.d.mts +5 -0
- package/dist/workflows/observe/sample.mjs +37 -0
- package/dist/workflows/observe/sampling.d.mts +21 -0
- package/dist/workflows/observe/sampling.mjs +59 -0
- package/dist/workflows/observe/session.d.mts +36 -0
- package/dist/workflows/observe/session.mjs +174 -0
- package/dist/workflows/observe/step-runner.d.mts +14 -0
- package/dist/workflows/observe/step-runner.mjs +134 -0
- package/dist/workflows/observe/steps.d.mts +21 -16
- package/dist/workflows/observe/steps.mjs +100 -164
- package/dist/workflows/observe/summaries.d.mts +10 -0
- package/dist/workflows/observe/summaries.mjs +87 -0
- package/dist/workflows/observe/ui-read.d.mts +5 -0
- package/dist/workflows/observe/ui-read.mjs +26 -0
- package/dist/workflows/reads.mjs +1 -1
- package/dist/workflows/refresh/classify.d.mts +21 -0
- package/dist/workflows/refresh/classify.mjs +47 -0
- package/dist/workflows/refresh/config.d.mts +39 -0
- package/dist/workflows/refresh/config.mjs +78 -0
- package/dist/workflows/refresh/probe.d.mts +38 -0
- package/dist/workflows/refresh/probe.mjs +158 -0
- package/dist/workflows/refresh/run.d.mts +5 -0
- package/dist/workflows/refresh/run.mjs +223 -0
- package/dist/workflows/refresh/session.d.mts +26 -0
- package/dist/workflows/refresh/session.mjs +82 -0
- package/dist/workflows/{refresh.d.mts → refresh/types.d.mts} +7 -49
- package/dist/workflows/refresh/types.mjs +1 -0
- package/dist/workflows/web.d.mts +3 -1
- package/dist/workflows/web.mjs +1 -1
- package/docs/android.md +1 -0
- package/docs/compare.md +3 -3
- package/docs/demo.svg +1 -1
- package/docs/desktop.md +4 -2
- package/docs/ipc.md +4 -4
- package/docs/mcp.md +4 -4
- package/docs/net.md +3 -2
- package/docs/observe.md +29 -1
- package/docs/runner.md +4 -2
- package/docs/start.md +2 -2
- package/docs/verify.md +1 -1
- package/package.json +3 -1
- package/dist/cli/legacy.d.mts +0 -16
- package/dist/cli/legacy.mjs +0 -117
- package/dist/targets/cdp-bridge.mjs +0 -237
- package/dist/tools/compare.d.mts +0 -76
- package/dist/tools/compare.mjs +0 -255
- package/dist/tools/guided-start.d.mts +0 -47
- package/dist/tools/guided-start.mjs +0 -279
- package/dist/tools/suspects.d.mts +0 -54
- package/dist/tools/suspects.mjs +0 -444
- package/dist/tools/watch.mjs +0 -328
- package/dist/transports/net.mjs +0 -307
- package/dist/workflows/action.d.mts +0 -74
- package/dist/workflows/action.mjs +0 -310
- package/dist/workflows/check/http.d.mts +0 -51
- package/dist/workflows/check/http.mjs +0 -270
- package/dist/workflows/check/ipc.d.mts +0 -45
- package/dist/workflows/check/ipc.mjs +0 -238
- package/dist/workflows/observe/run.d.mts +0 -110
- package/dist/workflows/observe/run.mjs +0 -994
- package/dist/workflows/refresh.mjs +0 -398
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,192 @@ 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
|
+
## 1.0.1 (2026-10-28)
|
|
8
|
+
|
|
9
|
+
- Reject browser-origin WebSocket connections and untrusted Host headers on the Android CDP bridge before opening an upstream connection. Validate the network proxy control API's Host header to block DNS rebinding.
|
|
10
|
+
- Bound complete inbound CDP WebSocket messages, including continuation frames, and close oversized messages with code 1009.
|
|
11
|
+
- Suppress MCP tool responses after cancellation and emit `structuredContent` only for object results.
|
|
12
|
+
- Match network host names with or without a final DNS dot. Document wildcard apex behavior, unrestricted local CONNECT tunneling, and the `webContents.send` scope of IPC push counting.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
## 1.0.0 (2026-10-27)
|
|
16
|
+
|
|
17
|
+
The first release with an explicit 1.x compatibility commitment. It removes the old command spellings and brings in everything since 0.6.0: the 0.7.0 and 0.8.0 previews below. The README defines the supported interfaces and experimental exceptions, and explains that failed checks can save unredacted screen-text quotes of up to 200 characters.
|
|
18
|
+
|
|
19
|
+
Breaking:
|
|
20
|
+
|
|
21
|
+
- The old spellings `desktop`, `web`, `ipc`, `--demo` and `--config` are gone. Each now stops with a usage error (exit 3) that names the commands that replaced it: `windows`, `reads` and `check` for `desktop`; `login`, `reads`, `check`, `discover` and `windows` for `web`; `check`, `discover` and `action` for `ipc`; `demo`; and `check --config`. Errors no longer exit with 2: usage errors exit with 3 and setup failures with 4.
|
|
22
|
+
- `demo` and the JSON runner's `check` always write `report.json` into a new `--out` folder; the single report file of the old spellings is gone.
|
|
23
|
+
- `watch` and `verify` rerun only `check`, `discover`, `action`, `observe` and `refresh`; `run_recovery_probe` in the MCP server no longer takes the old spellings.
|
|
24
|
+
|
|
25
|
+
Since 0.6.0:
|
|
26
|
+
|
|
27
|
+
- `observe` file steps (`--files`) that damage a file the way an interrupted download does, and `expect` steps that report `EXPECTATION_NOT_MET` (0.7.0).
|
|
28
|
+
- A `BASELINE_FAILED` result says why, and a fault that wasn't recovered from quotes what the screen showed instead (0.8.0-preview.15). In 1.0.0 the JSON runner quotes the screen too.
|
|
29
|
+
- `check --restore-window`, or `"restoreWindow": true`, un-minimizes the window for an IPC check and minimizes it again afterwards. The IPC check used to ignore it, so an app that hides a minimized window's page, as Electron does by default, stopped the check.
|
|
30
|
+
- The code is restructured into small functions and modules with no change in behaviour, held to size limits that `npm run lint` enforces, with a public API report and report-shape checks in CI (0.8.0-preview.1 to .14).
|
|
31
|
+
- The tests are type-checked (0.8.0-preview.16).
|
|
32
|
+
|
|
33
|
+
Reports written by older versions still read, compare and watch the same. Public package imports and the IPC hook's path are unchanged; restart the development app after upgrading so its hook matches the CLI.
|
|
34
|
+
|
|
35
|
+
## 0.8.0-preview.16 (2026-10-27)
|
|
36
|
+
|
|
37
|
+
The tests are type-checked. No change to the package.
|
|
38
|
+
|
|
39
|
+
- `npm run typecheck` covers `test`, against the built declarations, so a test that calls a function with the wrong options or reads a field a report doesn't have fails before it runs.
|
|
40
|
+
- `fake()` in `test/helpers/fake.mjs` builds a page, browser, IPC hook or report from only the members a test needs, typed as the real thing; a misspelled member is a type error.
|
|
41
|
+
- `listen()` in `test/helpers/ports.mjs` starts a test server on a free loopback port and returns the port.
|
|
42
|
+
- Deliberately invalid input is marked with `// @ts-expect-error` and the reason.
|
|
43
|
+
|
|
44
|
+
## 0.8.0-preview.15 (2026-10-27)
|
|
45
|
+
|
|
46
|
+
Check results say more about why they aren't a pass.
|
|
47
|
+
|
|
48
|
+
- `BASELINE_FAILED` has a `reason`, for example `the ready selector matched 2 elements`, `the ready element doesn't contain "Saved"` or `no successful response from the endpoint within 5000 ms`. The HTTP and IPC checks and the JSON runner give one; the CLI prints it under the result as `Why:`.
|
|
49
|
+
- A fault that was applied and not recovered from gets `screenText`: the lines the screen showed that the healthy screen didn't, such as `You have no orders yet`, up to 200 characters. It's in the CLI output, `report.json`, `report.html`, `fix-brief.md` and the `check_read_recovery` result. The JSON runner doesn't quote the screen.
|
|
50
|
+
- `check_read_recovery` tells agents that `readySelector` must match exactly one element, and to use a list's container or a single item.
|
|
51
|
+
|
|
52
|
+
## 0.8.0-preview.14 (2026-10-27)
|
|
53
|
+
|
|
54
|
+
The MCP server and tools, the remaining commands and two report writers, restructured. No change to the CLI, the MCP tools or the reports.
|
|
55
|
+
|
|
56
|
+
- The MCP server is a small class with a table of methods, and `tools/mcp/tools.mts` (592 lines) is split by area: the browser tools, the network tools and their proxy, the change tools (suspects, compare, verify) and running a command.
|
|
57
|
+
- `android`, `net` and the browser runner are split into small steps.
|
|
58
|
+
- The discovery report and the evidence of a check report are built in small functions.
|
|
59
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 12 to 1, the command dispatcher, whose old spellings go in 1.0.
|
|
60
|
+
|
|
61
|
+
## 0.8.0-preview.13 (2026-10-27)
|
|
62
|
+
|
|
63
|
+
The suspect scanner, `compare` and `watch`, restructured. No change to the CLI, the suspects found or the reports.
|
|
64
|
+
|
|
65
|
+
- `tools/suspects.mts` (574 lines, with a 298-line `scanSource`) is a `tools/suspects/` folder: a `SourceTree` with the questions the rules ask about a node, the failure paths, the four rules as a table, scanning one file, and listing files and changed lines.
|
|
66
|
+
- `tools/compare.mts` is a `tools/compare/` folder: reading reports, the verdict as small functions, the Markdown and the comparison.
|
|
67
|
+
- `tools/watch.mts` (406 lines) is a `tools/watch/` folder: the file watcher, running a check, the summary and a small `Watch` class that queues one job at a time.
|
|
68
|
+
- The `compare` command parses one option at a time and prints in small steps; `watch` prints each event with its own function.
|
|
69
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 26 to 12.
|
|
70
|
+
|
|
71
|
+
## 0.8.0-preview.12 (2026-10-27)
|
|
72
|
+
|
|
73
|
+
Guided start, `doctor` and `verify`, restructured. No change to the CLI, the saved setups or the reports.
|
|
74
|
+
|
|
75
|
+
- `tools/guided-start.mts` (399 lines, with a 165-line `runStart`) is a `tools/start/` folder: the arguments, launching Chromium, configuring a screen, and a small `StartRun` class that loads the saved setup, opens the target, sets up or reuses the check and runs it. The terminal choices that `init` uses too moved to `tools/ask.mts`.
|
|
76
|
+
- `verify` checks a plan entry by entry, and reading the baseline and scanning the changed lines are their own steps.
|
|
77
|
+
- `doctor` reports a hook error and the hook's channels in separate functions.
|
|
78
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 36 to 26.
|
|
79
|
+
|
|
80
|
+
## 0.8.0-preview.11 (2026-10-27)
|
|
81
|
+
|
|
82
|
+
The repair preview, restructured. No change to the CLI, the run folders or what is sent to the model.
|
|
83
|
+
|
|
84
|
+
- `tools/repair/run.mts` (667 lines) keeps `prepareRepair`, `generateRepair` and `verifyRepair` as short sequences of steps. The config rules, the source paths and proposal edits, the isolated checkout with its commands, and launching and attaching to the target each have their own module.
|
|
85
|
+
- The provider builds its request and reads the proposal in separate functions, and stopping a command's process tree is its own function.
|
|
86
|
+
- The `repair` command is split into reproduce, generate and verify steps.
|
|
87
|
+
- The repair tests give the app's first healthy load 10 seconds instead of 1, keeping the 1-second recovery window, so a cold Windows runner no longer fails them.
|
|
88
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 51 to 36.
|
|
89
|
+
|
|
90
|
+
## 0.8.0-preview.10 (2026-10-27)
|
|
91
|
+
|
|
92
|
+
The IPC hook and the code that runs in the page, restructured. No change to the CLI, the library, the hook's API or the reports.
|
|
93
|
+
|
|
94
|
+
- The IPC hook (575 lines, with a 445-line `installIpcProbe`) is a `src/hook/` layer of small CommonJS modules: the public types, the install and plan checks, the read counters and labels, tracking one real call, the push counter, the plan state, and a small `ProbeHook` class behind the same frozen object. `ipc-probe.cts` only re-exports, like the other entry points, and the layer test keeps the hook free of imports from the rest of the package, since it runs inside the app's main process.
|
|
95
|
+
- `readRegion` moved to `core/region-read.mts` and reads the region in small inner steps. It stays one function because Playwright sends only its source to the page; the observer kit and the marker picker follow the same rule. Those three are the only functions allowed past the length limit, each with the reason next to it.
|
|
96
|
+
- `core/screen.mts` keeps summarizing, comparing and classifying regions, each split into short functions.
|
|
97
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 70 to 51.
|
|
98
|
+
|
|
99
|
+
## 0.8.0-preview.9 (2026-10-27)
|
|
100
|
+
|
|
101
|
+
The IPC inspector, the CDP bridge and the window controls, restructured. No change to the CLI, the library or the reports.
|
|
102
|
+
|
|
103
|
+
- The Node inspector's WebSocket is a small `InspectorSocket` class in `transports/ipc/socket.mts`, next to the loopback check and the target discovery. `callIpcInspector` keeps its synchronous and asynchronous paths in two short functions.
|
|
104
|
+
- `targets/cdp-bridge.mts` (293 lines) is a `targets/cdp-bridge/` folder: the WebSocket server with its framing as plain functions, a `TargetFilter` that decides what each client sees, and the bridge.
|
|
105
|
+
- `windowVisibility` reads the window through one function per mechanism, and the window polls and state changes are shared helpers.
|
|
106
|
+
- `waitForSettledCalls` can refuse a plan that is still armed, so the refresh adapter uses it instead of its own copy of the wait.
|
|
107
|
+
- `core/server.mts` listens on loopback and closes a server for both the network proxy and the bridge.
|
|
108
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 81 to 70; `transports/` and `targets/` have none left.
|
|
109
|
+
|
|
110
|
+
## 0.8.0-preview.8 (2026-10-27)
|
|
111
|
+
|
|
112
|
+
The HTTP and network fault layer, restructured. No change to the CLI, the library or the reports.
|
|
113
|
+
|
|
114
|
+
- `transports/net.mts` (453 lines, with a 233-line `startNetworkFaultProxy`) is a `transports/net/` folder: the public types (free of Node types, so consumers type-check without `@types/node`), the rules and which one applies, the open tunnels, the control API, its client, and the proxy. The proxy keeps its state in a small class behind the same plain object, so its methods can still be passed around unbound.
|
|
115
|
+
- `createFaultFetch` and `withFault` share the count, status, method and kind rules from `core/faults.mts`; each still checks them in its own order. `withFault`'s route handler is a small class, and the result is checked by one plain function.
|
|
116
|
+
- The HTTP observer is a class with one method per event.
|
|
117
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 90 to 81.
|
|
118
|
+
|
|
119
|
+
## 0.8.0-preview.7 (2026-10-26)
|
|
120
|
+
|
|
121
|
+
The action check, restructured. No change to the CLI, the library or the reports.
|
|
122
|
+
|
|
123
|
+
- `workflows/action.mts` (470 lines, with a 197-line `checkAction`) is a `workflows/action/` folder: the config as short rules, the report types, the findings as plain functions, reading and watching the screen (the only code that runs in the page), and a small `ActionCheck` class that attaches, prepares and performs each run, reloads and releases.
|
|
124
|
+
- `runSnapshot` in `transports/ipc/control.mts` reads the hook's state of one run and fails if another run or window took over. The IPC check and the action check share it.
|
|
125
|
+
- `targets/visibility.mts` exports the prepared-window and window-report types that discovery, refresh and the action check each declared.
|
|
126
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 97 to 90.
|
|
127
|
+
|
|
128
|
+
## 0.8.0-preview.6 (2026-10-26)
|
|
129
|
+
|
|
130
|
+
The recovery checks, restructured. No change to the CLI, the library or the reports.
|
|
131
|
+
|
|
132
|
+
- `workflows/check/http.mts` (356 lines, with a 153-line `checkDesktop`) is a `workflows/check/http/` folder: the config as short rules, the screen health helpers, and a `FaultTrial` class that takes one fault through arming, reload, Retry and recovery. `checkDesktop` is a short loop over those trials.
|
|
133
|
+
- `workflows/check/ipc.mts` (with a 182-line `checkIpc`) is a `workflows/check/ipc/` folder: the config, the phase verdict as a plain function with its own unit test, and a small `IpcCheck` class that attaches, runs the phases, reloads and disconnects. An unreachable branch of the timed-out verdict is gone.
|
|
134
|
+
- `probeRecovery` is split into small steps. `ensure` takes an optional error class, so the library's input checks still throw `TypeError`, and `ensureRanges` checks its keys against the config's type.
|
|
135
|
+
- The `check` command writes the IPC report through `reports/check.mts`, like the desktop report.
|
|
136
|
+
- `sleep` from `node:timers/promises` replaces eight copies of the same helper and five inline timer promises. The HTTP observer exports its type instead of three modules each deriving it.
|
|
137
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 111 to 97.
|
|
138
|
+
|
|
139
|
+
## 0.8.0-preview.5 (2026-10-26)
|
|
140
|
+
|
|
141
|
+
The refresh experiment, restructured. No change to the CLI, the library or the reports.
|
|
142
|
+
|
|
143
|
+
- `workflows/refresh.mts` (605 lines, with a 327-line `runRefresh` of complexity 50) is now a `workflows/refresh/` folder: the config, the types, the outcome classification as plain functions, a `RefreshProbe` that reloads, watches and triggers the page, and a small `RefreshExperiment` class with one method per phase.
|
|
144
|
+
- The `refresh` command's setup moved out of the CLI into `workflows/refresh/session.mts`; the CLI keeps signals, the report files and the console output.
|
|
145
|
+
- `ensureRanges` takes an optional message, for configs that word range errors their own way.
|
|
146
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 119 to 111.
|
|
147
|
+
|
|
148
|
+
## 0.8.0-preview.4 (2026-10-26)
|
|
149
|
+
|
|
150
|
+
Discovery, restructured. No change to the CLI, the library or the reports.
|
|
151
|
+
|
|
152
|
+
- `runDiscovery` (302 lines) is a small `Discovery` class: calibrate, healthy control, experiment, reset and release are separate methods. One reload, watched until it is ready or out of time, is its own `load.mts`, and the engine's types are in `types.mts`.
|
|
153
|
+
- The HTTP and IPC discovery configs are short rule lists on `core/validate.mts`, which gains `overDefaults` and `ensureRanges`; the observation config uses `ensureRanges` too. Each config gets its own default arrays.
|
|
154
|
+
- The `discover` and `reads` commands are split into small steps: input, run, write, print.
|
|
155
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 134 to 119.
|
|
156
|
+
|
|
157
|
+
## 0.8.0-preview.3 (2026-10-26)
|
|
158
|
+
|
|
159
|
+
The rest of the observation workflow, restructured. No change to the CLI, the library or the reports.
|
|
160
|
+
|
|
161
|
+
- `workflows/observe/report.mts` (833 lines) keeps the report's types; sampling metrics, content comparisons, summaries, action effects and the HTML report each have their own module. Sampling metrics share one accumulator instead of three copies of the same bookkeeping, and the HTML report is built from one small function per section.
|
|
162
|
+
- Step validation is a parser per step kind in `steps.mts`; running steps moved to `step-runner.mts`.
|
|
163
|
+
- File steps run through a `FileFaults` class, and the content comparison tracker is a `ContentComparisons` class.
|
|
164
|
+
- `selectorSpec` and its type moved to `core/selector.mts`, so the core layer no longer imports them from a workflow.
|
|
165
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 153 to 134.
|
|
166
|
+
|
|
167
|
+
## 0.8.0-preview.2 (2026-10-26)
|
|
168
|
+
|
|
169
|
+
The observation engine, restructured. No change to the CLI, the library or the reports.
|
|
170
|
+
|
|
171
|
+
- `workflows/observe/run.mts` (1,294 lines) is now one module per job: configuration, read counters, the IPC and HTTP adapters, row tracking, the capture loop, the recorder that turns samples into the report, and what the page is given. The capture loop is a small class instead of a 451-line function.
|
|
172
|
+
- The `observe` command's setup (files, network faults, steps, attaching to the target and the evidence they add) moved out of the CLI into `workflows/observe/session.mts`; the CLI keeps terminal input, the report files and the console output.
|
|
173
|
+
- `core/validate.mts` holds the checks configuration validators share, starting with observation configs, and keeps every error message the same.
|
|
174
|
+
- The size-limit violations listed in `eslint-suppressions.json` drop from 169 to 153.
|
|
175
|
+
|
|
176
|
+
## 0.8.0-preview.1 (2026-10-26)
|
|
177
|
+
|
|
178
|
+
The first step towards 1.0: checks that let the code be restructured without changing what it does. No change to the CLI, the library or the reports.
|
|
179
|
+
|
|
180
|
+
- ESLint limits the size of `src` code: functions to 50 lines, files to 300, complexity to 12, nesting to 4 levels and parameters to 4. The 169 places that exceed them are listed in `eslint-suppressions.json`, so new code meets them and the list only shrinks.
|
|
181
|
+
- `api/recovery-probe.api.md` records the public API from the built type declarations, and `npm run api:check` fails in CI when it changes without the file being updated.
|
|
182
|
+
- Integration and Electron tests check each workflow's report against the fields listed in `test/fixtures/report-shapes`, so a restructured workflow cannot drop or rename a report field unnoticed.
|
|
183
|
+
|
|
184
|
+
## 0.7.0-preview.2 (2026-10-26)
|
|
185
|
+
|
|
186
|
+
- A file step whose file could not be checked or put back no longer writes the error message to the report. The message names local paths, which belong in the private `files.json`, so the report now gets only the error code, such as `EBUSY`, and `files.json` gets the message next to the kept copy.
|
|
187
|
+
|
|
188
|
+
## 0.7.0-preview.1 (2026-10-26)
|
|
189
|
+
|
|
190
|
+
- File steps. With `observe --files DIR`, a step can remove, truncate or corrupt a file under that directory, the way an interrupted download or an antivirus quarantine does. When the capture ends, each file is reported as repaired by the app, still damaged, or changed; a file the app did not restore adds `LOCAL_FILE_NOT_REPAIRED` and is put back from a private copy. The step's own damage is left out of the `LOCAL_FILES_REMOVED` comparison.
|
|
191
|
+
- `expect` steps. They wait like `waitFor`, but when nothing matching shows in time the script goes on and the report gets `EXPECTATION_NOT_MET`. It counts as a failed check in the evidence block, so `compare` reports it as a suspected defect rather than a lead. `action` setup rejects `expect`, since its step results are not reported.
|
|
192
|
+
|
|
7
193
|
## 0.6.0 (2026-10-23)
|
|
8
194
|
|
|
9
195
|
Promotes previews 1–13 to the stable npm `latest` channel without additional runtime changes.
|
package/CONTRIBUTING.md
CHANGED
|
@@ -16,6 +16,7 @@ npm ci
|
|
|
16
16
|
npm run format:check
|
|
17
17
|
npm run lint
|
|
18
18
|
npm run typecheck
|
|
19
|
+
npm run api:check # public API unchanged, or api/recovery-probe.api.md updated
|
|
19
20
|
npm test # unit tests, no browser
|
|
20
21
|
npm run test:package # installs the packed package like a user would
|
|
21
22
|
npx playwright install chromium
|
|
@@ -26,9 +27,17 @@ npm run test:electron # real Electron
|
|
|
26
27
|
|
|
27
28
|
Tests live in `test/unit`, `test/integration`, `test/electron` and `test/package`, and each script runs every `*.test.mjs` in its folder. Shared helpers are in `test/helpers` (free ports, launching an Electron fixture, the repair fixture) and fixture apps in `test/fixtures`. Electron tests start Electron through `test/helpers/electron.mjs`, which also clears `ELECTRON_RUN_AS_NODE` (some editors set it) and stops the whole process tree.
|
|
28
29
|
|
|
30
|
+
Tests are type-checked against the built declarations. Build a stand-in for a page, a browser or the IPC hook with `fake()` from `test/helpers/fake.mjs`: it takes only the members the test needs and is typed as the real thing, so a misspelled member fails the check. Mark input that is invalid on purpose with `// @ts-expect-error` and the reason.
|
|
31
|
+
|
|
32
|
+
`test/fixtures/report-shapes` lists, for each workflow, the report fields every run produces. Integration and Electron tests fail when a report lacks one, so a change cannot drop or rename a field unnoticed. Rerunning a suite with `UPDATE_REPORT_SHAPES=1` keeps only the fields that run produced too; delete a file first to record new fields, and run twice so fields that depend on timing drop out.
|
|
33
|
+
|
|
29
34
|
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.
|
|
30
35
|
|
|
31
|
-
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 `
|
|
36
|
+
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`, `scripts` and `test` (not the fixture apps) 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/reports/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.
|
|
37
|
+
|
|
38
|
+
Code in `src` keeps functions to 50 lines and files to 300, not counting blank lines and comments, with a cyclomatic complexity of at most 12, at most 4 levels of nesting and at most 4 parameters. A function passed to `page.evaluate` may run longer, because Playwright sends only its source and its helpers must live inside it; mark it with an `eslint-disable` comment that says so, and keep each inner function within the other limits. `npm run lint` fails on any violation.
|
|
39
|
+
|
|
40
|
+
`api/recovery-probe.api.md` lists the public API as the built type declarations describe it. `npm run api:check` fails when it is out of date; run `npm run api:report` after an intended change, so the change is visible in review.
|
|
32
41
|
|
|
33
42
|
## Layout
|
|
34
43
|
|
|
@@ -36,6 +45,7 @@ Code and JSON are formatted with Prettier (`npm run format`) and linted with ESL
|
|
|
36
45
|
|
|
37
46
|
| Folder | Holds |
|
|
38
47
|
| --- | --- |
|
|
48
|
+
| `hook` | The IPC hook, which runs inside the app's main process: CommonJS that imports nothing else from the package |
|
|
39
49
|
| `core` | Fault kinds, URL identity, reading and comparing the screen, package paths |
|
|
40
50
|
| `transports` | Failing reads: Playwright routes, the fetch wrapper, the HTTPS proxy, the IPC inspector and control |
|
|
41
51
|
| `targets` | Reaching the app: launching Chromium, attaching over CDP, window visibility, Android |
|
|
@@ -44,7 +54,7 @@ Code and JSON are formatted with Prettier (`npm run format`) and linted with ESL
|
|
|
44
54
|
| `tools` | What's built on them: init, doctor, guided start, suspects, compare, watch, verify, MCP, repair |
|
|
45
55
|
| `cli` | Argument parsing and output |
|
|
46
56
|
|
|
47
|
-
The files directly in `src/` are the package's public entry points. They only re-export, so their import paths never change; `ipc-probe.cts` is the
|
|
57
|
+
The files directly in `src/` are the package's public entry points. They only re-export, so their import paths never change; `ipc-probe.cts`, which re-exports `hook`, is the file apps load by path. `test/unit/layers.test.mjs` fails when a module imports a layer above it at run time; type imports are free.
|
|
48
58
|
|
|
49
59
|
## Install an unpublished source preview
|
|
50
60
|
|
package/README.md
CHANGED
|
@@ -107,11 +107,19 @@ It doesn't simulate a whole device going offline, WebSocket drops, token expiry,
|
|
|
107
107
|
|
|
108
108
|
Reports stay on your machine and there's no telemetry. Request and response bodies aren't recorded, and discovery and observation keep screen text only as hashes. Reports can still contain endpoint paths, selectors, text you picked as a marker and, with `--screenshots`, what was on screen, so check them before you share them. Nothing calls an AI service except the opt-in [repair](docs/repair.md) workflow.
|
|
109
109
|
|
|
110
|
+
Failed recovery checks can also save `screenText`: up to 200 characters of newly visible screen text, included in terminal output, reports, fix briefs and MCP results. These quotes are not redacted and can contain personal or sensitive data even without screenshots. Review these outputs before sharing them or passing them to an agent.
|
|
111
|
+
|
|
110
112
|
Only test apps and accounts you're allowed to, and keep debugging ports on localhost.
|
|
111
113
|
|
|
112
|
-
##
|
|
114
|
+
## Compatibility in 1.x
|
|
115
|
+
|
|
116
|
+
The compatibility commitment covers documented, non-experimental package exports, CLI commands and options, exit codes, configuration fields, MCP tools and JSON report fields. Removing or renaming these interfaces, changing their types incompatibly, or changing their documented meaning requires a major version. Backward-compatible additions can ship in minor releases; fixes that restore documented behavior can ship in patch releases.
|
|
117
|
+
|
|
118
|
+
Consumers should tolerate additional JSON fields. Exact terminal wording, HTML layout, timing measurements and heuristic findings are not fixed contracts. Internal files under `dist/` are not public imports; use the package's declared exports. Features explicitly labeled experimental, including Android WebView support and repair, may change in minor releases, with changes recorded in the changelog.
|
|
119
|
+
|
|
120
|
+
## Upgrading to 1.0
|
|
113
121
|
|
|
114
|
-
|
|
122
|
+
1.0 removes the old command spellings `desktop`, `web`, `ipc`, `--demo` and `--config`. Each now stops with a usage error that names the commands that replaced it, such as `windows`, `reads`, `check`, `discover`, `action` and `demo`. Usage errors exit with 3 and setup failures with 4, where the old spellings exited with 2, so update CI scripts that read exit codes. `demo` and the JSON runner's `check` write `report.json` into the `--out` folder. Restart the development app after upgrading so its IPC hook matches the CLI. Public package imports and the hook's path are unchanged. See the [changelog](CHANGELOG.md).
|
|
115
123
|
|
|
116
124
|
## Docs
|
|
117
125
|
|
package/dist/cli/action.mjs
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { join } from 'node:path';
|
|
2
2
|
import { reportFolder } from '../reports/folder.mjs';
|
|
3
3
|
import { writeActionReport } from '../reports/action.mjs';
|
|
4
|
-
import { actionConfig
|
|
4
|
+
import { actionConfig } from '../workflows/action/config.mjs';
|
|
5
|
+
import { checkAction } from '../workflows/action/run.mjs';
|
|
5
6
|
import { readConfig, text, UsageError, validated, } from './args.mjs';
|
|
6
7
|
export const usage = `recovery-probe action --config FILE [options]
|
|
7
8
|
|
package/dist/cli/android.mjs
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
+
import { setTimeout as sleep } from 'node:timers/promises';
|
|
1
2
|
import { adbRunner, androidDevices, androidDevtoolsTargets, androidDisplayState, displayProblems, forwardAndroidDevtools, keepQuestAwake, } from '../targets/android.mjs';
|
|
2
|
-
import { startCdpBridge } from '../targets/cdp-bridge.mjs';
|
|
3
|
+
import { startCdpBridge, } from '../targets/cdp-bridge/bridge.mjs';
|
|
3
4
|
import { untilStopped } from './until-stopped.mjs';
|
|
4
5
|
import { integerOption, parseOptions, text } from './args.mjs';
|
|
5
6
|
const USAGE = 'recovery-probe android [--list] [--serial SERIAL] [--package NAME] [--port N] [--duration MS] [--keep-awake] [--adb PATH]';
|
|
@@ -14,7 +15,6 @@ while the display sleeps or a system dialog is in front; the command warns when
|
|
|
14
15
|
sees either. On a Meta Quest, --keep-awake keeps the display awake and pauses the
|
|
15
16
|
Guardian boundary until the forward stops, so nobody has to wear the headset.
|
|
16
17
|
See docs/android.md.`;
|
|
17
|
-
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
18
18
|
function parseArgs(args) {
|
|
19
19
|
const { values } = parseOptions(args, {
|
|
20
20
|
list: { type: 'boolean' },
|
|
@@ -42,35 +42,58 @@ export async function androidMain(args) {
|
|
|
42
42
|
return;
|
|
43
43
|
}
|
|
44
44
|
const options = parseArgs(args);
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
throw Error(devices.length
|
|
50
|
-
? `Several devices are connected (${devices.join(', ')}); choose one with --serial`
|
|
51
|
-
: 'No device is connected over adb; enable USB debugging and check adb devices');
|
|
52
|
-
serial = devices[0];
|
|
53
|
-
}
|
|
54
|
-
const run = adbRunner({ adb: options.adb, serial });
|
|
45
|
+
const run = adbRunner({
|
|
46
|
+
adb: options.adb,
|
|
47
|
+
serial: await deviceSerial(options),
|
|
48
|
+
});
|
|
55
49
|
const targets = await androidDevtoolsTargets(run);
|
|
56
50
|
if (options.list) {
|
|
57
|
-
console.log(targets.length
|
|
58
|
-
? targets.map(describe).join('\n')
|
|
59
|
-
: 'Nothing to inspect: no app with WebView debugging enabled is running.');
|
|
51
|
+
console.log(targets.length ? targets.map(describe).join('\n') : NOTHING);
|
|
60
52
|
return;
|
|
61
53
|
}
|
|
62
|
-
const
|
|
63
|
-
|
|
54
|
+
const target = chosenTarget(targets, options.package);
|
|
55
|
+
if (options.keepAwake && !(await androidDisplayState(run)).quest)
|
|
56
|
+
throw Error('--keep-awake works on Meta Quest headsets only');
|
|
57
|
+
await forwardUntilStopped(run, target, options);
|
|
58
|
+
}
|
|
59
|
+
const NOTHING = 'Nothing to inspect: no app with WebView debugging enabled is running.';
|
|
60
|
+
/** The serial given, or of the one connected device. */
|
|
61
|
+
async function deviceSerial(options) {
|
|
62
|
+
if (options.serial)
|
|
63
|
+
return options.serial;
|
|
64
|
+
const devices = await androidDevices(adbRunner({ adb: options.adb }));
|
|
65
|
+
if (devices.length !== 1)
|
|
66
|
+
throw Error(devices.length
|
|
67
|
+
? `Several devices are connected (${devices.join(', ')}); choose one with --serial`
|
|
68
|
+
: 'No device is connected over adb; enable USB debugging and check adb devices');
|
|
69
|
+
return devices[0];
|
|
70
|
+
}
|
|
71
|
+
function chosenTarget(targets, name) {
|
|
72
|
+
const matching = name
|
|
73
|
+
? targets.filter((target) => target.package === name)
|
|
64
74
|
: targets;
|
|
65
75
|
if (matching.length !== 1)
|
|
66
76
|
throw Error(matching.length
|
|
67
77
|
? `Several targets can be inspected; choose one with --package:\n${matching.map(describe).join('\n')}`
|
|
68
|
-
:
|
|
69
|
-
? `${
|
|
70
|
-
:
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
78
|
+
: name
|
|
79
|
+
? `${name} has no WebView to inspect; is it running with WebView debugging enabled?`
|
|
80
|
+
: NOTHING);
|
|
81
|
+
return matching[0];
|
|
82
|
+
}
|
|
83
|
+
function printForward(target, url, display, awake) {
|
|
84
|
+
console.log(`Android ${describe(target).trim()} on ${url}
|
|
85
|
+
|
|
86
|
+
Use it like a desktop debugging endpoint:
|
|
87
|
+
recovery-probe windows --cdp ${url}
|
|
88
|
+
"cdp": "${url}" in a check or observe config
|
|
89
|
+
|
|
90
|
+
Keep the app on screen while a check runs. Press Ctrl+C to remove the forward.`);
|
|
91
|
+
if (awake)
|
|
92
|
+
console.log('Keeping the Quest display awake and the Guardian boundary paused until the forward stops.');
|
|
93
|
+
for (const problem of display ? displayProblems(display) : [])
|
|
94
|
+
console.log(`Warning: ${problem} ${display?.quest && !awake ? 'Wear the headset, or use --keep-awake.' : 'Wake the device and bring the app to the front.'}`);
|
|
95
|
+
}
|
|
96
|
+
async function forwardUntilStopped(run, target, options) {
|
|
74
97
|
const forward = await forwardAndroidDevtools(run, target.socket);
|
|
75
98
|
let bridge;
|
|
76
99
|
let awake;
|
|
@@ -84,17 +107,7 @@ export async function androidMain(args) {
|
|
|
84
107
|
await sleep(3000);
|
|
85
108
|
}
|
|
86
109
|
const display = await androidDisplayState(run).catch(() => undefined);
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
Use it like a desktop debugging endpoint:
|
|
90
|
-
recovery-probe desktop --cdp ${bridge.url} --list
|
|
91
|
-
"cdp": "${bridge.url}" in an observe or desktop config
|
|
92
|
-
|
|
93
|
-
Keep the app on screen while a check runs. Press Ctrl+C to remove the forward.`);
|
|
94
|
-
if (awake)
|
|
95
|
-
console.log('Keeping the Quest display awake and the Guardian boundary paused until the forward stops.');
|
|
96
|
-
for (const problem of display ? displayProblems(display) : [])
|
|
97
|
-
console.log(`Warning: ${problem} ${display?.quest && !awake ? 'Wear the headset, or use --keep-awake.' : 'Wake the device and bring the app to the front.'}`);
|
|
110
|
+
printForward(target, bridge.url, display, awake);
|
|
98
111
|
await untilStopped(options.duration);
|
|
99
112
|
}
|
|
100
113
|
finally {
|
package/dist/cli/check.mjs
CHANGED
|
@@ -1,16 +1,15 @@
|
|
|
1
|
-
import { writeFile } from 'node:fs/promises';
|
|
2
1
|
import { dirname, join, resolve } from 'node:path';
|
|
3
2
|
import { connectDesktop, selectDesktopPage } from '../targets/cdp.mjs';
|
|
4
3
|
import { prepareVisibility } from '../targets/visibility.mjs';
|
|
5
4
|
import { reportFolder } from '../reports/folder.mjs';
|
|
6
|
-
import { writeDesktopReport } from '../reports/check.mjs';
|
|
7
|
-
import {
|
|
8
|
-
import { checkDesktop,
|
|
9
|
-
import {
|
|
5
|
+
import { rowNotes, writeDesktopReport, writeIpcReport, } from '../reports/check.mjs';
|
|
6
|
+
import { validateDesktopConfig, } from '../workflows/check/http/config.mjs';
|
|
7
|
+
import { checkDesktop, } from '../workflows/check/http/run.mjs';
|
|
8
|
+
import { validateIpcConfig, } from '../workflows/check/ipc/config.mjs';
|
|
9
|
+
import { checkIpc } from '../workflows/check/ipc/run.mjs';
|
|
10
10
|
import { checkWeb } from '../workflows/web.mjs';
|
|
11
11
|
import { integerOption, readConfig, text, UsageError, validated, } from './args.mjs';
|
|
12
12
|
import { runBrowserCheck } from './runner.mjs';
|
|
13
|
-
import { withEvidence } from '../reports/evidence.mjs';
|
|
14
13
|
export const usage = `recovery-probe check --config FILE [options]
|
|
15
14
|
|
|
16
15
|
Fails one read the way the config says and checks that the screen comes back.
|
|
@@ -51,10 +50,7 @@ export function exitCodeOf(report) {
|
|
|
51
50
|
return 0;
|
|
52
51
|
return report.results.some((row) => row.outcome === 'fail') ? 1 : 2;
|
|
53
52
|
}
|
|
54
|
-
|
|
55
|
-
const openFolder = (values) => reportFolder('check', text(values, 'out'), {
|
|
56
|
-
reuse: values.reuseOut === true,
|
|
57
|
-
});
|
|
53
|
+
const openFolder = (values) => reportFolder('check', text(values, 'out'));
|
|
58
54
|
export async function run(values) {
|
|
59
55
|
const path = text(values, 'config');
|
|
60
56
|
if (!path)
|
|
@@ -64,12 +60,10 @@ export async function run(values) {
|
|
|
64
60
|
return checkIpcRead(config, values);
|
|
65
61
|
if (typeof config.requestPattern === 'string')
|
|
66
62
|
return runBrowserCheck(config, values);
|
|
67
|
-
//
|
|
68
|
-
const attach =
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
config.cdp !== undefined ||
|
|
72
|
-
config.page !== undefined);
|
|
63
|
+
// A debugging port means attach; otherwise it opens Chromium at pageUrl.
|
|
64
|
+
const attach = values.cdp !== undefined ||
|
|
65
|
+
config.cdp !== undefined ||
|
|
66
|
+
config.page !== undefined;
|
|
73
67
|
return attach
|
|
74
68
|
? checkAttached(config, values)
|
|
75
69
|
: checkLaunched(config, path, values);
|
|
@@ -90,8 +84,11 @@ function finish(report, directory, values) {
|
|
|
90
84
|
console.log(JSON.stringify(report, null, 2));
|
|
91
85
|
return;
|
|
92
86
|
}
|
|
93
|
-
for (const row of report.results)
|
|
87
|
+
for (const row of report.results) {
|
|
94
88
|
console.log(`${row.outcome.toUpperCase().padEnd(12)} ${row.kind}: ${row.code} (injected ${row.applied}, later successful responses ${row.successfulResponsesAfterFault})`);
|
|
89
|
+
for (const note of rowNotes(row))
|
|
90
|
+
console.log(`${' '.repeat(13)}${note}`);
|
|
91
|
+
}
|
|
95
92
|
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')}`);
|
|
96
93
|
}
|
|
97
94
|
async function checkAttached(raw, values) {
|
|
@@ -118,8 +115,6 @@ async function checkAttached(raw, values) {
|
|
|
118
115
|
finally {
|
|
119
116
|
await visibility.revert();
|
|
120
117
|
}
|
|
121
|
-
if (typeof values.mode === 'string')
|
|
122
|
-
report.mode = values.mode;
|
|
123
118
|
await writeDesktopReport(directory, report, {
|
|
124
119
|
...config,
|
|
125
120
|
target: 'desktop',
|
|
@@ -159,24 +154,22 @@ async function checkIpcRead(raw, values) {
|
|
|
159
154
|
}));
|
|
160
155
|
const directory = await openFolder(values);
|
|
161
156
|
const report = await checkIpc(config);
|
|
162
|
-
await
|
|
163
|
-
await writeFile(join(directory, 'report.json'), JSON.stringify(withEvidence(report, { workflow: 'check', transport: 'ipc' }), null, 2), { mode: 0o600 });
|
|
164
|
-
await writeFile(join(directory, 'report.html'), renderTemplate('ipc', {
|
|
165
|
-
heading: report.ok
|
|
166
|
-
? 'Selected IPC experiments completed without findings requiring review'
|
|
167
|
-
: 'IPC recovery needs investigation',
|
|
168
|
-
limitation: report.limitation,
|
|
169
|
-
finalReset: report.finalReset,
|
|
170
|
-
evidence: JSON.stringify(report, null, 2),
|
|
171
|
-
}), { mode: 0o600 });
|
|
157
|
+
await writeIpcReport(directory, report, config);
|
|
172
158
|
process.exitCode = exitCodeOf(report);
|
|
173
|
-
if (values.json)
|
|
159
|
+
if (values.json)
|
|
174
160
|
console.log(JSON.stringify(report, null, 2));
|
|
175
|
-
|
|
176
|
-
|
|
161
|
+
else
|
|
162
|
+
printIpcReport(report, directory);
|
|
163
|
+
}
|
|
164
|
+
function printIpcReport(report, directory) {
|
|
177
165
|
console.log(`Baseline: ${report.baseline?.code ?? report.error ?? 'not established'}`);
|
|
178
|
-
for (const
|
|
166
|
+
for (const note of rowNotes(report.baseline ?? {}))
|
|
167
|
+
console.log(` ${note}`);
|
|
168
|
+
for (const row of report.results) {
|
|
179
169
|
console.log(`${row.outcome.toUpperCase()}: ${row.fault} — ${row.code}; injected=${row.snapshot.injected}; later real successes=${row.snapshot.successfulAfterFault}`);
|
|
170
|
+
for (const note of rowNotes(row))
|
|
171
|
+
console.log(` ${note}`);
|
|
172
|
+
}
|
|
180
173
|
if (report.error)
|
|
181
174
|
console.error(`Check stopped: ${report.error}`);
|
|
182
175
|
if (report.cleanupError)
|
package/dist/cli/compare.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { describeRuns, describeSide } from '../tools/compare/markdown.mjs';
|
|
2
|
+
import { compareReports } from '../tools/compare/run.mjs';
|
|
2
3
|
import { UsageError } from './args.mjs';
|
|
3
4
|
const USAGE = 'recovery-probe compare --before REPORT... --after REPORT... [--before-label TEXT] [--after-label TEXT] [--markdown | --json]';
|
|
4
5
|
const HELP = `${USAGE}
|
|
@@ -16,6 +17,21 @@ const STATUS = {
|
|
|
16
17
|
GONE: 'gone',
|
|
17
18
|
UNVERIFIED: 'not checked to the end',
|
|
18
19
|
};
|
|
20
|
+
/** Reads the option at `i` into `options`; returns the index of the last argument it used. */
|
|
21
|
+
function readOption(args, i, options) {
|
|
22
|
+
const arg = args[i];
|
|
23
|
+
if (arg === '--json' || arg === '--markdown') {
|
|
24
|
+
options.format = arg.slice(2);
|
|
25
|
+
return i;
|
|
26
|
+
}
|
|
27
|
+
if (arg === '--before-label' || arg === '--after-label') {
|
|
28
|
+
if (!args[i + 1] || args[i + 1].startsWith('--'))
|
|
29
|
+
throw new UsageError(`${arg} needs a text, such as main`);
|
|
30
|
+
options.labels[arg.slice(2, -'-label'.length)] = args[i + 1];
|
|
31
|
+
return i + 1;
|
|
32
|
+
}
|
|
33
|
+
throw new UsageError(`Use ${USAGE}`);
|
|
34
|
+
}
|
|
19
35
|
function parseArgs(args) {
|
|
20
36
|
const options = { before: [], after: [], labels: {} };
|
|
21
37
|
let side;
|
|
@@ -23,17 +39,11 @@ function parseArgs(args) {
|
|
|
23
39
|
const arg = args[i];
|
|
24
40
|
if (arg === '--before' || arg === '--after')
|
|
25
41
|
side = arg.slice(2);
|
|
26
|
-
else if (arg
|
|
27
|
-
|
|
42
|
+
else if (arg.startsWith('--')) {
|
|
43
|
+
i = readOption(args, i, options);
|
|
28
44
|
side = undefined;
|
|
29
45
|
}
|
|
30
|
-
else if (
|
|
31
|
-
if (!args[i + 1] || args[i + 1].startsWith('--'))
|
|
32
|
-
throw new UsageError(`${arg} needs a text, such as main`);
|
|
33
|
-
options.labels[arg.slice(2, -'-label'.length)] = args[++i];
|
|
34
|
-
side = undefined;
|
|
35
|
-
}
|
|
36
|
-
else if (arg.startsWith('--') || !side)
|
|
46
|
+
else if (!side)
|
|
37
47
|
throw new UsageError(`Use ${USAGE}`);
|
|
38
48
|
else
|
|
39
49
|
options[side].push(arg);
|
|
@@ -42,21 +52,32 @@ function parseArgs(args) {
|
|
|
42
52
|
throw new UsageError(`Give reports on both sides: ${USAGE}`);
|
|
43
53
|
return options;
|
|
44
54
|
}
|
|
45
|
-
function
|
|
46
|
-
|
|
47
|
-
console.log(`Recovery Probe comparison${comparison.mode ? `: ${comparison.mode}` : ''}${comparison.target ? `, ${comparison.target}` : ''}`);
|
|
48
|
-
console.log(` ${labels.before}: ${describeRuns(comparison.before)}`);
|
|
49
|
-
console.log(` ${labels.after}: ${describeRuns(comparison.after)}`);
|
|
50
|
-
if (comparison.changes.length)
|
|
55
|
+
function printChanges({ changes, labels }) {
|
|
56
|
+
if (changes.length)
|
|
51
57
|
console.log('');
|
|
52
|
-
for (const change of
|
|
58
|
+
for (const change of changes) {
|
|
53
59
|
const problem = `${change.code}${change.scope ? ` (${change.scope})` : ''}`;
|
|
54
60
|
console.log(` ${STATUS[change.status].padEnd(22)} ${problem.padEnd(36)} ${change.severity === 'defect' ? 'suspected defect' : 'lead'}`);
|
|
55
61
|
console.log(` ${''.padEnd(22)} ${labels.before}: ${describeSide(change.before)}; ${labels.after}: ${describeSide(change.after)}`);
|
|
56
62
|
}
|
|
63
|
+
}
|
|
64
|
+
function printText(comparison) {
|
|
65
|
+
const { labels } = comparison;
|
|
66
|
+
console.log(`Recovery Probe comparison${comparison.mode ? `: ${comparison.mode}` : ''}${comparison.target ? `, ${comparison.target}` : ''}`);
|
|
67
|
+
console.log(` ${labels.before}: ${describeRuns(comparison.before)}`);
|
|
68
|
+
console.log(` ${labels.after}: ${describeRuns(comparison.after)}`);
|
|
69
|
+
printChanges(comparison);
|
|
57
70
|
const { outcomes } = comparison;
|
|
58
71
|
if (outcomes.before.length || outcomes.after.length)
|
|
59
72
|
console.log(`\n Other outcomes: ${labels.before} ${outcomes.before.join(', ') || 'none'}; ${labels.after} ${outcomes.after.join(', ') || 'none'}`);
|
|
73
|
+
printGaps(comparison);
|
|
74
|
+
console.log(`\n${comparison.verdict}: ${comparison.summary}`);
|
|
75
|
+
if (comparison.limitation)
|
|
76
|
+
console.log(`Covers only this check. ${comparison.limitation}`);
|
|
77
|
+
}
|
|
78
|
+
/** The runs that stopped early or left something unchecked, and why. */
|
|
79
|
+
function printGaps(comparison) {
|
|
80
|
+
const { labels } = comparison;
|
|
60
81
|
const sides = [
|
|
61
82
|
[labels.before, comparison.before],
|
|
62
83
|
[labels.after, comparison.after],
|
|
@@ -65,9 +86,6 @@ function printText(comparison) {
|
|
|
65
86
|
for (const run of runs)
|
|
66
87
|
if (run.gaps.length)
|
|
67
88
|
console.log(`\n ${label} ${run.complete ? 'partial' : 'incomplete'}, ${run.path}:\n ${run.gaps.join('\n ')}`);
|
|
68
|
-
console.log(`\n${comparison.verdict}: ${comparison.summary}`);
|
|
69
|
-
if (comparison.limitation)
|
|
70
|
-
console.log(`Covers only this check. ${comparison.limitation}`);
|
|
71
89
|
}
|
|
72
90
|
export async function compareMain(args) {
|
|
73
91
|
if (args.includes('--help')) {
|