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,275 @@
1
+ // The `notifications` block of shapewall.config.json. The config holds only
2
+ // the names of environment variables for anything secret (webhook URLs with
3
+ // tokens in them, signing secrets, API keys), never the values, so a config
4
+ // file, an export or a log line can never carry a secret. Values are read
5
+ // from the environment when a message is sent.
6
+ //
7
+ // Without a `channels` list, channels come from the environment alone:
8
+ // SHAPEWALL_WEBHOOK_URL (+ SHAPEWALL_WEBHOOK_SECRET), SHAPEWALL_SLACK_WEBHOOK_URL,
9
+ // SHAPEWALL_DISCORD_WEBHOOK_URL, and RESEND_API_KEY with SHAPEWALL_EMAIL_FROM.
10
+
11
+ import { COMMENT_EVENTS } from '../events.js'
12
+ import { MENTION_HANDLE_RE } from '../mentions.js'
13
+
14
+ export const CHANNEL_TYPES = ['webhook', 'slack', 'discord', 'email']
15
+ export const ENV_NAME_RE = /^[A-Z_][A-Z0-9_]{0,63}$/
16
+ // The variables an email channel may read its API key from.
17
+ export const EMAIL_KEY_ENV_RE = /^(RESEND_API_KEY|SHAPEWALL_[A-Z0-9_]{1,54})$/
18
+ // Shapewall's own secrets for other services are not an email key either.
19
+ const NOT_EMAIL_KEYS = new Set([
20
+ 'SHAPEWALL_GITHUB_TOKEN',
21
+ 'SHAPEWALL_GITHUB_WEBHOOK_SECRET',
22
+ 'SHAPEWALL_AGENT_API_KEY',
23
+ 'SHAPEWALL_WEBHOOK_SECRET',
24
+ 'SHAPEWALL_TOKEN',
25
+ 'SHAPEWALL_UPDATE_TOKEN',
26
+ 'SHAPEWALL_ACCOUNT_SETUP_TOKEN',
27
+ ])
28
+ const CHANNEL_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/
29
+ const CHANNELS_MAX = 20
30
+ const PEOPLE_MAX = 500
31
+ const RETRIES_MAX = 10
32
+ export const RETRIES_DEFAULT = 3
33
+ // A simple address check; the email service has the last word.
34
+ const EMAIL_RE = /^[^\s@<>"]{1,64}@[^\s@<>"]{1,190}\.[^\s@<>"]{2,}$/
35
+ const SLACK_ID_RE = /^[UW][A-Z0-9]{2,20}$/
36
+ const DISCORD_ID_RE = /^[0-9]{5,25}$/
37
+
38
+ // Chat channels ping mapped people inside the created/replied message, so a
39
+ // separate mentioned message would be a duplicate; email is for mentions.
40
+ export const DEFAULT_EVENTS = {
41
+ webhook: [...COMMENT_EVENTS],
42
+ slack: ['comment.created', 'comment.replied', 'comment.resolved', 'comment.reopened'],
43
+ discord: ['comment.created', 'comment.replied', 'comment.resolved', 'comment.reopened'],
44
+ email: ['comment.mentioned'],
45
+ }
46
+
47
+ export const DEFAULT_ENV = {
48
+ webhook: { urlEnv: 'SHAPEWALL_WEBHOOK_URL', secretEnv: 'SHAPEWALL_WEBHOOK_SECRET' },
49
+ slack: { urlEnv: 'SHAPEWALL_SLACK_WEBHOOK_URL' },
50
+ discord: { urlEnv: 'SHAPEWALL_DISCORD_WEBHOOK_URL' },
51
+ email: { apiKeyEnv: 'RESEND_API_KEY' },
52
+ }
53
+
54
+ // Keys that look like a secret value in the config file: refused, with a
55
+ // pointer to the *Env key that names the variable instead.
56
+ const SECRET_KEYS = { secret: 'secretEnv', apiKey: 'apiKeyEnv', token: 'secretEnv', password: 'secretEnv', key: 'apiKeyEnv' }
57
+
58
+ const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
59
+
60
+ function isHttpUrl(value) {
61
+ try {
62
+ return ['http:', 'https:'].includes(new URL(value).protocol)
63
+ } catch {
64
+ return false
65
+ }
66
+ }
67
+
68
+ // "created" and "comment.created" both work; "*" or "all" is every event.
69
+ function normalizeEvents(raw, where, problems) {
70
+ if (!Array.isArray(raw) || !raw.length) {
71
+ problems.push(`${where}: a non-empty list of ${COMMENT_EVENTS.join(', ')} (or "all")`)
72
+ return []
73
+ }
74
+ if (raw.some((item) => item === '*' || item === 'all')) return [...COMMENT_EVENTS]
75
+ const out = []
76
+ for (const item of raw) {
77
+ const name = typeof item === 'string' ? (item.startsWith('comment.') ? item : `comment.${item}`) : ''
78
+ if (!COMMENT_EVENTS.includes(name)) problems.push(`${where}: unknown event ${JSON.stringify(item)} (use ${COMMENT_EVENTS.join(', ')})`)
79
+ else if (!out.includes(name)) out.push(name)
80
+ }
81
+ return out
82
+ }
83
+
84
+ function envName(value, where, problems) {
85
+ if (value === undefined || value === null) return null
86
+ if (typeof value !== 'string' || !ENV_NAME_RE.test(value)) {
87
+ problems.push(`${where}: the name of an environment variable, like SHAPEWALL_SLACK_WEBHOOK_URL`)
88
+ return null
89
+ }
90
+ return value
91
+ }
92
+
93
+ function emailList(value, where, problems) {
94
+ if (value === undefined || value === null) return []
95
+ const list = typeof value === 'string' ? [value] : value
96
+ if (!Array.isArray(list) || list.length > 50 || list.some((item) => typeof item !== 'string' || !EMAIL_RE.test(item.trim()))) {
97
+ problems.push(`${where}: an email address or a list of up to 50`)
98
+ return []
99
+ }
100
+ return list.map((item) => item.trim())
101
+ }
102
+
103
+ function validateChannel(raw, where, boardIds, problems) {
104
+ if (!isObject(raw)) {
105
+ problems.push(`${where}: a channel is an object with id and type`)
106
+ return null
107
+ }
108
+ const before = problems.length
109
+ const type = raw.type
110
+ if (!CHANNEL_TYPES.includes(type)) problems.push(`${where}.type: one of ${CHANNEL_TYPES.join(', ')} (got ${JSON.stringify(type)})`)
111
+ const id = raw.id ?? type
112
+ if (typeof id !== 'string' || !CHANNEL_ID_RE.test(id)) problems.push(`${where}.id: lowercase letters, digits and dashes`)
113
+ for (const [key, instead] of Object.entries(SECRET_KEYS)) {
114
+ if (raw[key] !== undefined)
115
+ problems.push(`${where}.${key}: never put secrets in the config; set ${instead} to the name of an environment variable`)
116
+ }
117
+ const defaults = DEFAULT_ENV[type] || {}
118
+ const channel = { id, type, events: DEFAULT_EVENTS[type] || [], boards: null }
119
+ if (raw.events !== undefined) channel.events = normalizeEvents(raw.events, `${where}.events`, problems)
120
+ if (raw.boards !== undefined) {
121
+ if (!Array.isArray(raw.boards) || !raw.boards.length || raw.boards.some((item) => !boardIds.includes(item))) {
122
+ problems.push(`${where}.boards: board ids from this config (${boardIds.join(', ')})`)
123
+ } else channel.boards = [...raw.boards]
124
+ }
125
+ if (type === 'webhook' || type === 'slack' || type === 'discord') {
126
+ // Slack and Discord webhook URLs are the secret, so only by name. A
127
+ // generic webhook may give its URL here; its signing secret is by name.
128
+ if (raw.url !== undefined && type !== 'webhook') {
129
+ problems.push(`${where}.url: a ${type} webhook URL is a secret; set urlEnv to the name of an environment variable instead`)
130
+ } else if (raw.url !== undefined && !isHttpUrl(raw.url)) problems.push(`${where}.url: an http(s) URL`)
131
+ channel.url = type === 'webhook' && isHttpUrl(raw.url) ? raw.url : null
132
+ channel.urlEnv = envName(raw.urlEnv, `${where}.urlEnv`, problems) || (channel.url ? null : defaults.urlEnv)
133
+ if (type === 'webhook') channel.secretEnv = envName(raw.secretEnv, `${where}.secretEnv`, problems) || defaults.secretEnv
134
+ }
135
+ if (type === 'email') {
136
+ channel.apiKeyEnv = envName(raw.apiKeyEnv, `${where}.apiKeyEnv`, problems) || defaults.apiKeyEnv
137
+ // The key goes to the email service as a bearer token, and the config is
138
+ // usually committed: it may name the email key or a variable made for
139
+ // Shapewall, never another tool's secret (GITHUB_TOKEN, a model key).
140
+ if (!EMAIL_KEY_ENV_RE.test(channel.apiKeyEnv) || NOT_EMAIL_KEYS.has(channel.apiKeyEnv)) {
141
+ problems.push(
142
+ `${where}.apiKeyEnv: RESEND_API_KEY or a variable whose name starts with SHAPEWALL_ (got ${JSON.stringify(raw.apiKeyEnv)}); other variables are not sent to the email service`,
143
+ )
144
+ channel.apiKeyEnv = defaults.apiKeyEnv
145
+ }
146
+ const from = typeof raw.from === 'string' ? raw.from.trim() : ''
147
+ const address = /<([^>]+)>$/.exec(from)?.[1] || from
148
+ if (!EMAIL_RE.test(address))
149
+ problems.push(`${where}.from: the sender, "Name <reviews@example.com>" on a domain your email service sends for`)
150
+ channel.from = from
151
+ channel.to = emailList(raw.to, `${where}.to`, problems)
152
+ // With no API key, write each message to <outputDir>/notifications/outbox/
153
+ // as an .eml file instead (for trying it out, or a local mail pickup).
154
+ if (raw.fallback !== undefined && raw.fallback !== null && raw.fallback !== 'none' && raw.fallback !== 'outbox') {
155
+ problems.push(`${where}.fallback: "outbox" or "none" (the default)`)
156
+ }
157
+ channel.fallback = raw.fallback === 'outbox' ? 'outbox' : 'none'
158
+ }
159
+ return problems.length > before ? null : channel
160
+ }
161
+
162
+ function validatePeople(raw, problems) {
163
+ if (raw === undefined) return {}
164
+ if (!isObject(raw) || Object.keys(raw).length > PEOPLE_MAX) {
165
+ problems.push(`notifications.people: an object keyed by mention handle, like { "robin": { "email": "robin@example.com" } }`)
166
+ return {}
167
+ }
168
+ const out = {}
169
+ for (const [key, value] of Object.entries(raw)) {
170
+ const handle = key.replace(/^@/, '').toLowerCase()
171
+ const where = `notifications.people.${key}`
172
+ if (!MENTION_HANDLE_RE.test(handle)) {
173
+ problems.push(`${where}: a mention handle (letters, digits, dots, dashes, underscores; starts with a letter)`)
174
+ continue
175
+ }
176
+ if (!isObject(value)) {
177
+ problems.push(`${where}: { "email", "slack", "discord" } (any of them)`)
178
+ continue
179
+ }
180
+ const person = {}
181
+ if (value.email !== undefined) {
182
+ if (typeof value.email !== 'string' || !EMAIL_RE.test(value.email.trim())) problems.push(`${where}.email: an email address`)
183
+ else person.email = value.email.trim()
184
+ }
185
+ if (value.slack !== undefined) {
186
+ if (typeof value.slack !== 'string' || !SLACK_ID_RE.test(value.slack))
187
+ problems.push(`${where}.slack: a Slack member id like U012AB3CD`)
188
+ else person.slack = value.slack
189
+ }
190
+ if (value.discord !== undefined) {
191
+ if (typeof value.discord !== 'string' || !DISCORD_ID_RE.test(value.discord))
192
+ problems.push(`${where}.discord: a Discord user id (digits)`)
193
+ else person.discord = value.discord
194
+ }
195
+ out[handle] = person
196
+ }
197
+ return out
198
+ }
199
+
200
+ // Channels from the environment alone, for a config without a channel list.
201
+ export function channelsFromEnv(env = process.env) {
202
+ const channels = []
203
+ if (env.SHAPEWALL_WEBHOOK_URL)
204
+ channels.push({ id: 'webhook', type: 'webhook', events: DEFAULT_EVENTS.webhook, boards: null, url: null, ...DEFAULT_ENV.webhook })
205
+ if (env.SHAPEWALL_SLACK_WEBHOOK_URL)
206
+ channels.push({ id: 'slack', type: 'slack', events: DEFAULT_EVENTS.slack, boards: null, url: null, ...DEFAULT_ENV.slack })
207
+ if (env.SHAPEWALL_DISCORD_WEBHOOK_URL)
208
+ channels.push({ id: 'discord', type: 'discord', events: DEFAULT_EVENTS.discord, boards: null, url: null, ...DEFAULT_ENV.discord })
209
+ if (env.RESEND_API_KEY && env.SHAPEWALL_EMAIL_FROM) {
210
+ const to = String(env.SHAPEWALL_EMAIL_TO || '')
211
+ .split(',')
212
+ .map((item) => item.trim())
213
+ .filter((item) => EMAIL_RE.test(item))
214
+ channels.push({
215
+ id: 'email',
216
+ type: 'email',
217
+ events: DEFAULT_EVENTS.email,
218
+ boards: null,
219
+ ...DEFAULT_ENV.email,
220
+ from: env.SHAPEWALL_EMAIL_FROM,
221
+ to,
222
+ fallback: 'none',
223
+ })
224
+ }
225
+ return channels.map((channel) => ({ ...channel, fromEnv: true }))
226
+ }
227
+
228
+ // Returns { boardUrl, retries, people, channels }. Pushes problems.
229
+ export function normalizeNotifications(raw, { boardIds = [], env = process.env } = {}, problems = []) {
230
+ const out = { boardUrl: null, retries: RETRIES_DEFAULT, people: {}, channels: [] }
231
+ if (raw !== undefined && !isObject(raw)) {
232
+ problems.push('notifications: an object with channels (see docs/notifications.md)')
233
+ return out
234
+ }
235
+ const value = raw || {}
236
+ if (value.boardUrl !== undefined && value.boardUrl !== null) {
237
+ if (!isHttpUrl(value.boardUrl)) problems.push('notifications.boardUrl: the http(s) URL people open the board at')
238
+ else out.boardUrl = value.boardUrl
239
+ }
240
+ if (value.retries !== undefined) {
241
+ if (!Number.isInteger(value.retries) || value.retries < 0 || value.retries > RETRIES_MAX) {
242
+ problems.push(`notifications.retries: a whole number from 0 to ${RETRIES_MAX}`)
243
+ } else out.retries = value.retries
244
+ }
245
+ out.people = validatePeople(value.people, problems)
246
+ if (value.channels === undefined) {
247
+ out.channels = channelsFromEnv(env)
248
+ return out
249
+ }
250
+ if (!Array.isArray(value.channels) || value.channels.length > CHANNELS_MAX) {
251
+ problems.push(`notifications.channels: a list of up to ${CHANNELS_MAX} channels`)
252
+ return out
253
+ }
254
+ out.channels = value.channels
255
+ .map((channel, index) => validateChannel(channel, `notifications.channels[${index}]`, boardIds, problems))
256
+ .filter(Boolean)
257
+ const seen = new Set()
258
+ for (const channel of out.channels) {
259
+ if (seen.has(channel.id)) problems.push(`notifications.channels: duplicate channel id "${channel.id}"`)
260
+ seen.add(channel.id)
261
+ }
262
+ return out
263
+ }
264
+
265
+ // What a channel still needs from the environment: [] when it can send.
266
+ export function missingEnv(channel, env = process.env) {
267
+ const missing = []
268
+ if (channel.type === 'email') {
269
+ if (!env[channel.apiKeyEnv] && channel.fallback !== 'outbox') missing.push(channel.apiKeyEnv)
270
+ return missing
271
+ }
272
+ if (!channel.url && !env[channel.urlEnv]) missing.push(channel.urlEnv)
273
+ if (channel.type === 'webhook' && !env[channel.secretEnv]) missing.push(channel.secretEnv)
274
+ return missing
275
+ }
@@ -0,0 +1,301 @@
1
+ // Notifications: comment events (src/events.js) sent to webhooks, Slack,
2
+ // Discord and email (Resend). Off unless channels are configured.
3
+ //
4
+ // - Never on the request path: an event is queued and the change that made it
5
+ // returns at once. Each channel has its own queue, sent in order.
6
+ // - Retries with exponential backoff on network errors, timeouts, 408, 429
7
+ // (honouring Retry-After) and 5xx; other answers are final.
8
+ // - Secrets come from the environment when a message is sent. Log lines name
9
+ // the channel, the event and the HTTP status, never a URL, a header or a body.
10
+ //
11
+ // See docs/notifications.md.
12
+
13
+ import fs from 'node:fs'
14
+ import path from 'node:path'
15
+ import { createHmac, randomUUID } from 'node:crypto'
16
+ import { setTimeout as sleep } from 'node:timers/promises'
17
+ import { onCommentEvent } from '../events.js'
18
+ import { boardUrlFor, discordMessage, emailMessage, emailRecipients, slackMessage, webhookPayload } from './messages.js'
19
+ import { missingEnv } from './config.js'
20
+
21
+ export const RESEND_URL = 'https://api.resend.com/emails'
22
+ const QUEUE_MAX = 200
23
+ const RETRY_AFTER_MAX_MS = 60000
24
+ const USER_AGENT = 'Shapewall-Notifications'
25
+
26
+ export function signPayload(secret, timestamp, body) {
27
+ return `sha256=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`
28
+ }
29
+
30
+ const retryable = (status) => status === 408 || status === 429 || status >= 500
31
+
32
+ function retryAfterMs(value) {
33
+ if (!value) return null
34
+ const seconds = Number(value)
35
+ if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000)
36
+ const date = Date.parse(value)
37
+ return Number.isFinite(date) ? Math.max(0, date - Date.now()) : null
38
+ }
39
+
40
+ // Why a send failed, without anything that could hold a secret (a fetch error
41
+ // can quote the URL).
42
+ function reason(error) {
43
+ if (error?.name === 'TimeoutError' || error?.name === 'AbortError') return 'timed out'
44
+ const code = error?.cause?.code || error?.code
45
+ return code ? `network error (${code})` : 'network error'
46
+ }
47
+
48
+ export function channelMatches(channel, event) {
49
+ if (event.type === 'notify.test') return true
50
+ if (!channel.events.includes(event.type)) return false
51
+ return !channel.boards || channel.boards.includes(event.boardId)
52
+ }
53
+
54
+ // createNotifier(config, options) -> { channels, start, stop, flush, deliver, handle }
55
+ // Options: env, fetch, log, boardUrl (fallback for the deep links: the URL
56
+ // `serve` listens on), backoffMs (first retry wait), timeoutMs (per request).
57
+ export function createNotifier(
58
+ config,
59
+ { env = process.env, fetch = globalThis.fetch, log = () => {}, boardUrl = null, backoffMs = 1000, timeoutMs = 10000 } = {},
60
+ ) {
61
+ const settings = config.notifications || { channels: [], retries: 0, people: {} }
62
+ const channels = settings.channels
63
+ const stopper = new AbortController()
64
+ const queues = new Map(channels.map((channel) => [channel.id, { items: [], running: false }]))
65
+ const warned = new Set()
66
+ let idleWaiters = []
67
+ let unsubscribe = null
68
+ const linkBase = () => boardUrlFor(config, { boardUrl, env })
69
+
70
+ const busy = () => [...queues.values()].some((queue) => queue.running || queue.items.length)
71
+ const settleIdle = () => {
72
+ if (busy()) return
73
+ const waiters = idleWaiters
74
+ idleWaiters = []
75
+ for (const resolve of waiters) resolve()
76
+ }
77
+
78
+ // One request -> { ok, status, retryAfter }; throws on network errors.
79
+ async function post(url, { headers = {}, body }) {
80
+ const signal = AbortSignal.any([AbortSignal.timeout(timeoutMs), stopper.signal])
81
+ const response = await fetch(url, {
82
+ method: 'POST',
83
+ headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT, ...headers },
84
+ body,
85
+ signal,
86
+ redirect: 'error',
87
+ })
88
+ // Read and drop the body so the connection can be reused.
89
+ await response.arrayBuffer().catch(() => null)
90
+ return { ok: response.ok, status: response.status, retryAfter: retryAfterMs(response.headers.get('retry-after')) }
91
+ }
92
+
93
+ // What to send for an event on a channel: { url, headers, body } or
94
+ // { outbox: text }, or { skip: why } when there is nothing to send.
95
+ function prepare(channel, event, overrides = {}) {
96
+ const base = linkBase()
97
+ if (channel.type === 'slack') return { url: env[channel.urlEnv], body: JSON.stringify(slackMessage(config, event, base)) }
98
+ if (channel.type === 'discord') return { url: env[channel.urlEnv], body: JSON.stringify(discordMessage(config, event, base)) }
99
+ if (channel.type === 'webhook') {
100
+ const body = JSON.stringify(webhookPayload(config, event, base))
101
+ const timestamp = String(Math.floor(Date.now() / 1000))
102
+ return {
103
+ url: channel.url || env[channel.urlEnv],
104
+ body,
105
+ headers: {
106
+ 'X-Shapewall-Event': event.type,
107
+ 'X-Shapewall-Delivery': event.id,
108
+ 'X-Shapewall-Timestamp': timestamp,
109
+ 'X-Shapewall-Signature': signPayload(env[channel.secretEnv], timestamp, body),
110
+ },
111
+ }
112
+ }
113
+ // Email
114
+ const to = overrides.to || emailRecipients(config, channel, event)
115
+ if (!to.length)
116
+ return { skip: event.type === 'comment.mentioned' ? `no email for @${event.handle} in notifications.people` : 'no "to" addresses' }
117
+ const message = emailMessage(config, channel, event, base, to)
118
+ if (!env[channel.apiKeyEnv]) return { outbox: message }
119
+ return {
120
+ url: env.SHAPEWALL_RESEND_URL || RESEND_URL,
121
+ body: JSON.stringify(message),
122
+ headers: { Authorization: `Bearer ${env[channel.apiKeyEnv]}`, 'Idempotency-Key': `${event.id}-${channel.id}` },
123
+ }
124
+ }
125
+
126
+ function writeOutbox(channel, event, message) {
127
+ const dir = path.join(config.outputDir, 'notifications', 'outbox')
128
+ fs.mkdirSync(dir, { recursive: true })
129
+ const file = path.join(dir, `${new Date().toISOString().replace(/[:.]/g, '-')}-${channel.id}-${event.id.slice(0, 8)}.eml`)
130
+ const header = (value) => String(value).replace(/[\r\n]+/g, ' ')
131
+ // Headers are ASCII; anything else in the subject is RFC 2047 encoded.
132
+ const subject = header(message.subject)
133
+ const encoded = /^[\x20-\x7e]*$/.test(subject) ? subject : `=?UTF-8?B?${Buffer.from(subject).toString('base64')}?=`
134
+ const eml = [
135
+ `From: ${header(message.from)}`,
136
+ `To: ${message.to.map(header).join(', ')}`,
137
+ `Subject: ${encoded}`,
138
+ `Date: ${new Date().toUTCString()}`,
139
+ `Message-ID: <${event.id}.${channel.id}@shapewall.local>`,
140
+ 'MIME-Version: 1.0',
141
+ 'Content-Type: text/plain; charset=utf-8',
142
+ '',
143
+ message.text,
144
+ ].join('\r\n')
145
+ fs.writeFileSync(file, eml, { mode: 0o600 })
146
+ return file
147
+ }
148
+
149
+ // Sends one event on one channel, with retries. Resolves with
150
+ // { ok, attempts, status, error, skipped, file }; never rejects.
151
+ async function deliver(channel, event, overrides = {}) {
152
+ const missing = missingEnv(channel, env)
153
+ if (missing.length) return { ok: false, attempts: 0, skipped: true, error: `set ${missing.join(' and ')}` }
154
+ let request
155
+ try {
156
+ request = prepare(channel, event, overrides)
157
+ } catch (error) {
158
+ return { ok: false, attempts: 0, error: `could not build the message (${error.message})` }
159
+ }
160
+ if (request.skip) return { ok: false, attempts: 0, skipped: true, error: request.skip }
161
+ if (request.outbox) {
162
+ try {
163
+ return { ok: true, attempts: 1, file: writeOutbox(channel, event, request.outbox) }
164
+ } catch (error) {
165
+ return { ok: false, attempts: 1, error: `could not write the outbox (${error.code || 'error'})` }
166
+ }
167
+ }
168
+ const retries = overrides.retries ?? settings.retries
169
+ let last = { ok: false, attempts: 0, error: 'not sent' }
170
+ for (let attempt = 0; attempt <= retries; attempt += 1) {
171
+ if (stopper.signal.aborted) return { ...last, error: 'stopped' }
172
+ let wait = null
173
+ try {
174
+ const result = await post(request.url, request)
175
+ last = { ok: result.ok, attempts: attempt + 1, status: result.status, error: result.ok ? null : `HTTP ${result.status}` }
176
+ if (result.ok || !retryable(result.status)) return last
177
+ wait = result.retryAfter
178
+ } catch (error) {
179
+ if (stopper.signal.aborted) return { ...last, attempts: attempt + 1, error: 'stopped' }
180
+ last = { ok: false, attempts: attempt + 1, error: reason(error) }
181
+ }
182
+ if (attempt === retries) break
183
+ const backoff = backoffMs * 2 ** attempt * (0.75 + Math.random() * 0.5)
184
+ try {
185
+ await sleep(Math.min(wait ?? backoff, RETRY_AFTER_MAX_MS), null, { signal: stopper.signal })
186
+ } catch {
187
+ return { ...last, error: 'stopped' }
188
+ }
189
+ }
190
+ return last
191
+ }
192
+
193
+ async function drain(channel) {
194
+ const queue = queues.get(channel.id)
195
+ if (queue.running) return
196
+ queue.running = true
197
+ try {
198
+ while (queue.items.length && !stopper.signal.aborted) {
199
+ const event = queue.items.shift()
200
+ const result = await deliver(channel, event)
201
+ const what = `${event.type}${event.commentId ? ` #${event.commentId}` : ''}`
202
+ if (result.ok) log(`notify: ${channel.id} sent ${what}${result.file ? ' to the outbox' : ''}`)
203
+ else if (result.skipped) {
204
+ const key = `${channel.id}:${result.error}`
205
+ if (!warned.has(key)) log(`notify: ${channel.id} skipped ${what}: ${result.error}`)
206
+ warned.add(key)
207
+ } else
208
+ log(`notify: ${channel.id} failed ${what} after ${result.attempts} attempt${result.attempts === 1 ? '' : 's'}: ${result.error}`)
209
+ }
210
+ } finally {
211
+ queue.running = false
212
+ settleIdle()
213
+ }
214
+ }
215
+
216
+ // Queues an event for every channel that wants it. Synchronous and cheap.
217
+ function handle(event) {
218
+ if (stopper.signal.aborted) return
219
+ for (const channel of channels) {
220
+ if (!channelMatches(channel, event)) continue
221
+ const queue = queues.get(channel.id)
222
+ if (queue.items.length >= QUEUE_MAX) {
223
+ queue.items.shift()
224
+ log(`notify: ${channel.id} queue full, dropped the oldest message`)
225
+ }
226
+ queue.items.push(event)
227
+ setImmediate(() => drain(channel))
228
+ }
229
+ }
230
+
231
+ return {
232
+ channels,
233
+ handle,
234
+ deliver,
235
+ // Starts listening for comment events in this process.
236
+ start() {
237
+ if (!unsubscribe && channels.length) unsubscribe = onCommentEvent(handle)
238
+ return this
239
+ },
240
+ // Resolves once every queue is empty, or after `ms`, whichever is first.
241
+ flush(ms = 15000) {
242
+ if (!busy()) return Promise.resolve(true)
243
+ return new Promise((resolve) => {
244
+ const timer = setTimeout(() => resolve(false), ms)
245
+ timer.unref?.()
246
+ idleWaiters.push(() => {
247
+ clearTimeout(timer)
248
+ resolve(true)
249
+ })
250
+ })
251
+ },
252
+ // Stops listening and drops what is still queued.
253
+ stop() {
254
+ unsubscribe?.()
255
+ unsubscribe = null
256
+ stopper.abort()
257
+ for (const queue of queues.values()) queue.items = []
258
+ settleIdle()
259
+ },
260
+ }
261
+ }
262
+
263
+ // A sample event for `shapewall notify test`: a made-up comment on the
264
+ // board's first page, marked as a test so nobody mistakes it for real.
265
+ export function testEvent(config, boardId = config.boards[0].id) {
266
+ const board = config.boards.find((item) => item.id === boardId) || config.boards[0]
267
+ const page = board.pages[0]
268
+ const now = new Date().toISOString()
269
+ return {
270
+ id: randomUUID(),
271
+ type: 'notify.test',
272
+ at: now,
273
+ boardId: board.id,
274
+ commentId: null,
275
+ comment: null,
276
+ test: true,
277
+ page: page ? { id: page.id, title: page.title } : null,
278
+ }
279
+ }
280
+
281
+ // Channels with what each needs, for `notify list` and `doctor`. Names of
282
+ // environment variables only, never their values.
283
+ export function describeChannels(config, env = process.env) {
284
+ return (config.notifications?.channels || []).map((channel) => {
285
+ const missing = missingEnv(channel, env)
286
+ const info = {
287
+ id: channel.id,
288
+ type: channel.type,
289
+ events: channel.events,
290
+ boards: channel.boards,
291
+ ready: !missing.length,
292
+ missing,
293
+ fromEnv: Boolean(channel.fromEnv),
294
+ }
295
+ if (channel.type === 'email') {
296
+ info.to = channel.to.length
297
+ info.mode = env[channel.apiKeyEnv] ? 'resend' : channel.fallback === 'outbox' ? 'outbox' : 'off'
298
+ }
299
+ return info
300
+ })
301
+ }
@@ -0,0 +1,73 @@
1
+ // The notifier lease: <outputDir>/notifier.json says which `shapewall serve`
2
+ // sends notifications for this output folder, so a change is sent once
3
+ // whichever process made it.
4
+ //
5
+ // { pid, start, startedAt, heartbeatAt }. Taken with the same exclusive
6
+ // create as the capture lock (src/lock.js), so two servers never both hold
7
+ // it; the holder rewrites heartbeatAt every HEARTBEAT_MS. A lease is live
8
+ // while its process runs (pid + start time) and its heartbeat is fresh.
9
+ //
10
+ // The rule both sides follow: an event at or after the lease's startedAt is
11
+ // the server's to send (it reads it from the event log); anything earlier,
12
+ // or any event when no live lease exists, the process that made it sends.
13
+
14
+ import fs from 'node:fs'
15
+ import path from 'node:path'
16
+ import { acquireLock, isLockLive, readLock, releaseLock } from '../lock.js'
17
+ import { writeJsonAtomic } from '../store.js'
18
+
19
+ export const LEASE_FILE = 'notifier.json'
20
+ export const HEARTBEAT_MS = 10000
21
+ export const LEASE_STALE_MS = 60000
22
+
23
+ export const leaseFile = (config) => path.join(config.outputDir, LEASE_FILE)
24
+
25
+ export function readLease(config) {
26
+ const lease = readLock(leaseFile(config))
27
+ return lease && Number.isInteger(Number(lease.pid)) ? lease : null
28
+ }
29
+
30
+ export function leaseIsLive(lease, { now = Date.now(), staleMs = LEASE_STALE_MS } = {}) {
31
+ if (!lease || !isLockLive(lease)) return false
32
+ const beat = Date.parse(lease.heartbeatAt || lease.startedAt || '')
33
+ return Number.isFinite(beat) && now - beat < staleMs
34
+ }
35
+
36
+ // The live lease, or null.
37
+ export function liveLease(config, options) {
38
+ const lease = readLease(config)
39
+ return leaseIsLive(lease, options) ? lease : null
40
+ }
41
+
42
+ // True when a live server notifier will send this event from the log.
43
+ export function leaseCovers(lease, event) {
44
+ const started = Date.parse(lease?.startedAt || '')
45
+ const at = Date.parse(event?.at || '')
46
+ return Number.isFinite(started) && Number.isFinite(at) && at >= started
47
+ }
48
+
49
+ // Takes the lease for this process. Returns it, or null while another live
50
+ // server holds it. A lease left by a process that is gone is taken over; one
51
+ // whose process runs but has stopped beating is not (it may come back).
52
+ export function acquireLease(config) {
53
+ const file = leaseFile(config)
54
+ fs.mkdirSync(config.outputDir, { recursive: true })
55
+ if (!acquireLock(file)) return null
56
+ const lease = readLock(file)
57
+ if (!lease || Number(lease.pid) !== process.pid) return null
58
+ const held = { ...lease, heartbeatAt: lease.startedAt }
59
+ writeJsonAtomic(file, held)
60
+ return held
61
+ }
62
+
63
+ // Refreshes the heartbeat; false when this process no longer holds the lease.
64
+ export function heartbeat(config, lease, now = new Date()) {
65
+ const current = readLease(config)
66
+ if (!current || Number(current.pid) !== process.pid || current.startedAt !== lease.startedAt) return false
67
+ writeJsonAtomic(leaseFile(config), { ...current, heartbeatAt: now.toISOString() })
68
+ return true
69
+ }
70
+
71
+ export function releaseLease(config) {
72
+ releaseLock(leaseFile(config))
73
+ }