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/tokens.js ADDED
@@ -0,0 +1,11 @@
1
+ // Comparing a secret from a request with the expected one in constant time.
2
+ // Both sides are hashed first, so the comparison never depends on (or
3
+ // reveals) the length of either. A missing or empty value never matches.
4
+
5
+ import { createHash, timingSafeEqual } from 'node:crypto'
6
+
7
+ export function tokenEquals(given, expected) {
8
+ if (typeof expected !== 'string' || !expected || typeof given !== 'string' || !given) return false
9
+ const digest = (value) => createHash('sha256').update(value).digest()
10
+ return timingSafeEqual(digest(given), digest(expected))
11
+ }
@@ -0,0 +1,245 @@
1
+ // Installation updates are an explicit operator capability. Shapewall never
2
+ // downloads or executes an updater unless its installer provides a helper.
3
+ import fs from 'node:fs'
4
+ import path from 'node:path'
5
+ import { fileURLToPath } from 'node:url'
6
+ import { spawn } from 'node:child_process'
7
+ import express from 'express'
8
+ import { sameOriginWrite, settingsRefusal, settingsTokenOk } from '../agent/settings-routes.js'
9
+ import { createRateLimiter } from '../hosted/ratelimit.js'
10
+ import { tokenEquals } from '../tokens.js'
11
+
12
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
13
+ const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'))
14
+ const MAX_OUTPUT = 65536
15
+ const VERSION = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,79}$/
16
+ const REVISION = /^[a-f0-9]{7,40}$/i
17
+ const MANUAL = 'Updates are managed by the person who installed Shapewall.'
18
+ const UPDATE_TOKEN_MIN = 32
19
+ const UPDATE_TOKEN_FAILS = { limit: 10, windowMs: 15 * 60_000 }
20
+
21
+ function revision(value) {
22
+ return typeof value === 'string' && REVISION.test(value) ? value.toLowerCase() : null
23
+ }
24
+
25
+ export function runningVersion(env = process.env) {
26
+ let metadata
27
+ for (const file of ['dist/client/build-info.json', 'build-info.json']) {
28
+ try {
29
+ metadata = JSON.parse(fs.readFileSync(path.join(ROOT, file), 'utf8'))
30
+ if (revision(metadata?.revision)) break
31
+ } catch {
32
+ metadata = null
33
+ }
34
+ }
35
+ return { version: PACKAGE.version, revision: revision(env.SHAPEWALL_BUILD_REVISION) || revision(metadata?.revision) }
36
+ }
37
+
38
+ function tokenOk(req, token) {
39
+ return tokenEquals(req.headers['x-shapewall-update-token'], token)
40
+ }
41
+
42
+ function executable(value) {
43
+ if (typeof value !== 'string' || !path.isAbsolute(value)) return null
44
+ try {
45
+ if (!fs.statSync(value).isFile()) return null
46
+ fs.accessSync(value, fs.constants.X_OK)
47
+ return value
48
+ } catch {
49
+ return null
50
+ }
51
+ }
52
+
53
+ function result(value) {
54
+ const latest = value?.latest
55
+ if (!latest || typeof latest.version !== 'string' || !VERSION.test(latest.version) || typeof value.updateAvailable !== 'boolean')
56
+ throw new Error('Invalid updater response.')
57
+ if (latest.revision !== undefined && latest.revision !== null && !revision(latest.revision)) throw new Error('Invalid updater response.')
58
+ return {
59
+ latest: { version: latest.version, revision: revision(latest.revision) },
60
+ updateAvailable: value.updateAvailable,
61
+ restartRequired: value.restartRequired === true,
62
+ }
63
+ }
64
+
65
+ // One child per server. The installer must additionally serialize across
66
+ // processes and preserve rollback when replacing a running installation.
67
+ export function appUpdateRouter({
68
+ env = process.env,
69
+ settingsToken = null,
70
+ shared = false,
71
+ readOnly = false,
72
+ appUpdate = {},
73
+ children,
74
+ } = {}) {
75
+ // The proxy capability can replace app code: a guessable one is refused at startup.
76
+ const updateToken = env.SHAPEWALL_UPDATE_TOKEN || null
77
+ if (updateToken !== null && updateToken.length < UPDATE_TOKEN_MIN) {
78
+ throw new Error(
79
+ `SHAPEWALL_UPDATE_TOKEN must be at least ${UPDATE_TOKEN_MIN} characters (it has ${updateToken.length}). Generate one with "openssl rand -base64 32".`,
80
+ )
81
+ }
82
+ const router = express.Router()
83
+ // Wrong update tokens are counted per address; past the limit, requests
84
+ // carrying a wrong one are refused before any check (GET status says too,
85
+ // through canUpdate). The right token always passes: behind the update
86
+ // proxy every caller shares one address, so wrong guesses must not lock
87
+ // out the token's holder.
88
+ const limiter = createRateLimiter()
89
+ const failKey = (req) => req.socket?.remoteAddress || 'unknown'
90
+ const presented = (req) => req.headers['x-shapewall-update-token'] !== undefined
91
+ const tokenLimited = (req, res) => {
92
+ if (!presented(req) || tokenOk(req, updateToken)) return false
93
+ const { ok, retryAfter } = limiter.peek('updateTokenFail', failKey(req), UPDATE_TOKEN_FAILS)
94
+ if (ok) return false
95
+ res.setHeader('Retry-After', String(retryAfter))
96
+ fail(res, 429, 'update_rate_limited', 'Too many wrong update tokens. Try again later.')
97
+ return true
98
+ }
99
+ const countFailure = (req) => {
100
+ if (presented(req) && !tokenOk(req, updateToken)) limiter.hit('updateTokenFail', failKey(req), UPDATE_TOKEN_FAILS)
101
+ }
102
+ const current = runningVersion(env)
103
+ const helper = executable(appUpdate.helper ?? env.SHAPEWALL_UPDATE_HELPER)
104
+ let latest = null
105
+ let updateAvailable = false
106
+ let checkedAt = null
107
+ let job = null
108
+ let restartPending = false
109
+ const authorized = (req) => tokenOk(req, updateToken) || (settingsTokenOk(req, settingsToken) && !settingsRefusal(req, { shared }))
110
+ const status = (req) => ({
111
+ current,
112
+ latest,
113
+ updateAvailable,
114
+ supported: Boolean(helper),
115
+ canUpdate: Boolean(helper) && !readOnly && authorized(req),
116
+ reason: !helper
117
+ ? MANUAL
118
+ : readOnly
119
+ ? 'This board is read-only.'
120
+ : !authorized(req)
121
+ ? 'Open the owner link on this machine to manage updates.'
122
+ : null,
123
+ checkedAt,
124
+ job,
125
+ })
126
+ const fail = (res, code, name, message) => res.status(code).json({ error: { code: name, message } })
127
+
128
+ function run(action) {
129
+ if (action === 'check') {
130
+ checkedAt = null
131
+ updateAvailable = false
132
+ }
133
+ const active = { action, state: 'running', startedAt: new Date().toISOString(), finishedAt: null, error: null }
134
+ job = active
135
+ let child
136
+ let timer
137
+ let output = ''
138
+ let bytes = 0
139
+ let settled = false
140
+ let aborted = null
141
+ const finish = (error = null, value = null) => {
142
+ if (settled) return
143
+ settled = true
144
+ clearTimeout(timer)
145
+ children?.delete(child)
146
+ active.finishedAt = new Date().toISOString()
147
+ active.state = error ? 'failed' : 'succeeded'
148
+ active.error = error
149
+ if (value) {
150
+ latest = value.latest
151
+ updateAvailable = value.updateAvailable
152
+ if (action === 'check') checkedAt = active.finishedAt
153
+ if (action === 'apply' && value.restartRequired && typeof appUpdate.onRestart === 'function') {
154
+ restartPending = true
155
+ const delay = appUpdate.restartDelayMs
156
+ const restartTimer = setTimeout(
157
+ () => {
158
+ try {
159
+ appUpdate.onRestart()
160
+ } catch {
161
+ restartPending = false
162
+ active.state = 'failed'
163
+ active.error = 'Shapewall could not restart. Contact the installer.'
164
+ }
165
+ },
166
+ Number.isFinite(delay) && delay >= 0 ? Math.min(delay, 1500) : 1500,
167
+ )
168
+ restartTimer.unref?.()
169
+ }
170
+ }
171
+ }
172
+ try {
173
+ // No shell or request-derived arguments/environment. The helper needs
174
+ // the actual running artifact, since a previous attempt may already
175
+ // have switched its pointer without completing the process restart.
176
+ child = spawn(helper, [action], {
177
+ shell: false,
178
+ stdio: ['ignore', 'pipe', 'ignore'],
179
+ env: { ...env, SHAPEWALL_RUNNING_REVISION: current.revision || '' },
180
+ })
181
+ children?.add(child)
182
+ const timeout = action === 'check' ? 30000 : 900000
183
+ const configured = appUpdate[`${action}TimeoutMs`]
184
+ timer = setTimeout(
185
+ () => {
186
+ aborted = 'The update helper timed out. Check the installation before trying again.'
187
+ child.kill('SIGKILL')
188
+ },
189
+ Number.isFinite(configured) && configured > 0 ? Math.min(configured, timeout) : timeout,
190
+ )
191
+ timer.unref?.()
192
+ child.stdout.on('data', (chunk) => {
193
+ if (aborted) return
194
+ bytes += chunk.length
195
+ if (bytes > MAX_OUTPUT) {
196
+ aborted = 'The update helper returned too much output.'
197
+ child.kill('SIGKILL')
198
+ } else output += chunk.toString('utf8')
199
+ })
200
+ child.once('error', () => finish('The update helper could not start. Contact the installer.'))
201
+ child.once('close', (code) => {
202
+ if (settled) return
203
+ if (aborted) return finish(aborted)
204
+ if (code !== 0) return finish('The update helper failed. Check the installation before trying again.')
205
+ try {
206
+ finish(null, result(JSON.parse(output)))
207
+ } catch {
208
+ finish('The update helper returned an invalid response.')
209
+ }
210
+ })
211
+ } catch {
212
+ finish('The update helper could not start. Contact the installer.')
213
+ }
214
+ }
215
+
216
+ router.use((req, res, next) => {
217
+ res.setHeader('Cache-Control', 'no-store')
218
+ next()
219
+ })
220
+ router.get('/', (req, res) => {
221
+ if (tokenLimited(req, res)) return
222
+ countFailure(req)
223
+ res.json(status(req))
224
+ })
225
+ for (const action of ['check', 'apply']) {
226
+ router.post(`/${action}`, (req, res) => {
227
+ if (tokenLimited(req, res)) return
228
+ if (!authorized(req)) {
229
+ countFailure(req)
230
+ return fail(res, 403, 'update_forbidden', 'Only the installation owner can manage updates.')
231
+ }
232
+ if (!sameOriginWrite(req)) return fail(res, 403, 'update_origin', 'Manage updates from this board.')
233
+ if (readOnly) return fail(res, 403, 'read_only', 'This board is read-only.')
234
+ if (!req.body || typeof req.body !== 'object' || Array.isArray(req.body) || Object.keys(req.body).length)
235
+ return fail(res, 400, 'invalid_update_request', 'Send an empty JSON object.')
236
+ if (!helper) return fail(res, 503, 'update_unsupported', MANUAL)
237
+ if (job?.state === 'running' || restartPending) return fail(res, 409, 'update_busy', 'An update operation is already running.')
238
+ if (action === 'apply' && (!checkedAt || !updateAvailable))
239
+ return fail(res, 409, 'update_not_available', 'Check for an available update first.')
240
+ run(action)
241
+ res.status(202).json(status(req))
242
+ })
243
+ }
244
+ return router
245
+ }
package/src/watch.js ADDED
@@ -0,0 +1,403 @@
1
+ // `shapewall watch`: hands each new open comment to a coding agent.
2
+ //
3
+ // The watcher looks at comments.json (fs.watch on the board folder, plus a
4
+ // poll in case fs events are missed, debounced) and, for every open comment
5
+ // that no agent has taken yet (agentStatus null):
6
+ //
7
+ // - claims it: agentStatus null -> queued, a compare-and-set under the
8
+ // comments file lock, so a comment is handed out once even across restarts
9
+ // or with several watchers;
10
+ // - then either prints it as one JSON line (the default, for piping into an
11
+ // agent) or runs the configured command with the comment JSON on stdin,
12
+ // marking it working while the command runs and done (exit 0) or
13
+ // needs-human (anything else) afterwards, unless the agent set a status
14
+ // itself.
15
+ //
16
+ // With claim: false (`watch --no-claim`) it only looks: every open comment
17
+ // is printed or run once per process (again when it is reopened), and no
18
+ // agent status, reply or lock is ever written, so it can run beside a
19
+ // claiming watcher or the starter agent (a chat bot relaying comments).
20
+ //
21
+ // One claiming watcher per board holds <board>/watch.lock (same pid +
22
+ // start-time lock as captures). The command is the user's own: it is split into argv and
23
+ // spawned without a shell, and comment text only ever reaches it as data
24
+ // (stdin, a JSON file), never as part of a command line.
25
+
26
+ import fs from 'node:fs'
27
+ import path from 'node:path'
28
+ import { spawn } from 'node:child_process'
29
+ import { recaptureComment } from './agent/feedback-loop.js'
30
+ import { getBoard } from './config.js'
31
+ import { feedbackContext, feedbackItem } from './feedback.js'
32
+ import { acquireLock, readLock, releaseLock } from './lock.js'
33
+ import { addReply, boardDir, getComment, listComments, setAgentStatus } from './store.js'
34
+ import { absoluteProgram } from './which.js'
35
+
36
+ const KILL_GRACE_MS = 5000
37
+
38
+ // Splits a command string into argv, like a shell would for plain words and
39
+ // quotes, but without one: no variables, globs, pipes or redirects. Those
40
+ // belong in a script the command points at.
41
+ export function splitCommand(command, flag = '--exec') {
42
+ const args = []
43
+ let current = ''
44
+ let quote = null
45
+ let started = false
46
+ const value = String(command || '')
47
+ for (let index = 0; index < value.length; index += 1) {
48
+ const char = value[index]
49
+ if (quote === "'") {
50
+ if (char === "'") quote = null
51
+ else current += char
52
+ } else if (quote === '"') {
53
+ if (char === '"') quote = null
54
+ else if (char === '\\' && index + 1 < value.length && '"\\$`'.includes(value[index + 1])) current += value[++index]
55
+ else if (char === '$' || char === '`') throw new Error(`${flag} runs one program without a shell: no $ or \` (use a script)`)
56
+ else current += char
57
+ } else if (char === "'" || char === '"') {
58
+ quote = char
59
+ started = true
60
+ } else if (char === '\\' && index + 1 < value.length) {
61
+ current += value[++index]
62
+ started = true
63
+ } else if (/\s/.test(char)) {
64
+ if (started) args.push(current)
65
+ current = ''
66
+ started = false
67
+ } else if ('|&;<>$`()'.includes(char)) {
68
+ throw new Error(`${flag} runs one program without a shell, so "${char}" is not allowed unquoted (put pipes and the like in a script)`)
69
+ } else {
70
+ current += char
71
+ started = true
72
+ }
73
+ }
74
+ if (quote) throw new Error(`${flag} has an unclosed quote`)
75
+ if (started) args.push(current)
76
+ if (!args.length) throw new Error(`${flag} needs a command`)
77
+ return args
78
+ }
79
+
80
+ // The program path, or null when it is not on PATH. A bare name is looked
81
+ // up on absolute PATH entries only (which.js): a relative entry would let a
82
+ // program in the project folder decide what runs.
83
+ export function findProgram(name, env = process.env) {
84
+ if (!(name.includes('/') || name.includes(path.sep))) return absoluteProgram(name, env)
85
+ const candidates = [path.resolve(name)]
86
+ for (const file of candidates) {
87
+ try {
88
+ fs.accessSync(file, fs.constants.X_OK)
89
+ if (fs.statSync(file).isFile()) return file
90
+ } catch {
91
+ /* next */
92
+ }
93
+ }
94
+ return null
95
+ }
96
+
97
+ // Environment for the agent command: everything about the comment except
98
+ // its text, which comes on stdin and in SHAPEWALL_COMMENT_FILE.
99
+ export function commentEnv(config, board, item, commentFile) {
100
+ return {
101
+ SHAPEWALL_COMMENT_ID: String(item.id),
102
+ SHAPEWALL_BOARD: board.id,
103
+ SHAPEWALL_PAGE_ID: item.page?.id || item.variant?.pageId || '',
104
+ SHAPEWALL_VARIANT_ID: item.variant?.id || '',
105
+ SHAPEWALL_PAGE_URL: item.page?.url || '',
106
+ SHAPEWALL_VIEWPORT: item.viewport.name,
107
+ SHAPEWALL_SCREENSHOT: item.files.screenshot || '',
108
+ SHAPEWALL_LIVE_HTML: item.files.liveHtml || '',
109
+ // The page as it is now, when it was captured again since the comment.
110
+ SHAPEWALL_LATEST_SCREENSHOT: item.files.latestScreenshot || '',
111
+ SHAPEWALL_COMMENT_FILE: commentFile,
112
+ SHAPEWALL_CONFIG: config.file || '',
113
+ }
114
+ }
115
+
116
+ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref())
117
+
118
+ // Runs until `signal` aborts (or, with `once`, until the comments open right
119
+ // now are handed out and their commands have finished). Options:
120
+ // - exec: command string; without it each comment is printed with `out`
121
+ // - concurrency: commands at once (1 to 4)
122
+ // - newOnly: skip comments that already exist when the watcher starts
123
+ // - claim: false hands out without claiming (no status, no lock; see above)
124
+ // - mention: only comments that mention this handle ("agent"), so people can
125
+ // talk among themselves and tag the agent when a comment is ready for it
126
+ // - pollMs, debounceMs, timeoutMs (per command)
127
+ // - out(line): JSON lines; log(line): progress
128
+ export async function watchComments({
129
+ config,
130
+ boardId = null,
131
+ exec = null,
132
+ concurrency = 1,
133
+ newOnly = false,
134
+ once = false,
135
+ mention = null,
136
+ claim = true,
137
+ recapture = false,
138
+ capture = null,
139
+ pollMs = 2000,
140
+ debounceMs = 200,
141
+ timeoutMs = 60 * 60 * 1000,
142
+ signal = null,
143
+ out = (line) => process.stdout.write(`${line}\n`),
144
+ log = (line) => process.stderr.write(`${line}\n`),
145
+ env = process.env,
146
+ }) {
147
+ const board = getBoard(config, boardId)
148
+ if (recapture && (!exec || !claim)) throw new Error('--recapture needs --exec and cannot be used with --no-claim')
149
+ if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) throw new Error('--concurrency must be 1 to 4')
150
+ let argv = null
151
+ if (exec) {
152
+ argv = splitCommand(exec)
153
+ const program = findProgram(argv[0], env)
154
+ if (!program) throw new Error(`--exec: "${argv[0]}" is not an executable on PATH`)
155
+ argv[0] = program
156
+ }
157
+ const dir = boardDir(config, board.id)
158
+ const agentDir = path.join(dir, 'agent')
159
+ fs.mkdirSync(agentDir, { recursive: true })
160
+ const lockFile = path.join(dir, 'watch.lock')
161
+ if (claim && !acquireLock(lockFile)) {
162
+ const holder = readLock(lockFile)
163
+ throw new Error(`Another "shapewall watch" is running for board "${board.id}"${holder?.pid ? ` (pid ${holder.pid})` : ''}.`)
164
+ }
165
+
166
+ const running = new Map() // comment id -> { child, done }
167
+ // --no-claim: what this process handed out, as id:reopenCount (a reopen is new).
168
+ const handed = new Set()
169
+ const handedKey = (comment) => `${comment.id}:${comment.reopenCount || 0}`
170
+ // Every status the watcher sets says it was the watcher.
171
+ const setStatus = (id, value, options = {}) => setAgentStatus(config, board.id, id, value, { ...options, actor: 'shapewall' })
172
+ const baseline = newOnly ? Math.max(0, ...listComments(config, board.id).map((comment) => comment.id)) : 0
173
+ let stopped = false
174
+ let scanning = null
175
+ let again = false
176
+ let wake = null
177
+
178
+ const left = claim
179
+ ? listComments(config, board.id, { status: 'open' }).filter((comment) => ['queued', 'working'].includes(comment.agentStatus))
180
+ : []
181
+ if (left.length) {
182
+ log(
183
+ `${left.length} open comment${left.length === 1 ? ' is' : 's are'} already ${left.map((comment) => `#${comment.id} ${comment.agentStatus}`).join(', ')}; ` +
184
+ 'they are not handed out again. Clear one with "shapewall comments status ID clear".',
185
+ )
186
+ }
187
+
188
+ const runCommand = async (item) => {
189
+ const commentFile = path.join(agentDir, `comment-${item.id}.json`)
190
+ const logFile = path.join(agentDir, `comment-${item.id}.log`)
191
+ const json = JSON.stringify({ board: board.id, comment: item }, null, 2)
192
+ fs.writeFileSync(commentFile, `${json}\n`, { mode: 0o600 })
193
+ const began = Date.now()
194
+ const repliesBefore = (getComment(config, board.id, item.id).replies || []).length
195
+ const logFd = fs.openSync(logFile, 'w', 0o600)
196
+ let result
197
+ try {
198
+ if (claim) await setStatus(item.id, 'working')
199
+ log(`#${item.id} working: ${path.basename(argv[0])} (log ${path.relative(process.cwd(), logFile) || logFile})`)
200
+ result = await new Promise((resolve) => {
201
+ let child
202
+ try {
203
+ child = spawn(argv[0], argv.slice(1), {
204
+ cwd: config.dir,
205
+ env: { ...env, ...commentEnv(config, board, item, commentFile) },
206
+ stdio: ['pipe', logFd, logFd],
207
+ shell: false,
208
+ windowsHide: true,
209
+ })
210
+ } catch (error) {
211
+ resolve({ code: null, error })
212
+ return
213
+ }
214
+ const entry = running.get(item.id)
215
+ if (entry) entry.child = child
216
+ let killTimer = null
217
+ const timer = setTimeout(() => {
218
+ child.kill('SIGTERM')
219
+ killTimer = setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS)
220
+ }, timeoutMs)
221
+ child.stdin.on('error', () => {}) // a command that does not read stdin
222
+ child.stdin.end(json)
223
+ child.once('error', (error) => {
224
+ clearTimeout(timer)
225
+ clearTimeout(killTimer)
226
+ resolve({ code: null, error })
227
+ })
228
+ child.once('exit', (code, exitSignal) => {
229
+ clearTimeout(timer)
230
+ clearTimeout(killTimer)
231
+ resolve({ code, signal: exitSignal, timedOut: Date.now() - began >= timeoutMs })
232
+ })
233
+ })
234
+ } finally {
235
+ fs.closeSync(logFd)
236
+ }
237
+ const seconds = Math.round((Date.now() - began) / 1000)
238
+ if (!claim) {
239
+ const how = result.code === 0 ? 'exit 0' : result.error ? 'could not start' : `exit ${result.code ?? result.signal}`
240
+ log(`#${item.id} finished (${how}, ${seconds}s); --no-claim leaves its agent status alone`)
241
+ return
242
+ }
243
+ let comment = null
244
+ try {
245
+ comment = getComment(config, board.id, item.id)
246
+ } catch {
247
+ /* deleted while the agent ran */
248
+ }
249
+ if (recapture && comment && result.code === 0 && !stopped && !['needs-human', null].includes(comment.agentStatus)) {
250
+ try {
251
+ await recaptureComment({ config, board, id: item.id, capture, log })
252
+ if (comment.status === 'open') await setStatus(item.id, 'done')
253
+ log(`#${item.id} recaptured (exit 0, ${seconds}s)`)
254
+ } catch (error) {
255
+ await addReply(config, board.id, item.id, { author: 'shapewall', body: `Recapture needs a person: ${error.message}` })
256
+ await setStatus(item.id, 'needs-human')
257
+ }
258
+ return
259
+ }
260
+ if (!comment || comment.agentStatus !== 'working' || comment.status !== 'open') {
261
+ log(
262
+ `#${item.id} finished in ${seconds}s, agent status ${comment?.agentStatus || 'cleared'}${comment?.status === 'resolved' ? ', resolved' : ''}`,
263
+ )
264
+ return
265
+ }
266
+ // Exit 0 is "done" only when the agent left a word: a reply (or a status
267
+ // of its own, handled above). A silent exit 0 (a command that ignored the
268
+ // comment, a wrong --exec) is for a person to look at, not a fix.
269
+ const replied = (comment.replies || []).length > repliesBefore
270
+ if (result.code === 0 && replied) {
271
+ await setStatus(item.id, 'done')
272
+ log(`#${item.id} done (exit 0, ${seconds}s)`)
273
+ return
274
+ }
275
+ const why =
276
+ result.code === 0
277
+ ? 'the agent command exited 0 without a reply or a status change, so nothing says what it did'
278
+ : stopped
279
+ ? 'shapewall watch stopped while the agent command was running'
280
+ : result.error
281
+ ? `the agent command could not start (${result.error.code || result.error.message})`
282
+ : result.timedOut
283
+ ? `the agent command ran past the ${Math.round(timeoutMs / 60000)} minute timeout and was stopped`
284
+ : `the agent command exited with ${result.code === null ? `signal ${result.signal}` : `code ${result.code}`}`
285
+ await addReply(config, board.id, item.id, { author: 'shapewall', body: `Needs a person: ${why}. Log: ${logFile}` })
286
+ await setStatus(item.id, 'needs-human')
287
+ log(`#${item.id} needs-human: ${why}`)
288
+ }
289
+
290
+ const scan = async () => {
291
+ const context = feedbackContext(config, board)
292
+ const candidates = listComments(config, board.id, { status: 'open', mention })
293
+ .filter((comment) => (claim ? comment.agentStatus === null : !handed.has(handedKey(comment))))
294
+ .filter((comment) => comment.id > baseline && !running.has(comment.id))
295
+ .sort((a, b) => a.id - b.id)
296
+ for (const comment of candidates) {
297
+ if (stopped || (argv && running.size >= concurrency)) break
298
+ let claimed = comment
299
+ if (claim) {
300
+ const result = await setStatus(comment.id, 'queued', { onlyFrom: [null] })
301
+ if (!result.changed) continue
302
+ claimed = result.comment
303
+ } else handed.add(handedKey(comment))
304
+ const item = feedbackItem(context, claimed)
305
+ if (!argv) {
306
+ out(JSON.stringify({ board: board.id, comment: item }))
307
+ continue
308
+ }
309
+ const entry = { child: null, done: null }
310
+ running.set(item.id, entry)
311
+ entry.done = runCommand(item)
312
+ .catch(async (error) => {
313
+ log(`#${item.id} error: ${error.message}`)
314
+ // Not left queued or working for good: a person looks at it (unless the agent set a status itself).
315
+ if (claim) await setStatus(item.id, 'needs-human', { onlyFrom: ['queued', 'working'] }).catch(() => {})
316
+ })
317
+ .finally(() => {
318
+ running.delete(item.id)
319
+ trigger()
320
+ })
321
+ }
322
+ }
323
+
324
+ // Scans never overlap; a trigger during a scan runs one more afterwards.
325
+ const runScan = () => {
326
+ if (scanning) {
327
+ again = true
328
+ return scanning
329
+ }
330
+ scanning = (async () => {
331
+ do {
332
+ again = false
333
+ try {
334
+ await scan()
335
+ } catch (error) {
336
+ log(`watch: ${error.message}`)
337
+ }
338
+ } while (again && !stopped)
339
+ })().finally(() => {
340
+ scanning = null
341
+ wake?.()
342
+ })
343
+ return scanning
344
+ }
345
+
346
+ let debounce = null
347
+ function trigger() {
348
+ if (stopped) return
349
+ clearTimeout(debounce)
350
+ debounce = setTimeout(runScan, debounceMs)
351
+ }
352
+
353
+ let watcher = null
354
+ let poll = null
355
+ const onAbort = () => {
356
+ stopped = true
357
+ wake?.()
358
+ }
359
+ signal?.addEventListener('abort', onAbort, { once: true })
360
+ try {
361
+ if (once) {
362
+ // Hand out everything open now; with a command, keep going until the
363
+ // queue is empty and every command has finished.
364
+ for (;;) {
365
+ await runScan()
366
+ if (!running.size || stopped) break
367
+ await Promise.race([...running.values()].map((entry) => entry.done))
368
+ }
369
+ } else {
370
+ try {
371
+ watcher = fs.watch(dir, (event, filename) => {
372
+ if (!filename || String(filename).startsWith('comments.json')) trigger()
373
+ })
374
+ watcher.on('error', () => {})
375
+ } catch {
376
+ watcher = null // the poll still works
377
+ }
378
+ poll = setInterval(trigger, pollMs)
379
+ log(
380
+ `Watching board "${board.id}" for new comments${argv ? ` (running ${path.basename(argv[0])}, ${concurrency} at a time)` : ''}${claim ? '' : ', without claiming them'}. Ctrl+C stops.`,
381
+ )
382
+ await runScan()
383
+ while (!stopped) await new Promise((resolve) => (wake = resolve))
384
+ }
385
+ } finally {
386
+ stopped = true
387
+ clearTimeout(debounce)
388
+ clearInterval(poll)
389
+ watcher?.close()
390
+ signal?.removeEventListener('abort', onAbort)
391
+ for (const entry of running.values()) {
392
+ try {
393
+ entry.child?.kill('SIGTERM')
394
+ } catch {
395
+ /* gone */
396
+ }
397
+ }
398
+ // Let the runners record what happened (needs-human) before unlocking.
399
+ await Promise.race([Promise.all([...running.values()].map((entry) => entry.done)), sleep(KILL_GRACE_MS + 1000)])
400
+ if (scanning) await scanning
401
+ if (claim) releaseLock(lockFile)
402
+ }
403
+ }