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,189 @@
1
+ // Journeys: named, ordered page sequences ("sign up", "upgrade to Plus").
2
+ // They come from the config (read-only on the board) and from the board
3
+ // itself, stored in <board>/journeys.json with the same atomic writes and
4
+ // file lock as comments.
5
+
6
+ import fs from 'node:fs'
7
+ import path from 'node:path'
8
+ import { randomBytes } from 'node:crypto'
9
+ import { ID_RE, JOURNEY_STEPS_MAX, checkJourney } from './config.js'
10
+ import { checkSteps, isBranching, isFork, journeyPages, journeyPaths, pruneSteps, resolvePath } from './journey-paths.js'
11
+ import { CommentError, boardDir, writeJsonAtomic } from './store.js'
12
+ import { withFileLock } from './lock.js'
13
+
14
+ const JOURNEYS_MAX = 200
15
+
16
+ export function journeysFile(config, boardId) {
17
+ return path.join(boardDir(config, boardId), 'journeys.json')
18
+ }
19
+
20
+ function readStore(config, boardId) {
21
+ const file = journeysFile(config, boardId)
22
+ let text
23
+ try {
24
+ text = fs.readFileSync(file, 'utf8')
25
+ } catch (error) {
26
+ if (error.code === 'ENOENT') return []
27
+ throw error
28
+ }
29
+ let raw
30
+ try {
31
+ raw = JSON.parse(text)
32
+ } catch (error) {
33
+ throw new CommentError(
34
+ 500,
35
+ 'corrupt_file',
36
+ `journeys.json is not valid JSON (${error.message}); fix or move it, nothing was written.`,
37
+ {
38
+ cause: error,
39
+ },
40
+ )
41
+ }
42
+ return Array.isArray(raw?.journeys) ? raw.journeys.filter((item) => item && typeof item === 'object' && ID_RE.test(item.id)) : []
43
+ }
44
+
45
+ // Every journey on the board: config ones first, then board ones, each with
46
+ // `source` ('config' | 'board') and, read from its steps, `branching`,
47
+ // `pages` (every page it visits, on any branch) and `paths` (each way
48
+ // through the forks; one for a linear journey). Steps whose page left the
49
+ // config are dropped; a journey left with fewer than two steps is not shown.
50
+ export function listJourneys(config, board) {
51
+ const pageIds = new Set(board.pages.map((page) => page.id))
52
+ const fromConfig = board.journeys.map((journey) => ({ ...journey, source: 'config' }))
53
+ const taken = new Set(fromConfig.map((journey) => journey.id))
54
+ const fromBoard = readStore(config, board.id)
55
+ .filter((journey) => !taken.has(journey.id))
56
+ .map((journey) => ({
57
+ id: journey.id,
58
+ name: typeof journey.name === 'string' ? journey.name : journey.id,
59
+ description: typeof journey.description === 'string' ? journey.description : '',
60
+ steps: storedSteps(journey.steps, pageIds),
61
+ source: 'board',
62
+ createdAt: typeof journey.createdAt === 'string' ? journey.createdAt : null,
63
+ updatedAt: typeof journey.updatedAt === 'string' ? journey.updatedAt : null,
64
+ }))
65
+ return [...fromConfig, ...fromBoard].filter((journey) => countSteps(journey.steps) >= 2).map(withPaths)
66
+ }
67
+
68
+ function countSteps(steps) {
69
+ return resolvePath(steps).steps.length
70
+ }
71
+
72
+ function withPaths(journey) {
73
+ return { ...journey, branching: isBranching(journey.steps), pages: journeyPages(journey.steps), paths: journeyPaths(journey.steps) }
74
+ }
75
+
76
+ // Steps of a stored journey, without pages that left the config. If pruning
77
+ // leaves an invalid fork (say, one at the start), the journey falls back to
78
+ // its first path, as a linear journey.
79
+ function storedSteps(raw, pageIds) {
80
+ const pruned = pruneSteps(raw, pageIds)
81
+ if (!isBranching(pruned)) return pruned
82
+ if (checkSteps(pruned, pageIds, 'steps', [], { stepsMax: JOURNEY_STEPS_MAX })) return pruned
83
+ return resolvePath(pruned).steps.map((step) => step.pageId)
84
+ }
85
+
86
+ function validate(board, input, id) {
87
+ const problems = []
88
+ const clean = checkJourney({ ...input, id }, new Set(board.pages.map((page) => page.id)), 'journey', problems)
89
+ if (!clean) throw new CommentError(400, 'invalid_journey', problems.map((problem) => problem.replace(/^journey\.?/, '')).join('; '))
90
+ return clean
91
+ }
92
+
93
+ function slug(name) {
94
+ return (
95
+ String(name || '')
96
+ .toLowerCase()
97
+ .replace(/[^a-z0-9]+/g, '-')
98
+ .replace(/^-+|-+$/g, '')
99
+ .slice(0, 40) || 'journey'
100
+ )
101
+ }
102
+
103
+ export async function createJourney(config, board, input, { now = new Date() } = {}) {
104
+ if (!input || typeof input !== 'object') throw new CommentError(400, 'invalid_journey', 'Send { name, steps }.')
105
+ const file = journeysFile(config, board.id)
106
+ return withFileLock(file, () => {
107
+ const list = readStore(config, board.id)
108
+ if (list.length >= JOURNEYS_MAX) throw new CommentError(409, 'too_many_journeys', `A board holds at most ${JOURNEYS_MAX} journeys.`)
109
+ const taken = new Set([...board.journeys.map((item) => item.id), ...list.map((item) => item.id)])
110
+ let id = `${slug(input.name)}`
111
+ while (taken.has(id)) id = `${slug(input.name)}-${randomBytes(2).toString('hex')}`
112
+ const clean = validate(board, input, id)
113
+ const journey = { ...clean, createdAt: now.toISOString(), updatedAt: now.toISOString() }
114
+ list.push(journey)
115
+ writeJsonAtomic(file, { journeys: list })
116
+ return withPaths({ ...journey, source: 'board' })
117
+ })
118
+ }
119
+
120
+ function boardOnly(board, journeyId) {
121
+ if (board.journeys.some((item) => item.id === journeyId)) {
122
+ throw new CommentError(409, 'config_journey', 'This journey is defined in shapewall.config.json; change it there.')
123
+ }
124
+ }
125
+
126
+ export async function updateJourney(config, board, journeyId, changes, { now = new Date() } = {}) {
127
+ boardOnly(board, journeyId)
128
+ if (!changes || typeof changes !== 'object') throw new CommentError(400, 'invalid_journey', 'Nothing to change.')
129
+ const file = journeysFile(config, board.id)
130
+ return withFileLock(file, () => {
131
+ const list = readStore(config, board.id)
132
+ const index = list.findIndex((item) => item.id === journeyId)
133
+ if (index < 0) throw new CommentError(404, 'unknown_journey', 'That journey does not exist.')
134
+ const current = list[index]
135
+ const merged = {
136
+ name: changes.name !== undefined ? changes.name : current.name,
137
+ description: changes.description !== undefined ? changes.description : current.description,
138
+ steps: changes.steps !== undefined ? changes.steps : current.steps,
139
+ }
140
+ const clean = validate(board, merged, journeyId)
141
+ list[index] = { ...clean, createdAt: current.createdAt || now.toISOString(), updatedAt: now.toISOString() }
142
+ writeJsonAtomic(file, { journeys: list })
143
+ return withPaths({ ...list[index], source: 'board' })
144
+ })
145
+ }
146
+
147
+ export async function deleteJourney(config, board, journeyId) {
148
+ boardOnly(board, journeyId)
149
+ const file = journeysFile(config, board.id)
150
+ return withFileLock(file, () => {
151
+ const list = readStore(config, board.id)
152
+ const kept = list.filter((item) => item.id !== journeyId)
153
+ if (kept.length === list.length) throw new CommentError(404, 'unknown_journey', 'That journey does not exist.')
154
+ writeJsonAtomic(file, { journeys: kept })
155
+ return true
156
+ })
157
+ }
158
+
159
+ // Plain-text journeys for `shapewall journeys`: each step on its own line,
160
+ // forks as indented branches.
161
+ export function formatJourneys(board, journeys) {
162
+ const titles = new Map(board.pages.map((page) => [page.id, page.title]))
163
+ const lines = []
164
+ const list = (items, indent) => {
165
+ for (const item of items) {
166
+ if (typeof item === 'string') {
167
+ lines.push(`${indent}- ${titles.get(item) || item} (${item})`)
168
+ continue
169
+ }
170
+ if (!isFork(item)) continue
171
+ lines.push(`${indent} fork:`)
172
+ for (const branch of item.branches) {
173
+ const note = branch.end ? ', ends here' : branch.steps.length ? '' : ', skips to the next step'
174
+ lines.push(`${indent} > ${branch.label} [${branch.id}${note}]`)
175
+ list(branch.steps, `${indent} `)
176
+ }
177
+ }
178
+ }
179
+ if (!journeys.length) return `No journeys on board "${board.id}".`
180
+ for (const journey of journeys) {
181
+ if (lines.length) lines.push('')
182
+ const paths = journey.paths.length
183
+ const shape = journey.branching ? `, ${paths} path${paths === 1 ? '' : 's'}` : ''
184
+ lines.push(`${journey.name} (${journey.id}, ${journey.source}${shape})`)
185
+ if (journey.description) lines.push(` ${journey.description}`)
186
+ list(journey.steps, ' ')
187
+ }
188
+ return lines.join('\n')
189
+ }
package/src/links.js ADDED
@@ -0,0 +1,106 @@
1
+ // Links between pages, for the board's arrows and journeys.
2
+ //
3
+ // During a capture the page's anchors are read (their resolved hrefs, which
4
+ // come from the captured site and are untrusted). Only links that resolve to
5
+ // a page configured on the board are kept, and only as that page's id, so
6
+ // nothing from the captured page is ever stored or shown as-is.
7
+
8
+ import { joinUrl } from './config.js'
9
+
10
+ export const LINKS_READ_MAX = 2000
11
+ const HREF_MAX = 2048
12
+
13
+ // In the page: every <a href> and <area href>, resolved by the browser.
14
+ export const READ_LINKS_JS = `(() => {
15
+ const out = [];
16
+ for (const el of document.querySelectorAll('a[href], area[href]')) {
17
+ if (out.length >= ${LINKS_READ_MAX}) break;
18
+ const href = el.href;
19
+ if (typeof href === 'string' && href.length <= ${HREF_MAX}) out.push(href);
20
+ }
21
+ return out;
22
+ })()`
23
+
24
+ // A comparable key for a URL path: decoded where that is safe, no repeated
25
+ // or trailing slashes, and "/index.html" the same as "/".
26
+ function pathKey(pathname) {
27
+ let value = pathname
28
+ try {
29
+ value = decodeURI(pathname)
30
+ } catch {
31
+ /* keep it encoded */
32
+ }
33
+ value = value.replace(/\/{2,}/g, '/').replace(/\/index\.html?$/i, '/')
34
+ if (value.length > 1) value = value.replace(/\/+$/, '')
35
+ return value || '/'
36
+ }
37
+
38
+ function queryKey(search) {
39
+ const params = new URLSearchParams(search)
40
+ return [...params.entries()]
41
+ .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
42
+ .sort()
43
+ .join('&')
44
+ }
45
+
46
+ // Builds a matcher for one board and base URL: href -> page id or null.
47
+ // A link matches a page with the same path and query (in any order); failing
48
+ // that, a page with the same path and no query of its own (so "?utm=..."
49
+ // links still count). Links outside the base URL's origin and path never match.
50
+ export function createLinkMatcher(board, baseUrl = board.baseUrl) {
51
+ const base = new URL(baseUrl)
52
+ const prefix = pathKey(base.pathname) === '/' ? '' : pathKey(base.pathname)
53
+ const exact = new Map()
54
+ const byPath = new Map()
55
+ for (const page of board.pages) {
56
+ const url = new URL(joinUrl(baseUrl, page.path))
57
+ const key = pathKey(url.pathname)
58
+ const query = queryKey(url.search)
59
+ if (!exact.has(`${key}?${query}`)) exact.set(`${key}?${query}`, page.id)
60
+ if (!query && !byPath.has(key)) byPath.set(key, page.id)
61
+ }
62
+ return (href) => {
63
+ if (typeof href !== 'string' || !href || href.length > HREF_MAX) return null
64
+ let url
65
+ try {
66
+ url = new URL(href, base)
67
+ } catch {
68
+ return null
69
+ }
70
+ if (!/^https?:$/.test(url.protocol) || url.origin !== base.origin || url.username || url.password) return null
71
+ const key = pathKey(url.pathname)
72
+ if (prefix && key !== prefix && !key.startsWith(`${prefix}/`)) return null
73
+ return exact.get(`${key}?${queryKey(url.search)}`) || byPath.get(key) || null
74
+ }
75
+ }
76
+
77
+ // The ids of configured pages that `hrefs` link to, in first-seen order,
78
+ // without the page itself.
79
+ export function linkTargets(hrefs, board, { baseUrl = board.baseUrl, self = null } = {}) {
80
+ if (!Array.isArray(hrefs)) return []
81
+ const match = createLinkMatcher(board, baseUrl)
82
+ const out = []
83
+ for (const href of hrefs.slice(0, LINKS_READ_MAX)) {
84
+ const id = match(href)
85
+ if (id && id !== self && !out.includes(id)) out.push(id)
86
+ }
87
+ return out
88
+ }
89
+
90
+ // Page -> pages it links to, from a capture manifest (every viewport merged),
91
+ // limited to pages still on the board.
92
+ export function pageLinks(manifest, board) {
93
+ const ids = new Set(board.pages.map((page) => page.id))
94
+ const out = {}
95
+ for (const page of board.pages) {
96
+ const entry = manifest?.pages?.[page.id]
97
+ if (!entry || typeof entry !== 'object') continue
98
+ const targets = []
99
+ for (const shot of Object.values(entry)) {
100
+ if (!Array.isArray(shot?.links)) continue
101
+ for (const id of shot.links) if (typeof id === 'string' && ids.has(id) && id !== page.id && !targets.includes(id)) targets.push(id)
102
+ }
103
+ if (targets.length) out[page.id] = targets
104
+ }
105
+ return out
106
+ }
@@ -0,0 +1,182 @@
1
+ // A private, per-user index of local projects. It holds config paths, never
2
+ // commands, settings tokens or agent credentials. Each project keeps its
3
+ // own server and agent root; switching projects navigates to that server.
4
+ import fs from 'node:fs'
5
+ import path from 'node:path'
6
+ import http from 'node:http'
7
+ import { createHash, randomBytes } from 'node:crypto'
8
+ import { loadConfig } from './config.js'
9
+ import { projectKey, userSettingsFile, withSettingsLock } from './agent/user-settings.js'
10
+ import { runningBoardUrl } from './serve-state.js'
11
+
12
+ const MAX_PROJECTS = 100
13
+ const MAX_BYTES = 1024 * 1024
14
+ export const projectId = (file) => createHash('sha256').update(projectKey(file)).digest('hex').slice(0, 24)
15
+
16
+ export function projectsFile(env = process.env) {
17
+ const settings = userSettingsFile(env)
18
+ return settings ? path.join(path.dirname(settings), 'projects.json') : null
19
+ }
20
+
21
+ function safe(file) {
22
+ for (const target of [path.dirname(file), file]) {
23
+ let stat
24
+ try {
25
+ stat = fs.lstatSync(target)
26
+ } catch (error) {
27
+ if (error.code === 'ENOENT') continue
28
+ throw error
29
+ }
30
+ if (stat.isSymbolicLink()) throw new Error('The local project index must not be a symlink.')
31
+ if (process.platform !== 'win32' && typeof process.getuid === 'function') {
32
+ if (stat.uid !== process.getuid() || stat.mode & 0o022)
33
+ throw new Error('The local project index must be owned and writable only by you.')
34
+ }
35
+ if (target === file && (!stat.isFile() || stat.size > MAX_BYTES))
36
+ throw new Error('The local project index is not a small regular file.')
37
+ }
38
+ }
39
+
40
+ function read(file) {
41
+ safe(file)
42
+ let data
43
+ try {
44
+ data = JSON.parse(fs.readFileSync(file, 'utf8'))
45
+ } catch (error) {
46
+ if (error.code === 'ENOENT') return []
47
+ throw new Error('The local project index could not be read. Fix projects.json in your Shapewall settings folder.', { cause: error })
48
+ }
49
+ if (data?.version !== 1 || !Array.isArray(data.projects) || data.projects.length > MAX_PROJECTS)
50
+ throw new Error('Invalid local project index.')
51
+ return data.projects.filter(
52
+ (entry) => typeof entry?.file === 'string' && path.isAbsolute(entry.file) && entry.id === projectId(entry.file),
53
+ )
54
+ }
55
+
56
+ // Registration is best-effort at init/serve; a broken index must not stop a
57
+ // board. Callers surface a warning instead of silently replacing bad data.
58
+ export function registerProject(config, env = process.env) {
59
+ const file = projectsFile(env)
60
+ if (!file || !config.file) return
61
+ fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
62
+ safe(file)
63
+ return withSettingsLock(file, () => {
64
+ const entries = read(file)
65
+ const target = projectKey(config.file)
66
+ const id = projectId(target)
67
+ const projects = [{ id, file: target }, ...entries.filter((entry) => entry.id !== id)].slice(0, MAX_PROJECTS)
68
+ const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
69
+ try {
70
+ fs.writeFileSync(temp, JSON.stringify({ version: 1, projects }, null, 2) + '\n', { flag: 'wx', mode: 0o600 })
71
+ fs.renameSync(temp, file)
72
+ } finally {
73
+ try {
74
+ fs.unlinkSync(temp)
75
+ } catch {
76
+ // Rename normally consumed the temporary file. Preserve the original
77
+ // write error if cleanup was needed but could not finish.
78
+ }
79
+ }
80
+ return id
81
+ })
82
+ }
83
+
84
+ // Never navigate to arbitrary URLs from a registry or serve-state file.
85
+ // Remote access has its own identity/pairing model, not this local index.
86
+ export function localProjectUrl(value) {
87
+ try {
88
+ const url = new URL(value)
89
+ return url.protocol === 'http:' &&
90
+ ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) &&
91
+ !url.username &&
92
+ !url.password &&
93
+ url.pathname === '/' &&
94
+ !url.search &&
95
+ !url.hash
96
+ ? url.href
97
+ : null
98
+ } catch {
99
+ return null
100
+ }
101
+ }
102
+
103
+ // A live PID is only a hint: PIDs and ports can be reused. Before enabling
104
+ // navigation, ask the listener for this exact project's identity. No cookies,
105
+ // tokens or redirects; responses are bounded and only loopback is allowed.
106
+ function servesProject(url, id) {
107
+ return new Promise((resolve) => {
108
+ if (!localProjectUrl(url)) return resolve(false)
109
+ let settled = false
110
+ const finish = (result) => {
111
+ if (settled) return
112
+ settled = true
113
+ clearTimeout(timer)
114
+ resolve(result)
115
+ }
116
+ const request = http.get(new URL('api/local-project-id', url), (response) => {
117
+ let body = ''
118
+ if (response.statusCode !== 200) {
119
+ response.resume()
120
+ finish(false)
121
+ return
122
+ }
123
+ response.setEncoding('utf8')
124
+ response.on('data', (chunk) => {
125
+ body += chunk
126
+ if (body.length > 512) request.destroy()
127
+ })
128
+ response.on('error', () => finish(false))
129
+ response.on('end', () => {
130
+ try {
131
+ finish(JSON.parse(body).projectId === id)
132
+ } catch {
133
+ finish(false)
134
+ }
135
+ })
136
+ })
137
+ const timer = setTimeout(() => {
138
+ request.destroy()
139
+ finish(false)
140
+ }, 500)
141
+ request.on('error', () => finish(false))
142
+ })
143
+ }
144
+
145
+ export async function listLocalProjects(config, env = process.env) {
146
+ const file = projectsFile(env)
147
+ const entries = file ? read(file) : []
148
+ const current = config?.file ? projectId(config.file) : null
149
+ if (config?.file && !entries.some((entry) => entry.id === current)) entries.unshift({ id: current, file: config.file })
150
+ const projects = entries
151
+ .flatMap((entry) => {
152
+ try {
153
+ const project = entry.id === current ? config : loadConfig(entry.file)
154
+ const url = localProjectUrl(runningBoardUrl(project))
155
+ return [
156
+ {
157
+ id: entry.id,
158
+ title: project.title,
159
+ current: entry.id === current,
160
+ url,
161
+ running: Boolean(url),
162
+ boardCount: project.boards.length,
163
+ },
164
+ ]
165
+ } catch {
166
+ // Removed folders and invalid configs are not usable projects.
167
+ return []
168
+ }
169
+ })
170
+ .sort((a, b) => a.title.localeCompare(b.title))
171
+ let next = 0
172
+ await Promise.all(
173
+ Array.from({ length: Math.min(4, projects.length) }, async () => {
174
+ while (next < projects.length) {
175
+ const project = projects[next++]
176
+ project.running = Boolean(project.url) && (await servesProject(project.url, project.id))
177
+ if (!project.running) project.url = null
178
+ }
179
+ }),
180
+ )
181
+ return projects
182
+ }
package/src/lock.js ADDED
@@ -0,0 +1,193 @@
1
+ // File locks.
2
+ //
3
+ // The capture lock (<board>/capture.lock) holds { pid, start, startedAt } and
4
+ // is the single source of truth for "a capture is running", whoever started
5
+ // it (the CLI or the server).
6
+ // - Created with an atomic exclusive open ('wx'), so only one taker wins.
7
+ // - A lock is live only if its pid exists AND, on Linux, that process started
8
+ // at the recorded time (from /proc/<pid>/stat), so a recycled pid is stale.
9
+ // - A stale lock is renamed aside (by the one taker holding `<lock>.takeover`),
10
+ // then 'wx' is retried, so two takers can never both win.
11
+ //
12
+ // withFileLock() is the short-lived variant for read-modify-write of JSON
13
+ // files (comments), shared by the server and the CLI.
14
+
15
+ import fs from 'node:fs'
16
+ import path from 'node:path'
17
+ import { randomBytes } from 'node:crypto'
18
+
19
+ // Field 22 of /proc/<pid>/stat (clock ticks since boot); null when unknown.
20
+ export function processStartTime(pid) {
21
+ try {
22
+ const stat = fs.readFileSync(`/proc/${Number(pid)}/stat`, 'utf8')
23
+ const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ')
24
+ return fields[19] || null
25
+ } catch {
26
+ return null
27
+ }
28
+ }
29
+
30
+ const hasProc = () => fs.existsSync('/proc/self/stat')
31
+
32
+ function pidExists(pid) {
33
+ if (!Number.isInteger(pid) || pid <= 0) return false
34
+ if (hasProc()) return fs.existsSync(`/proc/${pid}/stat`)
35
+ try {
36
+ process.kill(pid, 0)
37
+ return true
38
+ } catch (error) {
39
+ return error.code === 'EPERM'
40
+ }
41
+ }
42
+
43
+ export function readLock(file) {
44
+ try {
45
+ const value = JSON.parse(fs.readFileSync(file, 'utf8'))
46
+ return value && typeof value === 'object' ? value : null
47
+ } catch {
48
+ return null
49
+ }
50
+ }
51
+
52
+ export function isLockLive(lock) {
53
+ if (!lock) return false
54
+ const pid = Number(lock.pid)
55
+ if (!pidExists(pid)) return false
56
+ const start = processStartTime(pid)
57
+ // Without /proc (macOS, Windows) the pid check is all there is.
58
+ if (start === null) return !hasProc()
59
+ return String(lock.start) === start
60
+ }
61
+
62
+ function lockBody(pid = process.pid) {
63
+ return JSON.stringify({ pid, start: processStartTime(pid), startedAt: new Date().toISOString() })
64
+ }
65
+
66
+ function tryCreate(file, body) {
67
+ let fd
68
+ try {
69
+ fd = fs.openSync(file, 'wx', 0o644)
70
+ } catch (error) {
71
+ if (error.code === 'EEXIST') return false
72
+ throw error
73
+ }
74
+ try {
75
+ fs.writeSync(fd, body)
76
+ } finally {
77
+ fs.closeSync(fd)
78
+ }
79
+ return true
80
+ }
81
+
82
+ function pause(ms) {
83
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
84
+ }
85
+
86
+ const TAKEOVER_STALE_MS = 10000
87
+
88
+ // Returns true when this process now holds the lock, false when a live
89
+ // process does.
90
+ export function acquireLock(file, { attempts = 40 } = {}) {
91
+ const body = lockBody()
92
+ const takeover = `${file}.takeover`
93
+ for (let attempt = 0; attempt < attempts; attempt += 1) {
94
+ if (tryCreate(file, body)) return true
95
+ const current = readLock(file)
96
+ if (current && isLockLive(current)) return false
97
+ // A lock being written right now can briefly read as empty.
98
+ if (!current && attempt === 0) {
99
+ pause(50)
100
+ continue
101
+ }
102
+ if (!tryCreate(takeover, String(process.pid))) {
103
+ try {
104
+ if (Date.now() - fs.statSync(takeover).mtimeMs > TAKEOVER_STALE_MS) fs.rmSync(takeover, { force: true })
105
+ } catch {
106
+ /* gone already */
107
+ }
108
+ pause(10 + Math.floor(Math.random() * 20))
109
+ continue
110
+ }
111
+ try {
112
+ const again = readLock(file)
113
+ if (fs.existsSync(file) && !(again && isLockLive(again))) {
114
+ const aside = `${file}.stale-${process.pid}-${Date.now()}-${randomBytes(4).toString('hex')}`
115
+ try {
116
+ fs.renameSync(file, aside)
117
+ fs.rmSync(aside, { force: true })
118
+ } catch (error) {
119
+ if (error.code !== 'ENOENT') throw error
120
+ }
121
+ }
122
+ } finally {
123
+ fs.rmSync(takeover, { force: true })
124
+ }
125
+ }
126
+ return false
127
+ }
128
+
129
+ // Removes the lock only if this process holds it.
130
+ export function releaseLock(file) {
131
+ const current = readLock(file)
132
+ if (current && Number(current.pid) === process.pid) fs.rmSync(file, { force: true })
133
+ }
134
+
135
+ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
136
+
137
+ // Runs `fn` while holding `<file>.lock`. Waits up to `timeoutMs` for another
138
+ // holder; a lock whose process is gone, or older than `staleMs`, is taken over.
139
+ export async function withFileLock(file, fn, { timeoutMs = 5000, staleMs = 15000 } = {}) {
140
+ const lockFile = `${file}.lock`
141
+ fs.mkdirSync(path.dirname(lockFile), { recursive: true })
142
+ const takeover = `${lockFile}.takeover`
143
+ // A nonce tells our lock apart from one a taker created after ours was
144
+ // (wrongly) judged stale, so we never remove someone else's.
145
+ const nonce = randomBytes(8).toString('hex')
146
+ const body = JSON.stringify({ ...JSON.parse(lockBody()), nonce })
147
+ const until = Date.now() + timeoutMs
148
+ const isStale = () => {
149
+ const current = readLock(lockFile)
150
+ let age
151
+ try {
152
+ age = Date.now() - fs.statSync(lockFile).mtimeMs
153
+ } catch {
154
+ return false // gone: the next create attempt decides
155
+ }
156
+ return (current && !isLockLive(current)) || age > staleMs
157
+ }
158
+ for (;;) {
159
+ if (tryCreate(lockFile, body)) break
160
+ if (isStale()) {
161
+ // Only the holder of `.takeover` may move a stale lock aside, and it
162
+ // re-checks first, so two takers can never both remove and recreate.
163
+ if (tryCreate(takeover, String(process.pid))) {
164
+ try {
165
+ if (isStale()) {
166
+ const aside = `${lockFile}.stale-${process.pid}-${randomBytes(4).toString('hex')}`
167
+ try {
168
+ fs.renameSync(lockFile, aside)
169
+ fs.rmSync(aside, { force: true })
170
+ } catch {
171
+ /* already gone */
172
+ }
173
+ }
174
+ } finally {
175
+ fs.rmSync(takeover, { force: true })
176
+ }
177
+ continue
178
+ }
179
+ try {
180
+ if (Date.now() - fs.statSync(takeover).mtimeMs > TAKEOVER_STALE_MS) fs.rmSync(takeover, { force: true })
181
+ } catch {
182
+ /* gone already */
183
+ }
184
+ }
185
+ if (Date.now() > until) throw new Error(`timed out waiting for ${lockFile}`)
186
+ await sleep(15 + Math.floor(Math.random() * 25))
187
+ }
188
+ try {
189
+ return await fn()
190
+ } finally {
191
+ if (readLock(lockFile)?.nonce === nonce) fs.rmSync(lockFile, { force: true })
192
+ }
193
+ }