shapewall 0.0.0-stage → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (304) hide show
  1. package/CHANGELOG.md +139 -0
  2. package/Dockerfile.agent +45 -0
  3. package/LICENSE +202 -0
  4. package/NOTICE +12 -0
  5. package/README.md +651 -2
  6. package/THIRD_PARTY.md +165 -0
  7. package/bin/shapewall.js +29 -0
  8. package/dist/agent/package-lock.json +8384 -0
  9. package/dist/client/assets/BoardChat-D5SFd8HE.js +28 -0
  10. package/dist/client/assets/BuzzDialog-HWXBy52W.js +1 -0
  11. package/dist/client/assets/ChecksPanel-DTdImWoD.js +1 -0
  12. package/dist/client/assets/History-CEv6b-av.js +1 -0
  13. package/dist/client/assets/LocalSettings-C4vriEVQ.js +1 -0
  14. package/dist/client/assets/Management-DCfhcEUY.js +1 -0
  15. package/dist/client/assets/QuickConnect-DQGgUsl1.js +1 -0
  16. package/dist/client/assets/ShareDialog-C_plIto0.js +2 -0
  17. package/dist/client/assets/app-update-dialog-2hPz_N9G.js +1 -0
  18. package/dist/client/assets/circle-x-BZMPi8Zf.js +1 -0
  19. package/dist/client/assets/index-ByQRKVit.css +2 -0
  20. package/dist/client/assets/index-DweQ8Qtu.js +29 -0
  21. package/dist/client/assets/refresh-cw-CRow0Nbq.js +1 -0
  22. package/dist/client/assets/runtime-Bft6x_6E.js +4 -0
  23. package/dist/client/assets/square-A8EnIYLR.js +1 -0
  24. package/dist/client/assets/tts-dist-DYlBQmwG.js +18 -0
  25. package/dist/client/assets/tts-en-g2p-BPUtBFGG.js +1 -0
  26. package/dist/client/assets/tts-ort-wasm-simd-threaded-qh98TCA_.wasm +0 -0
  27. package/dist/client/assets/tts-ort.wasm.bundle.min-rEkcs_ow.js +12 -0
  28. package/dist/client/assets/tts-rolldown-runtime-D8NudN84.js +1 -0
  29. package/dist/client/assets/tts-spacy-en-tokenizer-6SNMl--A.json +1 -0
  30. package/dist/client/assets/tts-tts.worker-Bzm6aWbv.js +1 -0
  31. package/dist/client/assets/tts-us_gold-DcjeNMH1.json +92589 -0
  32. package/dist/client/assets/tts-us_silver-C964mEB5.json +93363 -0
  33. package/dist/client/assets/ui-CLbws0rx.js +41 -0
  34. package/dist/client/build-info.json +1 -0
  35. package/dist/client/favicon.svg +7 -0
  36. package/dist/client/icons/apple-touch-icon.png +0 -0
  37. package/dist/client/icons/icon-192.png +0 -0
  38. package/dist/client/icons/icon-512.png +0 -0
  39. package/dist/client/icons/maskable-512.png +0 -0
  40. package/dist/client/index.html +25 -0
  41. package/dist/client/manifest.webmanifest +15 -0
  42. package/dist/client/sw.js +53 -0
  43. package/dist/client/theme-boot.js +27 -0
  44. package/dist/console/assets/LocalAccountsApp-BQCcmj3x.js +1 -0
  45. package/dist/console/assets/LocalConsole-Bb2FUDs7.js +1 -0
  46. package/dist/console/assets/app-update-dialog-DIeYepLZ.js +1 -0
  47. package/dist/console/assets/console-C7uJLLOn.js +51 -0
  48. package/dist/console/assets/console-R8IBY3Am.css +2 -0
  49. package/dist/console/build-info.json +1 -0
  50. package/dist/console/console.html +21 -0
  51. package/dist/console/favicon.svg +7 -0
  52. package/dist/console/icons/apple-touch-icon.png +0 -0
  53. package/dist/console/icons/icon-192.png +0 -0
  54. package/dist/console/icons/icon-512.png +0 -0
  55. package/dist/console/icons/maskable-512.png +0 -0
  56. package/dist/console/manifest.webmanifest +15 -0
  57. package/dist/console/theme-boot.js +27 -0
  58. package/docs/agent-hardening.md +342 -0
  59. package/docs/agent-recipes.md +187 -0
  60. package/docs/agent-workflow.md +320 -0
  61. package/docs/agents.md +894 -0
  62. package/docs/architecture.md +242 -0
  63. package/docs/buzz.md +140 -0
  64. package/docs/capture-warnings.md +57 -0
  65. package/docs/config.md +489 -0
  66. package/docs/deployment.md +289 -0
  67. package/docs/design-system.md +162 -0
  68. package/docs/github.md +107 -0
  69. package/docs/hosted.md +764 -0
  70. package/docs/images/board-overview.png +0 -0
  71. package/docs/images/journeys.png +0 -0
  72. package/docs/images/live-comment.png +0 -0
  73. package/docs/images/phone-comment.png +0 -0
  74. package/docs/images/phone-overview.png +0 -0
  75. package/docs/images/variant.png +0 -0
  76. package/docs/interaction-audits.md +40 -0
  77. package/docs/journeys.md +137 -0
  78. package/docs/local-accounts.md +80 -0
  79. package/docs/notifications.md +237 -0
  80. package/docs/page-checks.md +69 -0
  81. package/docs/performance.md +174 -0
  82. package/docs/starter-agent.md +325 -0
  83. package/docs/updates.md +87 -0
  84. package/examples/audits/interaction.audit.json +17 -0
  85. package/package.json +132 -4
  86. package/src/accounts/avatar.js +121 -0
  87. package/src/accounts/local.js +464 -0
  88. package/src/agent/acp/command.js +204 -0
  89. package/src/agent/acp/detect.js +75 -0
  90. package/src/agent/acp/sandbox.js +160 -0
  91. package/src/agent/agent-health.js +75 -0
  92. package/src/agent/backends/acp.js +1297 -0
  93. package/src/agent/backends/index.js +61 -0
  94. package/src/agent/backends/openai.js +308 -0
  95. package/src/agent/composer.js +221 -0
  96. package/src/agent/config.js +338 -0
  97. package/src/agent/context.js +191 -0
  98. package/src/agent/control.js +122 -0
  99. package/src/agent/errors.js +17 -0
  100. package/src/agent/feedback-loop.js +137 -0
  101. package/src/agent/manage.js +94 -0
  102. package/src/agent/next-steps.js +51 -0
  103. package/src/agent/owner-mcp.js +38 -0
  104. package/src/agent/plain-text.js +52 -0
  105. package/src/agent/ratings-core.js +213 -0
  106. package/src/agent/ratings.js +100 -0
  107. package/src/agent/reply-text.js +67 -0
  108. package/src/agent/routes.js +1065 -0
  109. package/src/agent/run.js +326 -0
  110. package/src/agent/settings-routes.js +704 -0
  111. package/src/agent/showable.js +23 -0
  112. package/src/agent/starter/approvals.js +181 -0
  113. package/src/agent/starter/build-image.js +90 -0
  114. package/src/agent/starter/cli.js +163 -0
  115. package/src/agent/starter/disk.js +53 -0
  116. package/src/agent/starter/doctor.js +180 -0
  117. package/src/agent/starter/egress-proxy.js +351 -0
  118. package/src/agent/starter/gate.js +90 -0
  119. package/src/agent/starter/loop.js +114 -0
  120. package/src/agent/starter/model-relay.js +289 -0
  121. package/src/agent/starter/pause.js +14 -0
  122. package/src/agent/starter/probe.js +272 -0
  123. package/src/agent/starter/prompt.js +41 -0
  124. package/src/agent/starter/push-guard.js +146 -0
  125. package/src/agent/starter/rpc.js +164 -0
  126. package/src/agent/starter/runtime.js +287 -0
  127. package/src/agent/starter/sandbox-main.js +121 -0
  128. package/src/agent/starter/settings.js +290 -0
  129. package/src/agent/starter/source.js +69 -0
  130. package/src/agent/starter/supervisor.js +755 -0
  131. package/src/agent/starter/sweep.js +46 -0
  132. package/src/agent/starter/tools.js +524 -0
  133. package/src/agent/starter/watch.js +84 -0
  134. package/src/agent/starter/worktree.js +409 -0
  135. package/src/agent/text-diff.js +210 -0
  136. package/src/agent/thread-history.js +223 -0
  137. package/src/agent/threads.js +399 -0
  138. package/src/agent/tools.js +200 -0
  139. package/src/agent/turn-changes.js +424 -0
  140. package/src/agent/undo-state.js +26 -0
  141. package/src/agent/user-settings.js +308 -0
  142. package/src/auth/record.js +375 -0
  143. package/src/broken-links.js +164 -0
  144. package/src/buzz/client.js +75 -0
  145. package/src/buzz/config.js +151 -0
  146. package/src/buzz/environment.js +13 -0
  147. package/src/buzz/gateway.js +192 -0
  148. package/src/buzz/routes.js +61 -0
  149. package/src/buzz/signer-child.js +205 -0
  150. package/src/buzz/store.js +89 -0
  151. package/src/buzz/transport.js +60 -0
  152. package/src/buzz/verify.js +140 -0
  153. package/src/capture/actions.js +159 -0
  154. package/src/capture/capture.js +776 -0
  155. package/src/capture/dom-names.js +189 -0
  156. package/src/capture/element-map.js +509 -0
  157. package/src/capture/live.js +827 -0
  158. package/src/capture/media-scheme.js +317 -0
  159. package/src/capture/network-summary.js +86 -0
  160. package/src/capture/pacing.js +34 -0
  161. package/src/capture/requests.js +167 -0
  162. package/src/capture/sanitize.js +752 -0
  163. package/src/checks/accessibility.js +134 -0
  164. package/src/checks/budgets.js +58 -0
  165. package/src/checks/cli.js +55 -0
  166. package/src/checks/comparison.js +113 -0
  167. package/src/checks/environments.js +32 -0
  168. package/src/checks/flow-config.js +82 -0
  169. package/src/checks/flow-origin.js +53 -0
  170. package/src/checks/flows.js +398 -0
  171. package/src/checks/lighthouse-auth.js +145 -0
  172. package/src/checks/lighthouse-findings.js +130 -0
  173. package/src/checks/lighthouse.js +395 -0
  174. package/src/checks/robots.js +85 -0
  175. package/src/checks/routes.js +52 -0
  176. package/src/checks/run-control.js +259 -0
  177. package/src/checks/runner.js +724 -0
  178. package/src/checks/schema.js +133 -0
  179. package/src/checks/seo-analysis.js +443 -0
  180. package/src/checks/seo-probe.js +190 -0
  181. package/src/checks/seo-snapshot.js +99 -0
  182. package/src/checks/store.js +214 -0
  183. package/src/checks/transport.js +47 -0
  184. package/src/cli/args.js +319 -0
  185. package/src/cli/capture.js +79 -0
  186. package/src/cli/commands.js +92 -0
  187. package/src/cli/comments.js +84 -0
  188. package/src/cli/help.js +243 -0
  189. package/src/cli/init.js +214 -0
  190. package/src/cli/misc.js +64 -0
  191. package/src/cli/notify.js +87 -0
  192. package/src/cli/open.js +22 -0
  193. package/src/cli/serve.js +274 -0
  194. package/src/cli/variant.js +82 -0
  195. package/src/cli/watch.js +70 -0
  196. package/src/cli.js +130 -0
  197. package/src/comment-fields.js +76 -0
  198. package/src/comments-cli.js +208 -0
  199. package/src/config-reload.js +100 -0
  200. package/src/config.js +1061 -0
  201. package/src/devices-cli.js +21 -0
  202. package/src/diff.js +95 -0
  203. package/src/discover.js +284 -0
  204. package/src/doctor.js +295 -0
  205. package/src/event-log.js +268 -0
  206. package/src/events-cli.js +102 -0
  207. package/src/events.js +113 -0
  208. package/src/export.js +119 -0
  209. package/src/feedback.js +246 -0
  210. package/src/github.js +551 -0
  211. package/src/hosted/LICENSE.md +105 -0
  212. package/src/hosted/access-cli.js +78 -0
  213. package/src/hosted/admin.js +682 -0
  214. package/src/hosted/agent-approvals.js +163 -0
  215. package/src/hosted/agent-policy.js +189 -0
  216. package/src/hosted/app.js +510 -0
  217. package/src/hosted/auth-routes.js +540 -0
  218. package/src/hosted/auth.js +536 -0
  219. package/src/hosted/backup.js +483 -0
  220. package/src/hosted/board-context.js +35 -0
  221. package/src/hosted/board-routes.js +486 -0
  222. package/src/hosted/board-view.js +94 -0
  223. package/src/hosted/clean-worker.js +24 -0
  224. package/src/hosted/cleaner.js +89 -0
  225. package/src/hosted/comments.js +355 -0
  226. package/src/hosted/console-routes.js +401 -0
  227. package/src/hosted/cookies.js +18 -0
  228. package/src/hosted/crypto.js +80 -0
  229. package/src/hosted/db.js +496 -0
  230. package/src/hosted/device-routes.js +175 -0
  231. package/src/hosted/device.js +233 -0
  232. package/src/hosted/events.js +63 -0
  233. package/src/hosted/guards.js +172 -0
  234. package/src/hosted/guest-view.js +65 -0
  235. package/src/hosted/http.js +39 -0
  236. package/src/hosted/import.js +300 -0
  237. package/src/hosted/mail.js +73 -0
  238. package/src/hosted/mcp-http.js +71 -0
  239. package/src/hosted/membership.js +114 -0
  240. package/src/hosted/operator.js +478 -0
  241. package/src/hosted/ops-cli.js +345 -0
  242. package/src/hosted/pages.js +146 -0
  243. package/src/hosted/permissions.js +113 -0
  244. package/src/hosted/presence.js +372 -0
  245. package/src/hosted/projects.js +124 -0
  246. package/src/hosted/public.js +109 -0
  247. package/src/hosted/push.js +622 -0
  248. package/src/hosted/quotas.js +115 -0
  249. package/src/hosted/ratelimit.js +96 -0
  250. package/src/hosted/rebind.js +316 -0
  251. package/src/hosted/retention.js +128 -0
  252. package/src/hosted/server.js +260 -0
  253. package/src/hosted/setup-link.js +64 -0
  254. package/src/hosted/setup.js +323 -0
  255. package/src/hosted/shares.js +444 -0
  256. package/src/hosted/tailscale.js +204 -0
  257. package/src/hosted/tenancy.js +301 -0
  258. package/src/hosted/token-api.js +455 -0
  259. package/src/hosted/token-events.js +60 -0
  260. package/src/hosted/tokens.js +57 -0
  261. package/src/hosted/turnstile.js +49 -0
  262. package/src/hosted/usercontent.js +154 -0
  263. package/src/hosted/zip.js +155 -0
  264. package/src/invocation.js +58 -0
  265. package/src/journey-paths.js +282 -0
  266. package/src/journeys.js +189 -0
  267. package/src/links.js +106 -0
  268. package/src/local-projects.js +182 -0
  269. package/src/lock.js +193 -0
  270. package/src/mcp.js +417 -0
  271. package/src/mentions.js +151 -0
  272. package/src/net.js +15 -0
  273. package/src/notify/config.js +275 -0
  274. package/src/notify/index.js +301 -0
  275. package/src/notify/lease.js +73 -0
  276. package/src/notify/messages.js +212 -0
  277. package/src/notify/run.js +174 -0
  278. package/src/pixeldiff.js +49 -0
  279. package/src/png.js +143 -0
  280. package/src/reactions.js +111 -0
  281. package/src/remote/cli.js +133 -0
  282. package/src/remote/credentials.js +62 -0
  283. package/src/remote/ids.js +12 -0
  284. package/src/remote/login.js +155 -0
  285. package/src/remote/remote-mcp.js +237 -0
  286. package/src/remote/remote-watch.js +291 -0
  287. package/src/remote/remote.js +313 -0
  288. package/src/remote/share-state.js +78 -0
  289. package/src/remote/share.js +369 -0
  290. package/src/remote/terminal.js +13 -0
  291. package/src/serve-state.js +64 -0
  292. package/src/server/app.js +824 -0
  293. package/src/server/devices.js +186 -0
  294. package/src/server/local-console.js +28 -0
  295. package/src/server/local-user.js +59 -0
  296. package/src/server/pairing-routes.js +159 -0
  297. package/src/server/share-routes.js +89 -0
  298. package/src/server/tailscale.js +97 -0
  299. package/src/sitemap.js +431 -0
  300. package/src/store.js +983 -0
  301. package/src/tokens.js +11 -0
  302. package/src/update/routes.js +245 -0
  303. package/src/watch.js +403 -0
  304. package/src/which.js +58 -0
@@ -0,0 +1,134 @@
1
+ import axe from 'axe-core'
2
+
3
+ export const AXE_VERSION = axe.version
4
+ export const ACCESSIBILITY_MAX_ELEMENTS = 10000
5
+ const KNOWN_RULES = new Set(
6
+ axe
7
+ .getRules()
8
+ .map((rule) => rule.ruleId)
9
+ .filter((id) => /^[a-z][a-z0-9-]{0,55}$/.test(id)),
10
+ )
11
+ const LIMIT = 60
12
+ const RULE_TITLES = {
13
+ 'button-name': 'Button accessible name is missing',
14
+ 'link-name': 'Link accessible name is missing',
15
+ label: 'Form control accessible label is missing',
16
+ 'image-alt': 'Image alternative text needs review',
17
+ 'color-contrast': 'Text contrast needs review',
18
+ 'html-has-lang': 'Document language is missing',
19
+ 'document-title': 'Document title is missing',
20
+ 'target-size': 'Control target size or spacing needs review',
21
+ 'aria-allowed-attr': 'ARIA attribute is not supported on this element',
22
+ 'aria-valid-attr-value': 'ARIA attribute value is invalid',
23
+ 'aria-roles': 'ARIA role is invalid',
24
+ 'aria-required-children': 'Required ARIA child structure is missing',
25
+ 'aria-required-parent': 'Required ARIA parent structure is missing',
26
+ }
27
+ const count = (value) => (Number.isInteger(value) && value >= 0 ? Math.min(value, 100000) : 0)
28
+
29
+ export function accessibilityFindings(result) {
30
+ if (
31
+ !Array.isArray(result?.violations) ||
32
+ result.violations.length > 120 ||
33
+ ['incompleteRules', 'passedRules', 'scannedElements'].some(
34
+ (key) => !Number.isInteger(result[key]) || result[key] < 0 || result[key] > 100000,
35
+ ) ||
36
+ result.violations.some((rule) => !KNOWN_RULES.has(rule.id) || !Number.isInteger(rule.count) || rule.count < 0 || rule.count > 100000)
37
+ )
38
+ throw new Error('The accessibility engine returned an unsupported result shape.')
39
+ const violations = (Array.isArray(result?.violations) ? result.violations : []).filter((rule) => KNOWN_RULES.has(rule.id))
40
+ const findings = violations.slice(0, LIMIT).map((rule) => ({
41
+ id: `axe-${rule.id}`,
42
+ category: 'accessibility',
43
+ severity: ['critical', 'serious'].includes(rule.impact) ? 'warning' : 'advisory',
44
+ title: RULE_TITLES[rule.id] || `Accessibility rule ${rule.id} needs review`,
45
+ observation: `Rule ${rule.id} reported ${count(rule.count)} affected elements.`,
46
+ impact: 'Some users may be unable to perceive or operate this page. Automated checks do not establish accessibility compliance.',
47
+ nextAction:
48
+ 'Review this engine rule on the original page, fix the affected controls and verify with keyboard and assistive technology.',
49
+ }))
50
+ if (count(result?.incompleteRules))
51
+ findings.push({
52
+ id: 'axe-needs-review',
53
+ category: 'accessibility',
54
+ severity: 'advisory',
55
+ title: 'Accessibility checks need manual review',
56
+ observation: `${count(result.incompleteRules)} rules could not reach a definite result.`,
57
+ impact: 'An unknown automated result is not a passing accessibility check.',
58
+ nextAction: 'Review the original page with keyboard and assistive technology.',
59
+ })
60
+ if (violations.length > LIMIT)
61
+ findings.push({
62
+ id: 'axe-findings-limited',
63
+ category: 'accessibility',
64
+ severity: 'advisory',
65
+ title: 'Accessibility finding limit reached',
66
+ observation: 'Additional automated rule findings exceeded the report limit.',
67
+ impact: 'This bounded report does not contain every finding.',
68
+ nextAction: 'Run the accessibility engine on the original page to inspect the remaining rules.',
69
+ })
70
+ return {
71
+ findings,
72
+ metrics: {
73
+ violationRules: violations.length,
74
+ violationNodes: violations.reduce((n, rule) => n + count(rule.count), 0),
75
+ incompleteRules: count(result?.incompleteRules),
76
+ passedRules: count(result?.passedRules),
77
+ scannedElements: count(result?.scannedElements),
78
+ },
79
+ partial: violations.length > LIMIT || count(result?.incompleteRules) > 0,
80
+ }
81
+ }
82
+
83
+ export async function inspectAccessibility(page) {
84
+ const session = await page.context().newCDPSession(page)
85
+ try {
86
+ const { frameTree } = await session.send('Page.getFrameTree')
87
+ const { executionContextId } = await session.send('Page.createIsolatedWorld', {
88
+ frameId: frameTree.frame.id,
89
+ worldName: 'shapewall-accessibility',
90
+ grantUniveralAccess: false,
91
+ })
92
+ const evaluate = async (expression) => {
93
+ const result = await session.send('Runtime.evaluate', {
94
+ expression,
95
+ contextId: executionContextId,
96
+ awaitPromise: true,
97
+ returnByValue: true,
98
+ timeout: 20000,
99
+ })
100
+ if (result.exceptionDetails || result.result?.subtype === 'error')
101
+ throw new Error('Accessibility engine could not evaluate this state.')
102
+ return result.result.value
103
+ }
104
+ const size = await evaluate(`(() => {
105
+ let count = 0;
106
+ const roots = [document];
107
+ while (roots.length) {
108
+ const walker = document.createTreeWalker(roots.pop(), NodeFilter.SHOW_ELEMENT);
109
+ while (walker.nextNode()) {
110
+ if (++count > 10000) return count;
111
+ if (walker.currentNode.shadowRoot) roots.push(walker.currentNode.shadowRoot);
112
+ }
113
+ }
114
+ return count;
115
+ })()`)
116
+ if (size > ACCESSIBILITY_MAX_ELEMENTS) return { unsupported: true }
117
+ // The pinned engine is local package code, never a downloaded page script.
118
+ await evaluate(axe.source)
119
+ const result = await evaluate(`(async () => {
120
+ const results = await axe.run(document, {
121
+ runOnly: { type: 'tag', values: ['wcag2a','wcag2aa','wcag21a','wcag21aa','wcag22aa'] },
122
+ iframes: false, selectors: false, ancestry: false, xpath: false, elementRef: false,
123
+ resultTypes: ['violations'], preload: false,
124
+ });
125
+ return {
126
+ violations: results.violations.slice(0,120).map(rule => ({id:rule.id,impact:rule.impact,count:rule.nodes.length})),
127
+ incompleteRules: results.incomplete.length, passedRules: results.passes.length,
128
+ };
129
+ })()`)
130
+ return { ...result, scannedElements: size }
131
+ } finally {
132
+ await session.detach().catch(() => {})
133
+ }
134
+ }
@@ -0,0 +1,58 @@
1
+ // Shared with the browser. Budgets are explicit upper bounds, never implied
2
+ // product-wide pass scores. Reports retain the exact policy used at run time.
3
+ export const BUDGET_METRICS = Object.freeze({
4
+ ttfbMs: 'Time to first byte (ms)',
5
+ loadMs: 'Load (ms)',
6
+ domContentLoadedMs: 'DOM content loaded (ms)',
7
+ documentTransferBytes: 'Document transfer (bytes)',
8
+ resourceTransferBytes: 'Resource transfer (bytes)',
9
+ resourceDecodedBytes: 'Decoded resources (bytes)',
10
+ requestCount: 'Requests',
11
+ largestContentfulPaintMs: 'Largest contentful paint (ms)',
12
+ firstContentfulPaintMs: 'First contentful paint (ms)',
13
+ totalBlockingTimeMs: 'Total blocking time (ms)',
14
+ cumulativeLayoutShift: 'Cumulative layout shift',
15
+ transferredResourceBytes: 'Transferred resources (bytes)',
16
+ observedRequests: 'Observed requests',
17
+ speedIndexMs: 'Speed index (ms)',
18
+ })
19
+ export function normalizeBudgets(value, problems) {
20
+ if (value === undefined) return undefined
21
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
22
+ problems.push('checks.budgets: an object of metric names and maximum values')
23
+ return undefined
24
+ }
25
+ const thresholds = {}
26
+ for (const [key, limit] of Object.entries(value)) {
27
+ if (!Object.hasOwn(BUDGET_METRICS, key)) problems.push(`checks.budgets.${key}: unknown budget metric`)
28
+ else if (typeof limit !== 'number' || !Number.isFinite(limit) || limit < 0 || limit > 1e15)
29
+ problems.push(`checks.budgets.${key}: a finite maximum from 0 to 1000000000000000`)
30
+ else thresholds[key] = limit
31
+ }
32
+ return thresholds
33
+ }
34
+ export function budgetResults(report) {
35
+ return Object.entries(report.budgets?.thresholds || {}).map(([metric, limit]) => {
36
+ const raw = report.metrics[metric]
37
+ const value = ['complete', 'partial'].includes(report.state) && typeof raw === 'number' && Number.isFinite(raw) ? raw : null
38
+ return { metric, limit, value, state: value === null ? 'unknown' : value > limit ? 'over' : 'within' }
39
+ })
40
+ }
41
+ export function applyBudgets(report, thresholds) {
42
+ if (!thresholds || !Object.keys(thresholds).length) return report
43
+ const next = { ...report, budgets: { version: 1, source: 'config', thresholds: { ...thresholds } } }
44
+ const findings = budgetResults(next)
45
+ .filter((result) => result.state === 'over')
46
+ .map(({ metric, value, limit }) => ({
47
+ id: `budget-${metric.toLowerCase()}`,
48
+ category: 'performance',
49
+ severity: 'warning',
50
+ title: `${BUDGET_METRICS[metric]} exceeds the configured budget`,
51
+ observation: `Observed ${Math.round(value * 100) / 100}; configured maximum ${limit}.`,
52
+ impact: 'This measurement exceeds the chosen lab budget. It does not establish a regression or field performance.',
53
+ nextAction: 'Inspect the original page and repeat the same measurement profile before deciding on a change.',
54
+ }))
55
+ // Keep findings bounded without dropping a failed-run diagnostic.
56
+ next.findings = [...report.findings.filter((f) => !f.id.startsWith('budget-')).slice(0, 80 - findings.length), ...findings]
57
+ return next
58
+ }
@@ -0,0 +1,55 @@
1
+ import { checksView } from './store.js'
2
+ import { runChecks } from './runner.js'
3
+
4
+ export async function checksCommand(config, positional, flags, out, err = () => {}) {
5
+ const action = positional[0] || 'run'
6
+ if (action === 'flow' || action === 'accessibility') {
7
+ const { flowCommand, accessibilityCommand } = await import('./flows.js')
8
+ return (action === 'flow' ? flowCommand : accessibilityCommand)(config, positional.slice(1), flags, out, err)
9
+ }
10
+ if (action === 'list') {
11
+ const result = checksView(config, flags.board || config.boards[0].id, flags.env || null)
12
+ out(flags.json ? JSON.stringify(result, null, 2) : `${result.checked} of ${result.total} page views checked. Use --json for reports.`)
13
+ return 0
14
+ }
15
+ if (action !== 'run') throw new Error('checks: use run, list, flow or accessibility.')
16
+ // SIGTERM (the board's Stop, its time limit) or Ctrl-C stops the run after
17
+ // the view in progress is abandoned; a second signal exits at once.
18
+ const controller = new AbortController()
19
+ const onSignal = () => {
20
+ if (controller.signal.aborted) process.exit(130)
21
+ controller.abort()
22
+ }
23
+ for (const s of STOP_SIGNALS) process.on(s, onSignal)
24
+ let reports
25
+ try {
26
+ reports = await runChecks({
27
+ config,
28
+ boardId: flags.board,
29
+ envId: flags.env,
30
+ only: flags.only,
31
+ // --seo or --no-seo, else the config's checks.seo default.
32
+ seo: flags.seo ? true : flags['no-seo'] ? false : (config.checks?.seo ?? false),
33
+ limit: flags.limit === undefined ? 20 : Number(flags.limit),
34
+ sourceBuild: flags['source-build'],
35
+ onProgress: flags.json ? err : out,
36
+ signal: controller.signal,
37
+ })
38
+ } finally {
39
+ for (const s of STOP_SIGNALS) process.off(s, onSignal)
40
+ }
41
+ const failed = reports.filter((r) => r.state === 'failed').length
42
+ const stopped = reports.stopped
43
+ out(
44
+ flags.json
45
+ ? JSON.stringify({ schemaVersion: 1, reports, ...(stopped ? { stopped } : {}) }, null, 2)
46
+ : stopped
47
+ ? `Stopped after ${stopped.checked} of ${stopped.total} page views. ${failed} failed. Page views not checked keep their earlier results.`
48
+ : `Checked ${reports.length} page views. ${failed} failed. Reports are local and were not sent to an agent.`,
49
+ )
50
+ return stopped ? CHECKS_STOPPED_EXIT : failed ? 2 : 0
51
+ }
52
+
53
+ const STOP_SIGNALS = ['SIGTERM', 'SIGINT']
54
+ // Exit code of a run that was stopped before every page view was checked.
55
+ export const CHECKS_STOPPED_EXIT = 3
@@ -0,0 +1,113 @@
1
+ // Pure shared presentation logic: callers supply validated v1 reports.
2
+ import { findingSeverity } from './seo-analysis.js'
3
+
4
+ const stable = (value) =>
5
+ JSON.stringify(value, (_key, item) =>
6
+ item && typeof item === 'object' && !Array.isArray(item)
7
+ ? Object.fromEntries(
8
+ Object.keys(item)
9
+ .sort()
10
+ .map((key) => [key, item[key]]),
11
+ )
12
+ : item,
13
+ )
14
+ const equal = (a, b) => stable(a) === stable(b)
15
+ const usable = (report) => ['complete', 'partial'].includes(report.state)
16
+ const number = (value) => typeof value === 'number' && Number.isFinite(value)
17
+
18
+ export function compareReports(before, after, { allowBuildChange = false } = {}) {
19
+ const reasons = []
20
+ const left = before.profile,
21
+ right = after.profile
22
+ for (const [label, a, b] of [
23
+ ['page or environment', [before.boardId, before.pageId, before.environment], [after.boardId, after.pageId, after.environment]],
24
+ ['viewport', before.viewport, after.viewport],
25
+ ['observation window', before.completeness.window, after.completeness.window],
26
+ ['network coverage', before.completeness.network, after.completeness.network],
27
+ ['service worker state', before.completeness.serviceWorker, after.completeness.serviceWorker],
28
+ ])
29
+ if (!equal(a, b)) reasons.push(`Different ${label}.`)
30
+ const buildChanged = left.sourceBuild !== right.sourceBuild
31
+ const declaredBuildChange = buildChanged && allowBuildChange && Boolean(left.sourceBuild && right.sourceBuild)
32
+ const keys = [...new Set([...Object.keys(left), ...Object.keys(right)])]
33
+ for (const key of keys) {
34
+ if (key === 'sourceBuild' && declaredBuildChange) continue
35
+ if (!equal(left[key], right[key])) reasons.push(`Different ${key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase()}.`)
36
+ }
37
+ for (const key of ['browser', 'device', 'throttling'])
38
+ if (!left[key] || !right[key]) reasons.push(`Missing ${key} conditions in an older report.`)
39
+ if ((left.authRole === 'configured' || right.authRole === 'configured') && (!left.authStateHash || !right.authStateHash))
40
+ reasons.push('Missing authentication state evidence.')
41
+ if (!usable(before) || !usable(after)) reasons.push('A run has no usable measurements.')
42
+ const comparable = reasons.length === 0
43
+ const metrics = [...new Set([...Object.keys(before.metrics), ...Object.keys(after.metrics)])].map((key) => {
44
+ const a = usable(before) && number(before.metrics[key]) ? before.metrics[key] : null
45
+ const b = usable(after) && number(after.metrics[key]) ? after.metrics[key] : null
46
+ const delta = comparable && a !== null && b !== null ? b - a : null
47
+ const absolute = key.endsWith('Ms') ? 50 : key.endsWith('Bytes') ? 1024 : key === 'cumulativeLayoutShift' ? 0.01 : 1
48
+ const small = delta !== null && (Math.abs(delta) < absolute || Math.abs(delta) < Math.abs(a) * 0.05)
49
+ return {
50
+ key,
51
+ before: a,
52
+ after: b,
53
+ delta,
54
+ percent: delta === null || a === 0 ? null : (delta / a) * 100,
55
+ change: delta === null ? 'unknown' : delta === 0 ? 'unchanged' : small ? 'small' : delta > 0 ? 'increased' : 'decreased',
56
+ }
57
+ })
58
+ const budgetsChanged = !equal(before.budgets, after.budgets)
59
+ const findingsComparable = comparable && before.state === 'complete' && after.state === 'complete' && !budgetsChanged
60
+ const beforeIds = new Set(before.findings.map((f) => f.id)),
61
+ afterIds = new Set(after.findings.map((f) => f.id))
62
+ return {
63
+ comparable,
64
+ reasons,
65
+ buildChanged,
66
+ declaredBuildChange,
67
+ budgetsChanged,
68
+ metrics,
69
+ findingsComparable,
70
+ added: findingsComparable ? after.findings.filter((f) => !beforeIds.has(f.id)) : [],
71
+ removed: findingsComparable ? before.findings.filter((f) => !afterIds.has(f.id)) : [],
72
+ retained: findingsComparable ? after.findings.filter((f) => beforeIds.has(f.id)) : [],
73
+ changed: findingsComparable
74
+ ? after.findings.filter((f) => {
75
+ const previous = before.findings.find((item) => item.id === f.id)
76
+ return previous && (previous.severity !== f.severity || previous.title !== f.title)
77
+ })
78
+ : [],
79
+ }
80
+ }
81
+
82
+ export const viewRuns = (view) => (view.runs?.length ? view.runs : view.report ? [{ report: view.report, state: view.state }] : [])
83
+ export const actionableCount = (view) =>
84
+ viewRuns(view).reduce((count, run) => count + run.report.findings.filter((f) => findingSeverity(f) === 'warning').length, 0)
85
+ export const hasState = (view, state) =>
86
+ view.state === state || viewRuns(view).some((run) => run.state === state || run.report.state === state)
87
+ export const isSlowView = (view) =>
88
+ viewRuns(view).some(
89
+ ({ report }) => usable(report) && report.findings.some((f) => f.category === 'performance' && f.severity === 'warning'),
90
+ )
91
+ export function sortViews(views, order = 'problems') {
92
+ const lcp = (view) => {
93
+ const run = viewRuns(view).find((item) => item.report.profile.runner === 'lighthouse')
94
+ const value = run?.report.metrics.largestContentfulPaintMs
95
+ return run && usable(run.report) && number(value) ? value : -1
96
+ }
97
+ const problem = (view) =>
98
+ hasState(view, 'failed') || hasState(view, 'unsupported')
99
+ ? 4
100
+ : actionableCount(view)
101
+ ? 3
102
+ : hasState(view, 'stale')
103
+ ? 2
104
+ : hasState(view, 'partial')
105
+ ? 1
106
+ : 0
107
+ return [...views].sort(
108
+ (a, b) =>
109
+ (order === 'lcp' ? lcp(b) - lcp(a) : problem(b) - problem(a) || actionableCount(b) - actionableCount(a)) ||
110
+ a.pageId.localeCompare(b.pageId) ||
111
+ a.viewport.localeCompare(b.viewport),
112
+ )
113
+ }
@@ -0,0 +1,32 @@
1
+ // Diagnostic environment labels are independent of captured environments.
2
+ // They carry no URLs, paths or arbitrary presentation text.
3
+ export const CHECK_ENVIRONMENTS_MAX = 8
4
+ const id = /^[a-z0-9][a-z0-9-]{0,63}$/
5
+ export function validateCheckEnvironments(value) {
6
+ if (!Array.isArray(value) || !value.length || value.length > CHECK_ENVIRONMENTS_MAX)
7
+ throw new Error('Checks need one to eight diagnostic environments.')
8
+ const seen = new Set()
9
+ const environments = value.map((item) => {
10
+ if (
11
+ !item ||
12
+ typeof item !== 'object' ||
13
+ Array.isArray(item) ||
14
+ !id.test(item.id) ||
15
+ typeof item.captured !== 'boolean' ||
16
+ Object.keys(item).some((key) => !['id', 'captured'].includes(key)) ||
17
+ seen.has(item.id)
18
+ )
19
+ throw new Error('Invalid diagnostic environment descriptor.')
20
+ seen.add(item.id)
21
+ return { id: item.id, captured: item.captured }
22
+ })
23
+ if (environments.filter((item) => item.captured).length > 1)
24
+ throw new Error('Only one diagnostic environment can identify the hosted capture.')
25
+ return environments
26
+ }
27
+ export function mergeCheckEnvironments(previous, incoming) {
28
+ const selected = incoming?.find((item) => item.captured)?.id
29
+ const merged = new Map(previous.map((item) => [item.id, { ...item, ...(selected ? { captured: item.id === selected } : {}) }]))
30
+ for (const item of incoming || []) merged.set(item.id, { ...item })
31
+ return validateCheckEnvironments([...merged.values()])
32
+ }
@@ -0,0 +1,82 @@
1
+ import fs from 'node:fs'
2
+ import path from 'node:path'
3
+ import { ID_RE } from '../config.js'
4
+
5
+ export const FLOW_MAX_BYTES = 32 * 1024
6
+ export const FLOW_MAX_STEPS = 20
7
+ const object = (value) => value && typeof value === 'object' && !Array.isArray(value)
8
+ const selector = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 500
9
+ const fail = () => {
10
+ throw new Error('Invalid flow definition. Use one configured page and viewport, with at most 20 bounded explicit steps.')
11
+ }
12
+
13
+ export function normalizeFlow(value) {
14
+ if (
15
+ !object(value) ||
16
+ Buffer.byteLength(JSON.stringify(value)) > FLOW_MAX_BYTES ||
17
+ value.schemaVersion !== 1 ||
18
+ typeof value.pageId !== 'string' ||
19
+ !ID_RE.test(value.pageId) ||
20
+ typeof value.viewport !== 'string' ||
21
+ !/^[a-z][a-z0-9-]{0,31}$/.test(value.viewport) ||
22
+ Object.keys(value).some((key) => !['schemaVersion', 'pageId', 'viewport', 'accessibility', 'steps'].includes(key)) ||
23
+ (value.accessibility !== undefined && typeof value.accessibility !== 'boolean') ||
24
+ !Array.isArray(value.steps) ||
25
+ !value.steps.length ||
26
+ value.steps.length > FLOW_MAX_STEPS
27
+ )
28
+ fail()
29
+ const steps = value.steps.map((step) => {
30
+ if (
31
+ !object(step) ||
32
+ Object.keys(step).some((key) => !['action', 'ready', 'maxDurationMs'].includes(key)) ||
33
+ (step.ready !== undefined && !selector(step.ready)) ||
34
+ (step.maxDurationMs !== undefined &&
35
+ (!Number.isFinite(step.maxDurationMs) || step.maxDurationMs < 1 || step.maxDurationMs > 20000)) ||
36
+ !object(step.action) ||
37
+ Object.keys(step.action).length !== 1
38
+ )
39
+ fail()
40
+ const [type, input] = Object.entries(step.action)[0]
41
+ let action
42
+ if (['click', 'hover', 'waitFor'].includes(type) && selector(input)) action = { type, selector: input }
43
+ else if (
44
+ type === 'fill' &&
45
+ Array.isArray(input) &&
46
+ input.length === 2 &&
47
+ selector(input[0]) &&
48
+ typeof input[1] === 'string' &&
49
+ input[1].length <= 2000
50
+ )
51
+ action = { type, selector: input[0], value: input[1] }
52
+ else if (type === 'press' && typeof input === 'string' && input.length > 0 && input.length <= 80) action = { type, key: input }
53
+ else if (type === 'wait' && Number.isInteger(input) && input >= 0 && input <= 5000) action = { type, ms: input }
54
+ else if (type === 'scrollTo' && Number.isFinite(input) && input >= 0 && input <= 100000) action = { type, y: input }
55
+ else fail()
56
+ return { action, ready: step.ready ?? null, maxDurationMs: step.maxDurationMs ?? null }
57
+ })
58
+ return { schemaVersion: 1, pageId: value.pageId, viewport: value.viewport, accessibility: value.accessibility ?? false, steps }
59
+ }
60
+
61
+ export function readFlow(file, dir) {
62
+ if (typeof file !== 'string' || !file.trim()) throw new Error('Flow checks require an explicit flow file.')
63
+ let descriptor
64
+ try {
65
+ descriptor = fs.openSync(path.resolve(dir, file), 'r')
66
+ const stat = fs.fstatSync(descriptor)
67
+ if (!stat.isFile() || stat.size > FLOW_MAX_BYTES) fail()
68
+ const bytes = Buffer.alloc(FLOW_MAX_BYTES + 1)
69
+ let size = 0
70
+ while (size < bytes.length) {
71
+ const read = fs.readSync(descriptor, bytes, size, bytes.length - size, null)
72
+ if (!read) break
73
+ size += read
74
+ }
75
+ if (size > FLOW_MAX_BYTES) fail()
76
+ return normalizeFlow(JSON.parse(bytes.subarray(0, size).toString('utf8')))
77
+ } catch {
78
+ throw new Error('Could not read a valid bounded flow file. No flow actions were executed.')
79
+ } finally {
80
+ if (descriptor !== undefined) fs.closeSync(descriptor)
81
+ }
82
+ }
@@ -0,0 +1,53 @@
1
+ // Browser routes do not reliably re-run for every redirect hop. Chromium Fetch
2
+ // interception checks each main-document request before it leaves the browser.
3
+ // Authentication setup uses its own context before this guard is installed.
4
+ export async function installFlowOriginGuard(context, page, origin, closeContext) {
5
+ let violated = false
6
+ const reject = () => {
7
+ violated = true
8
+ void closeContext(context)
9
+ }
10
+ context.on('page', (popup) => {
11
+ if (popup !== page) reject()
12
+ })
13
+ await context.route('**/*', async (route) => {
14
+ const request = route.request()
15
+ try {
16
+ if (
17
+ request.isNavigationRequest() &&
18
+ !request.frame().parentFrame() &&
19
+ (request.frame().page() !== page || new URL(request.url()).origin !== origin)
20
+ ) {
21
+ violated = true
22
+ await route.abort('blockedbyclient')
23
+ reject()
24
+ return
25
+ }
26
+ await route.continue()
27
+ } catch {
28
+ reject()
29
+ }
30
+ })
31
+ const session = await context.newCDPSession(page)
32
+ const { frameTree } = await session.send('Page.getFrameTree')
33
+ session.on('Fetch.requestPaused', async (event) => {
34
+ try {
35
+ if (event.frameId === frameTree.frame.id && new URL(event.request.url).origin !== origin) {
36
+ violated = true
37
+ await session.send('Fetch.failRequest', { requestId: event.requestId, errorReason: 'BlockedByClient' })
38
+ reject()
39
+ } else await session.send('Fetch.continueRequest', { requestId: event.requestId })
40
+ } catch {
41
+ if (!page.isClosed()) reject()
42
+ }
43
+ })
44
+ await session.send('Fetch.enable', { patterns: [{ urlPattern: '*', resourceType: 'Document', requestStage: 'Request' }] })
45
+ return {
46
+ get violated() {
47
+ return violated
48
+ },
49
+ assertOrigin() {
50
+ if (violated || page.isClosed() || new URL(page.url()).origin !== origin) throw new Error('Audit origin boundary changed.')
51
+ },
52
+ }
53
+ }