recovery-probe 0.5.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (387) hide show
  1. package/CHANGELOG.md +274 -0
  2. package/CONTRIBUTING.md +34 -7
  3. package/README.md +86 -94
  4. package/dist/cli/action.d.mts +20 -0
  5. package/dist/cli/action.mjs +58 -0
  6. package/dist/cli/android.mjs +67 -59
  7. package/dist/cli/args.d.mts +18 -0
  8. package/dist/cli/args.mjs +63 -0
  9. package/dist/cli/check.d.mts +41 -0
  10. package/dist/cli/check.mjs +178 -0
  11. package/dist/cli/compare.mjs +41 -22
  12. package/dist/cli/core-demo.mjs +2 -1
  13. package/dist/cli/demo.d.mts +11 -0
  14. package/dist/cli/demo.mjs +15 -0
  15. package/dist/cli/discover.d.mts +29 -0
  16. package/dist/cli/discover.mjs +98 -0
  17. package/dist/cli/doctor.d.mts +1 -0
  18. package/dist/cli/doctor.mjs +41 -0
  19. package/dist/cli/init.d.mts +1 -0
  20. package/dist/cli/init.mjs +95 -0
  21. package/dist/cli/login.d.mts +11 -0
  22. package/dist/cli/login.mjs +40 -0
  23. package/dist/cli/main.mjs +161 -204
  24. package/dist/cli/mcp.mjs +7 -7
  25. package/dist/cli/net.mjs +61 -53
  26. package/dist/cli/observe.mjs +172 -235
  27. package/dist/cli/reads.d.mts +29 -0
  28. package/dist/cli/reads.mjs +102 -0
  29. package/dist/cli/refresh.mjs +47 -118
  30. package/dist/cli/repair.mjs +64 -53
  31. package/dist/cli/runner.d.mts +24 -0
  32. package/dist/cli/runner.mjs +111 -0
  33. package/dist/cli/start.mjs +7 -18
  34. package/dist/cli/suspects.mjs +13 -19
  35. package/dist/cli/terminal.d.mts +5 -0
  36. package/dist/cli/terminal.mjs +19 -0
  37. package/dist/cli/verify.d.mts +1 -0
  38. package/dist/cli/verify.mjs +58 -0
  39. package/dist/cli/watch.mjs +75 -87
  40. package/dist/cli/windows.d.mts +11 -0
  41. package/dist/cli/windows.mjs +35 -0
  42. package/dist/core/faults.d.mts +13 -0
  43. package/dist/core/faults.mjs +25 -0
  44. package/dist/core/package.d.mts +3 -0
  45. package/dist/core/package.mjs +6 -0
  46. package/dist/core/region-read.d.mts +57 -0
  47. package/dist/core/region-read.mjs +222 -0
  48. package/dist/{ipc-observation.d.mts → core/screen.d.mts} +3 -50
  49. package/dist/core/screen.mjs +104 -0
  50. package/dist/core/selector.d.mts +9 -0
  51. package/dist/core/selector.mjs +22 -0
  52. package/dist/core/server.d.mts +5 -0
  53. package/dist/core/server.mjs +14 -0
  54. package/dist/core/urls.d.mts +1 -0
  55. package/dist/core/urls.mjs +8 -0
  56. package/dist/core/validate.d.mts +19 -0
  57. package/dist/core/validate.mjs +39 -0
  58. package/dist/desktop.d.mts +6 -73
  59. package/dist/desktop.mjs +5 -422
  60. package/dist/fetch-fault.d.mts +2 -21
  61. package/dist/fetch-fault.mjs +1 -84
  62. package/dist/hook/calls.cjs +54 -0
  63. package/dist/hook/calls.d.cts +14 -0
  64. package/dist/hook/checks.cjs +69 -0
  65. package/dist/hook/checks.d.cts +48 -0
  66. package/dist/hook/probe.cjs +253 -0
  67. package/dist/hook/probe.d.cts +16 -0
  68. package/dist/hook/pushes.cjs +75 -0
  69. package/dist/hook/pushes.d.cts +10 -0
  70. package/dist/hook/state.cjs +76 -0
  71. package/dist/hook/state.d.cts +13 -0
  72. package/dist/hook/stats.cjs +38 -0
  73. package/dist/hook/stats.d.cts +9 -0
  74. package/dist/hook/types.cjs +4 -0
  75. package/dist/hook/types.d.cts +119 -0
  76. package/dist/index.d.mts +6 -49
  77. package/dist/index.mjs +4 -240
  78. package/dist/ipc-inspector.d.mts +1 -19
  79. package/dist/ipc-inspector.mjs +1 -144
  80. package/dist/ipc-probe.cjs +3 -391
  81. package/dist/ipc-probe.d.cts +2 -122
  82. package/dist/net-fault.d.mts +4 -80
  83. package/dist/net-fault.mjs +3 -307
  84. package/dist/{action-report.d.mts → reports/action.d.mts} +1 -1
  85. package/dist/{action-report.mjs → reports/action.mjs} +3 -2
  86. package/dist/reports/check.d.mts +13 -0
  87. package/dist/{desktop-report.mjs → reports/check.mjs} +42 -5
  88. package/dist/reports/discovery.d.mts +23 -0
  89. package/dist/reports/discovery.mjs +44 -0
  90. package/dist/reports/evidence.d.mts +48 -0
  91. package/dist/reports/evidence.mjs +176 -0
  92. package/dist/reports/folder.d.mts +5 -0
  93. package/dist/reports/folder.mjs +21 -0
  94. package/dist/{report-template.d.mts → reports/template.d.mts} +1 -1
  95. package/dist/{report-template.mjs → reports/template.mjs} +2 -2
  96. package/dist/{report-templates → reports/templates}/desktop.html +3 -3
  97. package/dist/{report-templates → reports/templates}/discovery.html +8 -0
  98. package/dist/targets/browser.d.mts +13 -0
  99. package/dist/targets/browser.mjs +25 -0
  100. package/dist/{cdp-bridge.d.mts → targets/cdp-bridge/bridge.d.mts} +1 -14
  101. package/dist/targets/cdp-bridge/bridge.mjs +97 -0
  102. package/dist/targets/cdp-bridge/filter.d.mts +19 -0
  103. package/dist/targets/cdp-bridge/filter.mjs +75 -0
  104. package/dist/targets/cdp-bridge/websocket.d.mts +8 -0
  105. package/dist/targets/cdp-bridge/websocket.mjs +121 -0
  106. package/dist/targets/cdp.d.mts +7 -0
  107. package/dist/targets/cdp.mjs +45 -0
  108. package/dist/targets/ipc-window.d.mts +11 -0
  109. package/dist/targets/ipc-window.mjs +17 -0
  110. package/dist/{visibility.d.mts → targets/visibility.d.mts} +7 -1
  111. package/dist/targets/visibility.mjs +149 -0
  112. package/dist/tools/ask.d.mts +17 -0
  113. package/dist/tools/ask.mjs +37 -0
  114. package/dist/tools/compare/markdown.d.mts +5 -0
  115. package/dist/tools/compare/markdown.mjs +58 -0
  116. package/dist/tools/compare/reports.d.mts +12 -0
  117. package/dist/tools/compare/reports.mjs +53 -0
  118. package/dist/tools/compare/run.d.mts +15 -0
  119. package/dist/tools/compare/run.mjs +96 -0
  120. package/dist/tools/compare/types.d.mts +49 -0
  121. package/dist/tools/compare/types.mjs +1 -0
  122. package/dist/tools/compare/verdict.d.mts +4 -0
  123. package/dist/tools/compare/verdict.mjs +74 -0
  124. package/dist/tools/doctor.d.mts +33 -0
  125. package/dist/tools/doctor.mjs +183 -0
  126. package/dist/tools/init.d.mts +38 -0
  127. package/dist/tools/init.mjs +24 -0
  128. package/dist/tools/mcp/args.d.mts +6 -0
  129. package/dist/tools/mcp/args.mjs +41 -0
  130. package/dist/tools/mcp/browser-tools.d.mts +3 -0
  131. package/dist/tools/mcp/browser-tools.mjs +144 -0
  132. package/dist/tools/mcp/change-tools.d.mts +4 -0
  133. package/dist/tools/mcp/change-tools.mjs +152 -0
  134. package/dist/tools/mcp/cli-tool.d.mts +2 -0
  135. package/dist/tools/mcp/cli-tool.mjs +80 -0
  136. package/dist/tools/mcp/network-tools.d.mts +4 -0
  137. package/dist/tools/mcp/network-tools.mjs +112 -0
  138. package/dist/tools/mcp/server.mjs +141 -0
  139. package/dist/tools/mcp/tools.d.mts +5 -0
  140. package/dist/tools/mcp/tools.mjs +25 -0
  141. package/dist/{pick-marker.mjs → tools/pick-marker.mjs} +8 -2
  142. package/dist/tools/repair/config.d.mts +17 -0
  143. package/dist/tools/repair/config.mjs +61 -0
  144. package/dist/{repair-process.mjs → tools/repair/process.mjs} +23 -25
  145. package/dist/{repair-provider.mjs → tools/repair/provider.mjs} +21 -17
  146. package/dist/{repair.d.mts → tools/repair/run.d.mts} +6 -32
  147. package/dist/tools/repair/run.mjs +165 -0
  148. package/dist/tools/repair/sources.d.mts +14 -0
  149. package/dist/tools/repair/sources.mjs +89 -0
  150. package/dist/tools/repair/target.d.mts +6 -0
  151. package/dist/tools/repair/target.mjs +89 -0
  152. package/dist/tools/repair/workspace.d.mts +17 -0
  153. package/dist/tools/repair/workspace.mjs +90 -0
  154. package/dist/tools/start/args.d.mts +9 -0
  155. package/dist/tools/start/args.mjs +29 -0
  156. package/dist/tools/start/browser.d.mts +5 -0
  157. package/dist/tools/start/browser.mjs +39 -0
  158. package/dist/tools/start/configure.d.mts +15 -0
  159. package/dist/tools/start/configure.mjs +63 -0
  160. package/dist/tools/start/run.d.mts +17 -0
  161. package/dist/tools/start/run.mjs +199 -0
  162. package/dist/tools/suspects/files.d.mts +18 -0
  163. package/dist/tools/suspects/files.mjs +104 -0
  164. package/dist/tools/suspects/paths.d.mts +8 -0
  165. package/dist/tools/suspects/paths.mjs +55 -0
  166. package/dist/tools/suspects/rules.d.mts +10 -0
  167. package/dist/tools/suspects/rules.mjs +69 -0
  168. package/dist/tools/suspects/scan.d.mts +21 -0
  169. package/dist/tools/suspects/scan.mjs +38 -0
  170. package/dist/tools/suspects/source.d.mts +18 -0
  171. package/dist/tools/suspects/source.mjs +77 -0
  172. package/dist/tools/suspects/tree.d.mts +31 -0
  173. package/dist/tools/suspects/tree.mjs +174 -0
  174. package/dist/tools/verify.d.mts +63 -0
  175. package/dist/tools/verify.mjs +177 -0
  176. package/dist/tools/watch/checks.d.mts +19 -0
  177. package/dist/tools/watch/checks.mjs +62 -0
  178. package/dist/{watch.d.mts → tools/watch/run.d.mts} +4 -24
  179. package/dist/tools/watch/run.mjs +163 -0
  180. package/dist/tools/watch/sources.d.mts +13 -0
  181. package/dist/tools/watch/sources.mjs +110 -0
  182. package/dist/tools/watch/summary.d.mts +4 -0
  183. package/dist/tools/watch/summary.mjs +38 -0
  184. package/dist/transports/fetch.d.mts +21 -0
  185. package/dist/transports/fetch.mjs +90 -0
  186. package/dist/{http-observer.d.mts → transports/http/observer.d.mts} +23 -11
  187. package/dist/transports/http/observer.mjs +223 -0
  188. package/dist/transports/http/reads.d.mts +2 -0
  189. package/dist/transports/http/reads.mjs +13 -0
  190. package/dist/transports/http/route.d.mts +24 -0
  191. package/dist/transports/http/route.mjs +124 -0
  192. package/dist/{ipc-control.d.mts → transports/ipc/control.d.mts} +11 -4
  193. package/dist/{ipc-control.mjs → transports/ipc/control.mjs} +16 -3
  194. package/dist/transports/ipc/inspector.d.mts +19 -0
  195. package/dist/transports/ipc/inspector.mjs +70 -0
  196. package/dist/transports/ipc/socket.d.mts +12 -0
  197. package/dist/transports/ipc/socket.mjs +104 -0
  198. package/dist/transports/net/client.d.mts +5 -0
  199. package/dist/transports/net/client.mjs +25 -0
  200. package/dist/transports/net/control.d.mts +13 -0
  201. package/dist/transports/net/control.mjs +56 -0
  202. package/dist/transports/net/proxy.d.mts +13 -0
  203. package/dist/transports/net/proxy.mjs +122 -0
  204. package/dist/transports/net/rules.d.mts +21 -0
  205. package/dist/transports/net/rules.mjs +75 -0
  206. package/dist/transports/net/tunnels.d.mts +35 -0
  207. package/dist/transports/net/tunnels.mjs +99 -0
  208. package/dist/transports/net/types.d.mts +64 -0
  209. package/dist/transports/net/types.mjs +3 -0
  210. package/dist/transports/session.d.mts +47 -0
  211. package/dist/{refresh-adapters.mjs → transports/session.mjs} +23 -22
  212. package/dist/web.d.mts +2 -21
  213. package/dist/web.mjs +2 -46
  214. package/dist/workflows/action/classify.d.mts +3 -0
  215. package/dist/workflows/action/classify.mjs +60 -0
  216. package/dist/workflows/action/config.d.mts +21 -0
  217. package/dist/workflows/action/config.mjs +35 -0
  218. package/dist/workflows/action/run.d.mts +5 -0
  219. package/dist/workflows/action/run.mjs +194 -0
  220. package/dist/workflows/action/screen.d.mts +18 -0
  221. package/dist/workflows/action/screen.mjs +67 -0
  222. package/dist/workflows/action/types.d.mts +46 -0
  223. package/dist/workflows/action/types.mjs +1 -0
  224. package/dist/workflows/check/browser.d.mts +25 -0
  225. package/dist/workflows/check/browser.mjs +120 -0
  226. package/dist/workflows/check/http/config.d.mts +20 -0
  227. package/dist/workflows/check/http/config.mjs +47 -0
  228. package/dist/workflows/check/http/fault.d.mts +25 -0
  229. package/dist/workflows/check/http/fault.mjs +113 -0
  230. package/dist/workflows/check/http/health.d.mts +8 -0
  231. package/dist/workflows/check/http/health.mjs +45 -0
  232. package/dist/workflows/check/http/run.d.mts +22 -0
  233. package/dist/workflows/check/http/run.mjs +95 -0
  234. package/dist/workflows/check/ipc/config.d.mts +18 -0
  235. package/dist/workflows/check/ipc/config.mjs +35 -0
  236. package/dist/workflows/check/ipc/run.d.mts +30 -0
  237. package/dist/workflows/check/ipc/run.mjs +223 -0
  238. package/dist/workflows/check/ipc/verdict.d.mts +23 -0
  239. package/dist/workflows/check/ipc/verdict.mjs +49 -0
  240. package/dist/workflows/check/screen.d.mts +16 -0
  241. package/dist/workflows/check/screen.mjs +39 -0
  242. package/dist/workflows/discover/experiment.d.mts +59 -0
  243. package/dist/{discovery-control.mjs → workflows/discover/experiment.mjs} +30 -1
  244. package/dist/workflows/discover/http.d.mts +41 -0
  245. package/dist/workflows/discover/http.mjs +104 -0
  246. package/dist/workflows/discover/ipc.d.mts +41 -0
  247. package/dist/workflows/discover/ipc.mjs +119 -0
  248. package/dist/workflows/discover/load.d.mts +22 -0
  249. package/dist/workflows/discover/load.mjs +174 -0
  250. package/dist/workflows/discover/run.d.mts +9 -0
  251. package/dist/workflows/discover/run.mjs +250 -0
  252. package/dist/workflows/discover/screenshots.d.mts +10 -0
  253. package/dist/workflows/discover/screenshots.mjs +20 -0
  254. package/dist/workflows/discover/types.d.mts +140 -0
  255. package/dist/workflows/discover/types.mjs +1 -0
  256. package/dist/workflows/observe/action-effects.d.mts +24 -0
  257. package/dist/workflows/observe/action-effects.mjs +33 -0
  258. package/dist/workflows/observe/adapters.d.mts +13 -0
  259. package/dist/workflows/observe/adapters.mjs +107 -0
  260. package/dist/workflows/observe/capture.d.mts +22 -0
  261. package/dist/workflows/observe/capture.mjs +253 -0
  262. package/dist/workflows/observe/comparisons.d.mts +55 -0
  263. package/dist/workflows/observe/comparisons.mjs +160 -0
  264. package/dist/workflows/observe/config.d.mts +40 -0
  265. package/dist/workflows/observe/config.mjs +185 -0
  266. package/dist/workflows/observe/file-faults.d.mts +33 -0
  267. package/dist/workflows/observe/file-faults.mjs +178 -0
  268. package/dist/{file-evidence.d.mts → workflows/observe/files.d.mts} +5 -4
  269. package/dist/{file-evidence.mjs → workflows/observe/files.mjs} +8 -5
  270. package/dist/workflows/observe/initial-report.d.mts +6 -0
  271. package/dist/workflows/observe/initial-report.mjs +35 -0
  272. package/dist/{observation-kit.d.mts → workflows/observe/kit.d.mts} +1 -9
  273. package/dist/{observation-kit.mjs → workflows/observe/kit.mjs} +30 -39
  274. package/dist/{observe-network.d.mts → workflows/observe/network.d.mts} +3 -3
  275. package/dist/workflows/observe/page-input.d.mts +6 -0
  276. package/dist/workflows/observe/page-input.mjs +33 -0
  277. package/dist/workflows/observe/reads.d.mts +34 -0
  278. package/dist/workflows/observe/reads.mjs +68 -0
  279. package/dist/workflows/observe/recorder.d.mts +39 -0
  280. package/dist/workflows/observe/recorder.mjs +225 -0
  281. package/dist/workflows/observe/render.d.mts +2 -0
  282. package/dist/workflows/observe/render.mjs +101 -0
  283. package/dist/{observation-report.d.mts → workflows/observe/report.d.mts} +44 -99
  284. package/dist/workflows/observe/report.mjs +31 -0
  285. package/dist/workflows/observe/rows.d.mts +35 -0
  286. package/dist/workflows/observe/rows.mjs +231 -0
  287. package/dist/workflows/observe/sample.d.mts +5 -0
  288. package/dist/workflows/observe/sample.mjs +37 -0
  289. package/dist/workflows/observe/sampling.d.mts +21 -0
  290. package/dist/workflows/observe/sampling.mjs +59 -0
  291. package/dist/workflows/observe/session.d.mts +36 -0
  292. package/dist/workflows/observe/session.mjs +174 -0
  293. package/dist/workflows/observe/step-runner.d.mts +14 -0
  294. package/dist/workflows/observe/step-runner.mjs +134 -0
  295. package/dist/workflows/observe/steps.d.mts +63 -0
  296. package/dist/workflows/observe/steps.mjs +127 -0
  297. package/dist/workflows/observe/summaries.d.mts +10 -0
  298. package/dist/workflows/observe/summaries.mjs +87 -0
  299. package/dist/workflows/observe/ui-read.d.mts +5 -0
  300. package/dist/workflows/observe/ui-read.mjs +26 -0
  301. package/dist/workflows/reads.d.mts +16 -0
  302. package/dist/workflows/reads.mjs +46 -0
  303. package/dist/workflows/refresh/classify.d.mts +21 -0
  304. package/dist/workflows/refresh/classify.mjs +47 -0
  305. package/dist/workflows/refresh/config.d.mts +39 -0
  306. package/dist/workflows/refresh/config.mjs +78 -0
  307. package/dist/workflows/refresh/probe.d.mts +38 -0
  308. package/dist/workflows/refresh/probe.mjs +158 -0
  309. package/dist/workflows/refresh/run.d.mts +5 -0
  310. package/dist/workflows/refresh/run.mjs +223 -0
  311. package/dist/workflows/refresh/session.d.mts +26 -0
  312. package/dist/workflows/refresh/session.mjs +82 -0
  313. package/dist/{refresh.d.mts → workflows/refresh/types.d.mts} +7 -49
  314. package/dist/workflows/refresh/types.mjs +1 -0
  315. package/dist/workflows/web.d.mts +14 -0
  316. package/dist/workflows/web.mjs +23 -0
  317. package/docs/android.md +3 -3
  318. package/docs/api.md +1 -1
  319. package/docs/ci.md +1 -1
  320. package/docs/compare.md +36 -7
  321. package/docs/demo.svg +1 -1
  322. package/docs/desktop.md +22 -64
  323. package/docs/discovery.md +101 -0
  324. package/docs/ipc.md +16 -75
  325. package/docs/mcp.md +31 -10
  326. package/docs/observe.md +57 -17
  327. package/docs/refresh.md +3 -3
  328. package/docs/repair.md +5 -5
  329. package/docs/runner.md +8 -3
  330. package/docs/start.md +7 -15
  331. package/docs/suspects.md +1 -1
  332. package/docs/verify.md +60 -0
  333. package/docs/watch.md +3 -3
  334. package/package.json +16 -34
  335. package/dist/cdp-bridge.mjs +0 -237
  336. package/dist/cli/attach.d.mts +0 -1
  337. package/dist/cli/attach.mjs +0 -85
  338. package/dist/cli/desktop.d.mts +0 -1
  339. package/dist/cli/desktop.mjs +0 -124
  340. package/dist/cli/ipc.d.mts +0 -1
  341. package/dist/cli/ipc.mjs +0 -120
  342. package/dist/cli/web.d.mts +0 -1
  343. package/dist/cli/web.mjs +0 -107
  344. package/dist/compare.d.mts +0 -92
  345. package/dist/compare.mjs +0 -376
  346. package/dist/desktop-report.d.mts +0 -5
  347. package/dist/discovery-control.d.mts +0 -16
  348. package/dist/discovery-report.d.mts +0 -40
  349. package/dist/discovery-report.mjs +0 -31
  350. package/dist/guided-start.d.mts +0 -42
  351. package/dist/guided-start.mjs +0 -262
  352. package/dist/http-discover.d.mts +0 -111
  353. package/dist/http-discover.mjs +0 -323
  354. package/dist/http-observer.mjs +0 -186
  355. package/dist/ipc-action.d.mts +0 -74
  356. package/dist/ipc-action.mjs +0 -314
  357. package/dist/ipc-check.d.mts +0 -45
  358. package/dist/ipc-check.mjs +0 -242
  359. package/dist/ipc-discover.d.mts +0 -119
  360. package/dist/ipc-discover.mjs +0 -371
  361. package/dist/ipc-observation.mjs +0 -302
  362. package/dist/mcp-server.mjs +0 -131
  363. package/dist/mcp-tools.d.mts +0 -5
  364. package/dist/mcp-tools.mjs +0 -468
  365. package/dist/observation-report.mjs +0 -343
  366. package/dist/observe-steps.d.mts +0 -58
  367. package/dist/observe-steps.mjs +0 -191
  368. package/dist/observe.d.mts +0 -104
  369. package/dist/observe.mjs +0 -892
  370. package/dist/refresh-adapters.d.mts +0 -40
  371. package/dist/refresh.mjs +0 -399
  372. package/dist/repair.mjs +0 -443
  373. package/dist/suspects.d.mts +0 -45
  374. package/dist/suspects.mjs +0 -395
  375. package/dist/visibility.mjs +0 -144
  376. package/dist/watch.mjs +0 -315
  377. /package/dist/{report-templates → reports/templates}/action.html +0 -0
  378. /package/dist/{report-templates → reports/templates}/ipc.html +0 -0
  379. /package/dist/{report-templates → reports/templates}/observation.html +0 -0
  380. /package/dist/{report-templates → reports/templates}/refresh.html +0 -0
  381. /package/dist/{android.d.mts → targets/android.d.mts} +0 -0
  382. /package/dist/{android.mjs → targets/android.mjs} +0 -0
  383. /package/dist/{mcp-server.d.mts → tools/mcp/server.d.mts} +0 -0
  384. /package/dist/{pick-marker.d.mts → tools/pick-marker.d.mts} +0 -0
  385. /package/dist/{repair-process.d.mts → tools/repair/process.d.mts} +0 -0
  386. /package/dist/{repair-provider.d.mts → tools/repair/provider.d.mts} +0 -0
  387. /package/dist/{observe-network.mjs → workflows/observe/network.mjs} +0 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,280 @@ 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
+ ## 1.0.0 (2026-10-27)
8
+
9
+ The first release with an explicit 1.x compatibility commitment. It removes the old command spellings and brings in everything since 0.6.0: the 0.7.0 and 0.8.0 previews below. The README defines the supported interfaces and experimental exceptions, and explains that failed checks can save unredacted screen-text quotes of up to 200 characters.
10
+
11
+ Breaking:
12
+
13
+ - The old spellings `desktop`, `web`, `ipc`, `--demo` and `--config` are gone. Each now stops with a usage error (exit 3) that names the commands that replaced it: `windows`, `reads` and `check` for `desktop`; `login`, `reads`, `check`, `discover` and `windows` for `web`; `check`, `discover` and `action` for `ipc`; `demo`; and `check --config`. Errors no longer exit with 2: usage errors exit with 3 and setup failures with 4.
14
+ - `demo` and the JSON runner's `check` always write `report.json` into a new `--out` folder; the single report file of the old spellings is gone.
15
+ - `watch` and `verify` rerun only `check`, `discover`, `action`, `observe` and `refresh`; `run_recovery_probe` in the MCP server no longer takes the old spellings.
16
+
17
+ Since 0.6.0:
18
+
19
+ - `observe` file steps (`--files`) that damage a file the way an interrupted download does, and `expect` steps that report `EXPECTATION_NOT_MET` (0.7.0).
20
+ - A `BASELINE_FAILED` result says why, and a fault that wasn't recovered from quotes what the screen showed instead (0.8.0-preview.15). In 1.0.0 the JSON runner quotes the screen too.
21
+ - `check --restore-window`, or `"restoreWindow": true`, un-minimizes the window for an IPC check and minimizes it again afterwards. The IPC check used to ignore it, so an app that hides a minimized window's page, as Electron does by default, stopped the check.
22
+ - The code is restructured into small functions and modules with no change in behaviour, held to size limits that `npm run lint` enforces, with a public API report and report-shape checks in CI (0.8.0-preview.1 to .14).
23
+ - The tests are type-checked (0.8.0-preview.16).
24
+
25
+ Reports written by older versions still read, compare and watch the same. Public package imports and the IPC hook's path are unchanged; restart the development app after upgrading so its hook matches the CLI.
26
+
27
+ ## 0.8.0-preview.16 (2026-10-27)
28
+
29
+ The tests are type-checked. No change to the package.
30
+
31
+ - `npm run typecheck` covers `test`, against the built declarations, so a test that calls a function with the wrong options or reads a field a report doesn't have fails before it runs.
32
+ - `fake()` in `test/helpers/fake.mjs` builds a page, browser, IPC hook or report from only the members a test needs, typed as the real thing; a misspelled member is a type error.
33
+ - `listen()` in `test/helpers/ports.mjs` starts a test server on a free loopback port and returns the port.
34
+ - Deliberately invalid input is marked with `// @ts-expect-error` and the reason.
35
+
36
+ ## 0.8.0-preview.15 (2026-10-27)
37
+
38
+ Check results say more about why they aren't a pass.
39
+
40
+ - `BASELINE_FAILED` has a `reason`, for example `the ready selector matched 2 elements`, `the ready element doesn't contain "Saved"` or `no successful response from the endpoint within 5000 ms`. The HTTP and IPC checks and the JSON runner give one; the CLI prints it under the result as `Why:`.
41
+ - A fault that was applied and not recovered from gets `screenText`: the lines the screen showed that the healthy screen didn't, such as `You have no orders yet`, up to 200 characters. It's in the CLI output, `report.json`, `report.html`, `fix-brief.md` and the `check_read_recovery` result. The JSON runner doesn't quote the screen.
42
+ - `check_read_recovery` tells agents that `readySelector` must match exactly one element, and to use a list's container or a single item.
43
+
44
+ ## 0.8.0-preview.14 (2026-10-27)
45
+
46
+ The MCP server and tools, the remaining commands and two report writers, restructured. No change to the CLI, the MCP tools or the reports.
47
+
48
+ - The MCP server is a small class with a table of methods, and `tools/mcp/tools.mts` (592 lines) is split by area: the browser tools, the network tools and their proxy, the change tools (suspects, compare, verify) and running a command.
49
+ - `android`, `net` and the browser runner are split into small steps.
50
+ - The discovery report and the evidence of a check report are built in small functions.
51
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 12 to 1, the command dispatcher, whose old spellings go in 1.0.
52
+
53
+ ## 0.8.0-preview.13 (2026-10-27)
54
+
55
+ The suspect scanner, `compare` and `watch`, restructured. No change to the CLI, the suspects found or the reports.
56
+
57
+ - `tools/suspects.mts` (574 lines, with a 298-line `scanSource`) is a `tools/suspects/` folder: a `SourceTree` with the questions the rules ask about a node, the failure paths, the four rules as a table, scanning one file, and listing files and changed lines.
58
+ - `tools/compare.mts` is a `tools/compare/` folder: reading reports, the verdict as small functions, the Markdown and the comparison.
59
+ - `tools/watch.mts` (406 lines) is a `tools/watch/` folder: the file watcher, running a check, the summary and a small `Watch` class that queues one job at a time.
60
+ - The `compare` command parses one option at a time and prints in small steps; `watch` prints each event with its own function.
61
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 26 to 12.
62
+
63
+ ## 0.8.0-preview.12 (2026-10-27)
64
+
65
+ Guided start, `doctor` and `verify`, restructured. No change to the CLI, the saved setups or the reports.
66
+
67
+ - `tools/guided-start.mts` (399 lines, with a 165-line `runStart`) is a `tools/start/` folder: the arguments, launching Chromium, configuring a screen, and a small `StartRun` class that loads the saved setup, opens the target, sets up or reuses the check and runs it. The terminal choices that `init` uses too moved to `tools/ask.mts`.
68
+ - `verify` checks a plan entry by entry, and reading the baseline and scanning the changed lines are their own steps.
69
+ - `doctor` reports a hook error and the hook's channels in separate functions.
70
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 36 to 26.
71
+
72
+ ## 0.8.0-preview.11 (2026-10-27)
73
+
74
+ The repair preview, restructured. No change to the CLI, the run folders or what is sent to the model.
75
+
76
+ - `tools/repair/run.mts` (667 lines) keeps `prepareRepair`, `generateRepair` and `verifyRepair` as short sequences of steps. The config rules, the source paths and proposal edits, the isolated checkout with its commands, and launching and attaching to the target each have their own module.
77
+ - The provider builds its request and reads the proposal in separate functions, and stopping a command's process tree is its own function.
78
+ - The `repair` command is split into reproduce, generate and verify steps.
79
+ - The repair tests give the app's first healthy load 10 seconds instead of 1, keeping the 1-second recovery window, so a cold Windows runner no longer fails them.
80
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 51 to 36.
81
+
82
+ ## 0.8.0-preview.10 (2026-10-27)
83
+
84
+ The IPC hook and the code that runs in the page, restructured. No change to the CLI, the library, the hook's API or the reports.
85
+
86
+ - The IPC hook (575 lines, with a 445-line `installIpcProbe`) is a `src/hook/` layer of small CommonJS modules: the public types, the install and plan checks, the read counters and labels, tracking one real call, the push counter, the plan state, and a small `ProbeHook` class behind the same frozen object. `ipc-probe.cts` only re-exports, like the other entry points, and the layer test keeps the hook free of imports from the rest of the package, since it runs inside the app's main process.
87
+ - `readRegion` moved to `core/region-read.mts` and reads the region in small inner steps. It stays one function because Playwright sends only its source to the page; the observer kit and the marker picker follow the same rule. Those three are the only functions allowed past the length limit, each with the reason next to it.
88
+ - `core/screen.mts` keeps summarizing, comparing and classifying regions, each split into short functions.
89
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 70 to 51.
90
+
91
+ ## 0.8.0-preview.9 (2026-10-27)
92
+
93
+ The IPC inspector, the CDP bridge and the window controls, restructured. No change to the CLI, the library or the reports.
94
+
95
+ - The Node inspector's WebSocket is a small `InspectorSocket` class in `transports/ipc/socket.mts`, next to the loopback check and the target discovery. `callIpcInspector` keeps its synchronous and asynchronous paths in two short functions.
96
+ - `targets/cdp-bridge.mts` (293 lines) is a `targets/cdp-bridge/` folder: the WebSocket server with its framing as plain functions, a `TargetFilter` that decides what each client sees, and the bridge.
97
+ - `windowVisibility` reads the window through one function per mechanism, and the window polls and state changes are shared helpers.
98
+ - `waitForSettledCalls` can refuse a plan that is still armed, so the refresh adapter uses it instead of its own copy of the wait.
99
+ - `core/server.mts` listens on loopback and closes a server for both the network proxy and the bridge.
100
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 81 to 70; `transports/` and `targets/` have none left.
101
+
102
+ ## 0.8.0-preview.8 (2026-10-27)
103
+
104
+ The HTTP and network fault layer, restructured. No change to the CLI, the library or the reports.
105
+
106
+ - `transports/net.mts` (453 lines, with a 233-line `startNetworkFaultProxy`) is a `transports/net/` folder: the public types (free of Node types, so consumers type-check without `@types/node`), the rules and which one applies, the open tunnels, the control API, its client, and the proxy. The proxy keeps its state in a small class behind the same plain object, so its methods can still be passed around unbound.
107
+ - `createFaultFetch` and `withFault` share the count, status, method and kind rules from `core/faults.mts`; each still checks them in its own order. `withFault`'s route handler is a small class, and the result is checked by one plain function.
108
+ - The HTTP observer is a class with one method per event.
109
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 90 to 81.
110
+
111
+ ## 0.8.0-preview.7 (2026-10-26)
112
+
113
+ The action check, restructured. No change to the CLI, the library or the reports.
114
+
115
+ - `workflows/action.mts` (470 lines, with a 197-line `checkAction`) is a `workflows/action/` folder: the config as short rules, the report types, the findings as plain functions, reading and watching the screen (the only code that runs in the page), and a small `ActionCheck` class that attaches, prepares and performs each run, reloads and releases.
116
+ - `runSnapshot` in `transports/ipc/control.mts` reads the hook's state of one run and fails if another run or window took over. The IPC check and the action check share it.
117
+ - `targets/visibility.mts` exports the prepared-window and window-report types that discovery, refresh and the action check each declared.
118
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 97 to 90.
119
+
120
+ ## 0.8.0-preview.6 (2026-10-26)
121
+
122
+ The recovery checks, restructured. No change to the CLI, the library or the reports.
123
+
124
+ - `workflows/check/http.mts` (356 lines, with a 153-line `checkDesktop`) is a `workflows/check/http/` folder: the config as short rules, the screen health helpers, and a `FaultTrial` class that takes one fault through arming, reload, Retry and recovery. `checkDesktop` is a short loop over those trials.
125
+ - `workflows/check/ipc.mts` (with a 182-line `checkIpc`) is a `workflows/check/ipc/` folder: the config, the phase verdict as a plain function with its own unit test, and a small `IpcCheck` class that attaches, runs the phases, reloads and disconnects. An unreachable branch of the timed-out verdict is gone.
126
+ - `probeRecovery` is split into small steps. `ensure` takes an optional error class, so the library's input checks still throw `TypeError`, and `ensureRanges` checks its keys against the config's type.
127
+ - The `check` command writes the IPC report through `reports/check.mts`, like the desktop report.
128
+ - `sleep` from `node:timers/promises` replaces eight copies of the same helper and five inline timer promises. The HTTP observer exports its type instead of three modules each deriving it.
129
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 111 to 97.
130
+
131
+ ## 0.8.0-preview.5 (2026-10-26)
132
+
133
+ The refresh experiment, restructured. No change to the CLI, the library or the reports.
134
+
135
+ - `workflows/refresh.mts` (605 lines, with a 327-line `runRefresh` of complexity 50) is now a `workflows/refresh/` folder: the config, the types, the outcome classification as plain functions, a `RefreshProbe` that reloads, watches and triggers the page, and a small `RefreshExperiment` class with one method per phase.
136
+ - The `refresh` command's setup moved out of the CLI into `workflows/refresh/session.mts`; the CLI keeps signals, the report files and the console output.
137
+ - `ensureRanges` takes an optional message, for configs that word range errors their own way.
138
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 119 to 111.
139
+
140
+ ## 0.8.0-preview.4 (2026-10-26)
141
+
142
+ Discovery, restructured. No change to the CLI, the library or the reports.
143
+
144
+ - `runDiscovery` (302 lines) is a small `Discovery` class: calibrate, healthy control, experiment, reset and release are separate methods. One reload, watched until it is ready or out of time, is its own `load.mts`, and the engine's types are in `types.mts`.
145
+ - The HTTP and IPC discovery configs are short rule lists on `core/validate.mts`, which gains `overDefaults` and `ensureRanges`; the observation config uses `ensureRanges` too. Each config gets its own default arrays.
146
+ - The `discover` and `reads` commands are split into small steps: input, run, write, print.
147
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 134 to 119.
148
+
149
+ ## 0.8.0-preview.3 (2026-10-26)
150
+
151
+ The rest of the observation workflow, restructured. No change to the CLI, the library or the reports.
152
+
153
+ - `workflows/observe/report.mts` (833 lines) keeps the report's types; sampling metrics, content comparisons, summaries, action effects and the HTML report each have their own module. Sampling metrics share one accumulator instead of three copies of the same bookkeeping, and the HTML report is built from one small function per section.
154
+ - Step validation is a parser per step kind in `steps.mts`; running steps moved to `step-runner.mts`.
155
+ - File steps run through a `FileFaults` class, and the content comparison tracker is a `ContentComparisons` class.
156
+ - `selectorSpec` and its type moved to `core/selector.mts`, so the core layer no longer imports them from a workflow.
157
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 153 to 134.
158
+
159
+ ## 0.8.0-preview.2 (2026-10-26)
160
+
161
+ The observation engine, restructured. No change to the CLI, the library or the reports.
162
+
163
+ - `workflows/observe/run.mts` (1,294 lines) is now one module per job: configuration, read counters, the IPC and HTTP adapters, row tracking, the capture loop, the recorder that turns samples into the report, and what the page is given. The capture loop is a small class instead of a 451-line function.
164
+ - The `observe` command's setup (files, network faults, steps, attaching to the target and the evidence they add) moved out of the CLI into `workflows/observe/session.mts`; the CLI keeps terminal input, the report files and the console output.
165
+ - `core/validate.mts` holds the checks configuration validators share, starting with observation configs, and keeps every error message the same.
166
+ - The size-limit violations listed in `eslint-suppressions.json` drop from 169 to 153.
167
+
168
+ ## 0.8.0-preview.1 (2026-10-26)
169
+
170
+ The first step towards 1.0: checks that let the code be restructured without changing what it does. No change to the CLI, the library or the reports.
171
+
172
+ - ESLint limits the size of `src` code: functions to 50 lines, files to 300, complexity to 12, nesting to 4 levels and parameters to 4. The 169 places that exceed them are listed in `eslint-suppressions.json`, so new code meets them and the list only shrinks.
173
+ - `api/recovery-probe.api.md` records the public API from the built type declarations, and `npm run api:check` fails in CI when it changes without the file being updated.
174
+ - Integration and Electron tests check each workflow's report against the fields listed in `test/fixtures/report-shapes`, so a restructured workflow cannot drop or rename a report field unnoticed.
175
+
176
+ ## 0.7.0-preview.2 (2026-10-26)
177
+
178
+ - A file step whose file could not be checked or put back no longer writes the error message to the report. The message names local paths, which belong in the private `files.json`, so the report now gets only the error code, such as `EBUSY`, and `files.json` gets the message next to the kept copy.
179
+
180
+ ## 0.7.0-preview.1 (2026-10-26)
181
+
182
+ - File steps. With `observe --files DIR`, a step can remove, truncate or corrupt a file under that directory, the way an interrupted download or an antivirus quarantine does. When the capture ends, each file is reported as repaired by the app, still damaged, or changed; a file the app did not restore adds `LOCAL_FILE_NOT_REPAIRED` and is put back from a private copy. The step's own damage is left out of the `LOCAL_FILES_REMOVED` comparison.
183
+ - `expect` steps. They wait like `waitFor`, but when nothing matching shows in time the script goes on and the report gets `EXPECTATION_NOT_MET`. It counts as a failed check in the evidence block, so `compare` reports it as a suspected defect rather than a lead. `action` setup rejects `expect`, since its step results are not reported.
184
+
185
+ ## 0.6.0 (2026-10-23)
186
+
187
+ Promotes previews 1–13 to the stable npm `latest` channel without additional runtime changes.
188
+
189
+ - Add `init` for guided first checks and `doctor` for setup diagnostics, including IPC hook channels.
190
+ - Unify CLI commands around `check`, `discover`, `action`, `windows`, `reads`, `login` and `demo`, with consistent option parsing and JSON output where supported.
191
+ - Add `verify` and the MCP `verify_change` tool to compare checks before and after a change and scan changed lines for suspects.
192
+ - Add row-state markers and `UNEXPECTED_ROW_STATE` observations, plus discovery experiments that fail later calls separately and optional screenshots.
193
+ - Share discovery, read sessions, HTTP fault handling, target identification and report-folder creation across workflows. Reports expose one evidence shape for comparison, watching and verification, while older reports remain readable.
194
+ - Organize source into tested architectural layers, consolidate documentation and validate documentation links.
195
+
196
+ Upgrading from 0.5.0: public package exports and the IPC hook path are unchanged; restart the development app so its hook matches the CLI. Old CLI spellings remain supported until 1.0 and retain exit code 2 for errors. New commands use 0 for passed, 1 for failed, 2 for inconclusive or needs review, 3 for usage/config errors and 4 when a run could not start. Update scripts that interpret these codes. For `demo` and JSON-runner `check`, `--out` names a new report folder; old spellings retain file output. Unsupported imports into internal `dist/` files may break after the source reorganization. Experimental workflows remain experimental.
197
+
198
+ ## 0.6.0-preview.13 (2026-10-23)
199
+
200
+ - One fault layer. The fault kinds are listed once (`FAULT_KINDS` in `core/faults`), and one function answers a request with a fault for `withFault`, the HTTP observer and the HTTP check. The HTTP check fails its read through the same observer as discovery and observation, instead of its own copy of the route handler.
201
+ - A successful read after a fault counts when its response finishes, not when its headers arrive, as in discovery.
202
+ - The IPC check, the HTTP check and the JSON runner stay separate on purpose: they promise different things. The IPC check needs exact call counts and takes its deadline from the measured read; the HTTP check clicks Retry and waits for a ready marker; the runner opens a fresh browser for each fault.
203
+
204
+ ## 0.6.0-preview.12 (2026-10-23)
205
+
206
+ - Every `report.json` has an `evidence` block in one shape: workflow, transport, target, problems, outcomes, what the run checked and why parts don't count. `compare`, `watch` and `verify` read it; older reports are read from their other fields as before.
207
+ - `compare` matches runs by workflow and transport instead of the report's label, so a check from `check --cdp` compares with one from the old `web --attach`, and an older refresh report compares with a new one.
208
+ - Discovery, action and refresh findings are told apart by experiment: before, `rejection-1`, `rejection-2` and `rejection-1-call2` all counted as `rejection`, so a problem that moved between them looked unchanged.
209
+
210
+ ## 0.6.0-preview.11 (2026-10-23)
211
+
212
+ - One set of commands. `check`, `discover` and `action` read what to do from the config: a `channel` means IPC, an `endpoint` means HTTP, and `check` attaches when given `--cdp` or a config with `cdp` or `page`, otherwise it opens Chromium. `windows`, `reads`, `login` and `demo` replace `--list`, `--discover` without a config, `--login` and `--demo`.
213
+ - The old spellings (`--demo`, `--config`, `desktop`, `web`, `web --attach`, `ipc`) run the new commands with the same options, print one line saying what replaced them, and keep exit code 2 for errors. They work until 1.0.
214
+ - `recovery-probe --help` lists every command with what it does, and `recovery-probe <command> --help` its options. Every command parses its options the same way.
215
+ - Exit codes: 0 passed, 1 a check failed, 2 needs review or inconclusive, 3 wrong usage or config, 4 couldn't run. Before, usage and setup errors exited with 2.
216
+ - `check`, `discover`, `action`, `reads` and `windows` take `--json`. `check` takes `--screenshots` in a browser it opens too.
217
+ - When nothing answers on a debugging port, the error says how to start the app instead of showing Playwright's connection log.
218
+ - `demo --out` and `check --out` with a JSON-runner config name a new folder for report.json, like every other command; the old spellings still write one file.
219
+
220
+ ## 0.6.0-preview.10 (2026-10-23)
221
+
222
+ - One function finds the IPC hook's window and proves the debugging port and the hook reach the same one. It replaces five copies in the IPC check, discovery, the action check, observe and refresh, which had different error messages and, in refresh, removed any window challenge instead of only its own.
223
+ - `ipc`, `observe`, `refresh`, `web` and `web --attach` create their report folder the same way: `--out` must be a new folder, its parent folders are created, and without `--out` it's a new `.recovery-probe/<command>-…` folder.
224
+ - `watch`, `verify` and the MCP server still run each check as its own CLI process, on purpose: a hung or crashing check can be stopped without stopping them.
225
+
226
+ ## 0.6.0-preview.9 (2026-10-23)
227
+
228
+ - IPC and HTTP discovery run on one engine, built on the same read sessions as refresh. The IPC and HTTP modules only set up their transport.
229
+ - Both now behave the same where they had drifted apart:
230
+ - Over HTTP, a healthy load that doesn't settle stops the run with `BASELINE_NOT_HEALTHY`, as over IPC. `BASELINE_UNSTABLE` means healthy loads ended on different screens, over both, without the extra text IPC added.
231
+ - Over IPC, an `UNSTABLE` finding has low confidence, as over HTTP.
232
+ - HTTP findings and runs have the fields IPC ones had: `observationMs`, advice per classification, `verification`, `recoveryDetectedAt`, `timingNote`, `assessment`, and `uncaughtErrors` in the timeline.
233
+ - The read sessions take `skip`, and the HTTP one keeps the requests its observers saw.
234
+
235
+ ## 0.6.0-preview.8 (2026-10-23)
236
+
237
+ - The source is split into layers (core, transports, targets, reports, workflows, tools, cli), and a test keeps each layer from importing the ones above it. `desktop.mts`, which held the HTTP check, CDP attachment and endpoint listing, is now three modules, and `index.mts` no longer holds a check engine. The public imports (`recovery-probe`, `/fetch`, `/net`, `/desktop`, `/web`, `/ipc-inspector`, `/ipc`) and the hook's path are unchanged. Imports of other files inside `dist/` were never supported and now break.
238
+ - Paths to files that ship with the package come from one place, `core/package.mts`.
239
+ - Tests live in `test/unit`, `test/integration`, `test/electron` and `test/package`, and Electron tests share one launcher that stops the whole process tree.
240
+
241
+ ## 0.6.0-preview.7 (2026-10-23)
242
+
243
+ - New `recovery-probe init [URL]`. It finds what to test and runs a first check: the guided web check for a URL, the guided desktop check for an app on the debugging port, or IPC discovery when the app has the hook, after asking which channel loads the screen. Running it again repeats the check; `--fresh` sets it up again.
244
+ - New `recovery-probe doctor`. It checks Node.js, Playwright, Chromium, the app on the debugging port and the IPC hook, and prints the fix for anything missing, including the hook code with the path to load it from. `--json` prints the report.
245
+ - The IPC hook's `identify()` returns `channels`, the channels it may fail. `doctor` names the ones the app never registered, which usually means a typo or a hook loaded after the handlers.
246
+ - Agents can run `doctor` through the MCP tool `run_recovery_probe`, and the server tells them to when a check can't attach.
247
+
248
+ ## 0.6.0-preview.6 (2026-10-23)
249
+
250
+ - A shorter README, and MCP setup for any agent instead of one client.
251
+ - Discovery over IPC and HTTP is described once, in `docs/discovery.md`. The docs describe current behaviour; version history stays in this changelog.
252
+ - The package ships every doc, including `docs/verify.md`, which was missing.
253
+ - A docs test checks that relative links and headings resolve.
254
+
255
+ ## 0.6.0-preview.5 (2026-10-23)
256
+
257
+ - IPC and HTTP discovery count how often each healthy load reads the target. When every load reads it the same number of times, they also fail the 2nd, 3rd and 4th call of a load on its own, as findings such as `rejection-1-call2` with a `call` field. `readiness.callsGap` says when later calls were not failed on their own. IPC discovery needs the hook from this version for these experiments; restart the app after upgrading.
258
+ - `ipc --discover --screenshots` and `web --attach --discover --screenshots` save the screen after the first baseline and each faulted run, and show the screenshots in `report.html`.
259
+ - The IPC hook's `begin` takes `skip`, the calls on the channel that pass before the first fault.
260
+
261
+ ## 0.6.0-preview.4 (2026-10-23)
262
+
263
+ - A click on a `<label>` records its action once. The browser also clicks the label's control, which counted as a second click on the same action.
264
+
265
+ ## 0.6.0-preview.3 (2026-10-23)
266
+
267
+ - New `recovery-probe verify` and MCP tool `verify_change`. A plan lists the checks that prove a change; `--baseline` runs them before it, and `verify` runs them again, compares the runs and scans the lines changed since the base for suspects. The change is VERIFIED only when every check improved or stayed clean with complete runs on both sides and no changed line is a suspect.
268
+ - `scanForSuspects` takes `changedLinesOnly`, which leaves out suspects on lines the change did not touch.
269
+ - File names from `suspects --changed-since` keep the spelling of the working directory, such as a Windows short name, instead of appearing as `../../..` paths.
270
+
271
+ ## 0.6.0-preview.2 (2026-10-23)
272
+
273
+ - `UNEXPECTED_ROW_STATE` ends a stretch when the row leaves the region, so a row that comes back gets a new finding instead of extending the old one.
274
+ - Marker labels cannot be `none` or `other`, the states rows get without a marker or allowlisted text.
275
+
276
+ ## 0.6.0-preview.1 (2026-10-23)
277
+
278
+ - Observation rows can take their state from a marker element, such as an icon, with `rows.markers`. `state` and `states` are optional when markers are set.
279
+ - `rows.unexpected` lists states a region must not show. A row shown in one of them is reported as `UNEXPECTED_ROW_STATE`, once per stretch of samples, with the samples that showed it and the action before it.
280
+
7
281
  ## 0.5.0 (2026-10-21)
8
282
 
9
283
  Promotes previews 1–22 to the stable npm `latest` channel. The preview entries below retain the detailed history.
package/CONTRIBUTING.md CHANGED
@@ -16,18 +16,45 @@ npm ci
16
16
  npm run format:check
17
17
  npm run lint
18
18
  npm run typecheck
19
- npm test
20
- npm run test:package
19
+ npm run api:check # public API unchanged, or api/recovery-probe.api.md updated
20
+ npm test # unit tests, no browser
21
+ npm run test:package # installs the packed package like a user would
21
22
  npx playwright install chromium
22
- npm run test:browser
23
- npm run test:repair # safety, authenticated portal, before/after pipeline
24
- # After installing the optional Electron test runtime:
25
- npm run test:repair:electron
23
+ npm run test:integration # real Chromium
24
+ npm install --no-save --package-lock=false electron@44.5.1
25
+ npm run test:electron # real Electron
26
26
  ```
27
27
 
28
+ Tests live in `test/unit`, `test/integration`, `test/electron` and `test/package`, and each script runs every `*.test.mjs` in its folder. Shared helpers are in `test/helpers` (free ports, launching an Electron fixture, the repair fixture) and fixture apps in `test/fixtures`. Electron tests start Electron through `test/helpers/electron.mjs`, which also clears `ELECTRON_RUN_AS_NODE` (some editors set it) and stops the whole process tree.
29
+
30
+ Tests are type-checked against the built declarations. Build a stand-in for a page, a browser or the IPC hook with `fake()` from `test/helpers/fake.mjs`: it takes only the members the test needs and is typed as the real thing, so a misspelled member fails the check. Mark input that is invalid on purpose with `// @ts-expect-error` and the reason.
31
+
32
+ `test/fixtures/report-shapes` lists, for each workflow, the report fields every run produces. Integration and Electron tests fail when a report lacks one, so a change cannot drop or rename a field unnoticed. Rerunning a suite with `UPDATE_REPORT_SHAPES=1` keeps only the fields that run produced too; delete a file first to record new fields, and run twice so fields that depend on timing drop out.
33
+
28
34
  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
35
 
30
- Code and JSON are formatted with Prettier (`npm run format`) and linted with ESLint (`npm run lint`); CI fails on either. Functions passed to `page.evaluate` run in the browser: keep them self-contained, and list new in-page modules in `eslint.config.mjs` so they get browser globals. The package is written in TypeScript: modules are `.mts` (or `.cts` for CommonJS), and the command line lives in `src/cli`, with `bin/recovery-probe.mjs` only starting it. `npm run build` compiles them into `dist` with strict checks and generated declarations, and copies the report templates unchanged. `npm ci` builds once, and every script that runs code builds first, so tests never use a stale `dist`. `npm run typecheck` also checks the JavaScript in `bin`, `examples` and `scripts` with strict mode off; add JSDoc types where inference is not enough. TypeScript is pinned to 6.0 because typescript-eslint, which lints the TypeScript files, does not support 7 yet. Markdown, HTML fixtures, report templates and workflow files are left as written. Report markup lives in `src/report-templates`: `{{slot}}` takes text and escapes it, `{{{slot}}}` takes markup built with `escapeHtml`. `.gitattributes` keeps LF line endings on every platform so local checks match CI. The repository-wide reformat is listed in `.git-blame-ignore-revs`; run `git config blame.ignoreRevsFile .git-blame-ignore-revs` to skip it in local blame.
36
+ Code and JSON are formatted with Prettier (`npm run format`) and linted with ESLint (`npm run lint`); CI fails on either. Functions passed to `page.evaluate` run in the browser: keep them self-contained, and list new in-page modules in `eslint.config.mjs` so they get browser globals. The package is written in TypeScript: modules are `.mts` (or `.cts` for CommonJS), and the command line lives in `src/cli`, with `bin/recovery-probe.mjs` only starting it. `npm run build` compiles them into `dist` with strict checks and generated declarations, and copies the report templates unchanged. `npm ci` builds once, and every script that runs code builds first, so tests never use a stale `dist`. `npm run typecheck` also checks the JavaScript in `bin`, `examples`, `scripts` and `test` (not the fixture apps) 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/reports/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.
37
+
38
+ Code in `src` keeps functions to 50 lines and files to 300, not counting blank lines and comments, with a cyclomatic complexity of at most 12, at most 4 levels of nesting and at most 4 parameters. A function passed to `page.evaluate` may run longer, because Playwright sends only its source and its helpers must live inside it; mark it with an `eslint-disable` comment that says so, and keep each inner function within the other limits. `npm run lint` fails on any violation.
39
+
40
+ `api/recovery-probe.api.md` lists the public API as the built type declarations describe it. `npm run api:check` fails when it is out of date; run `npm run api:report` after an intended change, so the change is visible in review.
41
+
42
+ ## Layout
43
+
44
+ `src/` is split into layers, and each layer imports only itself and the layers below it:
45
+
46
+ | Folder | Holds |
47
+ | --- | --- |
48
+ | `hook` | The IPC hook, which runs inside the app's main process: CommonJS that imports nothing else from the package |
49
+ | `core` | Fault kinds, URL identity, reading and comparing the screen, package paths |
50
+ | `transports` | Failing reads: Playwright routes, the fetch wrapper, the HTTPS proxy, the IPC inspector and control |
51
+ | `targets` | Reaching the app: launching Chromium, attaching over CDP, window visibility, Android |
52
+ | `reports` | Report templates and the writers for check, discovery and action reports |
53
+ | `workflows` | The experiments: checks, discovery, refresh, observation, actions |
54
+ | `tools` | What's built on them: init, doctor, guided start, suspects, compare, watch, verify, MCP, repair |
55
+ | `cli` | Argument parsing and output |
56
+
57
+ The files directly in `src/` are the package's public entry points. They only re-export, so their import paths never change; `ipc-probe.cts`, which re-exports `hook`, is the file apps load by path. `test/unit/layers.test.mjs` fails when a module imports a layer above it at run time; type imports are free.
31
58
 
32
59
  ## Install an unpublished source preview
33
60
 
package/README.md CHANGED
@@ -1,141 +1,133 @@
1
1
  # Recovery Probe
2
2
 
3
- **Test whether web and desktop apps show the right data.**
3
+ See what your app shows when a data request fails.
4
4
 
5
- Apps can show the wrong data without any error: a list that disappears after one failed read, a cached screen that never picks up a change, or a row whose state lags behind data the app already received. Recovery Probe reproduces these cases on demand. It injects bounded faults into data reads and compares the screen with a healthy run, or it watches reads and the screen without any fault. Each run writes a local report that separates what it measured from what it suspects.
6
-
7
- Use it while you build, not only after. An AI coding agent can call it [over MCP](#use-it-from-an-ai-coding-agent) to see what the screen does when a read fails before it claims the code handles that. `recovery-probe suspects` reads the code a branch changed for error handling that turns a failed read into "no data", and names the read to fail to prove it. `recovery-probe compare` turns the same check, run before and after a change, into evidence for the pull request, and `recovery-probe watch` reruns the check and the scan on every save.
8
-
9
- Installing the package does not add recovery behavior to your application.
5
+ Most apps don't crash when a read fails. The list goes empty, the spinner never stops, or the screen keeps showing old data. There's no error and nothing in the logs, so it ships. Recovery Probe fails those reads on purpose, runs the same screen healthy for comparison, and tells you what changed.
10
6
 
11
7
  [![CI](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml/badge.svg)](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
12
8
  [![npm](https://img.shields.io/npm/v/recovery-probe.svg)](https://www.npmjs.com/package/recovery-probe)
13
9
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
14
10
 
15
- ## See it work
11
+ ![Recovery Probe catches a broken retry flow and passes the fixed one](docs/demo.svg)
16
12
 
17
- The package includes a deliberately broken app and a corrected one. Both pass the normal loading check; only the corrected one recovers from all three faults.
13
+ ## Try it
18
14
 
19
- ![Recovery Probe catches a broken retry flow and verifies the corrected flow](docs/demo.svg)
15
+ You need Node.js 22 or newer.
20
16
 
21
17
  ```bash
22
- mkdir recovery-probe-tools && cd recovery-probe-tools
23
- npm install --save-dev --save-exact recovery-probe@0.5.0 playwright@1.62.1
18
+ npm install --save-dev recovery-probe playwright
24
19
  npx playwright install chromium
25
- npx recovery-probe --demo
20
+ npx recovery-probe demo
26
21
  ```
27
22
 
28
- `--demo` exits successfully only when it observes that contrast: the happy path passes, the broken recovery is caught, and the corrected flow passes. Add `--json` to print the full report or `--out report.json` to save it.
23
+ The demo runs two versions of a small app. Both load fine. Only the fixed one survives a 503, a dropped connection and a broken JSON response.
29
24
 
30
- ## Test your own app
25
+ ## Check your own app
31
26
 
32
- | Goal | Start with | Guide |
33
- | --- | --- | --- |
34
- | Set up a first recovery check interactively | `recovery-probe start web URL` or `start desktop` | [Guided start](docs/start.md) |
35
- | Discover and test the reads behind a screen in a browser or Electron window | `recovery-probe desktop --cdp URL` | [Attachment and HTTP discovery](docs/desktop.md) |
36
- | Compare an Electron screen under IPC faults | `recovery-probe ipc --discover --config FILE` | [IPC setup and discovery](docs/ipc.md) |
37
- | Check what users see when a save or send fails in Electron | `recovery-probe ipc --action --config FILE` | [IPC action check](docs/ipc.md#action-check) |
38
- | Fail an SDK's or main process's own HTTPS connections | `recovery-probe net --rules FILE`, or network steps in `observe --network URL` | [Network faults](docs/net.md) |
39
- | Let an AI coding agent check what the screen does when a read fails | `recovery-probe mcp` | [AI coding agents (MCP)](docs/mcp.md) |
40
- | Find error handling that turns a failed read into "no data", before running anything | `recovery-probe suspects --changed-since main` | [Suspect scanner](docs/suspects.md) |
41
- | Show in a pull request that a change fixed what a check found | `recovery-probe compare --before DIR --after DIR --markdown` | [Before and after](docs/compare.md) |
42
- | See after every save whether an edit fixed or broke what a check found | `recovery-probe watch src -- CHECK` | [Watch mode](docs/watch.md) |
43
- | See whether a failure made the app delete local content | `recovery-probe observe --config FILE --files DIR` | [Local files](docs/observe.md#local-files) |
44
- | Inspect an Android app's WebView (experimental) | `recovery-probe android --package NAME` | [Android WebViews](docs/android.md) |
45
- | Test a refresh after content has already loaded | `recovery-probe refresh --config FILE --json` | [Refresh experiments](docs/refresh.md) |
46
- | Watch cached content and row states after user actions, without faults | `recovery-probe observe --config FILE [--steps FILE]` | [Observation](docs/observe.md) |
47
- | Run a repeatable recovery check in CI | `npm run test:ci-example` (source checkout) | [CI example](docs/ci.md) |
48
- | Assert recovery inside your own tests | `withFault` or `createFaultFetch` | [API](docs/api.md) |
49
- | Propose and verify a source change | Opt-in repair workflow | [Repair setup and limits](docs/repair.md) |
50
-
51
- `desktop` also attaches to an existing Chromium-based web browser.
52
-
53
- **Where it works:**
54
-
55
- - **Web apps** in Chromium-based browsers: launch a test browser or attach to an authorized development one.
56
- - **Electron apps that read over HTTP** in the renderer: attach through a loopback debugging endpoint.
57
- - **Electron apps that read over IPC**: add a development-only hook to the main process.
58
- - **JavaScript code that takes a fetch function**: use `recovery-probe/fetch`, without Playwright.
59
- - **Native HTTPS clients that use `HTTPS_PROXY`**, such as an SDK in the main process: fail whole connections per host with `recovery-probe net`.
60
- - **Android WebViews** with WebView debugging enabled (experimental): `recovery-probe android` makes them inspectable like a desktop page. On a Meta Quest, `--keep-awake` lets checks run without anyone wearing the headset.
61
-
62
- Desktop support means Electron, not arbitrary native applications. IPC faults do not exercise native networking, HTTP status handling or token refresh. Network faults reach native networking, but only whole connections: they cannot return an HTTP status inside HTTPS. An unsupported data path is inconclusive, never a successful recovery check.
63
-
64
- ## Use it from an AI coding agent
65
-
66
- `recovery-probe mcp` serves the checks as MCP tools, so an agent can verify its own error handling instead of assuming it:
27
+ **Web app.** Start it, then run:
67
28
 
68
29
  ```bash
69
- claude mcp add recovery-probe -- npx recovery-probe mcp
30
+ npx recovery-probe init http://localhost:3000
70
31
  ```
71
32
 
72
- The agent can then:
73
- - list the reads behind a page;
74
- - fail one of them and see whether the screen recovers;
75
- - run a network fault proxy for an SDK or a main process;
76
- - find error handling in the changed code that can lose data;
77
- - compare the same check before and after its change;
78
- - run the other commands.
33
+ A browser opens. Sign in, go to the screen you care about, and click something that only shows up once its data has loaded. Recovery Probe finds the request behind it, fails it three ways, and tells you whether the data came back.
34
+
35
+ **Electron app.** Start it with `--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222`, then run `npx recovery-probe init`.
36
+
37
+ **Electron app that loads data over IPC.** Load the small development-only hook in the main process. `npx recovery-probe doctor` prints the code and the path to load it from. Restart the app with the inspector on, then run `npx recovery-probe init`: it lists the hook's channels, asks which one loads the screen, and fails it in a few ways.
38
+
39
+ Each run saves an HTML and JSON report. Run the same command again to repeat the check, or add `--fresh` to set it up again. If something's missing, `npx recovery-probe doctor` says what and how to fix it.
79
40
 
80
- A caught fault comes with a fix brief and a script to reproduce it. The server tells the agent to report outcomes as they are: a pass covers only what was checked, and an inconclusive run is never a pass. See [AI coding agents (MCP)](docs/mcp.md).
41
+ ## More
81
42
 
82
- ## Add a recovery check to a Playwright test
43
+ | To | Run | Docs |
44
+ | --- | --- | --- |
45
+ | Fail the read behind a screen without writing assertions | `discover` | [Discovery](docs/discovery.md) |
46
+ | Catch stale screens and rows stuck in an old state, without faults | `observe` | [Observe](docs/observe.md) |
47
+ | See what users get when Save or Send fails | `action` | [Action check](docs/ipc.md#action-check) |
48
+ | Fail an SDK's or a main process's own HTTPS connections | `net` | [Network faults](docs/net.md) |
49
+ | Find code that turns a failed read into "no data" | `suspects` | [Suspects](docs/suspects.md) |
50
+ | Prove a change fixed it | `compare`, `watch`, `verify` | [Compare](docs/compare.md), [Watch](docs/watch.md), [Verify](docs/verify.md) |
51
+
52
+ ## Use it from a coding agent
53
+
54
+ `recovery-probe mcp` is an MCP server. Any agent that supports MCP can use it to fail a read and look at the screen before it claims the code handles errors. Most agents take this config:
55
+
56
+ ```json
57
+ {
58
+ "mcpServers": {
59
+ "recovery-probe": { "command": "npx", "args": ["recovery-probe", "mcp"] }
60
+ }
61
+ }
62
+ ```
63
+
64
+ Other config formats and the list of tools are in [MCP](docs/mcp.md).
83
65
 
84
- Use `withFault` inside an existing Playwright test. The callback contains the real user action and the application-specific recovery assertion.
66
+ ## Use it in your tests
67
+
68
+ `withFault` fails matching requests inside a Playwright test:
85
69
 
86
70
  ```js
87
- import { test, expect } from '@playwright/test';
88
- import { withFault } from 'recovery-probe';
89
-
90
- test('profile recovers after a transient 503', async ({ page }) => {
91
- const stats = await withFault(page, {
92
- match: '**/api/profile',
93
- kind: 'http-error',
94
- status: 503,
95
- count: 1,
96
- }, async () => {
97
- await page.goto('http://127.0.0.1:3000/profile');
98
- await page.getByRole('button', { name: 'Retry' }).click();
99
- await expect(page.getByTestId('profile-name')).toHaveText('Test User');
100
- });
101
-
102
- expect(stats.applied).toBe(1);
103
- });
71
+ import { test, expect } from '@playwright/test'
72
+ import { withFault } from 'recovery-probe'
73
+
74
+ test('profile recovers after a 503', async ({ page }) => {
75
+ const stats = await withFault(
76
+ page,
77
+ { match: '**/api/profile', kind: 'http-error', status: 503 },
78
+ async () => {
79
+ await page.goto('http://127.0.0.1:3000/profile')
80
+ await page.getByRole('button', { name: 'Retry' }).click()
81
+ await expect(page.getByTestId('profile-name')).toHaveText('Test User')
82
+ },
83
+ )
84
+ expect(stats.applied).toBe(1)
85
+ })
104
86
  ```
105
87
 
106
- If no request matches, `withFault` throws `FAULT_NOT_TRIGGERED` instead of letting the test pass silently. Code that takes a fetch function can use `createFaultFetch` instead. See the [API reference](docs/api.md) and the [JSON-configured runner](docs/runner.md).
88
+ If nothing matches, `withFault` throws `FAULT_NOT_TRIGGERED` instead of passing. For code that takes a `fetch` function there's `createFaultFetch`. See [API](docs/api.md).
89
+
90
+ ## How it decides
91
+
92
+ - Every faulted run has a healthy run right before it, on the same screen, and the report compares the two.
93
+ - A result is a pass, a failure or inconclusive. A fault that never fired, an unstable baseline or a path it can't reach is inconclusive, never a pass.
94
+ - Some findings, like `SILENT_EMPTY`, are leads. They tell you where to look, not that the code is wrong.
95
+ - Exit codes: 0 passed, 1 a check failed, 2 needs review or inconclusive, 3 wrong usage or config, 4 couldn't run.
107
96
 
108
- ## Install
97
+ ## Where it works
109
98
 
110
- **0.5.0** is the stable release on npm's `latest` channel, and the commands above pin it for reproducible reports. Prereleases use the `next` channel and are opt-in.
99
+ - Web apps in Chromium, either launched by Recovery Probe or attached through a local debugging port.
100
+ - Electron apps, over HTTP in the renderer or over IPC with the hook.
101
+ - Native HTTPS clients that use `HTTPS_PROXY`, such as an SDK in the main process. Only whole connections can fail there.
102
+ - Android WebViews, experimental.
111
103
 
112
- Use Node.js 22 or newer. A separate tools folder keeps the tester out of your application's production dependencies. Browser and desktop commands need Playwright; attached targets use their existing browser runtime. If a version is not on npm yet, use the [source installation](CONTRIBUTING.md#install-an-unpublished-source-preview): a GitHub merge alone does not publish the package. See [CHANGELOG.md](CHANGELOG.md) for version history.
104
+ It doesn't simulate a whole device going offline, WebSocket drops, token expiry, sleep or slow networks.
113
105
 
114
- When upgrading from 0.4.0, resolve any stored IPC hook path again with `node -p "require.resolve('recovery-probe/ipc')"` and restart the development app. The hook now ships in `dist/`. The library and CLI are compiled from TypeScript; using the published package does not require a build. Source scanning with `suspects` additionally needs the optional TypeScript peer dependency. Experimental commands retain that status in 0.5.0.
106
+ ## Privacy
115
107
 
116
- ## Reports, agents and privacy
108
+ Reports stay on your machine and there's no telemetry. Request and response bodies aren't recorded, and discovery and observation keep screen text only as hashes. Reports can still contain endpoint paths, selectors, text you picked as a marker and, with `--screenshots`, what was on screen, so check them before you share them. Nothing calls an AI service except the opt-in [repair](docs/repair.md) workflow.
117
109
 
118
- Reports separate measured facts, such as fault counts, successful reads, timings and UI changes, from suspected defects. A `CONTENT_LOSS` finding needs review. An unconsumed fault, an unstable control or an unsupported path is inconclusive. Observation findings such as `DELAYED_UI_UPDATE` are leads to check against the application logic, not verdicts.
110
+ Failed recovery checks can also save `screenText`: up to 200 characters of newly visible screen text, included in terminal output, reports, fix briefs and MCP results. These quotes are not redacted and can contain personal or sensitive data even without screenshots. Review these outputs before sharing them or passing them to an agent.
119
111
 
120
- Coding agents can run saved scenarios, read the JSON evidence, propose a change and rerun the same experiment. Recovery Probe supplies repeatable experiments and evidence; it is not a general bug detector or a production self-healing system.
112
+ Only test apps and accounts you're allowed to, and keep debugging ports on localhost.
121
113
 
122
- Reports stay local, and Recovery Probe sends no telemetry. Scenarios, endpoints, channels, selected text, screenshots, login state and command logs may be private, so do not publish them blindly. Request and response bodies and headers are not collected, and observation never records read contents.
114
+ ## Compatibility in 1.x
123
115
 
124
- Tests and discovery do not call an AI service. Only the opt-in repair workflow, with `--allow-source-upload`, sends the selected source files and bounded observations to your configured OpenAI model; login state and command logs are not part of that upload. It sets `store: false`, which is not a promise of zero provider retention, so review your employer's policy and the provider's data terms first. A repair is a reviewable candidate, not a guaranteed fix.
116
+ The compatibility commitment covers documented, non-experimental package exports, CLI commands and options, exit codes, configuration fields, MCP tools and JSON report fields. Removing or renaming these interfaces, changing their types incompatibly, or changing their documented meaning requires a major version. Backward-compatible additions can ship in minor releases; fixes that restore documented behavior can ship in patch releases.
125
117
 
126
- ## Scope
118
+ Consumers should tolerate additional JSON fields. Exact terminal wording, HTML layout, timing measurements and heuristic findings are not fixed contracts. Internal files under `dist/` are not public imports; use the package's declared exports. Features explicitly labeled experimental, including Android WebView support and repair, may change in minor releases, with changes recorded in the changelog.
127
119
 
128
- Recovery Probe checks request-level recovery deterministically and observes whether the screen reflects the reads it received. It does not simulate whole-device offline states, WebSocket interruptions, token expiry, browser sleep, slow networks or duplicate submissions.
120
+ ## Upgrading to 1.0
129
121
 
130
- Structural discovery compares healthy and faulted screens without a hand-written content selector, but it needs a selected read and a stable healthy baseline. No workflow infers your product's intended recovery policy.
122
+ 1.0 removes the old command spellings `desktop`, `web`, `ipc`, `--demo` and `--config`. Each now stops with a usage error that names the commands that replaced it, such as `windows`, `reads`, `check`, `discover`, `action` and `demo`. Usage errors exit with 3 and setup failures with 4, where the old spellings exited with 2, so update CI scripts that read exit codes. `demo` and the JSON runner's `check` write `report.json` into the `--out` folder. Restart the development app after upgrading so its IPC hook matches the CLI. Public package imports and the hook's path are unchanged. See the [changelog](CHANGELOG.md).
131
123
 
132
- The recovery, discovery and refresh workflows reload the renderer to establish controls. That clears in-memory caches, so those modes cannot prove account isolation. Observation keeps that state, but it does not infer identities or data ownership.
124
+ ## Docs
133
125
 
134
- Attach only to authorized test sessions, keep debugging endpoints on loopback, and keep the target window visible and uncovered.
126
+ [Guided start](docs/start.md) · [Desktop and browsers](docs/desktop.md) · [IPC](docs/ipc.md) · [Discovery](docs/discovery.md) · [Observe](docs/observe.md) · [Refresh](docs/refresh.md) · [Network faults](docs/net.md) · [Android](docs/android.md) · [Suspects](docs/suspects.md) · [Compare](docs/compare.md) · [Watch](docs/watch.md) · [Verify](docs/verify.md) · [MCP](docs/mcp.md) · [API](docs/api.md) · [JSON runner](docs/runner.md) · [CI](docs/ci.md) · [Repair](docs/repair.md) · [Changelog](CHANGELOG.md)
135
127
 
136
- ## Development
128
+ ## Contributing
137
129
 
138
- See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks and test suites, and [SECURITY.md](SECURITY.md) for reporting security issues. CI runs package checks on Node.js 22 and 24, Chromium integration, and real Electron checks.
130
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues as described in [SECURITY.md](SECURITY.md).
139
131
 
140
132
  ## License
141
133