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

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 +7 -0
  2. package/CONTRIBUTING.md +5 -0
  3. package/README.md +2 -0
  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 +10 -1
  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 +360 -142
  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,13 @@ 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.2 (2026-10-15)
8
+
9
+ - Apply consistent Prettier formatting and add formatting, ESLint and JavaScript type checks to CI.
10
+ - Add JSDoc annotations for implementation type checking without a build step; strict mode remains off.
11
+ - Preserve original causes in two wrapped errors and make small lint-driven cleanups. No new observation or fault-injection features.
12
+ - Publish the maintenance changes from PRs #22–#24 on the opt-in `next` channel; stable `latest` remains 0.3.0.
13
+
7
14
  ## 0.4.0-preview.1 (2026-10-15)
8
15
 
9
16
  - 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
@@ -32,6 +32,8 @@ npx recovery-probe --version
32
32
 
33
33
  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
34
 
35
+ For the 0.4 observation preview, install `recovery-probe@0.4.0-preview.2` (the `next` channel) with the same Playwright version. Preview.2 adds formatting, lint and implementation type checks; the action/row observation features were introduced in preview.1.
36
+
35
37
  ## Choose a workflow
36
38
 
37
39
  **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.
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
  }