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
package/src/config.js ADDED
@@ -0,0 +1,1061 @@
1
+ // Loads and validates shapewall.config.json. Every problem is collected and
2
+ // reported at once, with the JSON path of the bad value, so a config can be
3
+ // fixed in one pass. Paths in the config are relative to the config file.
4
+
5
+ import fs from 'node:fs'
6
+ import { isIP } from 'node:net'
7
+ import path from 'node:path'
8
+ import { checkSteps } from './journey-paths.js'
9
+ import { normalizeNotifications } from './notify/config.js'
10
+ import { validateAgent } from './agent/config.js'
11
+ import { validateStarterAgent } from './agent/starter/settings.js'
12
+ import { cliCommand } from './invocation.js'
13
+ import { normalizeBudgets } from './checks/budgets.js'
14
+ import { CAPTURE_PACING_DEFAULTS, CAPTURE_PACING_MAX } from './capture/pacing.js'
15
+
16
+ export const CONFIG_FILE = 'shapewall.config.json'
17
+ export const ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/
18
+ // A page path: starts with '/', may carry a query, never a hash or a scheme.
19
+ export const PAGE_PATH_RE = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]{0,500}$/
20
+ // The built-in viewport names. Any other name matching VIEWPORT_NAME_RE works
21
+ // too ("phone-landscape"); its device comes from its prefix or its flags
22
+ // (viewportDevice below).
23
+ export const VIEWPORT_NAMES = ['desktop', 'tablet', 'phone']
24
+ export const VIEWPORT_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/
25
+ const VIEWPORTS_MAX = 8
26
+ export const DEFAULT_VIEWPORTS = {
27
+ desktop: { width: 1440, height: 2200 },
28
+ phone: { width: 390, height: 1800 },
29
+ }
30
+ // How wide a frame is drawn on the board, per CSS pixel of the capture.
31
+ export const FRAME_SCALE = { desktop: 0.25, tablet: 0.3, phone: 0.4615 }
32
+ // Thumbnails, as a fraction of the capture width.
33
+ export const THUMB_SCALE = { desktop: 0.25, tablet: 0.35, phone: 0.5 }
34
+ export const PHONE_USER_AGENT =
35
+ 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1'
36
+ export const TABLET_USER_AGENT =
37
+ 'Mozilla/5.0 (iPad; CPU OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1'
38
+ export const NOTE_MAX = 200
39
+ export const ACTION_TYPES = [
40
+ 'click',
41
+ 'tap',
42
+ 'fill',
43
+ 'press',
44
+ 'hover',
45
+ 'wait',
46
+ 'waitFor',
47
+ 'waitForFunction',
48
+ 'scrollTo',
49
+ 'mouse',
50
+ 'hold',
51
+ 'keyDown',
52
+ 'keyUp',
53
+ ]
54
+ // Options any action may carry beside its one type key.
55
+ export const ACTION_OPTIONS = ['optional', 'viewports', 'force', 'timeout']
56
+ const FORCE_TYPES = ['click', 'tap', 'hover', 'fill']
57
+ // A wait may always last 30 s (the old cap); longer up to the page's timeout.
58
+ const WAIT_FLOOR_MS = 30000
59
+ const EXPRESSION_MAX = 2000
60
+ const ACTIONS_MAX = 30
61
+ const LOCAL_STORAGE_MAX = 50
62
+ const LOCAL_STORAGE_VALUE_MAX = 20000
63
+ export const TIMEOUT_MAX = 300000
64
+ export const REDUCED_MOTION = ['reduce', 'no-preference']
65
+ const BLOCK_MAX = 50
66
+ const BLOCK_PATTERN_MAX = 300
67
+ export const JOURNEY_NAME_MAX = 120
68
+ export const JOURNEY_DESCRIPTION_MAX = 500
69
+ export const JOURNEY_STEPS_MAX = 50
70
+ export const VERSIONS_DEFAULT = 5
71
+ export const VERSIONS_MAX = 50
72
+ const ENVIRONMENTS_MAX = 8
73
+ // owner/name, as GitHub allows them.
74
+ export const GITHUB_REPO_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/
75
+ const GITHUB_LABELS_MAX = 10
76
+ export const SITEMAP_LIMIT_DEFAULT = 100
77
+ export const SITEMAP_LIMIT_MAX = 1000
78
+
79
+ export class ConfigError extends Error {
80
+ constructor(problems, file) {
81
+ super(`${file ? `${file}: ` : ''}invalid config\n${problems.map((problem) => ` - ${problem}`).join('\n')}`)
82
+ this.problems = problems
83
+ }
84
+ }
85
+
86
+ function isHttpUrl(value) {
87
+ try {
88
+ return ['http:', 'https:'].includes(new URL(value).protocol)
89
+ } catch {
90
+ return false
91
+ }
92
+ }
93
+
94
+ const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
95
+ const text = (value, max) => (typeof value === 'string' ? value.trim().slice(0, max) : '')
96
+ const keyName = (value) => typeof value === 'string' && value.trim() && value.length <= 50
97
+
98
+ // The device a viewport emulates. A built-in name, or a name that starts with
99
+ // one ("phone-landscape", "tablet-wide"), is that device; any other name is a
100
+ // desktop unless it sets "mobile": true. "mobile", "touch" and "userAgent" on
101
+ // the viewport win over what the name implies.
102
+ export function viewportDevice(name, spec = {}) {
103
+ const prefix = VIEWPORT_NAMES.find((kind) => name === kind || String(name).startsWith(`${kind}-`))
104
+ const small = Math.min(Number(spec.width) || 0, Number(spec.height) || 0) < 600
105
+ const kind = prefix || (spec.mobile ? (small ? 'phone' : 'tablet') : 'desktop')
106
+ const mobile = typeof spec.mobile === 'boolean' ? spec.mobile : kind !== 'desktop'
107
+ const touch = typeof spec.touch === 'boolean' ? spec.touch : mobile
108
+ const uaKind = kind === 'desktop' ? (small ? 'phone' : 'tablet') : kind
109
+ const userAgent = spec.userAgent || (mobile ? (uaKind === 'phone' ? PHONE_USER_AGENT : TABLET_USER_AGENT) : null)
110
+ return { kind, mobile, touch, userAgent }
111
+ }
112
+
113
+ // Board frame and thumbnail scale for any viewport name.
114
+ export const frameScale = (name, spec) => FRAME_SCALE[name] ?? FRAME_SCALE[viewportDevice(name, spec).kind]
115
+ export const thumbScale = (name, spec) => THUMB_SCALE[name] ?? THUMB_SCALE[viewportDevice(name, spec).kind]
116
+
117
+ // The viewports of a board (a board may list its own); configs built by hand
118
+ // without them fall back to the top-level ones.
119
+ export const boardViewports = (config, board) => board?.viewports || config.viewports
120
+
121
+ // A page's frame for one viewport. A page's own frameHeight replaces the
122
+ // viewport's height for its shots and its board card; the browser window stays
123
+ // the viewport's (layoutHeight, else height), so the page lays out the same.
124
+ export function frameSize(size, page, viewportName) {
125
+ const height = page?.frameHeight?.[viewportName]
126
+ if (!size || !height || height === size.height) return size
127
+ return { ...size, height, layoutHeight: size.layoutHeight || size.height }
128
+ }
129
+
130
+ // Every auth.loginScript and auth.storageState path the config names (top
131
+ // level and per board): files that decide what capture runs and logs in as.
132
+ export function authFiles(config) {
133
+ const out = new Set()
134
+ for (const auth of [config?.auth, ...(config?.boards || []).map((board) => board?.auth)]) {
135
+ for (const key of ['loginScript', 'storageState']) if (typeof auth?.[key] === 'string' && auth[key]) out.add(auth[key])
136
+ }
137
+ return [...out]
138
+ }
139
+
140
+ // The auth a board captures with: its own, else the top-level one.
141
+ export const authFor = (config, board) => board?.auth || config.auth || { storageState: null, loginScript: null }
142
+
143
+ // Built-in request block lists, by keyword. "analytics": common analytics,
144
+ // tag manager and session-replay hosts, so captures do not count as visits.
145
+ // Bare host names match the host and its subdomains; anything with a "*" or
146
+ // a "/" matches the whole URL, "*" standing for any run of characters.
147
+ export const BLOCK_LISTS = {
148
+ analytics: [
149
+ 'google-analytics.com',
150
+ 'analytics.google.com',
151
+ 'googletagmanager.com',
152
+ 'stats.g.doubleclick.net',
153
+ 'plausible.io',
154
+ 'cloud.umami.is',
155
+ 'api-gateway.umami.dev',
156
+ 'static.cloudflareinsights.com',
157
+ '*/cdn-cgi/rum*',
158
+ 'cdn.segment.com',
159
+ 'api.segment.io',
160
+ 'hotjar.com',
161
+ 'hotjar.io',
162
+ 'clarity.ms',
163
+ 'mixpanel.com',
164
+ 'mxpnl.com',
165
+ 'amplitude.com',
166
+ 'i.posthog.com',
167
+ 'heapanalytics.com',
168
+ 'fullstory.com',
169
+ 'usefathom.com',
170
+ 'simpleanalyticscdn.com',
171
+ 'gc.zgo.at',
172
+ 'connect.facebook.net',
173
+ 'bat.bing.com',
174
+ 'snap.licdn.com',
175
+ 'static.ads-twitter.com',
176
+ 'analytics.tiktok.com',
177
+ 'js.hs-analytics.net',
178
+ ],
179
+ }
180
+
181
+ // A block list: URL patterns, and keywords from BLOCK_LISTS.
182
+ function validateBlock(raw, where, problems) {
183
+ if (raw === undefined || raw === null) return []
184
+ if (
185
+ !Array.isArray(raw) ||
186
+ raw.length > BLOCK_MAX ||
187
+ raw.some((item) => typeof item !== 'string' || !item.trim() || item.length > BLOCK_PATTERN_MAX || /\s/.test(item.trim()))
188
+ ) {
189
+ problems.push(
190
+ `${where}: up to ${BLOCK_MAX} URL patterns such as ["*/umami/*", "plausible.io"] or keywords (${Object.keys(BLOCK_LISTS).join(', ')})`,
191
+ )
192
+ return []
193
+ }
194
+ return [...new Set(raw.flatMap((item) => BLOCK_LISTS[item.trim()] || [item.trim()]))]
195
+ }
196
+
197
+ // "reduce" (the default: animations off), "no-preference", or a boolean.
198
+ function validateReducedMotion(raw, where, problems, fallback) {
199
+ if (raw === undefined || raw === null) return fallback
200
+ if (raw === true) return 'reduce'
201
+ if (raw === false) return 'no-preference'
202
+ if (REDUCED_MOTION.includes(raw)) return raw
203
+ problems.push(`${where}: "reduce", "no-preference", true or false (got ${JSON.stringify(raw)})`)
204
+ return fallback
205
+ }
206
+
207
+ // localStorage seeded before the page's own scripts run: { key: value }.
208
+ // Strings are stored as is; numbers, booleans, objects and arrays as JSON.
209
+ function validateLocalStorage(raw, where, problems) {
210
+ if (raw === undefined || raw === null) return null
211
+ if (!isObject(raw) || Object.keys(raw).length > LOCAL_STORAGE_MAX) {
212
+ problems.push(`${where}: an object of up to ${LOCAL_STORAGE_MAX} keys and values, such as { "tutorialSeen": "1" }`)
213
+ return null
214
+ }
215
+ const out = {}
216
+ for (const [key, value] of Object.entries(raw)) {
217
+ const stored = typeof value === 'string' ? value : value === undefined || value === null ? null : JSON.stringify(value)
218
+ if (!key || key.length > 200 || stored === null || stored.length > LOCAL_STORAGE_VALUE_MAX) {
219
+ problems.push(`${where}.${key}: a value up to ${LOCAL_STORAGE_VALUE_MAX} characters (strings as is, anything else as JSON)`)
220
+ continue
221
+ }
222
+ out[key] = stored
223
+ }
224
+ return Object.keys(out).length ? out : null
225
+ }
226
+
227
+ // `limits`: { viewportNames, waitMax } of the page (or setup) the action is on.
228
+ function validateAction(action, where, problems, limits = {}) {
229
+ if (!isObject(action)) {
230
+ problems.push(`${where}: an action is an object such as { "click": "button.menu" }`)
231
+ return null
232
+ }
233
+ const keys = Object.keys(action)
234
+ const types = keys.filter((key) => ACTION_TYPES.includes(key))
235
+ if (types.length !== 1) {
236
+ problems.push(`${where}: use exactly one of ${ACTION_TYPES.join(', ')}`)
237
+ return null
238
+ }
239
+ const type = types[0]
240
+ const before = problems.length
241
+ for (const key of keys) {
242
+ if (key !== type && !ACTION_OPTIONS.includes(key))
243
+ problems.push(`${where}.${key}: unknown action option (use one action key, plus ${ACTION_OPTIONS.join(', ')})`)
244
+ }
245
+ const options = {}
246
+ if (action.optional !== undefined) {
247
+ if (typeof action.optional !== 'boolean') problems.push(`${where}.optional: true or false`)
248
+ else if (action.optional) options.optional = true
249
+ }
250
+ if (action.force !== undefined) {
251
+ if (typeof action.force !== 'boolean') problems.push(`${where}.force: true or false`)
252
+ else if (action.force && !FORCE_TYPES.includes(type)) problems.push(`${where}.force: only for ${FORCE_TYPES.join(', ')}`)
253
+ else if (action.force) options.force = true
254
+ }
255
+ if (action.timeout !== undefined) {
256
+ if (!Number.isInteger(action.timeout) || action.timeout < 100 || action.timeout > TIMEOUT_MAX)
257
+ problems.push(`${where}.timeout: whole milliseconds from 100 to ${TIMEOUT_MAX}`)
258
+ else options.timeout = action.timeout
259
+ }
260
+ if (action.viewports !== undefined) {
261
+ const names = limits.viewportNames || []
262
+ if (!Array.isArray(action.viewports) || !action.viewports.length || action.viewports.some((name) => !names.includes(name)))
263
+ problems.push(`${where}.viewports: a non-empty subset of ${names.join(', ')}`)
264
+ else options.viewports = names.filter((name) => action.viewports.includes(name))
265
+ }
266
+ const waitMax = Math.max(WAIT_FLOOR_MS, limits.waitMax || 0)
267
+ const value = action[type]
268
+ let parsed = null
269
+ if (type === 'wait') {
270
+ if (!Number.isFinite(value) || value < 0 || value > waitMax)
271
+ problems.push(`${where}.wait: milliseconds from 0 to ${waitMax} (longer needs a longer page "timeout")`)
272
+ else parsed = { type, ms: value }
273
+ } else if (type === 'scrollTo') {
274
+ if (!Number.isFinite(value) || value < 0) problems.push(`${where}.scrollTo: a y position in CSS pixels`)
275
+ else parsed = { type, y: value }
276
+ } else if (type === 'fill') {
277
+ if (!Array.isArray(value) || value.length !== 2 || !value.every((item) => typeof item === 'string'))
278
+ problems.push(`${where}.fill: [selector, value]`)
279
+ else parsed = { type, selector: value[0], value: value[1] }
280
+ } else if (type === 'mouse') {
281
+ if (!Array.isArray(value) || value.length !== 2 || !value.every((item) => Number.isFinite(item) && item >= 0 && item <= 10000))
282
+ problems.push(`${where}.mouse: [x, y] in CSS pixels from the top left of the viewport`)
283
+ else parsed = { type, x: value[0], y: value[1] }
284
+ } else if (type === 'hold') {
285
+ if (
286
+ !Array.isArray(value) ||
287
+ value.length !== 2 ||
288
+ !keyName(value[0]) ||
289
+ !Number.isFinite(value[1]) ||
290
+ value[1] < 0 ||
291
+ value[1] > waitMax
292
+ )
293
+ problems.push(`${where}.hold: [key, milliseconds], such as ["ArrowLeft", 800], up to ${waitMax} ms`)
294
+ else parsed = { type, key: value[0], ms: value[1] }
295
+ } else if (type === 'waitForFunction') {
296
+ if (typeof value !== 'string' || !value.trim() || value.length > EXPRESSION_MAX)
297
+ problems.push(
298
+ `${where}.waitForFunction: a JavaScript expression up to ${EXPRESSION_MAX} characters, such as "window.game?.ready === true"`,
299
+ )
300
+ else parsed = { type, expression: value.trim() }
301
+ } else if (typeof value !== 'string' || !value.trim()) {
302
+ problems.push(`${where}.${type}: a non-empty string`)
303
+ } else if (['press', 'keyDown', 'keyUp'].includes(type)) {
304
+ parsed = { type, key: value }
305
+ } else parsed = { type, selector: value }
306
+ if (!parsed || problems.length > before) return null
307
+ return { ...parsed, ...options }
308
+ }
309
+
310
+ function validateActions(raw, where, problems, limits) {
311
+ if (raw === undefined) return []
312
+ if (!Array.isArray(raw) || raw.length > ACTIONS_MAX) {
313
+ problems.push(`${where}: an array of at most ${ACTIONS_MAX} actions`)
314
+ return []
315
+ }
316
+ return raw.map((action, index) => validateAction(action, `${where}[${index}]`, problems, limits)).filter(Boolean)
317
+ }
318
+
319
+ function validateTimeout(raw, where, problems) {
320
+ if (raw === undefined || raw === null) return null
321
+ if (!Number.isInteger(raw) || raw < 1000 || raw > TIMEOUT_MAX) {
322
+ problems.push(`${where}: whole milliseconds from 1000 to ${TIMEOUT_MAX}`)
323
+ return null
324
+ }
325
+ return raw
326
+ }
327
+
328
+ function validatePage(page, where, viewportNames, problems, { pageTimeout = 45000 } = {}) {
329
+ if (!isObject(page)) {
330
+ problems.push(`${where}: a page is an object with at least id and path`)
331
+ return null
332
+ }
333
+ const id = typeof page.id === 'string' ? page.id : ''
334
+ if (!ID_RE.test(id)) problems.push(`${where}.id: lowercase letters, digits and dashes (got ${JSON.stringify(page.id)})`)
335
+ const pagePath = typeof page.path === 'string' ? page.path : ''
336
+ if (!PAGE_PATH_RE.test(pagePath)) problems.push(`${where}.path: must start with "/" (got ${JSON.stringify(page.path)})`)
337
+ if (page.note !== undefined && typeof page.note !== 'string') problems.push(`${where}.note: a string`)
338
+ if (typeof page.note === 'string' && page.note.length > NOTE_MAX) problems.push(`${where}.note: at most ${NOTE_MAX} characters`)
339
+ if (page.waitFor !== undefined && (typeof page.waitFor !== 'string' || !page.waitFor.trim())) {
340
+ problems.push(`${where}.waitFor: a CSS selector string`)
341
+ }
342
+ // A page's own budget for loading, waiting and its actions.
343
+ const timeout = validateTimeout(page.timeout, `${where}.timeout`, problems)
344
+ const actions = validateActions(page.actions, `${where}.actions`, problems, { viewportNames, waitMax: timeout || pageTimeout })
345
+ const localStorage = validateLocalStorage(page.localStorage, `${where}.localStorage`, problems)
346
+ // An error page captured on purpose: "expectStatus": 404 or [404, 410].
347
+ let expectStatus = null
348
+ if (page.expectStatus !== undefined && page.expectStatus !== null) {
349
+ const list = Array.isArray(page.expectStatus) ? page.expectStatus : [page.expectStatus]
350
+ if (!list.length || list.length > 10 || list.some((code) => !Number.isInteger(code) || code < 100 || code > 599)) {
351
+ problems.push(`${where}.expectStatus: an HTTP status from 100 to 599, or a list of them (got ${JSON.stringify(page.expectStatus)})`)
352
+ } else {
353
+ expectStatus = [...new Set(list)]
354
+ }
355
+ }
356
+ let errorSelectors = null
357
+ if (page.errorSelectors !== undefined && page.errorSelectors !== null) {
358
+ if (
359
+ !Array.isArray(page.errorSelectors) ||
360
+ page.errorSelectors.length > 10 ||
361
+ page.errorSelectors.some((s) => typeof s !== 'string' || !s.trim() || s.length > 500)
362
+ ) {
363
+ problems.push(`${where}.errorSelectors: at most 10 non-empty CSS selectors, each at most 500 characters`)
364
+ } else errorSelectors = [...new Set(page.errorSelectors.map((s) => s.trim()))]
365
+ }
366
+ let seo = null
367
+ if (page.seo !== undefined && page.seo !== null) {
368
+ if (!isObject(page.seo) || typeof page.seo.indexable !== 'boolean' || Object.keys(page.seo).some((key) => key !== 'indexable'))
369
+ problems.push(`${where}.seo: an object with only a boolean indexable field`)
370
+ else seo = { indexable: page.seo.indexable }
371
+ }
372
+ let viewports = viewportNames
373
+ if (page.viewports !== undefined) {
374
+ if (!Array.isArray(page.viewports) || !page.viewports.length || page.viewports.some((name) => !viewportNames.includes(name))) {
375
+ problems.push(`${where}.viewports: a non-empty subset of ${viewportNames.join(', ')}`)
376
+ } else {
377
+ viewports = viewportNames.filter((name) => page.viewports.includes(name))
378
+ }
379
+ }
380
+ const frameHeight = validateFrameHeight(page.frameHeight, `${where}.frameHeight`, problems, viewportNames, viewports)
381
+ return {
382
+ id,
383
+ path: pagePath,
384
+ title: text(page.title, 120) || id,
385
+ group: text(page.group, 60) || 'Pages',
386
+ note: text(page.note, NOTE_MAX),
387
+ waitFor: typeof page.waitFor === 'string' ? page.waitFor.trim() : null,
388
+ actions,
389
+ viewports,
390
+ expectStatus,
391
+ errorSelectors,
392
+ seo,
393
+ ...(timeout ? { timeout } : {}),
394
+ ...(localStorage ? { localStorage } : {}),
395
+ ...(frameHeight ? { frameHeight } : {}),
396
+ }
397
+ }
398
+
399
+ // A page's own frame height: a number for every viewport of the page, or
400
+ // { viewportName: height }. Normalized to a map over the page's viewports
401
+ // (names the board has but this page skips are dropped). The browser window
402
+ // stays the viewport's: only the shot and its board card change height.
403
+ const FRAME_HEIGHT_RANGE = 'whole CSS pixels from 240 to 8000'
404
+ function validateFrameHeight(raw, where, problems, viewportNames, pageViewports) {
405
+ if (raw === undefined || raw === null) return null
406
+ const valid = (value) => Number.isInteger(value) && value >= 240 && value <= 8000
407
+ if (typeof raw === 'number') {
408
+ if (!valid(raw)) {
409
+ problems.push(`${where}: ${FRAME_HEIGHT_RANGE}, or { viewport: height }`)
410
+ return null
411
+ }
412
+ return Object.fromEntries(pageViewports.map((name) => [name, raw]))
413
+ }
414
+ if (!isObject(raw) || !Object.keys(raw).length) {
415
+ problems.push(`${where}: a height (${FRAME_HEIGHT_RANGE}) or { viewport: height }`)
416
+ return null
417
+ }
418
+ const out = {}
419
+ for (const [name, value] of Object.entries(raw)) {
420
+ if (!viewportNames.includes(name)) problems.push(`${where}.${name}: not a viewport of this board (${viewportNames.join(', ')})`)
421
+ else if (!valid(value)) problems.push(`${where}.${name}: ${FRAME_HEIGHT_RANGE}`)
422
+ else if (pageViewports.includes(name)) out[name] = value
423
+ }
424
+ return Object.keys(out).length ? out : null
425
+ }
426
+
427
+ // One viewport: { width, height } is the frame (and, by default, the browser
428
+ // window). Optional: layoutHeight (a shorter or taller window than the
429
+ // frame, e.g. lay out at 1440x900 but shoot 2200 px), mobile, touch, userAgent.
430
+ function validateViewport(value, where, problems) {
431
+ const width = Number(value?.width)
432
+ const height = Number(value?.height)
433
+ if (!Number.isInteger(width) || width < 240 || width > 3840 || !Number.isInteger(height) || height < 240 || height > 8000) {
434
+ problems.push(`${where}: { width: 240-3840, height: 240-8000 } in whole CSS pixels`)
435
+ return null
436
+ }
437
+ const out = { width, height }
438
+ if (value.layoutHeight !== undefined) {
439
+ const layoutHeight = Number(value.layoutHeight)
440
+ if (!Number.isInteger(layoutHeight) || layoutHeight < 240 || layoutHeight > 8000)
441
+ problems.push(`${where}.layoutHeight: the browser window height, 240-8000 whole CSS pixels`)
442
+ else if (layoutHeight !== height) out.layoutHeight = layoutHeight
443
+ }
444
+ for (const key of ['mobile', 'touch']) {
445
+ if (value[key] === undefined) continue
446
+ if (typeof value[key] !== 'boolean') problems.push(`${where}.${key}: true or false`)
447
+ else out[key] = value[key]
448
+ }
449
+ if (value.userAgent !== undefined) {
450
+ // No control characters in a header value.
451
+ const control = typeof value.userAgent === 'string' && [...value.userAgent].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127)
452
+ if (typeof value.userAgent !== 'string' || !value.userAgent.trim() || value.userAgent.length > 400 || control)
453
+ problems.push(`${where}.userAgent: a user agent string up to 400 characters`)
454
+ else out.userAgent = value.userAgent.trim()
455
+ }
456
+ return out
457
+ }
458
+
459
+ function validateViewportMap(raw, where, problems) {
460
+ const out = {}
461
+ for (const [name, value] of Object.entries(raw)) {
462
+ if (!VIEWPORT_NAME_RE.test(name)) {
463
+ problems.push(
464
+ `${where}.${name}: a viewport name is lowercase letters, digits and dashes, starting with a letter (such as "phone-landscape")`,
465
+ )
466
+ continue
467
+ }
468
+ const spec = validateViewport(value, `${where}.${name}`, problems)
469
+ if (spec) out[name] = spec
470
+ }
471
+ if (Object.keys(raw).length > VIEWPORTS_MAX) problems.push(`${where}: at most ${VIEWPORTS_MAX} viewports`)
472
+ return out
473
+ }
474
+
475
+ function validateViewports(raw, problems) {
476
+ if (raw === undefined) return structuredClone(DEFAULT_VIEWPORTS)
477
+ if (!isObject(raw) || !Object.keys(raw).length) {
478
+ problems.push(`viewports: an object keyed by viewport name (${VIEWPORT_NAMES.join(', ')} or your own)`)
479
+ return structuredClone(DEFAULT_VIEWPORTS)
480
+ }
481
+ const out = validateViewportMap(raw, 'viewports', problems)
482
+ return Object.keys(out).length ? out : structuredClone(DEFAULT_VIEWPORTS)
483
+ }
484
+
485
+ // A board's viewports: a list of top-level viewport names (a subset, in the
486
+ // board's order), or an object of its own viewports. Default: the top level's.
487
+ function validateBoardViewports(raw, where, top, problems) {
488
+ if (raw === undefined || raw === null) return top
489
+ if (Array.isArray(raw)) {
490
+ if (!raw.length || raw.some((name) => typeof name !== 'string' || !Object.hasOwn(top, name))) {
491
+ problems.push(
492
+ `${where}: a non-empty list of top-level viewport names (${Object.keys(top).join(', ')}), or an object of the board's own viewports`,
493
+ )
494
+ return top
495
+ }
496
+ return Object.fromEntries([...new Set(raw)].map((name) => [name, top[name]]))
497
+ }
498
+ if (!isObject(raw) || !Object.keys(raw).length) {
499
+ problems.push(`${where}: a list of top-level viewport names, or an object of the board's own viewports`)
500
+ return top
501
+ }
502
+ const out = validateViewportMap(raw, where, problems)
503
+ return Object.keys(out).length ? out : top
504
+ }
505
+
506
+ // Board auth: like the top-level auth, for this board only. null turns the
507
+ // top-level auth off for the board.
508
+ // Is `target` the folder `dir` or inside it? Symlinks are resolved where the
509
+ // paths exist, so a link out of (or into) the project is judged by where it leads.
510
+ function insideDir(dir, target) {
511
+ const real = (value) => {
512
+ let current = path.resolve(value)
513
+ const rest = []
514
+ for (;;) {
515
+ try {
516
+ return path.join(fs.realpathSync(current), ...rest.reverse())
517
+ } catch {
518
+ const parent = path.dirname(current)
519
+ if (parent === current) return path.resolve(value)
520
+ rest.push(path.basename(current))
521
+ current = parent
522
+ }
523
+ }
524
+ }
525
+ const check = (a, b) => {
526
+ const relative = path.relative(a, b)
527
+ return relative === '' || (relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative))
528
+ }
529
+ return check(path.resolve(dir), path.resolve(target)) || check(real(dir), real(target))
530
+ }
531
+
532
+ function validateAuth(raw, where, dir, problems) {
533
+ const auth = { storageState: null, loginScript: null }
534
+ if (raw === undefined || raw === null) return auth
535
+ if (!isObject(raw)) {
536
+ problems.push(`${where}: an object with storageState and/or loginScript`)
537
+ return auth
538
+ }
539
+ for (const key of ['storageState', 'loginScript']) {
540
+ if (raw[key] === undefined || raw[key] === null) continue
541
+ if (typeof raw[key] !== 'string' || !raw[key].trim()) problems.push(`${where}.${key}: a file path`)
542
+ else auth[key] = path.resolve(dir, raw[key])
543
+ }
544
+ return auth
545
+ }
546
+
547
+ // Setup: actions run once per viewport before the board's pages (a guest
548
+ // entry, a dismissed tutorial). The browser state they leave (cookies,
549
+ // localStorage, IndexedDB) is what each page in scope starts from; pages still
550
+ // load their own path. An array of actions, or { path, actions, groups, pages, timeout }.
551
+ function validateSetup(raw, where, pages, viewportNames, pageTimeout, problems) {
552
+ if (raw === undefined || raw === null) return null
553
+ const value = Array.isArray(raw) ? { actions: raw } : raw
554
+ if (!isObject(value)) {
555
+ problems.push(`${where}: an array of actions, or { "path": "/", "actions": [...], "groups"?: [...], "pages"?: [...] }`)
556
+ return null
557
+ }
558
+ const before = problems.length
559
+ for (const key of Object.keys(value)) {
560
+ if (!['path', 'actions', 'groups', 'pages', 'timeout'].includes(key))
561
+ problems.push(`${where}.${key}: unknown setup setting (use path, actions, groups, pages, timeout)`)
562
+ }
563
+ const setupPath = value.path ?? '/'
564
+ if (typeof setupPath !== 'string' || !PAGE_PATH_RE.test(setupPath))
565
+ problems.push(`${where}.path: must start with "/" (got ${JSON.stringify(value.path)})`)
566
+ const timeout = validateTimeout(value.timeout, `${where}.timeout`, problems)
567
+ const actionsWhere = Array.isArray(raw) ? where : `${where}.actions`
568
+ if (!Array.isArray(value.actions) || !value.actions.length) problems.push(`${actionsWhere}: list at least one action`)
569
+ const actions = validateActions(value.actions ?? [], actionsWhere, problems, { viewportNames, waitMax: timeout || pageTimeout })
570
+ const scope = {}
571
+ const groupNames = new Set(pages.map((page) => page.group))
572
+ const pageIds = new Set(pages.map((page) => page.id))
573
+ for (const [key, known] of [
574
+ ['groups', groupNames],
575
+ ['pages', pageIds],
576
+ ]) {
577
+ if (value[key] === undefined) continue
578
+ if (!Array.isArray(value[key]) || !value[key].length || value[key].some((item) => typeof item !== 'string' || !known.has(item.trim())))
579
+ problems.push(`${where}.${key}: a non-empty list of ${key === 'groups' ? 'group names' : 'page ids'} on this board`)
580
+ else scope[key] = [...new Set(value[key].map((item) => item.trim()))]
581
+ }
582
+ if (problems.length > before) return null
583
+ return { path: setupPath, actions, ...scope, ...(timeout ? { timeout } : {}) }
584
+ }
585
+
586
+ // Whether a page starts from the board's setup state: every page, unless the
587
+ // setup lists groups and/or pages (then a page in either).
588
+ export function inSetupScope(setup, page) {
589
+ if (!setup) return false
590
+ if (!setup.groups && !setup.pages) return true
591
+ return Boolean(setup.groups?.includes(page.group) || setup.pages?.includes(page.id))
592
+ }
593
+
594
+ // A journey: a named, ordered list of page ids on one board, which may fork
595
+ // into named branches (src/journey-paths.js). Used for the
596
+ // config and for journeys made on the board (src/journeys.js). Pushes one
597
+ // message per problem, each prefixed with `where`; returns null if any.
598
+ export function checkJourney(raw, pageIds, where, problems) {
599
+ if (!isObject(raw)) {
600
+ problems.push(`${where}: a journey is an object with id, name and steps`)
601
+ return null
602
+ }
603
+ const before = problems.length
604
+ const id = typeof raw.id === 'string' ? raw.id : ''
605
+ if (!ID_RE.test(id)) problems.push(`${where}.id: lowercase letters, digits and dashes (got ${JSON.stringify(raw.id)})`)
606
+ const name = typeof raw.name === 'string' ? raw.name.replace(/\s+/g, ' ').trim() : ''
607
+ if (!name || name.length > JOURNEY_NAME_MAX) problems.push(`${where}.name: 1 to ${JOURNEY_NAME_MAX} characters`)
608
+ if (raw.description !== undefined && raw.description !== null && typeof raw.description !== 'string') {
609
+ problems.push(`${where}.description: a string`)
610
+ }
611
+ const description = typeof raw.description === 'string' ? raw.description.trim() : ''
612
+ if (description.length > JOURNEY_DESCRIPTION_MAX) problems.push(`${where}.description: at most ${JOURNEY_DESCRIPTION_MAX} characters`)
613
+ const steps = checkSteps(raw.steps, pageIds, `${where}.steps`, problems, { stepsMax: JOURNEY_STEPS_MAX })
614
+ if (problems.length > before) return null
615
+ return { id, name, description, steps }
616
+ }
617
+
618
+ function validateJourneys(raw, pages, where, problems) {
619
+ if (raw === undefined) return []
620
+ if (!Array.isArray(raw)) {
621
+ problems.push(`${where}: an array of { id, name, steps }`)
622
+ return []
623
+ }
624
+ const pageIds = new Set(pages.map((page) => page.id))
625
+ const journeys = raw.map((item, index) => checkJourney(item, pageIds, `${where}[${index}]`, problems)).filter(Boolean)
626
+ const seen = new Set()
627
+ for (const journey of journeys) {
628
+ if (seen.has(journey.id)) problems.push(`${where}: duplicate journey id "${journey.id}"`)
629
+ seen.add(journey.id)
630
+ }
631
+ return journeys
632
+ }
633
+
634
+ // Environments: the same pages at other base URLs (staging, production). The
635
+ // first one is the board's default: plain `shapewall capture` captures it,
636
+ // and comments are made on it.
637
+ function validateEnvironments(raw, where, problems) {
638
+ if (!Array.isArray(raw) || !raw.length || raw.length > ENVIRONMENTS_MAX) {
639
+ problems.push(`${where}: 1 to ${ENVIRONMENTS_MAX} environments, each { id, baseUrl }`)
640
+ return []
641
+ }
642
+ const out = []
643
+ raw.forEach((env, index) => {
644
+ const at = `${where}[${index}]`
645
+ if (!isObject(env)) {
646
+ problems.push(`${at}: an object with id and baseUrl`)
647
+ return
648
+ }
649
+ const id = typeof env.id === 'string' ? env.id : ''
650
+ if (!ID_RE.test(id)) problems.push(`${at}.id: lowercase letters, digits and dashes (got ${JSON.stringify(env.id)})`)
651
+ if (!isHttpUrl(env.baseUrl)) problems.push(`${at}.baseUrl: an http(s) URL (got ${JSON.stringify(env.baseUrl)})`)
652
+ const publicUrl = env.publicUrl ?? null
653
+ if (publicUrl !== null && !isHttpUrl(publicUrl)) problems.push(`${at}.publicUrl: an http(s) URL`)
654
+ if (out.some((item) => item.id === id)) problems.push(`${where}: duplicate environment id "${id}"`)
655
+ out.push({ id, title: text(env.title, 60) || id, baseUrl: env.baseUrl, publicUrl })
656
+ })
657
+ return out
658
+ }
659
+
660
+ // Where `shapewall sitemap` reads pages from when no source is given:
661
+ // "https://example.com/sitemap.xml", a file path (relative to the config),
662
+ // or { source, limit?, group?, exclude? }.
663
+ export function validateSitemap(value, where, dir, problems) {
664
+ if (value === undefined || value === null) return null
665
+ const raw = typeof value === 'string' ? { source: value } : value
666
+ if (!isObject(raw) || typeof raw.source !== 'string' || !raw.source.trim()) {
667
+ problems.push(`${where}: a sitemap URL or file, or { "source": ..., "limit"?, "group"?, "exclude"? }`)
668
+ return null
669
+ }
670
+ const source = raw.source.trim()
671
+ const http = /^https?:\/\//i.test(source)
672
+ if (http && !isHttpUrl(source)) problems.push(`${where}.source: an http(s) URL or a file path`)
673
+ const limit = raw.limit ?? null
674
+ if (limit !== null && (!Number.isInteger(limit) || limit < 1 || limit > SITEMAP_LIMIT_MAX)) {
675
+ problems.push(`${where}.limit: a whole number from 1 to ${SITEMAP_LIMIT_MAX}`)
676
+ }
677
+ if (raw.group !== undefined && (typeof raw.group !== 'string' || !raw.group.trim())) problems.push(`${where}.group: a group name`)
678
+ const exclude = raw.exclude ?? []
679
+ if (!Array.isArray(exclude) || exclude.some((item) => typeof item !== 'string' || !item.startsWith('/'))) {
680
+ problems.push(`${where}.exclude: path prefixes such as ["/tag/", "/author/"]`)
681
+ }
682
+ return {
683
+ source: http ? source : path.resolve(dir, source),
684
+ limit,
685
+ group: typeof raw.group === 'string' ? text(raw.group, 60) || null : null,
686
+ exclude: Array.isArray(exclude) ? exclude.filter((item) => typeof item === 'string') : [],
687
+ }
688
+ }
689
+
690
+ function validateBoard(raw, where, defaults, problems) {
691
+ const id = typeof raw.id === 'string' ? raw.id : ''
692
+ if (!ID_RE.test(id)) problems.push(`${where}.id: lowercase letters, digits and dashes (got ${JSON.stringify(raw.id)})`)
693
+ const at = where === 'config' ? '' : `${where}.`
694
+ let baseUrl = raw.baseUrl ?? defaults.baseUrl
695
+ let publicUrl = raw.publicUrl ?? defaults.publicUrl ?? null
696
+ let environments
697
+ const ownEnvironments = raw.environments !== undefined
698
+ if (ownEnvironments || defaults.environments !== undefined) {
699
+ environments = validateEnvironments(
700
+ ownEnvironments ? raw.environments : defaults.environments,
701
+ ownEnvironments ? `${at}environments` : 'environments',
702
+ problems,
703
+ )
704
+ // The first environment is the default; a different baseUrl beside it is ambiguous.
705
+ const ownBase = ownEnvironments ? raw.baseUrl : baseUrl
706
+ if (environments.length && ownBase !== undefined && ownBase !== environments[0].baseUrl) {
707
+ problems.push(`${at}baseUrl: with environments, leave baseUrl out (the first environment is the default)`)
708
+ }
709
+ if (environments.length) {
710
+ baseUrl = environments[0].baseUrl
711
+ publicUrl = environments[0].publicUrl ?? (ownEnvironments ? (raw.publicUrl ?? null) : publicUrl)
712
+ }
713
+ } else {
714
+ if (!isHttpUrl(baseUrl)) problems.push(`${at}baseUrl: an http(s) URL (got ${JSON.stringify(baseUrl)})`)
715
+ if (publicUrl !== null && !isHttpUrl(publicUrl)) problems.push(`${at}publicUrl: an http(s) URL`)
716
+ environments = [{ id: 'default', title: 'Default', baseUrl, publicUrl }]
717
+ }
718
+ // A single-board config's top-level keys are the board's; only boards[] entries override.
719
+ const own = where !== 'config'
720
+ const viewports = own ? validateBoardViewports(raw.viewports, `${where}.viewports`, defaults.viewports, problems) : defaults.viewports
721
+ const viewportNames = Object.keys(viewports)
722
+ const pageTimeout = defaults.pageTimeout ?? 45000
723
+ const pagesWhere = where === 'config' ? 'pages' : `${where}.pages`
724
+ if (!Array.isArray(raw.pages) || !raw.pages.length) problems.push(`${pagesWhere}: list at least one page`)
725
+ const pages = (Array.isArray(raw.pages) ? raw.pages : [])
726
+ .map((page, index) => validatePage(page, `${pagesWhere}[${index}]`, viewportNames, problems, { pageTimeout }))
727
+ .filter(Boolean)
728
+ const seen = new Set()
729
+ for (const page of pages) {
730
+ if (seen.has(page.id)) problems.push(`${pagesWhere}: duplicate page id "${page.id}"`)
731
+ seen.add(page.id)
732
+ }
733
+ const groups = Array.isArray(raw.groups) ? raw.groups.filter((group) => typeof group === 'string').map((group) => group.trim()) : []
734
+ const journeys = validateJourneys(raw.journeys, pages, `${at}journeys`, problems)
735
+ const sitemap = validateSitemap(raw.sitemap, `${at}sitemap`, defaults.dir, problems)
736
+ // Capture settings a board may set for itself (top-level values are the defaults).
737
+ const block = own ? [...new Set([...(defaults.block || []), ...validateBlock(raw.block, `${at}block`, problems)])] : defaults.block || []
738
+ const reducedMotion = own
739
+ ? validateReducedMotion(raw.reducedMotion, `${at}reducedMotion`, problems, defaults.reducedMotion || 'reduce')
740
+ : defaults.reducedMotion || 'reduce'
741
+ // Only a board that sets auth carries its own; the others use the top level's (authFor).
742
+ const auth = own && raw.auth !== undefined ? validateAuth(raw.auth, `${at}auth`, defaults.dir, problems) : null
743
+ const boardStorage = validateLocalStorage(raw.localStorage, `${at}localStorage`, problems)
744
+ const localStorage = defaults.localStorage || boardStorage ? { ...defaults.localStorage, ...boardStorage } : null
745
+ const setup = validateSetup(raw.setup, `${at}setup`, pages, viewportNames, pageTimeout, problems)
746
+ return {
747
+ id,
748
+ title: text(raw.title, 120) || id,
749
+ baseUrl,
750
+ publicUrl,
751
+ environments,
752
+ groups: [...new Set([...groups, ...pages.map((page) => page.group)])],
753
+ pages,
754
+ journeys,
755
+ sitemap,
756
+ viewports,
757
+ ...(auth ? { auth } : {}),
758
+ block,
759
+ reducedMotion,
760
+ ...(localStorage ? { localStorage } : {}),
761
+ ...(setup ? { setup } : {}),
762
+ }
763
+ }
764
+
765
+ // `github`: the repository issues go to and pull requests come from, and
766
+ // where the board is served (for links back to a comment). The token and
767
+ // the webhook secret come from the environment only, never from this file,
768
+ // so they cannot end up in a commit or an export.
769
+ function validateGithub(raw, problems) {
770
+ if (raw === undefined || raw === null) return null
771
+ if (!isObject(raw)) {
772
+ problems.push('github: an object such as { "repo": "owner/name" }')
773
+ return null
774
+ }
775
+ for (const key of ['token', 'webhookSecret', 'secret']) {
776
+ if (raw[key] !== undefined) {
777
+ problems.push(
778
+ `github.${key}: never put secrets in the config; set GITHUB_TOKEN or SHAPEWALL_GITHUB_TOKEN (and SHAPEWALL_GITHUB_WEBHOOK_SECRET) in the environment`,
779
+ )
780
+ }
781
+ }
782
+ const repo = typeof raw.repo === 'string' ? raw.repo.trim() : ''
783
+ if (raw.repo !== undefined && !GITHUB_REPO_RE.test(repo)) problems.push(`github.repo: "owner/name" (got ${JSON.stringify(raw.repo)})`)
784
+ let boardUrl = null
785
+ if (raw.boardUrl !== undefined) {
786
+ if (!isHttpUrl(raw.boardUrl)) problems.push('github.boardUrl: an http(s) URL where the board is served')
787
+ else boardUrl = raw.boardUrl
788
+ }
789
+ let apiUrl = null
790
+ if (raw.apiUrl !== undefined) {
791
+ if (!isHttpUrl(raw.apiUrl)) problems.push('github.apiUrl: an http(s) URL (GitHub Enterprise: https://HOST/api/v3)')
792
+ else apiUrl = raw.apiUrl
793
+ }
794
+ let labels = []
795
+ if (raw.labels !== undefined) {
796
+ if (
797
+ !Array.isArray(raw.labels) ||
798
+ raw.labels.length > GITHUB_LABELS_MAX ||
799
+ raw.labels.some((label) => typeof label !== 'string' || !label.trim() || label.length > 50)
800
+ ) {
801
+ problems.push(`github.labels: up to ${GITHUB_LABELS_MAX} label names`)
802
+ } else labels = raw.labels.map((label) => label.trim())
803
+ }
804
+ let board = null
805
+ if (raw.board !== undefined) {
806
+ if (typeof raw.board !== 'string' || !ID_RE.test(raw.board)) problems.push('github.board: a board id')
807
+ else board = raw.board
808
+ }
809
+ return { repo: repo || null, boardUrl, apiUrl, labels, board }
810
+ }
811
+
812
+ // Validates a parsed config object. `dir` resolves relative paths.
813
+ // `env` is read only to find channels set up by environment alone; secret
814
+ // values never enter the config object.
815
+ export function normalizeConfig(raw, { dir = process.cwd(), file = null, env = process.env } = {}) {
816
+ const problems = []
817
+ if (!isObject(raw)) throw new ConfigError(['the config must be a JSON object'], file)
818
+ const viewports = validateViewports(raw.viewports, problems)
819
+ const concurrency = raw.concurrency ?? 2
820
+ if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 8) problems.push('concurrency: a whole number from 1 to 8')
821
+ const capturePacing = { ...CAPTURE_PACING_DEFAULTS }
822
+ if (raw.capturePacing !== undefined) {
823
+ if (!isObject(raw.capturePacing)) problems.push('capturePacing: an object with intervalMs and rateLimitCooldownMs')
824
+ else {
825
+ for (const [key, value] of Object.entries(raw.capturePacing)) {
826
+ if (!Object.hasOwn(CAPTURE_PACING_DEFAULTS, key)) problems.push(`capturePacing.${key}: unknown pacing setting`)
827
+ else if (!Number.isInteger(value) || value < 0 || value > CAPTURE_PACING_MAX[key])
828
+ problems.push(`capturePacing.${key}: whole milliseconds from 0 to ${CAPTURE_PACING_MAX[key]}`)
829
+ else capturePacing[key] = value
830
+ }
831
+ }
832
+ }
833
+ let checks
834
+ if (raw.checks !== undefined) {
835
+ if (!isObject(raw.checks)) problems.push('checks: an object with optional budgets and seo')
836
+ else {
837
+ for (const key of Object.keys(raw.checks))
838
+ if (!['budgets', 'seo'].includes(key)) problems.push(`checks.${key}: unknown checks setting`)
839
+ checks = { budgets: normalizeBudgets(raw.checks.budgets, problems) }
840
+ // SEO by default for `shapewall checks run` and the board's Run checks:
841
+ // true (every page not marked private) or a list of page ids.
842
+ const seo = raw.checks.seo
843
+ if (seo !== undefined) {
844
+ if (typeof seo === 'boolean') checks.seo = seo
845
+ else if (Array.isArray(seo) && seo.length <= 500 && seo.every((id) => typeof id === 'string' && ID_RE.test(id)))
846
+ checks.seo = [...new Set(seo)]
847
+ else problems.push('checks.seo: true, false or a list of page ids')
848
+ }
849
+ }
850
+ }
851
+ const timeouts = { page: 45000, settle: 8000, ...(isObject(raw.timeouts) ? raw.timeouts : {}) }
852
+ for (const key of ['page', 'settle']) {
853
+ if (!Number.isFinite(timeouts[key]) || timeouts[key] < 0 || timeouts[key] > 300000)
854
+ problems.push(`timeouts.${key}: milliseconds up to 300000`)
855
+ }
856
+ const auth = validateAuth(raw.auth, 'auth', dir, problems)
857
+ const block = validateBlock(raw.block, 'block', problems)
858
+ const reducedMotion = validateReducedMotion(raw.reducedMotion, 'reducedMotion', problems, 'reduce')
859
+ const localStorage = raw.boards !== undefined ? validateLocalStorage(raw.localStorage, 'localStorage', problems) : null
860
+ const browser = { channel: null, executablePath: null }
861
+ if (isObject(raw.browser)) {
862
+ if (typeof raw.browser.channel === 'string') browser.channel = raw.browser.channel
863
+ if (typeof raw.browser.executablePath === 'string') {
864
+ // A browser inside the project folder is a program the repo ships: a
865
+ // committed config must not make capture (or doctor) run it. A system
866
+ // path stays fine; SHAPEWALL_BROWSER_PATH is the person's own override.
867
+ const executable = path.resolve(dir, raw.browser.executablePath)
868
+ if (insideDir(dir, executable))
869
+ problems.push(
870
+ 'browser.executablePath: a browser inside the project folder is refused (a config must not name a program the repo ships); use an absolute path to an installed browser, browser.channel, or set SHAPEWALL_BROWSER_PATH yourself',
871
+ )
872
+ else browser.executablePath = executable
873
+ }
874
+ }
875
+ const outputDir = path.resolve(dir, typeof raw.outputDir === 'string' && raw.outputDir.trim() ? raw.outputDir : '.shapewall')
876
+ const versions = raw.versions ?? VERSIONS_DEFAULT
877
+ if (!Number.isInteger(versions) || versions < 0 || versions > VERSIONS_MAX) {
878
+ problems.push(`versions: previous captures kept per page and viewport, a whole number from 0 to ${VERSIONS_MAX}`)
879
+ }
880
+ // Where people open the board, for links in notifications and GitHub issues.
881
+ let boardUrl = null
882
+ if (raw.boardUrl !== undefined && raw.boardUrl !== null) {
883
+ if (!isHttpUrl(raw.boardUrl)) problems.push('boardUrl: the http(s) URL people open the board at')
884
+ else boardUrl = raw.boardUrl
885
+ }
886
+ const defaults = {
887
+ baseUrl: raw.baseUrl,
888
+ publicUrl: raw.publicUrl,
889
+ environments: raw.environments,
890
+ viewports,
891
+ dir,
892
+ pageTimeout: Number.isFinite(timeouts.page) ? timeouts.page : 45000,
893
+ auth,
894
+ block,
895
+ reducedMotion,
896
+ localStorage,
897
+ }
898
+
899
+ let boards
900
+ if (raw.boards !== undefined) {
901
+ if (!Array.isArray(raw.boards) || !raw.boards.length) {
902
+ problems.push('boards: a non-empty array (or leave it out and list pages at the top level)')
903
+ boards = []
904
+ } else {
905
+ boards = raw.boards
906
+ .map((board, index) =>
907
+ isObject(board)
908
+ ? validateBoard(board, `boards[${index}]`, defaults, problems)
909
+ : (problems.push(`boards[${index}]: an object`), null),
910
+ )
911
+ .filter(Boolean)
912
+ }
913
+ if (raw.pages !== undefined) problems.push('pages: use either top-level pages or boards, not both')
914
+ if (raw.journeys !== undefined) problems.push('journeys: with boards, list journeys inside each board')
915
+ if (raw.sitemap !== undefined) problems.push('sitemap: with boards, set sitemap inside each board')
916
+ if (raw.setup !== undefined) problems.push('setup: with boards, set setup inside each board')
917
+ } else {
918
+ const single = {
919
+ id: raw.id ?? 'site',
920
+ title: raw.title,
921
+ groups: raw.groups,
922
+ pages: raw.pages,
923
+ journeys: raw.journeys,
924
+ sitemap: raw.sitemap,
925
+ environments: raw.environments,
926
+ baseUrl: raw.baseUrl,
927
+ setup: raw.setup,
928
+ localStorage: raw.localStorage,
929
+ }
930
+ boards = [validateBoard(single, 'config', { ...defaults, environments: undefined }, problems)]
931
+ }
932
+ const ids = new Set()
933
+ for (const board of boards) {
934
+ if (ids.has(board.id)) problems.push(`boards: duplicate board id "${board.id}"`)
935
+ ids.add(board.id)
936
+ }
937
+ const notifications = normalizeNotifications(raw.notifications, { boardIds: [...ids], env }, problems)
938
+ const github = validateGithub(raw.github, problems)
939
+ if (github?.board && !ids.has(github.board)) problems.push(`github.board: no board "${github.board}"`)
940
+ const agent = validateAgent(raw.agent, problems)
941
+ const starterAgent = validateStarterAgent(raw.starterAgent, problems, { boardIds: [...ids] })
942
+ if (problems.length) throw new ConfigError(problems, file)
943
+ return {
944
+ file,
945
+ dir,
946
+ title: text(raw.title, 120) || 'Shapewall',
947
+ boardUrl,
948
+ outputDir,
949
+ viewports,
950
+ concurrency,
951
+ capturePacing,
952
+ ...(checks ? { checks } : {}),
953
+ timeouts,
954
+ auth,
955
+ block,
956
+ reducedMotion,
957
+ browser,
958
+ liveHtml: raw.liveHtml !== false,
959
+ versions,
960
+ github,
961
+ agent,
962
+ starterAgent,
963
+ boards,
964
+ notifications,
965
+ }
966
+ }
967
+
968
+ export function findConfigFile(explicit, cwd = process.cwd()) {
969
+ if (explicit) return path.resolve(cwd, explicit)
970
+ if (process.env.SHAPEWALL_CONFIG) return path.resolve(cwd, process.env.SHAPEWALL_CONFIG)
971
+ return path.resolve(cwd, CONFIG_FILE)
972
+ }
973
+
974
+ export function loadConfig(explicit, { cwd = process.cwd() } = {}) {
975
+ const file = findConfigFile(explicit, cwd)
976
+ let textValue
977
+ try {
978
+ textValue = fs.readFileSync(file, 'utf8')
979
+ } catch (error) {
980
+ if (error.code === 'ENOENT') throw new Error(`No config at ${file}. Run "${cliCommand('init')}" to create one.`, { cause: error })
981
+ throw error
982
+ }
983
+ let raw
984
+ try {
985
+ raw = JSON.parse(textValue)
986
+ } catch (error) {
987
+ throw new ConfigError([`not valid JSON: ${error.message}`], file)
988
+ }
989
+ return normalizeConfig(raw, { dir: path.dirname(file), file })
990
+ }
991
+
992
+ // An environment of a board by id; no id is the default (first) one.
993
+ export function getEnvironment(board, envId) {
994
+ if (!envId) return board.environments[0]
995
+ const env = board.environments.find((item) => item.id === envId)
996
+ if (!env) {
997
+ throw new Error(`No environment "${envId}" on board "${board.id}" (have: ${board.environments.map((item) => item.id).join(', ')})`)
998
+ }
999
+ return env
1000
+ }
1001
+
1002
+ export function getBoard(config, boardId) {
1003
+ if (!boardId) return config.boards[0]
1004
+ const board = config.boards.find((item) => item.id === boardId)
1005
+ if (!board) throw new Error(`No board "${boardId}" in the config (have: ${config.boards.map((item) => item.id).join(', ')})`)
1006
+ return board
1007
+ }
1008
+
1009
+ // Page paths are relative to the base URL, which may carry a base path
1010
+ // (http://127.0.0.1:3000/app): no doubled or dropped slashes. A page path may
1011
+ // carry a query; the base's own query and hash are dropped.
1012
+ export function joinUrl(base, pagePath) {
1013
+ const url = new URL(base)
1014
+ const [pathPart, query = ''] = String(pagePath || '/').split(/\?(.*)/s)
1015
+ const prefix = url.pathname.replace(/\/+$/, '')
1016
+ url.pathname = `${prefix}/${pathPart.replace(/^\/+/, '')}`
1017
+ url.search = query ? `?${query}` : ''
1018
+ url.hash = ''
1019
+ return url.toString()
1020
+ }
1021
+
1022
+ // Finds pages by id or by path (both accepted by --only).
1023
+ export function selectPages(board, only) {
1024
+ if (!only || !only.length) return board.pages
1025
+ const wanted = new Set(only)
1026
+ const pages = board.pages.filter((page) => wanted.has(page.id) || wanted.has(page.path))
1027
+ const found = new Set(pages.flatMap((page) => [page.id, page.path]))
1028
+ const missing = only.filter((item) => !found.has(item))
1029
+ if (missing.length) throw new Error(`No page matches ${missing.map((item) => JSON.stringify(item)).join(', ')} on board "${board.id}"`)
1030
+ return pages
1031
+ }
1032
+
1033
+ // A board title from a base URL: the domain ("example.com" for
1034
+ // https://www.example.com/app). An IP address or localhost says nothing
1035
+ // about the site, so those keep the generic title.
1036
+ export function titleFromBaseUrl(baseUrl) {
1037
+ let host
1038
+ try {
1039
+ host = new URL(baseUrl).hostname.toLowerCase().replace(/^\[|\]$/g, '')
1040
+ } catch {
1041
+ return null
1042
+ }
1043
+ if (!host || isIP(host) || host === 'localhost' || host.endsWith('.localhost')) return null
1044
+ return host.replace(/^www\./, '').slice(0, 120)
1045
+ }
1046
+
1047
+ export function starterConfig({ baseUrl = 'http://localhost:3000' } = {}) {
1048
+ return {
1049
+ title: titleFromBaseUrl(baseUrl) || 'My site',
1050
+ baseUrl,
1051
+ outputDir: '.shapewall',
1052
+ concurrency: 2,
1053
+ viewports: structuredClone(DEFAULT_VIEWPORTS),
1054
+ groups: ['Marketing', 'App'],
1055
+ pages: [
1056
+ { id: 'home', path: '/', title: 'Home', group: 'Marketing' },
1057
+ { id: 'pricing', path: '/pricing', title: 'Pricing', group: 'Marketing' },
1058
+ { id: 'login', path: '/login', title: 'Sign in', group: 'App', note: 'Signed-out state' },
1059
+ ],
1060
+ }
1061
+ }