recovery-probe 0.4.0-preview.1 → 0.4.0-preview.3

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 (53) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/CONTRIBUTING.md +5 -0
  3. package/README.md +6 -3
  4. package/bin/attach.mjs +69 -36
  5. package/bin/core-demo.mjs +10 -7
  6. package/bin/desktop.mjs +125 -50
  7. package/bin/ipc.mjs +91 -40
  8. package/bin/observe.mjs +218 -80
  9. package/bin/recovery-probe.mjs +111 -80
  10. package/bin/refresh.mjs +156 -41
  11. package/bin/repair.mjs +82 -36
  12. package/bin/start.mjs +21 -14
  13. package/bin/web.mjs +96 -49
  14. package/docs/observe.md +1 -1
  15. package/examples/ci/run.mjs +117 -57
  16. package/examples/ci/verify.mjs +35 -22
  17. package/examples/core-demo.mjs +55 -28
  18. package/examples/demo-server.mjs +39 -25
  19. package/examples/profile-controller.mjs +25 -15
  20. package/package.json +15 -3
  21. package/src/desktop-report.mjs +59 -16
  22. package/src/desktop.d.mts +61 -18
  23. package/src/desktop.mjs +367 -156
  24. package/src/discovery-control.mjs +32 -15
  25. package/src/discovery-report.mjs +46 -9
  26. package/src/fetch-fault.d.mts +18 -15
  27. package/src/fetch-fault.mjs +69 -35
  28. package/src/guided-start.mjs +289 -115
  29. package/src/http-discover.mjs +338 -90
  30. package/src/http-observer.mjs +187 -57
  31. package/src/index.d.ts +49 -21
  32. package/src/index.mjs +183 -86
  33. package/src/ipc-check.mjs +249 -85
  34. package/src/ipc-control.mjs +25 -9
  35. package/src/ipc-discover.mjs +386 -127
  36. package/src/ipc-inspector.d.mts +31 -10
  37. package/src/ipc-inspector.mjs +138 -51
  38. package/src/ipc-observation.mjs +291 -117
  39. package/src/ipc-probe.cjs +366 -143
  40. package/src/ipc-probe.d.cts +98 -29
  41. package/src/observation-kit.mjs +143 -63
  42. package/src/observation-report.mjs +282 -109
  43. package/src/observe-steps.mjs +130 -53
  44. package/src/observe.mjs +896 -295
  45. package/src/pick-marker.mjs +111 -61
  46. package/src/refresh-adapters.mjs +56 -27
  47. package/src/refresh.mjs +401 -118
  48. package/src/repair-process.mjs +88 -28
  49. package/src/repair-provider.mjs +84 -25
  50. package/src/repair.mjs +469 -186
  51. package/src/visibility.mjs +112 -38
  52. package/src/web.d.mts +22 -8
  53. package/src/web.mjs +41 -18
package/CHANGELOG.md CHANGED
@@ -4,6 +4,18 @@ 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.4.0-preview.3 (2026-10-15)
8
+
9
+ - Restore an existing instance-level `webContents.send` (for example an app's tracing wrapper) when an observation ends or the hook is disposed, instead of deleting it. Previously that wrapper was lost and later pushes bypassed it. A wrapper installed after the observation began is left in place.
10
+ - Broaden the project description: recovery after failed reads, cached content, and screens that lag behind their data. Observation and `DELAYED_UI_UPDATE` remain fault-free leads, not verdicts.
11
+
12
+ ## 0.4.0-preview.2 (2026-10-15)
13
+
14
+ - Apply consistent Prettier formatting and add formatting, ESLint and JavaScript type checks to CI.
15
+ - Add JSDoc annotations for implementation type checking without a build step; strict mode remains off.
16
+ - Preserve original causes in two wrapped errors and make small lint-driven cleanups. No new observation or fault-injection features.
17
+ - Publish the maintenance changes from PRs #22–#24 on the opt-in `next` channel; stable `latest` remains 0.3.0.
18
+
7
19
  ## 0.4.0-preview.1 (2026-10-15)
8
20
 
9
21
  - Record configured user actions during observation (name, time, real-input flag) and report the tracked rows that appeared or changed after each action.
package/CONTRIBUTING.md CHANGED
@@ -13,12 +13,17 @@ Thanks for helping make recovery checks easier to trust.
13
13
 
14
14
  ```bash
15
15
  npm ci
16
+ npm run format:check
17
+ npm run lint
18
+ npm run typecheck
16
19
  npm test
17
20
  npm run test:package
18
21
  npx playwright install chromium
19
22
  npm run test:browser
20
23
  ```
21
24
 
25
+ 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. TypeScript checks the JavaScript in `src`, `bin` and `examples` (`npm run typecheck`, `checkJs` without emitting); add JSDoc types where inference is not enough. Strict mode is off for now and can be tightened file by file. Markdown, HTML fixtures and workflow files are left as written. `.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.
26
+
22
27
  ## Install an unpublished source preview
23
28
 
24
29
  When the version shown in the README is not on npm yet, install from a local checkout:
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Recovery Probe
2
2
 
3
- **Test how web and desktop applications recover when data reads fail—during loading and refresh.**
3
+ **Test whether web and desktop apps show the right data: recovery after failed reads, cached content, and screens that lag behind their data.**
4
4
 
5
- Recovery Probe injects bounded faults, compares healthy and faulted screens, and records whether content survives or returns. It helps developers and coding agents reproduce recovery problems such as disappearing lists, stuck loading states and missing retries. Installing the package does not add recovery behavior to your application.
5
+ Recovery Probe works in two ways. It injects bounded faults into data reads, compares healthy and faulted screens, and records whether content survives or returns. It also observes reads and the screen without any fault, timing what the user sees after an action against the data the app has already received. It helps developers and coding agents reproduce problems such as disappearing lists, stuck loading states, missing retries, content served from a cache and row states that stay stale after fresh data arrives. Installing the package does not add recovery behavior to your application.
6
6
 
7
7
  [![CI](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml/badge.svg)](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
8
8
  [![npm](https://img.shields.io/npm/v/recovery-probe.svg)](https://www.npmjs.com/package/recovery-probe)
@@ -16,6 +16,7 @@ Recovery Probe injects bounded faults, compares healthy and faulted screens, and
16
16
  | Electron desktop apps using renderer HTTP | The same request and UI checks | Attach through a loopback debugging endpoint |
17
17
  | Electron desktop apps using IPC reads | Renderer behavior after selected IPC rejections or null results | Add a development-only handler-registration hook and enable local inspection |
18
18
  | JavaScript code using fetch | Recovery logic around an explicitly supplied fetch wrapper | Import `recovery-probe/fetch`; Playwright is not required |
19
+ | Web and Electron apps, without faults | Selected reads, cached content and tracked row states after user actions, including delayed UI updates | Attach as above; IPC observation uses the same development hook |
19
20
 
20
21
  Desktop support currently means Electron, not arbitrary native applications. IPC faults do not exercise native/Rust networking, HTTP status handling or token refresh. An unsupported data path is inconclusive, never a successful recovery check.
21
22
 
@@ -32,6 +33,8 @@ npx recovery-probe --version
32
33
 
33
34
  If the version check reports that the version is unavailable, npm publication is still pending; use the [source installation](CONTRIBUTING.md#install-an-unpublished-source-preview). A GitHub merge alone does not publish the package. Use Node.js 22 or newer. A separate tools folder keeps the tester out of your application's production dependencies. Browser/desktop commands require Playwright; attached targets use their existing browser runtime. The guided web flow downloads Chromium when needed. See [CHANGELOG.md](CHANGELOG.md) for version history.
34
35
 
36
+ For the 0.4 observation preview, install `recovery-probe@0.4.0-preview.3` (the `next` channel) with the same Playwright version. Preview.3 restores an app's own `webContents.send` wrapper after an observation and updates the project description; preview.2 added formatting, lint and implementation type checks; the action/row observation features were introduced in preview.1.
37
+
35
38
  ## Choose a workflow
36
39
 
37
40
  **New in 0.3.0:** guided setup, HTTP/IPC discovery, refresh experiments and [fault-free observation](docs/observe.md) extend the original recovery helpers. Observation records selected reads and content while you navigate without reloading or clearing caches. Lightweight sampling, phase timings and separate cleanup evidence make capture cost and scope explicit. Use `"detail": "region"` for full DOM diagnostics.
@@ -227,7 +230,7 @@ Runs the baseline and the three default recovery checks used by the JSON CLI. Fo
227
230
 
228
231
  ## Scope
229
232
 
230
- Recovery Probe deliberately focuses on deterministic request-level recovery checks. It does not simulate whole-device offline states, WebSocket interruptions, token expiry, browser sleep, slow-network profiles, or duplicate-submission safety.
233
+ Recovery Probe focuses on deterministic request-level recovery checks and on fault-free observation of whether the screen reflects the reads it received. It does not simulate whole-device offline states, WebSocket interruptions, token expiry, browser sleep, slow-network profiles, or duplicate-submission safety. Observation findings such as `DELAYED_UI_UPDATE` are leads that need review against the application logic, not verdicts: read contents are never recorded.
231
234
 
232
235
  Playwright already provides the routing primitives used here. Recovery Probe adds bounded recipes, fault-occurrence verification, cleanup, consistent result codes, a fetch adapter, and a runnable broken-versus-fixed example. If a few direct `page.route()` calls are clearer for your test, use them; this package is most useful when teams want the recovery pattern to be repeatable.
233
236
 
package/bin/attach.mjs CHANGED
@@ -1,42 +1,75 @@
1
- import { readFile, mkdir } from 'node:fs/promises';
2
- import { resolve } from 'node:path';
3
- import { connectDesktop, selectDesktopPage } from '../src/desktop.mjs';
4
- import { discoverHttp, httpDiscoveryConfig } from '../src/http-discover.mjs';
5
- import { writeDiscoveryReport } from '../src/discovery-report.mjs';
6
- import { prepareVisibility } from '../src/visibility.mjs';
7
- import { checkDesktop } from '../src/desktop.mjs';
8
- import { writeDesktopReport } from '../src/desktop-report.mjs';
1
+ import { readFile, mkdir } from 'node:fs/promises'
2
+ import { resolve } from 'node:path'
3
+ import { connectDesktop, selectDesktopPage } from '../src/desktop.mjs'
4
+ import { discoverHttp, httpDiscoveryConfig } from '../src/http-discover.mjs'
5
+ import { writeDiscoveryReport } from '../src/discovery-report.mjs'
6
+ import { prepareVisibility } from '../src/visibility.mjs'
7
+ import { checkDesktop } from '../src/desktop.mjs'
8
+ import { writeDesktopReport } from '../src/desktop-report.mjs'
9
9
  export async function attachMain(args) {
10
- const options = {};
10
+ const options = {}
11
11
  for (let i = 0; i < args.length; i++) {
12
- const arg = args[i];
13
- if (arg === '--discover' || arg === '--restore-window') options[arg.slice(2)] = true;
14
- else if (['--config', '--cdp', '--out', '--page'].includes(arg) && args[i + 1] && !args[i + 1].startsWith('--')) options[arg.slice(2)] = args[++i];
15
- else throw new Error('Use web --attach [--discover] --config FILE [--cdp URL] [--page N] [--restore-window] [--out NEW_DIRECTORY]');
12
+ const arg = args[i]
13
+ if (arg === '--discover' || arg === '--restore-window')
14
+ options[arg.slice(2)] = true
15
+ else if (
16
+ ['--config', '--cdp', '--out', '--page'].includes(arg) &&
17
+ args[i + 1] &&
18
+ !args[i + 1].startsWith('--')
19
+ )
20
+ options[arg.slice(2)] = args[++i]
21
+ else
22
+ throw new Error(
23
+ 'Use web --attach [--discover] --config FILE [--cdp URL] [--page N] [--restore-window] [--out NEW_DIRECTORY]',
24
+ )
16
25
  }
17
- if (!options.config) throw new Error('--config is required');
18
- let config = JSON.parse(await readFile(options.config, 'utf8'));
19
- if (options.cdp) config.cdp = options.cdp;
20
- if (options.page !== undefined) { if (!/^\d+$/.test(options.page)) throw new Error('Invalid page'); config.page = Number(options.page); }
21
- if (options['restore-window']) config.restoreWindow = true;
22
- if (options.discover) config = httpDiscoveryConfig(config);
23
- const directory = resolve(options.out ?? `.recovery-probe/attached-${Date.now()}`);
24
- await mkdir(resolve(directory, '..'), { recursive: true, mode: 0o700 });
25
- await mkdir(directory, { mode: 0o700 });
26
- const browser = await connectDesktop(config.cdp);
26
+ if (!options.config) throw new Error('--config is required')
27
+ let config = JSON.parse(await readFile(options.config, 'utf8'))
28
+ if (options.cdp) config.cdp = options.cdp
29
+ if (options.page !== undefined) {
30
+ if (!/^\d+$/.test(options.page)) throw new Error('Invalid page')
31
+ config.page = Number(options.page)
32
+ }
33
+ if (options['restore-window']) config.restoreWindow = true
34
+ if (options.discover) config = httpDiscoveryConfig(config)
35
+ const directory = resolve(
36
+ options.out ?? `.recovery-probe/attached-${Date.now()}`,
37
+ )
38
+ await mkdir(resolve(directory, '..'), { recursive: true, mode: 0o700 })
39
+ await mkdir(directory, { mode: 0o700 })
40
+ const browser = await connectDesktop(config.cdp)
27
41
  try {
28
- const page = selectDesktopPage(browser, config);
29
- let report;
30
- if (options.discover) { report = await discoverHttp(page, config); await writeDiscoveryReport(directory, report, config); }
31
- else {
32
- const visibility = await prepareVisibility(page, config);
33
- try { report = await checkDesktop(page, config); report.mode = 'attached browser recovery'; }
34
- finally { await visibility.revert(); }
35
- await writeDesktopReport(directory, report, config);
42
+ const page = selectDesktopPage(browser, config)
43
+ let report
44
+ if (options.discover) {
45
+ report = await discoverHttp(page, config)
46
+ await writeDiscoveryReport(directory, report, config)
47
+ } else {
48
+ const visibility = await prepareVisibility(page, config)
49
+ try {
50
+ report = await checkDesktop(page, config)
51
+ report.mode = 'attached browser recovery'
52
+ } finally {
53
+ await visibility.revert()
54
+ }
55
+ await writeDesktopReport(directory, report, config)
36
56
  }
37
- for (const f of report.findings ?? report.results) console.log(`${f.id ?? f.kind}: ${f.classification ?? f.code}${f.partial ? `; runs=${f.completedRuns}/${f.plannedRuns} partial; observed=${f.observedInterpretation.classification}` : ''}`);
38
- if (report.error) console.error(report.error);
39
- console.log(`Final reload: ${report.finalReset}\nReport: ${directory}/report.html`);
40
- process.exitCode = report.ok ? 0 : options.discover ? 2 : report.results.some(r => r.outcome === 'fail') ? 1 : 2;
41
- } finally { await browser.close(); }
57
+ for (const f of report.findings ?? report.results)
58
+ console.log(
59
+ `${f.id ?? f.kind}: ${f.classification ?? f.code}${f.partial ? `; runs=${f.completedRuns}/${f.plannedRuns} partial; observed=${f.observedInterpretation.classification}` : ''}`,
60
+ )
61
+ if (report.error) console.error(report.error)
62
+ console.log(
63
+ `Final reload: ${report.finalReset}\nReport: ${directory}/report.html`,
64
+ )
65
+ process.exitCode = report.ok
66
+ ? 0
67
+ : options.discover
68
+ ? 2
69
+ : report.results.some((r) => r.outcome === 'fail')
70
+ ? 1
71
+ : 2
72
+ } finally {
73
+ await browser.close()
74
+ }
42
75
  }
package/bin/core-demo.mjs CHANGED
@@ -1,8 +1,11 @@
1
1
  #!/usr/bin/env node
2
- import { mkdir, writeFile } from 'node:fs/promises';
3
- import { runCoreDemo } from '../examples/core-demo.mjs';
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;
2
+ import { mkdir, writeFile } from 'node:fs/promises'
3
+ import { runCoreDemo } from '../examples/core-demo.mjs'
4
+ const report = await runCoreDemo()
5
+ await mkdir('artifacts', { recursive: true })
6
+ await writeFile(
7
+ 'artifacts/core-demo.json',
8
+ JSON.stringify(report, null, 2) + '\n',
9
+ )
10
+ console.log(JSON.stringify(report, null, 2))
11
+ process.exitCode = report.expectedDemonstrationVerified ? 0 : 1
package/bin/desktop.mjs CHANGED
@@ -1,7 +1,15 @@
1
- import { readFile, writeFile, mkdir } from 'node:fs/promises';
2
- import { resolve, join } from 'node:path';
3
- import { connectDesktop, desktopPages, selectDesktopPage, pageIdentity, discoverDesktop, checkDesktop, validateDesktopConfig } from '../src/desktop.mjs';
4
- import { writeDesktopReport } from '../src/desktop-report.mjs';
1
+ import { readFile, writeFile, mkdir } from 'node:fs/promises'
2
+ import { resolve, join } from 'node:path'
3
+ import {
4
+ connectDesktop,
5
+ desktopPages,
6
+ selectDesktopPage,
7
+ pageIdentity,
8
+ discoverDesktop,
9
+ checkDesktop,
10
+ validateDesktopConfig,
11
+ } from '../src/desktop.mjs'
12
+ import { writeDesktopReport } from '../src/desktop-report.mjs'
5
13
 
6
14
  export async function desktopMain(args) {
7
15
  if (!args.length || args.includes('--help')) {
@@ -18,65 +26,132 @@ Checks reload it once per baseline/fault, optionally click the configured Retry
18
26
  and perform a final reload reset. The app stays open. Use a test account/environment.
19
27
  The config selects one endpoint and a data-dependent readySelector; see docs/desktop.md.
20
28
  Requests made by native SDKs/IPC and untouched app screens are outside this check.
21
- Reports stay local. Screenshots are opt-in and may contain private on-screen content.`);
22
- return;
29
+ Reports stay local. Screenshots are opt-in and may contain private on-screen content.`)
30
+ return
23
31
  }
24
- const options = {};
25
- const values = new Set(['--cdp', '--page', '--duration', '--out', '--config']);
32
+ const options = {}
33
+ const values = new Set(['--cdp', '--page', '--duration', '--out', '--config'])
26
34
  for (let i = 0; i < args.length; i++) {
27
- const arg = args[i];
28
- const key = arg.slice(2);
29
- if (['--list', '--discover', '--screenshots'].includes(arg)) options[key] = true;
35
+ const arg = args[i]
36
+ const key = arg.slice(2)
37
+ if (['--list', '--discover', '--screenshots'].includes(arg))
38
+ options[key] = true
30
39
  else if (values.has(arg)) {
31
- if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${arg} needs a value`);
32
- options[key] = args[++i];
33
- } else throw new Error(`Unknown desktop option: ${arg}`);
40
+ if (!args[i + 1] || args[i + 1].startsWith('--'))
41
+ throw new Error(`${arg} needs a value`)
42
+ options[key] = args[++i]
43
+ } else throw new Error(`Unknown desktop option: ${arg}`)
34
44
  }
35
- if ([options.list, options.discover, options.config].filter(Boolean).length !== 1) throw new Error('Choose one of --list, --discover, or --config');
45
+ if (
46
+ [options.list, options.discover, options.config].filter(Boolean).length !==
47
+ 1
48
+ )
49
+ throw new Error('Choose one of --list, --discover, or --config')
36
50
  if (options.page !== undefined) {
37
- if (!/^\d+$/.test(options.page)) throw new Error('--page must be a non-negative integer');
38
- options.page = Number(options.page);
51
+ if (!/^\d+$/.test(options.page))
52
+ throw new Error('--page must be a non-negative integer')
53
+ options.page = Number(options.page)
39
54
  }
40
- if (options.duration !== undefined && (!/^\d+$/.test(options.duration) || Number(options.duration) < 200 || Number(options.duration) > 30000)) throw new Error('--duration must be 200–30000 ms');
41
- let config = options.config ? JSON.parse(await readFile(options.config, 'utf8')) : {};
42
- if (options.page !== undefined) config.page = options.page;
43
- config.cdp = options.cdp ?? config.cdp ?? 'http://127.0.0.1:9222';
44
- if (options.config) config = validateDesktopConfig(config);
45
- const browser = await connectDesktop(config.cdp);
55
+ if (
56
+ options.duration !== undefined &&
57
+ (!/^\d+$/.test(options.duration) ||
58
+ Number(options.duration) < 200 ||
59
+ Number(options.duration) > 30000)
60
+ )
61
+ throw new Error('--duration must be 200–30000 ms')
62
+ let config = options.config
63
+ ? JSON.parse(await readFile(options.config, 'utf8'))
64
+ : {}
65
+ if (options.page !== undefined) config.page = options.page
66
+ config.cdp = options.cdp ?? config.cdp ?? 'http://127.0.0.1:9222'
67
+ if (options.config) config = validateDesktopConfig(config)
68
+ const browser = await connectDesktop(config.cdp)
46
69
  try {
47
70
  if (options.list) {
48
- const pages = desktopPages(browser);
49
- if (!pages.length) throw new Error('No renderer pages found');
50
- pages.forEach((page, index) => console.log(`${index} ${pageIdentity(page.url())}`));
51
- return;
71
+ const pages = desktopPages(browser)
72
+ if (!pages.length) throw new Error('No renderer pages found')
73
+ pages.forEach((page, index) =>
74
+ console.log(`${index} ${pageIdentity(page.url())}`),
75
+ )
76
+ return
52
77
  }
53
- const page = selectDesktopPage(browser, config);
54
- const directory = resolve(options.out ?? `.recovery-probe/${new Date().toISOString().replace(/[:.]/g, '-')}`);
55
- await mkdir(directory, { recursive: true, mode: 0o700 });
78
+ const page = selectDesktopPage(browser, config)
79
+ const directory = resolve(
80
+ options.out ??
81
+ `.recovery-probe/${new Date().toISOString().replace(/[:.]/g, '-')}`,
82
+ )
83
+ await mkdir(directory, { recursive: true, mode: 0o700 })
56
84
  if (options.discover) {
57
- const discovery = await discoverDesktop(page, { durationMs: Number(options.duration ?? 5000) });
58
- await writeFile(join(directory, 'discovery.json'), JSON.stringify(discovery, null, 2) + '\n', { mode: 0o600 });
59
- const template = { cdp: config.cdp, page: desktopPages(browser).indexOf(page), pageUrl: discovery.pageUrl, endpoint: discovery.endpoints.length === 1 ? discovery.endpoints[0].endpoint : '', readySelector: '', retrySelector: '', recovery: 'retry', timeoutMs: 5000 };
60
- await writeFile(join(directory, 'scenario.json'), JSON.stringify(template, null, 2) + '\n', { mode: 0o600 });
61
- discovery.endpoints.forEach((row, index) => console.log(`${index + 1}. GET ${row.endpoint} (${row.observed} response(s), query values omitted)`));
62
- if (!discovery.endpoints.length) console.log('No matching renderer GET JSON responses observed. The screen may use cached data, native SDK/IPC requests, a service worker, or load after the discovery window. This is not a pass.');
63
- console.log(`\nDiscovery: ${join(directory, 'discovery.json')}\nFill endpoint (if blank), readySelector and retrySelector in ${join(directory, 'scenario.json')}`);
64
- return;
85
+ const discovery = await discoverDesktop(page, {
86
+ durationMs: Number(options.duration ?? 5000),
87
+ })
88
+ await writeFile(
89
+ join(directory, 'discovery.json'),
90
+ JSON.stringify(discovery, null, 2) + '\n',
91
+ { mode: 0o600 },
92
+ )
93
+ const template = {
94
+ cdp: config.cdp,
95
+ page: desktopPages(browser).indexOf(page),
96
+ pageUrl: discovery.pageUrl,
97
+ endpoint:
98
+ discovery.endpoints.length === 1
99
+ ? discovery.endpoints[0].endpoint
100
+ : '',
101
+ readySelector: '',
102
+ retrySelector: '',
103
+ recovery: 'retry',
104
+ timeoutMs: 5000,
105
+ }
106
+ await writeFile(
107
+ join(directory, 'scenario.json'),
108
+ JSON.stringify(template, null, 2) + '\n',
109
+ { mode: 0o600 },
110
+ )
111
+ discovery.endpoints.forEach((row, index) =>
112
+ console.log(
113
+ `${index + 1}. GET ${row.endpoint} (${row.observed} response(s), query values omitted)`,
114
+ ),
115
+ )
116
+ if (!discovery.endpoints.length)
117
+ console.log(
118
+ 'No matching renderer GET JSON responses observed. The screen may use cached data, native SDK/IPC requests, a service worker, or load after the discovery window. This is not a pass.',
119
+ )
120
+ console.log(
121
+ `\nDiscovery: ${join(directory, 'discovery.json')}\nFill endpoint (if blank), readySelector and retrySelector in ${join(directory, 'scenario.json')}`,
122
+ )
123
+ return
65
124
  }
66
- console.log('Checking the current development renderer. It will reload between faults.');
125
+ console.log(
126
+ 'Checking the current development renderer. It will reload between faults.',
127
+ )
67
128
  const report = await checkDesktop(page, config, {
68
- onFailure: options.screenshots ? async (target, row) => {
69
- const filename = `${row.kind}.png`;
70
- await target.screenshot({ path: join(directory, filename), timeout: 5000 });
71
- row.screenshot = filename;
72
- } : undefined,
73
- });
74
- await writeDesktopReport(directory, report, config);
75
- for (const row of report.results) console.log(`${row.outcome.toUpperCase().padEnd(12)} ${row.kind}: ${row.code} (injected ${row.applied}, later successful responses ${row.successfulResponsesAfterFault})`);
76
- console.log(`Final reload reset: ${report.finalReset}\nReport: ${join(directory, 'report.html')}\nReproduce: node ${join(directory, 'reproduce.mjs')}\nFix investigation: ${join(directory, 'fix-brief.md')}`);
77
- process.exitCode = report.ok ? 0 : report.results.some(row => row.outcome === 'fail') ? 1 : 2;
129
+ onFailure: options.screenshots
130
+ ? async (target, row) => {
131
+ const filename = `${row.kind}.png`
132
+ await target.screenshot({
133
+ path: join(directory, filename),
134
+ timeout: 5000,
135
+ })
136
+ row.screenshot = filename
137
+ }
138
+ : undefined,
139
+ })
140
+ await writeDesktopReport(directory, report, config)
141
+ for (const row of report.results)
142
+ console.log(
143
+ `${row.outcome.toUpperCase().padEnd(12)} ${row.kind}: ${row.code} (injected ${row.applied}, later successful responses ${row.successfulResponsesAfterFault})`,
144
+ )
145
+ console.log(
146
+ `Final reload reset: ${report.finalReset}\nReport: ${join(directory, 'report.html')}\nReproduce: node ${join(directory, 'reproduce.mjs')}\nFix investigation: ${join(directory, 'fix-brief.md')}`,
147
+ )
148
+ process.exitCode = report.ok
149
+ ? 0
150
+ : report.results.some((row) => row.outcome === 'fail')
151
+ ? 1
152
+ : 2
78
153
  } finally {
79
154
  // Closing a CDP connection disconnects this client; it does not close the existing app.
80
- await browser.close();
155
+ await browser.close()
81
156
  }
82
157
  }
package/bin/ipc.mjs CHANGED
@@ -1,9 +1,16 @@
1
- import { writeDiscoveryReport } from '../src/discovery-report.mjs';
2
- import { readFile, mkdir, writeFile, mkdtemp } from 'node:fs/promises';
3
- import { resolve, join } from 'node:path';
4
- import { discoverIpc, discoveryConfig } from '../src/ipc-discover.mjs';
5
- import { checkIpc } from '../src/ipc-check.mjs';
6
- const escape = value => String(value).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
1
+ import { writeDiscoveryReport } from '../src/discovery-report.mjs'
2
+ import { readFile, mkdir, writeFile, mkdtemp } from 'node:fs/promises'
3
+ import { resolve, join } from 'node:path'
4
+ import { discoverIpc, discoveryConfig } from '../src/ipc-discover.mjs'
5
+ import { checkIpc } from '../src/ipc-check.mjs'
6
+ const escape = (value) =>
7
+ String(value).replace(
8
+ /[&<>"']/g,
9
+ (c) =>
10
+ ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[
11
+ c
12
+ ],
13
+ )
7
14
  export async function ipcMain(args) {
8
15
  if (!args.length || args.includes('--help')) {
9
16
  console.log(`Recovery Probe IPC preview
@@ -14,43 +21,87 @@ Electron CDP (usually 9222) and Node inspector (usually 9229).
14
21
  Default: verify one IPC rejection; null-result is explicitly optional.
15
22
  --discover: compare healthy controls with single/double rejection and null-result experiments.
16
23
  Discovery uses structural comparisons and language hints; findings require review. No readiness selector needed.
17
- No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and scope.`);
18
- return;
24
+ No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and scope.`)
25
+ return
19
26
  }
20
- const options = {};
27
+ const options = {}
21
28
  for (let i = 0; i < args.length; i++) {
22
- if (args[i] === '--restore-window') { options.restoreWindow = true; continue; }
23
- if (args[i] === '--discover') { options.discover = true; continue; }
24
- if (!['--config', '--out'].includes(args[i]) || !args[i + 1] || args[i + 1].startsWith('--')) throw new Error('Use ipc --config FILE [--out NEW_DIRECTORY] [--discover]');
25
- options[args[i].slice(2)] = args[++i];
29
+ if (args[i] === '--restore-window') {
30
+ options.restoreWindow = true
31
+ continue
32
+ }
33
+ if (args[i] === '--discover') {
34
+ options.discover = true
35
+ continue
36
+ }
37
+ if (
38
+ !['--config', '--out'].includes(args[i]) ||
39
+ !args[i + 1] ||
40
+ args[i + 1].startsWith('--')
41
+ )
42
+ throw new Error(
43
+ 'Use ipc --config FILE [--out NEW_DIRECTORY] [--discover]',
44
+ )
45
+ options[args[i].slice(2)] = args[++i]
26
46
  }
27
- if (!options.config) throw new Error('--config is required');
28
- const rawConfig = JSON.parse(await readFile(options.config, 'utf8'));
29
- if (options.restoreWindow) rawConfig.restoreWindow = true;
30
- const config = options.discover ? discoveryConfig(rawConfig) : rawConfig;
31
- const parent = resolve('.recovery-probe');
32
- let directory;
33
- if (options.out) { directory = resolve(options.out); await mkdir(directory, { mode: 0o700 }); }
34
- else { await mkdir(parent, { recursive: true, mode: 0o700 }); directory = await mkdtemp(join(parent, 'ipc-')); }
35
- await writeFile(join(directory, '.gitignore'), '*\n', { mode: 0o600 });
36
- const report = options.discover ? await discoverIpc(config) : await checkIpc(config);
37
- await writeFile(join(directory, 'scenario.json'), JSON.stringify(config, null, 2), { mode: 0o600 });
38
- await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
39
- const html = `<!doctype html><meta charset="utf-8"><title>Recovery Probe IPC report</title><style>body{max-width:1000px;margin:40px auto;font:16px system-ui;padding:20px}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#f4f5f7;padding:20px}</style><h1>${report.ok ? 'Selected IPC experiments completed without findings requiring review' : 'IPC recovery needs investigation'}</h1><p>${escape(report.limitation)}</p><p>Final reload: ${escape(report.finalReset)}. Cleanup cannot turn an earlier failure into a pass.</p><pre>${escape(JSON.stringify(report, null, 2))}</pre>`;
40
- await writeFile(join(directory, 'report.html'), html, { mode: 0o600 });
47
+ if (!options.config) throw new Error('--config is required')
48
+ const rawConfig = JSON.parse(await readFile(options.config, 'utf8'))
49
+ if (options.restoreWindow) rawConfig.restoreWindow = true
50
+ const config = options.discover ? discoveryConfig(rawConfig) : rawConfig
51
+ const parent = resolve('.recovery-probe')
52
+ let directory
53
+ if (options.out) {
54
+ directory = resolve(options.out)
55
+ await mkdir(directory, { mode: 0o700 })
56
+ } else {
57
+ await mkdir(parent, { recursive: true, mode: 0o700 })
58
+ directory = await mkdtemp(join(parent, 'ipc-'))
59
+ }
60
+ await writeFile(join(directory, '.gitignore'), '*\n', { mode: 0o600 })
61
+ const report = options.discover
62
+ ? await discoverIpc(config)
63
+ : await checkIpc(config)
64
+ await writeFile(
65
+ join(directory, 'scenario.json'),
66
+ JSON.stringify(config, null, 2),
67
+ { mode: 0o600 },
68
+ )
69
+ await writeFile(
70
+ join(directory, 'report.json'),
71
+ JSON.stringify(report, null, 2),
72
+ { mode: 0o600 },
73
+ )
74
+ const html = `<!doctype html><meta charset="utf-8"><title>Recovery Probe IPC report</title><style>body{max-width:1000px;margin:40px auto;font:16px system-ui;padding:20px}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#f4f5f7;padding:20px}</style><h1>${report.ok ? 'Selected IPC experiments completed without findings requiring review' : 'IPC recovery needs investigation'}</h1><p>${escape(report.limitation)}</p><p>Final reload: ${escape(report.finalReset)}. Cleanup cannot turn an earlier failure into a pass.</p><pre>${escape(JSON.stringify(report, null, 2))}</pre>`
75
+ await writeFile(join(directory, 'report.html'), html, { mode: 0o600 })
41
76
  if (options.discover) {
42
- await writeDiscoveryReport(directory, report, config);
43
- for (const finding of report.findings) console.log(`${finding.kind.toUpperCase()}: ${finding.id} — ${finding.classification}; runs=${finding.confirmations}${finding.partial ? `/${finding.plannedRuns} partial; observed=${finding.observedInterpretation.classification}` : ''}`);
44
- if (report.error) console.error(`Discovery stopped: ${report.error}`);
45
- if (report.cleanupError) console.error(`Cleanup: ${report.cleanupError}`);
46
- console.log(`Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}\nReplay: recovery-probe ipc --discover --config ${join(directory, 'scenario.json')}`);
47
- process.exitCode = report.ok ? 0 : 2; // Heuristic findings are never proven test failures.
48
- return;
77
+ await writeDiscoveryReport(directory, report, config)
78
+ for (const finding of report.findings)
79
+ console.log(
80
+ `${finding.kind.toUpperCase()}: ${finding.id} — ${finding.classification}; runs=${finding.confirmations}${finding.partial ? `/${finding.plannedRuns} partial; observed=${finding.observedInterpretation.classification}` : ''}`,
81
+ )
82
+ if (report.error) console.error(`Discovery stopped: ${report.error}`)
83
+ if (report.cleanupError) console.error(`Cleanup: ${report.cleanupError}`)
84
+ console.log(
85
+ `Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}\nReplay: recovery-probe ipc --discover --config ${join(directory, 'scenario.json')}`,
86
+ )
87
+ process.exitCode = report.ok ? 0 : 2 // Heuristic findings are never proven test failures.
88
+ return
49
89
  }
50
- console.log(`Baseline: ${report.baseline?.code ?? report.error ?? 'not established'}`);
51
- for (const row of report.results) console.log(`${row.outcome.toUpperCase()}: ${row.fault} — ${row.code}; injected=${row.snapshot.injected}; later real successes=${row.snapshot.successfulAfterFault}`);
52
- if (report.error) console.error(`Check stopped: ${report.error}`);
53
- if (report.cleanupError) console.error(`Cleanup: ${report.cleanupError}`);
54
- console.log(`Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}`);
55
- process.exitCode = report.ok ? 0 : report.results.some(row => row.outcome === 'fail') ? 1 : 2;
90
+ console.log(
91
+ `Baseline: ${report.baseline?.code ?? report.error ?? 'not established'}`,
92
+ )
93
+ for (const row of report.results)
94
+ console.log(
95
+ `${row.outcome.toUpperCase()}: ${row.fault} — ${row.code}; injected=${row.snapshot.injected}; later real successes=${row.snapshot.successfulAfterFault}`,
96
+ )
97
+ if (report.error) console.error(`Check stopped: ${report.error}`)
98
+ if (report.cleanupError) console.error(`Cleanup: ${report.cleanupError}`)
99
+ console.log(
100
+ `Final reload: ${report.finalReset}\nReport: ${join(directory, 'report.html')}`,
101
+ )
102
+ process.exitCode = report.ok
103
+ ? 0
104
+ : report.results.some((row) => row.outcome === 'fail')
105
+ ? 1
106
+ : 2
56
107
  }