shapewall 0.7.3 → 0.9.0

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 (105) hide show
  1. package/CHANGELOG.md +121 -0
  2. package/README.md +7 -3
  3. package/bin/shapewall.js +2 -1
  4. package/dist/agent/package-lock.json +130 -72
  5. package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
  6. package/dist/client/assets/{BuzzDialog-DwEAN6va.js → BuzzDialog-DnjF36OB.js} +1 -1
  7. package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
  8. package/dist/client/assets/{History-Cp4QRJti.js → History-FzpzGmXZ.js} +1 -1
  9. package/dist/client/assets/LocalSettings-BGFl4VKr.js +1 -0
  10. package/dist/client/assets/{Management-B-x1faV8.js → Management-BGdmGtby.js} +1 -1
  11. package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
  12. package/dist/client/assets/{ShareDialog-CdLdd6WQ.js → ShareDialog-D0tmOGcQ.js} +2 -2
  13. package/dist/client/assets/{app-update-dialog-BneaJeqQ.js → app-update-dialog-BQxVHa5e.js} +1 -1
  14. package/dist/client/assets/{circle-x-D5MkDLJk.js → circle-x-Dxsku6s6.js} +1 -1
  15. package/dist/client/assets/error-reports-sdk-COuSIAQO.js +15 -0
  16. package/dist/client/assets/index-B_m65HWT.css +2 -0
  17. package/dist/client/assets/index-C1ZwriJU.js +37 -0
  18. package/dist/client/assets/{play--xrZ7VCR.js → play-vJhLsLhL.js} +1 -1
  19. package/dist/client/assets/{refresh-cw-B-npxKae.js → refresh-cw-TbGHlgDq.js} +1 -1
  20. package/dist/client/assets/ui-CogdFhRH.js +41 -0
  21. package/dist/client/build-info.json +1 -1
  22. package/dist/client/index.html +3 -3
  23. package/dist/client/sw.js +2 -2
  24. package/dist/console/assets/{LocalAccountsApp-uKpz8EwR.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
  25. package/dist/console/assets/{LocalConsole-XeqnTeRB.js → LocalConsole-Rg-MTvSJ.js} +2 -2
  26. package/dist/console/assets/{LocalUsage-Br3Ddp7_.js → LocalUsage-BGCSfmBU.js} +1 -1
  27. package/dist/console/assets/{app-update-dialog-h11DnNZi.js → app-update-dialog-CEhV7th4.js} +1 -1
  28. package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
  29. package/dist/console/assets/console-BD5_Gha1.js +11 -0
  30. package/dist/console/assets/console-PWt8SxrJ.css +2 -0
  31. package/dist/console/assets/error-reports-sdk-COuSIAQO.js +15 -0
  32. package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
  33. package/dist/console/assets/minus-Cnq0kKnu.js +1 -0
  34. package/dist/console/assets/{tailnet-DJGcztR5.js → tailnet-Cqtbptzq.js} +2 -2
  35. package/dist/console/assets/theme-CB-cwoG6.js +1 -0
  36. package/dist/console/assets/ui-HgfwUo3E.js +41 -0
  37. package/dist/console/assets/{usage-fzmilDTS.js → usage-BCIwgDP9.js} +2 -2
  38. package/dist/console/assets/{usage-DjmUlnXL.js → usage-CeY6XnGX.js} +1 -1
  39. package/dist/console/build-info.json +1 -1
  40. package/dist/console/console.html +8 -8
  41. package/docs/README.md +64 -0
  42. package/docs/agent-hardening.md +3 -3
  43. package/docs/agent-recipes.md +3 -3
  44. package/docs/agent-workflow.md +6 -4
  45. package/docs/agents.md +25 -16
  46. package/docs/architecture.md +9 -2
  47. package/docs/config.md +53 -25
  48. package/docs/deployment.md +19 -3
  49. package/docs/github.md +1 -1
  50. package/docs/hosted.md +265 -70
  51. package/docs/local-accounts.md +1 -1
  52. package/docs/performance.md +3 -2
  53. package/docs/pull-requests.md +1 -1
  54. package/docs/starter-agent.md +4 -4
  55. package/docs/where-to-run.md +1 -1
  56. package/package.json +5 -2
  57. package/src/agent/backends/acp.js +39 -9
  58. package/src/capture/capture.js +35 -5
  59. package/src/capture/destination.js +67 -0
  60. package/src/capture/load-errors.js +82 -0
  61. package/src/checks/cli.js +41 -5
  62. package/src/cli/args.js +1 -0
  63. package/src/cli/capture.js +5 -0
  64. package/src/cli/comments.js +41 -3
  65. package/src/cli/help.js +4 -1
  66. package/src/cli/init.js +8 -4
  67. package/src/cli/misc.js +3 -3
  68. package/src/cli/serve.js +37 -6
  69. package/src/comment-fields.js +5 -0
  70. package/src/comments-cli.js +26 -5
  71. package/src/config-keys.js +191 -0
  72. package/src/config-reload.js +4 -1
  73. package/src/config.js +33 -2
  74. package/src/doctor.js +188 -39
  75. package/src/error-scrub.js +135 -0
  76. package/src/error-tracking.js +105 -0
  77. package/src/feedback.js +36 -2
  78. package/src/hosted/app.js +9 -3
  79. package/src/hosted/auth.js +14 -8
  80. package/src/hosted/board-routes.js +6 -6
  81. package/src/hosted/db.js +50 -0
  82. package/src/hosted/pages.js +16 -7
  83. package/src/hosted/server.js +4 -0
  84. package/src/hosted/token-api.js +17 -1
  85. package/src/hosted/usage-shape.js +1 -1
  86. package/src/missing-package.js +11 -0
  87. package/src/ports.js +35 -0
  88. package/src/serve-state.js +16 -0
  89. package/src/server/app.js +18 -14
  90. package/src/server/local-console.js +7 -3
  91. package/src/watch.js +6 -0
  92. package/dist/client/assets/BoardChat-BVbIXN0v.js +0 -27
  93. package/dist/client/assets/ChecksPanel-BJmSzge1.js +0 -1
  94. package/dist/client/assets/LocalSettings-Bt52or8s.js +0 -1
  95. package/dist/client/assets/QuickConnect-C6sW-MA7.js +0 -1
  96. package/dist/client/assets/index-C-pM8Kf2.js +0 -37
  97. package/dist/client/assets/index-C2_XIPRO.css +0 -2
  98. package/dist/client/assets/ui-2lMx-4bc.js +0 -41
  99. package/dist/console/assets/app-version-IdaEWb4n.js +0 -1
  100. package/dist/console/assets/console-BDuWmrw9.js +0 -11
  101. package/dist/console/assets/console-BGRSS8Ru.css +0 -2
  102. package/dist/console/assets/local-agents-BkSN9lXJ.js +0 -6
  103. package/dist/console/assets/minus-887msXez.js +0 -1
  104. package/dist/console/assets/theme-CPfJOmcz.js +0 -1
  105. package/dist/console/assets/ui-DnyJhoQU.js +0 -41
package/src/doctor.js CHANGED
@@ -3,7 +3,6 @@
3
3
  // that matches the bundled Playwright version.
4
4
 
5
5
  import fs from 'node:fs'
6
- import net from 'node:net'
7
6
  import path from 'node:path'
8
7
  import { spawn } from 'node:child_process'
9
8
  import { createRequire } from 'node:module'
@@ -16,6 +15,9 @@ import { formatCommand, loginHint } from './agent/acp/command.js'
16
15
  import { acpHandshake } from './agent/backends/acp.js'
17
16
  import { cliCommand, invocation } from './invocation.js'
18
17
  import { listAgentBranches } from './agent/branch-mode.js'
18
+ import { nextFreePort, portInUse, probePort } from './ports.js'
19
+ import { DEFAULT_PORT, recordedServe } from './serve-state.js'
20
+ import { formatKeyWarning } from './config-keys.js'
19
21
 
20
22
  const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
21
23
  const PACKAGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'))
@@ -35,12 +37,16 @@ export const installHint = () => cliCommand('doctor --install-browser')
35
37
  // System libraries for Chromium, from the Playwright version Shapewall uses.
36
38
  const depsHint = () => `npx playwright@${playwrightVersion()} install-deps chromium`
37
39
 
38
- function checkNode(version = process.versions.node) {
39
- const wanted = Number(/\d+/.exec(PACKAGE.engines?.node || '22')[0])
40
- const major = Number(version.split('.')[0])
41
- return major >= wanted
40
+ // package.json's engines floor (">=22.19.0"), compared major, minor and patch.
41
+ export function checkNode(version = process.versions.node, engines = PACKAGE.engines?.node || '>=22') {
42
+ const parts = (text) => (/(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(text)) || []).slice(1, 4).map((part) => Number(part || 0))
43
+ const wanted = parts(engines)
44
+ const have = parts(version)
45
+ const order = have[0] - wanted[0] || have[1] - wanted[1] || have[2] - wanted[2]
46
+ const floor = wanted[1] || wanted[2] ? wanted.join('.') : String(wanted[0])
47
+ return order >= 0
42
48
  ? { name: 'node', status: 'ok', message: `Node ${version}` }
43
- : { name: 'node', status: 'fail', message: `Node ${version}; Shapewall needs ${wanted} or newer`, fix: 'Install a current Node LTS.' }
49
+ : { name: 'node', status: 'fail', message: `Node ${version}; Shapewall needs ${floor} or newer`, fix: 'Install a current Node LTS.' }
44
50
  }
45
51
 
46
52
  async function checkBrowser(config, { launch = true, chromium = null } = {}) {
@@ -142,23 +148,101 @@ function checkStore(config) {
142
148
  }
143
149
  }
144
150
 
145
- export function checkPort(port, host = '127.0.0.1') {
146
- return new Promise((resolve) => {
147
- const server = net.createServer()
148
- server.once('error', (error) =>
149
- resolve(
150
- error.code === 'EADDRINUSE'
151
- ? {
152
- name: 'port',
153
- status: 'warn',
154
- message: `Port ${port} on ${host} is in use`,
155
- fix: `Use "${cliCommand(`serve --port ${port + 1}`)}" (or stop what is using it).`,
156
- }
157
- : { name: 'port', status: 'warn', message: `Port ${port} on ${host}: ${error.code || error.message}` },
158
- ),
159
- )
160
- server.listen(port, host, () => server.close(() => resolve({ name: 'port', status: 'ok', message: `Port ${port} on ${host} is free` })))
161
- })
151
+ // The port serve will listen on: free, in use (with a port that is free
152
+ // now), or this project's own running server. `running`: the URL of a live
153
+ // `shapewall serve` for this project (serve.json), when there is one.
154
+ export async function checkPort(port, host = '127.0.0.1', { running = null } = {}) {
155
+ const state = await probePort(port, host)
156
+ if (state === 'free') return { name: 'port', status: 'ok', message: `Port ${port} on ${host} is free` }
157
+ if (state !== 'in-use') return { name: 'port', status: 'warn', message: `Port ${port} on ${host}: ${state}` }
158
+ const mine = running && Number(new URL(running).port) === port ? running : null
159
+ if (mine) return { name: 'port', status: 'ok', message: `Shapewall is already serving this project at ${mine}` }
160
+ const free = await nextFreePort(port, host)
161
+ const { message, fix } = portInUse({ port, host, free, command: (next) => cliCommand(`serve --port ${next}`) })
162
+ return { name: 'port', status: 'warn', message: message.replace(/\.$/, ''), fix }
163
+ }
164
+
165
+ // Shapewall's own dependencies must be installed: a package.json for each,
166
+ // where Node looks for it from here. A package left out of node_modules (an
167
+ // interrupted install, a pruned folder) otherwise passes every check and
168
+ // `serve` dies with "Cannot find package".
169
+ // `lookIn(name)`: the node_modules folders Node would search, nearest first.
170
+ export function checkInstall({
171
+ dependencies = PACKAGE.dependencies,
172
+ lookIn = (name) => require.resolve.paths(name) || [path.join(ROOT, 'node_modules')],
173
+ exists = fs.existsSync,
174
+ } = {}) {
175
+ const missing = Object.keys(dependencies || {}).filter(
176
+ (name) => !lookIn(name).some((dir) => exists(path.join(dir, name, 'package.json'))),
177
+ )
178
+ if (!missing.length)
179
+ return { name: 'install', status: 'ok', message: `Dependencies installed (${Object.keys(dependencies || {}).length})` }
180
+ const shown = missing.slice(0, 5).join(', ') + (missing.length > 5 ? `, and ${missing.length - 5} more` : '')
181
+ return {
182
+ name: 'install',
183
+ status: 'fail',
184
+ message: `Shapewall's install is incomplete: ${missing.length === 1 ? 'a dependency is' : `${missing.length} dependencies are`} missing (${shown})`,
185
+ fix: 'Reinstall it: "npm install" in this project (or "npm install -g shapewall" for a global install), then run doctor again.',
186
+ }
187
+ }
188
+
189
+ // The site the config captures must answer, or capture fails every shot.
190
+ // People run doctor before they start their dev server too, so a site
191
+ // that does not answer is a warning that says what to do, not a FAIL:
192
+ // serve works without it. Each board's default environment, a few at most.
193
+ const SITE_TIMEOUT_MS = 5000
194
+ const SITES_MAX = 4
195
+ export async function checkSites(config, { fetchImpl = globalThis.fetch, network = true, timeoutMs = SITE_TIMEOUT_MS } = {}) {
196
+ if (!config) return []
197
+ const urls = [...new Set(config.boards.map((board) => board.environments?.[0]?.baseUrl || board.baseUrl).filter(Boolean))]
198
+ if (!network)
199
+ return urls.length ? [{ name: 'site', status: 'skip', message: `Not checked whether ${urls[0]} answers (no network checks)` }] : []
200
+ const checks = await Promise.all(urls.slice(0, SITES_MAX).map((url) => checkSite(url, { fetchImpl, timeoutMs })))
201
+ if (urls.length > SITES_MAX)
202
+ checks.push({ name: 'site', status: 'skip', message: `${urls.length - SITES_MAX} more base URLs not checked` })
203
+ return checks
204
+ }
205
+
206
+ export async function checkSite(url, { fetchImpl = globalThis.fetch, timeoutMs = SITE_TIMEOUT_MS } = {}) {
207
+ const start = `Start it (or fix baseUrl in the config) before "${cliCommand('capture')}"; serve works without it.`
208
+ try {
209
+ const response = await fetchImpl(url, { method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) })
210
+ response.body?.cancel?.().catch?.(() => {})
211
+ const status = response.status
212
+ if (status >= 500)
213
+ return {
214
+ name: 'site',
215
+ status: 'warn',
216
+ message: `${url} answers with HTTP ${status}`,
217
+ fix: 'Captures of an error page fail. Check the site.',
218
+ }
219
+ if (status === 401 || status === 403)
220
+ return {
221
+ name: 'site',
222
+ status: 'ok',
223
+ message: `${url} answers (HTTP ${status}: it needs a sign-in; see Auth in docs/config.md to capture signed in)`,
224
+ }
225
+ return { name: 'site', status: 'ok', message: `${url} answers (HTTP ${status})` }
226
+ } catch (error) {
227
+ const code = error?.cause?.code || error?.code
228
+ if (error?.name === 'TimeoutError' || error?.name === 'AbortError')
229
+ return { name: 'site', status: 'warn', message: `${url} did not answer within ${timeoutMs / 1000} s`, fix: start }
230
+ if (code === 'ECONNREFUSED')
231
+ return { name: 'site', status: 'warn', message: `Nothing answers at ${url} (connection refused): is the site running?`, fix: start }
232
+ if (code === 'ENOTFOUND' || code === 'EAI_AGAIN')
233
+ return {
234
+ name: 'site',
235
+ status: 'warn',
236
+ message: `The host of ${url} is not found`,
237
+ fix: 'Check baseUrl in the config (a typo, or a host only another network knows).',
238
+ }
239
+ return {
240
+ name: 'site',
241
+ status: 'warn',
242
+ message: `${url} could not be reached (${code || String(error?.message || error).slice(0, 120)})`,
243
+ fix: start,
244
+ }
245
+ }
162
246
  }
163
247
 
164
248
  function checkClient() {
@@ -270,7 +354,9 @@ export async function checkAgentBranches(config) {
270
354
 
271
355
  export async function runDoctor({
272
356
  configFile = null,
273
- port = 4600,
357
+ // null: the port serve will use, the one this project's serve.json
358
+ // records (a running server, or the last one), else the default.
359
+ port = null,
274
360
  host = '127.0.0.1',
275
361
  launch = true,
276
362
  chromium = null,
@@ -282,12 +368,16 @@ export async function runDoctor({
282
368
  } = {}) {
283
369
  const { check: configCheck, config } = loadConfigCheck(configFile, { optional: configOptional })
284
370
  const useAcp = Boolean(acp || env.SHAPEWALL_AGENT_ACP || (config && agentSettings(config, env, { acp }).backend === 'acp'))
371
+ const recorded = recordedServe(config)
285
372
  const checks = [
286
373
  checkNode(),
374
+ checkInstall(),
287
375
  configCheck,
376
+ ...configWarningChecks(config),
288
377
  await checkBrowser(config, { launch, chromium }),
289
378
  checkStore(config),
290
- await checkPort(port, host),
379
+ await checkPort(port ?? recorded?.port ?? DEFAULT_PORT, host, { running: recorded?.alive ? recorded.url : null }),
380
+ ...(await checkSites(config, { fetchImpl, network })),
291
381
  checkClient(),
292
382
  checkNotifications(config, env),
293
383
  useAcp ? await checkAcpAgent(config, env, { acp, launch }) : checkAgent(config, env),
@@ -302,7 +392,15 @@ export function formatDoctor(report) {
302
392
  const mark = { ok: 'ok ', warn: 'warn', fail: 'FAIL', skip: 'skip' }
303
393
  const lines = report.checks.flatMap((check) => [`${mark[check.status]} ${check.message}`, ...(check.fix ? [` ${check.fix}`] : [])])
304
394
  const how = invocation()
305
- lines.push('', report.ok ? 'Ready.' : `Fix the FAIL lines above, then run "${how.command} doctor" again.`)
395
+ const warnings = report.checks.filter((check) => check.status === 'warn').length
396
+ lines.push(
397
+ '',
398
+ !report.ok
399
+ ? `Fix the FAIL lines above, then run "${how.command} doctor" again.`
400
+ : warnings
401
+ ? `Ready, with ${warnings} warning${warnings === 1 ? '' : 's'} above.`
402
+ : 'Ready.',
403
+ )
306
404
  if (how.note) lines.push(`(Commands above are written as "${how.command}": ${how.note}.)`)
307
405
  return lines.join('\n')
308
406
  }
@@ -310,6 +408,45 @@ export function formatDoctor(report) {
310
408
  // A line of the box Playwright's installer draws around its npx warning.
311
409
  export const isInstallerBox = (line) => /^\s*[\u2554\u2551\u255A]/.test(line)
312
410
 
411
+ // Playwright says this once per download (Chromium, its headless shell,
412
+ // ffmpeg) on a Linux it does not list, Fedora or Arch among them, in capitals.
413
+ const UNSUPPORTED_OS_RE = /^\s*BEWARE: your OS is not officially supported by Playwright/
414
+ export const UNSUPPORTED_OS_NOTE =
415
+ 'Note: Playwright does not list this Linux distribution, so it downloads its generic Linux build. That works on most distributions; if Chromium then does not start, doctor says which system libraries it needs.'
416
+
417
+ // What to print for one line of the installer's output: the line, our note
418
+ // instead of the first "BEWARE" (null for the others), or null for the box.
419
+ // `state` remembers whether the note was printed.
420
+ export function installerLine(line, state) {
421
+ if (isInstallerBox(line)) return null
422
+ if (UNSUPPORTED_OS_RE.test(line)) {
423
+ if (state.noted) return null
424
+ state.noted = true
425
+ return UNSUPPORTED_OS_NOTE
426
+ }
427
+ return line
428
+ }
429
+
430
+ // Line by line through installerLine into `write`; returns { push, end }.
431
+ function installerFilter(write, state) {
432
+ let rest = ''
433
+ return {
434
+ push(chunk) {
435
+ const lines = (rest + chunk).split('\n')
436
+ rest = lines.pop()
437
+ for (const line of lines) {
438
+ const shown = installerLine(line, state)
439
+ if (shown !== null) write(`${shown}\n`)
440
+ }
441
+ },
442
+ end() {
443
+ const shown = rest ? installerLine(rest, state) : null
444
+ if (shown) write(shown)
445
+ rest = ''
446
+ },
447
+ }
448
+ }
449
+
313
450
  // Downloads Chromium for the bundled Playwright (its own CLI, so the browser
314
451
  // build always matches). Resolves with the exit code.
315
452
  export function installBrowser({ stdio = 'inherit' } = {}) {
@@ -318,26 +455,38 @@ export function installBrowser({ stdio = 'inherit' } = {}) {
318
455
  // meant for `npx playwright install` in a project without Playwright
319
456
  // ("install your project's dependencies first"). It does not apply here
320
457
  // (this Playwright is Shapewall's own) and reads as a failure, so the box
321
- // is left out; every other line passes through.
458
+ // is left out, and its "BEWARE: your OS is not officially supported" (on
459
+ // stdout, once per download) becomes one calm note; every other line
460
+ // passes through. Its progress bar is then the plain one it prints when
461
+ // the output is not a terminal.
322
462
  const filter = stdio === 'inherit'
323
463
  const child = spawn(process.execPath, [playwrightCli(), 'install', 'chromium'], {
324
- stdio: filter ? ['inherit', 'inherit', 'pipe'] : stdio,
464
+ stdio: filter ? ['inherit', 'pipe', 'pipe'] : stdio,
325
465
  shell: false,
326
466
  })
327
467
  if (filter) {
328
- let rest = ''
329
- const write = (text) => {
330
- const lines = text.split('\n')
331
- rest = lines.pop()
332
- for (const line of lines) if (!isInstallerBox(line)) process.stderr.write(`${line}\n`)
468
+ const state = { noted: false }
469
+ for (const [stream, target] of [
470
+ [child.stdout, process.stdout],
471
+ [child.stderr, process.stderr],
472
+ ]) {
473
+ const lines = installerFilter((text) => target.write(text), state)
474
+ stream.setEncoding('utf8')
475
+ stream.on('data', (chunk) => lines.push(chunk))
476
+ stream.on('end', () => lines.end())
333
477
  }
334
- child.stderr.setEncoding('utf8')
335
- child.stderr.on('data', (chunk) => write(rest + chunk))
336
- child.stderr.on('end', () => {
337
- if (rest && !isInstallerBox(rest)) process.stderr.write(rest)
338
- })
339
478
  }
340
479
  child.once('error', reject)
341
- child.once('exit', (code) => resolve(code ?? 1))
480
+ // 'close', not 'exit': the last of its output is written by then.
481
+ child.once('close', (code) => resolve(code ?? 1))
342
482
  })
343
483
  }
484
+
485
+ // A config key Shapewall does not use (a typo, most often): one warning
486
+ // each, with the key it probably meant (config-keys.js).
487
+ export function configWarningChecks(config) {
488
+ const warnings = config?.warnings || []
489
+ const checks = warnings.slice(0, 10).map((warning) => ({ name: 'config-key', status: 'warn', message: formatKeyWarning(warning) }))
490
+ if (warnings.length > 10) checks.push({ name: 'config-key', status: 'warn', message: `and ${warnings.length - 10} more unknown keys` })
491
+ return checks
492
+ }
@@ -0,0 +1,135 @@
1
+ // What an opt-in error report may carry (SHAPEWALL_ERROR_DSN, docs/config.md
2
+ // "Error reports"). Used as beforeSend / beforeBreadcrumb by the server
3
+ // (src/error-tracking.js) and the browser (client/src/lib/error-tracking.js),
4
+ // so both send the same thing: the error, its stack trace, the URL path,
5
+ // the browser or runtime and the release. Never cookies, request bodies,
6
+ // headers other than the user agent, query strings or fragments (invite,
7
+ // share and setup links carry secrets there), user identities, local
8
+ // variables or console output, and so never board, page or comment content.
9
+ // No imports: the browser bundle loads this file as is.
10
+
11
+ // Path segments that look like a secret (long random tokens), not a word or an id.
12
+ const TOKEN_SEGMENT = /^(?=[A-Za-z0-9_-]*\d)(?=[A-Za-z0-9_-]*[A-Za-z])[A-Za-z0-9_-]{24,}$/
13
+
14
+ // A URL without its query string and fragment, and with token-like path
15
+ // segments replaced. Relative URLs and paths stay relative.
16
+ export function scrubUrl(value) {
17
+ if (typeof value !== 'string') return undefined
18
+ const bare = value.replace(/[?#][\s\S]*$/, '')
19
+ const match = bare.match(/^([a-z][a-z0-9+.-]*:\/\/[^/]*)?([\s\S]*)$/i)
20
+ const origin = (match[1] || '').replace(/^([a-z][a-z0-9+.-]*:\/\/)[^@/]*@/i, '$1')
21
+ const path = match[2]
22
+ .split('/')
23
+ .map((segment) => (TOKEN_SEGMENT.test(segment) ? '[token]' : segment))
24
+ .join('/')
25
+ return origin + path
26
+ }
27
+
28
+ // Breadcrumbs: page navigations and request URLs only (method and status
29
+ // kept). Console lines, clicks and key presses can hold what someone typed.
30
+ const KEPT_BREADCRUMBS = new Set(['navigation', 'fetch', 'xhr'])
31
+
32
+ export function scrubBreadcrumb(breadcrumb) {
33
+ if (!breadcrumb || !KEPT_BREADCRUMBS.has(breadcrumb.category)) return null
34
+ const data = breadcrumb.data || {}
35
+ const kept = {}
36
+ if (breadcrumb.category === 'navigation') {
37
+ if (data.from !== undefined) kept.from = scrubUrl(String(data.from))
38
+ if (data.to !== undefined) kept.to = scrubUrl(String(data.to))
39
+ } else {
40
+ if (data.url !== undefined) kept.url = scrubUrl(String(data.url))
41
+ if (typeof data.method === 'string') kept.method = data.method
42
+ if (Number.isInteger(data.status_code)) kept.status_code = data.status_code
43
+ }
44
+ return {
45
+ type: breadcrumb.type,
46
+ category: breadcrumb.category,
47
+ level: breadcrumb.level,
48
+ timestamp: breadcrumb.timestamp,
49
+ data: kept,
50
+ }
51
+ }
52
+
53
+ function scrubFrames(stacktrace) {
54
+ if (!stacktrace || !Array.isArray(stacktrace.frames)) return
55
+ for (const frame of stacktrace.frames) {
56
+ delete frame.vars
57
+ if (typeof frame.abs_path === 'string') frame.abs_path = scrubUrl(frame.abs_path)
58
+ if (typeof frame.filename === 'string') frame.filename = scrubUrl(frame.filename)
59
+ }
60
+ }
61
+
62
+ // An error message without quoted text: some messages quote the input that
63
+ // failed, e.g. JSON.parse's `Unexpected token 'x', "{"text":"my note"..." is
64
+ // not valid JSON`, and that input can be board or comment content.
65
+ export function scrubMessage(message) {
66
+ // From the first quote to the last (quoted input can hold quotes itself), or to the end when there is only one.
67
+ return message.replace(/["“][\s\S]*["”]|["“][\s\S]*$/, '"[redacted]"')
68
+ }
69
+
70
+ // Strips an event down to what it may carry (see the top of this file).
71
+ // Returns the event, changed in place.
72
+ export function scrubEvent(event) {
73
+ if (!event || typeof event !== 'object') return event
74
+ delete event.user
75
+ delete event.extra
76
+ delete event.server_name
77
+ if (event.request) {
78
+ const userAgent = Object.entries(event.request.headers || {}).find(([name]) => name.toLowerCase() === 'user-agent')?.[1]
79
+ event.request = {
80
+ ...(event.request.method ? { method: event.request.method } : {}),
81
+ ...(event.request.url ? { url: scrubUrl(event.request.url) } : {}),
82
+ ...(typeof userAgent === 'string' ? { headers: { 'User-Agent': userAgent } } : {}),
83
+ }
84
+ }
85
+ if (typeof event.transaction === 'string') event.transaction = scrubUrl(event.transaction)
86
+ if (Array.isArray(event.breadcrumbs)) event.breadcrumbs = event.breadcrumbs.map(scrubBreadcrumb).filter(Boolean)
87
+ for (const value of event.exception?.values || []) {
88
+ scrubFrames(value.stacktrace)
89
+ if (typeof value.value === 'string') value.value = scrubMessage(value.value)
90
+ }
91
+ if (typeof event.message === 'string') event.message = scrubMessage(event.message)
92
+ if (event.logentry && typeof event.logentry.message === 'string') {
93
+ event.logentry = { message: scrubMessage(event.logentry.message) }
94
+ }
95
+ for (const thread of event.threads?.values || []) scrubFrames(thread.stacktrace)
96
+ // The device's and app's names and memory are not needed to fix an error.
97
+ if (event.contexts) {
98
+ if (event.contexts.device) {
99
+ const { type, family, model, arch } = event.contexts.device
100
+ event.contexts.device = Object.fromEntries(Object.entries({ type, family, model, arch }).filter(([, value]) => value !== undefined))
101
+ }
102
+ delete event.contexts.app?.app_memory
103
+ delete event.contexts.culture
104
+ delete event.contexts.cloud_resource
105
+ }
106
+ return event
107
+ }
108
+
109
+ // Reads SHAPEWALL_ERROR_DSN and SHAPEWALL_ERROR_ENVIRONMENT. Returns null
110
+ // (reporting stays off) unless the DSN is a Sentry-style DSN:
111
+ // https://<public key>@<host>/<project id>. The DSN's key is public by
112
+ // design (browsers send it); the origin is what the CSP allows.
113
+ export function errorSettingsFrom(env = {}) {
114
+ const raw = String(env.SHAPEWALL_ERROR_DSN || '').trim()
115
+ if (!raw) return null
116
+ let url
117
+ try {
118
+ url = new URL(raw)
119
+ } catch {
120
+ return { problem: 'SHAPEWALL_ERROR_DSN is not a URL; error reports stay off.' }
121
+ }
122
+ if (
123
+ !/^https?:$/.test(url.protocol) ||
124
+ !url.username ||
125
+ url.password ||
126
+ !/^\/(?:[^/?#]+\/)*\d+$/.test(url.pathname) ||
127
+ url.search ||
128
+ url.hash
129
+ )
130
+ return { problem: 'SHAPEWALL_ERROR_DSN is not a DSN (https://<key>@<host>/<project id>); error reports stay off.' }
131
+ const environment = String(env.SHAPEWALL_ERROR_ENVIRONMENT || '').trim() || 'production'
132
+ if (!/^[A-Za-z0-9._-]{1,64}$/.test(environment))
133
+ return { problem: 'SHAPEWALL_ERROR_ENVIRONMENT must be a short name such as production or staging; error reports stay off.' }
134
+ return { dsn: url.href, origin: url.origin, environment }
135
+ }
@@ -0,0 +1,105 @@
1
+ // Opt-in error reports for a server you run (docs/config.md "Error reports").
2
+ // Off unless SHAPEWALL_ERROR_DSN is set: nothing is loaded and nothing is
3
+ // sent. With a DSN (Sentry, GlitchTip or anything that speaks the Sentry
4
+ // protocol), the server reports its own unhandled errors there, and the
5
+ // pages it serves tell the browser to do the same (a <meta> tag, plus the
6
+ // DSN's origin in connect-src). What a report may carry: src/error-scrub.js.
7
+ // The DSN is yours: Shapewall has no default one and never reports anywhere else.
8
+ import fs from 'node:fs'
9
+ import { errorSettingsFrom, scrubBreadcrumb, scrubEvent } from './error-scrub.js'
10
+
11
+ export { errorSettingsFrom }
12
+
13
+ let sentry = null
14
+
15
+ // The integrations a report needs: the error, its causes, its source lines and
16
+ // the runtime. Not request or HTTP/fetch tracing (URLs of the sites you
17
+ // capture), console lines, child processes, local variables, installed
18
+ // modules or sessions.
19
+ const KEPT_INTEGRATIONS = new Set([
20
+ 'EventFilters',
21
+ 'FunctionToString',
22
+ 'LinkedErrors',
23
+ 'Dedupe',
24
+ 'NodeSystemError',
25
+ 'OnUncaughtException',
26
+ 'OnUnhandledRejection',
27
+ 'ContextLines',
28
+ 'Context',
29
+ ])
30
+
31
+ function release() {
32
+ try {
33
+ const info = JSON.parse(fs.readFileSync(new URL('../dist/client/build-info.json', import.meta.url), 'utf8'))
34
+ if (/^[a-f0-9]{7,40}$/i.test(info.revision || '')) return info.revision.slice(0, 7)
35
+ if (info.version) return `shapewall@${info.version}`
36
+ } catch {
37
+ /* not built */
38
+ }
39
+ try {
40
+ return `shapewall@${JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version}`
41
+ } catch {
42
+ return undefined
43
+ }
44
+ }
45
+
46
+ // Starts reporting when env has a DSN. Returns the settings ({ dsn, origin,
47
+ // environment }) or null; logs one line either way it is configured.
48
+ export async function startErrorTracking(env = process.env, { log = () => {} } = {}) {
49
+ const settings = errorSettingsFrom(env)
50
+ if (!settings) return null
51
+ if (settings.problem) {
52
+ log(`Warning: ${settings.problem}`)
53
+ return null
54
+ }
55
+ if (!sentry) {
56
+ const Sentry = await import('@sentry/node')
57
+ Sentry.init({
58
+ dsn: settings.dsn,
59
+ environment: settings.environment,
60
+ release: release(),
61
+ sendDefaultPii: false,
62
+ tracesSampleRate: 0,
63
+ includeLocalVariables: false,
64
+ maxBreadcrumbs: 20,
65
+ integrations: (defaults) =>
66
+ defaults
67
+ .filter((integration) => KEPT_INTEGRATIONS.has(integration.name) && integration.name !== 'OnUnhandledRejection')
68
+ // Report, then exit, as Node does without a handler.
69
+ .concat(Sentry.onUnhandledRejectionIntegration({ mode: 'strict' })),
70
+ beforeSend: (event) => scrubEvent(event),
71
+ beforeBreadcrumb: (breadcrumb) => scrubBreadcrumb(breadcrumb),
72
+ })
73
+ sentry = Sentry
74
+ }
75
+ log(`Error reports go to ${settings.origin} (SHAPEWALL_ERROR_DSN, environment ${settings.environment}).`)
76
+ return settings
77
+ }
78
+
79
+ // Reports a request error that ended in a 5xx. No-op when reporting is off.
80
+ export function reportServerError(error) {
81
+ if (!sentry) return
82
+ try {
83
+ sentry.captureException(error, { mechanism: { type: 'express', handled: false } })
84
+ } catch {
85
+ /* reporting never breaks a response */
86
+ }
87
+ }
88
+
89
+ // Sends what is queued (tests, shutdown).
90
+ export async function flushErrorReports(ms = 2000) {
91
+ if (sentry) await sentry.flush(ms)
92
+ }
93
+
94
+ // The <meta> tags that turn the browser's reporting on (client/src/lib/error-tracking.js).
95
+ export function errorMeta(settings) {
96
+ if (!settings?.dsn) return ''
97
+ const attr = (value) => String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
98
+ return `<meta name="shapewall-error-dsn" content="${attr(settings.dsn)}">\n<meta name="shapewall-error-environment" content="${attr(settings.environment)}">\n`
99
+ }
100
+
101
+ // A page's CSP with the DSN's origin added to connect-src.
102
+ export function cspWithErrors(csp, settings) {
103
+ if (!settings?.origin) return csp
104
+ return csp.replace(/connect-src ([^;]*)/, (all, sources) => `connect-src ${sources} ${settings.origin}`)
105
+ }
package/src/feedback.js CHANGED
@@ -267,10 +267,38 @@ export function formatFeedbackItem(item, { cwd = process.cwd() } = {}) {
267
267
  return lines
268
268
  }
269
269
 
270
+ // What a report leaves out, in one line under the count. A remote report read
271
+ // with a claim-scoped token holds only the comments that agent may take
272
+ // (another agent's work, and work nobody has been given, are not its to see),
273
+ // and share link guests' comments wait to be asked for. Neither was said in
274
+ // the text report, so the count read like the board's own: "2 comments on
275
+ // testbed" while a third was open and routed to another agent. Counting them
276
+ // is the server's job (token-api.js remoteReport); saying so is this one's.
277
+ export function withheldNote(report) {
278
+ const parts = []
279
+ if (report?.routedElsewhere > 0) {
280
+ parts.push(
281
+ `${report.routedElsewhere} ${report.routedElsewhere === 1 ? 'is' : 'are'} routed to another agent or not dispatched, ` +
282
+ 'so this token does not read them',
283
+ )
284
+ }
285
+ if (report?.guestsHidden > 0) {
286
+ parts.push(
287
+ `${report.guestsHidden} ${report.guestsHidden === 1 ? 'is' : 'are'} from share link guests ` + '(--include-guests to see them)',
288
+ )
289
+ }
290
+ return parts.length ? `Not shown here: ${parts.join('; ')}.` : null
291
+ }
292
+
270
293
  export function formatFeedback(report, options = {}) {
271
- if (!report.comments.length) return `No ${report.status === 'all' ? '' : `${report.status} `}comments on "${report.board.id}".`
294
+ const withheld = withheldNote(report)
295
+ if (!report.comments.length) {
296
+ const none = `No ${report.status === 'all' ? '' : `${report.status} `}comments on "${report.board.id}".`
297
+ return withheld ? `${none}\n${withheld}` : none
298
+ }
272
299
  const lines = [
273
300
  `${report.count} ${report.status === 'all' ? '' : `${report.status} `}comment${report.count === 1 ? '' : 's'} on "${report.board.id}"`,
301
+ ...(withheld ? [withheld] : []),
274
302
  '',
275
303
  ]
276
304
  for (const item of report.comments) lines.push(...formatFeedbackItem(item, options), '')
@@ -315,7 +343,13 @@ const AGENT_HEADER =
315
343
  // `comments --for-agent`: the report as quoted data.
316
344
  export function formatFeedbackForAgent(report) {
317
345
  const status = report.status === 'all' ? '' : `${report.status} `
318
- const lines = [AGENT_HEADER, '', `${report.count} ${status}comment${report.count === 1 ? '' : 's'} on board "${report.board.id}".`]
346
+ const withheld = withheldNote(report)
347
+ const lines = [
348
+ AGENT_HEADER,
349
+ '',
350
+ `${report.count} ${status}comment${report.count === 1 ? '' : 's'} on board "${report.board.id}".`,
351
+ ...(withheld ? [withheld] : []),
352
+ ]
319
353
  for (const item of report.comments) lines.push('', quoteItem(item, report.board.id))
320
354
  return lines.join('\n')
321
355
  }
package/src/hosted/app.js CHANGED
@@ -71,6 +71,7 @@ import { mountPages } from './pages.js'
71
71
  import { createPasskeyPolicy } from './passkey-policy.js'
72
72
  import { createTailnetAccounts } from './tailnet.js'
73
73
  import { mountTailnetAdmin } from './tailnet-routes.js'
74
+ import { cspWithErrors, reportServerError } from '../error-tracking.js'
74
75
 
75
76
  export { changeEventType, publicBoardView, TOKEN_SCOPES, INVITE_DAYS }
76
77
 
@@ -124,6 +125,8 @@ export function createHostedApp({
124
125
  usercontentOrigin = null,
125
126
  // The origin this server is moving from (src/hosted/rebind.js), or null.
126
127
  previousOrigin = null,
128
+ // Opt-in error reports ({ dsn, origin, environment } from src/error-tracking.js); none by default.
129
+ errorTracking = null,
127
130
  // Bot checks on open sign-up and comment-link guests ({ siteKey, verify },
128
131
  // src/hosted/turnstile.js); none by default.
129
132
  turnstile = null,
@@ -256,7 +259,7 @@ export function createHostedApp({
256
259
  return resolveFile(ctx.config, ctx.board.id, kind, file)
257
260
  },
258
261
  })
259
- const BOARD_PAGE_CSP = usercontent.boardCsp(BOARD_CSP)
262
+ const BOARD_PAGE_CSP = cspWithErrors(usercontent.boardCsp(BOARD_CSP), errorTracking)
260
263
  // true: a proxy on this host. A string ('uniquelocal'): the proxy is on a
261
264
  // private network (Docker Compose), in Express's trust proxy syntax.
262
265
  app.set('trust proxy', trustProxy ? (typeof trustProxy === 'string' ? trustProxy : 'loopback') : false)
@@ -572,7 +575,7 @@ export function createHostedApp({
572
575
  app.use('/api/v1', v1)
573
576
  app.use('/api', consoleApi)
574
577
 
575
- mountPages(app, { db, dataDir, consoleDir, clientDir, turnstile, sessionOf, BOARD_PAGE_CSP, deps })
578
+ mountPages(app, { db, dataDir, consoleDir, clientDir, turnstile, sessionOf, BOARD_PAGE_CSP, deps, errorTracking })
576
579
 
577
580
  app.use((req, res) => {
578
581
  if (req.path.startsWith('/api/') || req.path.startsWith('/auth/')) return fail(res, 404, 'not_found', 'No such route.')
@@ -581,7 +584,10 @@ export function createHostedApp({
581
584
  // eslint-disable-next-line no-unused-vars
582
585
  app.use((error, req, res, next) => {
583
586
  const status = Number(error.status || error.statusCode) || 500
584
- if (status >= 500) log(`error: ${error.name || 'Error'} (request failed; request values omitted)`)
587
+ if (status >= 500) {
588
+ log(`error: ${error.name || 'Error'} (request failed; request values omitted)`)
589
+ reportServerError(error)
590
+ }
585
591
  const api = /^\/(api|auth|w\/[^/]+\/p\/[^/]+\/api|s\/[^/]+\/api)\//.test(req.path)
586
592
  if (api) {
587
593
  return fail(