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,243 @@
1
+ // Help text: every command's section, the full help and one command's help.
2
+
3
+ import fs from 'node:fs'
4
+ import { CONFIG_FILE, SITEMAP_LIMIT_DEFAULT } from '../config.js'
5
+ import { AUTH_HELP } from '../auth/record.js'
6
+ import { AGENT_STATUSES } from '../store.js'
7
+ import { DEFAULT_PORT } from '../serve-state.js'
8
+
9
+ export const VERSION = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version
10
+
11
+ // Each command's help, printed by `shapewall --help` (all of them) and by
12
+ // `shapewall <command> --help` (that one).
13
+ export const SECTIONS = {
14
+ 'buzz-bridge': ` buzz-bridge run a private foreground gateway to existing Buzz agents
15
+ --bridge-config FILE private operator map outside project/capture data; Ctrl-C stops it
16
+ no new agent, session, model, or automatic completion (docs/buzz.md)`,
17
+ settings: ` settings open temporary host-only agent settings (no board or chat)
18
+ --port N loopback port (default: a free port)
19
+ --open open the private settings link in your browser`,
20
+ auth: AUTH_HELP,
21
+ init: ` init write ${CONFIG_FILE} in this folder
22
+ --base-url URL the site to capture (default http://localhost:3000); finds its
23
+ pages: <base URL>/sitemap.xml, else links from the home page
24
+ (2 levels, 25 pages, same site only)
25
+ --sitemap [URL|FILE] take the pages from this sitemap instead
26
+ (alone: <base URL>/sitemap.xml)
27
+ (with --limit, --group, --exclude as for sitemap)
28
+ --no-discover do not look for pages: write the home page only
29
+ --force overwrite an existing config`,
30
+ sitemap: ` sitemap [URL|FILE] add the pages of a sitemap.xml (or sitemap index) to the config
31
+ (default: the board's "sitemap" setting)
32
+ --limit N at most N new pages, the shallowest first (default ${SITEMAP_LIMIT_DEFAULT})
33
+ --group NAME put them all in one group (default: by first path segment)
34
+ --exclude /PREFIX leave out paths starting with this (repeat or comma-separate)
35
+ --board ID board to add them to (default: the first)
36
+ --dry-run show what would be added, change nothing
37
+ --json machine-readable result`,
38
+ capture: ` capture capture every page (desktop + phone, PNG + live HTML) and check its links
39
+ --board ID board to capture (default: the first)
40
+ --only ID|PATH only these pages (repeat or comma-separate)
41
+ --env ID capture this environment (default: the first)
42
+ --check-external also check links to other sites (default: same-site links only)
43
+ --json machine-readable summary on stdout (shots, failures, broken links); progress on stderr
44
+ -y, --yes never ask anything (capture does not prompt; for CI scripts)
45
+ exit code: 0 all shots ok, 2 some failed (an "expectStatus" page is ok), 1 error`,
46
+ checks: ` checks [run|list] check original pages and save private diagnostic reports
47
+ checks flow --flow-file FILE run one explicit interaction flow, with an optional final accessibility snapshot
48
+ checks accessibility --only ID [--viewport NAME] audit one original page state with axe
49
+ --board ID board to check (default: the first)
50
+ --env ID environment to check (default: the first)
51
+ --only ID|PATH only these pages (repeat or comma-separate)
52
+ --seo | --no-seo include public SEO and social-image checks, or leave them out when the config turns them on
53
+ --limit N maximum page views to check (default 20)
54
+ --source-build SHA source revision for report provenance
55
+ --json machine-readable reports; progress on stderr`,
56
+ audit: ` audit [board] run bounded Chrome Lighthouse lab audits on original pages
57
+ --board ID board to audit (default: the first)
58
+ --env ID environment to audit (default: the first)
59
+ --only ID only these page ids (repeat or comma-separate)
60
+ --viewports NAMES configured viewport names, comma-separated
61
+ --samples N repeated samples per view (default 1, maximum 10)
62
+ --max-pages N explicit page cap (default 5, maximum 20)
63
+ --max-runs N explicit navigation cap (default 10, maximum 40)
64
+ --cache MODE cold, warm or auth-preserved
65
+ --production MODE production, development or unknown
66
+ --source-build SHA source build identifier for provenance
67
+ --browser-version V require this installed browser version
68
+ --seo | --no-seo include optional Lighthouse SEO checks, or leave them out when the config turns them on
69
+ --json machine-readable reports; progress on stderr`,
70
+ serve: ` serve serve the board (http://127.0.0.1:4600/ by default)
71
+ --port N default ${DEFAULT_PORT}
72
+ --host ADDR default 127.0.0.1 (see docs/deployment.md before changing)
73
+ --tailscale[=print] private HTTPS over Tailscale; =print changes nothing
74
+ --no-identity pair even devices signed in as the Tailscale owner
75
+ --lan[=IP|INTERFACE] pair devices on your network (HTTP cookies can be sniffed)
76
+ --tls-cert FILE with --lan: HTTPS certificate (also --tls-key FILE)
77
+ --no-remote-chat paired devices cannot use the agent
78
+ --approve-on-host paired devices cannot approve agent commands
79
+ --open also open the board in your browser, with agent settings
80
+ --read-only no comments or captures from the UI
81
+ --accounts require local passkey accounts after owner setup (Node 22.13+)
82
+ --accounts-origin URL fixed HTTPS origin (default: loopback URL or --tailscale URL)
83
+ --no-capture comments allowed, captures only from the CLI
84
+ --buzz-bridge FILE owner-only existing Buzz conversation (private operator map; docs/buzz.md)
85
+ --allowed-host NAME extra Host header to accept (repeatable; also $SHAPEWALL_ALLOWED_HOSTS, "*" = any)
86
+ --chat | --no-chat the board chat with your agent (default on, off when shared beyond this machine)
87
+ --agent-acp "CMD" chat with an agent CLI over ACP, e.g. "claude-agent-acp" (installed globally)
88
+ (also $SHAPEWALL_AGENT_ACP; never read from the config; docs/agents.md)
89
+ --allow-remote-agent with --chat on a shared board, let an ACP agent run anyway (anyone reaching it acts as you)`,
90
+ devices: ` devices list paired devices and pending requests for this project [--json]
91
+ devices approve CODE approve after matching the code on your device
92
+ devices deny CODE deny a pending request
93
+ devices revoke ID|--all revoke a device or all devices immediately`,
94
+ comments: ` comments [list] print comments (feedback for you or a coding agent)
95
+ --open | --resolved | --all which ones (default --open)
96
+ --page ID only comments on this page
97
+ --mention NAME only comments that mention @NAME (in the text or a reply)
98
+ --since ID|TIME only comments after this comment id, or created or changed after this ISO time
99
+ --json machine-readable, with selectors, file paths and replies
100
+ --for-agent each comment quoted as untrusted data (<shapewall-data>), for an agent to read
101
+ comments get ID one comment, everything about it [--json] [--for-agent]
102
+ comments add add a comment --page ID --body TEXT [--viewport NAME (default the page's first)]
103
+ [--selector CSS (pin it to that element)] [--author NAME (default agent)] [--json]
104
+ comments resolve ID mark a comment resolved [--note TEXT] [--ref URL|COMMIT] [--author NAME] [--json]
105
+ comments reopen ID reopen a comment [--author NAME] [--json]
106
+ comments reply ID add a reply --body TEXT [--author NAME (default agent)] [--json]
107
+ comments status ID S agent status: ${AGENT_STATUSES.join(', ')} or clear [--note TEXT] [--author NAME] [--json]
108
+ --board ID board (default: the first); --remote URL for a hosted board (see push)`,
109
+ events: ` events comment events from every process (the shared log); never claims anything
110
+ --follow keep printing new events until Ctrl+C
111
+ --since ID|TIME after this event id (from --json) or ISO time
112
+ --limit N without --follow or --since: the last N (default 20)
113
+ --json one JSON line per event [--board ID]`,
114
+ journeys: ` journeys [list] print the board's journeys, with every fork and branch
115
+ --json machine-readable: steps (forks included), pages and every path`,
116
+ links: ` links links between the board's pages, from the last capture
117
+ --broken only links that lead to an error (4xx/5xx or no answer)
118
+ --board ID | --env ID | --json`,
119
+ watch: ` watch hand each new open comment to an agent (runs until Ctrl+C)
120
+ --exec "CMD ARGS" run this command per comment (comment JSON on stdin; no shell)
121
+ without --exec, print one JSON line per comment
122
+ --concurrency N commands at once, 1 to 4 (default 1)
123
+ --recapture recapture the comment page after a successful --exec (local only)
124
+ --new-only skip comments that exist when the watch starts
125
+ --once hand out what is open now, wait for the commands, exit
126
+ --timeout MIN stop a command after this many minutes (default 60)
127
+ --mention NAME only comments that mention @NAME, e.g. --mention agent
128
+ --no-claim hand out every open comment once without claiming it (no agent status, beside other watchers)
129
+ a command that exits 0 must reply or set a status itself, else the
130
+ comment becomes needs-human (docs/agent-workflow.md)`,
131
+ agent: ` agent run --comment ID the sandboxed starter agent on one comment: a container with only a fresh
132
+ worktree, egress to the package registry only (the model is called from here), a branch
133
+ --pr also push the branch and open a pull request (GitHub connect); not when it
134
+ touches CI config, manifests or build files unless --allow-ci-push
135
+ --git-remote NAME the git remote --pr pushes to (default origin; never from the config)
136
+ --fork-remote NAME push to your fork (a git remote) instead, and open the PR from it
137
+ --retry take a comment whose agent status is done or needs-human too
138
+ --trust-comment run a comment the trigger gate holds back (never a guest's)
139
+ --max-turns N | --max-tokens N | --max-minutes N budget for this comment
140
+ --max-disk SIZE disk cap on the checkout (default 2g; the run stops over it)
141
+ --model-timeout S seconds a model call may take to start answering, 1 to 900 (default 180 for
142
+ the first call, 60 after; tried once more on a timeout)
143
+ --trusted NAME may dispatch work (repeatable; adds to starterAgent.trusted)
144
+ --runtime podman|docker --image NAME --profile openai-compatible
145
+ --allow-host HOST[:PORT] extra egress host (repeatable) --registry HOST|none
146
+ --work-dir DIR where worktrees go (default: the cache folder)
147
+ agent watch run the starter agent on each comment the trigger gate lets through [--once]
148
+ agent doctor check the runtime, image, model, trust lists and the sandbox itself [--no-egress]
149
+ agent build-image build the agent's image from this package's Dockerfile.agent
150
+ --runtime podman|docker --image NAME (default localhost/shapewall-agent:latest)
151
+ (docs/starter-agent.md; --remote URL works for run and watch)`,
152
+ github: ` github issue ID open a GitHub issue from a comment (or show the one it has)
153
+ github link ID PR link a pull request (12, #12 or its URL) to a comment
154
+ github sync link pull requests that name a comment; resolve comments whose PR merged
155
+ (repo: "github.repo" in the config; token: $SHAPEWALL_GITHUB_TOKEN or $GITHUB_TOKEN,
156
+ else a signed-in GitHub CLI ("gh auth token"))`,
157
+ mcp: ` mcp MCP server on stdio for coding agents
158
+ --read-only | --no-capture`,
159
+ notify: ` notify list notification channels, their events and what each still needs [--json]
160
+ notify test CHANNEL send a test message to one channel [--to EMAIL for email channels]`,
161
+ doctor: ` doctor check Node, the browser, the config, the port, the output folder, notifications and chat
162
+ --install-browser download the Chromium this Shapewall needs first (no config needed for this)
163
+ --port N port to check (default ${DEFAULT_PORT})
164
+ --no-launch find the browser and the ACP agent without starting them
165
+ --agent-acp "CMD" the ACP agent to check: starts it, does the handshake, stops it (also $SHAPEWALL_AGENT_ACP)
166
+ --json machine-readable report`,
167
+ variant: ` variant add PAGE capture another version of a page beside it
168
+ --url URL | --path /p the version to capture (path is on the board's baseUrl)
169
+ --title TEXT [--note TEXT] [--source TEXT] [--id ID] [--viewport desktop,phone]
170
+ the id is --id, else the title as a slug plus 4 random characters
171
+ variant rm ID | variant list`,
172
+ export: ` export static read-only copy of the boards
173
+ --include-checks explicitly include private diagnostic reports
174
+ --out DIR default shapewall-export
175
+ --no-comments leave comments out
176
+ --browser-comments visitors may comment; their comments stay in their own browser
177
+ --noindex ask search engines not to index the export`,
178
+ share: ` share --remote URL move local captures, history and comments to a shared project
179
+ --include-checks explicitly include private diagnostic reports
180
+ --board ID move only this board (default all)
181
+ --dry-run show counts; sends nothing
182
+ --no-comments captures, history and journeys only`,
183
+ login: ` login --remote URL get a project token through the browser; saved for the --remote commands`,
184
+ push: ` push upload the latest captures to a hosted project
185
+ --include-checks explicitly include private diagnostic reports
186
+ --remote URL the hosted Shapewall (or $SHAPEWALL_REMOTE)
187
+ --board ID only this board (default: every board)
188
+ comments | watch | mcp --remote URL
189
+ the same commands against a hosted board (--board ID picks one)
190
+ token: $SHAPEWALL_TOKEN or --token-file FILE (a project token, swp_...)
191
+ watch --exec commands get no token unless --pass-token
192
+ --include-guests comments and watch: also share link guests' comments (untrusted)`,
193
+ hosted: ` hosted run the hosted server (accounts, workspaces, pushed boards)
194
+ --data DIR default ./shapewall-hosted-data (or $SHAPEWALL_HOSTED_DATA)
195
+ --origin URL public origin, e.g. https://app.example.com (default http://HOST:PORT)
196
+ --port N | --host ADDR default 4700 on 127.0.0.1
197
+ --signup invite|open default invite (the first account uses the setup link)
198
+ --trust-proxy behind a reverse proxy on this host (client IPs from X-Forwarded-For)
199
+ --usercontent-origin URL serve live HTML only from this other origin (or $SHAPEWALL_USERCONTENT_ORIGIN)
200
+ --previous-origin URL while moving to a new origin: the old one (sign-in moves, up to 30 days)
201
+ --report-email ADDR where "Report this board" on public projects goes
202
+ --tailscale on your tailnet through tailscale serve (https://<machine>.<tailnet>.ts.net)
203
+ --tailscale-port N default 443; --funnel: share links public through Tailscale Funnel
204
+ (share pages only, never the console), on --funnel-port 8443|443|10000
205
+ --quotas FILE per-workspace quotas (default <data>/quotas.json when it exists)
206
+ --retention-hours N prune old versions every N hours (default 6, 0 = off); --retention-keep N (2)
207
+ hosted setup-link print the first account's one-time link (it is not in the log)
208
+ --data DIR | --new --new: make a new link (the old one stops working)
209
+ hosted move-origin --to URL move the server to a new origin (passkeys move with a rebind)
210
+ --data DIR | --days N | --status window 1 to 30 days (default 30)
211
+ hosted --setup --domain HOST write a Docker Compose + Caddy folder for your own domain
212
+ --usercontent-domain HOST live HTML on its own domain; --email (TLS); --dir (./shapewall-hosted)
213
+ --source DIR a Shapewall checkout to build from; --dry-run; --force; --start (build, start, setup link)
214
+ hosted admin list|suspend|resume|delete|export|reports|retention|log the operator's commands
215
+ hosted backup --to DIR [--keep-days N] a consistent copy while the server runs
216
+ hosted restore --from BACKUP --data NEW | --from BACKUP --check (the restore drill)`,
217
+ }
218
+
219
+ const LOCAL_COMMANDS = Object.keys(SECTIONS).filter((name) => !['login', 'push', 'hosted'].includes(name))
220
+
221
+ const GLOBAL_HELP = `Global
222
+ --config FILE default ./${CONFIG_FILE} (or $SHAPEWALL_CONFIG)
223
+ -h, --help | -v, --version (shapewall <command> --help shows one command)`
224
+
225
+ export const HELP = `shapewall ${VERSION} -- every page of your site on one zoomable wall
226
+
227
+ Usage: shapewall <command> [options]
228
+
229
+ Commands
230
+ ${LOCAL_COMMANDS.map((name) => SECTIONS[name]).join('\n')}
231
+
232
+ Hosted Shapewall (docs/hosted.md)
233
+ ${SECTIONS.login}
234
+ ${SECTIONS.push}
235
+ ${SECTIONS.hosted}
236
+
237
+ ${GLOBAL_HELP}
238
+ `
239
+
240
+ export function commandHelp(command) {
241
+ if (!SECTIONS[command]) return HELP
242
+ return `Usage: shapewall ${command} [options]\n\n${SECTIONS[command]}\n\n${GLOBAL_HELP}\n`
243
+ }
@@ -0,0 +1,214 @@
1
+ // `shapewall init` and `shapewall sitemap`: write the config, or add a sitemap's pages to it.
2
+
3
+ import fs from 'node:fs'
4
+ import path from 'node:path'
5
+ import { CONFIG_FILE, ConfigError, SITEMAP_LIMIT_MAX, findConfigFile, normalizeConfig, starterConfig, titleFromBaseUrl } from '../config.js'
6
+ import { writeFileAtomic } from '../store.js'
7
+ import { addPagesToRaw, defaultSitemapUrl, formatImport, importSitemap, sitemapPages } from '../sitemap.js'
8
+ import { DISCOVER_DEFAULTS, cutTitle, describeFetchError, discoverPages, pageTitle } from '../discover.js'
9
+ import { cliCommand } from '../invocation.js'
10
+
11
+ const isHttp = (value) => /^https?:\/\//i.test(String(value))
12
+
13
+ function limitFlag(value) {
14
+ if (value === undefined) return null
15
+ const limit = Number(value)
16
+ if (!Number.isInteger(limit) || limit < 1 || limit > SITEMAP_LIMIT_MAX)
17
+ throw new Error(`--limit: a whole number from 1 to ${SITEMAP_LIMIT_MAX}`)
18
+ return limit
19
+ }
20
+
21
+ function sitemapOptions(flags) {
22
+ const exclude = flags.exclude || null
23
+ if (exclude?.some((prefix) => !prefix.startsWith('/'))) throw new Error('--exclude: path prefixes such as /tag/')
24
+ return {
25
+ limit: limitFlag(flags.limit),
26
+ group: typeof flags.group === 'string' && flags.group.trim() ? flags.group.trim().slice(0, 60) : null,
27
+ exclude,
28
+ }
29
+ }
30
+
31
+ // Indented "+ id path (group)" lines, the first `max` of them.
32
+ function pageLines(pages, max = 30) {
33
+ const lines = pages.slice(0, max).map((page) => ` + ${page.id} ${page.path} (${page.group})`)
34
+ if (pages.length > max) lines.push(` ... and ${pages.length - max} more`)
35
+ return lines.join('\n')
36
+ }
37
+
38
+ const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`
39
+ // The base URL's path (http://localhost:3000/app) is not part of page paths.
40
+ const pagePathKey = (url, basePath) => {
41
+ let pathname = new URL(url).pathname
42
+ if (basePath && (pathname === basePath || pathname.startsWith(`${basePath}/`))) pathname = pathname.slice(basePath.length) || '/'
43
+ return pathname.replace(/\/+$/, '') || '/'
44
+ }
45
+ const boardTitle = (homeTitle, baseUrl) => (homeTitle && cutTitle(homeTitle, 60)) || titleFromBaseUrl(baseUrl) || new URL(baseUrl).host
46
+
47
+ // The config for "init --base-url" with discovery: the pages of
48
+ // <baseUrl>/sitemap.xml if it has any, else the pages the home page links
49
+ // to (two levels deep), else the home page alone. Prints how they were found.
50
+ // Returns { config, found: 'sitemap' | 'links' | 'none' }.
51
+ async function discoverConfig({ baseUrl, dir, fetch, out }) {
52
+ out(`Looking for pages on ${baseUrl} ...`)
53
+ const empty = { ...starterConfig({ baseUrl }), groups: [], pages: [] }
54
+ const sitemapUrl = defaultSitemapUrl(baseUrl)
55
+ // Discovery stays quick: no single request may take long.
56
+ const quick = (url, options = {}) =>
57
+ fetch(url, { ...options, signal: AbortSignal.any([options.signal, AbortSignal.timeout(DISCOVER_DEFAULTS.requestMs)].filter(Boolean)) })
58
+ let sitemapNote
59
+ try {
60
+ const result = await importSitemap({ raw: empty, dir, source: sitemapUrl, fetch: quick })
61
+ if (result.pages.length) {
62
+ const { homeTitle } = await discoverPages(baseUrl, { fetch, maxDepth: 0 })
63
+ const config = { ...result.raw, title: boardTitle(homeTitle, baseUrl), sitemap: sitemapUrl }
64
+ out(`Found ${plural(result.pages.length, 'page')} in ${sitemapUrl}:`)
65
+ out(pageLines(result.pages, 8))
66
+ return { config, found: 'sitemap' }
67
+ }
68
+ sitemapNote = 'no pages on this site'
69
+ } catch (error) {
70
+ sitemapNote = describeFetchError(error).replace(`${sitemapUrl}: `, '')
71
+ }
72
+
73
+ const crawl = await discoverPages(baseUrl, { fetch })
74
+ if (!crawl.pages.length) {
75
+ out(`Could not open ${baseUrl}: ${crawl.home.error}.`)
76
+ out('So the config gets just the home page ("/") for now.')
77
+ const config = { ...empty, title: boardTitle(null, baseUrl), groups: ['Pages'] }
78
+ config.pages = [{ id: 'home', path: '/', title: 'Home', group: 'Pages' }]
79
+ return { config, found: 'none' }
80
+ }
81
+ const basePath = new URL(baseUrl).pathname.replace(/\/+$/, '')
82
+ const siteTitle = crawl.homeTitle
83
+ const titles = new Map(crawl.pages.map((page, index) => [pagePathKey(page.url, basePath), index === 0 ? 'Home' : page.title]))
84
+ const { pages } = sitemapPages(
85
+ crawl.pages.map((page) => page.url),
86
+ { baseUrl, limit: DISCOVER_DEFAULTS.maxPages },
87
+ )
88
+ for (const page of pages) {
89
+ const own = titles.get(page.path.replace(/\/+$/, '') || '/')
90
+ const title = own === 'Home' ? 'Home' : pageTitle(own, siteTitle)
91
+ if (title) page.title = title
92
+ }
93
+ const config = addPagesToRaw({ ...empty, title: boardTitle(siteTitle, baseUrl) }, pages)
94
+ normalizeConfig(config, { dir })
95
+ const stopped = { pages: ` (stopped at ${DISCOVER_DEFAULTS.maxPages})`, time: ` (stopped after ${DISCOVER_DEFAULTS.totalMs / 1000} s)` }
96
+ out(`No sitemap at ${sitemapUrl} (${sitemapNote}), so Shapewall followed the links on your pages.`)
97
+ out(`Found ${plural(pages.length, 'page')}${stopped[crawl.stopped] || ''}:`)
98
+ out(pageLines(pages, 8))
99
+ if (crawl.failed.length) {
100
+ const shown = crawl.failed.slice(0, 3).map((item) => `${new URL(item.url).pathname} (${item.reason})`)
101
+ out(` left out ${plural(crawl.failed.length, 'link')} that did not open: ${shown.join(', ')}${crawl.failed.length > 3 ? ', ...' : ''}`)
102
+ }
103
+ return { config, found: 'links' }
104
+ }
105
+
106
+ export async function init(flags, out, { fetch }) {
107
+ const file = path.resolve(flags.config || CONFIG_FILE)
108
+ if (fs.existsSync(file) && !flags.force) throw new Error(`${file} already exists (use --force to overwrite)`)
109
+ const baseUrl = flags['base-url'] || 'http://localhost:3000'
110
+ if (!isHttp(baseUrl)) throw new Error(`--base-url: an http(s) URL such as https://example.com (got ${JSON.stringify(baseUrl)})`)
111
+ const givenBaseUrl = Boolean(flags['base-url'])
112
+ let config = starterConfig({ baseUrl })
113
+ const fromSitemap = flags.sitemap !== undefined
114
+ let found = null
115
+ if (givenBaseUrl && !fromSitemap) {
116
+ if (flags['no-discover']) {
117
+ // The bare config: the home page only, never example pages the site may not have.
118
+ config = { ...config, groups: ['Pages'], pages: [{ id: 'home', path: '/', title: 'Home', group: 'Pages' }] }
119
+ } else {
120
+ ;({ config, found } = await discoverConfig({ baseUrl, dir: path.dirname(file), fetch, out }))
121
+ }
122
+ }
123
+ if (fromSitemap) {
124
+ const given = flags.sitemap === true ? defaultSitemapUrl(baseUrl) : flags.sitemap
125
+ const source = isHttp(given) ? given : path.resolve(String(given))
126
+ // Recorded in the config (with the options given), so a later
127
+ // "shapewall sitemap" picks up new pages the same way.
128
+ const options = sitemapOptions(flags)
129
+ const recorded = isHttp(source) ? source : path.relative(path.dirname(file), source) || source
130
+ const extra = Object.fromEntries(Object.entries(options).filter(([, value]) => value !== null))
131
+ config = { ...config, groups: [], pages: [], sitemap: Object.keys(extra).length ? { source: recorded, ...extra } : recorded }
132
+ const result = await importSitemap({ raw: config, dir: path.dirname(file), source, ...options, fetch })
133
+ out(formatImport(result))
134
+ if (!result.pages.length) throw new Error('the sitemap has no pages Shapewall can use; nothing was written')
135
+ config = result.raw
136
+ out(pageLines(result.pages))
137
+ }
138
+ fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`)
139
+ out(`Wrote ${path.relative(process.cwd(), file) || file}`)
140
+ // Captures, comments and auth files stay out of git.
141
+ const gitignore = path.join(path.dirname(file), '.gitignore')
142
+ const wanted = ['.shapewall/', 'shapewall-export/', '*.auth.json']
143
+ const current = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, 'utf8') : ''
144
+ const missing = wanted.filter((line) => !current.split(/\r?\n/).includes(line))
145
+ if (missing.length) {
146
+ fs.writeFileSync(gitignore, `${current}${current && !current.endsWith('\n') ? '\n' : ''}# Shapewall\n${missing.join('\n')}\n`)
147
+ out(`Added ${missing.join(', ')} to .gitignore`)
148
+ }
149
+ out(initNextHint({ baseUrl, givenBaseUrl, fromSitemap, found, file: path.basename(file) }))
150
+ }
151
+
152
+ // The "Next:" line after init: only the steps still left to do. found is
153
+ // how discovery went ('sitemap', 'links', 'none'), or null without it.
154
+ export function initNextHint({ baseUrl, givenBaseUrl, fromSitemap, found = null, file = CONFIG_FILE }) {
155
+ const run = `run "${cliCommand('capture')}" and then "${cliCommand('serve --open')}"`
156
+ // Links and sitemaps stop at an app's front door, so say so where people start.
157
+ const app = 'App screens behind Start, a guest entry or sign-in need their own pages with actions (docs/config.md, "Capturing an app").'
158
+ if (fromSitemap) return `Next: make sure ${baseUrl} is up, then ${run}.\n${app}`
159
+ if (found === 'sitemap' || found === 'links') return `Next: ${run}.\n${app}`
160
+ if (found === 'none')
161
+ return (
162
+ `Next: start your site, then run "${cliCommand(`init --base-url ${baseUrl} --force`)}" again to find its pages,` +
163
+ ` or add pages by hand in ${file}. Then ${run}.\n${app}`
164
+ )
165
+ if (givenBaseUrl)
166
+ return `Next: list your pages in ${file} (or add them from a sitemap with "${cliCommand('sitemap <URL>')}"), start your site, then ${run}.\n${app}`
167
+ return (
168
+ `Next: start your site and run "${cliCommand('init --base-url <its URL> --force')}" so Shapewall finds its pages` +
169
+ ` (the pages in ${file} are examples), then ${run}.\n${app}`
170
+ )
171
+ }
172
+
173
+ // Adds a sitemap's pages to the config file (the raw JSON, so the rest of
174
+ // the file stays as it was written). Validated before anything is written.
175
+ export async function sitemap(positional, flags, out, { fetch }) {
176
+ const file = findConfigFile(flags.config)
177
+ let raw
178
+ try {
179
+ raw = JSON.parse(fs.readFileSync(file, 'utf8'))
180
+ } catch (error) {
181
+ if (error.code === 'ENOENT') throw new Error(`No config at ${file}. Run "shapewall init" (it takes --sitemap too).`, { cause: error })
182
+ throw new ConfigError([`not valid JSON: ${error.message}`], file)
183
+ }
184
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new ConfigError(['the config must be a JSON object'], file)
185
+ const source = positional[0] ? (isHttp(positional[0]) ? positional[0] : path.resolve(positional[0])) : null
186
+ const result = await importSitemap({
187
+ raw,
188
+ dir: path.dirname(file),
189
+ boardId: flags.board || null,
190
+ source,
191
+ ...sitemapOptions(flags),
192
+ fetch,
193
+ })
194
+ const dryRun = Boolean(flags['dry-run'])
195
+ if (result.pages.length && !dryRun) writeFileAtomic(file, `${JSON.stringify(result.raw, null, 2)}\n`)
196
+ if (flags.json) {
197
+ const report = { ...result, written: Boolean(result.pages.length && !dryRun), config: file }
198
+ delete report.raw
199
+ out(JSON.stringify(report, null, 2))
200
+ return
201
+ }
202
+ out(formatImport(result))
203
+ if (!result.pages.length) {
204
+ out('No new pages to add.')
205
+ return
206
+ }
207
+ out(pageLines(result.pages))
208
+ const count = `${result.pages.length} page${result.pages.length === 1 ? '' : 's'}`
209
+ out(
210
+ dryRun
211
+ ? `Dry run: would add ${count}; ${path.basename(file)} is unchanged.`
212
+ : `Added ${count} to ${path.relative(process.cwd(), file) || file}. Next: ${cliCommand('capture')}`,
213
+ )
214
+ }
@@ -0,0 +1,64 @@
1
+ // `shapewall github` and `shapewall doctor`.
2
+
3
+ import { getBoard, loadConfig } from '../config.js'
4
+ import { DEFAULT_PORT } from '../serve-state.js'
5
+ import { acpFlag } from './serve.js'
6
+
7
+ export async function github(positional, flags, out) {
8
+ const config = loadConfig(flags.config)
9
+ const { createIssue, linkPull, syncGithub } = await import('../github.js')
10
+ const action = positional[0]
11
+ const print = (value, line) => out(flags.json ? JSON.stringify(value, null, 2) : line)
12
+ if (action === 'issue') {
13
+ const id = positional[1]
14
+ if (!id) throw new Error('usage: shapewall github issue COMMENT_ID')
15
+ const board = getBoard(config, flags.board)
16
+ const result = await createIssue(config, { boardId: board.id, commentId: id })
17
+ print(
18
+ result,
19
+ `${result.created ? 'Opened' : 'Already has'} issue #${result.issue.number} for comment #${result.comment.id}: ${result.issue.url}`,
20
+ )
21
+ return
22
+ }
23
+ if (action === 'link') {
24
+ const [, id, pr] = positional
25
+ if (!id || !pr) throw new Error('usage: shapewall github link COMMENT_ID PR (12, #12 or the pull request URL)')
26
+ const board = getBoard(config, flags.board)
27
+ const result = await linkPull(config, { boardId: board.id, commentId: id, pr })
28
+ const merged = result.merged ? '; it has merged, so the comment is resolved' : ''
29
+ print(result, `Linked pull request #${result.pull.number} [${result.pull.state}] to comment #${result.comment.id}${merged}`)
30
+ return
31
+ }
32
+ if (action === 'sync') {
33
+ const result = await syncGithub(config, { log: out })
34
+ const lines = [`Read ${result.scanned} pull request${result.scanned === 1 ? '' : 's'} of ${result.repo}`]
35
+ for (const item of result.linked) lines.push(` linked #${item.pull} [${item.state}] to comment ${item.board}/${item.comment}`)
36
+ for (const item of result.merged) lines.push(` resolved comment ${item.board}/${item.comment} (pull request #${item.pull} merged)`)
37
+ for (const item of result.skipped) lines.push(` skipped comment ${item.board}/${item.comment} named by #${item.pull}: ${item.reason}`)
38
+ if (!result.linked.length && !result.skipped.length) lines.push(' nothing new')
39
+ print(result, lines.join('\n'))
40
+ return
41
+ }
42
+ throw new Error('usage: shapewall github issue|link|sync')
43
+ }
44
+
45
+ export async function doctor(flags, out) {
46
+ const { formatDoctor, installBrowser, runDoctor } = await import('../doctor.js')
47
+ if (flags['install-browser']) {
48
+ out('Downloading Chromium for Playwright...')
49
+ const code = await installBrowser()
50
+ if (code !== 0) throw new Error('the browser download failed (see above)')
51
+ }
52
+ const port = flags.port === undefined ? DEFAULT_PORT : Number(flags.port)
53
+ if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('--port must be a port number')
54
+ // --install-browser works anywhere (the demo runs it in the Shapewall clone): no config is a skip there.
55
+ const report = await runDoctor({
56
+ configFile: flags.config,
57
+ port,
58
+ launch: !flags['no-launch'],
59
+ acp: acpFlag(flags),
60
+ configOptional: Boolean(flags['install-browser']),
61
+ })
62
+ out(flags.json ? JSON.stringify(report, null, 2) : formatDoctor(report))
63
+ return report.ok ? 0 : 1
64
+ }
@@ -0,0 +1,87 @@
1
+ // Notifications: `shapewall notify`, and sending comment events while a command runs.
2
+
3
+ import { getBoard, loadConfig } from '../config.js'
4
+ import { MENTION_HANDLE_RE } from '../mentions.js'
5
+
6
+ // --mention NAME (with or without the @): a handle, or an error.
7
+ export function mentionFlag(value) {
8
+ if (value === undefined) return null
9
+ const handle = String(value).replace(/^@/, '').toLowerCase()
10
+ if (!MENTION_HANDLE_RE.test(handle)) throw new Error('--mention needs a name like robin or agent')
11
+ return handle
12
+ }
13
+
14
+ // Starts sending comment events to the configured channels; null when there
15
+ // are none. `serve: true` makes this the notifier for every process while it
16
+ // runs; otherwise only this process's own changes that no running server
17
+ // sends (src/notify/run.js). Log lines go to `log` (stderr for commands
18
+ // whose stdout is data).
19
+ export async function startNotifier(config, log, options = {}) {
20
+ if (!config.notifications?.channels.length) return null
21
+ const { startNotifications } = await import('../notify/run.js')
22
+ return startNotifications(config, { log, ...options })
23
+ }
24
+
25
+ // Runs `work` with notifications on, then waits (up to 15 s) for its
26
+ // messages to go out before the command exits.
27
+ export async function withNotifications(config, log, work) {
28
+ const notifier = await startNotifier(config, log)
29
+ try {
30
+ return await work()
31
+ } finally {
32
+ if (notifier) {
33
+ if (!(await notifier.flush(15000))) log('notify: some messages were not sent before exit')
34
+ notifier.stop()
35
+ }
36
+ }
37
+ }
38
+
39
+ export async function notify(positional, flags, out) {
40
+ const config = loadConfig(flags.config)
41
+ const { createNotifier, describeChannels, testEvent } = await import('../notify/index.js')
42
+ const action = positional[0] || 'list'
43
+ const people = Object.keys(config.notifications.people)
44
+ if (action === 'list') {
45
+ const list = describeChannels(config)
46
+ if (flags.json) {
47
+ out(JSON.stringify({ channels: list, people }, null, 2))
48
+ return 0
49
+ }
50
+ if (!list.length) {
51
+ out('No notification channels. Add notifications.channels to the config, or set SHAPEWALL_SLACK_WEBHOOK_URL (docs/notifications.md).')
52
+ return 0
53
+ }
54
+ for (const item of list) {
55
+ const email =
56
+ item.type === 'email'
57
+ ? `, ${item.mode === 'off' ? 'off' : `via ${item.mode}`}, ${item.to} fixed recipient${item.to === 1 ? '' : 's'}`
58
+ : ''
59
+ const boards = item.boards ? ` boards: ${item.boards.join(', ')}` : ''
60
+ out(`${item.id} ${item.type}${item.fromEnv ? ' (from the environment)' : ''}${email}`)
61
+ out(` events: ${item.events.map((name) => name.replace(/^comment\./, '')).join(', ')}${boards}`)
62
+ out(` ${item.ready ? 'ready' : `not ready: set ${item.missing.join(' and ')}`}`)
63
+ }
64
+ if (people.length) out(`People mapped for mentions: ${people.map((handle) => `@${handle}`).join(', ')}`)
65
+ return 0
66
+ }
67
+ if (action === 'test') {
68
+ const channel = config.notifications.channels.find((item) => item.id === positional[1])
69
+ if (!channel) {
70
+ const have = config.notifications.channels.map((item) => item.id)
71
+ throw new Error(`usage: shapewall notify test CHANNEL (${have.length ? `have: ${have.join(', ')}` : 'no channels configured'})`)
72
+ }
73
+ const to = typeof flags.to === 'string' ? [flags.to] : undefined
74
+ if (channel.type === 'email' && !to && !channel.to.length) throw new Error('this email channel has no "to" addresses; pass --to EMAIL')
75
+ const notifier = createNotifier(config)
76
+ const result = await notifier.deliver(channel, testEvent(config, getBoard(config, flags.board).id), { to })
77
+ notifier.stop()
78
+ if (result.ok) {
79
+ out(result.file ? `Wrote a test message to ${result.file}` : `Sent a test message to ${channel.id} (HTTP ${result.status})`)
80
+ return 0
81
+ }
82
+ const attempts = result.attempts > 1 ? ` (after ${result.attempts} attempts)` : ''
83
+ out(`Could not send to ${channel.id}: ${result.error}${attempts}`)
84
+ return 1
85
+ }
86
+ throw new Error(`unknown notify action "${action}" (list, test)`)
87
+ }
@@ -0,0 +1,22 @@
1
+ // Opening a URL in the default browser.
2
+
3
+ import { spawn } from 'node:child_process'
4
+
5
+ // Opens a URL in the default browser (xdg-open, open, start), without a
6
+ // shell and without waiting. Failing to open is a note, not an error.
7
+ export function openerFor(platform = process.platform) {
8
+ if (platform === 'darwin') return { command: 'open', args: [] }
9
+ if (platform === 'win32') return { command: 'explorer.exe', args: [] }
10
+ return { command: 'xdg-open', args: [] }
11
+ }
12
+
13
+ export function openBrowser(url, out, { spawnImpl = spawn } = {}) {
14
+ const { command, args } = openerFor()
15
+ try {
16
+ const child = spawnImpl(command, [...args, url], { stdio: 'ignore', detached: true, shell: false, windowsHide: true })
17
+ child.once('error', (error) => out(`Could not open a browser (${command}: ${error.code || error.message}); open ${url} yourself.`))
18
+ child.unref()
19
+ } catch (error) {
20
+ out(`Could not open a browser (${error.message}); open ${url} yourself.`)
21
+ }
22
+ }