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,307 @@
1
+ // `shapewall ci comment`: one pull request comment from a result folder,
2
+ // created once and then updated in place (found again by a hidden marker).
3
+ //
4
+ // The token is the workflow's GITHUB_TOKEN (or SHAPEWALL_GITHUB_TOKEN) from
5
+ // the environment, and it goes only where src/github.js sends tokens: to
6
+ // api.github.com, or to an API URL the environment itself names
7
+ // (SHAPEWALL_GITHUB_API_URL, or GITHUB_API_URL, which the Actions runner sets).
8
+ // A config can never point it at another host, and the signed-in GitHub CLI is
9
+ // never asked here. Redirects are refused, so the token cannot follow one.
10
+ //
11
+ // Pull requests from forks get a read-only token. That is detected from the
12
+ // event (and from a 403 on write), and the summary then goes to the job
13
+ // summary ($GITHUB_STEP_SUMMARY) instead; nothing fails.
14
+ //
15
+ // Images: a comment cannot show files from a workflow artifact, so by default
16
+ // it links to the artifact. With "ci": { "images": "branch" } in a public
17
+ // repository, the thumbnails and images are committed to an orphan branch
18
+ // (shapewall-ci) with the git data API and embedded from it. That needs
19
+ // "contents: write" and makes the images public.
20
+
21
+ import fs from 'node:fs'
22
+ import path from 'node:path'
23
+ import { DEFAULT_API_URL, checkApiUrl, tokenFrom } from '../github.js'
24
+ import { COMMENT_MARKER, normalizeSummary, renderMissing, renderSummary, renderUnreadable } from './summary.js'
25
+ import { SUMMARY_SCHEMA } from './compare.js'
26
+
27
+ export const IMAGES_BRANCH = 'shapewall-ci'
28
+ const REPO_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/
29
+ const REQUEST_TIMEOUT_MS = 20000
30
+ const COMMENT_PAGES_MAX = 10
31
+ const BRANCH_SHOTS_MAX = 20
32
+
33
+ function readJson(file) {
34
+ try {
35
+ return JSON.parse(fs.readFileSync(file, 'utf8'))
36
+ } catch {
37
+ return null
38
+ }
39
+ }
40
+
41
+ // The pull request this job runs for: from the event file, or --repo and --pull.
42
+ export function prContext(env = process.env, { repo = null, pull = null } = {}) {
43
+ const event = env.GITHUB_EVENT_PATH ? readJson(env.GITHUB_EVENT_PATH) : null
44
+ const pr = event?.pull_request || null
45
+ const fullName = String(repo || env.GITHUB_REPOSITORY || pr?.base?.repo?.full_name || '')
46
+ const number = Number(pull ?? pr?.number)
47
+ const headRepo = pr?.head?.repo?.full_name || null
48
+ const baseRepo = pr?.base?.repo?.full_name || null
49
+ return {
50
+ repo: REPO_RE.test(fullName) ? fullName : null,
51
+ pull: Number.isInteger(number) && number > 0 ? number : null,
52
+ title: typeof pr?.title === 'string' ? pr.title : '',
53
+ headSha: typeof pr?.head?.sha === 'string' && /^[0-9a-f]{40}$/.test(pr.head.sha) ? pr.head.sha : null,
54
+ // A fork's pull request: GitHub gives its workflow a read-only token.
55
+ fork: Boolean(headRepo && baseRepo && headRepo !== baseRepo),
56
+ }
57
+ }
58
+
59
+ export const SKIP_MARKER = '[skip shapewall]'
60
+ export const skipRequested = (title) =>
61
+ String(title || '')
62
+ .toLowerCase()
63
+ .includes(SKIP_MARKER)
64
+
65
+ // Where API calls go, and whether the environment named that host.
66
+ export function apiTarget(config, env = process.env) {
67
+ const named = String(env.SHAPEWALL_GITHUB_API_URL || env.GITHUB_API_URL || '').trim()
68
+ const apiUrl = String(named || config?.github?.apiUrl || DEFAULT_API_URL).replace(/\/+$/, '')
69
+ return { apiUrl, confirmed: apiUrl === DEFAULT_API_URL || Boolean(named), error: checkApiUrl(apiUrl) }
70
+ }
71
+
72
+ // The GitHub web host (links to the run, the artifact and raw images).
73
+ export function serverUrl(env = process.env) {
74
+ const value = String(env.GITHUB_SERVER_URL || 'https://github.com').replace(/\/+$/, '')
75
+ try {
76
+ const url = new URL(value)
77
+ return url.protocol === 'https:' && !url.pathname.replace(/\/+$/, '') ? url.origin : 'https://github.com'
78
+ } catch {
79
+ return 'https://github.com'
80
+ }
81
+ }
82
+
83
+ export function runUrl(env, repo) {
84
+ return repo && /^\d{1,20}$/.test(String(env.GITHUB_RUN_ID || '')) ? `${serverUrl(env)}/${repo}/actions/runs/${env.GITHUB_RUN_ID}` : null
85
+ }
86
+
87
+ // An artifact link is used only when it points at this GitHub's own web host.
88
+ export function checkArtifactUrl(value, env = process.env) {
89
+ if (!value || value === true) return null
90
+ try {
91
+ const url = new URL(String(value))
92
+ // ( ) [ ] percent-encoded: they could end the markdown link the URL goes in.
93
+ const escaped = url.toString().replace(/\(/g, '%28').replace(/\)/g, '%29').replace(/\[/g, '%5B').replace(/\]/g, '%5D')
94
+ return url.protocol === 'https:' && url.origin === serverUrl(env) ? escaped : null
95
+ } catch {
96
+ return null
97
+ }
98
+ }
99
+
100
+ // REST calls with the token; never throws for an HTTP status, only when
101
+ // GitHub cannot be reached. Returns { status, data }.
102
+ export function githubClient({ apiUrl, token, fetchImpl = globalThis.fetch }) {
103
+ return async (method, route, body) => {
104
+ let response
105
+ try {
106
+ response = await fetchImpl(`${apiUrl}${route}`, {
107
+ method,
108
+ headers: {
109
+ Accept: 'application/vnd.github+json',
110
+ Authorization: `Bearer ${token}`,
111
+ 'X-GitHub-Api-Version': '2022-11-28',
112
+ 'User-Agent': 'shapewall-ci',
113
+ ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
114
+ },
115
+ body: body === undefined ? undefined : JSON.stringify(body),
116
+ signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
117
+ redirect: 'error',
118
+ })
119
+ } catch (error) {
120
+ throw new Error(`could not reach GitHub at ${apiUrl} (${error.cause?.code || error.name})`, { cause: error })
121
+ }
122
+ let data = null
123
+ try {
124
+ data = await response.json()
125
+ } catch {
126
+ data = null
127
+ }
128
+ return { status: response.status, data }
129
+ }
130
+ }
131
+
132
+ const said = (result) => (typeof result.data?.message === 'string' ? result.data.message.slice(0, 200) : `HTTP ${result.status}`)
133
+
134
+ // The comment this job wrote before: the newest one with the marker,
135
+ // preferring ones a bot (the workflow's token) wrote.
136
+ export async function findComment(request, repo, pull) {
137
+ const found = []
138
+ for (let page = 1; page <= COMMENT_PAGES_MAX; page += 1) {
139
+ const result = await request('GET', `/repos/${repo}/issues/${pull}/comments?per_page=100&page=${page}`)
140
+ if (result.status !== 200 || !Array.isArray(result.data)) {
141
+ if (page === 1) return { error: result }
142
+ break
143
+ }
144
+ for (const comment of result.data) if (typeof comment?.body === 'string' && comment.body.startsWith(COMMENT_MARKER)) found.push(comment)
145
+ if (result.data.length < 100) break
146
+ }
147
+ const bots = found.filter((comment) => comment.user?.type === 'Bot')
148
+ return { comment: (bots.length ? bots : found).at(-1) || null }
149
+ }
150
+
151
+ // Creates or updates the one comment. Returns { action, id, url } or { error }.
152
+ export async function upsertComment(request, repo, pull, body) {
153
+ const existing = await findComment(request, repo, pull)
154
+ if (existing.error) return { error: existing.error }
155
+ if (existing.comment) {
156
+ const result = await request('PATCH', `/repos/${repo}/issues/comments/${existing.comment.id}`, { body })
157
+ if (result.status === 200) return { action: 'updated', id: result.data?.id ?? existing.comment.id, url: result.data?.html_url || null }
158
+ // A marker comment someone else wrote cannot be edited: write our own.
159
+ if (![403, 404].includes(result.status)) return { error: result }
160
+ }
161
+ const result = await request('POST', `/repos/${repo}/issues/${pull}/comments`, { body })
162
+ if (result.status === 201) return { action: 'created', id: result.data?.id ?? null, url: result.data?.html_url || null }
163
+ return { error: result }
164
+ }
165
+
166
+ // Commits the changed shots' images to the orphan branch and returns a
167
+ // function from a result-folder path to its raw URL, or { error }.
168
+ export async function pushImages(request, { repo, pull, sha, summary, dir, env }) {
169
+ const info = await request('GET', `/repos/${repo}`)
170
+ if (info.status !== 200) return { error: `could not read the repository (${said(info)})` }
171
+ if (info.data?.private !== false)
172
+ return { error: 'images: "branch" is for public repositories only (the images would be public); links are used instead' }
173
+ const prefix = `pr-${pull}/${(sha || String(Date.now())).slice(0, 12)}`
174
+ const files = []
175
+ for (const shot of summary.shots.filter((item) => item.changed && item.images).slice(0, BRANCH_SHOTS_MAX)) {
176
+ for (const rel of Object.values(shot.images)) {
177
+ if (typeof rel !== 'string' || !/^images\/[a-z0-9][a-z0-9.-]{0,100}\/[a-z.]{1,40}\.png$/.test(rel)) continue
178
+ files.push(rel)
179
+ }
180
+ }
181
+ if (!files.length) return { url: () => null }
182
+ const tree = []
183
+ for (const rel of files) {
184
+ const content = fs.readFileSync(path.join(dir, rel)).toString('base64')
185
+ const blob = await request('POST', `/repos/${repo}/git/blobs`, { content, encoding: 'base64' })
186
+ if (blob.status !== 201) return { error: `could not upload an image (${said(blob)})`, status: blob.status }
187
+ tree.push({ path: `${prefix}/${rel.slice('images/'.length)}`, mode: '100644', type: 'blob', sha: blob.data.sha })
188
+ }
189
+ for (let attempt = 0; attempt < 2; attempt += 1) {
190
+ const ref = await request('GET', `/repos/${repo}/git/ref/heads/${IMAGES_BRANCH}`)
191
+ const tip = ref.status === 200 ? ref.data?.object?.sha : null
192
+ let baseTree = null
193
+ if (tip) {
194
+ const commit = await request('GET', `/repos/${repo}/git/commits/${tip}`)
195
+ baseTree = commit.data?.tree?.sha || null
196
+ }
197
+ const newTree = await request('POST', `/repos/${repo}/git/trees`, { ...(baseTree ? { base_tree: baseTree } : {}), tree })
198
+ if (newTree.status !== 201) return { error: `could not write the images (${said(newTree)})`, status: newTree.status }
199
+ const commit = await request('POST', `/repos/${repo}/git/commits`, {
200
+ message: `Shapewall images for pull request #${pull}`,
201
+ tree: newTree.data.sha,
202
+ parents: tip ? [tip] : [],
203
+ })
204
+ if (commit.status !== 201) return { error: `could not write the images (${said(commit)})`, status: commit.status }
205
+ const update = tip
206
+ ? await request('PATCH', `/repos/${repo}/git/refs/heads/${IMAGES_BRANCH}`, { sha: commit.data.sha, force: false })
207
+ : await request('POST', `/repos/${repo}/git/refs`, { ref: `refs/heads/${IMAGES_BRANCH}`, sha: commit.data.sha })
208
+ if (update.status === 200 || update.status === 201) {
209
+ const server = serverUrl(env)
210
+ const raw =
211
+ server === 'https://github.com'
212
+ ? `https://raw.githubusercontent.com/${repo}/${commit.data.sha}`
213
+ : `${server}/${repo}/raw/${commit.data.sha}`
214
+ return { url: (rel) => (files.includes(rel) ? `${raw}/${prefix}/${rel.slice('images/'.length)}` : null) }
215
+ }
216
+ // Another pull request moved the branch meanwhile: once more from its new tip.
217
+ if (update.status !== 422) return { error: `could not update the ${IMAGES_BRANCH} branch (${said(update)})`, status: update.status }
218
+ }
219
+ return { error: `the ${IMAGES_BRANCH} branch kept moving; links are used instead` }
220
+ }
221
+
222
+ export function writeStepSummary(env, markdown) {
223
+ const file = env.GITHUB_STEP_SUMMARY
224
+ if (!file) return false
225
+ try {
226
+ fs.appendFileSync(file, `${markdown}\n`)
227
+ return true
228
+ } catch {
229
+ return false
230
+ }
231
+ }
232
+
233
+ // The whole `ci comment`. Returns { posted, action?, url?, fallback?, reason? }.
234
+ // Never throws for GitHub's answers: the pull request must not fail over a comment.
235
+ export async function commentFromResult({
236
+ dir,
237
+ config = null,
238
+ env = process.env,
239
+ repo = null,
240
+ pull = null,
241
+ artifactUrl = null,
242
+ fetchImpl,
243
+ log = () => {},
244
+ }) {
245
+ const context = prContext(env, { repo, pull })
246
+ const run = runUrl(env, context.repo)
247
+ const artifact = checkArtifactUrl(artifactUrl, env)
248
+ // From the artifact, which the pull request's code could have written:
249
+ // checked field by field before any of it reaches the comment.
250
+ const file = path.join(dir, 'summary.json')
251
+ const raw = readJson(file)
252
+ const summary = raw?.schema === SUMMARY_SCHEMA ? normalizeSummary(raw) : null
253
+ const valid = Boolean(summary)
254
+ const fallback = (reason, body) => {
255
+ const wrote = writeStepSummary(env, body)
256
+ log(`${reason}${wrote ? ' The summary is in the job summary instead.' : ''}`)
257
+ return { posted: false, fallback: wrote ? 'step-summary' : null, reason }
258
+ }
259
+ let body = valid
260
+ ? renderSummary(summary, { artifactUrl: artifact, runUrl: run })
261
+ : fs.existsSync(file)
262
+ ? renderUnreadable({ runUrl: run })
263
+ : renderMissing({ runUrl: run })
264
+ if (!context.repo || !context.pull)
265
+ return fallback(
266
+ 'No pull request to comment on (set GITHUB_REPOSITORY and run on a pull_request event, or pass --repo and --pull).',
267
+ body,
268
+ )
269
+ if (context.fork) return fallback('This pull request comes from a fork, whose workflow token is read-only, so there is no comment.', body)
270
+ const target = apiTarget(config, env)
271
+ if (target.error) return fallback(`GitHub API URL: ${target.error}.`, body)
272
+ const token = tokenFrom({ ...env, SHAPEWALL_GITHUB_GH: '0' }, target.apiUrl, target.confirmed)
273
+ if (!token) {
274
+ const why = target.confirmed
275
+ ? 'No GitHub token: the workflow step needs GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} in its env.'
276
+ : `The config sets github.apiUrl to ${target.apiUrl}; the token is only sent there when SHAPEWALL_GITHUB_API_URL names it in the environment.`
277
+ return fallback(why, body)
278
+ }
279
+ const request = githubClient({ apiUrl: target.apiUrl, token: token.value, fetchImpl })
280
+ try {
281
+ if (valid && config?.ci?.images === 'branch' && summary.shots.some((shot) => shot.changed)) {
282
+ const pushed = await pushImages(request, { repo: context.repo, pull: context.pull, sha: context.headSha, summary, dir, env })
283
+ if (pushed.error) {
284
+ const hint = pushed.status === 403 ? ' (the workflow needs "contents: write" for images: "branch")' : ''
285
+ log(`Images branch: ${pushed.error}${hint}`)
286
+ body = renderSummary(summary, { artifactUrl: artifact, runUrl: run, note: `Images are linked, not shown: ${pushed.error}${hint}.` })
287
+ } else body = renderSummary(summary, { artifactUrl: artifact, runUrl: run, imageUrl: pushed.url })
288
+ }
289
+ const result = await upsertComment(request, context.repo, context.pull, body)
290
+ if (result.error) {
291
+ const status = result.error.status
292
+ if (status === 403)
293
+ return fallback(
294
+ `GitHub refused the comment (${said(result.error)}): the token is read-only here (a fork, or no "pull-requests: write").`,
295
+ body,
296
+ )
297
+ return fallback(`GitHub refused the comment (${said(result.error)}).`, body)
298
+ }
299
+ writeStepSummary(env, body)
300
+ log(
301
+ `${result.action === 'created' ? 'Commented on' : 'Updated the comment on'} ${context.repo}#${context.pull}${result.url ? `: ${result.url}` : ''}`,
302
+ )
303
+ return { posted: true, action: result.action, url: result.url }
304
+ } catch (error) {
305
+ return fallback(`${error.message}.`, body)
306
+ }
307
+ }
@@ -0,0 +1,76 @@
1
+ // Images for a pull request comment: the pixel diff of two shots (the same
2
+ // pixelmatch diff compare mode draws, src/pixeldiff.js), drawn as a picture
3
+ // people can read (the "after" shot faded, the changed pixels in red), and
4
+ // small PNG thumbnails. pngjs only: no image library beyond what captures use.
5
+
6
+ import { PNG } from 'pngjs'
7
+ import { DIFF_COLOR, diffPixels } from '../pixeldiff.js'
8
+
9
+ export const THUMB_WIDTH = 320
10
+ // How much of the "after" shot shows through under the red: faded towards white.
11
+ const FADE = 0.75
12
+
13
+ // Compares two PNG buffers. Returns { width, height, changed, total, ratio,
14
+ // base: { width, height }, head: { width, height }, dimensionsChanged, png }
15
+ // where png is the diff picture (at the larger size of the two).
16
+ export function compareShots(baseBuffer, headBuffer) {
17
+ const base = PNG.sync.read(baseBuffer)
18
+ const head = PNG.sync.read(headBuffer)
19
+ const result = diffPixels(base, head)
20
+ const picture = new PNG({ width: result.width, height: result.height })
21
+ const out = picture.data
22
+ for (let y = 0; y < result.height; y += 1) {
23
+ for (let x = 0; x < result.width; x += 1) {
24
+ const offset = (y * result.width + x) * 4
25
+ if (result.data[offset + 3]) {
26
+ out[offset] = DIFF_COLOR[0]
27
+ out[offset + 1] = DIFF_COLOR[1]
28
+ out[offset + 2] = DIFF_COLOR[2]
29
+ } else if (x < head.width && y < head.height) {
30
+ const from = (y * head.width + x) * 4
31
+ for (let c = 0; c < 3; c += 1) out[offset + c] = Math.round(head.data[from + c] * (1 - FADE) + 255 * FADE)
32
+ } else {
33
+ out[offset] = out[offset + 1] = out[offset + 2] = 255
34
+ }
35
+ out[offset + 3] = 255
36
+ }
37
+ }
38
+ return {
39
+ width: result.width,
40
+ height: result.height,
41
+ changed: result.changed,
42
+ total: result.total,
43
+ ratio: result.total ? result.changed / result.total : 0,
44
+ base: { width: base.width, height: base.height },
45
+ head: { width: head.width, height: head.height },
46
+ dimensionsChanged: base.width !== head.width || base.height !== head.height,
47
+ png: PNG.sync.write(picture),
48
+ }
49
+ }
50
+
51
+ // A PNG at most `maxWidth` wide (box filter, a whole-number factor), or the
52
+ // same bytes when it is already that small.
53
+ export function thumbnail(buffer, maxWidth = THUMB_WIDTH) {
54
+ const image = PNG.sync.read(buffer)
55
+ const factor = Math.ceil(image.width / maxWidth)
56
+ if (factor <= 1) return buffer
57
+ const width = Math.max(1, Math.floor(image.width / factor))
58
+ const height = Math.max(1, Math.floor(image.height / factor))
59
+ const out = new PNG({ width, height })
60
+ const area = factor * factor
61
+ for (let y = 0; y < height; y += 1) {
62
+ for (let x = 0; x < width; x += 1) {
63
+ const sums = [0, 0, 0, 0]
64
+ for (let dy = 0; dy < factor; dy += 1) {
65
+ const row = (y * factor + dy) * image.width
66
+ for (let dx = 0; dx < factor; dx += 1) {
67
+ const from = (row + x * factor + dx) * 4
68
+ for (let c = 0; c < 4; c += 1) sums[c] += image.data[from + c]
69
+ }
70
+ }
71
+ const to = (y * width + x) * 4
72
+ for (let c = 0; c < 4; c += 1) out.data[to + c] = Math.round(sums[c] / area)
73
+ }
74
+ }
75
+ return PNG.sync.write(out)
76
+ }
@@ -0,0 +1,211 @@
1
+ // The `ci` section of shapewall.config.json: capture on every pull request.
2
+ // src/config.js calls validateCi; the `shapewall ci` commands read the result.
3
+ //
4
+ // `ci.start` names the commands that install, build and serve the site in a
5
+ // CI job. A config in a cloned repository must not gain a new way to run code,
6
+ // so the commands have one shape only: an argv array (a program name looked up
7
+ // on PATH, then its arguments), never a shell string, never a path to a program
8
+ // the repository ships, and never a shell or a launcher such as `env` or `sudo`
9
+ // that would turn the array back into a shell string. They run only from
10
+ // `shapewall ci capture --allow-start` inside a CI job (src/ci/start.js).
11
+
12
+ export const CI_DEFAULTS = Object.freeze({
13
+ enabled: true,
14
+ threshold: 0.001,
15
+ images: 'links',
16
+ maxPages: 50,
17
+ })
18
+ export const CI_IMAGE_MODES = ['links', 'branch']
19
+ export const CI_PAGES_MAX = 500
20
+ export const CI_IGNORE_MAX = 50
21
+ export const CI_SELECTOR_MAX = 300
22
+ export const CI_MAX_PAGES_LIMIT = 500
23
+ export const START_TIMEOUT_DEFAULT = 180000
24
+ export const START_TIMEOUT_MAX = 1800000
25
+ const ARGV_MAX = 50
26
+ const ARG_MAX = 1000
27
+ const PAGE_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/
28
+ const VIEWPORT_RE = /^[a-z][a-z0-9-]{0,31}$/
29
+ // A bare program name: no folder, so a program inside the repository cannot be named.
30
+ export const PROGRAM_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/
31
+ // Programs that run a command line given as a string, or another program
32
+ // given as an argument: in an argv array they would bring the shell string back.
33
+ export const REFUSED_PROGRAMS = new Set([
34
+ 'sh',
35
+ 'bash',
36
+ 'zsh',
37
+ 'dash',
38
+ 'ksh',
39
+ 'mksh',
40
+ 'csh',
41
+ 'tcsh',
42
+ 'fish',
43
+ 'ash',
44
+ 'busybox',
45
+ 'cmd',
46
+ 'cmd.exe',
47
+ 'powershell',
48
+ 'powershell.exe',
49
+ 'pwsh',
50
+ 'env',
51
+ 'sudo',
52
+ 'doas',
53
+ 'su',
54
+ 'xargs',
55
+ 'nohup',
56
+ 'nice',
57
+ 'timeout',
58
+ 'eval',
59
+ 'exec',
60
+ 'script',
61
+ 'setsid',
62
+ 'stdbuf',
63
+ ])
64
+ const START_STEPS = ['install', 'build', 'serve']
65
+ const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]'])
66
+
67
+ const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
68
+
69
+ // One command: an argv array. Returns it, or null with a problem pushed.
70
+ export function validateArgv(raw, where, problems) {
71
+ if (typeof raw === 'string') {
72
+ problems.push(
73
+ `${where}: an argv array such as ["npm", "run", "start"], not a string. A string would need a shell, and a config must not hand one a command line.`,
74
+ )
75
+ return null
76
+ }
77
+ if (!Array.isArray(raw) || !raw.length || raw.length > ARGV_MAX || raw.some((arg) => typeof arg !== 'string' || arg.length > ARG_MAX)) {
78
+ problems.push(`${where}: an argv array of 1 to ${ARGV_MAX} strings, such as ["npm", "run", "build"]`)
79
+ return null
80
+ }
81
+ if (raw.some((arg) => arg.includes('\0'))) {
82
+ problems.push(`${where}: no NUL characters`)
83
+ return null
84
+ }
85
+ const program = raw[0]
86
+ if (!PROGRAM_RE.test(program)) {
87
+ problems.push(
88
+ `${where}[0]: a program name found on PATH, such as "npm" or "node" (got ${JSON.stringify(program.slice(0, 80))}); paths are refused so a config cannot name a program the repository ships`,
89
+ )
90
+ return null
91
+ }
92
+ if (REFUSED_PROGRAMS.has(program.toLowerCase())) {
93
+ problems.push(
94
+ `${where}[0]: "${program}" is refused: it runs a command line or another program, which would turn the array back into a shell string. Name the real program ("npm", "node", "npx", "pnpm", "yarn") instead.`,
95
+ )
96
+ return null
97
+ }
98
+ return [...raw]
99
+ }
100
+
101
+ function validateStart(raw, where, problems) {
102
+ if (raw === undefined || raw === null) return null
103
+ if (!isObject(raw)) {
104
+ problems.push(`${where}: an object such as { "install": ["npm", "ci"], "serve": ["npm", "start"], "url": "http://127.0.0.1:3000" }`)
105
+ return null
106
+ }
107
+ for (const key of Object.keys(raw)) {
108
+ if (![...START_STEPS, 'url', 'timeout'].includes(key))
109
+ problems.push(`${where}.${key}: unknown setting (use install, build, serve, url, timeout)`)
110
+ }
111
+ const before = problems.length
112
+ const start = {}
113
+ for (const step of START_STEPS) {
114
+ if (raw[step] === undefined) continue
115
+ const argv = validateArgv(raw[step], `${where}.${step}`, problems)
116
+ if (argv) start[step] = argv
117
+ }
118
+ if (raw.serve === undefined) problems.push(`${where}.serve: the command that serves the site, such as ["npm", "start"]`)
119
+ if (raw.url !== undefined) {
120
+ let url = null
121
+ try {
122
+ url = new URL(raw.url)
123
+ } catch {
124
+ url = null
125
+ }
126
+ if (!url || !['http:', 'https:'].includes(url.protocol) || !LOOPBACK_HOSTS.has(url.hostname))
127
+ problems.push(
128
+ `${where}.url: the local address the serve command listens on, such as http://127.0.0.1:3000 (127.0.0.1, localhost or [::1] only)`,
129
+ )
130
+ else start.url = raw.url
131
+ }
132
+ start.timeout = START_TIMEOUT_DEFAULT
133
+ if (raw.timeout !== undefined) {
134
+ if (!Number.isInteger(raw.timeout) || raw.timeout < 1000 || raw.timeout > START_TIMEOUT_MAX)
135
+ problems.push(`${where}.timeout: whole milliseconds from 1000 to ${START_TIMEOUT_MAX}, for each step and for the site to answer`)
136
+ else start.timeout = raw.timeout
137
+ }
138
+ return problems.length > before ? null : start
139
+ }
140
+
141
+ // `pageIds` and `viewportNames`: every board's, for the allow-lists.
142
+ export function validateCi(raw, problems, { pageIds = [], viewportNames = [] } = {}) {
143
+ if (raw === undefined || raw === null) return { ...CI_DEFAULTS, pages: null, viewports: null, ignore: [], start: null }
144
+ if (!isObject(raw)) {
145
+ problems.push('ci: an object such as { "enabled": true, "threshold": 0.001 }')
146
+ return { ...CI_DEFAULTS, pages: null, viewports: null, ignore: [], start: null }
147
+ }
148
+ const known = ['enabled', 'threshold', 'pages', 'viewports', 'ignore', 'images', 'maxPages', 'start']
149
+ for (const key of Object.keys(raw)) if (!known.includes(key)) problems.push(`ci.${key}: unknown setting (use ${known.join(', ')})`)
150
+ const ci = { ...CI_DEFAULTS, pages: null, viewports: null, ignore: [], start: null }
151
+ if (raw.enabled !== undefined) {
152
+ if (typeof raw.enabled !== 'boolean') problems.push('ci.enabled: true or false')
153
+ else ci.enabled = raw.enabled
154
+ }
155
+ if (raw.threshold !== undefined) {
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')
158
+ else ci.threshold = raw.threshold
159
+ }
160
+ if (raw.pages !== undefined) {
161
+ const ids = new Set(pageIds)
162
+ if (
163
+ !Array.isArray(raw.pages) ||
164
+ !raw.pages.length ||
165
+ raw.pages.length > CI_PAGES_MAX ||
166
+ raw.pages.some((id) => typeof id !== 'string' || !PAGE_ID_RE.test(id))
167
+ )
168
+ problems.push(`ci.pages: a list of 1 to ${CI_PAGES_MAX} page ids`)
169
+ else {
170
+ const missing = raw.pages.filter((id) => !ids.has(id))
171
+ if (missing.length) problems.push(`ci.pages: no page ${missing.map((id) => JSON.stringify(id)).join(', ')}`)
172
+ else ci.pages = [...new Set(raw.pages)]
173
+ }
174
+ }
175
+ if (raw.viewports !== undefined) {
176
+ const names = new Set(viewportNames)
177
+ if (
178
+ !Array.isArray(raw.viewports) ||
179
+ !raw.viewports.length ||
180
+ raw.viewports.some((name) => typeof name !== 'string' || !VIEWPORT_RE.test(name))
181
+ )
182
+ problems.push('ci.viewports: a list of viewport names, such as ["desktop", "phone"]')
183
+ else {
184
+ const missing = raw.viewports.filter((name) => !names.has(name))
185
+ if (missing.length) problems.push(`ci.viewports: no viewport ${missing.map((name) => JSON.stringify(name)).join(', ')}`)
186
+ else ci.viewports = [...new Set(raw.viewports)]
187
+ }
188
+ }
189
+ if (raw.ignore !== undefined) {
190
+ if (
191
+ !Array.isArray(raw.ignore) ||
192
+ raw.ignore.length > CI_IGNORE_MAX ||
193
+ raw.ignore.some((selector) => typeof selector !== 'string' || !selector.trim() || selector.length > CI_SELECTOR_MAX)
194
+ )
195
+ problems.push(
196
+ `ci.ignore: up to ${CI_IGNORE_MAX} CSS selectors (each up to ${CI_SELECTOR_MAX} characters), such as [".clock", "#ad-slot"]`,
197
+ )
198
+ else ci.ignore = raw.ignore.map((selector) => selector.trim())
199
+ }
200
+ if (raw.images !== undefined) {
201
+ if (!CI_IMAGE_MODES.includes(raw.images)) problems.push(`ci.images: "links" (the default) or "branch" (public repositories only)`)
202
+ else ci.images = raw.images
203
+ }
204
+ if (raw.maxPages !== undefined) {
205
+ if (!Number.isInteger(raw.maxPages) || raw.maxPages < 1 || raw.maxPages > CI_MAX_PAGES_LIMIT)
206
+ problems.push(`ci.maxPages: a whole number from 1 to ${CI_MAX_PAGES_LIMIT}`)
207
+ else ci.maxPages = raw.maxPages
208
+ }
209
+ ci.start = validateStart(raw.start, 'ci.start', problems)
210
+ return ci
211
+ }