recovery-probe 0.5.0 → 0.6.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 +96 -0
- package/CONTRIBUTING.md +24 -7
- package/README.md +79 -95
- package/dist/cli/action.d.mts +20 -0
- package/dist/cli/action.mjs +57 -0
- package/dist/cli/android.mjs +21 -26
- package/dist/cli/args.d.mts +18 -0
- package/dist/cli/args.mjs +63 -0
- package/dist/cli/check.d.mts +41 -0
- package/dist/cli/check.mjs +185 -0
- package/dist/cli/compare.mjs +5 -4
- package/dist/cli/core-demo.mjs +2 -1
- package/dist/cli/demo.d.mts +11 -0
- package/dist/cli/demo.mjs +15 -0
- package/dist/cli/discover.d.mts +29 -0
- package/dist/cli/discover.mjs +92 -0
- package/dist/cli/doctor.d.mts +1 -0
- package/dist/cli/doctor.mjs +41 -0
- package/dist/cli/init.d.mts +1 -0
- package/dist/cli/init.mjs +95 -0
- package/dist/cli/legacy.d.mts +16 -0
- package/dist/cli/legacy.mjs +117 -0
- package/dist/cli/login.d.mts +11 -0
- package/dist/cli/login.mjs +40 -0
- package/dist/cli/main.mjs +167 -203
- package/dist/cli/mcp.mjs +7 -7
- package/dist/cli/net.mjs +16 -23
- package/dist/cli/observe.mjs +39 -67
- package/dist/cli/reads.d.mts +29 -0
- package/dist/cli/reads.mjs +95 -0
- package/dist/cli/refresh.mjs +32 -52
- package/dist/cli/repair.mjs +14 -17
- package/dist/cli/runner.d.mts +24 -0
- package/dist/cli/runner.mjs +105 -0
- package/dist/cli/start.mjs +6 -18
- package/dist/cli/suspects.mjs +13 -19
- package/dist/cli/terminal.d.mts +5 -0
- package/dist/cli/terminal.mjs +19 -0
- package/dist/cli/verify.d.mts +1 -0
- package/dist/cli/verify.mjs +58 -0
- package/dist/cli/watch.mjs +19 -33
- package/dist/cli/windows.d.mts +11 -0
- package/dist/cli/windows.mjs +35 -0
- package/dist/core/faults.d.mts +9 -0
- package/dist/core/faults.mjs +19 -0
- package/dist/core/package.d.mts +3 -0
- package/dist/core/package.mjs +6 -0
- package/dist/{ipc-observation.d.mts → core/screen.d.mts} +5 -2
- package/dist/{ipc-observation.mjs → core/screen.mjs} +5 -1
- package/dist/core/urls.d.mts +1 -0
- package/dist/core/urls.mjs +8 -0
- package/dist/desktop.d.mts +4 -73
- package/dist/desktop.mjs +4 -422
- package/dist/fetch-fault.d.mts +2 -21
- package/dist/fetch-fault.mjs +1 -84
- package/dist/index.d.mts +6 -49
- package/dist/index.mjs +4 -240
- package/dist/ipc-inspector.d.mts +1 -19
- package/dist/ipc-inspector.mjs +1 -144
- package/dist/ipc-probe.cjs +13 -2
- package/dist/ipc-probe.d.cts +7 -0
- package/dist/net-fault.d.mts +1 -80
- package/dist/net-fault.mjs +1 -307
- package/dist/{action-report.d.mts → reports/action.d.mts} +1 -1
- package/dist/{action-report.mjs → reports/action.mjs} +3 -2
- package/dist/{desktop-report.d.mts → reports/check.d.mts} +1 -1
- package/dist/{desktop-report.mjs → reports/check.mjs} +3 -2
- package/dist/reports/discovery.d.mts +23 -0
- package/dist/{discovery-report.mjs → reports/discovery.mjs} +12 -2
- package/dist/reports/evidence.d.mts +48 -0
- package/dist/reports/evidence.mjs +169 -0
- package/dist/reports/folder.d.mts +8 -0
- package/dist/reports/folder.mjs +22 -0
- package/dist/{report-template.d.mts → reports/template.d.mts} +1 -1
- package/dist/{report-template.mjs → reports/template.mjs} +2 -2
- package/dist/{report-templates → reports/templates}/discovery.html +8 -0
- package/dist/targets/browser.d.mts +13 -0
- package/dist/targets/browser.mjs +25 -0
- package/dist/targets/cdp.d.mts +7 -0
- package/dist/targets/cdp.mjs +45 -0
- package/dist/targets/ipc-window.d.mts +11 -0
- package/dist/targets/ipc-window.mjs +17 -0
- package/dist/{visibility.d.mts → targets/visibility.d.mts} +1 -1
- package/dist/{compare.d.mts → tools/compare.d.mts} +5 -21
- package/dist/{compare.mjs → tools/compare.mjs} +17 -138
- package/dist/tools/doctor.d.mts +33 -0
- package/dist/tools/doctor.mjs +183 -0
- package/dist/{guided-start.d.mts → tools/guided-start.d.mts} +6 -1
- package/dist/{guided-start.mjs → tools/guided-start.mjs} +20 -3
- package/dist/tools/init.d.mts +38 -0
- package/dist/tools/init.mjs +24 -0
- package/dist/tools/mcp/tools.d.mts +5 -0
- package/dist/{mcp-tools.mjs → tools/mcp/tools.mjs} +84 -12
- package/dist/{repair.d.mts → tools/repair/run.d.mts} +3 -3
- package/dist/{repair.mjs → tools/repair/run.mjs} +5 -4
- package/dist/{suspects.d.mts → tools/suspects.d.mts} +11 -2
- package/dist/{suspects.mjs → tools/suspects.mjs} +62 -13
- package/dist/tools/verify.d.mts +63 -0
- package/dist/tools/verify.mjs +185 -0
- package/dist/{watch.d.mts → tools/watch.d.mts} +12 -2
- package/dist/{watch.mjs → tools/watch.mjs} +42 -29
- package/dist/transports/fetch.d.mts +21 -0
- package/dist/transports/fetch.mjs +80 -0
- package/dist/{http-observer.d.mts → transports/http/observer.d.mts} +4 -2
- package/dist/{http-observer.mjs → transports/http/observer.mjs} +10 -13
- package/dist/transports/http/reads.d.mts +2 -0
- package/dist/transports/http/reads.mjs +13 -0
- package/dist/transports/http/route.d.mts +24 -0
- package/dist/transports/http/route.mjs +117 -0
- package/dist/{ipc-control.d.mts → transports/ipc/control.d.mts} +2 -2
- package/dist/transports/ipc/inspector.d.mts +19 -0
- package/dist/transports/ipc/inspector.mjs +144 -0
- package/dist/transports/net.d.mts +80 -0
- package/dist/transports/net.mjs +307 -0
- package/dist/transports/session.d.mts +52 -0
- package/dist/{refresh-adapters.mjs → transports/session.mjs} +20 -10
- package/dist/web.d.mts +2 -21
- package/dist/web.mjs +2 -46
- package/dist/{ipc-action.d.mts → workflows/action.d.mts} +7 -7
- package/dist/{ipc-action.mjs → workflows/action.mjs} +13 -17
- package/dist/workflows/check/browser.d.mts +21 -0
- package/dist/workflows/check/browser.mjs +104 -0
- package/dist/workflows/check/http.d.mts +51 -0
- package/dist/workflows/check/http.mjs +270 -0
- package/dist/{ipc-check.d.mts → workflows/check/ipc.d.mts} +3 -3
- package/dist/{ipc-check.mjs → workflows/check/ipc.mjs} +8 -12
- package/dist/workflows/discover/experiment.d.mts +59 -0
- package/dist/{discovery-control.mjs → workflows/discover/experiment.mjs} +30 -1
- package/dist/workflows/discover/http.d.mts +41 -0
- package/dist/workflows/discover/http.mjs +113 -0
- package/dist/workflows/discover/ipc.d.mts +41 -0
- package/dist/workflows/discover/ipc.mjs +125 -0
- package/dist/workflows/discover/run.d.mts +153 -0
- package/dist/workflows/discover/run.mjs +291 -0
- package/dist/workflows/discover/screenshots.d.mts +10 -0
- package/dist/workflows/discover/screenshots.mjs +20 -0
- package/dist/{file-evidence.d.mts → workflows/observe/files.d.mts} +1 -1
- package/dist/{observation-kit.mjs → workflows/observe/kit.mjs} +18 -0
- package/dist/{observe-network.d.mts → workflows/observe/network.d.mts} +3 -3
- package/dist/{observation-report.d.mts → workflows/observe/report.d.mts} +15 -2
- package/dist/{observation-report.mjs → workflows/observe/report.mjs} +12 -5
- package/dist/{observe.d.mts → workflows/observe/run.d.mts} +15 -9
- package/dist/{observe.mjs → workflows/observe/run.mjs} +119 -17
- package/dist/{observe-steps.d.mts → workflows/observe/steps.d.mts} +2 -2
- package/dist/{observe-steps.mjs → workflows/observe/steps.mjs} +3 -3
- package/dist/workflows/reads.d.mts +16 -0
- package/dist/workflows/reads.mjs +46 -0
- package/dist/{refresh.d.mts → workflows/refresh.d.mts} +1 -1
- package/dist/{refresh.mjs → workflows/refresh.mjs} +3 -4
- package/dist/workflows/web.d.mts +12 -0
- package/dist/workflows/web.mjs +23 -0
- package/docs/android.md +3 -3
- package/docs/api.md +1 -1
- package/docs/ci.md +1 -1
- package/docs/compare.md +35 -6
- package/docs/desktop.md +18 -62
- package/docs/discovery.md +101 -0
- package/docs/ipc.md +13 -72
- package/docs/mcp.md +28 -7
- package/docs/observe.md +30 -16
- package/docs/refresh.md +3 -3
- package/docs/repair.md +5 -5
- package/docs/runner.md +5 -2
- package/docs/start.md +5 -13
- package/docs/suspects.md +1 -1
- package/docs/verify.md +60 -0
- package/docs/watch.md +3 -3
- package/package.json +14 -34
- package/dist/cli/attach.d.mts +0 -1
- package/dist/cli/attach.mjs +0 -85
- package/dist/cli/desktop.d.mts +0 -1
- package/dist/cli/desktop.mjs +0 -124
- package/dist/cli/ipc.d.mts +0 -1
- package/dist/cli/ipc.mjs +0 -120
- package/dist/cli/web.d.mts +0 -1
- package/dist/cli/web.mjs +0 -107
- package/dist/discovery-control.d.mts +0 -16
- package/dist/discovery-report.d.mts +0 -40
- package/dist/http-discover.d.mts +0 -111
- package/dist/http-discover.mjs +0 -323
- package/dist/ipc-discover.d.mts +0 -119
- package/dist/ipc-discover.mjs +0 -371
- package/dist/mcp-tools.d.mts +0 -5
- package/dist/refresh-adapters.d.mts +0 -40
- /package/dist/{report-templates → reports/templates}/action.html +0 -0
- /package/dist/{report-templates → reports/templates}/desktop.html +0 -0
- /package/dist/{report-templates → reports/templates}/ipc.html +0 -0
- /package/dist/{report-templates → reports/templates}/observation.html +0 -0
- /package/dist/{report-templates → reports/templates}/refresh.html +0 -0
- /package/dist/{android.d.mts → targets/android.d.mts} +0 -0
- /package/dist/{android.mjs → targets/android.mjs} +0 -0
- /package/dist/{cdp-bridge.d.mts → targets/cdp-bridge.d.mts} +0 -0
- /package/dist/{cdp-bridge.mjs → targets/cdp-bridge.mjs} +0 -0
- /package/dist/{visibility.mjs → targets/visibility.mjs} +0 -0
- /package/dist/{mcp-server.d.mts → tools/mcp/server.d.mts} +0 -0
- /package/dist/{mcp-server.mjs → tools/mcp/server.mjs} +0 -0
- /package/dist/{pick-marker.d.mts → tools/pick-marker.d.mts} +0 -0
- /package/dist/{pick-marker.mjs → tools/pick-marker.mjs} +0 -0
- /package/dist/{repair-process.d.mts → tools/repair/process.d.mts} +0 -0
- /package/dist/{repair-process.mjs → tools/repair/process.mjs} +0 -0
- /package/dist/{repair-provider.d.mts → tools/repair/provider.d.mts} +0 -0
- /package/dist/{repair-provider.mjs → tools/repair/provider.mjs} +0 -0
- /package/dist/{ipc-control.mjs → transports/ipc/control.mjs} +0 -0
- /package/dist/{file-evidence.mjs → workflows/observe/files.mjs} +0 -0
- /package/dist/{observation-kit.d.mts → workflows/observe/kit.d.mts} +0 -0
- /package/dist/{observe-network.mjs → workflows/observe/network.mjs} +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,102 @@ 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.6.0 (2026-10-23)
|
|
8
|
+
|
|
9
|
+
Promotes previews 1–13 to the stable npm `latest` channel without additional runtime changes.
|
|
10
|
+
|
|
11
|
+
- Add `init` for guided first checks and `doctor` for setup diagnostics, including IPC hook channels.
|
|
12
|
+
- Unify CLI commands around `check`, `discover`, `action`, `windows`, `reads`, `login` and `demo`, with consistent option parsing and JSON output where supported.
|
|
13
|
+
- Add `verify` and the MCP `verify_change` tool to compare checks before and after a change and scan changed lines for suspects.
|
|
14
|
+
- Add row-state markers and `UNEXPECTED_ROW_STATE` observations, plus discovery experiments that fail later calls separately and optional screenshots.
|
|
15
|
+
- Share discovery, read sessions, HTTP fault handling, target identification and report-folder creation across workflows. Reports expose one evidence shape for comparison, watching and verification, while older reports remain readable.
|
|
16
|
+
- Organize source into tested architectural layers, consolidate documentation and validate documentation links.
|
|
17
|
+
|
|
18
|
+
Upgrading from 0.5.0: public package exports and the IPC hook path are unchanged; restart the development app so its hook matches the CLI. Old CLI spellings remain supported until 1.0 and retain exit code 2 for errors. New commands use 0 for passed, 1 for failed, 2 for inconclusive or needs review, 3 for usage/config errors and 4 when a run could not start. Update scripts that interpret these codes. For `demo` and JSON-runner `check`, `--out` names a new report folder; old spellings retain file output. Unsupported imports into internal `dist/` files may break after the source reorganization. Experimental workflows remain experimental.
|
|
19
|
+
|
|
20
|
+
## 0.6.0-preview.13 (2026-10-23)
|
|
21
|
+
|
|
22
|
+
- One fault layer. The fault kinds are listed once (`FAULT_KINDS` in `core/faults`), and one function answers a request with a fault for `withFault`, the HTTP observer and the HTTP check. The HTTP check fails its read through the same observer as discovery and observation, instead of its own copy of the route handler.
|
|
23
|
+
- A successful read after a fault counts when its response finishes, not when its headers arrive, as in discovery.
|
|
24
|
+
- The IPC check, the HTTP check and the JSON runner stay separate on purpose: they promise different things. The IPC check needs exact call counts and takes its deadline from the measured read; the HTTP check clicks Retry and waits for a ready marker; the runner opens a fresh browser for each fault.
|
|
25
|
+
|
|
26
|
+
## 0.6.0-preview.12 (2026-10-23)
|
|
27
|
+
|
|
28
|
+
- Every `report.json` has an `evidence` block in one shape: workflow, transport, target, problems, outcomes, what the run checked and why parts don't count. `compare`, `watch` and `verify` read it; older reports are read from their other fields as before.
|
|
29
|
+
- `compare` matches runs by workflow and transport instead of the report's label, so a check from `check --cdp` compares with one from the old `web --attach`, and an older refresh report compares with a new one.
|
|
30
|
+
- Discovery, action and refresh findings are told apart by experiment: before, `rejection-1`, `rejection-2` and `rejection-1-call2` all counted as `rejection`, so a problem that moved between them looked unchanged.
|
|
31
|
+
|
|
32
|
+
## 0.6.0-preview.11 (2026-10-23)
|
|
33
|
+
|
|
34
|
+
- One set of commands. `check`, `discover` and `action` read what to do from the config: a `channel` means IPC, an `endpoint` means HTTP, and `check` attaches when given `--cdp` or a config with `cdp` or `page`, otherwise it opens Chromium. `windows`, `reads`, `login` and `demo` replace `--list`, `--discover` without a config, `--login` and `--demo`.
|
|
35
|
+
- The old spellings (`--demo`, `--config`, `desktop`, `web`, `web --attach`, `ipc`) run the new commands with the same options, print one line saying what replaced them, and keep exit code 2 for errors. They work until 1.0.
|
|
36
|
+
- `recovery-probe --help` lists every command with what it does, and `recovery-probe <command> --help` its options. Every command parses its options the same way.
|
|
37
|
+
- Exit codes: 0 passed, 1 a check failed, 2 needs review or inconclusive, 3 wrong usage or config, 4 couldn't run. Before, usage and setup errors exited with 2.
|
|
38
|
+
- `check`, `discover`, `action`, `reads` and `windows` take `--json`. `check` takes `--screenshots` in a browser it opens too.
|
|
39
|
+
- When nothing answers on a debugging port, the error says how to start the app instead of showing Playwright's connection log.
|
|
40
|
+
- `demo --out` and `check --out` with a JSON-runner config name a new folder for report.json, like every other command; the old spellings still write one file.
|
|
41
|
+
|
|
42
|
+
## 0.6.0-preview.10 (2026-10-23)
|
|
43
|
+
|
|
44
|
+
- One function finds the IPC hook's window and proves the debugging port and the hook reach the same one. It replaces five copies in the IPC check, discovery, the action check, observe and refresh, which had different error messages and, in refresh, removed any window challenge instead of only its own.
|
|
45
|
+
- `ipc`, `observe`, `refresh`, `web` and `web --attach` create their report folder the same way: `--out` must be a new folder, its parent folders are created, and without `--out` it's a new `.recovery-probe/<command>-…` folder.
|
|
46
|
+
- `watch`, `verify` and the MCP server still run each check as its own CLI process, on purpose: a hung or crashing check can be stopped without stopping them.
|
|
47
|
+
|
|
48
|
+
## 0.6.0-preview.9 (2026-10-23)
|
|
49
|
+
|
|
50
|
+
- IPC and HTTP discovery run on one engine, built on the same read sessions as refresh. The IPC and HTTP modules only set up their transport.
|
|
51
|
+
- Both now behave the same where they had drifted apart:
|
|
52
|
+
- Over HTTP, a healthy load that doesn't settle stops the run with `BASELINE_NOT_HEALTHY`, as over IPC. `BASELINE_UNSTABLE` means healthy loads ended on different screens, over both, without the extra text IPC added.
|
|
53
|
+
- Over IPC, an `UNSTABLE` finding has low confidence, as over HTTP.
|
|
54
|
+
- HTTP findings and runs have the fields IPC ones had: `observationMs`, advice per classification, `verification`, `recoveryDetectedAt`, `timingNote`, `assessment`, and `uncaughtErrors` in the timeline.
|
|
55
|
+
- The read sessions take `skip`, and the HTTP one keeps the requests its observers saw.
|
|
56
|
+
|
|
57
|
+
## 0.6.0-preview.8 (2026-10-23)
|
|
58
|
+
|
|
59
|
+
- The source is split into layers (core, transports, targets, reports, workflows, tools, cli), and a test keeps each layer from importing the ones above it. `desktop.mts`, which held the HTTP check, CDP attachment and endpoint listing, is now three modules, and `index.mts` no longer holds a check engine. The public imports (`recovery-probe`, `/fetch`, `/net`, `/desktop`, `/web`, `/ipc-inspector`, `/ipc`) and the hook's path are unchanged. Imports of other files inside `dist/` were never supported and now break.
|
|
60
|
+
- Paths to files that ship with the package come from one place, `core/package.mts`.
|
|
61
|
+
- Tests live in `test/unit`, `test/integration`, `test/electron` and `test/package`, and Electron tests share one launcher that stops the whole process tree.
|
|
62
|
+
|
|
63
|
+
## 0.6.0-preview.7 (2026-10-23)
|
|
64
|
+
|
|
65
|
+
- New `recovery-probe init [URL]`. It finds what to test and runs a first check: the guided web check for a URL, the guided desktop check for an app on the debugging port, or IPC discovery when the app has the hook, after asking which channel loads the screen. Running it again repeats the check; `--fresh` sets it up again.
|
|
66
|
+
- New `recovery-probe doctor`. It checks Node.js, Playwright, Chromium, the app on the debugging port and the IPC hook, and prints the fix for anything missing, including the hook code with the path to load it from. `--json` prints the report.
|
|
67
|
+
- The IPC hook's `identify()` returns `channels`, the channels it may fail. `doctor` names the ones the app never registered, which usually means a typo or a hook loaded after the handlers.
|
|
68
|
+
- Agents can run `doctor` through the MCP tool `run_recovery_probe`, and the server tells them to when a check can't attach.
|
|
69
|
+
|
|
70
|
+
## 0.6.0-preview.6 (2026-10-23)
|
|
71
|
+
|
|
72
|
+
- A shorter README, and MCP setup for any agent instead of one client.
|
|
73
|
+
- Discovery over IPC and HTTP is described once, in `docs/discovery.md`. The docs describe current behaviour; version history stays in this changelog.
|
|
74
|
+
- The package ships every doc, including `docs/verify.md`, which was missing.
|
|
75
|
+
- A docs test checks that relative links and headings resolve.
|
|
76
|
+
|
|
77
|
+
## 0.6.0-preview.5 (2026-10-23)
|
|
78
|
+
|
|
79
|
+
- IPC and HTTP discovery count how often each healthy load reads the target. When every load reads it the same number of times, they also fail the 2nd, 3rd and 4th call of a load on its own, as findings such as `rejection-1-call2` with a `call` field. `readiness.callsGap` says when later calls were not failed on their own. IPC discovery needs the hook from this version for these experiments; restart the app after upgrading.
|
|
80
|
+
- `ipc --discover --screenshots` and `web --attach --discover --screenshots` save the screen after the first baseline and each faulted run, and show the screenshots in `report.html`.
|
|
81
|
+
- The IPC hook's `begin` takes `skip`, the calls on the channel that pass before the first fault.
|
|
82
|
+
|
|
83
|
+
## 0.6.0-preview.4 (2026-10-23)
|
|
84
|
+
|
|
85
|
+
- A click on a `<label>` records its action once. The browser also clicks the label's control, which counted as a second click on the same action.
|
|
86
|
+
|
|
87
|
+
## 0.6.0-preview.3 (2026-10-23)
|
|
88
|
+
|
|
89
|
+
- New `recovery-probe verify` and MCP tool `verify_change`. A plan lists the checks that prove a change; `--baseline` runs them before it, and `verify` runs them again, compares the runs and scans the lines changed since the base for suspects. The change is VERIFIED only when every check improved or stayed clean with complete runs on both sides and no changed line is a suspect.
|
|
90
|
+
- `scanForSuspects` takes `changedLinesOnly`, which leaves out suspects on lines the change did not touch.
|
|
91
|
+
- File names from `suspects --changed-since` keep the spelling of the working directory, such as a Windows short name, instead of appearing as `../../..` paths.
|
|
92
|
+
|
|
93
|
+
## 0.6.0-preview.2 (2026-10-23)
|
|
94
|
+
|
|
95
|
+
- `UNEXPECTED_ROW_STATE` ends a stretch when the row leaves the region, so a row that comes back gets a new finding instead of extending the old one.
|
|
96
|
+
- Marker labels cannot be `none` or `other`, the states rows get without a marker or allowlisted text.
|
|
97
|
+
|
|
98
|
+
## 0.6.0-preview.1 (2026-10-23)
|
|
99
|
+
|
|
100
|
+
- Observation rows can take their state from a marker element, such as an icon, with `rows.markers`. `state` and `states` are optional when markers are set.
|
|
101
|
+
- `rows.unexpected` lists states a region must not show. A row shown in one of them is reported as `UNEXPECTED_ROW_STATE`, once per stretch of samples, with the samples that showed it and the action before it.
|
|
102
|
+
|
|
7
103
|
## 0.5.0 (2026-10-21)
|
|
8
104
|
|
|
9
105
|
Promotes previews 1–22 to the stable npm `latest` channel. The preview entries below retain the detailed history.
|
package/CONTRIBUTING.md
CHANGED
|
@@ -16,18 +16,35 @@ npm ci
|
|
|
16
16
|
npm run format:check
|
|
17
17
|
npm run lint
|
|
18
18
|
npm run typecheck
|
|
19
|
-
npm test
|
|
20
|
-
npm run test:package
|
|
19
|
+
npm test # unit tests, no browser
|
|
20
|
+
npm run test:package # installs the packed package like a user would
|
|
21
21
|
npx playwright install chromium
|
|
22
|
-
npm run test:
|
|
23
|
-
npm
|
|
24
|
-
|
|
25
|
-
npm run test:repair:electron
|
|
22
|
+
npm run test:integration # real Chromium
|
|
23
|
+
npm install --no-save --package-lock=false electron@44.5.1
|
|
24
|
+
npm run test:electron # real Electron
|
|
26
25
|
```
|
|
27
26
|
|
|
27
|
+
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
|
+
|
|
28
29
|
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
30
|
|
|
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/
|
|
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 `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/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.
|
|
32
|
+
|
|
33
|
+
## Layout
|
|
34
|
+
|
|
35
|
+
`src/` is split into layers, and each layer imports only itself and the layers below it:
|
|
36
|
+
|
|
37
|
+
| Folder | Holds |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| `core` | Fault kinds, URL identity, reading and comparing the screen, package paths |
|
|
40
|
+
| `transports` | Failing reads: Playwright routes, the fetch wrapper, the HTTPS proxy, the IPC inspector and control |
|
|
41
|
+
| `targets` | Reaching the app: launching Chromium, attaching over CDP, window visibility, Android |
|
|
42
|
+
| `reports` | Report templates and the writers for check, discovery and action reports |
|
|
43
|
+
| `workflows` | The experiments: checks, discovery, refresh, observation, actions |
|
|
44
|
+
| `tools` | What's built on them: init, doctor, guided start, suspects, compare, watch, verify, MCP, repair |
|
|
45
|
+
| `cli` | Argument parsing and output |
|
|
46
|
+
|
|
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 hook 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.
|
|
31
48
|
|
|
32
49
|
## Install an unpublished source preview
|
|
33
50
|
|
package/README.md
CHANGED
|
@@ -1,141 +1,125 @@
|
|
|
1
1
|
# Recovery Probe
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
See what your app shows when a data request fails.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
9
|
-
Installing the package does not add recovery behavior to your application.
|
|
5
|
+
Most apps don't crash when a read fails. The list goes empty, the spinner never stops, or the screen keeps showing old data. There's no error and nothing in the logs, so it ships. Recovery Probe fails those reads on purpose, runs the same screen healthy for comparison, and tells you what changed.
|
|
10
6
|
|
|
11
7
|
[](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
|
|
12
8
|
[](https://www.npmjs.com/package/recovery-probe)
|
|
13
9
|
[](LICENSE)
|
|
14
10
|
|
|
15
|
-
|
|
11
|
+

|
|
16
12
|
|
|
17
|
-
|
|
13
|
+
## Try it
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
You need Node.js 22 or newer.
|
|
20
16
|
|
|
21
17
|
```bash
|
|
22
|
-
|
|
23
|
-
npm install --save-dev --save-exact recovery-probe@0.5.0 playwright@1.62.1
|
|
18
|
+
npm install --save-dev recovery-probe playwright
|
|
24
19
|
npx playwright install chromium
|
|
25
|
-
npx recovery-probe
|
|
20
|
+
npx recovery-probe demo
|
|
26
21
|
```
|
|
27
22
|
|
|
28
|
-
|
|
23
|
+
The demo runs two versions of a small app. Both load fine. Only the fixed one survives a 503, a dropped connection and a broken JSON response.
|
|
29
24
|
|
|
30
|
-
##
|
|
25
|
+
## Check your own app
|
|
31
26
|
|
|
32
|
-
|
|
33
|
-
| --- | --- | --- |
|
|
34
|
-
| Set up a first recovery check interactively | `recovery-probe start web URL` or `start desktop` | [Guided start](docs/start.md) |
|
|
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) |
|
|
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) |
|
|
45
|
-
| Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
|
|
46
|
-
| Watch cached content and row states after user actions, without faults | `recovery-probe observe --config FILE [--steps FILE]` | [Observation](docs/observe.md) |
|
|
47
|
-
| Run a repeatable recovery check in CI | `npm run test:ci-example` (source checkout) | [CI example](docs/ci.md) |
|
|
48
|
-
| Assert recovery inside your own tests | `withFault` or `createFaultFetch` | [API](docs/api.md) |
|
|
49
|
-
| Propose and verify a source change | Opt-in repair workflow | [Repair setup and limits](docs/repair.md) |
|
|
50
|
-
|
|
51
|
-
`desktop` also attaches to an existing Chromium-based web browser.
|
|
52
|
-
|
|
53
|
-
**Where it works:**
|
|
54
|
-
|
|
55
|
-
- **Web apps** in Chromium-based browsers: launch a test browser or attach to an authorized development one.
|
|
56
|
-
- **Electron apps that read over HTTP** in the renderer: attach through a loopback debugging endpoint.
|
|
57
|
-
- **Electron apps that read over IPC**: add a development-only hook to the main process.
|
|
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
|
|
65
|
-
|
|
66
|
-
`recovery-probe mcp` serves the checks as MCP tools, so an agent can verify its own error handling instead of assuming it:
|
|
27
|
+
**Web app.** Start it, then run:
|
|
67
28
|
|
|
68
29
|
```bash
|
|
69
|
-
|
|
30
|
+
npx recovery-probe init http://localhost:3000
|
|
70
31
|
```
|
|
71
32
|
|
|
72
|
-
|
|
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.
|
|
33
|
+
A browser opens. Sign in, go to the screen you care about, and click something that only shows up once its data has loaded. Recovery Probe finds the request behind it, fails it three ways, and tells you whether the data came back.
|
|
79
34
|
|
|
80
|
-
|
|
35
|
+
**Electron app.** Start it with `--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222`, then run `npx recovery-probe init`.
|
|
81
36
|
|
|
82
|
-
|
|
37
|
+
**Electron app that loads data over IPC.** Load the small development-only hook in the main process. `npx recovery-probe doctor` prints the code and the path to load it from. Restart the app with the inspector on, then run `npx recovery-probe init`: it lists the hook's channels, asks which one loads the screen, and fails it in a few ways.
|
|
83
38
|
|
|
84
|
-
|
|
39
|
+
Each run saves an HTML and JSON report. Run the same command again to repeat the check, or add `--fresh` to set it up again. If something's missing, `npx recovery-probe doctor` says what and how to fix it.
|
|
85
40
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
41
|
+
## More
|
|
42
|
+
|
|
43
|
+
| To | Run | Docs |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
| Fail the read behind a screen without writing assertions | `discover` | [Discovery](docs/discovery.md) |
|
|
46
|
+
| Catch stale screens and rows stuck in an old state, without faults | `observe` | [Observe](docs/observe.md) |
|
|
47
|
+
| See what users get when Save or Send fails | `action` | [Action check](docs/ipc.md#action-check) |
|
|
48
|
+
| Fail an SDK's or a main process's own HTTPS connections | `net` | [Network faults](docs/net.md) |
|
|
49
|
+
| Find code that turns a failed read into "no data" | `suspects` | [Suspects](docs/suspects.md) |
|
|
50
|
+
| Prove a change fixed it | `compare`, `watch`, `verify` | [Compare](docs/compare.md), [Watch](docs/watch.md), [Verify](docs/verify.md) |
|
|
51
|
+
|
|
52
|
+
## Use it from a coding agent
|
|
53
|
+
|
|
54
|
+
`recovery-probe mcp` is an MCP server. Any agent that supports MCP can use it to fail a read and look at the screen before it claims the code handles errors. Most agents take this config:
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"mcpServers": {
|
|
59
|
+
"recovery-probe": { "command": "npx", "args": ["recovery-probe", "mcp"] }
|
|
60
|
+
}
|
|
61
|
+
}
|
|
104
62
|
```
|
|
105
63
|
|
|
106
|
-
|
|
64
|
+
Other config formats and the list of tools are in [MCP](docs/mcp.md).
|
|
65
|
+
|
|
66
|
+
## Use it in your tests
|
|
67
|
+
|
|
68
|
+
`withFault` fails matching requests inside a Playwright test:
|
|
107
69
|
|
|
108
|
-
|
|
70
|
+
```js
|
|
71
|
+
import { test, expect } from '@playwright/test'
|
|
72
|
+
import { withFault } from 'recovery-probe'
|
|
73
|
+
|
|
74
|
+
test('profile recovers after a 503', async ({ page }) => {
|
|
75
|
+
const stats = await withFault(
|
|
76
|
+
page,
|
|
77
|
+
{ match: '**/api/profile', kind: 'http-error', status: 503 },
|
|
78
|
+
async () => {
|
|
79
|
+
await page.goto('http://127.0.0.1:3000/profile')
|
|
80
|
+
await page.getByRole('button', { name: 'Retry' }).click()
|
|
81
|
+
await expect(page.getByTestId('profile-name')).toHaveText('Test User')
|
|
82
|
+
},
|
|
83
|
+
)
|
|
84
|
+
expect(stats.applied).toBe(1)
|
|
85
|
+
})
|
|
86
|
+
```
|
|
109
87
|
|
|
110
|
-
|
|
88
|
+
If nothing matches, `withFault` throws `FAULT_NOT_TRIGGERED` instead of passing. For code that takes a `fetch` function there's `createFaultFetch`. See [API](docs/api.md).
|
|
111
89
|
|
|
112
|
-
|
|
90
|
+
## How it decides
|
|
113
91
|
|
|
114
|
-
|
|
92
|
+
- Every faulted run has a healthy run right before it, on the same screen, and the report compares the two.
|
|
93
|
+
- A result is a pass, a failure or inconclusive. A fault that never fired, an unstable baseline or a path it can't reach is inconclusive, never a pass.
|
|
94
|
+
- Some findings, like `SILENT_EMPTY`, are leads. They tell you where to look, not that the code is wrong.
|
|
95
|
+
- Exit codes: 0 passed, 1 a check failed, 2 needs review or inconclusive, 3 wrong usage or config, 4 couldn't run.
|
|
115
96
|
|
|
116
|
-
##
|
|
97
|
+
## Where it works
|
|
117
98
|
|
|
118
|
-
|
|
99
|
+
- Web apps in Chromium, either launched by Recovery Probe or attached through a local debugging port.
|
|
100
|
+
- Electron apps, over HTTP in the renderer or over IPC with the hook.
|
|
101
|
+
- Native HTTPS clients that use `HTTPS_PROXY`, such as an SDK in the main process. Only whole connections can fail there.
|
|
102
|
+
- Android WebViews, experimental.
|
|
119
103
|
|
|
120
|
-
|
|
104
|
+
It doesn't simulate a whole device going offline, WebSocket drops, token expiry, sleep or slow networks.
|
|
121
105
|
|
|
122
|
-
|
|
106
|
+
## Privacy
|
|
123
107
|
|
|
124
|
-
|
|
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.
|
|
125
109
|
|
|
126
|
-
|
|
110
|
+
Only test apps and accounts you're allowed to, and keep debugging ports on localhost.
|
|
127
111
|
|
|
128
|
-
|
|
112
|
+
## Upgrading from 0.5.0
|
|
129
113
|
|
|
130
|
-
|
|
114
|
+
Restart the development app after upgrading so its IPC hook matches the CLI. Public package imports and the hook's path are unchanged. The old command spellings still work until 1.0, with a migration notice; new commands distinguish usage errors (exit 3) and setup failures (exit 4) from inconclusive results (exit 2). Update CI scripts that interpret exit codes. With the new `demo` and JSON-runner `check` commands, `--out` names a new report folder; their old spellings still write one file. See the [changelog](CHANGELOG.md) for the full migration notes.
|
|
131
115
|
|
|
132
|
-
|
|
116
|
+
## Docs
|
|
133
117
|
|
|
134
|
-
|
|
118
|
+
[Guided start](docs/start.md) · [Desktop and browsers](docs/desktop.md) · [IPC](docs/ipc.md) · [Discovery](docs/discovery.md) · [Observe](docs/observe.md) · [Refresh](docs/refresh.md) · [Network faults](docs/net.md) · [Android](docs/android.md) · [Suspects](docs/suspects.md) · [Compare](docs/compare.md) · [Watch](docs/watch.md) · [Verify](docs/verify.md) · [MCP](docs/mcp.md) · [API](docs/api.md) · [JSON runner](docs/runner.md) · [CI](docs/ci.md) · [Repair](docs/repair.md) · [Changelog](CHANGELOG.md)
|
|
135
119
|
|
|
136
|
-
##
|
|
120
|
+
## Contributing
|
|
137
121
|
|
|
138
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
122
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues as described in [SECURITY.md](SECURITY.md).
|
|
139
123
|
|
|
140
124
|
## License
|
|
141
125
|
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { type Values } from './args.mjs';
|
|
2
|
+
export declare const usage = "recovery-probe action --config FILE [options]\n\nRuns the config's setup steps, then clicks its action while the IPC hook answers\nthe write channel: a simulated success, a simulated failure and a double-click.\nNothing is written. See docs/ipc.md#action-check.\n\nOptions:\n --cdp URL the app's debugging port (default http://127.0.0.1:9222)\n --inspector URL the app's Node inspector (default http://127.0.0.1:9229)\n --out DIR a new folder for the report\n --json print the report as JSON\n\nExit codes: 0 only feedback that differs from success, 2 findings to review or\ninconclusive, 3 wrong usage or config, 4 couldn't run.";
|
|
3
|
+
export declare const options: {
|
|
4
|
+
readonly config: {
|
|
5
|
+
readonly type: "string";
|
|
6
|
+
};
|
|
7
|
+
readonly cdp: {
|
|
8
|
+
readonly type: "string";
|
|
9
|
+
};
|
|
10
|
+
readonly inspector: {
|
|
11
|
+
readonly type: "string";
|
|
12
|
+
};
|
|
13
|
+
readonly out: {
|
|
14
|
+
readonly type: "string";
|
|
15
|
+
};
|
|
16
|
+
readonly json: {
|
|
17
|
+
readonly type: "boolean";
|
|
18
|
+
};
|
|
19
|
+
};
|
|
20
|
+
export declare function run(values: Values): Promise<void>;
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { join } from 'node:path';
|
|
2
|
+
import { reportFolder } from '../reports/folder.mjs';
|
|
3
|
+
import { writeActionReport } from '../reports/action.mjs';
|
|
4
|
+
import { actionConfig, checkAction } from '../workflows/action.mjs';
|
|
5
|
+
import { readConfig, text, UsageError, validated, } from './args.mjs';
|
|
6
|
+
export const usage = `recovery-probe action --config FILE [options]
|
|
7
|
+
|
|
8
|
+
Runs the config's setup steps, then clicks its action while the IPC hook answers
|
|
9
|
+
the write channel: a simulated success, a simulated failure and a double-click.
|
|
10
|
+
Nothing is written. See docs/ipc.md#action-check.
|
|
11
|
+
|
|
12
|
+
Options:
|
|
13
|
+
--cdp URL the app's debugging port (default http://127.0.0.1:9222)
|
|
14
|
+
--inspector URL the app's Node inspector (default http://127.0.0.1:9229)
|
|
15
|
+
--out DIR a new folder for the report
|
|
16
|
+
--json print the report as JSON
|
|
17
|
+
|
|
18
|
+
Exit codes: 0 only feedback that differs from success, 2 findings to review or
|
|
19
|
+
inconclusive, 3 wrong usage or config, 4 couldn't run.`;
|
|
20
|
+
export const options = {
|
|
21
|
+
config: { type: 'string' },
|
|
22
|
+
cdp: { type: 'string' },
|
|
23
|
+
inspector: { type: 'string' },
|
|
24
|
+
out: { type: 'string' },
|
|
25
|
+
json: { type: 'boolean' },
|
|
26
|
+
};
|
|
27
|
+
export async function run(values) {
|
|
28
|
+
const path = text(values, 'config');
|
|
29
|
+
if (!path)
|
|
30
|
+
throw new UsageError('--config is required');
|
|
31
|
+
const raw = await readConfig(path);
|
|
32
|
+
const cdp = text(values, 'cdp');
|
|
33
|
+
const inspector = text(values, 'inspector');
|
|
34
|
+
const config = {
|
|
35
|
+
...raw,
|
|
36
|
+
...(cdp ? { cdp } : {}),
|
|
37
|
+
...(inspector ? { inspector } : {}),
|
|
38
|
+
};
|
|
39
|
+
// Fails fast on a bad config; checkAction validates it again itself.
|
|
40
|
+
validated(() => actionConfig(config));
|
|
41
|
+
const directory = await reportFolder('action', text(values, 'out'));
|
|
42
|
+
const report = await checkAction(config);
|
|
43
|
+
await writeActionReport(directory, report, config);
|
|
44
|
+
// Heuristic findings are leads, not proven failures.
|
|
45
|
+
process.exitCode = report.ok ? 0 : 2;
|
|
46
|
+
if (values.json) {
|
|
47
|
+
console.log(JSON.stringify(report, null, 2));
|
|
48
|
+
return;
|
|
49
|
+
}
|
|
50
|
+
for (const finding of report.findings)
|
|
51
|
+
console.log(`${finding.kind.toUpperCase()}: ${finding.id} — ${finding.classification}`);
|
|
52
|
+
if (report.error)
|
|
53
|
+
console.error(`Action check stopped: ${report.error}`);
|
|
54
|
+
if (report.cleanupError)
|
|
55
|
+
console.error(`Cleanup: ${report.cleanupError}`);
|
|
56
|
+
console.log(`Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}`);
|
|
57
|
+
}
|
package/dist/cli/android.mjs
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
import { adbRunner, androidDevices, androidDevtoolsTargets, androidDisplayState, displayProblems, forwardAndroidDevtools, keepQuestAwake, } from '../android.mjs';
|
|
2
|
-
import { startCdpBridge } from '../cdp-bridge.mjs';
|
|
1
|
+
import { adbRunner, androidDevices, androidDevtoolsTargets, androidDisplayState, displayProblems, forwardAndroidDevtools, keepQuestAwake, } from '../targets/android.mjs';
|
|
2
|
+
import { startCdpBridge } from '../targets/cdp-bridge.mjs';
|
|
3
3
|
import { untilStopped } from './until-stopped.mjs';
|
|
4
|
+
import { integerOption, parseOptions, text } from './args.mjs';
|
|
4
5
|
const USAGE = 'recovery-probe android [--list] [--serial SERIAL] [--package NAME] [--port N] [--duration MS] [--keep-awake] [--adb PATH]';
|
|
5
6
|
const HELP = `${USAGE}
|
|
6
7
|
|
|
@@ -15,30 +16,24 @@ Guardian boundary until the forward stops, so nobody has to wear the headset.
|
|
|
15
16
|
See docs/android.md.`;
|
|
16
17
|
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
17
18
|
function parseArgs(args) {
|
|
18
|
-
const
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
if (options[key] !== undefined) {
|
|
37
|
-
options[key] = Number(options[key]);
|
|
38
|
-
if (!Number.isInteger(options[key]) || options[key] < 0)
|
|
39
|
-
throw Error(`--${key} must be a whole number`);
|
|
40
|
-
}
|
|
41
|
-
return options;
|
|
19
|
+
const { values } = parseOptions(args, {
|
|
20
|
+
list: { type: 'boolean' },
|
|
21
|
+
'keep-awake': { type: 'boolean' },
|
|
22
|
+
serial: { type: 'string' },
|
|
23
|
+
package: { type: 'string' },
|
|
24
|
+
adb: { type: 'string' },
|
|
25
|
+
port: { type: 'string' },
|
|
26
|
+
duration: { type: 'string' },
|
|
27
|
+
});
|
|
28
|
+
return {
|
|
29
|
+
...(values['list'] ? { list: true } : {}),
|
|
30
|
+
...(values['keep-awake'] ? { keepAwake: true } : {}),
|
|
31
|
+
serial: text(values, 'serial'),
|
|
32
|
+
package: text(values, 'package'),
|
|
33
|
+
adb: text(values, 'adb'),
|
|
34
|
+
port: integerOption(values, 'port', [0, 65535]),
|
|
35
|
+
duration: integerOption(values, 'duration', [0, Number.MAX_SAFE_INTEGER]),
|
|
36
|
+
};
|
|
42
37
|
}
|
|
43
38
|
const describe = (target) => `${target.kind.padEnd(7)} ${target.package ?? 'unknown app'}${target.pid ? ` (pid ${target.pid})` : ''}`;
|
|
44
39
|
export async function androidMain(args) {
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { type ParseArgsOptionsConfig } from 'node:util';
|
|
2
|
+
/** A mistake in how a command was called or configured. The CLI exits with 3. */
|
|
3
|
+
export declare class UsageError extends Error {
|
|
4
|
+
}
|
|
5
|
+
export type Values = Record<string, string | boolean | undefined>;
|
|
6
|
+
/** A string flag's value, or undefined when it isn't given. */
|
|
7
|
+
export declare const text: (values: Values, name: string) => string | undefined;
|
|
8
|
+
/** Parses a command's flags strictly; anything unknown or incomplete is a UsageError. */
|
|
9
|
+
export declare function parseOptions(args: string[], options: ParseArgsOptionsConfig, positionals?: number): {
|
|
10
|
+
values: Values;
|
|
11
|
+
positionals: string[];
|
|
12
|
+
};
|
|
13
|
+
/** A whole number flag within [min, max], or undefined when it isn't given. */
|
|
14
|
+
export declare function integerOption(values: Values, name: string, [min, max]: [number, number]): number | undefined;
|
|
15
|
+
/** Reads a JSON config; a missing file, bad JSON or a rejected config is a UsageError. */
|
|
16
|
+
export declare function readConfig<T = Record<string, unknown>>(path: string, validate?: (config: Record<string, unknown>) => T): Promise<T>;
|
|
17
|
+
/** Runs a config validator, reporting what it rejects as wrong usage. */
|
|
18
|
+
export declare function validated<T>(validate: () => T): T;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
import { parseArgs } from 'node:util';
|
|
3
|
+
/** A mistake in how a command was called or configured. The CLI exits with 3. */
|
|
4
|
+
export class UsageError extends Error {
|
|
5
|
+
}
|
|
6
|
+
/** A string flag's value, or undefined when it isn't given. */
|
|
7
|
+
export const text = (values, name) => typeof values[name] === 'string' ? values[name] : undefined;
|
|
8
|
+
/** Parses a command's flags strictly; anything unknown or incomplete is a UsageError. */
|
|
9
|
+
export function parseOptions(args, options, positionals = 0) {
|
|
10
|
+
let parsed;
|
|
11
|
+
try {
|
|
12
|
+
parsed = parseArgs({
|
|
13
|
+
args,
|
|
14
|
+
options,
|
|
15
|
+
strict: true,
|
|
16
|
+
allowPositionals: positionals > 0,
|
|
17
|
+
});
|
|
18
|
+
}
|
|
19
|
+
catch (error) {
|
|
20
|
+
// parseArgs explains how to pass a positional that starts with "-"; that's noise here.
|
|
21
|
+
throw new UsageError(error.message.split('. ')[0]);
|
|
22
|
+
}
|
|
23
|
+
if (parsed.positionals.length > positionals)
|
|
24
|
+
throw new UsageError(`Unexpected argument: ${parsed.positionals[positionals]}`);
|
|
25
|
+
return { values: parsed.values, positionals: parsed.positionals };
|
|
26
|
+
}
|
|
27
|
+
/** A whole number flag within [min, max], or undefined when it isn't given. */
|
|
28
|
+
export function integerOption(values, name, [min, max]) {
|
|
29
|
+
const value = values[name];
|
|
30
|
+
if (value === undefined)
|
|
31
|
+
return undefined;
|
|
32
|
+
if (typeof value !== 'string' || !/^\d+$/.test(value))
|
|
33
|
+
throw new UsageError(`--${name} must be a whole number`);
|
|
34
|
+
const number = Number(value);
|
|
35
|
+
if (number < min || number > max)
|
|
36
|
+
throw new UsageError(`--${name} must be ${min}–${max}`);
|
|
37
|
+
return number;
|
|
38
|
+
}
|
|
39
|
+
/** Reads a JSON config; a missing file, bad JSON or a rejected config is a UsageError. */
|
|
40
|
+
export async function readConfig(path, validate = (config) => config) {
|
|
41
|
+
let config;
|
|
42
|
+
try {
|
|
43
|
+
config = JSON.parse(await readFile(path, 'utf8'));
|
|
44
|
+
}
|
|
45
|
+
catch (error) {
|
|
46
|
+
throw new UsageError(`Can't read ${path}: ${error.message}`);
|
|
47
|
+
}
|
|
48
|
+
try {
|
|
49
|
+
return validate(config);
|
|
50
|
+
}
|
|
51
|
+
catch (error) {
|
|
52
|
+
throw new UsageError(`${path}: ${error.message}`);
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
/** Runs a config validator, reporting what it rejects as wrong usage. */
|
|
56
|
+
export function validated(validate) {
|
|
57
|
+
try {
|
|
58
|
+
return validate();
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
throw new UsageError(error.message);
|
|
62
|
+
}
|
|
63
|
+
}
|