recovery-probe 0.4.0 → 0.5.0-preview.7

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 (89) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/CONTRIBUTING.md +1 -1
  3. package/bin/attach.mjs +15 -11
  4. package/bin/desktop.mjs +2 -2
  5. package/bin/ipc.mjs +5 -5
  6. package/bin/observe.mjs +9 -7
  7. package/bin/recovery-probe.mjs +2 -1
  8. package/bin/refresh.mjs +9 -7
  9. package/bin/repair.mjs +1 -1
  10. package/bin/start.mjs +2 -1
  11. package/bin/web.mjs +2 -2
  12. package/dist/desktop-report.d.mts +5 -0
  13. package/dist/desktop-report.mjs +52 -0
  14. package/dist/discovery-control.d.mts +16 -0
  15. package/dist/discovery-control.mjs +39 -0
  16. package/dist/discovery-report.d.mts +40 -0
  17. package/dist/discovery-report.mjs +31 -0
  18. package/dist/fetch-fault.d.mts +21 -0
  19. package/dist/fetch-fault.mjs +84 -0
  20. package/dist/http-observer.d.mts +45 -0
  21. package/dist/http-observer.mjs +186 -0
  22. package/dist/ipc-check.d.mts +45 -0
  23. package/dist/ipc-check.mjs +261 -0
  24. package/dist/ipc-control.d.mts +12 -0
  25. package/dist/ipc-control.mjs +27 -0
  26. package/dist/ipc-discover.d.mts +119 -0
  27. package/dist/ipc-discover.mjs +386 -0
  28. package/dist/ipc-inspector.d.mts +19 -0
  29. package/dist/ipc-inspector.mjs +144 -0
  30. package/dist/ipc-observation.d.mts +111 -0
  31. package/dist/ipc-observation.mjs +302 -0
  32. package/dist/ipc-probe.cjs +382 -0
  33. package/dist/ipc-probe.d.cts +117 -0
  34. package/dist/observation-kit.d.mts +35 -0
  35. package/dist/observation-kit.mjs +160 -0
  36. package/dist/observation-report.d.mts +289 -0
  37. package/dist/observation-report.mjs +329 -0
  38. package/dist/observe-steps.d.mts +36 -0
  39. package/dist/observe-steps.mjs +143 -0
  40. package/dist/observe.d.mts +104 -0
  41. package/dist/observe.mjs +892 -0
  42. package/dist/refresh-adapters.d.mts +40 -0
  43. package/dist/refresh-adapters.mjs +74 -0
  44. package/dist/report-template.d.mts +7 -0
  45. package/dist/report-template.mjs +23 -0
  46. package/dist/visibility.d.mts +25 -0
  47. package/dist/visibility.mjs +127 -0
  48. package/docs/observe.md +1 -1
  49. package/examples/core-demo.mjs +1 -1
  50. package/package.json +41 -38
  51. package/src/desktop-report.mjs +0 -67
  52. package/src/discovery-control.mjs +0 -45
  53. package/src/discovery-report.mjs +0 -47
  54. package/src/fetch-fault.d.mts +0 -22
  55. package/src/fetch-fault.mjs +0 -96
  56. package/src/http-observer.mjs +0 -197
  57. package/src/ipc-check.mjs +0 -279
  58. package/src/ipc-control.mjs +0 -32
  59. package/src/ipc-discover.mjs +0 -413
  60. package/src/ipc-inspector.d.mts +0 -34
  61. package/src/ipc-inspector.mjs +0 -166
  62. package/src/ipc-observation.mjs +0 -332
  63. package/src/ipc-probe.cjs +0 -399
  64. package/src/ipc-probe.d.cts +0 -107
  65. package/src/observation-kit.mjs +0 -176
  66. package/src/observation-report.mjs +0 -385
  67. package/src/observe-steps.mjs +0 -164
  68. package/src/observe.mjs +0 -1025
  69. package/src/refresh-adapters.mjs +0 -68
  70. package/src/report-template.mjs +0 -33
  71. package/src/visibility.mjs +0 -130
  72. /package/{src → dist}/desktop.d.mts +0 -0
  73. /package/{src → dist}/desktop.mjs +0 -0
  74. /package/{src → dist}/guided-start.mjs +0 -0
  75. /package/{src → dist}/http-discover.mjs +0 -0
  76. /package/{src → dist}/index.d.ts +0 -0
  77. /package/{src → dist}/index.mjs +0 -0
  78. /package/{src → dist}/pick-marker.mjs +0 -0
  79. /package/{src → dist}/refresh.mjs +0 -0
  80. /package/{src → dist}/repair-process.mjs +0 -0
  81. /package/{src → dist}/repair-provider.mjs +0 -0
  82. /package/{src → dist}/repair.mjs +0 -0
  83. /package/{src → dist}/report-templates/desktop.html +0 -0
  84. /package/{src → dist}/report-templates/discovery.html +0 -0
  85. /package/{src → dist}/report-templates/ipc.html +0 -0
  86. /package/{src → dist}/report-templates/observation.html +0 -0
  87. /package/{src → dist}/report-templates/refresh.html +0 -0
  88. /package/{src → dist}/web.d.mts +0 -0
  89. /package/{src → dist}/web.mjs +0 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,39 @@ 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-preview.7 (2026-10-16)
8
+
9
+ - The IPC check and IPC discovery (`recovery-probe ipc` and `ipc --discover`) are written in TypeScript. Their reports are unchanged.
10
+
11
+ ## 0.5.0-preview.6 (2026-10-16)
12
+
13
+ - The IPC development hook (`recovery-probe/ipc`) is written in TypeScript and still ships as the CommonJS file `dist/ipc-probe.cjs`. Its declarations are generated from the source and match the previous ones; `ProbeWebContents` gains the optional `getOwnerBrowserWindow` that the window controls use.
14
+
15
+ ## 0.5.0-preview.5 (2026-10-16)
16
+
17
+ - The IPC control modules and `recovery-probe/ipc-inspector` are written in TypeScript. The inspector's declarations are now generated from its source and match the previous ones.
18
+
19
+ ## 0.5.0-preview.4 (2026-10-16)
20
+
21
+ - `observe` is written in TypeScript, and the observation report has a complete schema type. Captures and reports are unchanged.
22
+
23
+ ## 0.5.0-preview.3 (2026-10-16)
24
+
25
+ - The observation helpers are written in TypeScript: the in-page observation kit, scripted steps, the region reader and the HTTP observer. Their results are unchanged.
26
+
27
+ ## 0.5.0-preview.2 (2026-10-16)
28
+
29
+ - The report modules are written in TypeScript: the HTML template renderer and the desktop, discovery and observation reports. The reports they write are byte-identical to before.
30
+
31
+ ## 0.5.0-preview.1 (2026-10-16)
32
+
33
+ The first step of moving the package to TypeScript.
34
+
35
+ - The package is compiled into `dist/` and published from there. Package exports are unchanged, but `require.resolve('recovery-probe/ipc')` now returns a path ending in `dist/ipc-probe.cjs`. If you stored the old `src/ipc-probe.cjs` path in `RECOVERY_PROBE_IPC_MODULE`, run the command again after upgrading.
36
+ - `createFaultFetch` is written in TypeScript with strict checks, and its declarations are generated from the source. Its return type is exported as `FaultFetch`.
37
+ - TypeScript files are linted with typescript-eslint, so TypeScript is pinned to 6.0, the newest version typescript-eslint supports.
38
+ - A source checkout builds `dist/` during `npm ci`; test, demo and type-check scripts build first.
39
+
7
40
  ## 0.4.0 (2026-10-16)
8
41
 
9
42
  The first stable release since 0.3.0. It contains 0.4.0-preview.1 to preview.5; their entries below have the details.
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. 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, 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 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.
31
31
 
32
32
  ## Install an unpublished source preview
33
33
 
package/bin/attach.mjs CHANGED
@@ -1,11 +1,11 @@
1
1
  import { readFile, mkdir } from 'node:fs/promises'
2
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'
3
+ import { connectDesktop, selectDesktopPage } from '../dist/desktop.mjs'
4
+ import { discoverHttp, httpDiscoveryConfig } from '../dist/http-discover.mjs'
5
+ import { writeDiscoveryReport } from '../dist/discovery-report.mjs'
6
+ import { prepareVisibility } from '../dist/visibility.mjs'
7
+ import { checkDesktop } from '../dist/desktop.mjs'
8
+ import { writeDesktopReport } from '../dist/desktop-report.mjs'
9
9
  export async function attachMain(args) {
10
10
  const options = {}
11
11
  for (let i = 0; i < args.length; i++) {
@@ -40,19 +40,23 @@ export async function attachMain(args) {
40
40
  const browser = await connectDesktop(config.cdp)
41
41
  try {
42
42
  const page = selectDesktopPage(browser, config)
43
+ /** @type {Record<string, any>} */
43
44
  let report
44
45
  if (options.discover) {
45
- report = await discoverHttp(page, config)
46
- await writeDiscoveryReport(directory, report, config)
46
+ const discovery = await discoverHttp(page, config)
47
+ await writeDiscoveryReport(directory, discovery, config)
48
+ report = discovery
47
49
  } else {
48
50
  const visibility = await prepareVisibility(page, config)
51
+ let check
49
52
  try {
50
- report = await checkDesktop(page, config)
51
- report.mode = 'attached browser recovery'
53
+ check = await checkDesktop(page, config)
54
+ check.mode = 'attached browser recovery'
52
55
  } finally {
53
56
  await visibility.revert()
54
57
  }
55
- await writeDesktopReport(directory, report, config)
58
+ await writeDesktopReport(directory, check, config)
59
+ report = check
56
60
  }
57
61
  for (const f of report.findings ?? report.results)
58
62
  console.log(
package/bin/desktop.mjs CHANGED
@@ -8,8 +8,8 @@ import {
8
8
  discoverDesktop,
9
9
  checkDesktop,
10
10
  validateDesktopConfig,
11
- } from '../src/desktop.mjs'
12
- import { writeDesktopReport } from '../src/desktop-report.mjs'
11
+ } from '../dist/desktop.mjs'
12
+ import { writeDesktopReport } from '../dist/desktop-report.mjs'
13
13
 
14
14
  export async function desktopMain(args) {
15
15
  if (!args.length || args.includes('--help')) {
package/bin/ipc.mjs CHANGED
@@ -1,9 +1,9 @@
1
- import { writeDiscoveryReport } from '../src/discovery-report.mjs'
1
+ import { writeDiscoveryReport } from '../dist/discovery-report.mjs'
2
2
  import { readFile, mkdir, writeFile, mkdtemp } from 'node:fs/promises'
3
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
- import { renderTemplate } from '../src/report-template.mjs'
4
+ import { discoverIpc, discoveryConfig } from '../dist/ipc-discover.mjs'
5
+ import { checkIpc } from '../dist/ipc-check.mjs'
6
+ import { renderTemplate } from '../dist/report-template.mjs'
7
7
 
8
8
  export async function ipcMain(args) {
9
9
  if (!args.length || args.includes('--help')) {
@@ -74,7 +74,7 @@ No HTTP/Rust transport faults or AI calls. See docs/ipc.md for installation and
74
74
  evidence: JSON.stringify(report, null, 2),
75
75
  })
76
76
  await writeFile(join(directory, 'report.html'), html, { mode: 0o600 })
77
- if (options.discover) {
77
+ if ('findings' in report) {
78
78
  await writeDiscoveryReport(directory, report, config)
79
79
  for (const finding of report.findings)
80
80
  console.log(
package/bin/observe.mjs CHANGED
@@ -6,14 +6,14 @@ import {
6
6
  connectDesktop,
7
7
  selectDesktopPage,
8
8
  desktopPages,
9
- } from '../src/desktop.mjs'
10
- import { connectIpcInspector } from '../src/ipc-inspector.mjs'
9
+ } from '../dist/desktop.mjs'
10
+ import { connectIpcInspector } from '../dist/ipc-inspector.mjs'
11
11
  import {
12
12
  observationConfig,
13
13
  runObservation,
14
14
  httpObservationAdapter,
15
15
  ipcObservationAdapter,
16
- } from '../src/observe.mjs'
16
+ } from '../dist/observe.mjs'
17
17
  import {
18
18
  observationMetadata,
19
19
  samplingMetrics,
@@ -21,8 +21,8 @@ import {
21
21
  renderObservationReport,
22
22
  actionSummary,
23
23
  comparisonDigest,
24
- } from '../src/observation-report.mjs'
25
- import { observationSteps, runSteps } from '../src/observe-steps.mjs'
24
+ } from '../dist/observation-report.mjs'
25
+ import { observationSteps, runSteps } from '../dist/observe-steps.mjs'
26
26
 
27
27
  export async function observeMain(args) {
28
28
  if (!args.length || args.includes('--help')) {
@@ -76,9 +76,11 @@ IPC requires the observation-capable development hook. See docs/observe.md.`)
76
76
  const stop = () => abort.abort()
77
77
  process.on('SIGINT', stop)
78
78
  process.on('SIGTERM', stop)
79
+ /** @type {Awaited<ReturnType<typeof connectIpcInspector>> | undefined} */
80
+ let control
81
+ /** @type {import('node:readline').Interface | undefined} */
82
+ let input
79
83
  let browser,
80
- control,
81
- input,
82
84
  report,
83
85
  pendingMarkers = 0,
84
86
  browserVersion = null
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { readFile, writeFile, mkdir } from 'node:fs/promises'
3
3
  import { dirname } from 'node:path'
4
- import { probeRecovery } from '../src/index.mjs'
4
+ import { probeRecovery } from '../dist/index.mjs'
5
5
  import { startDemoServer } from '../examples/demo-server.mjs'
6
6
 
7
7
  const { version } = JSON.parse(
@@ -130,6 +130,7 @@ async function main() {
130
130
  const { chromium } = await import('playwright')
131
131
  const browser = await chromium.launch({ headless: true })
132
132
  let server
133
+ /** @type {Record<string, any>} */
133
134
  let report
134
135
  try {
135
136
  const apps = []
package/bin/refresh.mjs CHANGED
@@ -5,15 +5,15 @@ import {
5
5
  connectDesktop,
6
6
  selectDesktopPage,
7
7
  desktopPages,
8
- } from '../src/desktop.mjs'
9
- import { connectIpcInspector } from '../src/ipc-inspector.mjs'
10
- import { prepareVisibility } from '../src/visibility.mjs'
11
- import { refreshConfig, runRefresh } from '../src/refresh.mjs'
8
+ } from '../dist/desktop.mjs'
9
+ import { connectIpcInspector } from '../dist/ipc-inspector.mjs'
10
+ import { prepareVisibility } from '../dist/visibility.mjs'
11
+ import { refreshConfig, runRefresh } from '../dist/refresh.mjs'
12
12
  import {
13
13
  httpRefreshAdapter,
14
14
  ipcRefreshAdapter,
15
- } from '../src/refresh-adapters.mjs'
16
- import { escapeHtml, renderTemplate } from '../src/report-template.mjs'
15
+ } from '../dist/refresh-adapters.mjs'
16
+ import { escapeHtml, renderTemplate } from '../dist/report-template.mjs'
17
17
 
18
18
  export async function refreshMain(args) {
19
19
  if (args.includes('--help')) {
@@ -45,7 +45,9 @@ export async function refreshMain(args) {
45
45
  const onSignal = () => abort.abort()
46
46
  process.on('SIGINT', onSignal)
47
47
  process.on('SIGTERM', onSignal)
48
- let browser, control, visibility, report
48
+ let browser, control, visibility
49
+ /** @type {Record<string, any> | undefined} */
50
+ let report
49
51
  try {
50
52
  browser = await connectDesktop(c.cdp)
51
53
  let page, adapter
package/bin/repair.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  import { readFile } from 'node:fs/promises'
2
2
  import { resolve, dirname } from 'node:path'
3
- import { prepareRepair, generateRepair, verifyRepair } from '../src/repair.mjs'
3
+ import { prepareRepair, generateRepair, verifyRepair } from '../dist/repair.mjs'
4
4
 
5
5
  export async function repairMain(args) {
6
6
  if (!args.length || args.includes('--help')) {
package/bin/start.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createInterface } from 'node:readline/promises'
2
- import { parseStartArgs, runStart } from '../src/guided-start.mjs'
2
+ import { parseStartArgs, runStart } from '../dist/guided-start.mjs'
3
3
 
4
4
  export async function startMain(args) {
5
5
  if (!args.length || args.includes('--help')) {
@@ -16,6 +16,7 @@ Local checks only: no source upload or AI repair. Native/Rust/IPC traffic is not
16
16
  return
17
17
  }
18
18
  const options = parseStartArgs(args)
19
+ /** @type {import('node:readline/promises').Interface | undefined} */
19
20
  let terminal
20
21
  const io = {
21
22
  interactive: Boolean(process.stdin.isTTY),
package/bin/web.mjs CHANGED
@@ -2,8 +2,8 @@ import { attachMain } from './attach.mjs'
2
2
  import { readFile, writeFile, mkdir } from 'node:fs/promises'
3
3
  import { resolve, dirname, join } from 'node:path'
4
4
  import { createInterface } from 'node:readline/promises'
5
- import { openWeb, checkWeb, discoverWeb } from '../src/web.mjs'
6
- import { writeDesktopReport } from '../src/desktop-report.mjs'
5
+ import { openWeb, checkWeb, discoverWeb } from '../dist/web.mjs'
6
+ import { writeDesktopReport } from '../dist/desktop-report.mjs'
7
7
 
8
8
  export async function webMain(args) {
9
9
  if (args.includes('--attach') && !args.includes('--help')) {
@@ -0,0 +1,5 @@
1
+ import type { DesktopReport } from './desktop.mjs';
2
+ export declare function desktopReportHtml(report: DesktopReport, target?: 'desktop' | 'web'): string;
3
+ export declare function writeDesktopReport(directory: string, report: DesktopReport, config: {
4
+ target?: string;
5
+ }): Promise<string>;
@@ -0,0 +1,52 @@
1
+ import { mkdir, writeFile } from 'node:fs/promises';
2
+ import { resolve, join } from 'node:path';
3
+ import { escapeHtml, renderTemplate } from './report-template.mjs';
4
+ export function desktopReportHtml(report, target = 'desktop') {
5
+ const results = report.results
6
+ .map((row) => `<tr><td>${escapeHtml(row.kind)}</td><td class="${escapeHtml(row.outcome)}">${escapeHtml(row.outcome.toUpperCase())}</td><td>${escapeHtml(row.code)}</td><td>${row.applied}</td><td>${row.successfulResponsesAfterFault}</td><td>${row.retryClicked ? 'Yes' : 'No'}</td></tr>`)
7
+ .join('');
8
+ const screenshots = report.results
9
+ .filter((row) => row.screenshot && /^[a-z0-9-]+\.png$/.test(row.screenshot))
10
+ .map((row) => `<figure><figcaption>${escapeHtml(row.kind)} — ${escapeHtml(row.code)}</figcaption><img alt="Renderer at the end of the recovery check" src="${escapeHtml(row.screenshot)}"></figure>`)
11
+ .join('');
12
+ return renderTemplate('desktop', {
13
+ target,
14
+ targetLabel: target.toUpperCase(),
15
+ heading: report.ok
16
+ ? 'Selected recovery checks passed'
17
+ : 'Recovery needs investigation',
18
+ endpoint: report.endpoint,
19
+ recovery: report.recovery,
20
+ timeoutMs: report.timeoutMs,
21
+ generatedAt: report.generatedAt,
22
+ results,
23
+ finalReset: report.finalReset,
24
+ limitation: report.limitation,
25
+ reproduceWhere: target === 'web'
26
+ ? 'against the configured development URL'
27
+ : 'while your development app is on the same screen',
28
+ screenshots,
29
+ });
30
+ }
31
+ export async function writeDesktopReport(directory, report, config) {
32
+ const dir = resolve(directory);
33
+ await mkdir(dir, { recursive: true, mode: 0o700 });
34
+ const failures = report.results
35
+ .filter((r) => r.outcome !== 'pass')
36
+ .map((r) => `- ${r.kind}: ${r.code}; injected=${r.applied}; later successful responses=${r.successfulResponsesAfterFault}; retry clicked=${r.retryClicked}`)
37
+ .join('\n');
38
+ const brief = `# Recovery investigation\n\nThis is a test observation, not an automatic diagnosis or a source-code fix.\n\nSelected GET endpoint: ${JSON.stringify(report.endpoint)}\nRecovery mode: ${report.recovery}\nDeadline: ${report.timeoutMs} ms\nFinal reload reset: ${report.finalReset}\n\n## Observations\n\n${failures || 'All configured fault checks passed.'}\n\n## Instructions for a coding agent with authorized source access\n\n1. Read scenario.json and report.json. Validate that readySelector and optional readyText/busySelector prove this endpoint loaded, and that retrySelector identifies the intended action.\n2. Reproduce with node reproduce.mjs from this directory against the same development screen and test account. Treat BASELINE_FAILED, FAULT_NOT_TRIGGERED, and RETRY_ACTION_UNAVAILABLE as inconclusive, not app defects.\n3. Find the selected request and its recovery state transitions in the source. Check loading/in-flight flags, errors, retry handlers, cancellation and stale responses. These are hypotheses, not established causes.\n4. If an app defect is reproduced, propose the smallest source patch with an explanation. Preserve error reporting and authentication; do not mask the failure or weaken the assertion to make the test pass.\n5. Rerun the same scenario and the application's relevant tests. Compare the before/after reports. Obtain review before merging or deploying a patch.\n\nThis report contains local endpoint paths and may include optional screenshots. It has not been sent to an AI service.\n`;
39
+ const reproduction = config.target === 'web'
40
+ ? `import { readFile } from 'node:fs/promises';\nimport { checkWeb } from 'recovery-probe/web';\nconst config = JSON.parse(await readFile(new URL('./scenario.json', import.meta.url), 'utf8'));\nconst report = await checkWeb(config);\nconsole.log(JSON.stringify(report, null, 2));\nprocess.exitCode = report.ok ? 0 : 1;\n`
41
+ : `import { readFile } from 'node:fs/promises';\nimport { connectDesktop, selectDesktopPage, checkDesktop } from 'recovery-probe/desktop';\nconst config = JSON.parse(await readFile(new URL('./scenario.json', import.meta.url), 'utf8'));\nconst browser = await connectDesktop(config.cdp);\ntry {\n const report = await checkDesktop(selectDesktopPage(browser, config), config);\n console.log(JSON.stringify(report, null, 2));\n process.exitCode = report.ok ? 0 : 1;\n} finally { await browser.close(); }\n`;
42
+ for (const [name, value] of Object.entries({
43
+ 'report.json': JSON.stringify(report, null, 2) + '\n',
44
+ 'scenario.json': JSON.stringify(config, null, 2) + '\n',
45
+ 'report.html': desktopReportHtml(report, config.target === 'web' ? 'web' : 'desktop'),
46
+ 'fix-brief.md': brief,
47
+ 'reproduce.mjs': reproduction,
48
+ })) {
49
+ await writeFile(join(dir, name), value, { mode: 0o600 });
50
+ }
51
+ return dir;
52
+ }
@@ -0,0 +1,16 @@
1
+ import type { DiscoveryFinding, DiscoveryInterpretation } from './discovery-report.mjs';
2
+ interface DiscoveryRun {
3
+ fault: string;
4
+ times: number;
5
+ interpretation?: DiscoveryInterpretation;
6
+ assessment?: DiscoveryInterpretation;
7
+ }
8
+ export declare function matchesHealthyControl(ui: {
9
+ fingerprint?: string;
10
+ }, expectedFingerprint: string | undefined): boolean;
11
+ export declare function retainPartialFindings(report: {
12
+ results: DiscoveryRun[];
13
+ findings: DiscoveryFinding[];
14
+ error?: string;
15
+ }, plannedRuns: number): void;
16
+ export {};
@@ -0,0 +1,39 @@
1
+ // A stable intermediate screen is not a healthy control once a baseline exists.
2
+ export function matchesHealthyControl(ui, expectedFingerprint) {
3
+ return (expectedFingerprint === undefined || ui.fingerprint === expectedFingerprint);
4
+ }
5
+ // Keep completed runs visible when a later control aborts an experiment.
6
+ // Partial evidence must not inherit a confirmed defect/healthy verdict.
7
+ export function retainPartialFindings(report, plannedRuns) {
8
+ const groups = new Map();
9
+ for (const run of report.results) {
10
+ const id = `${run.fault}-${run.times}`;
11
+ if (!groups.has(id))
12
+ groups.set(id, []);
13
+ groups.get(id).push(run);
14
+ }
15
+ for (const [id, runs] of groups) {
16
+ if (report.findings.some((finding) => finding.id === id))
17
+ continue;
18
+ const interpretations = runs.map((run) => (run.interpretation ?? run.assessment));
19
+ const consistent = interpretations.every((value) => value.classification === interpretations[0].classification);
20
+ report.findings.push({
21
+ id,
22
+ fault: runs[0].fault,
23
+ times: runs[0].times,
24
+ classification: 'INCOMPLETE_EXPERIMENT',
25
+ kind: 'inconclusive',
26
+ confidence: 'low',
27
+ confirmations: runs.length,
28
+ completedRuns: runs.length,
29
+ plannedRuns,
30
+ partial: true,
31
+ repeatConfirmed: false,
32
+ observedInterpretation: consistent
33
+ ? interpretations[0]
34
+ : { classification: 'UNSTABLE', kind: 'inconclusive' },
35
+ stoppedReason: report.error ?? 'Experiment interrupted',
36
+ advice: 'Completed runs are partial evidence. Resolve the stopped control before claiming repeat confirmation.',
37
+ });
38
+ }
39
+ }
@@ -0,0 +1,40 @@
1
+ export interface DiscoveryInterpretation {
2
+ classification: string;
3
+ kind?: string;
4
+ [key: string]: unknown;
5
+ }
6
+ /** An experiment's verdict, or the partial evidence kept when it was interrupted. */
7
+ export interface DiscoveryFinding {
8
+ id: string;
9
+ fault: string;
10
+ times: number;
11
+ classification: string;
12
+ kind: string;
13
+ confidence?: string;
14
+ confirmations: number;
15
+ repeatConfirmed: boolean;
16
+ advice: string;
17
+ observationMs?: number;
18
+ verification?: string;
19
+ partial?: true;
20
+ completedRuns?: number;
21
+ plannedRuns?: number;
22
+ observedInterpretation?: DiscoveryInterpretation;
23
+ stoppedReason?: string;
24
+ }
25
+ /** The fields of an HTTP or IPC discovery report that the written report uses. */
26
+ export interface DiscoveryReport {
27
+ findings: DiscoveryFinding[];
28
+ limitation: string;
29
+ error?: string;
30
+ cleanupError?: string;
31
+ finalReset?: string;
32
+ window?: unknown;
33
+ coverage?: unknown;
34
+ readiness?: unknown;
35
+ failedControl?: {
36
+ reasons: unknown;
37
+ diff: unknown;
38
+ } | null;
39
+ }
40
+ export declare function writeDiscoveryReport(directory: string, report: DiscoveryReport, config: unknown): Promise<void>;
@@ -0,0 +1,31 @@
1
+ import { writeFile } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ import { escapeHtml, renderTemplate } from './report-template.mjs';
4
+ export async function writeDiscoveryReport(directory, report, config) {
5
+ await writeFile(join(directory, '.gitignore'), '*\n', { mode: 0o600 });
6
+ await writeFile(join(directory, 'scenario.json'), JSON.stringify(config, null, 2), { mode: 0o600 });
7
+ await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
8
+ const experiments = report.findings
9
+ .map((f) => `<tr><td>${escapeHtml(f.id)}</td><td>${escapeHtml(f.classification)}</td><td>${escapeHtml(f.kind)}</td><td>${escapeHtml(f.confidence ?? 'not-rated')}</td><td>${f.partial ? `${f.completedRuns}/${f.plannedRuns} (partial)` : f.confirmations}</td><td>${escapeHtml(f.observedInterpretation?.classification ?? '')}</td></tr>`)
10
+ .join('');
11
+ const summary = {
12
+ error: report.error,
13
+ cleanupError: report.cleanupError,
14
+ finalReset: report.finalReset,
15
+ window: report.window,
16
+ coverage: report.coverage,
17
+ readiness: report.readiness,
18
+ failedControl: report.failedControl
19
+ ? {
20
+ reasons: report.failedControl.reasons,
21
+ diff: report.failedControl.diff,
22
+ }
23
+ : undefined,
24
+ };
25
+ await writeFile(join(directory, 'report.html'), renderTemplate('discovery', {
26
+ limitation: report.limitation,
27
+ experiments,
28
+ summary: JSON.stringify(summary, null, 2),
29
+ evidence: JSON.stringify(report, null, 2),
30
+ }), { mode: 0o600 });
31
+ }
@@ -0,0 +1,21 @@
1
+ export type FaultKind = 'http-error' | 'connection-failure' | 'invalid-json';
2
+ export interface FetchFaultOptions {
3
+ url: string;
4
+ kind: FaultKind;
5
+ status?: number;
6
+ count?: number;
7
+ method?: string;
8
+ }
9
+ export interface FetchFaultStats {
10
+ kind: FaultKind;
11
+ requested: number;
12
+ applied: number;
13
+ matchingRequests: number;
14
+ }
15
+ export interface FaultFetch {
16
+ fetch: typeof fetch;
17
+ summary(): FetchFaultStats;
18
+ assertApplied(): FetchFaultStats;
19
+ }
20
+ /** Fault-injected fetch for an exact, absolute URL. Each instance is isolated. */
21
+ export declare function createFaultFetch(baseFetch: typeof fetch, options: FetchFaultOptions): FaultFetch;
@@ -0,0 +1,84 @@
1
+ const kinds = new Set([
2
+ 'http-error',
3
+ 'connection-failure',
4
+ 'invalid-json',
5
+ ]);
6
+ // A relative or malformed URL cannot be the absolute target, so it is never matched.
7
+ const absoluteHref = (value) => {
8
+ try {
9
+ return new URL(value).href;
10
+ }
11
+ catch {
12
+ return null;
13
+ }
14
+ };
15
+ /** Fault-injected fetch for an exact, absolute URL. Each instance is isolated. */
16
+ export function createFaultFetch(baseFetch, options) {
17
+ if (typeof baseFetch !== 'function')
18
+ throw new TypeError('baseFetch must be a function');
19
+ if (typeof options?.url !== 'string')
20
+ throw new TypeError('url must be an absolute HTTP(S) URL');
21
+ const target = new URL(options.url);
22
+ if (!['http:', 'https:'].includes(target.protocol) ||
23
+ target.username ||
24
+ target.password) {
25
+ throw new TypeError('Use an absolute HTTP(S) URL without embedded credentials');
26
+ }
27
+ if (!kinds.has(options.kind))
28
+ throw new TypeError('Unsupported fault kind');
29
+ const count = options.count ?? 1;
30
+ const method = options.method ?? 'GET';
31
+ const status = options.status ?? 503;
32
+ if (!Number.isInteger(count) || count < 1 || count > 20)
33
+ throw new TypeError('count must be an integer from 1 to 20');
34
+ if (!/^[A-Z]+$/.test(method))
35
+ throw new TypeError('method must be an uppercase HTTP method');
36
+ if (options.kind === 'http-error' &&
37
+ (!Number.isInteger(status) || status < 400 || status > 599)) {
38
+ throw new TypeError('HTTP fault status must be from 400 to 599');
39
+ }
40
+ let applied = 0;
41
+ let matchingRequests = 0;
42
+ const summary = () => ({
43
+ kind: options.kind,
44
+ requested: count,
45
+ applied,
46
+ matchingRequests,
47
+ });
48
+ return {
49
+ summary,
50
+ assertApplied() {
51
+ if (applied !== count) {
52
+ throw Object.assign(new Error(`Expected ${count} fault(s); observed ${applied}.`), { code: 'FAULT_NOT_TRIGGERED', stats: summary() });
53
+ }
54
+ return summary();
55
+ },
56
+ async fetch(input, init) {
57
+ const inputUrl = input instanceof Request ? input.url : input;
58
+ const requestMethod = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
59
+ const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
60
+ if (absoluteHref(inputUrl) !== target.href ||
61
+ requestMethod !== method ||
62
+ signal?.aborted) {
63
+ return baseFetch(input, init);
64
+ }
65
+ matchingRequests += 1;
66
+ if (applied >= count)
67
+ return baseFetch(input, init);
68
+ // Reserve before any await so concurrent calls cannot over-inject.
69
+ applied += 1;
70
+ if (options.kind === 'connection-failure')
71
+ throw new TypeError('Injected fetch connection failure');
72
+ if (options.kind === 'http-error') {
73
+ return new Response('{"error":"injected-test-fault"}', {
74
+ status,
75
+ headers: { 'Content-Type': 'application/json' },
76
+ });
77
+ }
78
+ return new Response('{invalid-json', {
79
+ status: 200,
80
+ headers: { 'Content-Type': 'application/json' },
81
+ });
82
+ },
83
+ };
84
+ }
@@ -0,0 +1,45 @@
1
+ import type { Page } from 'playwright';
2
+ import type { FaultKind } from './fetch-fault.mjs';
3
+ /** Read counters for one endpoint, in the same shape as an IPC channel row. */
4
+ export interface ReadChannelStats {
5
+ calls: number;
6
+ realCalls: number;
7
+ successes: number;
8
+ errors: number;
9
+ pending: number;
10
+ maxDurationMs: number;
11
+ firstReadAt: number | null;
12
+ lastReadAt: number | null;
13
+ firstCompletedAt: number | null;
14
+ lastCompletedAt: number | null;
15
+ lastSuccessAt: number | null;
16
+ }
17
+ export interface HttpObserverOptions {
18
+ endpoint: string;
19
+ requiredEndpoints?: string[];
20
+ fault?: FaultKind;
21
+ times?: number;
22
+ }
23
+ export declare function observeHttp(page: Page, { endpoint, requiredEndpoints, fault, times }: HttpObserverOptions): Promise<{
24
+ snapshot: () => {
25
+ startedAt: number;
26
+ capturedAt: number;
27
+ injected: number;
28
+ injectedAt: number | null;
29
+ successfulAfterFault: number;
30
+ injectionError: boolean;
31
+ armed: {
32
+ remaining: number;
33
+ } | null;
34
+ channels: Record<string, ReadChannelStats>;
35
+ };
36
+ coverage: () => {
37
+ method: string;
38
+ endpoint: string;
39
+ supported: boolean;
40
+ tested: boolean;
41
+ reason: string | undefined;
42
+ }[];
43
+ disarm(): Promise<void>;
44
+ stop(): Promise<void>;
45
+ }>;