shapewall 0.3.0 → 0.3.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 (64) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +3 -1
  3. package/dist/agent/package-lock.json +2 -2
  4. package/dist/client/assets/BoardChat-BeRp6007.js +27 -0
  5. package/dist/client/assets/{BuzzDialog-Ds7Thpfe.js → BuzzDialog-CrYy48hh.js} +1 -1
  6. package/dist/client/assets/ChecksPanel-CB820mhj.js +1 -0
  7. package/dist/client/assets/History-Ba909bGJ.js +1 -0
  8. package/dist/client/assets/{LocalSettings-CSNMhNyV.js → LocalSettings-ChMi9Zir.js} +1 -1
  9. package/dist/client/assets/{Management-CJVNAqAW.js → Management-DmTh1-tA.js} +1 -1
  10. package/dist/client/assets/QuickConnect-CrVweWZB.js +1 -0
  11. package/dist/client/assets/{ShareDialog-BouvNraR.js → ShareDialog-DO2HhY6g.js} +2 -2
  12. package/dist/client/assets/{app-update-dialog-rhaw0MRk.js → app-update-dialog-C09ODdUQ.js} +1 -1
  13. package/dist/client/assets/{circle-x-PRxj7kPi.js → circle-x-3UxAvczM.js} +1 -1
  14. package/dist/client/assets/index-BIjfZKnp.js +37 -0
  15. package/dist/client/assets/{refresh-cw-aeOBDuGQ.js → refresh-cw-BRHNyCnY.js} +1 -1
  16. package/dist/client/assets/{shield-check-DuPBJ6H_.js → shield-check-DMpniYP6.js} +1 -1
  17. package/dist/client/assets/ui-mhL9gsne.js +41 -0
  18. package/dist/client/build-info.json +1 -1
  19. package/dist/client/index.html +2 -2
  20. package/dist/client/sw.js +2 -2
  21. package/dist/console/assets/{LocalAccountsApp-DOKZI6Lt.js → LocalAccountsApp-IvHd9zWN.js} +1 -1
  22. package/dist/console/assets/{LocalConsole-DXzldLW9.js → LocalConsole-DOyLou56.js} +1 -1
  23. package/dist/console/assets/{app-update-dialog-CrqIMEwN.js → app-update-dialog-Da46CJpv.js} +1 -1
  24. package/dist/console/assets/{console-76WovHlh.js → console-CIBv7cXU.js} +5 -5
  25. package/dist/console/build-info.json +1 -1
  26. package/dist/console/console.html +1 -1
  27. package/docs/agent-workflow.md +19 -3
  28. package/docs/config.md +2 -2
  29. package/docs/pull-requests.md +7 -3
  30. package/package.json +1 -1
  31. package/src/agent/composer.js +9 -5
  32. package/src/agent/context.js +3 -1
  33. package/src/agent/routes.js +2 -1
  34. package/src/agent/starter/worktree.js +32 -4
  35. package/src/agent/tools.js +2 -1
  36. package/src/capture/capture.js +3 -1
  37. package/src/capture/element-map.js +12 -7
  38. package/src/ci/settings.js +3 -3
  39. package/src/ci/start.js +16 -0
  40. package/src/ci/summary.js +8 -1
  41. package/src/ci/workflow.js +14 -3
  42. package/src/cli/args.js +1 -0
  43. package/src/cli/ci.js +2 -2
  44. package/src/cli/comments.js +5 -4
  45. package/src/cli/help.js +3 -1
  46. package/src/cli/init.js +10 -7
  47. package/src/comment-fields.js +45 -0
  48. package/src/comments-cli.js +100 -21
  49. package/src/discover.js +34 -1
  50. package/src/doctor.js +26 -1
  51. package/src/event-log.js +5 -2
  52. package/src/feedback.js +5 -2
  53. package/src/github.js +4 -2
  54. package/src/hosted/board-routes.js +2 -1
  55. package/src/hosted/comments.js +11 -11
  56. package/src/hosted/import.js +7 -4
  57. package/src/notify/messages.js +6 -4
  58. package/src/store.js +14 -11
  59. package/dist/client/assets/BoardChat-CupOxioV.js +0 -27
  60. package/dist/client/assets/ChecksPanel-BqrS02Ih.js +0 -1
  61. package/dist/client/assets/History-CQG3NQOC.js +0 -1
  62. package/dist/client/assets/QuickConnect-B-4pUgXH.js +0 -1
  63. package/dist/client/assets/index-DKOCIQiq.js +0 -37
  64. package/dist/client/assets/ui-Cg4TTrec.js +0 -41
@@ -1 +1 @@
1
- {"version":"0.3.0","revision":"c34ececf96613a351c6811f5b6ee7e932d65e65b"}
1
+ {"version":"0.3.2","revision":"66f3267ba8e0bb2998ecbf3f3e393c4ee6946c82"}
@@ -12,7 +12,7 @@
12
12
  <title>Shapewall</title>
13
13
  <!-- Saved light/dark mode and theme, before the first paint (see src/lib/theme.js). -->
14
14
  <script src="/_console/theme-boot.js"></script>
15
- <script type="module" crossorigin src="/_console/assets/console-76WovHlh.js"></script>
15
+ <script type="module" crossorigin src="/_console/assets/console-CIBv7cXU.js"></script>
16
16
  <link rel="stylesheet" crossorigin href="/_console/assets/console-Fp4k9iyx.css">
17
17
  </head>
18
18
  <body>
@@ -87,6 +87,10 @@ to comments after that id, or created or changed after that ISO time (`--since 1
87
87
  One comment, the same shape: `shapewall comments get 12 [--json]`. Every write prints its result with `--json` too (`reply`, `status`,
88
88
  `resolve`, `reopen`, `add`).
89
89
 
90
+ A comment or a reply made on the board can be a drawing or images with no text. Its `body` is then `""` in JSON (the `drawing`,
91
+ `files.markup` and `files.images` fields say what it has), and the text listing shows `(drawing)`, `(image)` or `(2 images)` in its
92
+ place.
93
+
90
94
  ### Adding a comment from the command line
91
95
 
92
96
  ```sh
@@ -98,8 +102,19 @@ It goes through the same checks, events, mentions and notifications as a comment
98
102
  `--viewport` defaults to the page's first; `--author` defaults to `agent` (like `reply`; the starter agent never acts on an agent's own
99
103
  comment, so text a bot relays waits for a trusted person to tag it). Without `--selector` the pin sits near the page's top-left corner.
100
104
  With one, it is anchored to that element, using the selector grammar comments show (`#id`, `tag[data-testid="..."]`,
101
- `tag[aria-label="..."]`, `tag:nth-of-type(n)`, joined by `>`); the element text is read from the latest capture when the selector finds
102
- exactly one element there, and a note says so when it does not.
105
+ `tag[aria-label="..."]`, `tag:nth-of-type(n)`, joined by `>`). When the selector finds exactly one element in the latest capture, the
106
+ pin sits in the middle of that element, as if you had clicked there on the board, and the element's text is saved with it. When it does
107
+ not, a note says so, the selector is saved anyway and the pin stays near the corner.
108
+
109
+ To find a selector, list the ones the latest capture has, with each element's text:
110
+
111
+ ```sh
112
+ shapewall comments selectors --page signup --viewport phone --text "create account"
113
+ # button[data-testid="signup-submit"] ("Create account")
114
+ ```
115
+
116
+ `--text` keeps the elements whose text contains those words (any case); `--json` prints `{ selectors: [{ selector, text }] }`. The list
117
+ comes from the capture's element map (`<output>/<board>/captures/<page>.<viewport>.elements.json`), so capture the page first.
103
118
 
104
119
  ### Agent status
105
120
 
@@ -113,7 +128,8 @@ exactly one element there, and a note says so when it does not.
113
128
  | `done` | The agent thinks it is fixed and recaptured. A person checks and resolves. | the agent, or `watch` on exit 0 + reply |
114
129
  | `needs-human` | The agent stopped: unclear request, failure, timeout. A reply says why. | the agent, or `watch` on failure |
115
130
 
116
- Resolving keeps the agent status (the MCP `resolve_comment` tool sets it to `done`); reopening clears it.
131
+ Resolving a comment that is `queued` or `working` sets it to `done`, and clears `needs-human` (the question is answered), however it
132
+ is resolved: the board, `comments resolve`, the API or the MCP `resolve_comment` tool. Reopening clears the agent status.
117
133
 
118
134
  ### API
119
135
 
package/docs/config.md CHANGED
@@ -404,7 +404,7 @@ Capture on every pull request: what `shapewall ci` and the workflow from `shapew
404
404
  ```json
405
405
  {
406
406
  "ci": {
407
- "threshold": 0.001,
407
+ "threshold": 0.00001,
408
408
  "pages": ["home", "pricing", "login"],
409
409
  "viewports": ["desktop", "phone"],
410
410
  "ignore": [".clock", "#ad-slot"],
@@ -416,7 +416,7 @@ Capture on every pull request: what `shapewall ci` and the workflow from `shapew
416
416
  | Key | Type | Default | Notes |
417
417
  | ----------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
418
418
  | `enabled` | boolean | `true` | `false` turns pull request captures off without deleting the workflow. |
419
- | `threshold` | 0-1 | `0.001` | Share of pixels below which a shot counts as unchanged (0.001 is 0.1%). A size change always counts. `--threshold` overrides it. |
419
+ | `threshold` | 0-1 | `0.00001` | Share of pixels below which a shot counts as unchanged (0.00001 is 0.001%). A size change always counts. `--threshold` overrides it. |
420
420
  | `pages` | string[] | every page | Page ids to compare (an allow-list), in the config's order. |
421
421
  | `viewports` | string[] | each page's own | Viewport names to compare. |
422
422
  | `ignore` | string[] | none | CSS selectors hidden (`visibility: hidden`) on both sides before each shot: clocks, ads, random content. Up to 50. |
@@ -101,7 +101,10 @@ going) and a 25 minute capture timeout.
101
101
  - `images/<page>.<viewport>/`: `before.png`, `after.png`, `diff.png` (the after shot faded, changed pixels in red) and a 320 pixel wide
102
102
  `.thumb.png` of each, for changed shots only.
103
103
 
104
- A shot counts as changed when its share of changed pixels reaches `ci.threshold` (default 0.001, that is 0.1%) or its size changed.
104
+ A shot counts as changed when its share of changed pixels reaches `ci.threshold` or its size changed. The default is 0.00001, that is
105
+ 0.001%: about 30 pixels of a 1440 by 2200 desktop shot, so a changed price or a renamed button is reported. Both sides are captured
106
+ by the same browser in the same job and anti-aliasing is ignored, so an unchanged page compares as equal; if a page of yours still
107
+ flickers (a clock, a carousel), name the element in `ci.ignore` or raise the threshold.
105
108
  A page that answers 404 before and loads after is a new page; the other way round, a removed page.
106
109
 
107
110
  You can run it on your own machine too:
@@ -126,8 +129,9 @@ With `"ci": { "images": "branch" }`, the comment shows thumbnails inline: the jo
126
129
  images.
127
130
  - The images are public and stay in the branch history until you delete the branch. Delete it any time; old comments then lose their
128
131
  pictures.
129
- - The comment job needs `contents: write` in its `permissions` to push the branch. Without it, the comment falls back to links and
130
- says why.
132
+ - The comment job needs `contents: write` in its `permissions` to push the branch. `shapewall init --ci` writes that when the config
133
+ already has `"images": "branch"`; if you add the setting later, change `contents: read` to `contents: write` in the comment job (or
134
+ run `shapewall init --ci --force`). Without it, the comment falls back to links and says why.
131
135
 
132
136
  ## Turning it off
133
137
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shapewall",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Every page of your site on one zoomable wall: desktop and phone captures, sandboxed live HTML, and element-anchored comments your coding agent can read.",
5
5
  "license": "Apache-2.0 AND FSL-1.1-ALv2",
6
6
  "author": "Dan Baruch",
@@ -13,6 +13,7 @@ import { MENTION_HANDLE_RE, commentMentions, handleFor } from '../mentions.js'
13
13
  import { quoteData } from './context.js'
14
14
  import { AgentError } from './errors.js'
15
15
  import { commentForModel } from './tools.js'
16
+ import { commentText } from '../comment-fields.js'
16
17
 
17
18
  export const MENTIONS_MAX = 8
18
19
  export const FILES_MAX = 3
@@ -68,7 +69,7 @@ export function validateMentions(config, board, raw) {
68
69
  const id = Number(item.id)
69
70
  const found = Number.isSafeInteger(id) && id > 0 ? comment(id) : null
70
71
  if (found && (kind === 'comment' || found.anchor)) {
71
- const text = kind === 'element' ? found.anchor?.text || found.anchor?.selector || 'element' : found.body
72
+ const text = kind === 'element' ? found.anchor?.text || found.anchor?.selector || 'element' : commentText(found)
72
73
  entry = { kind, id: found.id, label: cut(`#${found.id} ${text}`, LABEL_MAX) }
73
74
  }
74
75
  } else if (kind === 'journey') {
@@ -135,7 +136,7 @@ export function mentionContext(config, board, mention, find = commentById(config
135
136
  element: { selector: comment.anchor?.selector || null, text: comment.anchor?.text || null },
136
137
  page: page ? { id: page.id, title: page.title, path: page.path } : { id: comment.pageId },
137
138
  viewport: comment.viewport,
138
- comment: { id: comment.id, body: cut(comment.body, BODY_MAX), status: comment.status },
139
+ comment: { id: comment.id, body: cut(commentText(comment), BODY_MAX), status: comment.status },
139
140
  },
140
141
  )
141
142
  }
@@ -170,9 +171,12 @@ export function mentionContext(config, board, mention, find = commentById(config
170
171
  { ...attrs, person: handle },
171
172
  {
172
173
  person: `@${handle}`,
173
- openComments: theirs
174
- .slice(0, PERSON_COMMENTS_MAX)
175
- .map((comment) => ({ id: comment.id, page: comment.pageId, author: comment.author || null, body: cut(comment.body, 300) })),
174
+ openComments: theirs.slice(0, PERSON_COMMENTS_MAX).map((comment) => ({
175
+ id: comment.id,
176
+ page: comment.pageId,
177
+ author: comment.author || null,
178
+ body: cut(commentText(comment), 300),
179
+ })),
176
180
  more: Math.max(0, theirs.length - PERSON_COMMENTS_MAX) || undefined,
177
181
  },
178
182
  )
@@ -6,6 +6,8 @@
6
6
  // system prompt. The payload is JSON with <, > and & escaped, so no text can
7
7
  // close the element early or forge another one.
8
8
 
9
+ import { commentText } from '../comment-fields.js'
10
+
9
11
  // How to point at the board: the panel turns these into links to the board
10
12
  // (client/src/chat/refs.js), and only for ids the board has.
11
13
  export const REFS_RULE =
@@ -143,7 +145,7 @@ export function openCommentsContext({ board, comments, skip = null, max = COMMEN
143
145
  for (const comment of open) {
144
146
  if (blocks.length >= max) break
145
147
  const page = pages.get(comment.pageId)
146
- const body = String(comment.body || '')
148
+ const body = commentText(comment)
147
149
  const block = quoteData(
148
150
  'comment',
149
151
  {
@@ -104,6 +104,7 @@ import {
104
104
  versionsOf,
105
105
  visibleTo,
106
106
  } from './threads.js'
107
+ import { commentText } from '../comment-fields.js'
107
108
 
108
109
  // Four 5 MB images in base64, and the text. Only POST .../messages reads a
109
110
  // body this big, and only once the message is allowed to run.
@@ -493,7 +494,7 @@ export function agentRouter({
493
494
  .find(Boolean)
494
495
  ?.slice(0, 72) || ''
495
496
  const message = comment
496
- ? `Fix comment #${commentId}: ${firstLine(comment.body) || 'agent change'}\n\n${commentLink(config, boardUrlFor(config, { env }), board.id, comment)}\n\nshapewall:${board.id}/${commentId}\n`
497
+ ? `Fix comment #${commentId}: ${firstLine(commentText(comment)) || 'agent change'}\n\n${commentLink(config, boardUrlFor(config, { env }), board.id, comment)}\n\nshapewall:${board.id}/${commentId}\n`
497
498
  : `Agent change from chat: ${firstLine(userText) || threadId}\n\nshapewall:${board.id}/${threadId}\n`
498
499
  let commit = null
499
500
  try {
@@ -621,18 +621,46 @@ export function sweepWorkRoot(root, { now = Date.now(), isAlive = alive, keep =
621
621
  return removed
622
622
  }
623
623
 
624
+ // What a push may travel over: https, http, ssh and a local path. Everything
625
+ // else is off, so a remote URL (or a url.*.insteadOf rewrite) in the
626
+ // repository's config cannot pick a transport that runs a program
627
+ // ("ext::sh -c ...", or any other git-remote-<name> helper). This is the
628
+ // environment variable, not `-c protocol.allow=never`: a protocol.<name>.allow
629
+ // in the repository's config would win over that, and never over this.
630
+ const PUSH_PROTOCOLS = 'https:http:ssh:file'
631
+
624
632
  // Pushes the agent's branch, and only it, to the same name on the remote.
633
+ //
634
+ // The push uses the person's own credentials on purpose (their credential
635
+ // helper, their ssh setup): that is how it reaches their remote at all. What
636
+ // it does not take from the repository's config is anything that would run a
637
+ // different program or send something else: the transport is limited (above),
638
+ // the receiving program is git's own whatever remote.<name>.receivepack says,
639
+ // and the push is not signed, so no gpg program runs.
625
640
  export async function pushBranch({ tree, remote }) {
626
641
  const { branch } = tree
627
642
  const last = branch.split('/').pop()
628
643
  if (PROTECTED_BRANCHES.has(branch) || PROTECTED_BRANCHES.has(last)) throw new Error(`refusing to push "${branch}"`)
644
+ // A remote name starting with "-" would be read as an option.
645
+ if (typeof remote !== 'string' || !remote || remote.startsWith('-')) throw new Error('refusing to push: not a remote name')
629
646
  // No tags (push.followTags) and no submodule pushes (push.recurseSubmodules)
630
647
  // from the person's config: the branch is all that goes.
631
648
  const refspec = `refs/heads/${branch}:refs/heads/${branch}`
632
- await git(['--git-dir', tree.gitDir, 'push', '--no-verify', '--no-follow-tags', '--recurse-submodules=no', remote, refspec], {
633
- cwd: tree.repo,
634
- timeoutMs: 180000,
635
- })
649
+ await git(
650
+ [
651
+ '--git-dir',
652
+ tree.gitDir,
653
+ 'push',
654
+ '--no-verify',
655
+ '--no-follow-tags',
656
+ '--no-signed',
657
+ '--recurse-submodules=no',
658
+ '--receive-pack=git-receive-pack',
659
+ remote,
660
+ refspec,
661
+ ],
662
+ { cwd: tree.repo, timeoutMs: 180000, extraEnv: { GIT_ALLOW_PROTOCOL: PUSH_PROTOCOLS } },
663
+ )
636
664
  }
637
665
 
638
666
  export { alive as processAlive }
@@ -6,6 +6,7 @@ import fs from 'node:fs'
6
6
  import { feedbackContext, feedbackItem } from '../feedback.js'
7
7
  import { addReply, captureFiles, commentCounts, getComment, listComments, setAgentStatus, updateComment } from '../store.js'
8
8
  import { quoteData } from './context.js'
9
+ import { commentText } from '../comment-fields.js'
9
10
 
10
11
  const LIST_MAX = 100
11
12
 
@@ -112,7 +113,7 @@ export const BOARD_TOOLS = [
112
113
  pageId: comment.pageId,
113
114
  viewport: comment.viewport,
114
115
  status: comment.status,
115
- body: comment.body,
116
+ body: commentText(comment),
116
117
  author: comment.author || null,
117
118
  element: comment.anchor?.text || null,
118
119
  agentStatus: comment.agentStatus || null,
@@ -541,9 +541,11 @@ export async function runCapture({
541
541
  pages: partial && previous?.pages ? { ...previous.pages } : {},
542
542
  }
543
543
  browser = await launchBrowser(config, { chromium })
544
- const storageState = await resolveStorageState(browser, config, board, { log })
545
544
  // The default environment is the board's baseUrl (which callers may override).
546
545
  const baseUrl = isDefault ? board.baseUrl : env.baseUrl
546
+ // The login script signs in to the environment being captured, not always
547
+ // the first one (as the page checks already did).
548
+ const storageState = await resolveStorageState(browser, config, { ...board, baseUrl }, { log })
547
549
  const options = captureOptions(config, board)
548
550
  const stateFor = setupStates({ browser, board, config, baseUrl, base: storageState, viewports })
549
551
  if (board.setup)
@@ -433,14 +433,16 @@ function stepMatches(item, step) {
433
433
  return item.n === step.nth
434
434
  }
435
435
 
436
- // The first element (document order) a stored selector names, or -1: the
437
- // map's answer to querySelector() for the anchor grammar (child combinators).
438
- export function matchSelector(map, selector) {
436
+ // Every element (document order) a stored selector names: the map's answer
437
+ // to querySelectorAll() for the anchor grammar (child combinators). `max`
438
+ // stops the search early.
439
+ export function matchSelectorAll(map, selector, max = Infinity) {
440
+ const found = []
439
441
  const steps = parseSelector(selector)
440
- if (!steps?.length) return -1
442
+ if (!steps?.length) return found
441
443
  const elements = map?.elements || []
442
444
  const last = steps[steps.length - 1]
443
- for (let position = 0; position < elements.length; position += 1) {
445
+ for (let position = 0; position < elements.length && found.length < max; position += 1) {
444
446
  if (!stepMatches(elements[position], last)) continue
445
447
  let node = elements[position].p
446
448
  let ok = true
@@ -451,11 +453,14 @@ export function matchSelector(map, selector) {
451
453
  }
452
454
  node = elements[node].p
453
455
  }
454
- if (ok) return position
456
+ if (ok) found.push(position)
455
457
  }
456
- return -1
458
+ return found
457
459
  }
458
460
 
461
+ // The first element a stored selector names, or -1 (querySelector()).
462
+ export const matchSelector = (map, selector) => matchSelectorAll(map, selector, 1)[0] ?? -1
463
+
459
464
  function lastTag(selector) {
460
465
  const last = String(selector).split('>').pop().trim()
461
466
  const match = /^([a-z][a-z0-9-]*)/i.exec(last)
@@ -11,7 +11,7 @@
11
11
 
12
12
  export const CI_DEFAULTS = Object.freeze({
13
13
  enabled: true,
14
- threshold: 0.001,
14
+ threshold: 0.00001,
15
15
  images: 'links',
16
16
  maxPages: 50,
17
17
  })
@@ -142,7 +142,7 @@ function validateStart(raw, where, problems) {
142
142
  export function validateCi(raw, problems, { pageIds = [], viewportNames = [] } = {}) {
143
143
  if (raw === undefined || raw === null) return { ...CI_DEFAULTS, pages: null, viewports: null, ignore: [], start: null }
144
144
  if (!isObject(raw)) {
145
- problems.push('ci: an object such as { "enabled": true, "threshold": 0.001 }')
145
+ problems.push('ci: an object such as { "enabled": true, "threshold": 0.00001 }')
146
146
  return { ...CI_DEFAULTS, pages: null, viewports: null, ignore: [], start: null }
147
147
  }
148
148
  const known = ['enabled', 'threshold', 'pages', 'viewports', 'ignore', 'images', 'maxPages', 'start']
@@ -154,7 +154,7 @@ export function validateCi(raw, problems, { pageIds = [], viewportNames = [] } =
154
154
  }
155
155
  if (raw.threshold !== undefined) {
156
156
  if (typeof raw.threshold !== 'number' || !Number.isFinite(raw.threshold) || raw.threshold < 0 || raw.threshold > 1)
157
- problems.push('ci.threshold: the share of pixels (0 to 1, such as 0.001 for 0.1%) below which a shot counts as unchanged')
157
+ problems.push('ci.threshold: the share of pixels (0 to 1, such as 0.00001 for 0.001%) below which a shot counts as unchanged')
158
158
  else ci.threshold = raw.threshold
159
159
  }
160
160
  if (raw.pages !== undefined) {
package/src/ci/start.js CHANGED
@@ -118,6 +118,17 @@ export async function waitForUrl(url, { timeout = 180000, interval = 1000, fetch
118
118
  }
119
119
  }
120
120
 
121
+ // True when `url` answers at all right now (any status).
122
+ async function answers(url, fetchImpl = globalThis.fetch) {
123
+ try {
124
+ const response = await fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(3000) })
125
+ await response.body?.cancel().catch(() => {})
126
+ return true
127
+ } catch {
128
+ return false
129
+ }
130
+ }
131
+
121
132
  // Runs install and build, starts serve and waits for `url`. Returns { stop }.
122
133
  export async function startSite(start, { cwd, url, env = process.env, log = () => {}, fetchImpl } = {}) {
123
134
  const childEnv = commandEnv(env)
@@ -126,6 +137,11 @@ export async function startSite(start, { cwd, url, env = process.env, log = () =
126
137
  log(`ci.start.${step}: ${describe(start[step])} (in ${cwd})`)
127
138
  await runToEnd(start[step], { cwd, env: childEnv, log, timeout: start.timeout })
128
139
  }
140
+ // Something already answering there would be captured in place of this
141
+ // checkout (and serve would fail on the taken port a moment too late): the
142
+ // base and the head would then show the same site, and "no visual changes".
143
+ if (await answers(url, fetchImpl))
144
+ throw new Error(`${url} already answers before ci.start.serve ran: stop what is serving it, so the capture is of this checkout`)
129
145
  log(`ci.start.serve: ${describe(start.serve)} (in ${cwd})`)
130
146
  const server = launch(start.serve, { cwd, env: childEnv, log, detached: process.platform !== 'win32' })
131
147
  let exited = null
package/src/ci/summary.js CHANGED
@@ -142,6 +142,13 @@ export function percent(ratio) {
142
142
  return `${value.toFixed(2)}%`
143
143
  }
144
144
 
145
+ // The threshold in words: "0.10%" as before, and a small one in full
146
+ // ("0.001%") where percent() would say "<0.01%".
147
+ export function thresholdPercent(ratio) {
148
+ const value = ratio * 100
149
+ return value > 0 && value < 0.01 ? `${Number(value.toPrecision(2))}%` : percent(ratio)
150
+ }
151
+
145
152
  function screen(shot) {
146
153
  const size = shot.viewportSize ? ` ${shot.viewportSize.width}x${shot.viewportSize.height}` : ''
147
154
  return `${plain(shot.viewport, 32)}${size}`
@@ -221,7 +228,7 @@ export function renderSummary(summary, { artifactUrl = null, runUrl = null, imag
221
228
  if (totals.newPages) facts.push(plural(totals.newPages, 'new page'))
222
229
  if (totals.removedPages) facts.push(plural(totals.removedPages, 'removed page'))
223
230
  if (totals.pagesNotCompared) facts.push(`${plural(totals.pagesNotCompared, 'page')} left out by the page limit`)
224
- facts.push(`a shot counts as changed from ${percent(summary.threshold)} of its pixels`)
231
+ facts.push(`a shot counts as changed from ${thresholdPercent(summary.threshold)} of its pixels`)
225
232
  lines.push(`${facts.join(', ')}.`)
226
233
  const links = []
227
234
  if (changed.length && artifactUrl) links.push(`[Before, after and diff images](${artifactUrl}) (the "shapewall-ci" artifact of this run)`)
@@ -8,7 +8,9 @@ export const WORKFLOW_FILE = '.github/workflows/shapewall.yml'
8
8
 
9
9
  const PACKAGE = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
10
10
 
11
- export function workflowYaml({ version = PACKAGE.version, playwright = PACKAGE.dependencies.playwright } = {}) {
11
+ // `imagesBranch`: the config has "ci": { "images": "branch" }, so the comment
12
+ // job may push the images branch (contents: write).
13
+ export function workflowYaml({ version = PACKAGE.version, playwright = PACKAGE.dependencies.playwright, imagesBranch = false } = {}) {
12
14
  return `# Shapewall: capture on every pull request.
13
15
  #
14
16
  # On each pull request (and each push to it) this job captures the pages in
@@ -198,10 +200,19 @@ jobs:
198
200
  if: always() && needs.shapewall.outputs.enabled == 'true'
199
201
  runs-on: ubuntu-latest
200
202
  timeout-minutes: 10
201
- # For "ci.images": "branch" (public repositories only) also set contents: write.
203
+ ${
204
+ imagesBranch
205
+ ? ` # contents: write is for "ci.images": "branch" (public repositories only): this
206
+ # job pushes the images to the shapewall-ci branch. Without that
207
+ # setting, contents: read is enough.
208
+ permissions:
209
+ contents: write
210
+ pull-requests: write`
211
+ : ` # For "ci.images": "branch" (public repositories only) also set contents: write.
202
212
  permissions:
203
213
  contents: read
204
- pull-requests: write
214
+ pull-requests: write`
215
+ }
205
216
  env:
206
217
  SHAPEWALL: shapewall@${version}
207
218
  steps:
package/src/cli/args.js CHANGED
@@ -128,6 +128,7 @@ export const COMMAND_FLAGS = {
128
128
  'since',
129
129
  'viewport',
130
130
  'selector',
131
+ 'text',
131
132
  'json',
132
133
  'for-agent',
133
134
  'note',
package/src/cli/ci.js CHANGED
@@ -12,7 +12,7 @@ import { CONFIG_FILE, findConfigFile, getBoard, loadConfig } from '../config.js'
12
12
  import { CI_DEFAULTS } from '../ci/settings.js'
13
13
  import { captureSide, ciPages } from '../ci/capture.js'
14
14
  import { compareCaptures } from '../ci/compare.js'
15
- import { headline } from '../ci/summary.js'
15
+ import { headline, percent } from '../ci/summary.js'
16
16
  import { commentFromResult, prContext, skipRequested } from '../ci/github.js'
17
17
  import { startRefusal, startSite, waitForUrl } from '../ci/start.js'
18
18
 
@@ -187,7 +187,7 @@ async function captureCompare(flags, out, env) {
187
187
  else {
188
188
  out(headline(summary))
189
189
  for (const shot of summary.shots.filter((item) => item.changed))
190
- out(` ${shot.page} ${shot.viewport}: ${shot.status === 'changed' ? `${(shot.ratio * 100).toFixed(2)}% of pixels` : shot.status}`)
190
+ out(` ${shot.page} ${shot.viewport}: ${shot.status === 'changed' ? `${percent(shot.ratio)} of pixels` : shot.status}`)
191
191
  for (const failure of summary.failures)
192
192
  out(` not captured: ${failure.page ? `${failure.page} ${failure.viewport} ` : ''}(${failure.side || 'compare'}) ${failure.error}`)
193
193
  out(`Result in ${target} (summary.json, summary.md, images/)`)
@@ -1,7 +1,7 @@
1
- // `shapewall comments`: list, get, add, resolve, reopen, reply and status.
1
+ // `shapewall comments`: list, get, add, selectors, resolve, reopen, reply and status.
2
2
 
3
3
  import { getBoard, loadConfig } from '../config.js'
4
- import { addComment, authorFlag, showComment, sinceFilter } from '../comments-cli.js'
4
+ import { addComment, authorFlag, listSelectors, showComment, sinceFilter } from '../comments-cli.js'
5
5
  import { feedback, formatFeedback, formatFeedbackForAgent, untrustedJson } from '../feedback.js'
6
6
  import { AGENT_STATUSES, addReply, setAgentStatus, updateComment } from '../store.js'
7
7
  import { mentionFlag, withNotifications } from './notify.js'
@@ -13,7 +13,7 @@ export async function comments(positional, flags, out, err) {
13
13
  return remoteComments(positional, flags, out)
14
14
  }
15
15
  const config = loadConfig(flags.config)
16
- if (['list', 'get', 'show'].includes(positional[0] || 'list')) return commentAction(config, positional, flags, out, err)
16
+ if (['list', 'get', 'show', 'selectors'].includes(positional[0] || 'list')) return commentAction(config, positional, flags, out, err)
17
17
  return withNotifications(config, err, () => commentAction(config, positional, flags, out, err))
18
18
  }
19
19
 
@@ -39,6 +39,7 @@ async function commentAction(config, positional, flags, out, err) {
39
39
  }
40
40
  if (action === 'get' || action === 'show') return showComment(config, board, positional, flags, out)
41
41
  if (action === 'add') return addComment(config, board, flags, out, err)
42
+ if (action === 'selectors') return listSelectors(config, board, flags, out)
42
43
  if (action === 'resolve' || action === 'reopen') {
43
44
  const id = positional[1]
44
45
  if (!id) throw new Error(`usage: shapewall comments ${action} ID`)
@@ -80,5 +81,5 @@ async function commentAction(config, positional, flags, out, err) {
80
81
  out(flags.json ? JSON.stringify({ comment }, null, 2) : `#${comment.id} agent status: ${comment.agentStatus || 'none'}`)
81
82
  return
82
83
  }
83
- throw new Error(`unknown comments action "${action}" (list, get, add, resolve, reopen, reply, status)`)
84
+ throw new Error(`unknown comments action "${action}" (list, get, add, selectors, resolve, reopen, reply, status)`)
84
85
  }
package/src/cli/help.js CHANGED
@@ -103,6 +103,8 @@ export const SECTIONS = {
103
103
  comments get ID one comment, everything about it [--json] [--for-agent]
104
104
  comments add add a comment --page ID --body TEXT [--viewport NAME (default the page's first)]
105
105
  [--selector CSS (pin it to that element)] [--author NAME (default agent)] [--json]
106
+ comments selectors the selectors --selector takes, with each element's text, from the latest capture
107
+ --page ID [--viewport NAME] [--text WORDS (only elements whose text has them)] [--json]
106
108
  comments resolve ID mark a comment resolved [--note TEXT] [--ref URL|COMMIT] [--author NAME] [--json]
107
109
  comments reopen ID reopen a comment [--author NAME] [--json]
108
110
  comments reply ID add a reply --body TEXT [--author NAME (default agent)] [--json]
@@ -161,7 +163,7 @@ export const SECTIONS = {
161
163
  --base-url URL before (default: the board's baseUrl) --head-url URL after
162
164
  --base-dir DIR or compare two capture folders --head-dir DIR
163
165
  --out DIR the result folder (default shapewall-ci)
164
- --threshold RATIO share of pixels below which a shot is unchanged (default ci.threshold, 0.001)
166
+ --threshold RATIO share of pixels below which a shot is unchanged (default ci.threshold, 0.00001)
165
167
  --max-pages N compare at most N pages (default ci.maxPages, 50)
166
168
  --fail-on-change exit 3 when something changed (default: always 0, never fails the pull request)
167
169
  ci capture --out DIR capture one side into a folder, from --url URL, or with --allow-start
package/src/cli/init.js CHANGED
@@ -5,7 +5,7 @@ import path from 'node:path'
5
5
  import { CONFIG_FILE, ConfigError, SITEMAP_LIMIT_MAX, findConfigFile, normalizeConfig, starterConfig, titleFromBaseUrl } from '../config.js'
6
6
  import { writeFileAtomic } from '../store.js'
7
7
  import { addPagesToRaw, defaultSitemapUrl, formatImport, importSitemap, sitemapPages } from '../sitemap.js'
8
- import { DISCOVER_DEFAULTS, cutTitle, describeFetchError, discoverPages, pageTitle } from '../discover.js'
8
+ import { DISCOVER_DEFAULTS, cutTitle, describeFetchError, discoverPages, pageTitle, siteNameFrom } from '../discover.js'
9
9
  import { cliCommand } from '../invocation.js'
10
10
  import { WORKFLOW_FILE, workflowYaml } from '../ci/workflow.js'
11
11
 
@@ -80,7 +80,7 @@ async function discoverConfig({ baseUrl, dir, fetch, out }) {
80
80
  return { config, found: 'none' }
81
81
  }
82
82
  const basePath = new URL(baseUrl).pathname.replace(/\/+$/, '')
83
- const siteTitle = crawl.homeTitle
83
+ const siteTitle = siteNameFrom(crawl.pages.map((page) => page.title)) || crawl.homeTitle
84
84
  const titles = new Map(crawl.pages.map((page, index) => [pagePathKey(page.url, basePath), index === 0 ? 'Home' : page.title]))
85
85
  const { pages } = sitemapPages(
86
86
  crawl.pages.map((page) => page.url),
@@ -163,14 +163,17 @@ export async function initCi(flags, out, { fetch }) {
163
163
  const shown = path.relative(process.cwd(), file) || file
164
164
  if (fs.existsSync(file) && !flags.force) throw new Error(`${shown} already exists (use --ci --force to replace it)`)
165
165
  fs.mkdirSync(path.dirname(file), { recursive: true })
166
- fs.writeFileSync(file, workflowYaml())
167
- out(`Wrote ${shown}: on every pull request it captures the pages before and after, and keeps one comment up to date.`)
168
- let hasStart = false
166
+ let ci = null
169
167
  try {
170
- hasStart = Boolean(JSON.parse(fs.readFileSync(configFile, 'utf8'))?.ci?.start)
168
+ ci = JSON.parse(fs.readFileSync(configFile, 'utf8'))?.ci
171
169
  } catch {
172
- hasStart = false
170
+ ci = null
173
171
  }
172
+ const hasStart = Boolean(ci?.start)
173
+ const imagesBranch = ci?.images === 'branch'
174
+ fs.writeFileSync(file, workflowYaml({ imagesBranch }))
175
+ out(`Wrote ${shown}: on every pull request it captures the pages before and after, and keeps one comment up to date.`)
176
+ if (imagesBranch) out('The config has "images": "branch", so the comment job has contents: write to push the images branch.')
174
177
  if (!hasStart)
175
178
  out(
176
179
  'Next: either add "ci": { "start": { "install": [...], "build": [...], "serve": [...], "url": "http://127.0.0.1:PORT" } } to the config (build and serve mode), or set SHAPEWALL_PREVIEW_URL in the workflow (preview URL mode). Then commit the workflow.',
@@ -22,6 +22,42 @@ export class CommentError extends Error {
22
22
  }
23
23
  }
24
24
 
25
+ // Whether a comment or reply carries something besides text: an image or a
26
+ // drawing with shapes. Takes what a client sends, a stored comment and the
27
+ // CLI's export item (where a drawing is { shapes: count }).
28
+ export function hasCommentMedia(item) {
29
+ const shapes = item?.drawing?.shapes
30
+ return (Array.isArray(item?.images) && item.images.length > 0) || (Array.isArray(shapes) ? shapes.length > 0 : shapes > 0)
31
+ }
32
+
33
+ // What stands in for the text of a comment or reply that has none:
34
+ // "(drawing)", "(image)", "(2 images)", "(image and drawing)". '' when it has
35
+ // neither, so callers keep their own fallback.
36
+ export function mediaLabel(item) {
37
+ const images = Array.isArray(item?.images) ? item.images.length : 0
38
+ const drawn = hasCommentMedia({ drawing: item?.drawing })
39
+ const parts = [images === 1 ? 'image' : images ? `${images} images` : '', drawn ? 'drawing' : ''].filter(Boolean)
40
+ return parts.length ? `(${parts.join(' and ')})` : ''
41
+ }
42
+
43
+ // The text to show where a comment or reply needs a line of it (lists,
44
+ // titles, notifications, the CLI): its own, or the stand-in above.
45
+ export function commentText(item) {
46
+ const body = typeof item?.body === 'string' ? item.body : ''
47
+ return body.trim() ? body : mediaLabel(item)
48
+ }
49
+
50
+ // The text of a comment or reply, cleaned. Empty text is refused unless
51
+ // `media` says an image or a drawing comes with it: a drawing or a
52
+ // screenshot can be the whole comment.
53
+ export function cleanCommentBody(value, { media = false } = {}) {
54
+ const body = typeof value === 'string' ? value.replace(/\r\n/g, '\n').trim() : ''
55
+ if (!body && !media) throw new CommentError(400, 'empty_comment', 'Write something first.')
56
+ if (body.length > COMMENT_BODY_MAX)
57
+ throw new CommentError(400, 'comment_too_long', `Comments are limited to ${COMMENT_BODY_MAX} characters.`)
58
+ return body
59
+ }
60
+
25
61
  export function validateAnchor(anchor) {
26
62
  if (anchor === undefined || anchor === null) return null
27
63
  const bad = (message) => new CommentError(400, 'invalid_anchor', message)
@@ -85,6 +121,15 @@ export const AGENT_STATUSES = ['queued', 'working', 'done', 'needs-human']
85
121
  export const BRANCH_READY = 'branch-ready'
86
122
  export const STORED_AGENT_STATUSES = [...AGENT_STATUSES, BRANCH_READY]
87
123
 
124
+ // The agent status of a comment once it is resolved: work that was queued
125
+ // or under way counts as done (nobody is working on a resolved comment),
126
+ // and a question for a person is answered, so needs-human is cleared. done
127
+ // and branch-ready stay (a branch still waits to be applied).
128
+ export function agentStatusOnResolve(current) {
129
+ if (current === 'queued' || current === 'working') return 'done'
130
+ return current === 'needs-human' ? null : (current ?? null)
131
+ }
132
+
88
133
  // Images on comments and replies: the chat's attachment limits
89
134
  // (src/agent/threads.js ATTACHMENTS_MAX, ATTACHMENT_BYTES_MAX), checked on
90
135
  // the server by src/comment-media.js and in the demo's backend.