shapewall 0.3.1 → 0.3.3

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 (98) hide show
  1. package/CHANGELOG.md +142 -0
  2. package/NOTICE +7 -0
  3. package/README.md +4 -2
  4. package/THIRD_PARTY.md +39 -0
  5. package/dist/agent/package-lock.json +2 -2
  6. package/dist/client/assets/BoardChat-DxehB761.js +27 -0
  7. package/dist/client/assets/BuzzDialog-Ix9qJvim.js +1 -0
  8. package/dist/client/assets/ChecksPanel-pA_ueIaJ.js +1 -0
  9. package/dist/client/assets/History-C9N32kCv.js +1 -0
  10. package/dist/client/assets/LocalSettings-DawtKnvi.js +1 -0
  11. package/dist/client/assets/{Management-BFcKFdbp.js → Management-NVFDtSZB.js} +1 -1
  12. package/dist/client/assets/QuickConnect-DO1TjS1t.js +1 -0
  13. package/dist/client/assets/ShareDialog-By0ETg6n.js +2 -0
  14. package/dist/client/assets/app-update-dialog-RGIw24iZ.js +1 -0
  15. package/dist/client/assets/{circle-x-PRxj7kPi.js → circle-x-B6KfScOE.js} +1 -1
  16. package/dist/client/assets/index-CsqLdqGx.css +2 -0
  17. package/dist/client/assets/index-DnZarJ3U.js +37 -0
  18. package/dist/client/assets/{refresh-cw-aeOBDuGQ.js → refresh-cw-vkgvCCfR.js} +1 -1
  19. package/dist/client/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  20. package/dist/client/assets/{shield-check-DuPBJ6H_.js → shield-check-QzwGhz0t.js} +1 -1
  21. package/dist/client/assets/ui-DI-FGWWK.js +41 -0
  22. package/dist/client/build-info.json +1 -1
  23. package/dist/client/index.html +4 -3
  24. package/dist/client/sw.js +2 -2
  25. package/dist/console/assets/{LocalAccountsApp-lJjkhUcH.js → LocalAccountsApp-VOCZg8dg.js} +1 -1
  26. package/dist/console/assets/{LocalConsole-BZHqYKnt.js → LocalConsole-CMwAW-mF.js} +1 -1
  27. package/dist/console/assets/{app-update-dialog-DCM9sYE3.js → app-update-dialog-Cw6UDqNP.js} +1 -1
  28. package/dist/console/assets/console-DgfWmUEx.js +55 -0
  29. package/dist/console/assets/console-Lis0vvdL.css +2 -0
  30. package/dist/console/build-info.json +1 -1
  31. package/dist/console/console.html +2 -2
  32. package/docs/agent-workflow.md +19 -3
  33. package/docs/agents.md +62 -2
  34. package/docs/config.md +3 -3
  35. package/docs/deployment.md +2 -0
  36. package/docs/design-system.md +20 -15
  37. package/docs/hosted.md +19 -0
  38. package/docs/pull-requests.md +4 -1
  39. package/docs/where-to-run.md +88 -0
  40. package/package.json +2 -1
  41. package/src/agent/agent-logos.js +81 -0
  42. package/src/agent/composer.js +9 -5
  43. package/src/agent/config.js +27 -2
  44. package/src/agent/context.js +3 -1
  45. package/src/agent/icon-store.js +100 -0
  46. package/src/agent/identity.js +77 -0
  47. package/src/agent/owner-mcp.js +19 -3
  48. package/src/agent/routes.js +82 -21
  49. package/src/agent/run.js +3 -1
  50. package/src/agent/settings-routes.js +233 -14
  51. package/src/agent/test-timing.js +14 -0
  52. package/src/agent/tools.js +6 -3
  53. package/src/agent/user-settings.js +51 -3
  54. package/src/capture/capture.js +3 -1
  55. package/src/capture/element-map.js +73 -11
  56. package/src/ci/settings.js +3 -3
  57. package/src/ci/start.js +16 -0
  58. package/src/ci/summary.js +8 -1
  59. package/src/cli/args.js +1 -0
  60. package/src/cli/ci.js +2 -2
  61. package/src/cli/comments.js +5 -4
  62. package/src/cli/help.js +3 -1
  63. package/src/cli/init.js +2 -2
  64. package/src/comment-fields.js +45 -0
  65. package/src/comments-cli.js +100 -21
  66. package/src/discover.js +34 -1
  67. package/src/doctor.js +26 -1
  68. package/src/event-log.js +5 -2
  69. package/src/feedback.js +5 -2
  70. package/src/github.js +4 -2
  71. package/src/hosted/agent-presence.js +40 -0
  72. package/src/hosted/app.js +6 -0
  73. package/src/hosted/board-routes.js +9 -1
  74. package/src/hosted/comments.js +11 -11
  75. package/src/hosted/console-routes.js +47 -1
  76. package/src/hosted/events.js +6 -4
  77. package/src/hosted/import.js +7 -4
  78. package/src/hosted/presence.js +1 -1
  79. package/src/hosted/projects.js +32 -1
  80. package/src/hosted/token-api.js +5 -1
  81. package/src/hosted/token-events.js +5 -2
  82. package/src/hosted/tokens.js +3 -2
  83. package/src/mcp.js +10 -2
  84. package/src/notify/messages.js +6 -4
  85. package/src/store.js +19 -11
  86. package/dist/client/assets/BoardChat-V1BCXdDB.js +0 -27
  87. package/dist/client/assets/BuzzDialog-Ds7Thpfe.js +0 -1
  88. package/dist/client/assets/ChecksPanel-Cm22bCdQ.js +0 -1
  89. package/dist/client/assets/History-U0bD1BjA.js +0 -1
  90. package/dist/client/assets/LocalSettings-DOSuW7VC.js +0 -1
  91. package/dist/client/assets/QuickConnect-DyfPSWbV.js +0 -1
  92. package/dist/client/assets/ShareDialog-BouvNraR.js +0 -2
  93. package/dist/client/assets/app-update-dialog-DH2Mgby8.js +0 -1
  94. package/dist/client/assets/index-C9S7HL_o.js +0 -37
  95. package/dist/client/assets/index-CXtuJi1K.css +0 -2
  96. package/dist/client/assets/ui-Cg4TTrec.js +0 -41
  97. package/dist/console/assets/console-C2LsvEco.js +0 -55
  98. package/dist/console/assets/console-Fp4k9iyx.css +0 -2
@@ -22,6 +22,7 @@ import { SETTINGS_SOURCE } from './acp/command.js'
22
22
  import { DENIED_KEY_VARS, KEY_VAR_RE, validateAgent } from './config.js'
23
23
  import { cleanBranchPrefix } from './branch-mode.js'
24
24
  import { cleanBatchFixes } from './batch-fixes.js'
25
+ import { IDENTITY_KEYS, cleanAgentName, isAgentIcon, isAgentTint } from './identity.js'
25
26
 
26
27
  export const SETTINGS_FILE_VAR = 'SHAPEWALL_AGENT_SETTINGS_FILE'
27
28
  export const ENTRY_KEYS = [
@@ -37,6 +38,12 @@ export const ENTRY_KEYS = [
37
38
  'branchMode',
38
39
  'branchPrefix',
39
40
  'batchFixes',
41
+ // How the agent looks on the board (identity.js): `icon` and `tint` here
42
+ // are the endpoint's; `fixedAgent` holds the name, icon and tint of an
43
+ // agent whose command a flag or the environment fixes.
44
+ 'icon',
45
+ 'tint',
46
+ 'fixedAgent',
40
47
  ]
41
48
  const SECRET_KEYS = ['apiKey', 'key', 'token', 'secret', 'password']
42
49
  const ACP_COMMAND_MAX = 2000
@@ -46,6 +53,18 @@ const HOST_RE = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9
46
53
 
47
54
  const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
48
55
 
56
+ // The icon and tint of `source` into `target`, each checked (identity.js).
57
+ function readLook(source, target, problems, where) {
58
+ if (source.icon !== undefined) {
59
+ if (!isAgentIcon(source.icon)) problems.push(`${where}icon: a built-in icon or an uploaded one`)
60
+ else target.icon = source.icon
61
+ }
62
+ if (source.tint !== undefined) {
63
+ if (!isAgentTint(source.tint)) problems.push(`${where}tint: one of the accent colours`)
64
+ else target.tint = source.tint
65
+ }
66
+ }
67
+
49
68
  // The settings file, or null when there is no home to put it in.
50
69
  export function userSettingsFile(env = process.env) {
51
70
  if (typeof env[SETTINGS_FILE_VAR] === 'string' && env[SETTINGS_FILE_VAR].trim()) return path.resolve(env[SETTINGS_FILE_VAR].trim())
@@ -78,7 +97,7 @@ export function validateUserEntry(raw) {
78
97
  problems.push(`${key}: keys are never saved; set the key in the environment and name its variable in apiKeyEnv`)
79
98
  else if (!ENTRY_KEYS.includes(key) && key !== 'updatedAt') problems.push(`${key}: not an agent setting`)
80
99
  }
81
- const { keyHosts, acpCommand, profiles, updatedAt, branchMode, branchPrefix, batchFixes, ...rest } = given
100
+ const { keyHosts, acpCommand, profiles, updatedAt, branchMode, branchPrefix, batchFixes, icon, tint, fixedAgent, ...rest } = given
82
101
  const fields = {}
83
102
  for (const key of ['backend', 'baseUrl', 'model', 'apiKeyEnv', 'label', 'vision']) if (rest[key] !== undefined) fields[key] = rest[key]
84
103
  const agentProblems = []
@@ -130,7 +149,7 @@ export function validateUserEntry(raw) {
130
149
  for (const profile of profiles) {
131
150
  if (
132
151
  !isObject(profile) ||
133
- Object.keys(profile).some((key) => !['id', 'label', 'acpCommand'].includes(key)) ||
152
+ Object.keys(profile).some((key) => !['id', 'label', 'acpCommand', 'icon', 'tint'].includes(key)) ||
134
153
  !/^[a-z][a-z0-9-]{0,39}$/.test(profile.id || '') ||
135
154
  profile.id === 'default' ||
136
155
  ids.has(profile.id) ||
@@ -144,12 +163,29 @@ export function validateUserEntry(raw) {
144
163
  }
145
164
  const validated = validateUserEntry({ acpCommand: profile.acpCommand })
146
165
  if (!validated.entry?.acpCommand) problems.push('profiles: each profile needs a valid ACP command')
147
- else checkedProfiles.push({ id: profile.id, label: profile.label.trim(), acpCommand: validated.entry.acpCommand })
166
+ else {
167
+ const checkedProfile = { id: profile.id, label: profile.label.trim(), acpCommand: validated.entry.acpCommand }
168
+ readLook(profile, checkedProfile, problems, 'profiles: ')
169
+ checkedProfiles.push(checkedProfile)
170
+ }
148
171
  ids.add(profile.id)
149
172
  }
150
173
  if (checkedProfiles.length) entry.profiles = checkedProfiles
151
174
  }
152
175
  }
176
+ readLook({ icon, tint }, entry, problems, '')
177
+ if (fixedAgent !== undefined) {
178
+ if (!isObject(fixedAgent) || Object.keys(fixedAgent).some((key) => !IDENTITY_KEYS.includes(key))) {
179
+ problems.push('fixedAgent: { label, icon, tint }')
180
+ } else {
181
+ const fixed = {}
182
+ const { name, problem } = cleanAgentName(fixedAgent.label)
183
+ if (problem) problems.push(`fixedAgent.${problem.replace(/^name/, 'label')}`)
184
+ else if (name) fixed.label = name
185
+ readLook(fixedAgent, fixed, problems, 'fixedAgent.')
186
+ if (Object.keys(fixed).length) entry.fixedAgent = fixed
187
+ }
188
+ }
153
189
  // Agent branch mode (branch-mode.js): the agent works on a branch in a worktree.
154
190
  if (branchMode !== undefined) {
155
191
  if (typeof branchMode !== 'boolean') problems.push('branchMode: true or false')
@@ -208,6 +244,18 @@ export function legacyProfile(entry, known = []) {
208
244
  return { id, label, acpCommand: entry.acpCommand }
209
245
  }
210
246
 
247
+ // The name saved for one of this project's agents, or null when none is
248
+ // saved (the caller then uses the agent's built-in name). `which`: "fixed"
249
+ // (the agent a flag or the environment fixes), "default" (the default
250
+ // connection) or a profile id.
251
+ export function savedAgentName(root, which, env = process.env) {
252
+ const { entry } = userAgentEntry(root, env)
253
+ if (!entry) return null
254
+ if (which === 'fixed') return entry.fixedAgent?.label || null
255
+ if (which === 'default') return (profileForDefault(entry) || implicitDefault(entry))?.label || entry.label || null
256
+ return (entry.profiles || []).find((profile) => profile.id === which)?.label || null
257
+ }
258
+
211
259
  // A file anyone else may write could redirect your key or start a command:
212
260
  // on POSIX the file and its folder must be yours and not group/world-writable.
213
261
  function unsafeOwnership(file) {
@@ -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)
@@ -337,9 +337,64 @@ export function hitTest(map, x, y) {
337
337
  return target === undefined ? best : target
338
338
  }
339
339
 
340
- // A short label for the element a comment would pin to (as
341
- // anchors.js describeElement): the last selector step and its text, and
342
- // `large` when it covers a fifth of the page or more.
340
+ // What a reviewer would call an element, from its tag: "Heading", "Button",
341
+ // "Image". Containers are a "Section"; other tags with words in them are "Text".
342
+ const KINDS = {
343
+ h1: 'Heading',
344
+ h2: 'Heading',
345
+ h3: 'Heading',
346
+ h4: 'Heading',
347
+ h5: 'Heading',
348
+ h6: 'Heading',
349
+ a: 'Link',
350
+ button: 'Button',
351
+ summary: 'Button',
352
+ img: 'Image',
353
+ picture: 'Image',
354
+ svg: 'Image',
355
+ video: 'Video',
356
+ input: 'Field',
357
+ textarea: 'Field',
358
+ select: 'Field',
359
+ label: 'Label',
360
+ li: 'List item',
361
+ ul: 'List',
362
+ ol: 'List',
363
+ table: 'Table',
364
+ form: 'Form',
365
+ nav: 'Navigation',
366
+ header: 'Header',
367
+ footer: 'Footer',
368
+ section: 'Section',
369
+ article: 'Section',
370
+ main: 'Section',
371
+ aside: 'Section',
372
+ div: 'Section',
373
+ }
374
+
375
+ // The tag a selector ends on ('' when its last step is an #id).
376
+ export function selectorTag(selector) {
377
+ const last = String(selector || '')
378
+ .split(' > ')
379
+ .pop()
380
+ const match = /^([a-z][a-z0-9-]*)/.exec(last)
381
+ return match ? match[1] : ''
382
+ }
383
+
384
+ // A plain name for an element: its kind and its text ("Heading: Notes that
385
+ // keep up...", "Button: Start free", "Section"). `large`: it covers a big
386
+ // part of the page, so a section says it is the whole of it.
387
+ export function plainLabel(tag, text = '', { large = false, max = 32 } = {}) {
388
+ const words = String(text || '').trim()
389
+ let kind = KINDS[tag] || (words ? 'Text' : 'Element')
390
+ if (large && kind === 'Section') kind = 'Whole section'
391
+ return words ? `${kind}: ${clip(words, max)}` : kind
392
+ }
393
+
394
+ // What hovering shows for the element a comment would pin to (as
395
+ // anchors.js describeElement): `name`, its plain label; `label`, the last
396
+ // selector step and its text (for people who read selectors); and `large`
397
+ // when it covers a fifth of the page or more.
343
398
  export function describeAt(map, position, native) {
344
399
  const item = map.elements[position]
345
400
  const selector = selectorOf(map, position)
@@ -347,9 +402,11 @@ export function describeAt(map, position, native) {
347
402
  const text = item.x || ''
348
403
  const [left, top, width, height] = item.b
349
404
  const area = native?.width && native?.height ? (width * height) / (native.width * native.height) : 0
405
+ const large = area > 0.2
350
406
  return {
407
+ name: plainLabel(item.t, text, { large }),
351
408
  label: `${clip(step, 48)}${text ? ` "${clip(text, 28)}"` : ''}`,
352
- large: area > 0.2,
409
+ large,
353
410
  rect: { left, top, width, height },
354
411
  }
355
412
  }
@@ -433,14 +490,16 @@ function stepMatches(item, step) {
433
490
  return item.n === step.nth
434
491
  }
435
492
 
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) {
493
+ // Every element (document order) a stored selector names: the map's answer
494
+ // to querySelectorAll() for the anchor grammar (child combinators). `max`
495
+ // stops the search early.
496
+ export function matchSelectorAll(map, selector, max = Infinity) {
497
+ const found = []
439
498
  const steps = parseSelector(selector)
440
- if (!steps?.length) return -1
499
+ if (!steps?.length) return found
441
500
  const elements = map?.elements || []
442
501
  const last = steps[steps.length - 1]
443
- for (let position = 0; position < elements.length; position += 1) {
502
+ for (let position = 0; position < elements.length && found.length < max; position += 1) {
444
503
  if (!stepMatches(elements[position], last)) continue
445
504
  let node = elements[position].p
446
505
  let ok = true
@@ -451,11 +510,14 @@ export function matchSelector(map, selector) {
451
510
  }
452
511
  node = elements[node].p
453
512
  }
454
- if (ok) return position
513
+ if (ok) found.push(position)
455
514
  }
456
- return -1
515
+ return found
457
516
  }
458
517
 
518
+ // The first element a stored selector names, or -1 (querySelector()).
519
+ export const matchSelector = (map, selector) => matchSelectorAll(map, selector, 1)[0] ?? -1
520
+
459
521
  function lastTag(selector) {
460
522
  const last = String(selector).split('>').pop().trim()
461
523
  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)`)
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),
@@ -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.
@@ -1,16 +1,22 @@
1
- // `shapewall comments add`, `comments get` and `comments --since`: what a
2
- // shell-only agent or a chat bot needs besides list, reply and status.
1
+ // `shapewall comments add`, `comments selectors`, `comments get` and
2
+ // `comments --since`: what a shell-only agent or a chat bot needs besides
3
+ // list, reply and status.
3
4
  //
4
5
  // add goes through the same store function the board uses (validation,
5
6
  // events, mentions, capture version). Without --selector the pin sits near
6
- // the page's top-left corner; with one, it is anchored to that element, and
7
- // the element's text is read from the latest capture's live HTML when the
8
- // selector finds exactly one element there.
7
+ // the page's top-left corner; with one, it is anchored to that element.
8
+ // When the selector finds exactly one element in the latest capture's
9
+ // element map (src/capture/element-map.js), the pin sits in the middle of
10
+ // that element, stored as a click there on the board would store it. A
11
+ // capture without a map (an older one) still gives the element's text, read
12
+ // from the live HTML.
9
13
 
10
14
  import fs from 'node:fs'
15
+ import path from 'node:path'
11
16
  import { parse } from 'parse5'
17
+ import { matchSelectorAll, parseElementMap, resolveOnMap, selectorOf } from './capture/element-map.js'
12
18
  import { feedbackContext, feedbackItem, formatFeedbackItem, formatFeedbackItemForAgent, untrustedJson } from './feedback.js'
13
- import { ANCHOR_TEXT_MAX, CommentError, createComment, getComment, resolveFile } from './store.js'
19
+ import { ANCHOR_SELECTOR_RE, ANCHOR_TEXT_MAX, CommentError, createComment, getComment, resolveFile } from './store.js'
14
20
  import { boardViewports } from './config.js'
15
21
 
16
22
  // Who a comment, reply or status change is from when --author is not given.
@@ -143,10 +149,71 @@ export function anchorText(html, selector) {
143
149
  return text.length > ANCHOR_TEXT_MAX ? `${text.slice(0, ANCHOR_TEXT_MAX - 3).trimEnd()}...` : text
144
150
  }
145
151
 
152
+ // ---- The element map ------------------------------------------------------------
153
+
154
+ // The latest capture's element map of a page, as { file, map }, or null
155
+ // when there is none (never captured, or captured before maps) or it does
156
+ // not read.
157
+ function latestElementMap(config, board, pageId, viewport) {
158
+ const file = resolveFile(config, board.id, 'captures', `${pageId}.${viewport}.elements.json`)
159
+ if (!file) return null
160
+ try {
161
+ return { file, map: parseElementMap(fs.readFileSync(file, 'utf8')) }
162
+ } catch {
163
+ return null
164
+ }
165
+ }
166
+
167
+ // A click in the middle of element `position`, as the board stores it:
168
+ // { anchor, pin } with the pin in percent of the page, or null when the
169
+ // element has no size to sit on.
170
+ function middleOf(map, position, selector) {
171
+ const native = { width: map.width, height: map.height }
172
+ const [, , width, height] = map.elements[position].b
173
+ if (!width || !height || !native.width || !native.height) return null
174
+ const anchor = { selector, text: map.elements[position].x || '', dx: 0.5, dy: 0.5 }
175
+ const spot = resolveOnMap(map, anchor, native)
176
+ if (!spot) return null
177
+ const share = (value) => Math.round(Math.min(1, value) * 10000) / 10000
178
+ const size = { w: share(width / native.width), h: share(height / native.height) }
179
+ return { anchor: size.w > 0 && size.h > 0 ? { ...anchor, ...size } : anchor, pin: { x: spot.x, y: spot.y } }
180
+ }
181
+
182
+ const SELECTORS_MAX = 200
183
+
184
+ // `comments selectors --page ID [--viewport NAME] [--text WORDS] [--json]`:
185
+ // the selectors `comments add --selector` takes, each with its element's
186
+ // text, from the latest capture's element map.
187
+ export function listSelectors(config, board, flags, out) {
188
+ const pageId = typeof flags.page === 'string' ? flags.page.trim() : ''
189
+ const page = board.pages.find((item) => item.id === pageId)
190
+ if (!page) throw new Error('usage: shapewall comments selectors --page ID [--viewport NAME] [--text WORDS] [--json]')
191
+ const viewport = typeof flags.viewport === 'string' ? flags.viewport : page.viewports[0]
192
+ const found = latestElementMap(config, board, page.id, viewport)
193
+ if (!found) throw new Error(`No element map for "${page.id}" (${viewport}) yet. Capture it first: shapewall capture --only ${page.id}`)
194
+ const wanted = typeof flags.text === 'string' ? flags.text.trim().toLowerCase() : ''
195
+ const all = found.map.elements
196
+ .map((item, position) => ({ selector: selectorOf(found.map, position), text: item.x || '', sized: item.b[2] > 0 && item.b[3] > 0 }))
197
+ .filter((row) => row.selector && row.sized && (wanted ? row.text.toLowerCase().includes(wanted) : true))
198
+ .map(({ selector, text }) => ({ selector, text }))
199
+ const rows = all.slice(0, SELECTORS_MAX)
200
+ const more = all.length - rows.length
201
+ const lines = rows.map((row) => `${row.selector}${row.text ? ` ("${row.text}")` : ''}`)
202
+ if (!rows.length) lines.push(wanted ? `No element on "${page.id}" (${viewport}) has text with "${flags.text.trim()}".` : 'No elements.')
203
+ if (more > 0) lines.push(`... and ${more} more: narrow it with --text WORDS`)
204
+ print(out, flags, untrustedJson({ board: board.id, page: page.id, viewport, selectors: rows, more }), lines.join('\n'))
205
+ return rows
206
+ }
207
+
146
208
  // ---- Commands -------------------------------------------------------------------
147
209
 
148
210
  const print = (out, flags, value, text) => out(flags.json ? JSON.stringify(value, null, 2) : text)
149
211
 
212
+ // What a selector must look like, and where to find one.
213
+ const selectorHelp = (pageId) =>
214
+ 'It takes steps like #id, button[data-testid="save"], nav[aria-label="Main"] or div:nth-of-type(2), joined by " > " ' +
215
+ `(no classes or other CSS). List the ones on the page: shapewall comments selectors --page ${pageId} --text "words on the element"`
216
+
150
217
  // `comments add --page ID --body TEXT [--viewport NAME] [--selector CSS] [--author NAME]`
151
218
  export async function addComment(config, board, flags, out, err = () => {}) {
152
219
  const pageId = typeof flags.page === 'string' ? flags.page.trim() : ''
@@ -160,29 +227,41 @@ export async function addComment(config, board, flags, out, err = () => {}) {
160
227
  const viewport =
161
228
  typeof flags.viewport === 'string' ? flags.viewport : page ? page.viewports[0] : Object.keys(boardViewports(config, board))[0]
162
229
  let anchor
230
+ let pin = DEFAULT_PIN
163
231
  if (flags.selector !== undefined) {
164
232
  const selector = String(flags.selector).trim()
165
- let text = ''
166
- const live = page ? resolveFile(config, board.id, 'captures', `${page.id}.${viewport}.html`) : null
167
- if (live) {
168
- const found = anchorText(fs.readFileSync(live, 'utf8'), selector)
169
- if (found === null)
170
- err(`note: "${selector}" does not find exactly one element in the latest ${viewport} capture; saved the selector anyway`)
171
- else text = found
233
+ if (!ANCHOR_SELECTOR_RE.test(selector))
234
+ throw new Error(`--selector "${selector.slice(0, 80)}" is not one Shapewall can use. ${selectorHelp(pageId)}`)
235
+ const mapped = page ? latestElementMap(config, board, page.id, viewport) : null
236
+ const hits = mapped ? matchSelectorAll(mapped.map, selector, 2) : []
237
+ const middle = hits.length === 1 ? middleOf(mapped.map, hits[0], selector) : null
238
+ if (middle) {
239
+ // The pin sits in the middle of the element, where the map has it.
240
+ anchor = middle.anchor
241
+ pin = middle.pin
242
+ } else {
243
+ // No map, or the map does not have exactly one such element: the
244
+ // selector is kept, and the pin stays near the corner until the
245
+ // board finds the element.
246
+ let text = ''
247
+ const live = page ? resolveFile(config, board.id, 'captures', `${page.id}.${viewport}.html`) : null
248
+ const found = live ? anchorText(fs.readFileSync(live, 'utf8'), selector) : ''
249
+ if (found === null || (mapped && hits.length !== 1)) {
250
+ const where = mapped
251
+ ? ` (its elements: ${path.relative(process.cwd(), mapped.file) || mapped.file}, or comments selectors --page ${pageId})`
252
+ : ''
253
+ err(`note: "${selector}" does not find exactly one element in the latest ${viewport} capture${where}; saved the selector anyway`)
254
+ }
255
+ if (found) text = found
256
+ anchor = { selector, text, dx: 0.5, dy: 0.5 }
172
257
  }
173
- // The pin sits in the middle of the element.
174
- anchor = { selector, text, dx: 0.5, dy: 0.5 }
175
258
  }
176
259
  let comment
177
260
  try {
178
- comment = await createComment(config, board, { pageId, viewport, ...DEFAULT_PIN, body, author: authorFlag(flags), anchor })
261
+ comment = await createComment(config, board, { pageId, viewport, ...pin, body, author: authorFlag(flags), anchor })
179
262
  } catch (error) {
180
263
  if (error instanceof CommentError && error.code === 'invalid_anchor') {
181
- throw new Error(
182
- `${error.message} Use the selector a comment shows (comments --json, element.selector): steps like #id, ` +
183
- 'button[data-testid="save"], nav[aria-label="Main"] or div:nth-of-type(2), joined by " > ".',
184
- { cause: error },
185
- )
264
+ throw new Error(`${error.message} ${selectorHelp(pageId)}`, { cause: error })
186
265
  }
187
266
  throw error
188
267
  }