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,208 @@
1
+ // `shapewall comments add`, `comments get` and `comments --since`: what a
2
+ // shell-only agent or a chat bot needs besides list, reply and status.
3
+ //
4
+ // add goes through the same store function the board uses (validation,
5
+ // events, mentions, capture version). Without --selector the pin sits near
6
+ // the page's top-left corner; with one, it is anchored to that element, and
7
+ // the element's text is read from the latest capture's live HTML when the
8
+ // selector finds exactly one element there.
9
+
10
+ import fs from 'node:fs'
11
+ import { parse } from 'parse5'
12
+ import { feedbackContext, feedbackItem, formatFeedbackItem, formatFeedbackItemForAgent, untrustedJson } from './feedback.js'
13
+ import { ANCHOR_TEXT_MAX, CommentError, createComment, getComment, resolveFile } from './store.js'
14
+ import { boardViewports } from './config.js'
15
+
16
+ // Who a comment, reply or status change is from when --author is not given.
17
+ // "agent", like reply and status: the starter agent never acts on an agent's
18
+ // own comment, so text a bot relays waits for a trusted person (docs/starter-agent.md).
19
+ export const CLI_AUTHOR = 'agent'
20
+ // Where a pin without --selector sits: near the top-left corner, in percent of the page.
21
+ export const DEFAULT_PIN = { x: 2, y: 2 }
22
+
23
+ export const authorFlag = (flags) => (typeof flags.author === 'string' && flags.author.trim() ? flags.author : CLI_AUTHOR)
24
+
25
+ // --since: a comment id (newer comments) or a time (comments created or
26
+ // changed after it). Returns a filter for feedback items or store comments.
27
+ export function sinceFilter(value) {
28
+ if (value === undefined) return null
29
+ const text = String(value).trim()
30
+ if (/^[0-9]+$/.test(text)) {
31
+ const id = Number(text)
32
+ return (comment) => comment.id > id
33
+ }
34
+ const time = /^\d{4}-\d{2}-\d{2}/.test(text) ? Date.parse(text) : NaN
35
+ if (!Number.isFinite(time)) throw new Error('--since needs a comment id (e.g. 12) or an ISO time (e.g. 2026-11-05T18:00:00Z)')
36
+ // updatedAt moves with every change (a reply, a status), so it covers "created after" too.
37
+ return (comment) => Date.parse(comment.updatedAt || comment.createdAt || '') > time
38
+ }
39
+
40
+ // ---- Anchor text from the live HTML ---------------------------------------------
41
+ // The anchor grammar (store.js ANCHOR_SELECTOR_RE): steps `#id`,
42
+ // `tag[data-testid="..."]`, `tag[aria-label="..."]`, `tag:nth-of-type(n)`,
43
+ // joined by ` > `. The first step may match anywhere, the rest are children.
44
+
45
+ const IDENT_CHAR = /[A-Za-z0-9_\u0080-￿-]/
46
+
47
+ function parseSteps(selector) {
48
+ const steps = []
49
+ let index = 0
50
+ const fail = () => {
51
+ throw new Error('not an anchor selector')
52
+ }
53
+ while (index < selector.length) {
54
+ if (selector[index] === '#') {
55
+ let id = ''
56
+ index += 1
57
+ while (index < selector.length) {
58
+ const char = selector[index]
59
+ if (char === '\\') {
60
+ const hex = /^[0-9a-fA-F]{1,6} ?/.exec(selector.slice(index + 1))
61
+ if (hex) {
62
+ id += String.fromCodePoint(parseInt(hex[0].trim(), 16))
63
+ index += 1 + hex[0].length
64
+ } else {
65
+ id += selector[index + 1] ?? ''
66
+ index += 2
67
+ }
68
+ } else if (IDENT_CHAR.test(char)) {
69
+ id += char
70
+ index += 1
71
+ } else break
72
+ }
73
+ if (!id) fail()
74
+ steps.push({ id })
75
+ } else {
76
+ const tag = /^[a-z][a-z0-9-]{0,40}/.exec(selector.slice(index))
77
+ if (!tag) fail()
78
+ index += tag[0].length
79
+ const rest = selector.slice(index)
80
+ const nth = /^:nth-of-type\(([1-9][0-9]{0,4})\)/.exec(rest)
81
+ const attr = /^\[(data-testid|aria-label)="((?:[^"\\\n]|\\.){0,200})"\]/.exec(rest)
82
+ if (nth) {
83
+ steps.push({ tag: tag[0], nth: Number(nth[1]) })
84
+ index += nth[0].length
85
+ } else if (attr) {
86
+ steps.push({ tag: tag[0], attr: attr[1], value: attr[2].replace(/\\(.)/g, '$1') })
87
+ index += attr[0].length
88
+ } else fail()
89
+ }
90
+ if (index < selector.length) {
91
+ if (selector.slice(index, index + 3) !== ' > ') fail()
92
+ index += 3
93
+ }
94
+ }
95
+ return steps
96
+ }
97
+
98
+ const elementsOf = (node) => (node.childNodes || []).filter((child) => child.tagName)
99
+ const attrOf = (node, name) => node.attrs?.find((item) => item.name === name)?.value
100
+
101
+ function matches(node, step, parent) {
102
+ if (step.id !== undefined) return attrOf(node, 'id') === step.id
103
+ if (node.tagName !== step.tag) return false
104
+ if (step.attr) return attrOf(node, step.attr) === step.value
105
+ const same = elementsOf(parent).filter((item) => item.tagName === step.tag)
106
+ return same.indexOf(node) + 1 === step.nth
107
+ }
108
+
109
+ function textOf(node) {
110
+ let text = ''
111
+ const walk = (item) => {
112
+ if (item.nodeName === '#text') text += item.value
113
+ else if (!['style', 'script', 'template'].includes(item.tagName)) for (const child of item.childNodes || []) walk(child)
114
+ }
115
+ walk(node)
116
+ const value = text.replace(/\s+/g, ' ').trim() || attrOf(node, 'aria-label') || attrOf(node, 'alt') || attrOf(node, 'placeholder') || ''
117
+ return value.replace(/\s+/g, ' ').trim()
118
+ }
119
+
120
+ // The text of the one element `selector` finds in `html`; null when it finds
121
+ // none or several.
122
+ export function anchorText(html, selector) {
123
+ let steps
124
+ try {
125
+ steps = parseSteps(selector)
126
+ } catch {
127
+ return null
128
+ }
129
+ const root = parse(html)
130
+ let found = []
131
+ const walk = (node) => {
132
+ for (const child of elementsOf(node)) {
133
+ if (matches(child, steps[0], node)) found.push(child)
134
+ walk(child)
135
+ }
136
+ }
137
+ walk(root)
138
+ for (const step of steps.slice(1)) {
139
+ found = found.flatMap((node) => elementsOf(node).filter((child) => matches(child, step, node)))
140
+ }
141
+ if (found.length !== 1) return null
142
+ const text = textOf(found[0])
143
+ return text.length > ANCHOR_TEXT_MAX ? `${text.slice(0, ANCHOR_TEXT_MAX - 3).trimEnd()}...` : text
144
+ }
145
+
146
+ // ---- Commands -------------------------------------------------------------------
147
+
148
+ const print = (out, flags, value, text) => out(flags.json ? JSON.stringify(value, null, 2) : text)
149
+
150
+ // `comments add --page ID --body TEXT [--viewport NAME] [--selector CSS] [--author NAME]`
151
+ export async function addComment(config, board, flags, out, err = () => {}) {
152
+ const pageId = typeof flags.page === 'string' ? flags.page.trim() : ''
153
+ const body = typeof flags.body === 'string' ? flags.body : ''
154
+ if (!pageId || !body.trim())
155
+ throw new Error('usage: shapewall comments add --page ID --body TEXT [--viewport NAME] [--selector CSS] [--author NAME]')
156
+ const page = board.pages.find((item) => item.id === pageId)
157
+ if (!page && !pageId.startsWith('variant:')) {
158
+ throw new Error(`No page "${pageId}" on board "${board.id}" (have: ${board.pages.map((item) => item.id).join(', ')})`)
159
+ }
160
+ const viewport =
161
+ typeof flags.viewport === 'string' ? flags.viewport : page ? page.viewports[0] : Object.keys(boardViewports(config, board))[0]
162
+ let anchor
163
+ if (flags.selector !== undefined) {
164
+ const selector = String(flags.selector).trim()
165
+ let text = ''
166
+ const live = page ? resolveFile(config, board.id, 'captures', `${page.id}.${viewport}.html`) : null
167
+ if (live) {
168
+ const found = anchorText(fs.readFileSync(live, 'utf8'), selector)
169
+ if (found === null)
170
+ err(`note: "${selector}" does not find exactly one element in the latest ${viewport} capture; saved the selector anyway`)
171
+ else text = found
172
+ }
173
+ // The pin sits in the middle of the element.
174
+ anchor = { selector, text, dx: 0.5, dy: 0.5 }
175
+ }
176
+ let comment
177
+ try {
178
+ comment = await createComment(config, board, { pageId, viewport, ...DEFAULT_PIN, body, author: authorFlag(flags), anchor })
179
+ } catch (error) {
180
+ if (error instanceof CommentError && error.code === 'invalid_anchor') {
181
+ throw new Error(
182
+ `${error.message} Use the selector a comment shows (comments --json, element.selector): steps like #id, ` +
183
+ 'button[data-testid="save"], nav[aria-label="Main"] or div:nth-of-type(2), joined by " > ".',
184
+ { cause: error },
185
+ )
186
+ }
187
+ throw error
188
+ }
189
+ const item = feedbackItem(feedbackContext(config, board), comment)
190
+ print(
191
+ out,
192
+ flags,
193
+ { board: board.id, comment: item },
194
+ `Added #${item.id} on ${item.page?.title || pageId} (${viewport}) as ${item.author}`,
195
+ )
196
+ return item
197
+ }
198
+
199
+ // `comments get ID [--json] [--for-agent]` (also `comments show ID`). Both
200
+ // say the comment is untrusted (src/feedback.js).
201
+ export function showComment(config, board, positional, flags, out) {
202
+ const id = positional[1]
203
+ if (!id) throw new Error('usage: shapewall comments get ID [--json] [--for-agent]')
204
+ const item = feedbackItem(feedbackContext(config, board), getComment(config, board.id, id))
205
+ if (flags['for-agent']) out(formatFeedbackItemForAgent(item, board.id))
206
+ else print(out, flags, untrustedJson({ board: board.id, comment: item }), formatFeedbackItem(item).join('\n'))
207
+ return item
208
+ }
@@ -0,0 +1,100 @@
1
+ // `serve` picks up edits to shapewall.config.json without a restart: the
2
+ // title, boards (pages, groups, journeys, environments, sitemap) and the
3
+ // capture settings. The server reads `config` on every request, so the new
4
+ // values are swapped into the same object. Anything that changes who or
5
+ // what the server talks to (agent, notifications, GitHub, auth, output
6
+ // folder) still needs a restart, and the log says so.
7
+ //
8
+ // The folder is watched, not the file: editors save by writing a new file
9
+ // and renaming it over the old one, which a watch on the file would miss.
10
+
11
+ import fs from 'node:fs'
12
+ import path from 'node:path'
13
+ import { loadConfig } from './config.js'
14
+
15
+ export const RELOADED_KEYS = [
16
+ 'title',
17
+ 'boards',
18
+ 'viewports',
19
+ 'concurrency',
20
+ 'capturePacing',
21
+ 'timeouts',
22
+ 'versions',
23
+ 'block',
24
+ 'reducedMotion',
25
+ ]
26
+ const RESTART_KEYS = ['outputDir', 'boardUrl', 'auth', 'browser', 'liveHtml', 'agent', 'starterAgent', 'notifications', 'github']
27
+ const DEBOUNCE_MS = 150
28
+
29
+ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b)
30
+
31
+ // Reads the config file again and applies what can change live. Returns
32
+ // { applied, restart } (key names), or { error } with the config untouched.
33
+ export function reloadConfig(config, { load = loadConfig } = {}) {
34
+ let next
35
+ try {
36
+ next = load(config.file)
37
+ } catch (error) {
38
+ return { error }
39
+ }
40
+ const applied = RELOADED_KEYS.filter((key) => !same(config[key], next[key]))
41
+ const restart = RESTART_KEYS.filter((key) => !same(config[key], next[key]))
42
+ for (const key of applied) config[key] = next[key]
43
+ return { applied, restart }
44
+ }
45
+
46
+ // Starts watching; returns stop(). `log` gets one line per reload.
47
+ export function watchConfig(config, { log = () => {}, server = null } = {}) {
48
+ if (!config.file) return () => {}
49
+ const name = path.basename(config.file)
50
+ let last = readText(config.file)
51
+ let timer = null
52
+ let watcher
53
+ const check = () => {
54
+ timer = null
55
+ const text = readText(config.file)
56
+ if (text === null || text === last) return
57
+ last = text
58
+ const result = reloadConfig(config)
59
+ if (result.error) {
60
+ log(`Config not reloaded (the board keeps the last good one): ${oneLine(result.error)}`)
61
+ return
62
+ }
63
+ if (result.applied.length) log(`Config reloaded: ${result.applied.join(', ')}. Refresh the board to see it.`)
64
+ if (result.restart.length) log(`Config: restart serve to apply ${result.restart.join(', ')}.`)
65
+ }
66
+ try {
67
+ watcher = fs.watch(path.dirname(config.file), (event, file) => {
68
+ if (file && file !== name) return
69
+ clearTimeout(timer)
70
+ timer = setTimeout(check, DEBOUNCE_MS)
71
+ })
72
+ watcher.on('error', () => stop())
73
+ watcher.unref()
74
+ } catch {
75
+ return () => {}
76
+ }
77
+ function stop() {
78
+ clearTimeout(timer)
79
+ watcher?.close()
80
+ watcher = null
81
+ }
82
+ server?.once('close', stop)
83
+ return stop
84
+ }
85
+
86
+ function readText(file) {
87
+ try {
88
+ return fs.readFileSync(file, 'utf8')
89
+ } catch {
90
+ return null
91
+ }
92
+ }
93
+
94
+ function oneLine(error) {
95
+ return String(error?.message || error)
96
+ .split('\n')
97
+ .map((line) => line.trim())
98
+ .filter(Boolean)
99
+ .join('; ')
100
+ }