recovery-probe 0.5.0-preview.17 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +37 -0
- package/CONTRIBUTING.md +1 -1
- package/README.md +6 -4
- package/bin/recovery-probe.mjs +2 -217
- package/dist/cli/android.d.mts +1 -0
- package/dist/cli/android.mjs +112 -0
- package/dist/cli/attach.d.mts +1 -0
- package/dist/cli/attach.mjs +85 -0
- package/dist/cli/compare.d.mts +1 -0
- package/dist/cli/compare.mjs +85 -0
- package/dist/cli/core-demo.d.mts +1 -0
- package/dist/cli/core-demo.mjs +8 -0
- package/dist/cli/desktop.d.mts +1 -0
- package/dist/cli/desktop.mjs +124 -0
- package/dist/cli/ipc.d.mts +1 -0
- package/dist/cli/ipc.mjs +120 -0
- package/dist/cli/main.d.mts +1 -0
- package/dist/cli/main.mjs +217 -0
- package/dist/cli/mcp.d.mts +1 -0
- package/dist/cli/mcp.mjs +29 -0
- package/dist/cli/net.d.mts +1 -0
- package/dist/cli/net.mjs +130 -0
- package/dist/cli/observe.d.mts +1 -0
- package/dist/cli/observe.mjs +266 -0
- package/dist/cli/refresh.d.mts +1 -0
- package/dist/cli/refresh.mjs +150 -0
- package/dist/cli/repair.d.mts +1 -0
- package/dist/cli/repair.mjs +90 -0
- package/dist/cli/start.d.mts +1 -0
- package/dist/cli/start.mjs +38 -0
- package/dist/cli/suspects.d.mts +1 -0
- package/dist/cli/suspects.mjs +65 -0
- package/dist/cli/until-stopped.d.mts +3 -0
- package/dist/cli/until-stopped.mjs +17 -0
- package/dist/cli/watch.d.mts +1 -0
- package/dist/cli/watch.mjs +143 -0
- package/dist/cli/web.d.mts +1 -0
- package/dist/cli/web.mjs +107 -0
- package/dist/desktop.d.mts +67 -61
- package/dist/desktop.mjs +394 -405
- package/dist/guided-start.d.mts +42 -0
- package/dist/guided-start.mjs +244 -321
- package/dist/http-discover.d.mts +111 -0
- package/dist/http-discover.mjs +310 -343
- package/dist/index.d.mts +49 -0
- package/dist/index.mjs +219 -235
- package/dist/pick-marker.d.mts +10 -0
- package/dist/pick-marker.mjs +86 -103
- package/dist/refresh.d.mts +156 -0
- package/dist/refresh.mjs +388 -412
- package/dist/repair-process.d.mts +17 -0
- package/dist/repair-process.mjs +89 -98
- package/dist/repair-provider.d.mts +53 -0
- package/dist/repair-provider.mjs +66 -88
- package/dist/repair.d.mts +72 -0
- package/dist/repair.mjs +412 -519
- package/dist/web.d.mts +19 -22
- package/dist/web.mjs +40 -46
- package/docs/android.md +2 -2
- package/docs/ci.md +1 -1
- package/docs/compare.md +1 -1
- package/docs/desktop.md +2 -2
- package/docs/ipc.md +4 -4
- package/docs/mcp.md +1 -1
- package/docs/net.md +2 -2
- package/docs/observe.md +3 -3
- package/docs/repair.md +1 -1
- package/docs/start.md +2 -2
- package/docs/suspects.md +1 -1
- package/docs/watch.md +1 -1
- package/package.json +5 -5
- package/bin/android.mjs +0 -140
- package/bin/attach.mjs +0 -79
- package/bin/compare.mjs +0 -98
- package/bin/core-demo.mjs +0 -11
- package/bin/desktop.mjs +0 -157
- package/bin/ipc.mjs +0 -134
- package/bin/mcp.mjs +0 -35
- package/bin/net.mjs +0 -149
- package/bin/observe.mjs +0 -331
- package/bin/refresh.mjs +0 -162
- package/bin/repair.mjs +0 -112
- package/bin/start.mjs +0 -39
- package/bin/suspects.mjs +0 -71
- package/bin/until-stopped.mjs +0 -15
- package/bin/watch.mjs +0 -163
- package/bin/web.mjs +0 -120
- package/dist/index.d.ts +0 -54
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,43 @@ All notable changes to Recovery Probe are documented here. The project follows [
|
|
|
4
4
|
|
|
5
5
|
Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
|
|
6
6
|
|
|
7
|
+
## 0.5.0 (2026-10-21)
|
|
8
|
+
|
|
9
|
+
Promotes previews 1–22 to the stable npm `latest` channel. The preview entries below retain the detailed history.
|
|
10
|
+
|
|
11
|
+
- Synchronize the brief-content observation fixture with completed samples so a slow sampler cannot race its restoration timer. Keep coverage of transitions entirely between samples.
|
|
12
|
+
- Complete the TypeScript migration of the library and CLI. Published JavaScript and declarations are built into `dist/`; public package imports and the `recovery-probe` command remain available.
|
|
13
|
+
- Add IPC action checks for simulated success, failure and double-clicks, delayed injected results, and scripted fill/press steps.
|
|
14
|
+
- Add a host-level HTTPS fault proxy and network steps during observation, plus evidence of local files removed by the app.
|
|
15
|
+
- Add MCP tools for coding agents, experimental source scanning with `suspects`, before/after report comparison, and `watch` to rerun checks after saves.
|
|
16
|
+
- Add experimental Android WebView attachment and Meta Quest keep-awake support, with diagnostics for visible pages that are not rendering.
|
|
17
|
+
|
|
18
|
+
Upgrading from 0.4.0: keep using the public package exports and CLI. If `RECOVERY_PROBE_IPC_MODULE` stores the old `src/ipc-probe.cjs` path, resolve it again with `node -p "require.resolve('recovery-probe/ipc')"`; it now points into `dist/`. Restart the development app after upgrading so its loaded IPC hook matches the CLI. The optional TypeScript peer dependency is needed only for source scanning. Experimental workflows remain experimental in this stable package.
|
|
19
|
+
|
|
20
|
+
## 0.5.0-preview.22 (2026-10-21)
|
|
21
|
+
|
|
22
|
+
- The command line is written in TypeScript under `src/cli` and compiled to `dist/cli`. `bin/recovery-probe.mjs` is now a launcher for it; the `recovery-probe` command, its options and its output are unchanged.
|
|
23
|
+
- `npm run demo` runs `dist/cli/core-demo.mjs`.
|
|
24
|
+
|
|
25
|
+
## 0.5.0-preview.21 (2026-10-21)
|
|
26
|
+
|
|
27
|
+
- The opt-in repair workflow (`recovery-probe repair`) is written in TypeScript. Its files, prompts and checks are unchanged.
|
|
28
|
+
- All of the library source is now TypeScript, and every published declaration is generated from it.
|
|
29
|
+
|
|
30
|
+
## 0.5.0-preview.20 (2026-10-21)
|
|
31
|
+
|
|
32
|
+
- HTTP discovery (`web --attach --discover`), the guided setup (`recovery-probe start`) and its content picker are written in TypeScript. Their reports and prompts are unchanged.
|
|
33
|
+
|
|
34
|
+
## 0.5.0-preview.19 (2026-10-21)
|
|
35
|
+
|
|
36
|
+
- The package root (`withFault`, `probeRecovery`), `recovery-probe/desktop` and `recovery-probe/web` are written in TypeScript. Their reports are unchanged.
|
|
37
|
+
- Their declarations are generated from the source instead of written by hand. They accept everything the old ones did and add `ValidDesktopConfig`, `DesktopDiscovery`, a typed `ProbeError` constructor, and the `baselineTimeoutMs`, `recoveryTimeoutMs` and `times` fields that `DesktopReport` already carried.
|
|
38
|
+
- The root declarations moved from `dist/index.d.ts` to `dist/index.d.mts`. The `types` fields point to the new file.
|
|
39
|
+
|
|
40
|
+
## 0.5.0-preview.18 (2026-10-21)
|
|
41
|
+
|
|
42
|
+
- Refresh experiments (`recovery-probe refresh`) are written in TypeScript. Their reports are unchanged.
|
|
43
|
+
|
|
7
44
|
## 0.5.0-preview.17 (2026-10-21)
|
|
8
45
|
|
|
9
46
|
- **`recovery-probe android --keep-awake`** keeps a Meta Quest's display awake and pauses the Guardian boundary until the forward stops, then restores both. Checks can then run on a headset that nobody wears.
|
package/CONTRIBUTING.md
CHANGED
|
@@ -27,7 +27,7 @@ npm run test:repair:electron
|
|
|
27
27
|
|
|
28
28
|
Repair integration tests use a **controlled mock model response** but real apps, fault injection, source changes and reruns. They validate orchestration, not live AI diagnosis quality.
|
|
29
29
|
|
|
30
|
-
Code and JSON are formatted with Prettier (`npm run format`) and linted with ESLint (`npm run lint`); CI fails on either. Functions passed to `page.evaluate` run in the browser: keep them self-contained, and list new in-page modules in `eslint.config.mjs` so they get browser globals. The package is
|
|
30
|
+
Code and JSON are formatted with Prettier (`npm run format`) and linted with ESLint (`npm run lint`); CI fails on either. Functions passed to `page.evaluate` run in the browser: keep them self-contained, and list new in-page modules in `eslint.config.mjs` so they get browser globals. The package is written in TypeScript: modules are `.mts` (or `.cts` for CommonJS), and the command line lives in `src/cli`, with `bin/recovery-probe.mjs` only starting it. `npm run build` compiles them into `dist` with strict checks and generated declarations, and copies the report templates unchanged. `npm ci` builds once, and every script that runs code builds first, so tests never use a stale `dist`. `npm run typecheck` also checks the JavaScript in `bin`, `examples` and `scripts` with strict mode off; add JSDoc types where inference is not enough. TypeScript is pinned to 6.0 because typescript-eslint, which lints the TypeScript files, does not support 7 yet. Markdown, HTML fixtures, report templates and workflow files are left as written. Report markup lives in `src/report-templates`: `{{slot}}` takes text and escapes it, `{{{slot}}}` takes markup built with `escapeHtml`. `.gitattributes` keeps LF line endings on every platform so local checks match CI. The repository-wide reformat is listed in `.git-blame-ignore-revs`; run `git config blame.ignoreRevsFile .git-blame-ignore-revs` to skip it in local blame.
|
|
31
31
|
|
|
32
32
|
## Install an unpublished source preview
|
|
33
33
|
|
package/README.md
CHANGED
|
@@ -20,7 +20,7 @@ The package includes a deliberately broken app and a corrected one. Both pass th
|
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
22
|
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
23
|
-
npm install --save-dev --save-exact recovery-probe@0.
|
|
23
|
+
npm install --save-dev --save-exact recovery-probe@0.5.0 playwright@1.62.1
|
|
24
24
|
npx playwright install chromium
|
|
25
25
|
npx recovery-probe --demo
|
|
26
26
|
```
|
|
@@ -34,13 +34,13 @@ npx recovery-probe --demo
|
|
|
34
34
|
| Set up a first recovery check interactively | `recovery-probe start web URL` or `start desktop` | [Guided start](docs/start.md) |
|
|
35
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
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
|
|
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
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
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
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
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
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
|
|
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
44
|
| Inspect an Android app's WebView (experimental) | `recovery-probe android --package NAME` | [Android WebViews](docs/android.md) |
|
|
45
45
|
| Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
|
|
46
46
|
| Watch cached content and row states after user actions, without faults | `recovery-probe observe --config FILE [--steps FILE]` | [Observation](docs/observe.md) |
|
|
@@ -107,10 +107,12 @@ If no request matches, `withFault` throws `FAULT_NOT_TRIGGERED` instead of letti
|
|
|
107
107
|
|
|
108
108
|
## Install
|
|
109
109
|
|
|
110
|
-
**0.
|
|
110
|
+
**0.5.0** is the stable release on npm's `latest` channel, and the commands above pin it for reproducible reports. Prereleases use the `next` channel and are opt-in.
|
|
111
111
|
|
|
112
112
|
Use Node.js 22 or newer. A separate tools folder keeps the tester out of your application's production dependencies. Browser and desktop commands need Playwright; attached targets use their existing browser runtime. If a version is not on npm yet, use the [source installation](CONTRIBUTING.md#install-an-unpublished-source-preview): a GitHub merge alone does not publish the package. See [CHANGELOG.md](CHANGELOG.md) for version history.
|
|
113
113
|
|
|
114
|
+
When upgrading from 0.4.0, resolve any stored IPC hook path again with `node -p "require.resolve('recovery-probe/ipc')"` and restart the development app. The hook now ships in `dist/`. The library and CLI are compiled from TypeScript; using the published package does not require a build. Source scanning with `suspects` additionally needs the optional TypeScript peer dependency. Experimental commands retain that status in 0.5.0.
|
|
115
|
+
|
|
114
116
|
## Reports, agents and privacy
|
|
115
117
|
|
|
116
118
|
Reports separate measured facts, such as fault counts, successful reads, timings and UI changes, from suspected defects. A `CONTENT_LOSS` finding needs review. An unconsumed fault, an unstable control or an unsupported path is inconclusive. Observation findings such as `DELAYED_UI_UPDATE` are leads to check against the application logic, not verdicts.
|
package/bin/recovery-probe.mjs
CHANGED
|
@@ -1,218 +1,3 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
import
|
|
4
|
-
import { probeRecovery } from '../dist/index.mjs'
|
|
5
|
-
import { startDemoServer } from '../examples/demo-server.mjs'
|
|
6
|
-
|
|
7
|
-
const { version } = JSON.parse(
|
|
8
|
-
await readFile(new URL('../package.json', import.meta.url), 'utf8'),
|
|
9
|
-
)
|
|
10
|
-
|
|
11
|
-
function printHelp() {
|
|
12
|
-
console.log(`Recovery Probe ${version}
|
|
13
|
-
|
|
14
|
-
Usage:
|
|
15
|
-
recovery-probe --demo [--out report.json] [--json]
|
|
16
|
-
recovery-probe --config scenario.json [--out report.json] [--json]
|
|
17
|
-
recovery-probe start web http://localhost:3000
|
|
18
|
-
recovery-probe start desktop
|
|
19
|
-
recovery-probe refresh --help
|
|
20
|
-
recovery-probe observe --help
|
|
21
|
-
recovery-probe ipc --help
|
|
22
|
-
recovery-probe net --help
|
|
23
|
-
recovery-probe mcp --help
|
|
24
|
-
recovery-probe suspects --help
|
|
25
|
-
recovery-probe compare --help
|
|
26
|
-
recovery-probe watch --help
|
|
27
|
-
recovery-probe android --help
|
|
28
|
-
recovery-probe desktop --help
|
|
29
|
-
recovery-probe web --help
|
|
30
|
-
recovery-probe repair --help
|
|
31
|
-
recovery-probe --version
|
|
32
|
-
|
|
33
|
-
Options:
|
|
34
|
-
--demo Run the included broken-versus-fixed browser demonstration.
|
|
35
|
-
--config <file> Check one JSON-configured recovery scenario.
|
|
36
|
-
--out <file> Save the full machine-readable report.
|
|
37
|
-
--json Print the full JSON report instead of a terminal summary.
|
|
38
|
-
--help Show this help.
|
|
39
|
-
|
|
40
|
-
Use only development or test targets you control.`)
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
function marker(outcome) {
|
|
44
|
-
if (outcome === 'pass') return 'PASS'
|
|
45
|
-
if (outcome === 'fail') return 'CAUGHT'
|
|
46
|
-
return outcome.toUpperCase()
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
function printSummary(report) {
|
|
50
|
-
console.log(`Recovery Probe ${report.version} — ${report.mode}\n`)
|
|
51
|
-
for (const app of report.apps) {
|
|
52
|
-
console.log(app.name)
|
|
53
|
-
for (const row of app.results) {
|
|
54
|
-
const injected = row.applied ? `, injected ${row.applied}` : ''
|
|
55
|
-
console.log(
|
|
56
|
-
` ${marker(row.outcome).padEnd(12)} ${row.scenario} (${row.code}${injected})`,
|
|
57
|
-
)
|
|
58
|
-
}
|
|
59
|
-
console.log('')
|
|
60
|
-
}
|
|
61
|
-
if (report.mode === 'controlled demonstration') {
|
|
62
|
-
console.log(
|
|
63
|
-
report.expectedDemonstrationVerified
|
|
64
|
-
? 'Demo verified: the happy path passes, the broken recovery is caught, and the fixed app recovers.'
|
|
65
|
-
: 'Demo failed: the expected broken-versus-fixed distinction was not observed.',
|
|
66
|
-
)
|
|
67
|
-
} else {
|
|
68
|
-
console.log(
|
|
69
|
-
report.apps.every((app) => app.ok)
|
|
70
|
-
? 'Recovery check passed.'
|
|
71
|
-
: 'Recovery check did not pass.',
|
|
72
|
-
)
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
async function main() {
|
|
77
|
-
const args = process.argv.slice(2)
|
|
78
|
-
if (args[0] === 'observe') {
|
|
79
|
-
const { observeMain } = await import('./observe.mjs')
|
|
80
|
-
return observeMain(args.slice(1))
|
|
81
|
-
}
|
|
82
|
-
if (args[0] === 'refresh') {
|
|
83
|
-
const { refreshMain } = await import('./refresh.mjs')
|
|
84
|
-
return refreshMain(args.slice(1))
|
|
85
|
-
}
|
|
86
|
-
if (args[0] === 'suspects') {
|
|
87
|
-
const { suspectsMain } = await import('./suspects.mjs')
|
|
88
|
-
return suspectsMain(args.slice(1))
|
|
89
|
-
}
|
|
90
|
-
if (args[0] === 'compare') {
|
|
91
|
-
const { compareMain } = await import('./compare.mjs')
|
|
92
|
-
return compareMain(args.slice(1))
|
|
93
|
-
}
|
|
94
|
-
if (args[0] === 'watch') {
|
|
95
|
-
const { watchMain } = await import('./watch.mjs')
|
|
96
|
-
return watchMain(args.slice(1))
|
|
97
|
-
}
|
|
98
|
-
if (args[0] === 'mcp') {
|
|
99
|
-
const { mcpMain } = await import('./mcp.mjs')
|
|
100
|
-
return mcpMain(args.slice(1))
|
|
101
|
-
}
|
|
102
|
-
if (args[0] === 'android') {
|
|
103
|
-
const { androidMain } = await import('./android.mjs')
|
|
104
|
-
return androidMain(args.slice(1))
|
|
105
|
-
}
|
|
106
|
-
if (args[0] === 'net') {
|
|
107
|
-
const { netMain } = await import('./net.mjs')
|
|
108
|
-
return netMain(args.slice(1))
|
|
109
|
-
}
|
|
110
|
-
if (args[0] === 'ipc') {
|
|
111
|
-
const { ipcMain } = await import('./ipc.mjs')
|
|
112
|
-
return ipcMain(args.slice(1))
|
|
113
|
-
}
|
|
114
|
-
if (args[0] === 'start') {
|
|
115
|
-
const { startMain } = await import('./start.mjs')
|
|
116
|
-
return startMain(args.slice(1))
|
|
117
|
-
}
|
|
118
|
-
if (args[0] === 'web') {
|
|
119
|
-
const { webMain } = await import('./web.mjs')
|
|
120
|
-
return webMain(args.slice(1))
|
|
121
|
-
}
|
|
122
|
-
if (args[0] === 'repair') {
|
|
123
|
-
const { repairMain } = await import('./repair.mjs')
|
|
124
|
-
return repairMain(args.slice(1))
|
|
125
|
-
}
|
|
126
|
-
if (args[0] === 'desktop') {
|
|
127
|
-
const { desktopMain } = await import('./desktop.mjs')
|
|
128
|
-
return desktopMain(args.slice(1))
|
|
129
|
-
}
|
|
130
|
-
if (args.includes('--help') || !args.length) {
|
|
131
|
-
printHelp()
|
|
132
|
-
return
|
|
133
|
-
}
|
|
134
|
-
if (args.length === 1 && args[0] === '--version') {
|
|
135
|
-
console.log(version)
|
|
136
|
-
return
|
|
137
|
-
}
|
|
138
|
-
let demo = false
|
|
139
|
-
let json = false
|
|
140
|
-
let configPath
|
|
141
|
-
let output
|
|
142
|
-
for (let i = 0; i < args.length; i++) {
|
|
143
|
-
const arg = args[i]
|
|
144
|
-
if (arg === '--demo') demo = true
|
|
145
|
-
else if (arg === '--json') json = true
|
|
146
|
-
else if (arg === '--config' || arg === '--out') {
|
|
147
|
-
const value = args[++i]
|
|
148
|
-
if (!value || value.startsWith('--'))
|
|
149
|
-
throw new Error(`${arg} needs a value`)
|
|
150
|
-
if (arg === '--config') configPath = value
|
|
151
|
-
else output = value
|
|
152
|
-
} else throw new Error(`Unknown argument: ${arg}`)
|
|
153
|
-
}
|
|
154
|
-
if (demo === Boolean(configPath))
|
|
155
|
-
throw new Error('Choose exactly one of --demo or --config')
|
|
156
|
-
|
|
157
|
-
const config = configPath
|
|
158
|
-
? JSON.parse(await readFile(configPath, 'utf8'))
|
|
159
|
-
: null
|
|
160
|
-
const { chromium } = await import('playwright')
|
|
161
|
-
const browser = await chromium.launch({ headless: true })
|
|
162
|
-
let server
|
|
163
|
-
/** @type {Record<string, any>} */
|
|
164
|
-
let report
|
|
165
|
-
try {
|
|
166
|
-
const apps = []
|
|
167
|
-
if (demo) {
|
|
168
|
-
server = await startDemoServer()
|
|
169
|
-
for (const variant of ['broken', 'fixed']) {
|
|
170
|
-
apps.push(
|
|
171
|
-
await probeRecovery(browser, {
|
|
172
|
-
name: `${variant} synthetic fixture`,
|
|
173
|
-
url: `${server.url}/${variant}`,
|
|
174
|
-
requestPattern: '**/api/profile',
|
|
175
|
-
readySelector: '#profile',
|
|
176
|
-
retrySelector: '#retry',
|
|
177
|
-
timeoutMs: 1200,
|
|
178
|
-
}),
|
|
179
|
-
)
|
|
180
|
-
}
|
|
181
|
-
} else apps.push(await probeRecovery(browser, config))
|
|
182
|
-
report = {
|
|
183
|
-
tool: 'Recovery Probe',
|
|
184
|
-
version,
|
|
185
|
-
generatedAt: new Date().toISOString(),
|
|
186
|
-
environment: {
|
|
187
|
-
node: process.version,
|
|
188
|
-
platform: process.platform,
|
|
189
|
-
chromium: browser.version(),
|
|
190
|
-
},
|
|
191
|
-
mode: demo ? 'controlled demonstration' : 'configured recovery check',
|
|
192
|
-
apps,
|
|
193
|
-
}
|
|
194
|
-
if (demo) {
|
|
195
|
-
report.expectedDemonstrationVerified =
|
|
196
|
-
apps[0].results[0].outcome === 'pass' &&
|
|
197
|
-
apps[0].results
|
|
198
|
-
.slice(1)
|
|
199
|
-
.every((row) => row.outcome === 'fail' && row.applied === 1) &&
|
|
200
|
-
apps[1].ok
|
|
201
|
-
process.exitCode = report.expectedDemonstrationVerified ? 0 : 1
|
|
202
|
-
} else process.exitCode = apps.every((app) => app.ok) ? 0 : 1
|
|
203
|
-
} finally {
|
|
204
|
-
await browser.close()
|
|
205
|
-
if (server) await server.close()
|
|
206
|
-
}
|
|
207
|
-
if (json) console.log(JSON.stringify(report, null, 2))
|
|
208
|
-
else printSummary(report)
|
|
209
|
-
if (output) {
|
|
210
|
-
await mkdir(dirname(output), { recursive: true })
|
|
211
|
-
await writeFile(output, JSON.stringify(report, null, 2) + '\n')
|
|
212
|
-
}
|
|
213
|
-
}
|
|
214
|
-
|
|
215
|
-
main().catch((error) => {
|
|
216
|
-
console.error(`Recovery Probe: ${error.message}`)
|
|
217
|
-
process.exitCode = 2
|
|
218
|
-
})
|
|
2
|
+
// The command line is compiled from src/cli; this file only starts it.
|
|
3
|
+
import '../dist/cli/main.mjs'
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function androidMain(args: string[]): Promise<void>;
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { adbRunner, androidDevices, androidDevtoolsTargets, androidDisplayState, displayProblems, forwardAndroidDevtools, keepQuestAwake, } from '../android.mjs';
|
|
2
|
+
import { startCdpBridge } from '../cdp-bridge.mjs';
|
|
3
|
+
import { untilStopped } from './until-stopped.mjs';
|
|
4
|
+
const USAGE = 'recovery-probe android [--list] [--serial SERIAL] [--package NAME] [--port N] [--duration MS] [--keep-awake] [--adb PATH]';
|
|
5
|
+
const HELP = `${USAGE}
|
|
6
|
+
|
|
7
|
+
Makes an Android WebView or Chrome inspectable like a desktop debugging endpoint.
|
|
8
|
+
It finds the app's DevTools socket over adb, forwards a local port to it and keeps
|
|
9
|
+
the forward until Ctrl+C or --duration. Use the printed URL with desktop --cdp, or as
|
|
10
|
+
"cdp" in an observe or desktop config. The app must enable WebView debugging, and the
|
|
11
|
+
device needs USB debugging. --list shows what can be inspected. A page draws no frames
|
|
12
|
+
while the display sleeps or a system dialog is in front; the command warns when it
|
|
13
|
+
sees either. On a Meta Quest, --keep-awake keeps the display awake and pauses the
|
|
14
|
+
Guardian boundary until the forward stops, so nobody has to wear the headset.
|
|
15
|
+
See docs/android.md.`;
|
|
16
|
+
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
17
|
+
function parseArgs(args) {
|
|
18
|
+
const options = {};
|
|
19
|
+
for (let i = 0; i < args.length; i++) {
|
|
20
|
+
const arg = args[i];
|
|
21
|
+
const value = args[i + 1];
|
|
22
|
+
if (arg === '--list')
|
|
23
|
+
options.list = true;
|
|
24
|
+
else if (arg === '--keep-awake')
|
|
25
|
+
options.keepAwake = true;
|
|
26
|
+
else if (['--serial', '--package', '--port', '--duration', '--adb'].includes(arg) &&
|
|
27
|
+
value &&
|
|
28
|
+
!value.startsWith('--')) {
|
|
29
|
+
options[arg.slice(2)] = value;
|
|
30
|
+
i++;
|
|
31
|
+
}
|
|
32
|
+
else
|
|
33
|
+
throw Error(`Use ${USAGE}`);
|
|
34
|
+
}
|
|
35
|
+
for (const key of ['port', 'duration'])
|
|
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;
|
|
42
|
+
}
|
|
43
|
+
const describe = (target) => `${target.kind.padEnd(7)} ${target.package ?? 'unknown app'}${target.pid ? ` (pid ${target.pid})` : ''}`;
|
|
44
|
+
export async function androidMain(args) {
|
|
45
|
+
if (args.includes('--help')) {
|
|
46
|
+
console.log(HELP);
|
|
47
|
+
return;
|
|
48
|
+
}
|
|
49
|
+
const options = parseArgs(args);
|
|
50
|
+
let serial = options.serial;
|
|
51
|
+
if (!serial) {
|
|
52
|
+
const devices = await androidDevices(adbRunner({ adb: options.adb }));
|
|
53
|
+
if (devices.length !== 1)
|
|
54
|
+
throw Error(devices.length
|
|
55
|
+
? `Several devices are connected (${devices.join(', ')}); choose one with --serial`
|
|
56
|
+
: 'No device is connected over adb; enable USB debugging and check adb devices');
|
|
57
|
+
serial = devices[0];
|
|
58
|
+
}
|
|
59
|
+
const run = adbRunner({ adb: options.adb, serial });
|
|
60
|
+
const targets = await androidDevtoolsTargets(run);
|
|
61
|
+
if (options.list) {
|
|
62
|
+
console.log(targets.length
|
|
63
|
+
? targets.map(describe).join('\n')
|
|
64
|
+
: 'Nothing to inspect: no app with WebView debugging enabled is running.');
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
const matching = options.package
|
|
68
|
+
? targets.filter((target) => target.package === options.package)
|
|
69
|
+
: targets;
|
|
70
|
+
if (matching.length !== 1)
|
|
71
|
+
throw Error(matching.length
|
|
72
|
+
? `Several targets can be inspected; choose one with --package:\n${matching.map(describe).join('\n')}`
|
|
73
|
+
: options.package
|
|
74
|
+
? `${options.package} has no WebView to inspect; is it running with WebView debugging enabled?`
|
|
75
|
+
: 'Nothing to inspect: no app with WebView debugging enabled is running.');
|
|
76
|
+
const [target] = matching;
|
|
77
|
+
if (options.keepAwake && !(await androidDisplayState(run)).quest)
|
|
78
|
+
throw Error('--keep-awake works on Meta Quest headsets only');
|
|
79
|
+
const forward = await forwardAndroidDevtools(run, target.socket);
|
|
80
|
+
let bridge;
|
|
81
|
+
let awake;
|
|
82
|
+
try {
|
|
83
|
+
// Android keeps blank WebViews without a window that never answer DevTools; a
|
|
84
|
+
// client attaching to them all would wait forever, so the bridge hides them.
|
|
85
|
+
bridge = await startCdpBridge({ upstream: forward.cdp, port: options.port });
|
|
86
|
+
if (options.keepAwake) {
|
|
87
|
+
awake = await keepQuestAwake(run);
|
|
88
|
+
// The display and the app's panel take a moment to come back.
|
|
89
|
+
await sleep(3000);
|
|
90
|
+
}
|
|
91
|
+
const display = await androidDisplayState(run).catch(() => undefined);
|
|
92
|
+
console.log(`Android ${describe(target).trim()} on ${bridge.url}
|
|
93
|
+
|
|
94
|
+
Use it like a desktop debugging endpoint:
|
|
95
|
+
recovery-probe desktop --cdp ${bridge.url} --list
|
|
96
|
+
"cdp": "${bridge.url}" in an observe or desktop config
|
|
97
|
+
|
|
98
|
+
Keep the app on screen while a check runs. Press Ctrl+C to remove the forward.`);
|
|
99
|
+
if (awake)
|
|
100
|
+
console.log('Keeping the Quest display awake and the Guardian boundary paused until the forward stops.');
|
|
101
|
+
for (const problem of display ? displayProblems(display) : [])
|
|
102
|
+
console.log(`Warning: ${problem} ${display?.quest && !awake ? 'Wear the headset, or use --keep-awake.' : 'Wake the device and bring the app to the front.'}`);
|
|
103
|
+
await untilStopped(options.duration);
|
|
104
|
+
}
|
|
105
|
+
finally {
|
|
106
|
+
await awake
|
|
107
|
+
?.restore()
|
|
108
|
+
.catch((error) => console.error(`Recovery Probe: ${error.message}`));
|
|
109
|
+
await bridge?.close();
|
|
110
|
+
await forward.remove();
|
|
111
|
+
}
|
|
112
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function attachMain(args: string[]): Promise<void>;
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { readFile, mkdir } from 'node:fs/promises';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
3
|
+
import { connectDesktop, selectDesktopPage, checkDesktop, } from '../desktop.mjs';
|
|
4
|
+
import { discoverHttp, httpDiscoveryConfig, } from '../http-discover.mjs';
|
|
5
|
+
import { writeDiscoveryReport } from '../discovery-report.mjs';
|
|
6
|
+
import { prepareVisibility } from '../visibility.mjs';
|
|
7
|
+
import { writeDesktopReport } from '../desktop-report.mjs';
|
|
8
|
+
export async function attachMain(args) {
|
|
9
|
+
const options = {};
|
|
10
|
+
for (let i = 0; i < args.length; i++) {
|
|
11
|
+
const arg = args[i];
|
|
12
|
+
if (arg === '--discover' || arg === '--restore-window')
|
|
13
|
+
options[arg.slice(2)] = true;
|
|
14
|
+
else if (['--config', '--cdp', '--out', '--page'].includes(arg) &&
|
|
15
|
+
args[i + 1] &&
|
|
16
|
+
!args[i + 1].startsWith('--'))
|
|
17
|
+
options[arg.slice(2)] = args[++i];
|
|
18
|
+
else
|
|
19
|
+
throw new Error('Use web --attach [--discover] --config FILE [--cdp URL] [--page N] [--restore-window] [--out NEW_DIRECTORY]');
|
|
20
|
+
}
|
|
21
|
+
if (!options.config)
|
|
22
|
+
throw new Error('--config is required');
|
|
23
|
+
// The checks below validate the configuration file.
|
|
24
|
+
let config = JSON.parse(await readFile(options.config, 'utf8'));
|
|
25
|
+
if (options.cdp)
|
|
26
|
+
config.cdp = options.cdp;
|
|
27
|
+
if (options.page !== undefined) {
|
|
28
|
+
if (!/^\d+$/.test(options.page))
|
|
29
|
+
throw new Error('Invalid page');
|
|
30
|
+
config.page = Number(options.page);
|
|
31
|
+
}
|
|
32
|
+
if (options['restore-window'])
|
|
33
|
+
config.restoreWindow = true;
|
|
34
|
+
if (options.discover)
|
|
35
|
+
config = httpDiscoveryConfig(config);
|
|
36
|
+
const directory = resolve(options.out ??
|
|
37
|
+
`.recovery-probe/attached-${Date.now()}`);
|
|
38
|
+
await mkdir(resolve(directory, '..'), { recursive: true, mode: 0o700 });
|
|
39
|
+
await mkdir(directory, { mode: 0o700 });
|
|
40
|
+
const browser = await connectDesktop(config.cdp);
|
|
41
|
+
try {
|
|
42
|
+
const page = selectDesktopPage(browser, config);
|
|
43
|
+
let report;
|
|
44
|
+
if (options.discover) {
|
|
45
|
+
const discovery = await discoverHttp(page, config);
|
|
46
|
+
await writeDiscoveryReport(directory, discovery, config);
|
|
47
|
+
report = discovery;
|
|
48
|
+
}
|
|
49
|
+
else {
|
|
50
|
+
const visibility = await prepareVisibility(page, config);
|
|
51
|
+
let check;
|
|
52
|
+
try {
|
|
53
|
+
check = await checkDesktop(page, config);
|
|
54
|
+
check.mode = 'attached browser recovery';
|
|
55
|
+
}
|
|
56
|
+
finally {
|
|
57
|
+
await visibility.revert();
|
|
58
|
+
}
|
|
59
|
+
await writeDesktopReport(directory, check, config);
|
|
60
|
+
report = check;
|
|
61
|
+
}
|
|
62
|
+
if ('findings' in report)
|
|
63
|
+
for (const f of report.findings)
|
|
64
|
+
console.log(
|
|
65
|
+
// A partial finding always carries the interpretation it observed.
|
|
66
|
+
`${f.id}: ${f.classification}${f.partial ? `; runs=${f.completedRuns}/${f.plannedRuns} partial; observed=${f.observedInterpretation.classification}` : ''}`);
|
|
67
|
+
else
|
|
68
|
+
for (const r of report.results)
|
|
69
|
+
console.log(`${r.kind}: ${r.code}`);
|
|
70
|
+
// Only discovery reports carry an error; a check's failures are its rows.
|
|
71
|
+
if ('findings' in report && report.error)
|
|
72
|
+
console.error(report.error);
|
|
73
|
+
console.log(`Final reload: ${report.finalReset}\nReport: ${directory}/report.html`);
|
|
74
|
+
process.exitCode = report.ok
|
|
75
|
+
? 0
|
|
76
|
+
: 'findings' in report
|
|
77
|
+
? 2
|
|
78
|
+
: report.results.some((r) => r.outcome === 'fail')
|
|
79
|
+
? 1
|
|
80
|
+
: 2;
|
|
81
|
+
}
|
|
82
|
+
finally {
|
|
83
|
+
await browser.close();
|
|
84
|
+
}
|
|
85
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function compareMain(args: string[]): Promise<void>;
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { compareReports, describeRuns, describeSide, } from '../compare.mjs';
|
|
2
|
+
const USAGE = 'recovery-probe compare --before REPORT... --after REPORT... [--before-label TEXT] [--after-label TEXT] [--markdown | --json]';
|
|
3
|
+
const HELP = `${USAGE}
|
|
4
|
+
|
|
5
|
+
Compares reports of the same check from before and after a change, such as
|
|
6
|
+
main and a pull request branch. REPORT is a report.json or its folder; give
|
|
7
|
+
several runs per side to compare repeated runs. A problem counts as found from
|
|
8
|
+
any run, but as gone only when a complete run after the change checked it, so a
|
|
9
|
+
run that stopped early never reads as a fix. --markdown prints a block for a
|
|
10
|
+
pull request. Exit 0: improved, or no problem on either side; 1: a new suspected
|
|
11
|
+
defect or failed check; 2: anything else to review. See docs/compare.md.`;
|
|
12
|
+
const STATUS = {
|
|
13
|
+
NEW: 'new',
|
|
14
|
+
STILL: 'still there',
|
|
15
|
+
GONE: 'gone',
|
|
16
|
+
UNVERIFIED: 'not checked to the end',
|
|
17
|
+
};
|
|
18
|
+
function parseArgs(args) {
|
|
19
|
+
const options = { before: [], after: [], labels: {} };
|
|
20
|
+
let side;
|
|
21
|
+
for (let i = 0; i < args.length; i++) {
|
|
22
|
+
const arg = args[i];
|
|
23
|
+
if (arg === '--before' || arg === '--after')
|
|
24
|
+
side = arg.slice(2);
|
|
25
|
+
else if (arg === '--json' || arg === '--markdown') {
|
|
26
|
+
options.format = arg.slice(2);
|
|
27
|
+
side = undefined;
|
|
28
|
+
}
|
|
29
|
+
else if (arg === '--before-label' || arg === '--after-label') {
|
|
30
|
+
if (!args[i + 1] || args[i + 1].startsWith('--'))
|
|
31
|
+
throw Error(`${arg} needs a text, such as main`);
|
|
32
|
+
options.labels[arg.slice(2, -'-label'.length)] = args[++i];
|
|
33
|
+
side = undefined;
|
|
34
|
+
}
|
|
35
|
+
else if (arg.startsWith('--') || !side)
|
|
36
|
+
throw Error(`Use ${USAGE}`);
|
|
37
|
+
else
|
|
38
|
+
options[side].push(arg);
|
|
39
|
+
}
|
|
40
|
+
if (!options.before.length || !options.after.length)
|
|
41
|
+
throw Error(`Give reports on both sides: ${USAGE}`);
|
|
42
|
+
return options;
|
|
43
|
+
}
|
|
44
|
+
function printText(comparison) {
|
|
45
|
+
const { labels } = comparison;
|
|
46
|
+
console.log(`Recovery Probe comparison${comparison.mode ? `: ${comparison.mode}` : ''}${comparison.target ? `, ${comparison.target}` : ''}`);
|
|
47
|
+
console.log(` ${labels.before}: ${describeRuns(comparison.before)}`);
|
|
48
|
+
console.log(` ${labels.after}: ${describeRuns(comparison.after)}`);
|
|
49
|
+
if (comparison.changes.length)
|
|
50
|
+
console.log('');
|
|
51
|
+
for (const change of comparison.changes) {
|
|
52
|
+
const problem = `${change.code}${change.scope ? ` (${change.scope})` : ''}`;
|
|
53
|
+
console.log(` ${STATUS[change.status].padEnd(22)} ${problem.padEnd(36)} ${change.severity === 'defect' ? 'suspected defect' : 'lead'}`);
|
|
54
|
+
console.log(` ${''.padEnd(22)} ${labels.before}: ${describeSide(change.before)}; ${labels.after}: ${describeSide(change.after)}`);
|
|
55
|
+
}
|
|
56
|
+
const { outcomes } = comparison;
|
|
57
|
+
if (outcomes.before.length || outcomes.after.length)
|
|
58
|
+
console.log(`\n Other outcomes: ${labels.before} ${outcomes.before.join(', ') || 'none'}; ${labels.after} ${outcomes.after.join(', ') || 'none'}`);
|
|
59
|
+
const sides = [
|
|
60
|
+
[labels.before, comparison.before],
|
|
61
|
+
[labels.after, comparison.after],
|
|
62
|
+
];
|
|
63
|
+
for (const [label, runs] of sides)
|
|
64
|
+
for (const run of runs)
|
|
65
|
+
if (run.gaps.length)
|
|
66
|
+
console.log(`\n ${label} ${run.complete ? 'partial' : 'incomplete'}, ${run.path}:\n ${run.gaps.join('\n ')}`);
|
|
67
|
+
console.log(`\n${comparison.verdict}: ${comparison.summary}`);
|
|
68
|
+
if (comparison.limitation)
|
|
69
|
+
console.log(`Covers only this check. ${comparison.limitation}`);
|
|
70
|
+
}
|
|
71
|
+
export async function compareMain(args) {
|
|
72
|
+
if (args.includes('--help')) {
|
|
73
|
+
console.log(HELP);
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
76
|
+
const options = parseArgs(args);
|
|
77
|
+
const comparison = await compareReports(options.before, options.after, options.labels);
|
|
78
|
+
if (options.format === 'json')
|
|
79
|
+
console.log(JSON.stringify(comparison, null, 2));
|
|
80
|
+
else if (options.format === 'markdown')
|
|
81
|
+
process.stdout.write(comparison.markdown);
|
|
82
|
+
else
|
|
83
|
+
printText(comparison);
|
|
84
|
+
process.exitCode = comparison.exitCode;
|
|
85
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { mkdir, writeFile } from 'node:fs/promises';
|
|
2
|
+
// The examples stay plain JavaScript, so this one is loaded by URL at run time.
|
|
3
|
+
const { runCoreDemo } = (await import(new URL('../../examples/core-demo.mjs', import.meta.url).href));
|
|
4
|
+
const report = await runCoreDemo();
|
|
5
|
+
await mkdir('artifacts', { recursive: true });
|
|
6
|
+
await writeFile('artifacts/core-demo.json', JSON.stringify(report, null, 2) + '\n');
|
|
7
|
+
console.log(JSON.stringify(report, null, 2));
|
|
8
|
+
process.exitCode = report.expectedDemonstrationVerified ? 0 : 1;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function desktopMain(args: string[]): Promise<void>;
|