recovery-probe 0.3.0-preview.12 → 0.3.0-preview.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.md +5 -3
- package/bin/observe.mjs +8 -5
- package/docs/ci.md +65 -0
- package/docs/desktop.md +2 -2
- package/docs/ipc.md +2 -2
- package/docs/observe.md +10 -2
- package/docs/start.md +2 -2
- package/examples/ci/run.mjs +70 -0
- package/examples/ci/scenario.json +8 -0
- package/examples/ci/verify.mjs +26 -0
- package/package.json +7 -5
- package/src/ipc-probe.cjs +2 -1
- package/src/ipc-probe.d.cts +2 -2
- package/src/observation-report.mjs +42 -0
- package/src/observe.mjs +10 -2
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,12 @@ 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.3.0-preview.13 (2026-10-14)
|
|
8
|
+
|
|
9
|
+
- Add observation report provenance: package/CLI runtime, available browser version and allowlisted IPC hook version/runtime/capabilities. Older observation-capable hooks remain supported with unknown metadata.
|
|
10
|
+
- Measure completed-sample duration and actual start-to-start cadence independently of the configured post-sample delay, including unchanged samples. Report first-content sample bounds and explain no-read versus pending-read findings without changing their codes or verdict semantics.
|
|
11
|
+
- Add a runnable synthetic CI recovery example with a saved scenario, explicit content assertion, bounded 503 injection, nonzero failure exits, JSON/Markdown reports and Playwright traces. Verify broken and fixed controls in CI; setup failures cannot satisfy the expected broken result.
|
|
12
|
+
|
|
7
13
|
## 0.3.0-preview.12 (2026-10-14)
|
|
8
14
|
|
|
9
15
|
- Add `observe --config FILE` for fault-free HTTP/IPC read observation in an existing renderer without reloads, navigation, focus changes or UI cleanup resets. Operator interval markers preserve cumulative read history.
|
package/README.md
CHANGED
|
@@ -21,12 +21,12 @@ Desktop support currently means Electron, not arbitrary native applications. IPC
|
|
|
21
21
|
|
|
22
22
|
## Install the current preview
|
|
23
23
|
|
|
24
|
-
This checkout targets **0.3.0-preview.
|
|
24
|
+
This checkout targets **0.3.0-preview.13**. Preview releases use npm's `next` tag; `latest` is the stable channel. Confirm that the exact version is published before installing it:
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
27
|
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
28
|
-
npm view recovery-probe@0.3.0-preview.
|
|
29
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.
|
|
28
|
+
npm view recovery-probe@0.3.0-preview.13 version
|
|
29
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.13 playwright@1.62.1
|
|
30
30
|
npx recovery-probe --version
|
|
31
31
|
```
|
|
32
32
|
|
|
@@ -42,6 +42,8 @@ If the version check reports that the version is unavailable, npm publication is
|
|
|
42
42
|
| Discover and test renderer reads in an existing browser or Electron window | `recovery-probe desktop --cdp URL` | [Attachment and HTTP discovery](docs/desktop.md) |
|
|
43
43
|
| Compare an Electron screen under IPC faults | `recovery-probe ipc --discover --config FILE` | [IPC setup and discovery](docs/ipc.md) |
|
|
44
44
|
| Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
|
|
45
|
+
| Observe cached content without a reload | `recovery-probe observe --config FILE` | [Observation](docs/observe.md) |
|
|
46
|
+
| Run a repeatable synthetic recovery check in CI | `npm run test:ci-example` (source checkout) | [CI example](docs/ci.md) |
|
|
45
47
|
| Add an explicit recovery assertion to a test | `withFault` or `createFaultFetch` | Examples below |
|
|
46
48
|
| Propose and verify a source change | Opt-in repair workflow | [Repair setup and limits](docs/repair.md) |
|
|
47
49
|
|
package/bin/observe.mjs
CHANGED
|
@@ -5,7 +5,7 @@ import { createInterface } from 'node:readline';
|
|
|
5
5
|
import { connectDesktop, selectDesktopPage, desktopPages } from '../src/desktop.mjs';
|
|
6
6
|
import { connectIpcInspector } from '../src/ipc-inspector.mjs';
|
|
7
7
|
import { observationConfig, runObservation, httpObservationAdapter, ipcObservationAdapter } from '../src/observe.mjs';
|
|
8
|
-
|
|
8
|
+
import { observationMetadata, samplingMetrics, observationSummary, renderObservationReport } from '../src/observation-report.mjs';
|
|
9
9
|
|
|
10
10
|
export async function observeMain(args) {
|
|
11
11
|
if (!args.length || args.includes('--help')) {
|
|
@@ -35,9 +35,10 @@ IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
|
35
35
|
const abort = new AbortController();
|
|
36
36
|
const stop = () => abort.abort();
|
|
37
37
|
process.on('SIGINT', stop); process.on('SIGTERM', stop);
|
|
38
|
-
let browser, control, input, report, pendingMarkers = 0;
|
|
38
|
+
let browser, control, input, report, pendingMarkers = 0, browserVersion = null;
|
|
39
39
|
try {
|
|
40
40
|
browser = await connectDesktop(config.cdp);
|
|
41
|
+
try { browserVersion = await browser.version(); } catch { /* Metadata may be unavailable on an attached runtime. */ }
|
|
41
42
|
let page, adapter;
|
|
42
43
|
if (config.transport === 'ipc') {
|
|
43
44
|
control = await connectIpcInspector(config.inspector);
|
|
@@ -76,7 +77,7 @@ IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
|
76
77
|
onInterval() { console.error('New observation interval.'); },
|
|
77
78
|
});
|
|
78
79
|
} catch (error) {
|
|
79
|
-
report ??= { schemaVersion: 1, mode: 'fault-free observation', status: 'incomplete', captureComplete: false, intervals: [], findings: [], reloads: 0, injected: 0 };
|
|
80
|
+
report ??= { schemaVersion: 1, metadata: observationMetadata(), sampling: samplingMetrics(config.sampleMs).snapshot(), mode: 'fault-free observation', status: 'incomplete', captureComplete: false, intervals: [], findings: [], reloads: 0, injected: 0 };
|
|
80
81
|
report.error = error.message;
|
|
81
82
|
} finally {
|
|
82
83
|
if (input) { input.close(); process.stdin.pause(); }
|
|
@@ -84,13 +85,15 @@ IPC requires the observation-capable development hook. See docs/observe.md.`);
|
|
|
84
85
|
try { await browser?.close(); } catch (error) { report.status = 'incomplete'; report.captureComplete = false; report.disconnectError = error.message; }
|
|
85
86
|
process.off('SIGINT', stop); process.off('SIGTERM', stop);
|
|
86
87
|
}
|
|
88
|
+
report.metadata.browserVersion = browserVersion;
|
|
87
89
|
await writeFile(join(directory, 'scenario.json'), JSON.stringify(config, null, 2), { mode: 0o600 });
|
|
88
90
|
await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
|
|
89
|
-
|
|
90
|
-
await writeFile(join(directory, 'report.html'), `<!doctype html><meta charset="utf-8"><title>Recovery Probe observation</title><style>body{font:16px system-ui;max-width:1000px;margin:40px auto;padding:20px}td,th{text-align:left;padding:8px}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style><h1>Fault-free observation</h1><p>Capture: ${escape(report.status)}. This is not a recovery or account-isolation verdict.</p><p>${escape(report.limitation ?? report.error)}</p><table><thead><tr><th>Interval</th><th>Reads started</th><th>Successes</th><th>Errors</th><th>First content sample</th></tr></thead><tbody>${rows}</tbody></table>${report.findings.map(f => `<p>Interval ${f.interval}: <strong>${escape(f.code)}</strong> — ${escape(f.basis)}</p>`).join('')}<details><summary>Evidence and coverage</summary><pre>${escape(JSON.stringify(report, null, 2))}</pre></details>`, { mode: 0o600 });
|
|
91
|
+
await writeFile(join(directory, 'report.html'), renderObservationReport(report), { mode: 0o600 });
|
|
91
92
|
if (options.json) console.log(JSON.stringify({ ...report, reportPath: join(directory, 'report.json') }));
|
|
92
93
|
else {
|
|
93
94
|
for (const i of report.intervals) console.log(`Interval ${i.index}: ${i.reads?.calls ?? '?'} reads, ${i.reads?.successes ?? '?'} successes, ${i.reads?.errors ?? '?'} errors${i.findings.length ? '; ' + i.findings.join(', ') : ''}`);
|
|
95
|
+
for (const finding of report.findings) console.log(`Interval ${finding.interval}: ${observationSummary(finding)}`);
|
|
96
|
+
console.log(`Sampling: requested delay ${config.sampleMs} ms; measured mean cadence ${report.sampling.startToStart.meanMs ?? 'unavailable'} ms.`);
|
|
94
97
|
if (report.error) console.error(report.error);
|
|
95
98
|
console.log(`Capture: ${report.status} (not a health verdict)\nReport: ${join(directory, 'report.html')}`);
|
|
96
99
|
}
|
package/docs/ci.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# A repeatable recovery check in CI
|
|
2
|
+
|
|
3
|
+
This synthetic example shows how to turn a specified recovery expectation into a CI result. It is not automatic discovery or a conversion of an arbitrary happy-path suite. Run it from a Recovery Probe source checkout with Node 22+:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm ci
|
|
7
|
+
npx playwright install --with-deps chromium
|
|
8
|
+
npm run test:ci-example
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The verifier runs the same saved `examples/ci/scenario.json` against broken and fixed versions of the bundled app. Both must pass the healthy baseline. It injects exactly one HTTP 503, clicks the explicit Retry button, then requires visible profile content with the exact expected text. The broken app leaves its loading guard set and cannot retry; the fixed app resets the guard and recovers.
|
|
12
|
+
|
|
13
|
+
The verifier only passes when the broken command exits 1 with `RECOVERY_ASSERTION_FAILED`, exactly one applied fault and verified cleanup, and the fixed command exits 0 with the same verified injection. A browser startup error, missed route or failed baseline does not count as detecting the defect. Each child has a 45-second timeout. Individual navigation and selector waits are bounded to 3 seconds. There are no test-runner retries that could hide the broken result.
|
|
14
|
+
|
|
15
|
+
To run a single variant as a normal gate:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
node examples/ci/run.mjs fixed artifacts/my-recovery-run
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Use a new output directory each time. Replace `fixed` with `broken` to observe exit 1. Exit 2 means an inconclusive/setup/cleanup failure. This command only starts the bundled synthetic application; adapting it to a real application requires explicit setup, actions and assertions.
|
|
22
|
+
|
|
23
|
+
Each variant saves `scenario.json`, `report.json`, `summary.md`, and baseline/fault Playwright trace ZIPs when tracing starts successfully. Open a trace locally:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx playwright show-trace artifacts/my-recovery-run/fault-trace.zip
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The scenario's selectors and expected text are synthetic. Traces record DOM snapshots, screenshots and sources; real-app traces may contain private data. Select artifact access and retention accordingly.
|
|
30
|
+
|
|
31
|
+
## GitHub Actions
|
|
32
|
+
|
|
33
|
+
The repository's Browser integration job runs the verifier and uploads artifacts even if a step fails. This standalone example assumes a checkout of this repository:
|
|
34
|
+
|
|
35
|
+
```yaml
|
|
36
|
+
name: Recovery example
|
|
37
|
+
on: [push, pull_request]
|
|
38
|
+
permissions:
|
|
39
|
+
contents: read
|
|
40
|
+
jobs:
|
|
41
|
+
recovery:
|
|
42
|
+
runs-on: ubuntu-latest
|
|
43
|
+
timeout-minutes: 5
|
|
44
|
+
steps:
|
|
45
|
+
- uses: actions/checkout@v7
|
|
46
|
+
- uses: actions/setup-node@v7
|
|
47
|
+
with:
|
|
48
|
+
node-version: '24'
|
|
49
|
+
cache: npm
|
|
50
|
+
- run: npm ci
|
|
51
|
+
- run: npx playwright install --with-deps chromium
|
|
52
|
+
- run: npm run test:ci-example
|
|
53
|
+
- uses: actions/upload-artifact@v6
|
|
54
|
+
if: always()
|
|
55
|
+
with:
|
|
56
|
+
name: recovery-example
|
|
57
|
+
path: artifacts/ci-example-*/
|
|
58
|
+
retention-days: 7
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Adapt it to an application
|
|
62
|
+
|
|
63
|
+
Install `recovery-probe@0.3.0-preview.13` and your compatible Playwright runtime. Copy the example's orchestration pattern into your test suite, replace the synthetic server startup with your authorized test application, choose one read-only request and specify the expected recovery action and result. Keep the healthy control, bounded fault count, cleanup, inconclusive outcomes and process exit checks. Run the normal gate against the current app; the deliberately broken variant belongs only in a synthetic verification fixture.
|
|
64
|
+
|
|
65
|
+
This example provides local/CI execution and artifacts. It does not post PR comments, upload to a hosted Recovery Probe service or infer what your product ought to display.
|
package/docs/desktop.md
CHANGED
|
@@ -38,8 +38,8 @@ Install the exact preview in a separate tester folder:
|
|
|
38
38
|
mkdir recovery-probe-desktop-test
|
|
39
39
|
cd recovery-probe-desktop-test
|
|
40
40
|
npm init -y
|
|
41
|
-
npm view recovery-probe@0.3.0-preview.
|
|
42
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.
|
|
41
|
+
npm view recovery-probe@0.3.0-preview.13 version
|
|
42
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.13 playwright@1.62.1
|
|
43
43
|
npx recovery-probe desktop --list
|
|
44
44
|
```
|
|
45
45
|
|
package/docs/ipc.md
CHANGED
|
@@ -12,8 +12,8 @@ Node 22+ is required for the CLI. Electron 29's bundled Node can load the small
|
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
mkdir -p recovery-probe-tools && cd recovery-probe-tools
|
|
15
|
-
npm view recovery-probe@0.3.0-preview.
|
|
16
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.
|
|
15
|
+
npm view recovery-probe@0.3.0-preview.13 version
|
|
16
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.13 playwright@1.62.1
|
|
17
17
|
node -p "require.resolve('recovery-probe/ipc')"
|
|
18
18
|
```
|
|
19
19
|
|
package/docs/observe.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Available in **0.3.0-preview.12**. Install the exact preview and verify the CLI:
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.
|
|
6
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.13 playwright@1.62.1
|
|
7
7
|
npx recovery-probe --version
|
|
8
8
|
```
|
|
9
9
|
|
|
@@ -28,7 +28,7 @@ Save a local JSON file, for example `observe.json`:
|
|
|
28
28
|
}
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
IPC requires the [explicit development hook](ipc.md), loaded **from the same installed
|
|
31
|
+
IPC requires the [explicit development hook](ipc.md), loaded **from the same installed package version** before handler registration. It must advertise `observation` and `readTimestamps` capabilities. An old running hook is rejected before starting a plan; reinstalling the CLI alone does not update a hook already loaded in the app. Resolve the updated hook with `node -p "require.resolve('recovery-probe/ipc')"`, update the app's development hook path if needed, and restart the development app **before reproducing the cached state**. The selected window is verified against that hook without reloading it.
|
|
32
32
|
|
|
33
33
|
For renderer HTTP reads, use:
|
|
34
34
|
|
|
@@ -66,6 +66,14 @@ Enter starts an interval at the next sample boundary; it does not navigate or re
|
|
|
66
66
|
|
|
67
67
|
To observe a particular cached state that already exists, start on a neutral screen immediately before returning to it. Reads before capture are unknown. Start earlier if you need a measured age of the last read.
|
|
68
68
|
|
|
69
|
+
## Report provenance and sampling
|
|
70
|
+
|
|
71
|
+
Since preview.13, `metadata` records the installed Recovery Probe version, CLI Node version, browser version when available, and the IPC hook's reported version, runtime and observation capabilities. Older observation-capable hooks remain compatible; unavailable metadata is null. Restart with the new hook if its version/runtime metadata is needed. No environment variables, account information, full user agent or registered-channel inventory is included.
|
|
72
|
+
|
|
73
|
+
`sampleMs` is the requested delay **after each completed sample**, not a guaranteed sampling resolution. `sampling.sampleDuration` summarizes the UI-read-to-counter-snapshot duration; `sampling.startToStart` measures actual cadence, including protocol work, delays and operator callbacks. Both contain count, meanMs, minMs and maxMs. All completed samples contribute, including unchanged samples omitted from the timeline. With no samples the duration statistics are null; with fewer than two samples cadence statistics are null. A timed-out/incomplete sample is not included. `captureComplete` retains its existing meaning and does not guarantee that brief UI flashes were captured.
|
|
74
|
+
|
|
75
|
+
JSON findings retain their codes/bases and add a plain-language `summary`. HTML shows first-content sample bounds relative to each interval rather than an exact paint time.
|
|
76
|
+
|
|
69
77
|
## Interpretation
|
|
70
78
|
|
|
71
79
|
Local `report.json` and `report.html` contain interval read counts, starts/completions, first-content sample bounds, and a change-only sampled timeline. `scenario.json` records the selected scope. No screenshots, response bodies or raw UI values are saved. Region text and repeated values are hashed; hashes are **not anonymization**, particularly for predictable text. Treat reports and selectors as private evidence.
|
package/docs/start.md
CHANGED
|
@@ -10,8 +10,8 @@ Install the exact npm preview after confirming availability:
|
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
mkdir recovery-probe-tools && cd recovery-probe-tools
|
|
13
|
-
npm view recovery-probe@0.3.0-preview.
|
|
14
|
-
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.
|
|
13
|
+
npm view recovery-probe@0.3.0-preview.13 version
|
|
14
|
+
npm install --save-dev --save-exact recovery-probe@0.3.0-preview.13 playwright@1.62.1
|
|
15
15
|
npx recovery-probe start web http://localhost:3000
|
|
16
16
|
```
|
|
17
17
|
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// Runnable synthetic CI example. Adapt the fixture, actions and assertions to your app.
|
|
2
|
+
import assert from 'node:assert/strict';
|
|
3
|
+
import { readFile, mkdir, writeFile } from 'node:fs/promises';
|
|
4
|
+
import { resolve, join } from 'node:path';
|
|
5
|
+
import { chromium } from 'playwright';
|
|
6
|
+
import { withFault } from 'recovery-probe';
|
|
7
|
+
import { startDemoServer } from '../demo-server.mjs';
|
|
8
|
+
|
|
9
|
+
const variant = process.argv[2];
|
|
10
|
+
const output = process.argv[3];
|
|
11
|
+
if (!['broken', 'fixed'].includes(variant) || !output || process.argv.length !== 4) {
|
|
12
|
+
console.error('Usage: node examples/ci/run.mjs broken|fixed NEW_OUTPUT_DIRECTORY');
|
|
13
|
+
process.exitCode = 2;
|
|
14
|
+
} else {
|
|
15
|
+
const directory = resolve(output);
|
|
16
|
+
await mkdir(directory, { mode: 0o700 }); // Never overwrite a previous experiment.
|
|
17
|
+
const scenario = JSON.parse(await readFile(new URL('./scenario.json', import.meta.url), 'utf8'));
|
|
18
|
+
const report = { variant, status: 'inconclusive', code: 'SETUP_FAILED', baseline: false, fault: null, cleanup: 'not-started' };
|
|
19
|
+
let server, browser;
|
|
20
|
+
try {
|
|
21
|
+
server = await startDemoServer();
|
|
22
|
+
browser = await chromium.launch();
|
|
23
|
+
async function inPage(name, exercise) {
|
|
24
|
+
const context = await browser.newContext({ serviceWorkers: 'block' });
|
|
25
|
+
try {
|
|
26
|
+
await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
|
|
27
|
+
const page = await context.newPage();
|
|
28
|
+
page.setDefaultTimeout(scenario.timeoutMs);
|
|
29
|
+
page.setDefaultNavigationTimeout(scenario.timeoutMs);
|
|
30
|
+
await exercise(page);
|
|
31
|
+
} finally {
|
|
32
|
+
try { await context.tracing.stop({ path: join(directory, `${name}-trace.zip`) }); }
|
|
33
|
+
finally { await context.close(); }
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
const ready = async page => {
|
|
37
|
+
await page.locator(scenario.readySelector).waitFor({ state: 'visible' });
|
|
38
|
+
assert.equal(await page.locator(scenario.readySelector).textContent(), scenario.expectedText);
|
|
39
|
+
};
|
|
40
|
+
await inPage('baseline', async page => {
|
|
41
|
+
await page.goto(`${server.url}/${variant}`, { waitUntil: 'domcontentloaded' });
|
|
42
|
+
await ready(page);
|
|
43
|
+
});
|
|
44
|
+
report.baseline = true;
|
|
45
|
+
await inPage('fault', async page => {
|
|
46
|
+
report.fault = await withFault(page, { ...scenario.fault, match: `${server.url}${scenario.requestPath}`, method: 'GET' }, async () => {
|
|
47
|
+
await page.goto(`${server.url}/${variant}`, { waitUntil: 'domcontentloaded' });
|
|
48
|
+
await page.locator(scenario.retrySelector).waitFor({ state: 'visible' });
|
|
49
|
+
await page.locator(scenario.retrySelector).click();
|
|
50
|
+
await ready(page);
|
|
51
|
+
});
|
|
52
|
+
});
|
|
53
|
+
assert.equal(report.fault.applied, 1);
|
|
54
|
+
report.status = 'pass'; report.code = 'OK';
|
|
55
|
+
} catch (error) {
|
|
56
|
+
report.status = error.code === 'RECOVERY_ASSERTION_FAILED' ? 'fail' : 'inconclusive';
|
|
57
|
+
report.code = error.code ?? 'RUNNER_ERROR';
|
|
58
|
+
report.fault = error.stats ?? report.fault;
|
|
59
|
+
} finally {
|
|
60
|
+
const cleanup = await Promise.allSettled([browser?.close(), server?.close()]);
|
|
61
|
+
report.cleanup = cleanup.every(r => r.status === 'fulfilled') ? 'complete' : 'unverified';
|
|
62
|
+
if (report.cleanup !== 'complete') { report.status = 'inconclusive'; report.code = 'CLEANUP_FAILED'; }
|
|
63
|
+
}
|
|
64
|
+
await writeFile(join(directory, 'scenario.json'), JSON.stringify(scenario, null, 2), { mode: 0o600 });
|
|
65
|
+
await writeFile(join(directory, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
|
|
66
|
+
const summary = `| Variant | Baseline | Faults applied | Result | Code |\n| --- | --- | --- | --- | --- |\n| ${variant} | ${report.baseline ? 'passed' : 'not established'} | ${report.fault?.applied ?? 0} | ${report.status} | ${report.code} |\n`;
|
|
67
|
+
await writeFile(join(directory, 'summary.md'), summary, { mode: 0o600 });
|
|
68
|
+
console.log(summary);
|
|
69
|
+
process.exitCode = report.status === 'pass' ? 0 : report.status === 'fail' ? 1 : 2;
|
|
70
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
// Verify both the CLI exit status and evidence: an unrelated crash is never the expected failure.
|
|
2
|
+
import assert from 'node:assert/strict';
|
|
3
|
+
import { spawn } from 'node:child_process';
|
|
4
|
+
import { mkdir, mkdtemp, readFile, appendFile } from 'node:fs/promises';
|
|
5
|
+
import { fileURLToPath } from 'node:url';
|
|
6
|
+
import { resolve, join } from 'node:path';
|
|
7
|
+
await mkdir('artifacts', { recursive: true });
|
|
8
|
+
const directory = await mkdtemp(resolve('artifacts/ci-example-'));
|
|
9
|
+
for (const variant of ['broken', 'fixed']) {
|
|
10
|
+
const output = join(directory, variant);
|
|
11
|
+
const code = await new Promise((done, reject) => {
|
|
12
|
+
const child = spawn(process.execPath, [fileURLToPath(new URL('./run.mjs', import.meta.url)), variant, output], { stdio: 'inherit', timeout: 45000 });
|
|
13
|
+
child.once('error', reject);
|
|
14
|
+
child.once('exit', (status, signal) => signal ? reject(Error(`Example stopped: ${signal}`)) : done(status));
|
|
15
|
+
});
|
|
16
|
+
if (process.env.GITHUB_STEP_SUMMARY) await appendFile(process.env.GITHUB_STEP_SUMMARY, await readFile(join(output, 'summary.md'), 'utf8'));
|
|
17
|
+
const report = JSON.parse(await readFile(join(output, 'report.json'), 'utf8'));
|
|
18
|
+
assert.equal(report.baseline, true);
|
|
19
|
+
assert.equal(report.fault.applied, 1);
|
|
20
|
+
assert.equal(report.fault.injectionErrors, 0);
|
|
21
|
+
assert.equal(report.cleanup, 'complete');
|
|
22
|
+
assert.equal(code, variant === 'broken' ? 1 : 0);
|
|
23
|
+
assert.equal(report.status, variant === 'broken' ? 'fail' : 'pass');
|
|
24
|
+
assert.equal(report.code, variant === 'broken' ? 'RECOVERY_ASSERTION_FAILED' : 'OK');
|
|
25
|
+
}
|
|
26
|
+
console.log(`Broken/fixed CI example verified. Artifacts: ${directory}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "recovery-probe",
|
|
3
|
-
"version": "0.3.0-preview.
|
|
3
|
+
"version": "0.3.0-preview.13",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Test recovery from failed reads in web and Electron desktop apps, during loading and refresh.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -57,7 +57,8 @@
|
|
|
57
57
|
"docs/start.md",
|
|
58
58
|
"docs/ipc.md",
|
|
59
59
|
"docs/refresh.md",
|
|
60
|
-
"docs/observe.md"
|
|
60
|
+
"docs/observe.md",
|
|
61
|
+
"docs/ci.md"
|
|
61
62
|
],
|
|
62
63
|
"sideEffects": false,
|
|
63
64
|
"engines": {
|
|
@@ -105,7 +106,7 @@
|
|
|
105
106
|
"test:core": "node --test test/fetch-core.test.mjs",
|
|
106
107
|
"test:browser": "node --test test/recovery.integration.test.mjs test/discovery.integration.test.mjs test/discovery-calibration.integration.test.mjs test/attach.integration.test.mjs test/refresh.integration.test.mjs test/observe.integration.test.mjs",
|
|
107
108
|
"test:package": "node --test test/package.integration.test.mjs",
|
|
108
|
-
"test:all": "npm run test:core && npm run test:package && npm run test:browser && npm run test:desktop && npm run test:repair && npm run test:guided && npm run test:ipc",
|
|
109
|
+
"test:all": "npm run test:core && npm run test:package && npm run test:browser && npm run test:desktop && npm run test:repair && npm run test:guided && npm run test:ipc && npm run test:ci-example",
|
|
109
110
|
"demo": "node bin/core-demo.mjs",
|
|
110
111
|
"demo:browser": "node bin/recovery-probe.mjs --demo --out artifacts/browser-demo.json",
|
|
111
112
|
"prepublishOnly": "npm run test:core && npm run test:package && npm run test:ipc",
|
|
@@ -114,7 +115,8 @@
|
|
|
114
115
|
"test:repair": "node --test test/repair.test.mjs test/repair.integration.test.mjs test/web.integration.test.mjs",
|
|
115
116
|
"test:repair:electron": "node --test test/repair.electron.test.mjs",
|
|
116
117
|
"test:guided": "node --test test/guided-start.test.mjs test/guided-start.integration.test.mjs",
|
|
117
|
-
"test:ipc": "node --test test/ipc-probe.test.mjs test/ipc-control.test.mjs test/ipc-observation.test.mjs test/visibility.test.mjs test/refresh.test.mjs test/observe.test.mjs",
|
|
118
|
-
"test:ipc:electron": "node --test --test-concurrency=1 test/ipc.electron.test.mjs test/observe.electron.test.mjs"
|
|
118
|
+
"test:ipc": "node --test test/ipc-probe.test.mjs test/ipc-control.test.mjs test/ipc-observation.test.mjs test/visibility.test.mjs test/refresh.test.mjs test/observe.test.mjs test/observation-report.test.mjs",
|
|
119
|
+
"test:ipc:electron": "node --test --test-concurrency=1 test/ipc.electron.test.mjs test/observe.electron.test.mjs",
|
|
120
|
+
"test:ci-example": "node examples/ci/verify.mjs"
|
|
119
121
|
}
|
|
120
122
|
}
|
package/src/ipc-probe.cjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
'use strict';
|
|
2
|
+
const { version } = require('../package.json');
|
|
2
3
|
|
|
3
4
|
const installed = new WeakSet();
|
|
4
5
|
|
|
@@ -18,7 +19,7 @@ exports.installIpcProbe = function installIpcProbe(ipcMain, { channels, sender,
|
|
|
18
19
|
const identify = challenge => {
|
|
19
20
|
const contents = sender();
|
|
20
21
|
if (!contents || contents.isDestroyed()) throw new Error('Target WebContents is not available');
|
|
21
|
-
const identity = { senderId: contents.id, pageUrl: contents.getURL(), registered: [...registered], capabilities: { maxFaultCount: 10, observation: true, readTimestamps: true } };
|
|
22
|
+
const identity = { version, runtime: { node: process.versions.node, electron: process.versions.electron ?? null, chrome: process.versions.chrome ?? null }, senderId: contents.id, pageUrl: contents.getURL(), registered: [...registered], capabilities: { maxFaultCount: 10, observation: true, readTimestamps: true } };
|
|
22
23
|
if (challenge === undefined) return identity;
|
|
23
24
|
if (typeof challenge !== 'string' || !/^[a-f0-9-]{36}$/.test(challenge)) throw new Error('Invalid window challenge');
|
|
24
25
|
return contents.executeJavaScript(`globalThis.__recoveryProbeWindowNonce === ${JSON.stringify(challenge)}`).then(matches => {
|
package/src/ipc-probe.d.cts
CHANGED
|
@@ -9,8 +9,8 @@ export interface IpcSnapshot {
|
|
|
9
9
|
channels: Record<string, { calls: number; realCalls: number; successes: number; errors: number; pending: number; maxDurationMs: number; firstReadAt: number | null; lastReadAt: number | null; firstCompletedAt: number | null; lastCompletedAt: number | null; lastSuccessAt: number | null }>;
|
|
10
10
|
}
|
|
11
11
|
export interface IpcProbe {
|
|
12
|
-
identify(): { senderId: number; pageUrl: string; registered: string[]; capabilities: { maxFaultCount: number; observation: true; readTimestamps: true } };
|
|
13
|
-
identify(challenge: string): Promise<{ senderId: number; pageUrl: string; registered: string[]; capabilities: { maxFaultCount: number; observation: true; readTimestamps: true } }>;
|
|
12
|
+
identify(): { version: string; runtime: { node: string; electron: string | null; chrome: string | null }; senderId: number; pageUrl: string; registered: string[]; capabilities: { maxFaultCount: number; observation: true; readTimestamps: true } };
|
|
13
|
+
identify(challenge: string): Promise<{ version: string; runtime: { node: string; electron: string | null; chrome: string | null }; senderId: number; pageUrl: string; registered: string[]; capabilities: { maxFaultCount: number; observation: true; readTimestamps: true } }>;
|
|
14
14
|
begin(options: { id: string; channel: string; requiredChannels?: string[]; times?: number; ttlMs?: number } & ({ observation: true; fault?: never } | { observation?: false; fault?: 'rejection' | 'null-result' })): IpcSnapshot;
|
|
15
15
|
snapshot(): IpcSnapshot | null;
|
|
16
16
|
windowState(): { minimized: boolean };
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { createRequire } from 'node:module';
|
|
2
|
+
const { version } = createRequire(import.meta.url)('../package.json');
|
|
3
|
+
|
|
4
|
+
export function observationMetadata() {
|
|
5
|
+
return { recoveryProbeVersion: version, runtime: { node: process.versions.node }, browserVersion: null, ipcHook: null };
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
// Aggregate every completed sample, including samples omitted from the change-only timeline.
|
|
9
|
+
export function samplingMetrics(requestedDelayMs) {
|
|
10
|
+
let previous, count = 0, sum = 0, min = Infinity, max = 0;
|
|
11
|
+
let gaps = 0, gapSum = 0, gapMin = Infinity, gapMax = 0;
|
|
12
|
+
return {
|
|
13
|
+
add(fromMs, toMs) {
|
|
14
|
+
const duration = toMs - fromMs;
|
|
15
|
+
count++; sum += duration; min = Math.min(min, duration); max = Math.max(max, duration);
|
|
16
|
+
if (previous !== undefined) {
|
|
17
|
+
const gap = fromMs - previous;
|
|
18
|
+
gaps++; gapSum += gap; gapMin = Math.min(gapMin, gap); gapMax = Math.max(gapMax, gap);
|
|
19
|
+
}
|
|
20
|
+
previous = fromMs;
|
|
21
|
+
},
|
|
22
|
+
snapshot() {
|
|
23
|
+
const stats = (n, total, low, high) => ({ count: n, meanMs: n ? Math.round(total / n * 100) / 100 : null, minMs: n ? low : null, maxMs: n ? high : null });
|
|
24
|
+
return { requestedDelayMs, completedSamples: count,
|
|
25
|
+
sampleDuration: stats(count, sum, min, max), startToStart: stats(gaps, gapSum, gapMin, gapMax),
|
|
26
|
+
note: 'The configured delay follows each completed sample. Sample duration brackets the UI read and following counter snapshot; cadence also includes other protocol work. These are completed-sample measurements, not guaranteed temporal coverage.' };
|
|
27
|
+
},
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function observationSummary(finding) {
|
|
32
|
+
if (finding.basis === 'NO_READ_OBSERVED_IN_INTERVAL') return 'Content was visible without a new selected read in this interval.';
|
|
33
|
+
if (finding.basis === 'NO_COMPLETION_OBSERVED_IN_INTERVAL') return 'Content was visible before any selected read completed in this interval (a read was pending or had started).';
|
|
34
|
+
return 'Content/read ordering was observed; inspect the evidence.';
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const escape = value => String(value).replace(/[&<>"']/g, c => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[c]));
|
|
38
|
+
export function renderObservationReport(report) {
|
|
39
|
+
const rows = report.intervals.map(i => `<tr><td>${i.index}</td><td>${i.reads?.calls ?? 'unknown'}</td><td>${i.reads?.successes ?? 'unknown'}</td><td>${i.reads?.errors ?? 'unknown'}</td><td>${i.firstContent ? `${i.firstContent.fromMs - i.startMs}–${i.firstContent.toMs - i.startMs} ms` : 'not sampled'}</td></tr>`).join('');
|
|
40
|
+
const sampling = report.sampling;
|
|
41
|
+
return `<!doctype html><meta charset="utf-8"><title>Recovery Probe observation</title><style>body{font:16px system-ui;max-width:1000px;margin:40px auto;padding:20px}td,th{text-align:left;padding:8px}pre{white-space:pre-wrap;overflow-wrap:anywhere}</style><h1>Fault-free observation</h1><p>Capture: ${escape(report.status)}. This is not a recovery or account-isolation verdict.</p><p>Recovery Probe ${escape(report.metadata?.recoveryProbeVersion ?? 'unknown')} · Node ${escape(report.metadata?.runtime?.node ?? 'unknown')} · Browser ${escape(report.metadata?.browserVersion ?? 'unknown')} · IPC hook ${escape(report.metadata?.ipcHook?.version ?? 'unknown / not applicable')}</p>${sampling ? `<p>Configured delay: ${sampling.requestedDelayMs} ms. Completed samples: ${sampling.completedSamples}. Mean sample duration: ${sampling.sampleDuration.meanMs ?? 'unavailable'} ms. Mean start-to-start cadence: ${sampling.startToStart.meanMs ?? 'unavailable'} ms (maximum ${sampling.startToStart.maxMs ?? 'unavailable'} ms).</p><p>${escape(sampling.note)}</p>` : ''}<p>${escape(report.limitation ?? report.error)}</p><table><thead><tr><th>Interval</th><th>Reads started</th><th>Successes</th><th>Errors</th><th>First content sample bounds</th></tr></thead><tbody>${rows}</tbody></table>${report.findings.map(f => `<p>Interval ${f.interval}: ${escape(observationSummary(f))} <strong>${escape(f.code)}</strong> — ${escape(f.basis)}</p>`).join('')}<details><summary>Evidence and coverage</summary><pre>${escape(JSON.stringify(report, null, 2))}</pre></details>`;
|
|
42
|
+
}
|
package/src/observe.mjs
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { observationMetadata, samplingMetrics, observationSummary } from './observation-report.mjs';
|
|
1
2
|
import { performance } from 'node:perf_hooks';
|
|
2
3
|
import { randomUUID } from 'node:crypto';
|
|
3
4
|
import { readRegion, summarizeRegion } from './ipc-observation.mjs';
|
|
@@ -34,11 +35,13 @@ export function observationConfig(input) {
|
|
|
34
35
|
}
|
|
35
36
|
|
|
36
37
|
export function ipcObservationAdapter(control, config, senderId) {
|
|
37
|
-
let id;
|
|
38
|
+
let id, metadata = null;
|
|
38
39
|
return {
|
|
40
|
+
metadata: () => metadata,
|
|
39
41
|
async start() {
|
|
40
42
|
const identity = await control.call('identify');
|
|
41
43
|
if (!identity.capabilities?.observation || !identity.capabilities?.readTimestamps) throw Error('IPC_OBSERVATION_UNSUPPORTED: restart the development app with the new observation-capable hook');
|
|
44
|
+
metadata = { version: identity.version ?? null, runtime: { node: identity.runtime?.node ?? null, electron: identity.runtime?.electron ?? null, chrome: identity.runtime?.chrome ?? null }, capabilities: { observation: identity.capabilities.observation, readTimestamps: identity.capabilities.readTimestamps, maxFaultCount: identity.capabilities.maxFaultCount ?? null } };
|
|
42
45
|
if (identity.senderId !== senderId) throw Error('IPC_TARGET_CHANGED');
|
|
43
46
|
const previous = await control.call('snapshot');
|
|
44
47
|
if (previous?.armed || previous?.observingUntil) throw Error('IPC_PLAN_ALREADY_ACTIVE');
|
|
@@ -95,7 +98,8 @@ async function boundedUiRead(action, signal) {
|
|
|
95
98
|
export async function runObservation(page, input, adapter, { signal, takeMarker = () => false, onReady = () => {}, onInterval = () => {}, onSample = () => {} } = {}) {
|
|
96
99
|
const c = observationConfig(input);
|
|
97
100
|
const target = c.transport === 'ipc' ? c.channel : c.endpoint;
|
|
98
|
-
const
|
|
101
|
+
const metrics = samplingMetrics(c.sampleMs);
|
|
102
|
+
const report = { schemaVersion: 1, metadata: observationMetadata(), mode: 'fault-free observation', transport: c.transport, target, generatedAt: new Date().toISOString(),
|
|
99
103
|
status: 'incomplete', captureComplete: false, observationMs: c.observationMs, sampleMs: c.sampleMs, intervals: [], findings: [], timeline: [],
|
|
100
104
|
injected: 0, reloads: 0, cleanup: 'not-started',
|
|
101
105
|
coverage: { historyBeforeCapture: 'unknown', pendingBeforeCapture: 'unknown', scope: 'One selected renderer and read target; only calls starting during capture are counted.', gaps: [] },
|
|
@@ -124,6 +128,7 @@ export async function runObservation(page, input, adapter, { signal, takeMarker
|
|
|
124
128
|
page.on('pageerror', errors); page.on('domcontentloaded', documentLoaded);
|
|
125
129
|
attempted = true;
|
|
126
130
|
await adapter.start();
|
|
131
|
+
report.metadata.ipcHook = adapter.metadata?.() ?? null;
|
|
127
132
|
started = performance.now();
|
|
128
133
|
lastSnapshot = await adapter.snapshot();
|
|
129
134
|
report.startedAt = lastSnapshot.startedAt;
|
|
@@ -162,6 +167,7 @@ export async function runObservation(page, input, adapter, { signal, takeMarker
|
|
|
162
167
|
basis: readCounts.calls === 0 && readCounts.pendingAtStart === 0 ? 'NO_READ_OBSERVED_IN_INTERVAL' : 'NO_COMPLETION_OBSERVED_IN_INTERVAL',
|
|
163
168
|
reads: readCounts, lastReadAgeMs: event.lastReadAgeMs, lastCompletionAgeMs: event.lastCompletionAgeMs,
|
|
164
169
|
note: 'The configured content marker is visible. This does not establish cache origin, ownership, a mount boundary, or a defect; earlier and unobserved reads are possible.' };
|
|
170
|
+
finding.summary = observationSummary(finding);
|
|
165
171
|
interval.findings.push(finding.code); report.findings.push(finding);
|
|
166
172
|
}
|
|
167
173
|
const signature = JSON.stringify([interval.index, ui, readCounts, pageErrors]);
|
|
@@ -169,6 +175,7 @@ export async function runObservation(page, input, adapter, { signal, takeMarker
|
|
|
169
175
|
if (report.timeline.length < 1000) report.timeline.push(event); else gap('TIMELINE_LIMIT_REACHED');
|
|
170
176
|
previousSignature = signature;
|
|
171
177
|
}
|
|
178
|
+
metrics.add(event.fromMs, event.toMs);
|
|
172
179
|
interval.samples++; samples++;
|
|
173
180
|
await onSample(event);
|
|
174
181
|
if (performance.now() - started >= c.observationMs) { report.status = 'complete'; break; }
|
|
@@ -181,6 +188,7 @@ export async function runObservation(page, input, adapter, { signal, takeMarker
|
|
|
181
188
|
if (interval) closeInterval();
|
|
182
189
|
report.elapsedMs = started === undefined ? 0 : elapsed();
|
|
183
190
|
report.samples = samples;
|
|
191
|
+
report.sampling = metrics.snapshot();
|
|
184
192
|
report.snapshot = lastSnapshot;
|
|
185
193
|
page.off('pageerror', errors); page.off('domcontentloaded', documentLoaded);
|
|
186
194
|
if (attempted) {
|