shapewall 0.2.4 → 0.3.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 +36 -0
  2. package/README.md +35 -1
  3. package/dist/agent/package-lock.json +2 -2
  4. package/dist/client/assets/BoardChat-CupOxioV.js +27 -0
  5. package/dist/client/assets/{BuzzDialog-CZdwIQLF.js → BuzzDialog-Ds7Thpfe.js} +1 -1
  6. package/dist/client/assets/ChecksPanel-BqrS02Ih.js +1 -0
  7. package/dist/client/assets/History-CQG3NQOC.js +1 -0
  8. package/dist/client/assets/{LocalSettings-B5gtfKEl.js → LocalSettings-CSNMhNyV.js} +1 -1
  9. package/dist/client/assets/{Management-BxEUZAmI.js → Management-CJVNAqAW.js} +1 -1
  10. package/dist/client/assets/QuickConnect-B-4pUgXH.js +1 -0
  11. package/dist/client/assets/{ShareDialog-CdVAreaw.js → ShareDialog-BouvNraR.js} +2 -2
  12. package/dist/client/assets/{app-update-dialog-BONq9YFp.js → app-update-dialog-rhaw0MRk.js} +1 -1
  13. package/dist/client/assets/{circle-x-BmT6vHKl.js → circle-x-PRxj7kPi.js} +1 -1
  14. package/dist/client/assets/index-CXtuJi1K.css +2 -0
  15. package/dist/client/assets/index-DKOCIQiq.js +37 -0
  16. package/dist/client/assets/{refresh-cw-ugt3cWKH.js → refresh-cw-aeOBDuGQ.js} +1 -1
  17. package/dist/client/assets/{square-_KG6tM5A.js → shield-check-DuPBJ6H_.js} +1 -1
  18. package/dist/client/assets/ui-Cg4TTrec.js +41 -0
  19. package/dist/client/build-info.json +1 -1
  20. package/dist/client/index.html +3 -3
  21. package/dist/client/sw.js +2 -2
  22. package/dist/console/assets/LocalAccountsApp-DOKZI6Lt.js +1 -0
  23. package/dist/console/assets/LocalConsole-DXzldLW9.js +1 -0
  24. package/dist/console/assets/{app-update-dialog-o4QY_jL9.js → app-update-dialog-CrqIMEwN.js} +1 -1
  25. package/dist/console/assets/console-76WovHlh.js +55 -0
  26. package/dist/console/assets/console-Fp4k9iyx.css +2 -0
  27. package/dist/console/build-info.json +1 -1
  28. package/dist/console/console.html +2 -2
  29. package/docs/agent-hardening.md +19 -0
  30. package/docs/agent-workflow.md +33 -0
  31. package/docs/agents.md +112 -0
  32. package/docs/config.md +41 -0
  33. package/docs/deployment.md +3 -0
  34. package/docs/hosted.md +10 -0
  35. package/docs/pull-requests.md +192 -0
  36. package/package.json +2 -1
  37. package/src/agent/backends/acp.js +23 -6
  38. package/src/agent/batch-fixes.js +45 -0
  39. package/src/agent/batch-queue.js +204 -0
  40. package/src/agent/branch-mode.js +753 -0
  41. package/src/agent/config.js +6 -0
  42. package/src/agent/fix-prompt.js +5 -0
  43. package/src/agent/routes.js +850 -185
  44. package/src/agent/run.js +8 -1
  45. package/src/agent/settings-routes.js +69 -1
  46. package/src/agent/starter/worktree.js +254 -25
  47. package/src/agent/threads.js +2 -7
  48. package/src/agent/tools.js +51 -0
  49. package/src/agent/user-settings.js +33 -2
  50. package/src/ci/capture.js +103 -0
  51. package/src/ci/compare.js +267 -0
  52. package/src/ci/github.js +307 -0
  53. package/src/ci/images.js +76 -0
  54. package/src/ci/settings.js +211 -0
  55. package/src/ci/start.js +148 -0
  56. package/src/ci/summary.js +262 -0
  57. package/src/ci/workflow.js +238 -0
  58. package/src/cli/args.js +24 -1
  59. package/src/cli/ci.js +229 -0
  60. package/src/cli/help.js +23 -1
  61. package/src/cli/init.js +33 -1
  62. package/src/cli.js +6 -2
  63. package/src/comment-drawing.js +161 -0
  64. package/src/comment-fields.js +51 -0
  65. package/src/comment-media.js +528 -0
  66. package/src/config.js +7 -0
  67. package/src/doctor.js +23 -0
  68. package/src/export.js +8 -0
  69. package/src/feedback.js +89 -12
  70. package/src/github.js +3 -3
  71. package/src/hosted/admin.js +36 -4
  72. package/src/hosted/app.js +5 -0
  73. package/src/hosted/board-routes.js +63 -7
  74. package/src/hosted/clean-worker.js +22 -4
  75. package/src/hosted/cleaner.js +4 -1
  76. package/src/hosted/comment-files.js +200 -0
  77. package/src/hosted/comments.js +68 -15
  78. package/src/hosted/db.js +32 -0
  79. package/src/hosted/guest-view.js +9 -0
  80. package/src/hosted/import.js +213 -18
  81. package/src/hosted/operator.js +3 -1
  82. package/src/hosted/projects.js +3 -2
  83. package/src/hosted/push.js +6 -3
  84. package/src/hosted/retention.js +18 -0
  85. package/src/hosted/tenancy.js +1 -0
  86. package/src/hosted/token-api.js +110 -9
  87. package/src/image-sniff.js +11 -0
  88. package/src/mcp.js +48 -3
  89. package/src/remote/remote-mcp.js +2 -2
  90. package/src/remote/remote.js +6 -2
  91. package/src/remote/share.js +77 -7
  92. package/src/server/app.js +18 -1
  93. package/src/store.js +119 -33
  94. package/src/watch.js +4 -0
  95. package/dist/client/assets/BoardChat-C0a3DDjv.js +0 -28
  96. package/dist/client/assets/ChecksPanel-BHWgwJWO.js +0 -1
  97. package/dist/client/assets/History-C01qLFpP.js +0 -1
  98. package/dist/client/assets/QuickConnect-BzTM3UNO.js +0 -1
  99. package/dist/client/assets/index-C1IsGdGs.js +0 -29
  100. package/dist/client/assets/index-DnsWelgZ.css +0 -2
  101. package/dist/client/assets/ui-BAGBTB_P.js +0 -41
  102. package/dist/console/assets/LocalAccountsApp-DtfTDbQg.js +0 -1
  103. package/dist/console/assets/LocalConsole-BPpsxDq_.js +0 -1
  104. package/dist/console/assets/console-DeOji9Zv.css +0 -2
  105. package/dist/console/assets/console-MvFrlUCC.js +0 -51
package/src/mcp.js CHANGED
@@ -17,7 +17,16 @@ import { feedback, feedbackContext, feedbackItem, untrustedJson } from './feedba
17
17
  import { createIssue, githubSettings, linkPull } from './github.js'
18
18
  import { listJourneys } from './journeys.js'
19
19
  import { cropAround } from './png.js'
20
- import { AGENT_STATUSES, addReply, captureFiles, getComment, readManifest, setAgentStatus, updateComment } from './store.js'
20
+ import {
21
+ AGENT_STATUSES,
22
+ STORED_AGENT_STATUSES,
23
+ addReply,
24
+ captureFiles,
25
+ getComment,
26
+ readManifest,
27
+ setAgentStatus,
28
+ updateComment,
29
+ } from './store.js'
21
30
 
22
31
  const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
23
32
 
@@ -65,6 +74,22 @@ export function readScreenshot(file) {
65
74
  }
66
75
  }
67
76
 
77
+ // A stored comment image or markup PNG: a regular file of bounded size, or null.
78
+ function readCommentImage(file) {
79
+ let fd
80
+ try {
81
+ fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0))
82
+ } catch {
83
+ return null
84
+ }
85
+ try {
86
+ const stat = fs.fstatSync(fd)
87
+ return stat.isFile() && stat.size <= SCREENSHOT_MAX ? fs.readFileSync(fd) : null
88
+ } finally {
89
+ fs.closeSync(fd)
90
+ }
91
+ }
92
+
68
93
  // Turns thrown errors into tool errors with their message (no stacks).
69
94
  const tool = (handler) => async (args) => {
70
95
  try {
@@ -176,7 +201,7 @@ export function createMcpServer({
176
201
  .optional()
177
202
  .describe('Only comments on pages of this journey (config or board journeys, any branch) and their variants'),
178
203
  agentStatus: z
179
- .enum([...AGENT_STATUSES, 'none'])
204
+ .enum([...STORED_AGENT_STATUSES, 'none'])
180
205
  .optional()
181
206
  .describe('Only comments with this agent status ("none" = no agent has taken it)'),
182
207
  mention: z
@@ -208,7 +233,9 @@ export function createMcpServer({
208
233
  description:
209
234
  'One comment with everything needed to act on it: page URL, viewport, element anchor (selector, text), pin position, replies, and the screenshot and live HTML ' +
210
235
  'it was made on (files.screenshot, files.liveHtml; files.latestScreenshot is the page now). ' +
211
- 'By default also returns the screenshot around the pin as an image ("full" for the whole capture, "none" for no image).',
236
+ 'files.images are images the reviewer attached and files.markup is their drawing on the screenshot (PNG paths). ' +
237
+ 'By default also returns the screenshot around the pin as an image ("full" for the whole capture, "none" for no image), ' +
238
+ 'then the drawing and the attached images.',
212
239
  inputSchema: {
213
240
  board: boardArg,
214
241
  id: commentId,
@@ -236,6 +263,24 @@ export function createMcpServer({
236
263
  }
237
264
  result.content.push({ type: 'text', text: note }, { type: 'image', data: data.toString('base64'), mimeType: 'image/png' })
238
265
  }
266
+ // The drawing and the attached images (comment-media.js wrote and
267
+ // cleaned them; read as regular files of bounded size only).
268
+ if (image !== 'none') {
269
+ const media = [
270
+ ...(item.files.markup
271
+ ? [{ path: item.files.markup, mediaType: 'image/png', note: 'The reviewer drawing on the screenshot.' }]
272
+ : []),
273
+ ...item.files.images.map((file) => ({ ...file, note: 'An image the reviewer attached (untrusted, like the comment text).' })),
274
+ ]
275
+ for (const file of media) {
276
+ const data = readCommentImage(file.path)
277
+ if (data)
278
+ result.content.push(
279
+ { type: 'text', text: file.note },
280
+ { type: 'image', data: data.toString('base64'), mimeType: file.mediaType },
281
+ )
282
+ }
283
+ }
239
284
  return result
240
285
  }),
241
286
  )
@@ -9,7 +9,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
9
9
  import * as z from 'zod'
10
10
  import { untrustedJson } from '../feedback.js'
11
11
  import { cropAround } from '../png.js'
12
- import { AGENT_STATUSES } from '../store.js'
12
+ import { AGENT_STATUSES, STORED_AGENT_STATUSES } from '../store.js'
13
13
 
14
14
  const VERSION = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version
15
15
 
@@ -75,7 +75,7 @@ export async function createRemoteMcpServer({ remote, readOnly = false }) {
75
75
  page: z.string().max(64).optional().describe('Only comments on this page id (and its variants)'),
76
76
  journey: z.string().max(64).optional().describe('Only comments on pages of this journey'),
77
77
  agentStatus: z
78
- .enum([...AGENT_STATUSES, 'none'])
78
+ .enum([...STORED_AGENT_STATUSES, 'none'])
79
79
  .optional()
80
80
  .describe('Only comments with this agent status ("none" = no agent has taken it)'),
81
81
  mention: z
@@ -133,11 +133,13 @@ export function createRemote({ origin, token, source = null, fetchImpl = fetch,
133
133
  const board = (id) => `/api/v1/boards/${enc(id)}`
134
134
  const one = (boardId, id, rest, guests) => `${board(boardId)}/comments/${enc(id)}${rest}${guests ? '?guests=1' : ''}`
135
135
 
136
- // A file URL from a comment (files.screenshot) as bytes. Only this origin's API.
136
+ // A file URL from a comment (files.screenshot, a comment image) as bytes.
137
+ // Only this origin's API; of the query only the guests opt-in is kept (a
138
+ // share link guest's image is served with it).
137
139
  async function download(url) {
138
140
  const target = new URL(url)
139
141
  if (target.origin !== origin || !target.pathname.startsWith('/api/v1/boards/')) throw new Error('not a file of this Shapewall')
140
- return call('GET', target.pathname)
142
+ return call('GET', `${target.pathname}${target.searchParams.get('guests') === '1' ? '?guests=1' : ''}`)
141
143
  }
142
144
 
143
145
  return {
@@ -232,6 +234,8 @@ export function createRemote({ origin, token, source = null, fetchImpl = fetch,
232
234
  }
233
235
  },
234
236
  importComments: (boardId, json) => call('POST', `${board(boardId)}/import`, { json }),
237
+ // One image of an imported comment, before the batch that lists it.
238
+ importImage: (boardId, json) => call('POST', `${board(boardId)}/import/images`, { json }),
235
239
  download,
236
240
  }
237
241
  }
@@ -9,6 +9,7 @@ import {
9
9
  CAPTURE_FILE_RE,
10
10
  VERSION_FILE_RE,
11
11
  VERSION_RE,
12
+ boardDir,
12
13
  listComments,
13
14
  readManifest,
14
15
  readMigration,
@@ -16,6 +17,8 @@ import {
16
17
  writeMigration,
17
18
  } from '../store.js'
18
19
  import { listJourneys } from '../journeys.js'
20
+ import { COMMENT_IMAGE_BYTES_MAX, readImages } from '../comment-fields.js'
21
+ import { commentFilePath } from '../comment-media.js'
19
22
  import { createRemote, pushDefinition, pushFiles, readCaptureFile, remoteOrigin, remoteSettings } from './remote.js'
20
23
  import { login } from './login.js'
21
24
  import { portableChecks } from '../checks/transport.js'
@@ -57,6 +60,11 @@ export function portableComment(comment, projectPath, boardId) {
57
60
  out.localId = comment.id
58
61
  out.importKey = hash(`${projectPath}\0${boardId}\0${comment.id}\0${comment.createdAt}`)
59
62
  out.reactions = (comment.reactions || []).map(({ emoji, count }) => ({ emoji, count }))
63
+ // A drawing goes as its shapes and the capture it was drawn on; images go
64
+ // in their own requests first (commentUploads) and are listed by ref.
65
+ const drawing = (value) =>
66
+ value?.shapes?.length ? { shapes: value.shapes, ...(value.captureVersion ? { captureVersion: value.captureVersion } : {}) } : null
67
+ if (drawing(comment.drawing)) out.drawing = drawing(comment.drawing)
60
68
  out.replies = (comment.replies || []).map((reply) => ({
61
69
  author: reply.author,
62
70
  body: reply.body,
@@ -65,10 +73,56 @@ export function portableComment(comment, projectPath, boardId) {
65
73
  ...(reply.agent ? { agent: true } : {}),
66
74
  ...(reply.guest ? { guest: true } : {}),
67
75
  reactions: (reply.reactions || []).map(({ emoji, count }) => ({ emoji, count })),
76
+ ...(drawing(reply.drawing) ? { drawing: drawing(reply.drawing) } : {}),
68
77
  }))
69
78
  return out
70
79
  }
71
80
 
81
+ // The images of a local comment and its replies, read from the board's
82
+ // comment-files/ (regular files only, at most the cleaned-size cap), as
83
+ // uploads ({ ref, name, mediaType, data }) and listed on the portable
84
+ // comment by ref. The ref hashes the comment, the slot and the bytes, so it
85
+ // is the same on every retry and differs for any change.
86
+ const COMMENT_IMAGE_READ_MAX = 2 * COMMENT_IMAGE_BYTES_MAX
87
+ export function commentUploads(config, boardId, comment, portable) {
88
+ const folder = boardDir(config, boardId)
89
+ const uploads = []
90
+ const refs = (images, slot) =>
91
+ readImages(images).flatMap((image, index) => {
92
+ const file = commentFilePath(folder, image.file)
93
+ let data = null
94
+ try {
95
+ const stat = file ? fs.lstatSync(file) : null
96
+ if (stat?.isFile() && stat.size <= COMMENT_IMAGE_READ_MAX) data = fs.readFileSync(file)
97
+ } catch {
98
+ data = null
99
+ }
100
+ if (!data) return []
101
+ const ref = hash(`${portable.importKey}\0${slot}:${index}\0${hash(data.toString('base64'))}`)
102
+ uploads.push({ ref, name: image.name, mediaType: image.mediaType, data })
103
+ return [{ ref, name: image.name }]
104
+ })
105
+ const own = refs(comment.images, 'comment')
106
+ if (own.length) portable.images = own
107
+ ;(comment.replies || []).forEach((reply, index) => {
108
+ const listed = refs(reply.images, `reply-${index}`)
109
+ if (listed.length && portable.replies[index]) portable.replies[index].images = listed
110
+ })
111
+ return uploads
112
+ }
113
+
114
+ // Portable comments of a board and the images each one lists, by import key.
115
+ function portableComments(config, board, projectPath) {
116
+ const uploads = new Map()
117
+ const comments = listComments(config, board.id).map((item) => {
118
+ const portable = portableComment(item, projectPath, board.id)
119
+ const files = commentUploads(config, board.id, item, portable)
120
+ if (files.length) uploads.set(portable.importKey, files)
121
+ return portable
122
+ })
123
+ return { comments, uploads }
124
+ }
125
+
72
126
  export function shareFiles(config, board) {
73
127
  const pages = new Map(board.pages.map((page) => [page.id, new Set(page.viewports)]))
74
128
  const variants = new Set(readVariants(config, board.id).map((variant) => variant.id))
@@ -186,12 +240,16 @@ async function runShare(
186
240
  const origin = remoteOrigin(flags, env)
187
241
  const boards = flags.board ? [getBoard(config, flags.board)] : config.boards
188
242
  const projectPath = fs.realpathSync(config.dir)
189
- const plans = boards.map((board) => ({
190
- board,
191
- checks: portableChecks(config, board, { includeChecks: !!flags['include-checks'] }),
192
- comments: flags['no-comments'] ? [] : listComments(config, board.id).map((item) => portableComment(item, projectPath, board.id)),
193
- files: shareFiles(config, board),
194
- }))
243
+ const plans = boards.map((board) => {
244
+ const portable = flags['no-comments'] ? { comments: [], uploads: new Map() } : portableComments(config, board, projectPath)
245
+ return {
246
+ board,
247
+ checks: portableChecks(config, board, { includeChecks: !!flags['include-checks'] }),
248
+ comments: portable.comments,
249
+ uploads: portable.uploads,
250
+ files: shareFiles(config, board),
251
+ }
252
+ })
195
253
  if (flags['dry-run']) {
196
254
  for (const { board, comments, files, checks } of plans)
197
255
  out(
@@ -269,7 +327,7 @@ async function runShare(
269
327
  frozen = true
270
328
  // Read again after freezing under the comment lock: no edits made
271
329
  // between planning and approval are lost from this move.
272
- plan.comments = listComments(config, board.id).map((item) => portableComment(item, projectPath, board.id))
330
+ Object.assign(plan, portableComments(config, board, projectPath))
273
331
  }
274
332
  if (
275
333
  !project.token.scopes.includes('import') &&
@@ -309,6 +367,18 @@ async function runShare(
309
367
  if (!flags['no-comments'] && project.token.scopes.includes('import')) {
310
368
  let importedCount = 0
311
369
  for (const comments of importBatches(plan.comments)) {
370
+ // Their images first, one request each, cleaned and counted
371
+ // against the quota by the server like any upload.
372
+ for (const comment of comments) {
373
+ for (const upload of plan.uploads?.get(comment.importKey) || []) {
374
+ if (signal?.aborted) throw new Error('Share cancelled.')
375
+ await remote.importImage(board.id, {
376
+ sessionId,
377
+ ref: upload.ref,
378
+ image: { name: upload.name, mediaType: upload.mediaType, data: upload.data.toString('base64') },
379
+ })
380
+ }
381
+ }
312
382
  importedCount += comments.length
313
383
  const result = await remote.importComments(board.id, { sessionId, batchKey: hash({ board: board.id, comments }), comments })
314
384
  out(
package/src/server/app.js CHANGED
@@ -29,6 +29,8 @@ import {
29
29
  variantsWithFiles,
30
30
  } from '../store.js'
31
31
  import { LIVE_CSP } from '../capture/live.js'
32
+ import { COMMENT_FILE_RE } from '../comment-fields.js'
33
+ import { commentFilePath, sendCommentFile } from '../comment-media.js'
32
34
  import { elementMapName } from '../capture/element-map.js'
33
35
  import { compareEnvironments } from '../diff.js'
34
36
  import { createJourney, deleteJourney, listJourneys, updateJourney } from '../journeys.js'
@@ -310,6 +312,9 @@ export function createApp({
310
312
  app.locals.agentRouter = router
311
313
  app.use('/api/agent', router)
312
314
  }
315
+ // New comments and replies may carry images (base64, src/comment-media.js):
316
+ // 4 of 5 MB, so their own limit; every other route keeps 64 kB.
317
+ app.post(['/api/boards/:id/comments', '/api/boards/:id/comments/:cid/replies'], express.json({ limit: '28mb' }))
313
318
  app.use('/api', express.json({ limit: '64kb' }))
314
319
  const buzz =
315
320
  buzzBridge && !readOnly && !shared
@@ -555,6 +560,17 @@ export function createApp({
555
560
  app.get('/api/boards/:id/elements/:file', sendElements('captures'))
556
561
  app.get('/api/boards/:id/variant-elements/:file', sendElements('variants'))
557
562
 
563
+ // Images on comments: only names Shapewall wrote, as the image type they
564
+ // are (checked when stored), never rendered as a document.
565
+ app.get(
566
+ '/api/boards/:id/comment-files/:file',
567
+ withBoard((req, res, board) => {
568
+ const file = COMMENT_FILE_RE.test(req.params.file) ? commentFilePath(boardDir(config, board.id), req.params.file) : null
569
+ if (!file) return fail(res, 404, 'not_found', 'No such image.')
570
+ sendCommentFile(res, file, req.params.file)
571
+ }),
572
+ )
573
+
558
574
  // Who changed a comment, for its events: the name the board sends (the
559
575
  // commenter's saved name), like the author of a reply. Display text only.
560
576
  const actorOf = (author) => (typeof author === 'string' ? author : null)
@@ -591,7 +607,8 @@ export function createApp({
591
607
  app.post(
592
608
  '/api/boards/:id/comments/:cid/replies',
593
609
  withBoard(async (req, res, board) => {
594
- const { comment, reply } = await addReply(config, board.id, req.params.cid, { body: req.body?.body, author: req.body?.author })
610
+ const { body, author, images, drawing } = req.body || {}
611
+ const { comment, reply } = await addReply(config, board.id, req.params.cid, { body, author, images, drawing })
595
612
  res.status(201).json({ comment, reply })
596
613
  }),
597
614
  )
package/src/store.js CHANGED
@@ -11,6 +11,7 @@
11
11
  // <out>/<board>/diffs/<a>_<b>/ cached pixel diffs between environments
12
12
  // <out>/<board>/journeys.json journeys made on the board
13
13
  // <out>/<board>/comments.json comments (written atomically)
14
+ // <out>/<board>/comment-files/ images on comments, rendered drawings (src/comment-media.js)
14
15
  // <out>/<board>/capture.lock | status.json | capture.log
15
16
  // <out>/<board>/watch.lock | agent/ `shapewall watch` (one per board)
16
17
  // <out>/events.jsonl (+ events.1.jsonl) comment events from every process (src/event-log.js)
@@ -33,23 +34,32 @@ import { appendEvents } from './event-log.js'
33
34
  import {
34
35
  ANCHOR_SELECTOR_MAX,
35
36
  ANCHOR_SELECTOR_RE,
37
+ AGENT_STATUSES,
36
38
  ANCHOR_TEXT_MAX,
39
+ BRANCH_READY,
37
40
  COMMENT_BODY_MAX,
38
41
  CommentError,
39
42
  FIX_REF_MAX,
43
+ STORED_AGENT_STATUSES,
40
44
  cleanFixRef,
45
+ readImages,
41
46
  validateAnchor,
42
47
  } from './comment-fields.js'
48
+ import { DrawingError, readDrawing, validateDrawing } from './comment-drawing.js'
49
+ import { parseImageInputs, removeCommentMedia, removeImageFiles, saveCommentImages } from './comment-media.js'
43
50
 
44
51
  // A comment's pure field rules live in comment-fields.js (the demo's
45
52
  // in-browser backend uses them too); re-exported for everyone else.
46
53
  export {
54
+ AGENT_STATUSES,
47
55
  ANCHOR_SELECTOR_MAX,
48
56
  ANCHOR_SELECTOR_RE,
49
57
  ANCHOR_TEXT_MAX,
58
+ BRANCH_READY,
50
59
  COMMENT_BODY_MAX,
51
60
  CommentError,
52
61
  FIX_REF_MAX,
62
+ STORED_AGENT_STATUSES,
53
63
  cleanFixRef,
54
64
  validateAnchor,
55
65
  }
@@ -492,16 +502,22 @@ function readCommentStore(config, boardId) {
492
502
  // The same goes for the reopen count; mentions are read from the text.
493
503
  // Reactions read as { emoji, count, by } on the comment and each reply.
494
504
  function withAgentFields(comment) {
495
- const replies = (Array.isArray(comment.replies) ? comment.replies : []).map((reply) => ({
496
- ...reply,
497
- reactions: publicReactions(reply.reactions),
498
- }))
505
+ const replies = (Array.isArray(comment.replies) ? comment.replies : []).map((reply) =>
506
+ withMedia({
507
+ ...reply,
508
+ reactions: publicReactions(reply.reactions),
509
+ }),
510
+ )
511
+ const { agentBranch, ...rest } = withMedia(comment)
512
+ // The branch of a fix waiting on one (branch-ready), and only then.
513
+ const branch = comment.agentStatus === BRANCH_READY ? cleanAgentBranch(agentBranch) : null
499
514
  return {
500
- ...comment,
515
+ ...rest,
516
+ ...(branch ? { agentBranch: branch } : {}),
501
517
  replies,
502
518
  reactions: publicReactions(comment.reactions),
503
519
  editedAt: typeof comment.editedAt === 'string' ? comment.editedAt : null,
504
- agentStatus: AGENT_STATUSES.includes(comment.agentStatus) ? comment.agentStatus : null,
520
+ agentStatus: STORED_AGENT_STATUSES.includes(comment.agentStatus) ? comment.agentStatus : null,
505
521
  agentStatusAt: typeof comment.agentStatusAt === 'string' ? comment.agentStatusAt : null,
506
522
  reopenCount: Number.isSafeInteger(comment.reopenCount) && comment.reopenCount > 0 ? comment.reopenCount : 0,
507
523
  reopenedAt: typeof comment.reopenedAt === 'string' ? comment.reopenedAt : null,
@@ -510,6 +526,33 @@ function withAgentFields(comment) {
510
526
  }
511
527
  }
512
528
 
529
+ // Images and a drawing are optional: read back through their validators,
530
+ // and left off entirely when there are none, so older files read unchanged.
531
+ export function withMedia(item) {
532
+ const out = { ...item }
533
+ const images = readImages(item.images)
534
+ const drawing = readDrawing(item.drawing)
535
+ delete out.images
536
+ delete out.drawing
537
+ if (images.length) out.images = images
538
+ if (drawing) out.drawing = drawing
539
+ return out
540
+ }
541
+
542
+ // The images and drawing of a new comment or reply, checked (nothing
543
+ // written yet). Throws CommentError.
544
+ export function validateCommentMedia(input) {
545
+ const images = parseImageInputs(input?.images)
546
+ let drawing = null
547
+ try {
548
+ drawing = validateDrawing(input?.drawing)
549
+ } catch (error) {
550
+ if (error instanceof DrawingError) throw new CommentError(400, error.code, error.message)
551
+ throw error
552
+ }
553
+ return { images, drawing }
554
+ }
555
+
513
556
  // `mention` keeps comments whose text or replies mention that handle.
514
557
  export function listComments(config, boardId, { status = null, mention = null } = {}) {
515
558
  const { comments } = readCommentStore(config, boardId)
@@ -590,8 +633,13 @@ async function logEvents(config, events) {
590
633
 
591
634
  export async function createComment(config, board, input, { now = new Date() } = {}) {
592
635
  const clean = validateCommentInput(config, board, input)
636
+ const media = validateCommentMedia(input)
593
637
  const file = commentsFile(config, board.id)
594
638
  let events = []
639
+ // Written before the lock (new random names), removed again if the
640
+ // comment is not saved.
641
+ const images = saveCommentImages(boardDir(config, board.id), media.images)
642
+ let stored = false
595
643
  const saved = await withFileLock(file, async () => {
596
644
  assertLocalComments(config, board.id)
597
645
  const store = readCommentStore(config, board.id)
@@ -612,11 +660,17 @@ export async function createComment(config, board, input, { now = new Date() } =
612
660
  agentStatusAt: null,
613
661
  }
614
662
  if (!comment.anchor) delete comment.anchor
663
+ if (images.length) comment.images = images
664
+ // The drawing belongs to the capture it was drawn on.
665
+ if (media.drawing) comment.drawing = { ...media.drawing, captureVersion: comment.captureVersion }
615
666
  store.comments.push(comment)
616
667
  writeJsonAtomic(file, { nextId: store.nextId + 1, comments: store.comments })
668
+ stored = true
617
669
  const result = withAgentFields(comment)
618
670
  events = await logEvents(config, createdEvents(board.id, result, now))
619
671
  return result
672
+ }).finally(() => {
673
+ if (!stored) removeImageFiles(boardDir(config, board.id), images)
620
674
  })
621
675
  emitCommentEvents(events)
622
676
  return saved
@@ -692,6 +746,8 @@ export async function deleteComment(config, boardId, commentId) {
692
746
  const kept = store.comments.filter((item) => item.id !== id)
693
747
  if (kept.length === store.comments.length) throw new CommentError(404, 'unknown_comment', 'That comment does not exist.')
694
748
  writeJsonAtomic(file, { nextId: store.nextId, comments: kept })
749
+ // Its images, its replies' images and its rendered drawings go with it.
750
+ for (const gone of store.comments.filter((item) => item.id === id)) removeCommentMedia(boardDir(config, boardId), gone)
695
751
  return true
696
752
  })
697
753
  }
@@ -704,16 +760,22 @@ export async function deleteComment(config, boardId, commentId) {
704
760
  // fixed; a person still resolves) or needs-human (the agent stopped and
705
761
  // asked). `shapewall watch` claims a comment by moving agentStatus from null
706
762
  // to queued under the file lock, so two watchers never take the same one.
763
+ // Agent branch mode adds branch-ready (comment-fields.js), with the branch's
764
+ // name in agentBranch while the status lasts.
707
765
 
708
- export const AGENT_STATUSES = ['queued', 'working', 'done', 'needs-human']
709
766
  const REPLIES_MAX = 200
767
+ const AGENT_BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*(?:\/[A-Za-z0-9][A-Za-z0-9_-]*)*$/
710
768
 
711
769
  function cleanAgentStatus(value) {
712
- if (value === null || AGENT_STATUSES.includes(value)) return value
713
- throw new CommentError(400, 'invalid_agent_status', `Agent status must be one of ${AGENT_STATUSES.join(', ')} (or null to clear).`)
770
+ if (value === null || STORED_AGENT_STATUSES.includes(value)) return value
771
+ throw new CommentError(400, 'invalid_agent_status', `Agent status must be one of ${STORED_AGENT_STATUSES.join(', ')} (or null to clear).`)
714
772
  }
715
773
 
716
- function setAgent(comment, agentStatus, now) {
774
+ const cleanAgentBranch = (value) => (typeof value === 'string' && value.length <= 120 && AGENT_BRANCH_RE.test(value) ? value : null)
775
+
776
+ function setAgent(comment, agentStatus, now, branch = null) {
777
+ if (agentStatus === BRANCH_READY && cleanAgentBranch(branch)) comment.agentBranch = branch
778
+ else delete comment.agentBranch
717
779
  if ((comment.agentStatus ?? null) === agentStatus) return
718
780
  comment.agentStatus = agentStatus
719
781
  comment.agentStatusAt = agentStatus ? now.toISOString() : null
@@ -760,29 +822,46 @@ export function getComment(config, boardId, commentId) {
760
822
  }
761
823
 
762
824
  // Adds a reply. Returns { comment, reply }.
825
+ // `images` and `drawing` as on a new comment (validateCommentMedia).
763
826
  export async function addReply(config, boardId, commentId, input, { now = new Date() } = {}) {
764
827
  const body = cleanBody(input?.body)
765
828
  const author = cleanAuthor(input?.author)
766
- const { comment, result } = await changeComment(
767
- config,
768
- boardId,
769
- commentId,
770
- (target) => {
771
- const replies = Array.isArray(target.replies) ? target.replies : []
772
- if (replies.length >= REPLIES_MAX) throw new CommentError(409, 'too_many_replies', `A comment holds at most ${REPLIES_MAX} replies.`)
773
- const reply = {
774
- id: Math.max(0, ...replies.map((item) => Number(item.id) || 0)) + 1,
775
- author,
776
- body,
777
- createdAt: now.toISOString(),
778
- }
779
- target.replies = [...replies, reply]
780
- return reply
781
- },
782
- now,
783
- (saved, reply) => replyEvents(boardId, saved, reply, now),
784
- )
785
- return { comment, reply: result }
829
+ const media = validateCommentMedia(input)
830
+ const images = saveCommentImages(boardDir(config, boardId), media.images)
831
+ let stored = false
832
+ try {
833
+ const { comment, result } = await changeComment(
834
+ config,
835
+ boardId,
836
+ commentId,
837
+ (target) => {
838
+ const replies = Array.isArray(target.replies) ? target.replies : []
839
+ if (replies.length >= REPLIES_MAX)
840
+ throw new CommentError(409, 'too_many_replies', `A comment holds at most ${REPLIES_MAX} replies.`)
841
+ const reply = {
842
+ id: Math.max(0, ...replies.map((item) => Number(item.id) || 0)) + 1,
843
+ author,
844
+ body,
845
+ createdAt: now.toISOString(),
846
+ }
847
+ if (images.length) reply.images = images
848
+ if (media.drawing) {
849
+ const version = String(target.pageId).startsWith('variant:')
850
+ ? null
851
+ : currentVersion(config, boardId, target.pageId, target.viewport)
852
+ reply.drawing = { ...media.drawing, captureVersion: version }
853
+ }
854
+ target.replies = [...replies, reply]
855
+ stored = true
856
+ return reply
857
+ },
858
+ now,
859
+ (saved, reply) => replyEvents(boardId, saved, reply, now),
860
+ )
861
+ return { comment, reply: withMedia(result) }
862
+ } finally {
863
+ if (!stored) removeImageFiles(boardDir(config, boardId), images)
864
+ }
786
865
  }
787
866
 
788
867
  // Adds or takes away a person's emoji reaction on a comment (replyId null)
@@ -820,7 +899,14 @@ export async function reactToComment(config, boardId, commentId, { emoji, replyI
820
899
  // meaning unset) the change is a compare-and-set: it happens only when the
821
900
  // comment is open and its status is one of them. Returns { comment, changed }.
822
901
  // `actor` names who made the change in its event.
823
- export async function setAgentStatus(config, boardId, commentId, agentStatus, { onlyFrom = null, now = new Date(), actor = null } = {}) {
902
+ // `branch`: with branch-ready, the name of the branch the fix waits on.
903
+ export async function setAgentStatus(
904
+ config,
905
+ boardId,
906
+ commentId,
907
+ agentStatus,
908
+ { onlyFrom = null, now = new Date(), actor = null, branch = null } = {},
909
+ ) {
824
910
  const next = cleanAgentStatus(agentStatus)
825
911
  let previous = null
826
912
  const { comment, changed } = await changeComment(
@@ -828,11 +914,11 @@ export async function setAgentStatus(config, boardId, commentId, agentStatus, {
828
914
  boardId,
829
915
  commentId,
830
916
  (target) => {
831
- const current = AGENT_STATUSES.includes(target.agentStatus) ? target.agentStatus : null
917
+ const current = STORED_AGENT_STATUSES.includes(target.agentStatus) ? target.agentStatus : null
832
918
  if (onlyFrom && (target.status !== 'open' || !onlyFrom.includes(current))) return false
833
919
  if (current === next) return false
834
920
  previous = current
835
- setAgent(target, next, now)
921
+ setAgent(target, next, now, branch)
836
922
  },
837
923
  now,
838
924
  (saved) => updateEvents(boardId, { ...saved, agentStatus: previous }, saved, now, cleanActor(actor)),
package/src/watch.js CHANGED
@@ -108,6 +108,10 @@ export function commentEnv(config, board, item, commentFile) {
108
108
  SHAPEWALL_LIVE_HTML: item.files.liveHtml || '',
109
109
  // The page as it is now, when it was captured again since the comment.
110
110
  SHAPEWALL_LATEST_SCREENSHOT: item.files.latestScreenshot || '',
111
+ // The reviewer's drawing on the screenshot (a PNG), and their images
112
+ // (paths, one per line); the comment file has their sizes and types.
113
+ SHAPEWALL_MARKUP: item.files.markup || '',
114
+ SHAPEWALL_IMAGES: (item.files.images || []).map((image) => image.path).join('\n'),
111
115
  SHAPEWALL_COMMENT_FILE: commentFile,
112
116
  SHAPEWALL_CONFIG: config.file || '',
113
117
  }