shapewall 0.2.4 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +35 -1
  3. package/dist/agent/package-lock.json +2 -2
  4. package/dist/client/assets/BoardChat-V1BCXdDB.js +27 -0
  5. package/dist/client/assets/{BuzzDialog-CZdwIQLF.js → BuzzDialog-Ds7Thpfe.js} +1 -1
  6. package/dist/client/assets/ChecksPanel-Cm22bCdQ.js +1 -0
  7. package/dist/client/assets/History-U0bD1BjA.js +1 -0
  8. package/dist/client/assets/{LocalSettings-B5gtfKEl.js → LocalSettings-DOSuW7VC.js} +1 -1
  9. package/dist/client/assets/{Management-BxEUZAmI.js → Management-BFcKFdbp.js} +1 -1
  10. package/dist/client/assets/QuickConnect-DyfPSWbV.js +1 -0
  11. package/dist/client/assets/{ShareDialog-CdVAreaw.js → ShareDialog-BouvNraR.js} +2 -2
  12. package/dist/client/assets/{app-update-dialog-BONq9YFp.js → app-update-dialog-DH2Mgby8.js} +1 -1
  13. package/dist/client/assets/{circle-x-BmT6vHKl.js → circle-x-PRxj7kPi.js} +1 -1
  14. package/dist/client/assets/index-C9S7HL_o.js +37 -0
  15. package/dist/client/assets/index-CXtuJi1K.css +2 -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-lJjkhUcH.js +1 -0
  23. package/dist/console/assets/LocalConsole-BZHqYKnt.js +1 -0
  24. package/dist/console/assets/{app-update-dialog-o4QY_jL9.js → app-update-dialog-DCM9sYE3.js} +1 -1
  25. package/dist/console/assets/console-C2LsvEco.js +55 -0
  26. package/dist/console/assets/console-Fp4k9iyx.css +2 -0
  27. package/dist/console/build-info.json +1 -1
  28. package/dist/console/console.html +2 -2
  29. package/docs/agent-hardening.md +19 -0
  30. package/docs/agent-workflow.md +33 -0
  31. package/docs/agents.md +112 -0
  32. package/docs/config.md +41 -0
  33. package/docs/deployment.md +3 -0
  34. package/docs/hosted.md +10 -0
  35. package/docs/pull-requests.md +193 -0
  36. package/package.json +2 -1
  37. package/src/agent/backends/acp.js +23 -6
  38. package/src/agent/batch-fixes.js +45 -0
  39. package/src/agent/batch-queue.js +204 -0
  40. package/src/agent/branch-mode.js +753 -0
  41. package/src/agent/config.js +6 -0
  42. package/src/agent/fix-prompt.js +5 -0
  43. package/src/agent/routes.js +850 -185
  44. package/src/agent/run.js +8 -1
  45. package/src/agent/settings-routes.js +69 -1
  46. package/src/agent/starter/worktree.js +286 -29
  47. package/src/agent/threads.js +2 -7
  48. package/src/agent/tools.js +51 -0
  49. package/src/agent/user-settings.js +33 -2
  50. package/src/ci/capture.js +103 -0
  51. package/src/ci/compare.js +267 -0
  52. package/src/ci/github.js +307 -0
  53. package/src/ci/images.js +76 -0
  54. package/src/ci/settings.js +211 -0
  55. package/src/ci/start.js +148 -0
  56. package/src/ci/summary.js +262 -0
  57. package/src/ci/workflow.js +249 -0
  58. package/src/cli/args.js +24 -1
  59. package/src/cli/ci.js +229 -0
  60. package/src/cli/help.js +23 -1
  61. package/src/cli/init.js +36 -1
  62. package/src/cli.js +6 -2
  63. package/src/comment-drawing.js +161 -0
  64. package/src/comment-fields.js +51 -0
  65. package/src/comment-media.js +528 -0
  66. package/src/config.js +7 -0
  67. package/src/doctor.js +23 -0
  68. package/src/export.js +8 -0
  69. package/src/feedback.js +89 -12
  70. package/src/github.js +3 -3
  71. package/src/hosted/admin.js +36 -4
  72. package/src/hosted/app.js +5 -0
  73. package/src/hosted/board-routes.js +63 -7
  74. package/src/hosted/clean-worker.js +22 -4
  75. package/src/hosted/cleaner.js +4 -1
  76. package/src/hosted/comment-files.js +200 -0
  77. package/src/hosted/comments.js +68 -15
  78. package/src/hosted/db.js +32 -0
  79. package/src/hosted/guest-view.js +9 -0
  80. package/src/hosted/import.js +213 -18
  81. package/src/hosted/operator.js +3 -1
  82. package/src/hosted/projects.js +3 -2
  83. package/src/hosted/push.js +6 -3
  84. package/src/hosted/retention.js +18 -0
  85. package/src/hosted/tenancy.js +1 -0
  86. package/src/hosted/token-api.js +110 -9
  87. package/src/image-sniff.js +11 -0
  88. package/src/mcp.js +48 -3
  89. package/src/remote/remote-mcp.js +2 -2
  90. package/src/remote/remote.js +6 -2
  91. package/src/remote/share.js +77 -7
  92. package/src/server/app.js +18 -1
  93. package/src/store.js +119 -33
  94. package/src/watch.js +4 -0
  95. package/dist/client/assets/BoardChat-C0a3DDjv.js +0 -28
  96. package/dist/client/assets/ChecksPanel-BHWgwJWO.js +0 -1
  97. package/dist/client/assets/History-C01qLFpP.js +0 -1
  98. package/dist/client/assets/QuickConnect-BzTM3UNO.js +0 -1
  99. package/dist/client/assets/index-C1IsGdGs.js +0 -29
  100. package/dist/client/assets/index-DnsWelgZ.css +0 -2
  101. package/dist/client/assets/ui-BAGBTB_P.js +0 -41
  102. package/dist/console/assets/LocalAccountsApp-DtfTDbQg.js +0 -1
  103. package/dist/console/assets/LocalConsole-BPpsxDq_.js +0 -1
  104. package/dist/console/assets/console-DeOji9Zv.css +0 -2
  105. package/dist/console/assets/console-MvFrlUCC.js +0 -51
@@ -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,249 @@
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
+ // `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 } = {}) {
14
+ return `# Shapewall: capture on every pull request.
15
+ #
16
+ # On each pull request (and each push to it) this job captures the pages in
17
+ # shapewall.config.json twice, before (the base branch) and after (the pull
18
+ # request), compares them pixel by pixel and keeps one comment on the pull
19
+ # request up to date, such as "Shapewall: 4 of 23 pages changed", with a table
20
+ # and a link to the before, after and diff images. It never fails the pull
21
+ # request: capture problems are reported in the comment.
22
+ #
23
+ # Two modes. Pick one with SHAPEWALL_PREVIEW_URL below.
24
+ #
25
+ # Build and serve (SHAPEWALL_PREVIEW_URL empty, the default): the job checks
26
+ # out the base branch and the pull request side by side and, in each, runs
27
+ # the install, build and serve commands from "ci.start" in the config, waits
28
+ # for "ci.start.url" to answer and captures it. Example config:
29
+ # "ci": { "start": { "install": ["npm", "ci"], "build": ["npm", "run", "build"],
30
+ # "serve": ["npm", "start"], "url": "http://127.0.0.1:3000" } }
31
+ #
32
+ # Preview URL: set SHAPEWALL_PREVIEW_URL to the deploy preview of this pull
33
+ # request. The job waits until it answers, then compares it with
34
+ # SHAPEWALL_BASE_URL (empty: "baseUrl" in the config, such as production).
35
+ #
36
+ # Turn it off: delete this file; or set "ci": { "enabled": false } in
37
+ # shapewall.config.json; or put [skip shapewall] in a pull request title.
38
+ # Guide: https://shapewall.com/docs/pull-requests
39
+
40
+ name: Shapewall
41
+
42
+ on:
43
+ # pull_request only: a fork's pull request then runs with a read-only token
44
+ # and no secrets. Never use pull_request_target for this workflow.
45
+ pull_request:
46
+ types: [opened, synchronize, reopened]
47
+
48
+ # Least privilege: the capture job, which builds and runs the pull request's
49
+ # code, can only read. Only the comment job, which runs no code from the pull
50
+ # request, can write the one comment.
51
+ permissions:
52
+ contents: read
53
+
54
+ # One run per pull request: a new push cancels the run still going.
55
+ concurrency:
56
+ group: shapewall-\${{ github.event.pull_request.number }}
57
+ cancel-in-progress: true
58
+
59
+ jobs:
60
+ shapewall:
61
+ name: Shapewall capture
62
+ # Skip: put [skip shapewall] anywhere in the pull request title.
63
+ if: \${{ !contains(github.event.pull_request.title, '[skip shapewall]') }}
64
+ runs-on: ubuntu-latest
65
+ timeout-minutes: 25
66
+ permissions:
67
+ contents: read
68
+ outputs:
69
+ enabled: \${{ steps.gate.outputs.enabled }}
70
+ artifact-url: \${{ steps.upload.outputs.artifact-url }}
71
+ env:
72
+ SHAPEWALL: shapewall@${version}
73
+ PLAYWRIGHT: playwright@${playwright}
74
+ # Preview URL mode: the deploy preview of this pull request; empty for build and serve mode.
75
+ # Netlify-style deploy previews:
76
+ # SHAPEWALL_PREVIEW_URL: https://deploy-preview-\${{ github.event.pull_request.number }}--YOUR-SITE.netlify.app
77
+ # Vercel branch URLs (the branch name, lower case, with "/" as "-"; check one in your Vercel dashboard):
78
+ # SHAPEWALL_PREVIEW_URL: https://YOUR-PROJECT-git-\${{ github.head_ref }}-YOUR-TEAM.vercel.app
79
+ SHAPEWALL_PREVIEW_URL: ''
80
+ # Preview URL mode: what to compare with (empty: "baseUrl" in the config).
81
+ SHAPEWALL_BASE_URL: ''
82
+ HEAD_DIR: \${{ github.workspace }}/head
83
+ BASE_DIR: \${{ github.workspace }}/base
84
+ OUT: \${{ github.workspace }}/shapewall-ci
85
+ steps:
86
+ - name: Check out the pull request
87
+ uses: actions/checkout@v4
88
+ with:
89
+ path: head
90
+ persist-credentials: false
91
+
92
+ - name: Check out the base branch (build and serve mode)
93
+ if: env.SHAPEWALL_PREVIEW_URL == ''
94
+ uses: actions/checkout@v4
95
+ with:
96
+ ref: \${{ github.event.pull_request.base.sha }}
97
+ path: base
98
+ persist-credentials: false
99
+
100
+ - uses: actions/setup-node@v4
101
+ with:
102
+ node-version: 22
103
+
104
+ # The pinned tools go in the runner's temp folder, installed from there:
105
+ # the pull request's .npmrc and package.json have no say, and every
106
+ # later step calls them by absolute path from that folder.
107
+ - name: Install Shapewall and Playwright (outside the checkout)
108
+ working-directory: \${{ runner.temp }}
109
+ env:
110
+ NPM_CONFIG_USERCONFIG: /dev/null
111
+ run: |
112
+ mkdir -p shapewall-tools
113
+ cd shapewall-tools
114
+ printf '{ "private": true }\\n' > package.json
115
+ npm install --no-audit --no-fund --ignore-scripts --registry https://registry.npmjs.org/ "$SHAPEWALL" "$PLAYWRIGHT"
116
+ echo "SW=$PWD/node_modules/.bin/shapewall" >> "$GITHUB_ENV"
117
+ echo "PW=$PWD/node_modules/.bin/playwright" >> "$GITHUB_ENV"
118
+
119
+ # "ci": { "enabled": false } in the config, or [skip shapewall] in the title, stops here.
120
+ - name: Is Shapewall on for this pull request?
121
+ id: gate
122
+ continue-on-error: true
123
+ working-directory: \${{ runner.temp }}
124
+ run: '"$SW" ci enabled --config "$HEAD_DIR/shapewall.config.json"'
125
+
126
+ - name: Cache the browser download
127
+ if: steps.gate.outputs.enabled == 'true'
128
+ id: browser-cache
129
+ uses: actions/cache@v4
130
+ with:
131
+ path: ~/.cache/ms-playwright
132
+ key: shapewall-chromium-\${{ runner.os }}-${playwright}
133
+
134
+ - name: Install Chromium and its system libraries
135
+ continue-on-error: true
136
+ if: steps.gate.outputs.enabled == 'true' && steps.browser-cache.outputs.cache-hit != 'true'
137
+ working-directory: \${{ runner.temp }}
138
+ run: '"$PW" install --with-deps chromium'
139
+
140
+ - name: Install the system libraries Chromium needs (browser from the cache)
141
+ continue-on-error: true
142
+ if: steps.gate.outputs.enabled == 'true' && steps.browser-cache.outputs.cache-hit == 'true'
143
+ working-directory: \${{ runner.temp }}
144
+ run: '"$PW" install-deps chromium'
145
+
146
+ # Preview URL mode.
147
+ - name: Wait for the deploy preview
148
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL != ''
149
+ continue-on-error: true
150
+ working-directory: \${{ runner.temp }}
151
+ run: '"$SW" ci wait --url "$SHAPEWALL_PREVIEW_URL" --timeout 600'
152
+
153
+ - name: Capture and compare (preview URL mode)
154
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL != ''
155
+ continue-on-error: true
156
+ working-directory: \${{ runner.temp }}
157
+ run: '"$SW" ci capture-compare --config "$HEAD_DIR/shapewall.config.json" --base-url "$SHAPEWALL_BASE_URL" --head-url "$SHAPEWALL_PREVIEW_URL" --out "$OUT/result"'
158
+
159
+ # Build and serve mode: ci.start runs only here, because of --allow-start,
160
+ # in the checkout --checkout names.
161
+ - name: Capture the base branch (build and serve mode)
162
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
163
+ continue-on-error: true
164
+ working-directory: \${{ runner.temp }}
165
+ run: '"$SW" ci capture --config "$HEAD_DIR/shapewall.config.json" --allow-start --checkout "$BASE_DIR" --out "$OUT/base"'
166
+
167
+ - name: Capture the pull request (build and serve mode)
168
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
169
+ continue-on-error: true
170
+ working-directory: \${{ runner.temp }}
171
+ run: '"$SW" ci capture --config "$HEAD_DIR/shapewall.config.json" --allow-start --checkout "$HEAD_DIR" --out "$OUT/head"'
172
+
173
+ - name: Compare (build and serve mode)
174
+ if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
175
+ continue-on-error: true
176
+ working-directory: \${{ runner.temp }}
177
+ run: '"$SW" ci capture-compare --config "$HEAD_DIR/shapewall.config.json" --base-dir "$OUT/base" --head-dir "$OUT/head" --out "$OUT/result"'
178
+
179
+ # The comment job reads the config from here: it never checks out the pull request.
180
+ - name: Keep the config with the result
181
+ if: always() && steps.gate.outputs.enabled == 'true'
182
+ continue-on-error: true
183
+ run: mkdir -p "$OUT/result" && cp "$HEAD_DIR/shapewall.config.json" "$OUT/result/shapewall.config.json"
184
+
185
+ - name: Keep the images as a workflow artifact
186
+ id: upload
187
+ if: always() && steps.gate.outputs.enabled == 'true'
188
+ continue-on-error: true
189
+ uses: actions/upload-artifact@v4
190
+ with:
191
+ name: shapewall-ci
192
+ path: shapewall-ci/result
193
+ retention-days: 14
194
+ if-no-files-found: ignore
195
+
196
+ comment:
197
+ name: Shapewall comment
198
+ needs: shapewall
199
+ # No checkout and no code from the pull request: the result is data.
200
+ if: always() && needs.shapewall.outputs.enabled == 'true'
201
+ runs-on: ubuntu-latest
202
+ timeout-minutes: 10
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.
212
+ permissions:
213
+ contents: read
214
+ pull-requests: write`
215
+ }
216
+ env:
217
+ SHAPEWALL: shapewall@${version}
218
+ steps:
219
+ - uses: actions/setup-node@v4
220
+ with:
221
+ node-version: 22
222
+
223
+ - name: Download the result
224
+ continue-on-error: true
225
+ uses: actions/download-artifact@v4
226
+ with:
227
+ name: shapewall-ci
228
+ path: \${{ runner.temp }}/shapewall-result
229
+
230
+ - name: Install Shapewall
231
+ working-directory: \${{ runner.temp }}
232
+ env:
233
+ NPM_CONFIG_USERCONFIG: /dev/null
234
+ run: |
235
+ mkdir -p shapewall-tools
236
+ cd shapewall-tools
237
+ printf '{ "private": true }\\n' > package.json
238
+ npm install --no-audit --no-fund --ignore-scripts --registry https://registry.npmjs.org/ "$SHAPEWALL"
239
+ echo "SW=$PWD/node_modules/.bin/shapewall" >> "$GITHUB_ENV"
240
+
241
+ - name: Comment on the pull request
242
+ continue-on-error: true
243
+ working-directory: \${{ runner.temp }}
244
+ env:
245
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
246
+ ARTIFACT_URL: \${{ needs.shapewall.outputs.artifact-url }}
247
+ run: '"$SW" ci comment --config "$RUNNER_TEMP/shapewall-result/shapewall.config.json" --dir "$RUNNER_TEMP/shapewall-result" --artifact-url "$ARTIFACT_URL"'
248
+ `
249
+ }