shapewall 0.2.3 → 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 (110) hide show
  1. package/CHANGELOG.md +48 -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-CvlVtNY_.js → LocalSettings-CSNMhNyV.js} +1 -1
  9. package/dist/client/assets/{Management-DOJkFY_o.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-Dox9-LWv.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-CrqIMEwN.js +1 -0
  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/design-system.md +13 -5
  35. package/docs/hosted.md +10 -0
  36. package/docs/journeys.md +13 -1
  37. package/docs/pull-requests.md +192 -0
  38. package/package.json +2 -1
  39. package/src/agent/backends/acp.js +35 -6
  40. package/src/agent/batch-fixes.js +45 -0
  41. package/src/agent/batch-queue.js +204 -0
  42. package/src/agent/branch-mode.js +753 -0
  43. package/src/agent/config.js +6 -0
  44. package/src/agent/fix-prompt.js +5 -0
  45. package/src/agent/manage.js +1 -1
  46. package/src/agent/routes.js +901 -186
  47. package/src/agent/run.js +8 -1
  48. package/src/agent/settings-events.js +103 -0
  49. package/src/agent/settings-routes.js +92 -2
  50. package/src/agent/starter/worktree.js +254 -25
  51. package/src/agent/threads.js +2 -7
  52. package/src/agent/tools.js +51 -0
  53. package/src/agent/user-settings.js +33 -2
  54. package/src/ci/capture.js +103 -0
  55. package/src/ci/compare.js +267 -0
  56. package/src/ci/github.js +307 -0
  57. package/src/ci/images.js +76 -0
  58. package/src/ci/settings.js +211 -0
  59. package/src/ci/start.js +148 -0
  60. package/src/ci/summary.js +262 -0
  61. package/src/ci/workflow.js +238 -0
  62. package/src/cli/args.js +24 -1
  63. package/src/cli/ci.js +229 -0
  64. package/src/cli/help.js +23 -1
  65. package/src/cli/init.js +33 -1
  66. package/src/cli.js +6 -2
  67. package/src/comment-drawing.js +161 -0
  68. package/src/comment-fields.js +51 -0
  69. package/src/comment-media.js +528 -0
  70. package/src/config.js +7 -0
  71. package/src/doctor.js +23 -0
  72. package/src/export.js +8 -0
  73. package/src/feedback.js +89 -12
  74. package/src/github.js +3 -3
  75. package/src/hosted/admin.js +36 -4
  76. package/src/hosted/app.js +5 -0
  77. package/src/hosted/board-routes.js +63 -7
  78. package/src/hosted/clean-worker.js +22 -4
  79. package/src/hosted/cleaner.js +4 -1
  80. package/src/hosted/comment-files.js +200 -0
  81. package/src/hosted/comments.js +68 -15
  82. package/src/hosted/db.js +32 -0
  83. package/src/hosted/guest-view.js +9 -0
  84. package/src/hosted/import.js +213 -18
  85. package/src/hosted/operator.js +3 -1
  86. package/src/hosted/projects.js +3 -2
  87. package/src/hosted/push.js +6 -3
  88. package/src/hosted/retention.js +18 -0
  89. package/src/hosted/tenancy.js +1 -0
  90. package/src/hosted/token-api.js +110 -9
  91. package/src/image-sniff.js +11 -0
  92. package/src/mcp.js +48 -3
  93. package/src/remote/remote-mcp.js +2 -2
  94. package/src/remote/remote.js +6 -2
  95. package/src/remote/share.js +77 -7
  96. package/src/server/app.js +18 -1
  97. package/src/store.js +119 -33
  98. package/src/watch.js +4 -0
  99. package/dist/client/assets/BoardChat-C88k4s-W.js +0 -28
  100. package/dist/client/assets/ChecksPanel-B54chcLA.js +0 -1
  101. package/dist/client/assets/History-CVVuuxUK.js +0 -1
  102. package/dist/client/assets/QuickConnect-D40mj4Ry.js +0 -1
  103. package/dist/client/assets/index-CwvFfwU0.js +0 -29
  104. package/dist/client/assets/index-UIYSPHoh.css +0 -2
  105. package/dist/client/assets/ui-BAGBTB_P.js +0 -41
  106. package/dist/console/assets/LocalAccountsApp-4MtW1QlZ.js +0 -1
  107. package/dist/console/assets/LocalConsole-CgKqYa8i.js +0 -1
  108. package/dist/console/assets/app-update-dialog-S2Yyc7Pw.js +0 -1
  109. package/dist/console/assets/console-BPmBRIoz.js +0 -51
  110. package/dist/console/assets/console-DgVrGRMD.css +0 -2
@@ -0,0 +1,148 @@
1
+ // Runs `ci.start` (src/ci/settings.js) for `shapewall ci capture --allow-start`:
2
+ // install and build to completion, then the serve command in the background
3
+ // until the site answers. Each command is an argv array run without a shell;
4
+ // the program is looked up on absolute PATH entries only (which.js), so
5
+ // neither a string nor a program inside the repository can be named.
6
+ //
7
+ // It runs only inside a CI job (GITHUB_ACTIONS or CI is "true") and only when
8
+ // the command line says --allow-start: a config in a cloned repository never
9
+ // starts anything on someone's own machine because they ran a Shapewall command.
10
+
11
+ import { spawn } from 'node:child_process'
12
+ import { absoluteProgram } from '../which.js'
13
+
14
+ // Tokens the job has that the project's own commands never need.
15
+ const WITHHELD = [
16
+ 'GITHUB_TOKEN',
17
+ 'SHAPEWALL_GITHUB_TOKEN',
18
+ 'ACTIONS_RUNTIME_TOKEN',
19
+ 'ACTIONS_ID_TOKEN_REQUEST_TOKEN',
20
+ 'ACTIONS_ID_TOKEN_REQUEST_URL',
21
+ 'SHAPEWALL_TOKEN',
22
+ ]
23
+
24
+ export const inCi = (env = process.env) => env.GITHUB_ACTIONS === 'true' || env.CI === 'true'
25
+
26
+ // Why ci.start may not run here, or null when it may.
27
+ export function startRefusal({ allowStart, env = process.env, start }) {
28
+ if (!start) return 'the config has no "ci.start" (the install, build and serve commands); add it, or capture a URL with --url'
29
+ if (!allowStart)
30
+ return 'ci.start runs only with --allow-start, which the workflow passes; Shapewall never runs commands from a config on its own'
31
+ if (!inCi(env))
32
+ return 'ci.start runs only inside a CI job (GITHUB_ACTIONS or CI set to "true"); on your own machine, start the site yourself and pass --url'
33
+ return null
34
+ }
35
+
36
+ export function commandEnv(env = process.env) {
37
+ const out = { ...env }
38
+ for (const name of WITHHELD) delete out[name]
39
+ return out
40
+ }
41
+
42
+ const describe = (argv) => argv.map((arg) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : JSON.stringify(arg))).join(' ')
43
+
44
+ function launch(argv, { cwd, env, log, detached }) {
45
+ const program = absoluteProgram(argv[0], env)
46
+ if (!program) throw new Error(`"${argv[0]}" is not on PATH (ci.start names programs, looked up on absolute PATH entries only)`)
47
+ const child = spawn(program, argv.slice(1), { cwd, env, shell: false, detached, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
48
+ const relay = (stream) => {
49
+ let rest = ''
50
+ stream.setEncoding('utf8')
51
+ stream.on('data', (chunk) => {
52
+ const lines = (rest + chunk).split('\n')
53
+ rest = lines.pop()
54
+ for (const line of lines) log(` | ${line.slice(0, 500)}`)
55
+ })
56
+ stream.on('end', () => rest && log(` | ${rest.slice(0, 500)}`))
57
+ }
58
+ relay(child.stdout)
59
+ relay(child.stderr)
60
+ return child
61
+ }
62
+
63
+ // A whole process group, so `npm start` does not leave its server behind.
64
+ function kill(child, signal) {
65
+ try {
66
+ if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal)
67
+ else child.kill(signal)
68
+ } catch {
69
+ /* already gone */
70
+ }
71
+ }
72
+
73
+ function runToEnd(argv, { cwd, env, log, timeout }) {
74
+ return new Promise((resolve, reject) => {
75
+ let child
76
+ try {
77
+ child = launch(argv, { cwd, env, log, detached: process.platform !== 'win32' })
78
+ } catch (error) {
79
+ reject(error)
80
+ return
81
+ }
82
+ const timer = setTimeout(() => {
83
+ kill(child, 'SIGKILL')
84
+ reject(new Error(`${describe(argv)} did not finish within ${Math.round(timeout / 1000)} s`))
85
+ }, timeout)
86
+ child.on('error', (error) => {
87
+ clearTimeout(timer)
88
+ reject(new Error(`${describe(argv)} did not start: ${error.message}`))
89
+ })
90
+ child.on('exit', (code, signal) => {
91
+ clearTimeout(timer)
92
+ if (code === 0) resolve()
93
+ else reject(new Error(`${describe(argv)} failed (${signal ? `signal ${signal}` : `exit code ${code}`})`))
94
+ })
95
+ })
96
+ }
97
+
98
+ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
99
+
100
+ // Waits until `url` answers with any status below 500. `isDead()` stops the
101
+ // wait early (the serve command exited). Throws on timeout.
102
+ export async function waitForUrl(url, { timeout = 180000, interval = 1000, fetchImpl = globalThis.fetch, isDead = () => null } = {}) {
103
+ const until = Date.now() + timeout
104
+ let last = 'no answer yet'
105
+ for (;;) {
106
+ const dead = isDead()
107
+ if (dead) throw new Error(`the serve command exited before ${url} answered (${dead})`)
108
+ try {
109
+ const response = await fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(Math.min(10000, timeout)) })
110
+ await response.body?.cancel().catch(() => {})
111
+ if (response.status < 500) return response.status
112
+ last = `HTTP ${response.status}`
113
+ } catch (error) {
114
+ last = error.cause?.code || error.name || 'no answer'
115
+ }
116
+ if (Date.now() >= until) throw new Error(`${url} did not answer within ${Math.round(timeout / 1000)} s (${last})`)
117
+ await sleep(interval)
118
+ }
119
+ }
120
+
121
+ // Runs install and build, starts serve and waits for `url`. Returns { stop }.
122
+ export async function startSite(start, { cwd, url, env = process.env, log = () => {}, fetchImpl } = {}) {
123
+ const childEnv = commandEnv(env)
124
+ for (const step of ['install', 'build']) {
125
+ if (!start[step]) continue
126
+ log(`ci.start.${step}: ${describe(start[step])} (in ${cwd})`)
127
+ await runToEnd(start[step], { cwd, env: childEnv, log, timeout: start.timeout })
128
+ }
129
+ log(`ci.start.serve: ${describe(start.serve)} (in ${cwd})`)
130
+ const server = launch(start.serve, { cwd, env: childEnv, log, detached: process.platform !== 'win32' })
131
+ let exited = null
132
+ server.on('exit', (code, signal) => (exited = signal ? `signal ${signal}` : `exit code ${code}`))
133
+ server.on('error', (error) => (exited = error.message))
134
+ const stop = async () => {
135
+ if (exited) return
136
+ kill(server, 'SIGTERM')
137
+ for (let waited = 0; waited < 5000 && !exited; waited += 100) await sleep(100)
138
+ if (!exited) kill(server, 'SIGKILL')
139
+ }
140
+ try {
141
+ await waitForUrl(url, { timeout: start.timeout, fetchImpl, isDead: () => exited })
142
+ } catch (error) {
143
+ await stop()
144
+ throw error
145
+ }
146
+ log(`${url} is up`)
147
+ return { stop }
148
+ }
@@ -0,0 +1,262 @@
1
+ // The pull request comment, rendered from summary.json (src/ci/compare.js).
2
+ // `shapewall ci capture-compare` writes it as summary.md; `shapewall ci
3
+ // comment` renders it again with the links it knows by then (the workflow
4
+ // artifact, and image URLs when ci.images is "branch").
5
+ //
6
+ // Everything in it that came from the repository (page titles, paths, error
7
+ // text) is plain text: markdown, HTML and @mentions are neutralised, so a
8
+ // config in a pull request cannot put markup or pings in the comment.
9
+
10
+ export const COMMENT_MARKER = '<!-- shapewall-ci -->'
11
+ export const ROWS_MAX = 50
12
+ const FAILURES_MAX = 20
13
+ // GitHub refuses comments over 65536 characters.
14
+ export const BODY_MAX = 60000
15
+
16
+ const plural = (count, word, many = `${word}s`) => `${count} ${count === 1 ? word : many}`
17
+
18
+ // One table cell or line of plain text: no markdown, HTML, mention or link.
19
+ // A zero-width space (U+200B) breaks every @ (mentions, and GitHub's email
20
+ // and mailto:/xmpp: autolinks), "://" and "www." (GitHub's bare autolinks).
21
+ export function plain(value, max = 120) {
22
+ return String(value ?? '')
23
+ .replace(/[\r\n\t]+/g, ' ')
24
+ .slice(0, max)
25
+ .replace(/[\\`*_{}[\]()#+!|<>~]/g, (char) => `\\${char}`)
26
+ .replace(/@/g, '@​')
27
+ .replace(/:\/\//g, ':​//')
28
+ .replace(/(www)\./gi, '$1​.')
29
+ }
30
+
31
+ // ---- Reading a summary.json back --------------------------------------------
32
+ //
33
+ // `shapewall ci comment` reads summary.json from the workflow artifact, which
34
+ // the pull request's own code could have written. normalizeSummary() keeps
35
+ // only what the comment uses, each field checked: counts are safe
36
+ // non-negative integers, ratios finite numbers in [0, 1], statuses and sides
37
+ // from their known values, image paths in the shape compare.js writes, and
38
+ // strings capped (and still passed through plain() when rendered). Anything
39
+ // else: null, and the comment says the result could not be read.
40
+
41
+ const SHOT_STATUSES = new Set(['unchanged', 'changed', 'new', 'removed', 'failed'])
42
+ const TOTAL_KEYS = [
43
+ 'pages',
44
+ 'changedPages',
45
+ 'shots',
46
+ 'changedShots',
47
+ 'unchangedShots',
48
+ 'failedShots',
49
+ 'newPages',
50
+ 'removedPages',
51
+ 'pagesNotCompared',
52
+ ]
53
+ const IMAGE_KEYS = ['before', 'after', 'diff', 'beforeThumb', 'afterThumb', 'diffThumb']
54
+ const IMAGE_PATH_RE = /^images\/[a-z0-9][a-z0-9.-]{0,100}\/[a-z.]{1,40}\.png$/
55
+ const SHOTS_MAX = 5000
56
+ const FAILURES_READ_MAX = 1000
57
+
58
+ class Unreadable extends Error {}
59
+ const unreadable = () => {
60
+ throw new Unreadable()
61
+ }
62
+ const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
63
+ const count = (value) => (Number.isSafeInteger(value) && value >= 0 ? value : unreadable())
64
+ const unit = (value) => (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1 ? value : unreadable())
65
+ const flag = (value) => (typeof value === 'boolean' ? value : unreadable())
66
+ const text = (value, max, { optional = false } = {}) => {
67
+ if (value === null || value === undefined) return optional ? null : unreadable()
68
+ return typeof value === 'string' ? value.slice(0, max) : unreadable()
69
+ }
70
+ const size = (value) => {
71
+ if (value === null || value === undefined) return null
72
+ return isObject(value) ? { width: count(value.width), height: count(value.height) } : unreadable()
73
+ }
74
+
75
+ function cleanShot(raw) {
76
+ if (!isObject(raw) || !SHOT_STATUSES.has(raw.status)) unreadable()
77
+ let images = null
78
+ if (raw.images !== null && raw.images !== undefined) {
79
+ if (!isObject(raw.images)) unreadable()
80
+ images = {}
81
+ for (const key of IMAGE_KEYS) {
82
+ const value = raw.images[key]
83
+ if (value === undefined) continue
84
+ if (typeof value !== 'string' || !IMAGE_PATH_RE.test(value)) unreadable()
85
+ images[key] = value
86
+ }
87
+ }
88
+ return {
89
+ page: text(raw.page, 200),
90
+ title: text(raw.title, 300, { optional: true }),
91
+ path: text(raw.path, 500, { optional: true }),
92
+ viewport: text(raw.viewport, 64),
93
+ viewportSize: size(raw.viewportSize),
94
+ status: raw.status,
95
+ changed: flag(raw.changed),
96
+ ratio: unit(raw.ratio),
97
+ changedPixels: count(raw.changedPixels ?? 0),
98
+ totalPixels: count(raw.totalPixels ?? 0),
99
+ dimensionsChanged: flag(raw.dimensionsChanged ?? false),
100
+ base: size(raw.base),
101
+ head: size(raw.head),
102
+ images,
103
+ error: text(raw.error, 2000, { optional: true }),
104
+ }
105
+ }
106
+
107
+ function cleanFailure(raw) {
108
+ if (!isObject(raw) || ![null, undefined, 'base', 'head'].includes(raw.side)) unreadable()
109
+ return {
110
+ side: raw.side ?? null,
111
+ page: text(raw.page, 200, { optional: true }),
112
+ viewport: text(raw.viewport, 64, { optional: true }),
113
+ error: text(raw.error, 2000, { optional: true }) || '',
114
+ }
115
+ }
116
+
117
+ // A parsed summary.json, checked field by field: the clean summary, or null.
118
+ export function normalizeSummary(raw) {
119
+ try {
120
+ if (!isObject(raw) || !isObject(raw.totals) || !Array.isArray(raw.shots)) return null
121
+ const failures = raw.failures ?? []
122
+ if (!Array.isArray(failures) || raw.shots.length > SHOTS_MAX || failures.length > FAILURES_READ_MAX) return null
123
+ const totals = {}
124
+ for (const key of TOTAL_KEYS) totals[key] = count(raw.totals[key] ?? 0)
125
+ return {
126
+ schema: raw.schema,
127
+ version: raw.version,
128
+ threshold: unit(raw.threshold),
129
+ totals,
130
+ failures: failures.map(cleanFailure),
131
+ shots: raw.shots.map(cleanShot),
132
+ }
133
+ } catch (error) {
134
+ if (error instanceof Unreadable) return null
135
+ throw error
136
+ }
137
+ }
138
+
139
+ export function percent(ratio) {
140
+ const value = ratio * 100
141
+ if (value > 0 && value < 0.01) return '<0.01%'
142
+ return `${value.toFixed(2)}%`
143
+ }
144
+
145
+ function screen(shot) {
146
+ const size = shot.viewportSize ? ` ${shot.viewportSize.width}x${shot.viewportSize.height}` : ''
147
+ return `${plain(shot.viewport, 32)}${size}`
148
+ }
149
+
150
+ function changeText(shot) {
151
+ if (shot.status === 'new') return 'new page'
152
+ if (shot.status === 'removed') return 'page removed'
153
+ let text = percent(shot.ratio)
154
+ if (shot.dimensionsChanged && shot.base && shot.head)
155
+ text += ` (size ${shot.base.width}x${shot.base.height} to ${shot.head.width}x${shot.head.height})`
156
+ return text
157
+ }
158
+
159
+ function pageCell(shot) {
160
+ const title = plain(shot.title || shot.page, 80)
161
+ return shot.path ? `${title} (${plain(shot.path, 80)})` : title
162
+ }
163
+
164
+ // The headline: "Shapewall: 4 of 23 pages changed".
165
+ export function headline(summary) {
166
+ const { totals } = summary
167
+ const sideFailed = summary.failures.some((failure) => failure.page === null)
168
+ if (sideFailed && !totals.changedPages) return 'Shapewall: capture failed'
169
+ if (!totals.changedPages) return `Shapewall: no visual changes on ${plural(totals.pages, 'page')}`
170
+ return `Shapewall: ${totals.changedPages} of ${plural(totals.pages, 'page')} changed`
171
+ }
172
+
173
+ // `imageUrl(path)`: a URL for a file of the result folder (images branch), or
174
+ // null for links only. `artifactUrl`: the workflow artifact with the images.
175
+ // `runUrl`: the workflow run, for "see the log".
176
+ export function renderSummary(summary, { artifactUrl = null, runUrl = null, imageUrl = null, note = null } = {}) {
177
+ const { totals } = summary
178
+ const lines = [COMMENT_MARKER]
179
+ const title = headline(summary)
180
+ const changed = summary.shots.filter((shot) => shot.changed)
181
+ const failed = summary.failures
182
+ const quiet = !changed.length && !failed.length
183
+ if (quiet) lines.push('<details>', `<summary>${title}</summary>`, '')
184
+ else lines.push(`### ${title}`, '')
185
+
186
+ if (changed.length) {
187
+ lines.push('| Page | Screen size | Pixels changed |', '| --- | --- | --- |')
188
+ for (const shot of changed.slice(0, ROWS_MAX)) lines.push(`| ${pageCell(shot)} | ${screen(shot)} | ${changeText(shot)} |`)
189
+ if (changed.length > ROWS_MAX) lines.push('', `And ${plural(changed.length - ROWS_MAX, 'more changed shot')} in summary.json.`)
190
+ lines.push('')
191
+ }
192
+
193
+ if (imageUrl && changed.length) {
194
+ lines.push('<details open>', '<summary>Before, after and diff</summary>', '')
195
+ for (const shot of changed.slice(0, ROWS_MAX)) {
196
+ const images = shot.images || {}
197
+ const cell = (label, thumb, full) =>
198
+ images[thumb] ? `[![${label}](${imageUrl(images[thumb])})](${imageUrl(images[full] || images[thumb])})` : ' '
199
+ lines.push(`**${pageCell(shot)}**, ${screen(shot)}`, '', '| Before | After | Diff |', '| --- | --- | --- |')
200
+ lines.push(
201
+ `| ${cell('before', 'beforeThumb', 'before')} | ${cell('after', 'afterThumb', 'after')} | ${cell('diff', 'diffThumb', 'diff')} |`,
202
+ '',
203
+ )
204
+ }
205
+ lines.push('</details>', '')
206
+ }
207
+
208
+ if (failed.length) {
209
+ lines.push(`**Not captured** (${plural(failed.length, 'problem')}):`, '')
210
+ for (const failure of failed.slice(0, FAILURES_MAX)) {
211
+ const where = failure.page ? `${plain(failure.page, 64)} ${plain(failure.viewport, 32)}` : 'every page'
212
+ const side = failure.side === 'base' ? 'before' : failure.side === 'head' ? 'after' : 'compare'
213
+ lines.push(`- ${where} (${side}): ${plain(failure.error, 300)}`)
214
+ }
215
+ if (failed.length > FAILURES_MAX) lines.push(`- and ${failed.length - FAILURES_MAX} more in summary.json`)
216
+ lines.push('')
217
+ }
218
+
219
+ const facts = [`${plural(totals.shots, 'shot')} compared`]
220
+ if (totals.unchangedShots) facts.push(`${totals.unchangedShots} unchanged`)
221
+ if (totals.newPages) facts.push(plural(totals.newPages, 'new page'))
222
+ if (totals.removedPages) facts.push(plural(totals.removedPages, 'removed page'))
223
+ 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`)
225
+ lines.push(`${facts.join(', ')}.`)
226
+ const links = []
227
+ if (changed.length && artifactUrl) links.push(`[Before, after and diff images](${artifactUrl}) (the "shapewall-ci" artifact of this run)`)
228
+ if (runUrl) links.push(`[the workflow run](${runUrl})`)
229
+ if (links.length) lines.push('', `${links.join(', ')}.`)
230
+ if (note) lines.push('', plain(note, 300))
231
+ lines.push(
232
+ '',
233
+ '<sub>Turn this off: delete .github/workflows/shapewall.yml, set "ci": { "enabled": false } in shapewall.config.json, or put [skip shapewall] in the pull request title.</sub>',
234
+ )
235
+ if (quiet) lines.push('', '</details>')
236
+ let body = `${lines.join('\n')}\n`
237
+ if (body.length > BODY_MAX) body = `${body.slice(0, BODY_MAX)}\n\n(cut short; the full list is in summary.json)\n`
238
+ return body
239
+ }
240
+
241
+ // The comment when summary.json is there but not one Shapewall wrote as it
242
+ // should be (normalizeSummary said null): nothing from it is shown.
243
+ export function renderUnreadable({ runUrl = null } = {}) {
244
+ return [
245
+ COMMENT_MARKER,
246
+ '### Shapewall: the result could not be read',
247
+ '',
248
+ `The capture result (summary.json) is not in the shape Shapewall writes, so none of it is shown here.${runUrl ? ` See [the workflow run](${runUrl}).` : ''}`,
249
+ '',
250
+ ].join('\n')
251
+ }
252
+
253
+ // The comment when no summary.json exists: the capture step itself failed.
254
+ export function renderMissing({ runUrl = null } = {}) {
255
+ return [
256
+ COMMENT_MARKER,
257
+ '### Shapewall: capture failed',
258
+ '',
259
+ `No result was written, so nothing was compared.${runUrl ? ` The log of [the workflow run](${runUrl}) says what failed.` : ''}`,
260
+ '',
261
+ ].join('\n')
262
+ }
@@ -0,0 +1,238 @@
1
+ // The GitHub Actions workflow `shapewall init --ci` writes to
2
+ // .github/workflows/shapewall.yml. It pins this Shapewall's version and the
3
+ // Playwright version it captures with, so the job runs what was tested here.
4
+
5
+ import fs from 'node:fs'
6
+
7
+ export const WORKFLOW_FILE = '.github/workflows/shapewall.yml'
8
+
9
+ const PACKAGE = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
10
+
11
+ export function workflowYaml({ version = PACKAGE.version, playwright = PACKAGE.dependencies.playwright } = {}) {
12
+ return `# Shapewall: capture on every pull request.
13
+ #
14
+ # On each pull request (and each push to it) this job captures the pages in
15
+ # shapewall.config.json twice, before (the base branch) and after (the pull
16
+ # request), compares them pixel by pixel and keeps one comment on the pull
17
+ # request up to date, such as "Shapewall: 4 of 23 pages changed", with a table
18
+ # and a link to the before, after and diff images. It never fails the pull
19
+ # request: capture problems are reported in the comment.
20
+ #
21
+ # Two modes. Pick one with SHAPEWALL_PREVIEW_URL below.
22
+ #
23
+ # Build and serve (SHAPEWALL_PREVIEW_URL empty, the default): the job checks
24
+ # out the base branch and the pull request side by side and, in each, runs
25
+ # the install, build and serve commands from "ci.start" in the config, waits
26
+ # for "ci.start.url" to answer and captures it. Example config:
27
+ # "ci": { "start": { "install": ["npm", "ci"], "build": ["npm", "run", "build"],
28
+ # "serve": ["npm", "start"], "url": "http://127.0.0.1:3000" } }
29
+ #
30
+ # Preview URL: set SHAPEWALL_PREVIEW_URL to the deploy preview of this pull
31
+ # request. The job waits until it answers, then compares it with
32
+ # SHAPEWALL_BASE_URL (empty: "baseUrl" in the config, such as production).
33
+ #
34
+ # Turn it off: delete this file; or set "ci": { "enabled": false } in
35
+ # shapewall.config.json; or put [skip shapewall] in a pull request title.
36
+ # Guide: https://shapewall.com/docs/pull-requests
37
+
38
+ name: Shapewall
39
+
40
+ on:
41
+ # pull_request only: a fork's pull request then runs with a read-only token
42
+ # and no secrets. Never use pull_request_target for this workflow.
43
+ pull_request:
44
+ types: [opened, synchronize, reopened]
45
+
46
+ # Least privilege: the capture job, which builds and runs the pull request's
47
+ # code, can only read. Only the comment job, which runs no code from the pull
48
+ # request, can write the one comment.
49
+ permissions:
50
+ contents: read
51
+
52
+ # One run per pull request: a new push cancels the run still going.
53
+ concurrency:
54
+ group: shapewall-\${{ github.event.pull_request.number }}
55
+ cancel-in-progress: true
56
+
57
+ jobs:
58
+ shapewall:
59
+ name: Shapewall capture
60
+ # Skip: put [skip shapewall] anywhere in the pull request title.
61
+ if: \${{ !contains(github.event.pull_request.title, '[skip shapewall]') }}
62
+ runs-on: ubuntu-latest
63
+ timeout-minutes: 25
64
+ permissions:
65
+ contents: read
66
+ outputs:
67
+ enabled: \${{ steps.gate.outputs.enabled }}
68
+ artifact-url: \${{ steps.upload.outputs.artifact-url }}
69
+ env:
70
+ SHAPEWALL: shapewall@${version}
71
+ PLAYWRIGHT: playwright@${playwright}
72
+ # Preview URL mode: the deploy preview of this pull request; empty for build and serve mode.
73
+ # Netlify-style deploy previews:
74
+ # SHAPEWALL_PREVIEW_URL: https://deploy-preview-\${{ github.event.pull_request.number }}--YOUR-SITE.netlify.app
75
+ # Vercel branch URLs (the branch name, lower case, with "/" as "-"; check one in your Vercel dashboard):
76
+ # SHAPEWALL_PREVIEW_URL: https://YOUR-PROJECT-git-\${{ github.head_ref }}-YOUR-TEAM.vercel.app
77
+ SHAPEWALL_PREVIEW_URL: ''
78
+ # Preview URL mode: what to compare with (empty: "baseUrl" in the config).
79
+ SHAPEWALL_BASE_URL: ''
80
+ HEAD_DIR: \${{ github.workspace }}/head
81
+ BASE_DIR: \${{ github.workspace }}/base
82
+ OUT: \${{ github.workspace }}/shapewall-ci
83
+ steps:
84
+ - name: Check out the pull request
85
+ uses: actions/checkout@v4
86
+ with:
87
+ path: head
88
+ persist-credentials: false
89
+
90
+ - name: Check out the base branch (build and serve mode)
91
+ if: env.SHAPEWALL_PREVIEW_URL == ''
92
+ uses: actions/checkout@v4
93
+ with:
94
+ ref: \${{ github.event.pull_request.base.sha }}
95
+ path: base
96
+ persist-credentials: false
97
+
98
+ - uses: actions/setup-node@v4
99
+ with:
100
+ node-version: 22
101
+
102
+ # The pinned tools go in the runner's temp folder, installed from there:
103
+ # the pull request's .npmrc and package.json have no say, and every
104
+ # later step calls them by absolute path from that folder.
105
+ - name: Install Shapewall and Playwright (outside the checkout)
106
+ working-directory: \${{ runner.temp }}
107
+ env:
108
+ NPM_CONFIG_USERCONFIG: /dev/null
109
+ run: |
110
+ mkdir -p shapewall-tools
111
+ cd shapewall-tools
112
+ printf '{ "private": true }\\n' > package.json
113
+ npm install --no-audit --no-fund --ignore-scripts --registry https://registry.npmjs.org/ "$SHAPEWALL" "$PLAYWRIGHT"
114
+ echo "SW=$PWD/node_modules/.bin/shapewall" >> "$GITHUB_ENV"
115
+ echo "PW=$PWD/node_modules/.bin/playwright" >> "$GITHUB_ENV"
116
+
117
+ # "ci": { "enabled": false } in the config, or [skip shapewall] in the title, stops here.
118
+ - name: Is Shapewall on for this pull request?
119
+ id: gate
120
+ continue-on-error: true
121
+ working-directory: \${{ runner.temp }}
122
+ run: '"$SW" ci enabled --config "$HEAD_DIR/shapewall.config.json"'
123
+
124
+ - name: Cache the browser download
125
+ if: steps.gate.outputs.enabled == 'true'
126
+ id: browser-cache
127
+ uses: actions/cache@v4
128
+ with:
129
+ path: ~/.cache/ms-playwright
130
+ key: shapewall-chromium-\${{ runner.os }}-${playwright}
131
+
132
+ - name: Install Chromium and its system libraries
133
+ continue-on-error: true
134
+ if: steps.gate.outputs.enabled == 'true' && steps.browser-cache.outputs.cache-hit != 'true'
135
+ working-directory: \${{ runner.temp }}
136
+ run: '"$PW" install --with-deps chromium'
137
+
138
+ - name: Install the system libraries Chromium needs (browser from the cache)
139
+ continue-on-error: true
140
+ if: steps.gate.outputs.enabled == 'true' && steps.browser-cache.outputs.cache-hit == 'true'
141
+ working-directory: \${{ runner.temp }}
142
+ run: '"$PW" install-deps chromium'
143
+
144
+ # Preview URL mode.
145
+ - name: Wait for the deploy preview
146
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL != ''
147
+ continue-on-error: true
148
+ working-directory: \${{ runner.temp }}
149
+ run: '"$SW" ci wait --url "$SHAPEWALL_PREVIEW_URL" --timeout 600'
150
+
151
+ - name: Capture and compare (preview URL mode)
152
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL != ''
153
+ continue-on-error: true
154
+ working-directory: \${{ runner.temp }}
155
+ run: '"$SW" ci capture-compare --config "$HEAD_DIR/shapewall.config.json" --base-url "$SHAPEWALL_BASE_URL" --head-url "$SHAPEWALL_PREVIEW_URL" --out "$OUT/result"'
156
+
157
+ # Build and serve mode: ci.start runs only here, because of --allow-start,
158
+ # in the checkout --checkout names.
159
+ - name: Capture the base branch (build and serve mode)
160
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
161
+ continue-on-error: true
162
+ working-directory: \${{ runner.temp }}
163
+ run: '"$SW" ci capture --config "$HEAD_DIR/shapewall.config.json" --allow-start --checkout "$BASE_DIR" --out "$OUT/base"'
164
+
165
+ - name: Capture the pull request (build and serve mode)
166
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
167
+ continue-on-error: true
168
+ working-directory: \${{ runner.temp }}
169
+ run: '"$SW" ci capture --config "$HEAD_DIR/shapewall.config.json" --allow-start --checkout "$HEAD_DIR" --out "$OUT/head"'
170
+
171
+ - name: Compare (build and serve mode)
172
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
173
+ continue-on-error: true
174
+ working-directory: \${{ runner.temp }}
175
+ run: '"$SW" ci capture-compare --config "$HEAD_DIR/shapewall.config.json" --base-dir "$OUT/base" --head-dir "$OUT/head" --out "$OUT/result"'
176
+
177
+ # The comment job reads the config from here: it never checks out the pull request.
178
+ - name: Keep the config with the result
179
+ if: always() && steps.gate.outputs.enabled == 'true'
180
+ continue-on-error: true
181
+ run: mkdir -p "$OUT/result" && cp "$HEAD_DIR/shapewall.config.json" "$OUT/result/shapewall.config.json"
182
+
183
+ - name: Keep the images as a workflow artifact
184
+ id: upload
185
+ if: always() && steps.gate.outputs.enabled == 'true'
186
+ continue-on-error: true
187
+ uses: actions/upload-artifact@v4
188
+ with:
189
+ name: shapewall-ci
190
+ path: shapewall-ci/result
191
+ retention-days: 14
192
+ if-no-files-found: ignore
193
+
194
+ comment:
195
+ name: Shapewall comment
196
+ needs: shapewall
197
+ # No checkout and no code from the pull request: the result is data.
198
+ if: always() && needs.shapewall.outputs.enabled == 'true'
199
+ runs-on: ubuntu-latest
200
+ timeout-minutes: 10
201
+ # For "ci.images": "branch" (public repositories only) also set contents: write.
202
+ permissions:
203
+ contents: read
204
+ pull-requests: write
205
+ env:
206
+ SHAPEWALL: shapewall@${version}
207
+ steps:
208
+ - uses: actions/setup-node@v4
209
+ with:
210
+ node-version: 22
211
+
212
+ - name: Download the result
213
+ continue-on-error: true
214
+ uses: actions/download-artifact@v4
215
+ with:
216
+ name: shapewall-ci
217
+ path: \${{ runner.temp }}/shapewall-result
218
+
219
+ - name: Install Shapewall
220
+ working-directory: \${{ runner.temp }}
221
+ env:
222
+ NPM_CONFIG_USERCONFIG: /dev/null
223
+ run: |
224
+ mkdir -p shapewall-tools
225
+ cd shapewall-tools
226
+ printf '{ "private": true }\\n' > package.json
227
+ npm install --no-audit --no-fund --ignore-scripts --registry https://registry.npmjs.org/ "$SHAPEWALL"
228
+ echo "SW=$PWD/node_modules/.bin/shapewall" >> "$GITHUB_ENV"
229
+
230
+ - name: Comment on the pull request
231
+ continue-on-error: true
232
+ working-directory: \${{ runner.temp }}
233
+ env:
234
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
235
+ ARTIFACT_URL: \${{ needs.shapewall.outputs.artifact-url }}
236
+ run: '"$SW" ci comment --config "$RUNNER_TEMP/shapewall-result/shapewall.config.json" --dir "$RUNNER_TEMP/shapewall-result" --artifact-url "$ARTIFACT_URL"'
237
+ `
238
+ }