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,724 @@
1
+ import fs from 'node:fs'
2
+ import { randomUUID } from 'node:crypto'
3
+ import { createRequire } from 'node:module'
4
+ import { authFor, boardViewports, getBoard, getEnvironment, joinUrl, selectPages, viewportDevice } from '../config.js'
5
+ import { captureOptions, launchBrowser, resolveStorageState, setupStates } from '../capture/capture.js'
6
+ import { runActions } from '../capture/actions.js'
7
+ import { installRequestRules, seedLocalStorage } from '../capture/requests.js'
8
+ import { entryVersion, readManifest } from '../store.js'
9
+ import { fingerprint, reportId, validateReport } from './schema.js'
10
+ import { saveReport, targetFingerprint } from './store.js'
11
+ import { probeSeo } from './seo-probe.js'
12
+ import { applyBudgets } from './budgets.js'
13
+ import { lengthIssues } from './seo-analysis.js'
14
+ import { saveSnapshot } from './seo-snapshot.js'
15
+
16
+ const require = createRequire(import.meta.url)
17
+ const VERSION = require('playwright/package.json').version
18
+ const OBSERVE = `() => {
19
+ const meta = name => document.querySelector('meta[name="'+name+'"]')?.content?.trim() || '';
20
+ const property = name => document.querySelector('meta[property="'+name+'"]')?.content?.trim() || '';
21
+ const nav = performance.getEntriesByType('navigation')[0];
22
+ const resources = performance.getEntriesByType('resource');
23
+ const canonical = document.querySelector('link[rel="canonical"]')?.getAttribute('href') || '';
24
+ let canonicalValid = false;
25
+ try { canonicalValid = ['https:','http:'].includes(new URL(canonical).protocol); } catch {}
26
+ let imageValid = false;
27
+ try { imageValid = ['https:','http:'].includes(new URL(property('og:image')).protocol); } catch {}
28
+ return {
29
+ title: document.title.trim().slice(0, 1000), description: meta('description').slice(0, 2000),
30
+ language: !!document.documentElement.lang.trim(), viewport: !!meta('viewport'),
31
+ main: !!document.querySelector('main,[role="main"]'), h1: !!document.querySelector('h1'),
32
+ unlabeledInputs: [...document.querySelectorAll('input:not([type="hidden"]):not([type="submit"]):not([type="button"]),textarea,select')].slice(0,1000).filter(el => !el.labels?.length && !el.getAttribute('aria-label') && !el.getAttribute('aria-labelledby') && !el.title).length,
33
+ canonical: !!canonical, canonicalValid, noindex: /noindex|none/i.test(meta('robots')),
34
+ canonicalHref: canonicalValid ? new URL(canonical).href.slice(0, 2049) : '',
35
+ robotsMeta: meta('robots').slice(0, 200), languageCode: document.documentElement.lang.trim().slice(0, 35),
36
+ ogTitleText: property('og:title').slice(0, 300), ogDescriptionText: property('og:description').slice(0, 600),
37
+ ogSiteName: property('og:site_name').slice(0, 120), ogType: property('og:type').slice(0, 60),
38
+ twitterCard: meta('twitter:card').slice(0, 40),
39
+ ogTitle: !!property('og:title'), ogDescription: !!property('og:description'), ogImage: !!property('og:image'), imageValid,
40
+ socialImageUrl: property('og:image').slice(0, 4097),
41
+ socialImageWidth: Number(property('og:image:width')) || null,
42
+ socialImageHeight: Number(property('og:image:height')) || null,
43
+ nav: nav ? { ttfbMs: nav.responseStart-nav.requestStart, domContentLoadedMs: nav.domContentLoadedEventEnd, loadMs: nav.loadEventEnd, documentTransferBytes: nav.transferSize || null } : null,
44
+ resourceCount: resources.length, resourceBufferFull: resources.length >= 250,
45
+ resourceTransferBytes: resources.length && resources.every(r => r.transferSize > 0) ? resources.reduce((sum,r) => sum+r.transferSize,0) : null,
46
+ resourceDecodedBytes: resources.length && resources.every(r => r.decodedBodySize > 0) ? resources.reduce((sum,r) => sum+r.decodedBodySize,0) : null,
47
+ serviceWorker: !!navigator.serviceWorker?.controller,
48
+ userAgent: navigator.userAgent
49
+ };
50
+ }`
51
+ const finding = (id, category, title, observation, nextAction, severity = 'warning') => ({
52
+ id,
53
+ category,
54
+ severity,
55
+ title,
56
+ observation,
57
+ impact:
58
+ category === 'seo'
59
+ ? 'This is a basic search presentation observation. It does not establish indexing or rank.'
60
+ : 'The observed page may be incomplete or harder to use.',
61
+ nextAction,
62
+ })
63
+
64
+ const LENGTH_FINDINGS = {
65
+ 'seo-title-long': [
66
+ 'Search title may be cut off',
67
+ 'The title is wider than search results usually show, about 580 pixels.',
68
+ 'Put the important words first and shorten the title.',
69
+ ],
70
+ 'seo-title-short': ['Search title is very short', 'The title has fewer than 10 characters.', 'Describe the page in a few more words.'],
71
+ 'seo-description-long': [
72
+ 'Search description may be cut off',
73
+ 'The description is wider than search snippets usually show, about 920 pixels.',
74
+ 'Keep the key message in the first 120 characters.',
75
+ ],
76
+ 'seo-description-short': [
77
+ 'Search description is very short',
78
+ 'The description has fewer than 50 characters.',
79
+ 'Write one or two full sentences about the page.',
80
+ ],
81
+ }
82
+ // A URL without credentials, query or fragment, for the local search preview.
83
+ function plainUrl(value) {
84
+ try {
85
+ const url = new URL(value)
86
+ if (!['http:', 'https:'].includes(url.protocol)) return null
87
+ const out = url.origin + url.pathname
88
+ return out.length <= 2048 ? out : null
89
+ } catch {
90
+ return null
91
+ }
92
+ }
93
+ // Whether two absolute URLs name the same path. Origins may differ between
94
+ // environments (staging pages declare the production canonical).
95
+ export function samePath(a, b) {
96
+ try {
97
+ const strip = (u) => {
98
+ const path = new URL(u).pathname.replace(/\/+$/, '') || '/'
99
+ try {
100
+ return decodeURIComponent(path)
101
+ } catch {
102
+ return path
103
+ }
104
+ }
105
+ return strip(a) === strip(b)
106
+ } catch {
107
+ return null
108
+ }
109
+ }
110
+
111
+ export async function checkPage({
112
+ config,
113
+ board,
114
+ page: target,
115
+ environment,
116
+ viewport,
117
+ browser,
118
+ storageState,
119
+ seo = false,
120
+ runId = randomUUID(),
121
+ sourceBuild = null,
122
+ signal = null,
123
+ }) {
124
+ const size = boardViewports(config, board)[viewport]
125
+ const device = viewportDevice(viewport, size)
126
+ const options = captureOptions(config, board)
127
+ const pageTimeout = target.timeout || config.timeouts.page
128
+ const manifest = readManifest(config, board.id, environment.id)
129
+ const report = {
130
+ schemaVersion: 1,
131
+ id: reportId(),
132
+ runId,
133
+ boardId: board.id,
134
+ pageId: target.id,
135
+ environment: environment.id,
136
+ viewport: { name: viewport, width: size.width, height: size.height },
137
+ captureVersion: entryVersion(manifest?.pages?.[target.id]?.[viewport], manifest),
138
+ sampledSeparately: true,
139
+ state: 'complete',
140
+ auditedAt: new Date().toISOString(),
141
+ profile: {
142
+ runner: 'playwright',
143
+ version: VERSION,
144
+ mode: 'navigation',
145
+ cache: storageState ? 'auth-preserved' : 'new-context',
146
+ authRole: authFor(config, board).storageState || authFor(config, board).loginScript ? 'configured' : 'anonymous',
147
+ sourceBuild: sourceBuild ? fingerprint(sourceBuild) : null,
148
+ stateFingerprint: targetFingerprint(config, board, target, environment, viewport),
149
+ seo,
150
+ production: 'unknown',
151
+ location: 'local',
152
+ sampleCount: 1,
153
+ },
154
+ completeness: {
155
+ window: 'navigation-through-configured-actions',
156
+ network: 'observed',
157
+ serviceWorker: null,
158
+ limitations: [
159
+ 'Separately sampled from the screenshot. No build or page state equivalence is established.',
160
+ 'Observed load window only. Cross origin and cached byte sizes may be unavailable.',
161
+ ],
162
+ },
163
+ metrics: {
164
+ documentStatus: null,
165
+ ttfbMs: null,
166
+ domContentLoadedMs: null,
167
+ loadMs: null,
168
+ documentTransferBytes: null,
169
+ resourceCount: null,
170
+ resourceTransferBytes: null,
171
+ resourceDecodedBytes: null,
172
+ failedRequests: null,
173
+ httpErrorResponses: null,
174
+ browserErrors: null,
175
+ requestCount: null,
176
+ },
177
+ findings: [],
178
+ }
179
+ let context
180
+ let timer
181
+ let observation = null
182
+ let snapshot = null
183
+ let collecting = true
184
+ const active = new Set()
185
+ // A stopped run abandons this view at once: closing the context ends the
186
+ // navigation or action in flight. The caller drops the result.
187
+ const abandon = () => context?.close().catch(() => {})
188
+ signal?.addEventListener('abort', abandon, { once: true })
189
+ try {
190
+ if (signal?.aborted) throw new Error('stopped')
191
+ if (storageState)
192
+ report.profile.authStateHash = fingerprint(
193
+ typeof storageState === 'string' ? JSON.parse(fs.readFileSync(storageState, 'utf8')) : storageState,
194
+ )
195
+ context = await browser.newContext({
196
+ viewport: { width: size.width, height: size.layoutHeight || size.height },
197
+ deviceScaleFactor: 1,
198
+ isMobile: device.mobile,
199
+ hasTouch: device.touch,
200
+ ...(storageState ? { storageState } : {}),
201
+ // Only when the board opts out of the capture default; checks never forced it.
202
+ ...(options.reducedMotion === 'no-preference' ? { reducedMotion: 'no-preference' } : {}),
203
+ })
204
+ // Hard cap also covers configured actions and a hanging page script.
205
+ if (signal?.aborted) throw new Error('stopped')
206
+ timer = setTimeout(() => context.close().catch(() => {}), Math.min(300000, pageTimeout + config.timeouts.settle + 30000))
207
+ const original = joinUrl(environment.baseUrl, target.path)
208
+ // The board's block list (analytics): blocked requests are not failures.
209
+ const rules = await installRequestRules(context, original, { block: options.block, guard: false })
210
+ await seedLocalStorage(context, original, { ...options.localStorage, ...target.localStorage })
211
+ const page = await context.newPage()
212
+ report.metrics.failedRequests = 0
213
+ report.metrics.httpErrorResponses = 0
214
+ report.metrics.browserErrors = 0
215
+ report.metrics.requestCount = 0
216
+ page.on('request', (request) => {
217
+ if (!collecting) return
218
+ active.add(request)
219
+ report.metrics.requestCount = Math.min(100000, report.metrics.requestCount + 1)
220
+ })
221
+ page.on('requestfinished', (request) => active.delete(request))
222
+ page.on('requestfailed', (request) => {
223
+ active.delete(request)
224
+ if (!collecting || rules.isBlocked(request)) return
225
+ report.metrics.failedRequests = Math.min(100000, report.metrics.failedRequests + 1)
226
+ })
227
+ const statuses = new Set()
228
+ page.on('response', (r) => {
229
+ if (!collecting) return
230
+ const expectedDocument =
231
+ r.request().isNavigationRequest() && r.frame() === page.mainFrame() && target.expectStatus?.includes(r.status())
232
+ if (r.status() >= 400 && !expectedDocument) {
233
+ report.metrics.httpErrorResponses = Math.min(100000, report.metrics.httpErrorResponses + 1)
234
+ statuses.add(r.status())
235
+ }
236
+ })
237
+ page.on('pageerror', () => {
238
+ if (!collecting) return
239
+ report.metrics.browserErrors = Math.min(100000, report.metrics.browserErrors + 1)
240
+ })
241
+ const response = await page.goto(original, { waitUntil: 'load', timeout: pageTimeout })
242
+ report.metrics.documentStatus = response?.status() ?? null
243
+ const expected = target.expectStatus?.length ? target.expectStatus.includes(response?.status()) : response?.status() < 400
244
+ if (!expected)
245
+ report.findings.push(
246
+ finding(
247
+ 'document-status',
248
+ 'reliability',
249
+ 'Unexpected document status',
250
+ `The main document returned HTTP ${response?.status() || 0}.`,
251
+ 'Check the configured expected status and the original page response.',
252
+ ),
253
+ )
254
+ await page.waitForLoadState('networkidle', { timeout: config.timeouts.settle }).catch(() => {
255
+ report.completeness.network = 'partial'
256
+ })
257
+ if (target.waitFor) await page.waitForSelector(target.waitFor, { timeout: pageTimeout, state: 'visible' })
258
+ await runActions(page, target.actions, { timeout: pageTimeout, viewport })
259
+ observation = await page.evaluate(`(${OBSERVE})()`)
260
+ if (target.errorSelectors?.length) {
261
+ const errors = await page.evaluate(
262
+ `((selectors) => {
263
+ let visible = 0, invalid = 0, limited = 0;
264
+ for (const selector of selectors) {
265
+ try {
266
+ const matches = document.querySelectorAll(selector);
267
+ if (matches.length > 1000) limited++;
268
+ if (Array.prototype.slice.call(matches,0,1000).some(el => {
269
+ const style = getComputedStyle(el), rect = el.getBoundingClientRect();
270
+ return style.visibility !== 'hidden' && style.visibility !== 'collapse' && rect.width > 0 && rect.height > 0;
271
+ })) visible++;
272
+ } catch { invalid++; }
273
+ }
274
+ return { visible, invalid, limited };
275
+ })(${JSON.stringify(target.errorSelectors)})`,
276
+ )
277
+ if (errors.visible)
278
+ report.findings.push(
279
+ finding(
280
+ 'configured-error-visible',
281
+ 'reliability',
282
+ 'Configured error state is visible',
283
+ `${errors.visible} configured error selectors matched visible elements.`,
284
+ 'Inspect the configured error states on the original page.',
285
+ ),
286
+ )
287
+ if (errors.invalid || errors.limited)
288
+ report.findings.push(
289
+ finding(
290
+ 'error-selectors-incomplete',
291
+ 'reliability',
292
+ 'Error selector coverage is incomplete',
293
+ 'A configured CSS selector was invalid or exceeded the element inspection limit.',
294
+ 'Use valid, specific CSS selectors for known error states.',
295
+ 'advisory',
296
+ ),
297
+ )
298
+ }
299
+ if (active.size) report.completeness.network = 'partial'
300
+ const final = new URL(page.url())
301
+ const initial = new URL(original)
302
+ if (final.origin !== initial.origin || final.pathname !== initial.pathname)
303
+ report.findings.push(
304
+ finding(
305
+ 'destination-changed',
306
+ 'reliability',
307
+ 'Navigation destination changed',
308
+ 'The final origin or path differs from the configured target. This may be a login redirect or an intentional redirect.',
309
+ 'Verify the signed in state and intended final route.',
310
+ ),
311
+ )
312
+ for (const [key, value] of Object.entries({
313
+ ...observation.nav,
314
+ resourceCount: observation.resourceCount,
315
+ resourceTransferBytes: observation.resourceTransferBytes,
316
+ resourceDecodedBytes: observation.resourceDecodedBytes,
317
+ }))
318
+ report.metrics[key] = Number.isFinite(value) && value >= 0 && value <= 1e15 ? value : null
319
+ report.completeness.serviceWorker = observation.serviceWorker
320
+ if (observation.resourceBufferFull) report.completeness.network = 'partial'
321
+ report.profile.browser = { version: browser.version(), userAgentHash: fingerprint(observation.userAgent) }
322
+ report.profile.device = { mobile: device.mobile, deviceScaleFactor: 1, screenEmulationDisabled: false }
323
+ report.profile.throttling = { method: 'provided', rttMs: null, throughputKbps: null, cpuSlowdownMultiplier: 1 }
324
+ if (report.metrics.failedRequests)
325
+ report.findings.push(
326
+ finding(
327
+ 'request-failed',
328
+ 'reliability',
329
+ 'Requests failed during load',
330
+ `${report.metrics.failedRequests} requests did not complete.`,
331
+ 'Inspect the original page network panel and retry the same profile.',
332
+ ),
333
+ )
334
+ if (report.metrics.httpErrorResponses)
335
+ report.findings.push(
336
+ finding(
337
+ 'http-errors',
338
+ 'reliability',
339
+ 'Error responses during load',
340
+ `Observed HTTP statuses ${[...statuses].sort().join(', ')} in ${report.metrics.httpErrorResponses} responses.`,
341
+ 'Inspect failed API and asset responses on the original page.',
342
+ ),
343
+ )
344
+ if (report.metrics.browserErrors)
345
+ report.findings.push(
346
+ finding(
347
+ 'browser-errors',
348
+ 'reliability',
349
+ 'Browser script errors',
350
+ `${report.metrics.browserErrors} uncaught browser errors occurred. Raw error text was not stored.`,
351
+ 'Inspect the original browser console with the same signed in state.',
352
+ ),
353
+ )
354
+ const semantics = [
355
+ ['title', 'Document title is missing'],
356
+ ['language', 'Document language is missing'],
357
+ ['viewport', 'Viewport metadata is missing'],
358
+ ['main', 'Main landmark was not found'],
359
+ ['h1', 'First level heading was not found'],
360
+ ]
361
+ for (const [key, title] of semantics)
362
+ if (!observation[key])
363
+ report.findings.push(
364
+ finding(
365
+ `missing-${key}`,
366
+ 'semantics',
367
+ title,
368
+ 'The expected basic document semantic was not observed.',
369
+ 'Review the original document structure and intended page semantics.',
370
+ 'advisory',
371
+ ),
372
+ )
373
+ if (observation.unlabeledInputs)
374
+ report.findings.push(
375
+ finding(
376
+ 'input-labels',
377
+ 'semantics',
378
+ 'Inputs may be missing labels',
379
+ `${observation.unlabeledInputs} controls have no direct label or naming attribute. This is not a full accessibility audit.`,
380
+ 'Check accessible names with keyboard and assistive technology.',
381
+ 'advisory',
382
+ ),
383
+ )
384
+ // Diagnostic probes are outside the navigation measurement window.
385
+ collecting = false
386
+ if (seo && target.seo?.indexable === false) {
387
+ report.findings.push(
388
+ finding(
389
+ 'seo-private-expected',
390
+ 'seo',
391
+ 'Search checks are not applicable',
392
+ 'This page is configured as intentionally non-indexable. Public metadata and crawl checks were skipped.',
393
+ 'Keep the intended private or staging search policy.',
394
+ 'advisory',
395
+ ),
396
+ )
397
+ }
398
+ if (seo && target.seo?.indexable !== false) {
399
+ report.completeness.limitations.push(
400
+ 'Crawl rules describe Googlebot only, not search inclusion. Image checks use the first Open Graph image only.',
401
+ 'SEO probes omit credentials and referrers, stay on the original origin and follow no redirects. Unsupported checks are unknown.',
402
+ 'SEO probes allow six seconds each, 500 KiB of crawl rules, and a 5 MiB raster image with at most 16 megapixels.',
403
+ )
404
+ for (const key of ['socialImageWidth', 'socialImageHeight'])
405
+ report.metrics[key] =
406
+ Number.isFinite(observation[key]) && observation[key] > 0 && observation[key] < 100000 ? observation[key] : null
407
+ const noindex = observation.noindex || /noindex|none/i.test((await response?.allHeaders())?.['x-robots-tag'] || '')
408
+ if (noindex)
409
+ report.findings.push(
410
+ finding(
411
+ 'search-noindex',
412
+ 'seo',
413
+ 'Search exclusion was observed',
414
+ 'A robots directive requests exclusion from search. This is expected for private pages and staging.',
415
+ 'Confirm this page is intended to be indexable before changing the directive.',
416
+ 'advisory',
417
+ ),
418
+ )
419
+ for (const [key, title] of [
420
+ ['description', 'Search description is missing'],
421
+ ['canonical', 'Canonical URL is missing'],
422
+ ['ogTitle', 'Social title is missing'],
423
+ ['ogDescription', 'Social description is missing'],
424
+ ['ogImage', 'Social image is missing'],
425
+ ])
426
+ if (!observation[key])
427
+ report.findings.push(
428
+ finding(
429
+ `seo-${key.toLowerCase()}`,
430
+ 'seo',
431
+ title,
432
+ 'The metadata was not observed on this opted in page.',
433
+ 'Review the metadata for this intended public page.',
434
+ 'advisory',
435
+ ),
436
+ )
437
+ report.metrics.titleLength = [...observation.title].length
438
+ report.metrics.descriptionLength = [...observation.description].length
439
+ for (const issue of lengthIssues(observation.title, observation.description))
440
+ report.findings.push(finding(issue.id, 'seo', ...LENGTH_FINDINGS[issue.id], 'advisory'))
441
+ if (observation.canonicalValid && samePath(observation.canonicalHref, page.url()) === false)
442
+ report.findings.push(
443
+ finding(
444
+ 'canonical-elsewhere',
445
+ 'seo',
446
+ 'Canonical URL names another page',
447
+ 'The canonical link points to a different path than this page. Search engines may show that page instead.',
448
+ 'Point the canonical link at this page, unless it is intentionally a copy of the other page.',
449
+ 'advisory',
450
+ ),
451
+ )
452
+ if (observation.canonical && !observation.canonicalValid)
453
+ report.findings.push(
454
+ finding(
455
+ 'canonical-invalid',
456
+ 'seo',
457
+ 'Canonical URL is not absolute HTTP',
458
+ 'The canonical value is not an absolute HTTP or HTTPS URL.',
459
+ 'Set an absolute canonical URL for the intended indexable page.',
460
+ 'advisory',
461
+ ),
462
+ )
463
+ const probes = await probeSeo(page, original, observation.imageValid ? observation.socialImageUrl : null)
464
+ snapshot = {
465
+ url: plainUrl(page.url()),
466
+ title: observation.title.slice(0, 300),
467
+ description: observation.description.slice(0, 600),
468
+ canonical: plainUrl(observation.canonicalHref),
469
+ robots: observation.robotsMeta,
470
+ language: observation.languageCode,
471
+ social: {
472
+ title: observation.ogTitleText,
473
+ description: observation.ogDescriptionText,
474
+ siteName: observation.ogSiteName,
475
+ type: observation.ogType,
476
+ card: observation.twitterCard,
477
+ image: observation.ogImage,
478
+ },
479
+ image: probes.image?.state === 'ok' && probes.image.thumbnail ? probes.image.thumbnail : null,
480
+ }
481
+ report.metrics.robotsStatus = probes.robots.status
482
+ report.metrics.robotsAllowed =
483
+ probes.robots.state === 'allowed' || probes.robots.state === 'absent' ? 1 : probes.robots.state === 'blocked' ? 0 : null
484
+ if (probes.robots.state === 'blocked')
485
+ report.findings.push(
486
+ finding(
487
+ 'robots-crawl-blocked',
488
+ 'seo',
489
+ 'Crawl rules restrict this page',
490
+ 'The applicable Googlebot rule disallows this route. A crawl restriction does not establish search exclusion.',
491
+ 'Review crawl rules against the intended public page policy.',
492
+ 'advisory',
493
+ ),
494
+ )
495
+ else if (!['allowed', 'absent'].includes(probes.robots.state))
496
+ report.findings.push(
497
+ finding(
498
+ 'robots-unavailable',
499
+ 'seo',
500
+ 'Crawl rules could not be established',
501
+ 'The crawl rules response was unavailable, redirected, unsupported or exceeded a probe limit. Crawl permission is unknown.',
502
+ 'Inspect the original crawl rules response and check the diagnostic limits.',
503
+ 'advisory',
504
+ ),
505
+ )
506
+ report.metrics.socialImageDecodedWidth = probes.image?.state === 'ok' ? probes.image.width : null
507
+ report.metrics.socialImageDecodedHeight = probes.image?.state === 'ok' ? probes.image.height : null
508
+ report.metrics.socialImageBytes = probes.image?.state === 'ok' ? probes.image.bytes : null
509
+ report.metrics.socialImageStatus = probes.image?.status ?? null
510
+ if (probes.image && probes.image.state !== 'ok') {
511
+ const invalid = ['http', 'invalid'].includes(probes.image.state)
512
+ report.findings.push(
513
+ finding(
514
+ invalid ? 'social-image-failed' : 'social-image-unavailable',
515
+ 'seo',
516
+ invalid ? 'Social image could not be loaded' : 'Social image validation is incomplete',
517
+ invalid
518
+ ? 'The referenced image returned an error response or could not be decoded as an image.'
519
+ : 'The referenced image was off origin, redirected, unavailable, unsupported or exceeded a probe limit. Its validity is unknown.',
520
+ 'Check the original image response and its public availability.',
521
+ 'advisory',
522
+ ),
523
+ )
524
+ }
525
+ if (
526
+ probes.image?.state === 'ok' &&
527
+ ((observation.socialImageWidth && observation.socialImageWidth !== probes.image.width) ||
528
+ (observation.socialImageHeight && observation.socialImageHeight !== probes.image.height))
529
+ )
530
+ report.findings.push(
531
+ finding(
532
+ 'social-image-dimensions',
533
+ 'seo',
534
+ 'Social image dimensions differ from metadata',
535
+ 'Decoded image dimensions do not match the declared dimensions.',
536
+ 'Update the declared dimensions to match the actual social image.',
537
+ 'advisory',
538
+ ),
539
+ )
540
+ if (observation.ogImage && !observation.imageValid)
541
+ report.findings.push(
542
+ finding(
543
+ 'social-image-invalid',
544
+ 'seo',
545
+ 'Social image URL is not absolute HTTP',
546
+ 'The social image value is not an absolute HTTP or HTTPS URL.',
547
+ 'Use a reachable absolute social image URL.',
548
+ 'advisory',
549
+ ),
550
+ )
551
+ }
552
+ } catch {
553
+ report.state = observation ? 'partial' : 'failed'
554
+ report.completeness.network = 'partial'
555
+ report.findings.push(
556
+ finding(
557
+ 'check-failed',
558
+ 'reliability',
559
+ 'Page check could not finish',
560
+ 'Navigation, the configured ready state, or an action did not finish. Captures were preserved.',
561
+ 'Run the original page manually and check authentication and configured actions.',
562
+ ),
563
+ )
564
+ } finally {
565
+ collecting = false
566
+ clearTimeout(timer)
567
+ signal?.removeEventListener('abort', abandon)
568
+ await context?.close().catch(() => {})
569
+ }
570
+ return {
571
+ report: validateReport(applyBudgets(report, config.checks?.budgets)),
572
+ duplicateKeys:
573
+ seo && target.seo?.indexable !== false && observation
574
+ ? {
575
+ title: observation.title ? fingerprint(observation.title) : null,
576
+ description: observation.description ? fingerprint(observation.description) : null,
577
+ }
578
+ : null,
579
+ snapshot:
580
+ snapshot && report.state !== 'failed'
581
+ ? {
582
+ schemaVersion: 1,
583
+ reportId: report.id,
584
+ boardId: board.id,
585
+ pageId: target.id,
586
+ environment: environment.id,
587
+ viewport,
588
+ auditedAt: report.auditedAt,
589
+ ...snapshot,
590
+ }
591
+ : null,
592
+ }
593
+ }
594
+
595
+ // `seo`: true for every selected page, false, or a list of page ids (the
596
+ // config's checks.seo). Private pages still record that SEO is not applicable.
597
+ export const seoEnabledFor = (seo, page) => seo === true || (Array.isArray(seo) && seo.includes(page.id))
598
+
599
+ export async function runChecks({
600
+ config,
601
+ boardId = null,
602
+ envId = null,
603
+ only = null,
604
+ seo = false,
605
+ limit = 20,
606
+ browser: suppliedBrowser = null,
607
+ sourceBuild = null,
608
+ onProgress = () => {},
609
+ // Aborting stops the run: the view in progress is abandoned, views not
610
+ // reached are skipped, and only finished views are saved, so every other
611
+ // view keeps its earlier results. The returned list then carries
612
+ // `stopped: { checked, total }`.
613
+ signal = null,
614
+ }) {
615
+ if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error('Checks limit must be from 1 to 100 page views.')
616
+ if (
617
+ sourceBuild !== null &&
618
+ sourceBuild !== undefined &&
619
+ (typeof sourceBuild !== 'string' || !/^[A-Za-z0-9._-]{1,120}$/.test(sourceBuild))
620
+ )
621
+ throw new Error('Source build must be a short commit or build identifier without paths or credentials.')
622
+ const board = getBoard(config, boardId)
623
+ const environment = getEnvironment(board, envId)
624
+ const targets = selectPages(board, only).flatMap((page) => page.viewports.map((viewport) => ({ page, viewport })))
625
+ if (targets.length > limit) throw new Error('The selected page views exceed the limit. Select fewer pages or explicitly raise the limit.')
626
+ let browser = suppliedBrowser
627
+ if (!browser && !signal?.aborted) {
628
+ try {
629
+ // The run handles SIGTERM and SIGINT itself (see signal), so Playwright
630
+ // must not close the browser under a view that is still being checked.
631
+ browser = await launchBrowser(config, { handleSignals: false })
632
+ } catch {
633
+ /* Write visible failed reports below. */
634
+ }
635
+ }
636
+ const runId = randomUUID()
637
+ const results = []
638
+ const anySeo = targets.some((t) => seoEnabledFor(seo, t.page))
639
+ try {
640
+ // Reuse the existing authentication mechanism. Run it against the chosen
641
+ // environment, without ever storing the resulting credentials in reports.
642
+ let storageState = null
643
+ let authFailed = false
644
+ try {
645
+ storageState = await resolveStorageState(browser, config, { ...board, baseUrl: environment.baseUrl })
646
+ } catch {
647
+ authFailed = true
648
+ }
649
+ // The board's setup (guest entry and the like) once per viewport, as in a capture.
650
+ const stateFor =
651
+ board.setup && browser && !authFailed
652
+ ? setupStates({
653
+ browser,
654
+ board,
655
+ config,
656
+ baseUrl: environment.baseUrl,
657
+ base: storageState,
658
+ viewports: boardViewports(config, board),
659
+ })
660
+ : null
661
+ for (const target of targets) {
662
+ if (signal?.aborted) break
663
+ onProgress(`Checking ${target.page.id} ${target.viewport}`)
664
+ let state = storageState
665
+ let setupFailed = false
666
+ if (stateFor) state = await stateFor(target.page, target.viewport).catch(() => ((setupFailed = true), null))
667
+ const result = await checkPage({
668
+ config,
669
+ board,
670
+ environment,
671
+ ...target,
672
+ browser: authFailed || setupFailed ? null : browser,
673
+ storageState: state,
674
+ seo: seoEnabledFor(seo, target.page),
675
+ runId,
676
+ sourceBuild,
677
+ signal,
678
+ })
679
+ // Stopped while this view was being checked: it was not checked.
680
+ if (signal?.aborted) break
681
+ results.push(result)
682
+ }
683
+ if (anySeo)
684
+ for (const key of ['title', 'description']) {
685
+ const byKey = new Map()
686
+ for (const r of results) {
687
+ const value = r.duplicateKeys?.[key]
688
+ if (value) {
689
+ const pages = byKey.get(value) || new Set()
690
+ pages.add(r.report.pageId)
691
+ byKey.set(value, pages)
692
+ }
693
+ }
694
+ for (const r of results)
695
+ if (byKey.get(r.duplicateKeys?.[key])?.size > 1)
696
+ r.report.findings.push(
697
+ finding(
698
+ `duplicate-${key}`,
699
+ 'seo',
700
+ `Duplicate ${key} in selected pages`,
701
+ 'The same metadata value was observed on multiple selected pages in this run.',
702
+ 'Review whether these intended public pages need distinct metadata.',
703
+ 'advisory',
704
+ ),
705
+ )
706
+ }
707
+ const saved = []
708
+ for (const { report, snapshot } of results) {
709
+ saved.push(await saveReport(config, report))
710
+ // A preview that fails validation is dropped; the report stands.
711
+ if (snapshot)
712
+ try {
713
+ saveSnapshot(config, snapshot)
714
+ } catch {
715
+ /* no preview for this report */
716
+ }
717
+ }
718
+ if (results.length < targets.length)
719
+ Object.defineProperty(saved, 'stopped', { value: { checked: results.length, total: targets.length } })
720
+ return saved
721
+ } finally {
722
+ if (!suppliedBrowser) await browser?.close()
723
+ }
724
+ }