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/doctor.js ADDED
@@ -0,0 +1,295 @@
1
+ // `shapewall doctor`: checks what a capture and the board need, and says how
2
+ // to fix what is missing. `--install-browser` downloads the Chromium build
3
+ // that matches the bundled Playwright version.
4
+
5
+ import fs from 'node:fs'
6
+ import net from 'node:net'
7
+ import path from 'node:path'
8
+ import { spawn } from 'node:child_process'
9
+ import { createRequire } from 'node:module'
10
+ import { fileURLToPath } from 'node:url'
11
+ import { findConfigFile, loadConfig } from './config.js'
12
+ import { describeChannels } from './notify/index.js'
13
+ import { checkGithub } from './github.js'
14
+ import { agentSettings } from './agent/config.js'
15
+ import { formatCommand, loginHint } from './agent/acp/command.js'
16
+ import { acpHandshake } from './agent/backends/acp.js'
17
+ import { cliCommand, invocation } from './invocation.js'
18
+
19
+ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
20
+ const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'))
21
+ const require = createRequire(import.meta.url)
22
+
23
+ export function playwrightCli() {
24
+ return path.join(path.dirname(require.resolve('playwright/package.json')), 'cli.js')
25
+ }
26
+
27
+ export function playwrightVersion() {
28
+ return require('playwright/package.json').version
29
+ }
30
+
31
+ // The command that installs the matching browser, for messages: written the
32
+ // way this shapewall was started (npx github:..., a linked command, ...).
33
+ export const installHint = () => cliCommand('doctor --install-browser')
34
+ // System libraries for Chromium, from the Playwright version Shapewall uses.
35
+ const depsHint = () => `npx playwright@${playwrightVersion()} install-deps chromium`
36
+
37
+ function checkNode(version = process.versions.node) {
38
+ const wanted = Number(/\d+/.exec(PACKAGE.engines?.node || '22')[0])
39
+ const major = Number(version.split('.')[0])
40
+ return major >= wanted
41
+ ? { name: 'node', status: 'ok', message: `Node ${version}` }
42
+ : { name: 'node', status: 'fail', message: `Node ${version}; Shapewall needs ${wanted} or newer`, fix: 'Install a current Node LTS.' }
43
+ }
44
+
45
+ async function checkBrowser(config, { launch = true, chromium = null } = {}) {
46
+ const channel = process.env.SHAPEWALL_BROWSER_CHANNEL || config?.browser.channel
47
+ const executablePath = process.env.SHAPEWALL_BROWSER_PATH || config?.browser.executablePath
48
+ let engine = chromium
49
+ try {
50
+ engine = engine || (await import('playwright')).chromium
51
+ } catch (error) {
52
+ return { name: 'browser', status: 'fail', message: `Playwright did not load (${error.message})`, fix: 'Reinstall Shapewall.' }
53
+ }
54
+ const label = executablePath ? `browser at ${executablePath}` : channel ? `installed browser channel "${channel}"` : 'Playwright Chromium'
55
+ if (!executablePath && !channel && !fs.existsSync(engine.executablePath())) {
56
+ return {
57
+ name: 'browser',
58
+ status: 'fail',
59
+ message: `Playwright ${playwrightVersion()} has no Chromium yet`,
60
+ fix: `Run "${installHint()}" (on Linux also "${depsHint()}" once, as root), or set browser.channel to "chrome".`,
61
+ }
62
+ }
63
+ if (executablePath && !fs.existsSync(executablePath)) {
64
+ return {
65
+ name: 'browser',
66
+ status: 'fail',
67
+ message: `${label} does not exist`,
68
+ fix: 'Fix browser.executablePath or SHAPEWALL_BROWSER_PATH.',
69
+ }
70
+ }
71
+ if (!launch) return { name: 'browser', status: 'ok', message: `${label} found (not started)` }
72
+ try {
73
+ const options = { timeout: 30000 }
74
+ if (executablePath) options.executablePath = executablePath
75
+ else if (channel) options.channel = channel
76
+ const browser = await engine.launch(options)
77
+ const version = browser.version()
78
+ await browser.close()
79
+ return { name: 'browser', status: 'ok', message: `${label} starts (${version})` }
80
+ } catch (error) {
81
+ return {
82
+ name: 'browser',
83
+ status: 'fail',
84
+ message: `${label} does not start: ${String(error.message).split('\n')[0].slice(0, 200)}`,
85
+ fix:
86
+ channel || executablePath
87
+ ? 'Check the browser install.'
88
+ : process.platform === 'linux'
89
+ ? `Chromium is downloaded, so this is usually missing system libraries: run "${depsHint()}" once as root (with sudo), then "${cliCommand('doctor')}" again.`
90
+ : `Run "${installHint()}" again, or set browser.channel to "chrome" to use an installed Chrome.`,
91
+ }
92
+ }
93
+ }
94
+
95
+ // With `optional` (doctor --install-browser, e.g. in the Shapewall clone for
96
+ // the demo) a missing config is a skip, not a FAIL.
97
+ function loadConfigCheck(explicit, { optional = false } = {}) {
98
+ const file = findConfigFile(explicit)
99
+ if (!fs.existsSync(file)) {
100
+ const fix = `Run "${cliCommand('init')}" in the project you want to review.`
101
+ const message = optional ? `No config at ${file} (not needed to install the browser)` : `No config at ${file}`
102
+ return { check: { name: 'config', status: optional ? 'skip' : 'fail', message, fix }, config: null }
103
+ }
104
+ try {
105
+ const config = loadConfig(explicit)
106
+ const pages = config.boards.reduce((sum, board) => sum + board.pages.length, 0)
107
+ return {
108
+ check: {
109
+ name: 'config',
110
+ status: 'ok',
111
+ message: `${path.relative(process.cwd(), file) || file}: ${config.boards.length} board${config.boards.length === 1 ? '' : 's'}, ${pages} page${pages === 1 ? '' : 's'}`,
112
+ },
113
+ config,
114
+ }
115
+ } catch (error) {
116
+ return { check: { name: 'config', status: 'fail', message: error.message, fix: 'Fix the config (docs/config.md).' }, config: null }
117
+ }
118
+ }
119
+
120
+ // The output folder, or the nearest folder above it that exists, must be
121
+ // writable. Nothing is created.
122
+ function checkStore(config) {
123
+ if (!config) return { name: 'store', status: 'skip', message: 'No valid config, so no output folder to check' }
124
+ let dir = config.outputDir
125
+ while (!fs.existsSync(dir) && path.dirname(dir) !== dir) dir = path.dirname(dir)
126
+ try {
127
+ fs.accessSync(dir, fs.constants.W_OK)
128
+ if (dir !== config.outputDir)
129
+ return { name: 'store', status: 'ok', message: `${config.outputDir} will be created (${dir} is writable)` }
130
+ const probe = path.join(dir, `.doctor-${process.pid}.tmp`)
131
+ fs.writeFileSync(probe, 'ok')
132
+ fs.rmSync(probe, { force: true })
133
+ return { name: 'store', status: 'ok', message: `${config.outputDir} is writable` }
134
+ } catch (error) {
135
+ return {
136
+ name: 'store',
137
+ status: 'fail',
138
+ message: `${dir} is not writable (${error.code || error.message})`,
139
+ fix: 'Fix the folder permissions or set outputDir.',
140
+ }
141
+ }
142
+ }
143
+
144
+ export function checkPort(port, host = '127.0.0.1') {
145
+ return new Promise((resolve) => {
146
+ const server = net.createServer()
147
+ server.once('error', (error) =>
148
+ resolve(
149
+ error.code === 'EADDRINUSE'
150
+ ? {
151
+ name: 'port',
152
+ status: 'warn',
153
+ message: `Port ${port} on ${host} is in use`,
154
+ fix: `Use "${cliCommand(`serve --port ${port + 1}`)}" (or stop what is using it).`,
155
+ }
156
+ : { name: 'port', status: 'warn', message: `Port ${port} on ${host}: ${error.code || error.message}` },
157
+ ),
158
+ )
159
+ server.listen(port, host, () => server.close(() => resolve({ name: 'port', status: 'ok', message: `Port ${port} on ${host} is free` })))
160
+ })
161
+ }
162
+
163
+ function checkClient() {
164
+ const index = path.join(ROOT, 'dist', 'client', 'index.html')
165
+ return fs.existsSync(index)
166
+ ? { name: 'client', status: 'ok', message: 'Board client is built' }
167
+ : { name: 'client', status: 'fail', message: 'The board client is not built', fix: 'Run "npm run build" in the Shapewall folder.' }
168
+ }
169
+
170
+ // Notification channels and what each still needs from the environment.
171
+ // Names of variables only: doctor output is pasted into issues.
172
+ export function checkNotifications(config, env = process.env) {
173
+ if (!config) return { name: 'notifications', status: 'skip', message: 'No valid config, so no notifications to check' }
174
+ const channels = describeChannels(config, env)
175
+ if (!channels.length) return { name: 'notifications', status: 'skip', message: 'Notifications: none configured (docs/notifications.md)' }
176
+ const list = channels.map((item) => `${item.id} (${item.type}${item.mode === 'outbox' ? ', outbox' : ''})`).join(', ')
177
+ const missing = channels.filter((item) => !item.ready)
178
+ const people = Object.keys(config.notifications.people).length
179
+ const mapped = people ? `; ${people} ${people === 1 ? 'person' : 'people'} mapped for mentions` : ''
180
+ if (!missing.length) return { name: 'notifications', status: 'ok', message: `Notifications: ${list}${mapped}` }
181
+ return {
182
+ name: 'notifications',
183
+ status: 'warn',
184
+ message: `Notifications: ${list}${mapped}; not ready: ${missing.map((item) => item.id).join(', ')}`,
185
+ fix:
186
+ missing.map((item) => `Set ${item.missing.join(' and ')} for ${item.id}.`).join(' ') +
187
+ ` Then "${cliCommand('notify test CHANNEL')}".`,
188
+ }
189
+ }
190
+
191
+ // What the chat panel is connected to. No network call: a model request
192
+ // costs money, so the first chat message is the real test.
193
+ export function checkAgent(config, env = process.env) {
194
+ if (!config) return { name: 'agent', status: 'skip', message: 'No valid config, so no chat agent to check' }
195
+ const settings = agentSettings(config, env)
196
+ if (settings.configured) {
197
+ // A keyless setup (Ollama, LM Studio) is fine: no "set the key" nudge
198
+ // unless the config names a key variable.
199
+ const key = settings.hasKey
200
+ ? `key from ${settings.keyVar} goes to ${settings.host}`
201
+ : settings.keyVarNamed
202
+ ? `no key (${settings.keyVar} is not set)`
203
+ : 'no key'
204
+ return { name: 'agent', status: 'ok', message: `Chat agent: ${settings.model} at ${settings.host} (OpenAI-compatible), ${key}` }
205
+ }
206
+ if (settings.problem) {
207
+ return {
208
+ name: 'agent',
209
+ status: 'warn',
210
+ message: 'Chat agent: not connected',
211
+ fix: `Fix the agent config: ${settings.problem}. See docs/agents.md.`,
212
+ }
213
+ }
214
+ return { name: 'agent', status: 'skip', message: 'Chat agent: none connected (docs/agents.md)' }
215
+ }
216
+
217
+ // An ACP agent: the command (it is the person's own, so printing it on this
218
+ // machine is fine) and whether it starts: initialize and session/new, no
219
+ // prompt. With launch false (--no-launch) it is not started.
220
+ export async function checkAcpAgent(config, env = process.env, { acp = null, launch = true, timeoutMs = 30000 } = {}) {
221
+ const settings = agentSettings(config || { agent: null }, env, { acp })
222
+ if (!settings.configured) {
223
+ return { name: 'agent', status: 'warn', message: 'Chat agent (ACP): not connected', fix: `${settings.problem}. See docs/agents.md.` }
224
+ }
225
+ const command = formatCommand(settings.acp.argv)
226
+ const refused = settings.acp.refusedEnv.length ? `; not passed: ${settings.acp.refusedEnv.join(', ')}` : ''
227
+ if (!launch || !config) {
228
+ return { name: 'agent', status: 'ok', message: `Chat agent: ${settings.label} over ACP: ${command} (not started)${refused}` }
229
+ }
230
+ const result = await acpHandshake(settings, { env, root: config.dir, timeoutMs })
231
+ if (result.ok) {
232
+ const info = result.agentInfo
233
+ const name = info ? `${info.title || info.name}${info.version ? ` ${info.version}` : ''}` : settings.label
234
+ return {
235
+ name: 'agent',
236
+ status: 'ok',
237
+ // A handshake needs no login; only a prompt shows it (and costs).
238
+ message: `Chat agent: ${name} over ACP: ${command} (handshake ok, login not checked${result.image ? ', takes images' : ''})${refused}`,
239
+ fix: `If the first chat message says it is not logged in: ${loginHint(settings.acp.argv)}.`,
240
+ }
241
+ }
242
+ return {
243
+ name: 'agent',
244
+ status: 'warn',
245
+ message: `Chat agent: ${settings.label} over ACP did not start: ${command}`,
246
+ fix: `${result.message} See docs/agents.md.`,
247
+ }
248
+ }
249
+
250
+ export async function runDoctor({
251
+ configFile = null,
252
+ port = 4600,
253
+ host = '127.0.0.1',
254
+ launch = true,
255
+ chromium = null,
256
+ env = process.env,
257
+ fetchImpl = undefined,
258
+ network = true,
259
+ acp = null,
260
+ configOptional = false,
261
+ } = {}) {
262
+ const { check: configCheck, config } = loadConfigCheck(configFile, { optional: configOptional })
263
+ const useAcp = Boolean(acp || env.SHAPEWALL_AGENT_ACP || (config && agentSettings(config, env, { acp }).backend === 'acp'))
264
+ const checks = [
265
+ checkNode(),
266
+ configCheck,
267
+ await checkBrowser(config, { launch, chromium }),
268
+ checkStore(config),
269
+ await checkPort(port, host),
270
+ checkClient(),
271
+ checkNotifications(config, env),
272
+ useAcp ? await checkAcpAgent(config, env, { acp, launch }) : checkAgent(config, env),
273
+ await checkGithub(config, { env, fetchImpl, network }),
274
+ ]
275
+ return { ok: !checks.some((check) => check.status === 'fail'), checks }
276
+ }
277
+
278
+ export function formatDoctor(report) {
279
+ const mark = { ok: 'ok ', warn: 'warn', fail: 'FAIL', skip: 'skip' }
280
+ const lines = report.checks.flatMap((check) => [`${mark[check.status]} ${check.message}`, ...(check.fix ? [` ${check.fix}`] : [])])
281
+ const how = invocation()
282
+ lines.push('', report.ok ? 'Ready.' : `Fix the FAIL lines above, then run "${how.command} doctor" again.`)
283
+ if (how.note) lines.push(`(Commands above are written as "${how.command}": ${how.note}.)`)
284
+ return lines.join('\n')
285
+ }
286
+
287
+ // Downloads Chromium for the bundled Playwright (its own CLI, so the browser
288
+ // build always matches). Resolves with the exit code.
289
+ export function installBrowser({ stdio = 'inherit' } = {}) {
290
+ return new Promise((resolve, reject) => {
291
+ const child = spawn(process.execPath, [playwrightCli(), 'install', 'chromium'], { stdio, shell: false })
292
+ child.once('error', reject)
293
+ child.once('exit', (code) => resolve(code ?? 1))
294
+ })
295
+ }
@@ -0,0 +1,268 @@
1
+ // The shared event log: <outputDir>/events.jsonl, one JSON line per comment
2
+ // event, from every process that changes comments (the server, the CLI,
3
+ // `shapewall watch`, MCP, the starter agent). In-process listeners
4
+ // (src/events.js) only hear their own process; this file is how
5
+ // `shapewall events` and the notifier in `shapewall serve` see the rest.
6
+ //
7
+ // - Appended by the store while it holds the comments file lock, so a board's
8
+ // events are in the order its changes were made. Each append is one
9
+ // write() of whole lines to an O_APPEND file, under the log's own short
10
+ // lock (boards have separate comment locks), so lines never interleave.
11
+ // - Bounded: past LOG_MAX_BYTES the file is renamed to events.1.jsonl (the
12
+ // one older file kept) and a new one starts. Readers follow the rename.
13
+ // - Lines hold a summary of the comment, not the whole thread: text, author,
14
+ // status, agent status, resolution, reply count; plus the reply for a reply.
15
+ // - Losing a line never fails a change: an append that cannot be written is
16
+ // dropped, and that process notifies for it itself (src/notify/run.js).
17
+
18
+ import fs from 'node:fs'
19
+ import path from 'node:path'
20
+ import { withFileLock } from './lock.js'
21
+
22
+ export const LOG_FILE = 'events.jsonl'
23
+ export const LOG_ROTATED = 'events.1.jsonl'
24
+ export const LOG_MAX_BYTES = 5 * 1024 * 1024
25
+ // Set on an event once its line is in the log (a symbol, so it never shows up in a payload).
26
+ export const LOGGED = Symbol('shapewall.logged')
27
+
28
+ export const eventLogFile = (config) => path.join(config.outputDir, LOG_FILE)
29
+ const rotatedFile = (config) => path.join(config.outputDir, LOG_ROTATED)
30
+
31
+ // The comment as a log line and `shapewall events` show it.
32
+ export function commentSummary(comment) {
33
+ if (!comment) return null
34
+ return {
35
+ id: comment.id,
36
+ pageId: comment.pageId,
37
+ viewport: comment.viewport,
38
+ author: comment.author || null,
39
+ body: comment.body,
40
+ status: comment.status,
41
+ agentStatus: comment.agentStatus ?? null,
42
+ resolution: comment.resolution ?? null,
43
+ fixRef: comment.fixRef ?? null,
44
+ mentions: comment.mentions || [],
45
+ replyCount: Array.isArray(comment.replies) ? comment.replies.length : (comment.replyCount ?? 0),
46
+ element: comment.anchor ? { selector: comment.anchor.selector, text: comment.anchor.text || '' } : (comment.element ?? null),
47
+ captureVersion: comment.captureVersion ?? null,
48
+ createdAt: comment.createdAt,
49
+ updatedAt: comment.updatedAt,
50
+ }
51
+ }
52
+
53
+ // One event as a log record (also what `shapewall events --json` prints).
54
+ export function eventRecord(event) {
55
+ const record = {
56
+ id: event.id,
57
+ type: event.type,
58
+ at: event.at,
59
+ board: event.boardId,
60
+ commentId: event.commentId,
61
+ actor: event.actor ?? null,
62
+ comment: commentSummary(event.comment),
63
+ }
64
+ if (event.reply)
65
+ record.reply = { id: event.reply.id, author: event.reply.author, body: event.reply.body, createdAt: event.reply.createdAt }
66
+ if (event.handle) record.handle = event.handle
67
+ if (event.previous) record.previous = event.previous
68
+ if (event.type === 'comment.status_changed') record.agentStatus = event.agentStatus ?? null
69
+ return record
70
+ }
71
+
72
+ // A record read back, in the shape the notifier takes (src/events.js).
73
+ export function recordEvent(record) {
74
+ const event = {
75
+ id: record.id,
76
+ type: record.type,
77
+ at: record.at,
78
+ boardId: record.board,
79
+ commentId: record.commentId,
80
+ comment: record.comment,
81
+ actor: record.actor ?? null,
82
+ }
83
+ for (const key of ['reply', 'handle', 'previous', 'agentStatus']) if (record[key] !== undefined) event[key] = record[key]
84
+ return event
85
+ }
86
+
87
+ const isRecord = (value) =>
88
+ Boolean(value) &&
89
+ typeof value === 'object' &&
90
+ typeof value.id === 'string' &&
91
+ typeof value.type === 'string' &&
92
+ typeof value.at === 'string'
93
+
94
+ // Appends events to the log; marks each one written with LOGGED. Never throws.
95
+ export async function appendEvents(config, events, { maxBytes = LOG_MAX_BYTES } = {}) {
96
+ if (!events.length || !config?.outputDir) return false
97
+ const file = eventLogFile(config)
98
+ try {
99
+ const data = Buffer.from(events.map((event) => `${JSON.stringify(eventRecord(event))}\n`).join(''))
100
+ fs.mkdirSync(config.outputDir, { recursive: true })
101
+ await withFileLock(file, () => {
102
+ let size = 0
103
+ try {
104
+ size = fs.statSync(file).size
105
+ } catch {
106
+ /* a new log */
107
+ }
108
+ if (size > 0 && size + data.length > maxBytes) fs.renameSync(file, rotatedFile(config))
109
+ const fd = fs.openSync(file, 'a', 0o600)
110
+ try {
111
+ fs.writeSync(fd, data)
112
+ } finally {
113
+ fs.closeSync(fd)
114
+ }
115
+ })
116
+ for (const event of events) event[LOGGED] = true
117
+ return true
118
+ } catch {
119
+ return false
120
+ }
121
+ }
122
+
123
+ function parseLines(buffer, onRecord) {
124
+ for (const line of buffer.toString('utf8').split('\n')) {
125
+ if (!line.trim()) continue
126
+ let record
127
+ try {
128
+ record = JSON.parse(line)
129
+ } catch {
130
+ continue // a damaged line is skipped, not fatal
131
+ }
132
+ if (isRecord(record)) onRecord(record)
133
+ }
134
+ }
135
+
136
+ function readRange(file, from, to) {
137
+ const fd = fs.openSync(file, 'r')
138
+ try {
139
+ const buffer = Buffer.alloc(Math.max(0, to - from))
140
+ let read = 0
141
+ while (read < buffer.length) {
142
+ const count = fs.readSync(fd, buffer, read, buffer.length - read, from + read)
143
+ if (!count) break
144
+ read += count
145
+ }
146
+ return buffer.subarray(0, read)
147
+ } finally {
148
+ fs.closeSync(fd)
149
+ }
150
+ }
151
+
152
+ const statOf = (file) => {
153
+ try {
154
+ return fs.statSync(file)
155
+ } catch {
156
+ return null
157
+ }
158
+ }
159
+
160
+ // Every record in the log, oldest first (the rotated file, then the current one).
161
+ export function readEventLog(config) {
162
+ const records = []
163
+ for (const file of [rotatedFile(config), eventLogFile(config)]) {
164
+ const stat = statOf(file)
165
+ if (stat) parseLines(readRange(file, 0, stat.size), (record) => records.push(record))
166
+ }
167
+ return records
168
+ }
169
+
170
+ // Follows the log: calls onRecord(record) for each new line. `from: 'end'`
171
+ // starts after what is there now (nothing old is replayed); 'start' reads the
172
+ // rotated file and the current one first. drain() reads what is new right
173
+ // now (it also runs on fs events and every `pollMs`); stop() ends it.
174
+ // keepAlive: the follow alone keeps the process running (`events --follow`).
175
+ export function followEventLog(config, { onRecord, from = 'end', pollMs = 1000, watch = true, keepAlive = false } = {}) {
176
+ const file = eventLogFile(config)
177
+ const rotated = rotatedFile(config)
178
+ let ino = null
179
+ let offset = 0
180
+ let partial = Buffer.alloc(0)
181
+ let stopped = false
182
+ let draining = false
183
+
184
+ // Whole lines only: a line still being written waits for the next read.
185
+ const consume = (chunk) => {
186
+ const buffer = partial.length ? Buffer.concat([partial, chunk]) : chunk
187
+ const end = buffer.lastIndexOf(0x0a)
188
+ if (end < 0) {
189
+ partial = buffer
190
+ return
191
+ }
192
+ partial = Buffer.from(buffer.subarray(end + 1))
193
+ parseLines(buffer.subarray(0, end + 1), (record) => {
194
+ if (!stopped) onRecord(record)
195
+ })
196
+ }
197
+
198
+ const start = statOf(file)
199
+ if (from === 'start') {
200
+ const old = statOf(rotated)
201
+ if (old) consume(readRange(rotated, 0, old.size))
202
+ partial = Buffer.alloc(0)
203
+ if (start) ino = start.ino
204
+ } else if (start) {
205
+ ino = start.ino
206
+ offset = start.size
207
+ }
208
+
209
+ function drain() {
210
+ if (stopped || draining) return
211
+ draining = true
212
+ try {
213
+ const current = statOf(file)
214
+ if (ino !== null && (!current || current.ino !== ino)) {
215
+ // Rotated since the last read: finish the old file first.
216
+ const old = statOf(rotated)
217
+ if (old && old.ino === ino && old.size > offset) consume(readRange(rotated, offset, old.size))
218
+ partial = Buffer.alloc(0)
219
+ ino = current ? current.ino : null
220
+ offset = 0
221
+ }
222
+ if (!current) return
223
+ if (ino === null) {
224
+ ino = current.ino
225
+ offset = 0
226
+ }
227
+ if (current.size < offset) {
228
+ // Truncated by hand: start over at the top.
229
+ offset = 0
230
+ partial = Buffer.alloc(0)
231
+ }
232
+ if (current.size > offset) {
233
+ const chunk = readRange(file, offset, current.size)
234
+ offset += chunk.length
235
+ consume(chunk)
236
+ }
237
+ } catch {
238
+ /* the next tick tries again */
239
+ } finally {
240
+ draining = false
241
+ }
242
+ }
243
+
244
+ let watcher = null
245
+ if (watch) {
246
+ try {
247
+ fs.mkdirSync(config.outputDir, { recursive: true })
248
+ watcher = fs.watch(config.outputDir, (event, name) => {
249
+ if (!name || String(name).startsWith('events')) drain()
250
+ })
251
+ watcher.on('error', () => {})
252
+ if (!keepAlive) watcher.unref?.()
253
+ } catch {
254
+ watcher = null // the poll still works
255
+ }
256
+ }
257
+ const timer = pollMs > 0 ? setInterval(drain, pollMs) : null
258
+ if (!keepAlive) timer?.unref?.()
259
+
260
+ return {
261
+ drain,
262
+ stop() {
263
+ stopped = true
264
+ clearInterval(timer)
265
+ watcher?.close()
266
+ },
267
+ }
268
+ }
@@ -0,0 +1,102 @@
1
+ // `shapewall events`: the shared event log (src/event-log.js) for bots and
2
+ // scripts. It only reads: it never claims a comment or sets an agent status,
3
+ // so it can run beside `shapewall watch`, the starter agent and the board.
4
+ //
5
+ // shapewall events the last few events, then exit
6
+ // shapewall events --follow new events as they happen (Ctrl+C stops)
7
+ // --since EVENT_ID|ISO_TIME start after that event or time (with --follow: then keep going)
8
+ // --board ID only that board
9
+ // --limit N without --follow or --since: how many recent events (default 20)
10
+ // --json one JSON line per event
11
+
12
+ import { getBoard } from './config.js'
13
+ import { followEventLog, readEventLog } from './event-log.js'
14
+
15
+ const LIMIT_DEFAULT = 20
16
+ const LIMIT_MAX = 1000
17
+
18
+ const clip = (value, max = 100) => {
19
+ const text = String(value || '')
20
+ .replace(/\s+/g, ' ')
21
+ .trim()
22
+ return text.length > max ? `${text.slice(0, max - 3)}...` : text
23
+ }
24
+
25
+ // One event as a line of text.
26
+ export function formatEvent(record) {
27
+ const what = record.type.replace(/^comment\./, '')
28
+ const target = `${record.board}#${record.commentId ?? '?'}`
29
+ const by = record.actor ? ` by ${record.actor}` : ''
30
+ let detail = ''
31
+ if (record.type === 'comment.replied' || (record.type === 'comment.mentioned' && record.reply)) detail = record.reply?.body
32
+ else if (record.type === 'comment.status_changed') detail = `${record.previous?.agentStatus || 'none'} -> ${record.agentStatus || 'none'}`
33
+ else if (record.type === 'comment.resolved') detail = record.comment?.resolution || record.comment?.body
34
+ else detail = record.comment?.body
35
+ const handle = record.handle ? ` @${record.handle}` : ''
36
+ return `${record.at} ${what}${handle} ${target}${by}: ${clip(detail)}`
37
+ }
38
+
39
+ // A filter for --since: after the event with that id (seen in order), or after a time.
40
+ export function sinceGate(value) {
41
+ if (value === undefined) return null
42
+ const text = String(value).trim()
43
+ if (/^\d{4}-\d{2}-\d{2}/.test(text)) {
44
+ const time = Date.parse(text)
45
+ if (!Number.isFinite(time)) throw new Error('--since: not a valid time (use ISO, e.g. 2026-11-05T18:00:00Z)')
46
+ return { byTime: true, found: true, pass: (record) => Date.parse(record.at) > time }
47
+ }
48
+ if (!/^[0-9a-f-]{8,64}$/i.test(text)) throw new Error('--since needs an event id (from --json) or an ISO time')
49
+ const gate = {
50
+ byTime: false,
51
+ found: false,
52
+ pass(record) {
53
+ if (gate.found) return true
54
+ if (record.id === text) gate.found = true
55
+ return false
56
+ },
57
+ }
58
+ return gate
59
+ }
60
+
61
+ export async function eventsCommand(config, flags, out, err = () => {}, { signal = null, pollMs = 1000 } = {}) {
62
+ const boardId = flags.board === undefined ? null : getBoard(config, flags.board).id
63
+ const limit = flags.limit === undefined ? LIMIT_DEFAULT : Number(flags.limit)
64
+ if (!Number.isInteger(limit) || limit < 1 || limit > LIMIT_MAX) throw new Error(`--limit: a whole number from 1 to ${LIMIT_MAX}`)
65
+ const gate = sinceGate(flags.since)
66
+ const wanted = (record) => !boardId || record.board === boardId
67
+ const show = (record) => out(flags.json ? JSON.stringify(record) : formatEvent(record))
68
+ const notFound = () =>
69
+ new Error(`--since: event ${flags.since} is not in the log (it may have been rotated away); use an ISO time instead`)
70
+
71
+ if (!flags.follow) {
72
+ let records = readEventLog(config)
73
+ if (gate) {
74
+ records = records.filter((record) => gate.pass(record))
75
+ if (!gate.found) throw notFound()
76
+ } else records = records.filter(wanted).slice(-limit)
77
+ for (const record of records.filter(wanted)) show(record)
78
+ return
79
+ }
80
+
81
+ // --follow: with --since, read the whole log first, then keep going.
82
+ const follower = followEventLog(config, {
83
+ from: gate ? 'start' : 'end',
84
+ pollMs,
85
+ keepAlive: true,
86
+ onRecord: (record) => {
87
+ if (gate && !gate.pass(record)) return
88
+ if (wanted(record)) show(record)
89
+ },
90
+ })
91
+ follower.drain()
92
+ if (gate && !gate.found) {
93
+ follower.stop()
94
+ throw notFound()
95
+ }
96
+ err('Following comment events (Ctrl+C stops).')
97
+ await new Promise((resolve) => {
98
+ if (signal?.aborted) return resolve()
99
+ signal?.addEventListener('abort', resolve, { once: true })
100
+ })
101
+ follower.stop()
102
+ }