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.
Files changed (88) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/CONTRIBUTING.md +1 -1
  3. package/README.md +6 -4
  4. package/bin/recovery-probe.mjs +2 -217
  5. package/dist/cli/android.d.mts +1 -0
  6. package/dist/cli/android.mjs +112 -0
  7. package/dist/cli/attach.d.mts +1 -0
  8. package/dist/cli/attach.mjs +85 -0
  9. package/dist/cli/compare.d.mts +1 -0
  10. package/dist/cli/compare.mjs +85 -0
  11. package/dist/cli/core-demo.d.mts +1 -0
  12. package/dist/cli/core-demo.mjs +8 -0
  13. package/dist/cli/desktop.d.mts +1 -0
  14. package/dist/cli/desktop.mjs +124 -0
  15. package/dist/cli/ipc.d.mts +1 -0
  16. package/dist/cli/ipc.mjs +120 -0
  17. package/dist/cli/main.d.mts +1 -0
  18. package/dist/cli/main.mjs +217 -0
  19. package/dist/cli/mcp.d.mts +1 -0
  20. package/dist/cli/mcp.mjs +29 -0
  21. package/dist/cli/net.d.mts +1 -0
  22. package/dist/cli/net.mjs +130 -0
  23. package/dist/cli/observe.d.mts +1 -0
  24. package/dist/cli/observe.mjs +266 -0
  25. package/dist/cli/refresh.d.mts +1 -0
  26. package/dist/cli/refresh.mjs +150 -0
  27. package/dist/cli/repair.d.mts +1 -0
  28. package/dist/cli/repair.mjs +90 -0
  29. package/dist/cli/start.d.mts +1 -0
  30. package/dist/cli/start.mjs +38 -0
  31. package/dist/cli/suspects.d.mts +1 -0
  32. package/dist/cli/suspects.mjs +65 -0
  33. package/dist/cli/until-stopped.d.mts +3 -0
  34. package/dist/cli/until-stopped.mjs +17 -0
  35. package/dist/cli/watch.d.mts +1 -0
  36. package/dist/cli/watch.mjs +143 -0
  37. package/dist/cli/web.d.mts +1 -0
  38. package/dist/cli/web.mjs +107 -0
  39. package/dist/desktop.d.mts +67 -61
  40. package/dist/desktop.mjs +394 -405
  41. package/dist/guided-start.d.mts +42 -0
  42. package/dist/guided-start.mjs +244 -321
  43. package/dist/http-discover.d.mts +111 -0
  44. package/dist/http-discover.mjs +310 -343
  45. package/dist/index.d.mts +49 -0
  46. package/dist/index.mjs +219 -235
  47. package/dist/pick-marker.d.mts +10 -0
  48. package/dist/pick-marker.mjs +86 -103
  49. package/dist/refresh.d.mts +156 -0
  50. package/dist/refresh.mjs +388 -412
  51. package/dist/repair-process.d.mts +17 -0
  52. package/dist/repair-process.mjs +89 -98
  53. package/dist/repair-provider.d.mts +53 -0
  54. package/dist/repair-provider.mjs +66 -88
  55. package/dist/repair.d.mts +72 -0
  56. package/dist/repair.mjs +412 -519
  57. package/dist/web.d.mts +19 -22
  58. package/dist/web.mjs +40 -46
  59. package/docs/android.md +2 -2
  60. package/docs/ci.md +1 -1
  61. package/docs/compare.md +1 -1
  62. package/docs/desktop.md +2 -2
  63. package/docs/ipc.md +4 -4
  64. package/docs/mcp.md +1 -1
  65. package/docs/net.md +2 -2
  66. package/docs/observe.md +3 -3
  67. package/docs/repair.md +1 -1
  68. package/docs/start.md +2 -2
  69. package/docs/suspects.md +1 -1
  70. package/docs/watch.md +1 -1
  71. package/package.json +5 -5
  72. package/bin/android.mjs +0 -140
  73. package/bin/attach.mjs +0 -79
  74. package/bin/compare.mjs +0 -98
  75. package/bin/core-demo.mjs +0 -11
  76. package/bin/desktop.mjs +0 -157
  77. package/bin/ipc.mjs +0 -134
  78. package/bin/mcp.mjs +0 -35
  79. package/bin/net.mjs +0 -149
  80. package/bin/observe.mjs +0 -331
  81. package/bin/refresh.mjs +0 -162
  82. package/bin/repair.mjs +0 -112
  83. package/bin/start.mjs +0 -39
  84. package/bin/suspects.mjs +0 -71
  85. package/bin/until-stopped.mjs +0 -15
  86. package/bin/watch.mjs +0 -163
  87. package/bin/web.mjs +0 -120
  88. 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 moving from JavaScript to TypeScript, one module at a time; write new modules as `.mts` (or `.cts` for CommonJS). `npm run build` compiles them into `dist` with strict checks and generated declarations, and copies the remaining JavaScript, hand-written declarations and report templates unchanged. `npm ci` builds once, and every script that runs code builds first, so tests never use a stale `dist`. `npm run typecheck` also checks the JavaScript in `src`, `bin` and `examples` with strict mode off; add JSDoc types where inference is not enough. TypeScript is pinned to 6.0 because typescript-eslint, which lints the TypeScript files, does not support 7 yet. Markdown, HTML fixtures, report templates and workflow files are left as written. Report markup lives in `src/report-templates`: `{{slot}}` takes text and escapes it, `{{{slot}}}` takes markup built with `escapeHtml`. `.gitattributes` keeps LF line endings on every platform so local checks match CI. The repository-wide reformat is listed in `.git-blame-ignore-revs`; run `git config blame.ignoreRevsFile .git-blame-ignore-revs` to skip it in local blame.
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.4.0 playwright@1.62.1
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-050-preview8) |
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-050-preview11) |
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.4.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.
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.
@@ -1,218 +1,3 @@
1
1
  #!/usr/bin/env node
2
- import { readFile, writeFile, mkdir } from 'node:fs/promises'
3
- import { dirname } from 'node:path'
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>;