shapewall 0.7.3 → 0.9.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 (105) hide show
  1. package/CHANGELOG.md +121 -0
  2. package/README.md +7 -3
  3. package/bin/shapewall.js +2 -1
  4. package/dist/agent/package-lock.json +130 -72
  5. package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
  6. package/dist/client/assets/{BuzzDialog-DwEAN6va.js → BuzzDialog-DnjF36OB.js} +1 -1
  7. package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
  8. package/dist/client/assets/{History-Cp4QRJti.js → History-FzpzGmXZ.js} +1 -1
  9. package/dist/client/assets/LocalSettings-BGFl4VKr.js +1 -0
  10. package/dist/client/assets/{Management-B-x1faV8.js → Management-BGdmGtby.js} +1 -1
  11. package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
  12. package/dist/client/assets/{ShareDialog-CdLdd6WQ.js → ShareDialog-D0tmOGcQ.js} +2 -2
  13. package/dist/client/assets/{app-update-dialog-BneaJeqQ.js → app-update-dialog-BQxVHa5e.js} +1 -1
  14. package/dist/client/assets/{circle-x-D5MkDLJk.js → circle-x-Dxsku6s6.js} +1 -1
  15. package/dist/client/assets/error-reports-sdk-COuSIAQO.js +15 -0
  16. package/dist/client/assets/index-B_m65HWT.css +2 -0
  17. package/dist/client/assets/index-C1ZwriJU.js +37 -0
  18. package/dist/client/assets/{play--xrZ7VCR.js → play-vJhLsLhL.js} +1 -1
  19. package/dist/client/assets/{refresh-cw-B-npxKae.js → refresh-cw-TbGHlgDq.js} +1 -1
  20. package/dist/client/assets/ui-CogdFhRH.js +41 -0
  21. package/dist/client/build-info.json +1 -1
  22. package/dist/client/index.html +3 -3
  23. package/dist/client/sw.js +2 -2
  24. package/dist/console/assets/{LocalAccountsApp-uKpz8EwR.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
  25. package/dist/console/assets/{LocalConsole-XeqnTeRB.js → LocalConsole-Rg-MTvSJ.js} +2 -2
  26. package/dist/console/assets/{LocalUsage-Br3Ddp7_.js → LocalUsage-BGCSfmBU.js} +1 -1
  27. package/dist/console/assets/{app-update-dialog-h11DnNZi.js → app-update-dialog-CEhV7th4.js} +1 -1
  28. package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
  29. package/dist/console/assets/console-BD5_Gha1.js +11 -0
  30. package/dist/console/assets/console-PWt8SxrJ.css +2 -0
  31. package/dist/console/assets/error-reports-sdk-COuSIAQO.js +15 -0
  32. package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
  33. package/dist/console/assets/minus-Cnq0kKnu.js +1 -0
  34. package/dist/console/assets/{tailnet-DJGcztR5.js → tailnet-Cqtbptzq.js} +2 -2
  35. package/dist/console/assets/theme-CB-cwoG6.js +1 -0
  36. package/dist/console/assets/ui-HgfwUo3E.js +41 -0
  37. package/dist/console/assets/{usage-fzmilDTS.js → usage-BCIwgDP9.js} +2 -2
  38. package/dist/console/assets/{usage-DjmUlnXL.js → usage-CeY6XnGX.js} +1 -1
  39. package/dist/console/build-info.json +1 -1
  40. package/dist/console/console.html +8 -8
  41. package/docs/README.md +64 -0
  42. package/docs/agent-hardening.md +3 -3
  43. package/docs/agent-recipes.md +3 -3
  44. package/docs/agent-workflow.md +6 -4
  45. package/docs/agents.md +25 -16
  46. package/docs/architecture.md +9 -2
  47. package/docs/config.md +53 -25
  48. package/docs/deployment.md +19 -3
  49. package/docs/github.md +1 -1
  50. package/docs/hosted.md +265 -70
  51. package/docs/local-accounts.md +1 -1
  52. package/docs/performance.md +3 -2
  53. package/docs/pull-requests.md +1 -1
  54. package/docs/starter-agent.md +4 -4
  55. package/docs/where-to-run.md +1 -1
  56. package/package.json +5 -2
  57. package/src/agent/backends/acp.js +39 -9
  58. package/src/capture/capture.js +35 -5
  59. package/src/capture/destination.js +67 -0
  60. package/src/capture/load-errors.js +82 -0
  61. package/src/checks/cli.js +41 -5
  62. package/src/cli/args.js +1 -0
  63. package/src/cli/capture.js +5 -0
  64. package/src/cli/comments.js +41 -3
  65. package/src/cli/help.js +4 -1
  66. package/src/cli/init.js +8 -4
  67. package/src/cli/misc.js +3 -3
  68. package/src/cli/serve.js +37 -6
  69. package/src/comment-fields.js +5 -0
  70. package/src/comments-cli.js +26 -5
  71. package/src/config-keys.js +191 -0
  72. package/src/config-reload.js +4 -1
  73. package/src/config.js +33 -2
  74. package/src/doctor.js +188 -39
  75. package/src/error-scrub.js +135 -0
  76. package/src/error-tracking.js +105 -0
  77. package/src/feedback.js +36 -2
  78. package/src/hosted/app.js +9 -3
  79. package/src/hosted/auth.js +14 -8
  80. package/src/hosted/board-routes.js +6 -6
  81. package/src/hosted/db.js +50 -0
  82. package/src/hosted/pages.js +16 -7
  83. package/src/hosted/server.js +4 -0
  84. package/src/hosted/token-api.js +17 -1
  85. package/src/hosted/usage-shape.js +1 -1
  86. package/src/missing-package.js +11 -0
  87. package/src/ports.js +35 -0
  88. package/src/serve-state.js +16 -0
  89. package/src/server/app.js +18 -14
  90. package/src/server/local-console.js +7 -3
  91. package/src/watch.js +6 -0
  92. package/dist/client/assets/BoardChat-BVbIXN0v.js +0 -27
  93. package/dist/client/assets/ChecksPanel-BJmSzge1.js +0 -1
  94. package/dist/client/assets/LocalSettings-Bt52or8s.js +0 -1
  95. package/dist/client/assets/QuickConnect-C6sW-MA7.js +0 -1
  96. package/dist/client/assets/index-C-pM8Kf2.js +0 -37
  97. package/dist/client/assets/index-C2_XIPRO.css +0 -2
  98. package/dist/client/assets/ui-2lMx-4bc.js +0 -41
  99. package/dist/console/assets/app-version-IdaEWb4n.js +0 -1
  100. package/dist/console/assets/console-BDuWmrw9.js +0 -11
  101. package/dist/console/assets/console-BGRSS8Ru.css +0 -2
  102. package/dist/console/assets/local-agents-BkSN9lXJ.js +0 -6
  103. package/dist/console/assets/minus-887msXez.js +0 -1
  104. package/dist/console/assets/theme-CPfJOmcz.js +0 -1
  105. package/dist/console/assets/ui-DnyJhoQU.js +0 -41
package/src/cli/init.js CHANGED
@@ -29,10 +29,14 @@ function sitemapOptions(flags) {
29
29
  }
30
30
  }
31
31
 
32
- // Indented "+ id path (group)" lines, the first `max` of them.
33
- function pageLines(pages, max = 30) {
34
- const lines = pages.slice(0, max).map((page) => ` + ${page.id} ${page.path} (${page.group})`)
35
- if (pages.length > max) lines.push(` ... and ${pages.length - max} more`)
32
+ // Indented "+ id path (group)" lines, the first `max` of them. A list
33
+ // only a line or two longer is shown whole: "... and 1 more" takes the
34
+ // line the page would have.
35
+ export const TRUNCATE_SLACK = 2
36
+ export function pageLines(pages, max = 30) {
37
+ const shown = pages.length - max <= TRUNCATE_SLACK ? pages.length : max
38
+ const lines = pages.slice(0, shown).map((page) => ` + ${page.id} ${page.path} (${page.group})`)
39
+ if (pages.length > shown) lines.push(` ... and ${pages.length - shown} more`)
36
40
  return lines.join('\n')
37
41
  }
38
42
 
package/src/cli/misc.js CHANGED
@@ -1,7 +1,6 @@
1
1
  // `shapewall github` and `shapewall doctor`.
2
2
 
3
3
  import { getBoard, loadConfig } from '../config.js'
4
- import { DEFAULT_PORT } from '../serve-state.js'
5
4
  import { acpFlag } from './serve.js'
6
5
 
7
6
  export async function github(positional, flags, out) {
@@ -49,8 +48,9 @@ export async function doctor(flags, out) {
49
48
  const code = await installBrowser()
50
49
  if (code !== 0) throw new Error('the browser download failed (see above)')
51
50
  }
52
- const port = flags.port === undefined ? DEFAULT_PORT : Number(flags.port)
53
- if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('--port must be a port number')
51
+ // No --port: the port serve would use (the one this project last served on, else the default).
52
+ const port = flags.port === undefined ? null : Number(flags.port)
53
+ if (port !== null && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('--port must be a port number')
54
54
  // --install-browser works anywhere (the demo runs it in the Shapewall clone): no config is a skip there.
55
55
  const report = await runDoctor({
56
56
  configFile: flags.config,
package/src/cli/serve.js CHANGED
@@ -12,7 +12,9 @@ import { detectAgents } from '../agent/acp/detect.js'
12
12
  import { agentSettings } from '../agent/config.js'
13
13
  import { watchConfig } from '../config-reload.js'
14
14
  import { cliCommand } from '../invocation.js'
15
- import { DEFAULT_PORT, clearServeState, servedUrl, writeServeState } from '../serve-state.js'
15
+ import { DEFAULT_PORT, clearServeState, runningBoardUrl, servedUrl, writeServeState } from '../serve-state.js'
16
+ import { nextFreePort, portInUse } from '../ports.js'
17
+ import { keyWarningLines } from '../config-keys.js'
16
18
  import { registerProject } from '../local-projects.js'
17
19
  import { openBrowser } from './open.js'
18
20
  import { startNotifier } from './notify.js'
@@ -80,8 +82,28 @@ export function detectedAgentsLine(found) {
80
82
  return parts.length ? parts.join(' ') : null
81
83
  }
82
84
 
85
+ // A port that is taken, in plain words and with a port that is free (the
86
+ // error Node gives is "listen EADDRINUSE: address already in use ...").
87
+ // Any other listen error is returned as it is.
88
+ export async function listenFailure(error, { port, host, config, flags = {} }) {
89
+ if (error?.code !== 'EADDRINUSE') return error
90
+ const running = runningBoardUrl(config)
91
+ const mine = running && Number(new URL(running).port) === port ? running : null
92
+ const free = mine ? null : await nextFreePort(port, host)
93
+ const keep = ['config', 'board']
94
+ .filter((name) => typeof flags[name] === 'string')
95
+ .map((name) => ` --${name} ${flags[name]}`)
96
+ .join('')
97
+ const { message, fix } = portInUse({ port, host, free, running: mine, command: (next) => cliCommand(`serve --port ${next}${keep}`) })
98
+ const friendly = new Error(`${message} ${fix}`)
99
+ friendly.code = 'EADDRINUSE'
100
+ return friendly
101
+ }
102
+
83
103
  export async function serve(flags, out) {
84
104
  const config = loadConfig(flags.config)
105
+ // Keys the config has but Shapewall does not use (a typo, most often).
106
+ for (const line of keyWarningLines(config.warnings)) out(line)
85
107
  const acp = acpFlag(flags)
86
108
  const { createApp, stopChildren } = await import('../server/app.js')
87
109
  if (flags.lan && flags.tailscale) throw new Error('Choose --lan or --tailscale, not both.')
@@ -130,6 +152,9 @@ export async function serve(flags, out) {
130
152
  } else if (flags['accounts-origin']) {
131
153
  throw new Error('--accounts-origin needs --accounts.')
132
154
  }
155
+ // Opt-in error reports (SHAPEWALL_ERROR_DSN); nothing is loaded without it.
156
+ const { startErrorTracking } = await import('../error-tracking.js')
157
+ await startErrorTracking(process.env, { log: out })
133
158
  const app = createApp({
134
159
  config,
135
160
  readOnly,
@@ -162,11 +187,17 @@ export async function serve(flags, out) {
162
187
  }
163
188
  : app
164
189
  const server = tls ? https.createServer(tls, handler).listen(port, host) : http.createServer(handler).listen(port, host)
165
- watchConfig(config, { log: out, server })
166
- await new Promise((resolve, reject) => {
167
- server.once('listening', resolve)
168
- server.once('error', reject)
169
- })
190
+ const unwatch = watchConfig(config, { log: out, server })
191
+ try {
192
+ await new Promise((resolve, reject) => {
193
+ server.once('listening', resolve)
194
+ server.once('error', reject)
195
+ })
196
+ } catch (error) {
197
+ unwatch?.()
198
+ stopChildren(app)
199
+ throw await listenFailure(error, { port, host, config, flags })
200
+ }
170
201
  let hostServer = null
171
202
  if (lan && host !== '0.0.0.0') {
172
203
  hostServer = tls
@@ -94,6 +94,11 @@ export function validateAnchor(anchor) {
94
94
  clean.w = round(anchor.w)
95
95
  clean.h = round(anchor.h)
96
96
  }
97
+ // Optional: true when the selector found no element in the capture it was
98
+ // pinned on (`comments add --selector`), so nothing names an element that
99
+ // is not there. Kept only when true.
100
+ if (anchor.unmatched !== undefined && typeof anchor.unmatched !== 'boolean') throw bad('The anchor unmatched flag must be true or false.')
101
+ if (anchor.unmatched === true) clean.unmatched = true
97
102
  return clean
98
103
  }
99
104
 
@@ -214,6 +214,19 @@ const selectorHelp = (pageId) =>
214
214
  'It takes steps like #id, button[data-testid="save"], nav[aria-label="Main"] or div:nth-of-type(2), joined by " > " ' +
215
215
  `(no classes or other CSS). List the ones on the page: shapewall comments selectors --page ${pageId} --text "words on the element"`
216
216
 
217
+ // The note when --selector does not find exactly one element: what it
218
+ // found, and where the pin goes meanwhile.
219
+ export function unmatchedNote({ selector, viewport, pageId, none, mapFile = null }) {
220
+ const what = none
221
+ ? `finds no element in the latest ${viewport} capture`
222
+ : mapFile
223
+ ? `finds more than one element in the latest ${viewport} capture`
224
+ : `does not find exactly one element in the latest ${viewport} capture`
225
+ const where = `The comment is saved with the selector, and its pin sits near the top-left corner of the page (${DEFAULT_PIN.x}% across, ${DEFAULT_PIN.y}% down) until the board finds the element.`
226
+ const look = mapFile ? ` To pick another: shapewall comments selectors --page ${pageId} (or read ${mapFile}).` : ''
227
+ return `note: "${selector}" ${what}. ${where}${look}`
228
+ }
229
+
217
230
  // `comments add --page ID --body TEXT [--viewport NAME] [--selector CSS] [--author NAME]`
218
231
  export async function addComment(config, board, flags, out, err = () => {}) {
219
232
  const pageId = typeof flags.page === 'string' ? flags.page.trim() : ''
@@ -246,14 +259,22 @@ export async function addComment(config, board, flags, out, err = () => {}) {
246
259
  let text = ''
247
260
  const live = page ? resolveFile(config, board.id, 'captures', `${page.id}.${viewport}.html`) : null
248
261
  const found = live ? anchorText(fs.readFileSync(live, 'utf8'), selector) : ''
262
+ // None at all (the map says so): the anchor says it, so the board
263
+ // does not name an element from the selector's words.
264
+ const none = Boolean(mapped && hits.length === 0)
249
265
  if (found === null || (mapped && hits.length !== 1)) {
250
- const where = mapped
251
- ? ` (its elements: ${path.relative(process.cwd(), mapped.file) || mapped.file}, or comments selectors --page ${pageId})`
252
- : ''
253
- err(`note: "${selector}" does not find exactly one element in the latest ${viewport} capture${where}; saved the selector anyway`)
266
+ err(
267
+ unmatchedNote({
268
+ selector,
269
+ viewport,
270
+ pageId,
271
+ none,
272
+ mapFile: mapped ? path.relative(process.cwd(), mapped.file) || mapped.file : null,
273
+ }),
274
+ )
254
275
  }
255
276
  if (found) text = found
256
- anchor = { selector, text, dx: 0.5, dy: 0.5 }
277
+ anchor = { selector, text, dx: 0.5, dy: 0.5, ...(none ? { unmatched: true } : {}) }
257
278
  }
258
279
  }
259
280
  let comment
@@ -0,0 +1,191 @@
1
+ // Keys a config does not use. A typo ("viewport", "conccurency", a page's
2
+ // "titel") was silently ignored and the setting fell back to its default, so
3
+ // every key the loader does not read is reported, with the key it probably
4
+ // meant. They are warnings, never errors: a config with an extra key still
5
+ // loads. "$schema" (an editor's JSON schema pointer) is allowed anywhere.
6
+
7
+ export const TOP_LEVEL_KEYS = [
8
+ 'title',
9
+ 'id',
10
+ 'baseUrl',
11
+ 'publicUrl',
12
+ 'outputDir',
13
+ 'concurrency',
14
+ 'capturePacing',
15
+ 'viewports',
16
+ 'timeouts',
17
+ 'block',
18
+ 'reducedMotion',
19
+ 'localStorage',
20
+ 'setup',
21
+ 'liveHtml',
22
+ 'versions',
23
+ 'boardUrl',
24
+ 'environments',
25
+ 'journeys',
26
+ 'auth',
27
+ 'browser',
28
+ 'groups',
29
+ 'pages',
30
+ 'boards',
31
+ 'notifications',
32
+ 'github',
33
+ 'agent',
34
+ 'starterAgent',
35
+ 'sitemap',
36
+ 'ci',
37
+ 'checks',
38
+ ]
39
+ export const BOARD_KEYS = [
40
+ 'id',
41
+ 'title',
42
+ 'baseUrl',
43
+ 'publicUrl',
44
+ 'environments',
45
+ 'viewports',
46
+ 'groups',
47
+ 'pages',
48
+ 'journeys',
49
+ 'sitemap',
50
+ 'block',
51
+ 'reducedMotion',
52
+ 'auth',
53
+ 'localStorage',
54
+ 'setup',
55
+ ]
56
+ export const PAGE_KEYS = [
57
+ 'id',
58
+ 'path',
59
+ 'title',
60
+ 'group',
61
+ 'note',
62
+ 'waitFor',
63
+ 'actions',
64
+ 'viewports',
65
+ 'expectStatus',
66
+ 'errorSelectors',
67
+ 'seo',
68
+ 'timeout',
69
+ 'localStorage',
70
+ 'frameHeight',
71
+ ]
72
+ export const ENVIRONMENT_KEYS = ['id', 'title', 'baseUrl', 'publicUrl']
73
+ export const TIMEOUT_KEYS = ['page', 'settle']
74
+ const ALLOWED_ANYWHERE = new Set(['$schema'])
75
+
76
+ // Optimal string alignment distance: edits, with a swap of two neighbours
77
+ // ("titel") as one.
78
+ export function editDistance(a, b) {
79
+ const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)])
80
+ for (let j = 1; j <= b.length; j += 1) rows[0][j] = j
81
+ for (let i = 1; i <= a.length; i += 1) {
82
+ for (let j = 1; j <= b.length; j += 1) {
83
+ const cost = a[i - 1] === b[j - 1] ? 0 : 1
84
+ rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost)
85
+ if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) rows[i][j] = Math.min(rows[i][j], rows[i - 2][j - 2] + 1)
86
+ }
87
+ }
88
+ return rows[a.length][b.length]
89
+ }
90
+
91
+ // The known key `key` most likely meant, or null: the same word in other
92
+ // case first ("baseURL", "outputdir", "waitfor"), then the nearest within
93
+ // one edit for a short key and two for a longer one.
94
+ export function didYouMean(key, known) {
95
+ const lower = String(key).toLowerCase()
96
+ const sameCase = known.find((item) => item.toLowerCase() === lower)
97
+ if (sameCase) return sameCase
98
+ const limit = lower.length <= 4 ? 1 : 2
99
+ let best = null
100
+ let bestDistance = Infinity
101
+ for (const item of known) {
102
+ const distance = editDistance(lower, item.toLowerCase())
103
+ if (distance < bestDistance) {
104
+ best = item
105
+ bestDistance = distance
106
+ }
107
+ }
108
+ return bestDistance <= limit ? best : null
109
+ }
110
+
111
+ const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
112
+
113
+ // Unknown keys of one object: [{ path, key, suggestion, belongs }].
114
+ // `elsewhere`: { label: keys } of the other levels, for a key that is
115
+ // right but in the wrong place ("waitFor" at the top level is a page key).
116
+ function unknownKeys(value, known, where, elsewhere = {}) {
117
+ if (!isObject(value)) return []
118
+ return Object.keys(value)
119
+ .filter((key) => !known.includes(key) && !ALLOWED_ANYWHERE.has(key))
120
+ .map((key) => {
121
+ const suggestion = didYouMean(key, known)
122
+ const path = where ? `${where}.${key}` : key
123
+ // A key that is there under its right name too is a duplicate, not a typo.
124
+ if (suggestion && !Object.hasOwn(value, suggestion)) return { path, key, suggestion }
125
+ for (const [label, keys] of Object.entries(elsewhere)) {
126
+ const right = keys.find((item) => item.toLowerCase() === key.toLowerCase())
127
+ if (right) return { path, key, suggestion: null, belongs: { label, key: right } }
128
+ }
129
+ return { path, key, suggestion: null }
130
+ })
131
+ }
132
+
133
+ const PAGE_ONLY = PAGE_KEYS.filter((key) => !TOP_LEVEL_KEYS.includes(key))
134
+ const TOP_ONLY = TOP_LEVEL_KEYS.filter((key) => !PAGE_KEYS.includes(key) && !BOARD_KEYS.includes(key))
135
+ function pageKeys(pages, where) {
136
+ return Array.isArray(pages)
137
+ ? pages.flatMap((page, index) => unknownKeys(page, PAGE_KEYS, `${where}[${index}]`, { 'a top-level key': TOP_ONLY }))
138
+ : []
139
+ }
140
+ function environmentKeys(environments, where) {
141
+ return Array.isArray(environments) ? environments.flatMap((env, index) => unknownKeys(env, ENVIRONMENT_KEYS, `${where}[${index}]`)) : []
142
+ }
143
+
144
+ // Every unknown key of a parsed config, in file order. At most `max`.
145
+ export function configKeyWarnings(raw, { max = 20 } = {}) {
146
+ if (!isObject(raw)) return []
147
+ const found = [
148
+ ...unknownKeys(raw, TOP_LEVEL_KEYS, '', { 'a page key, set on each page': PAGE_ONLY }),
149
+ ...unknownKeys(raw.timeouts, TIMEOUT_KEYS, 'timeouts'),
150
+ ...environmentKeys(raw.environments, 'environments'),
151
+ ...pageKeys(raw.pages, 'pages'),
152
+ ...(Array.isArray(raw.boards)
153
+ ? raw.boards.flatMap((board, index) => [
154
+ ...unknownKeys(board, BOARD_KEYS, `boards[${index}]`, {
155
+ 'a top-level key': TOP_ONLY,
156
+ 'a page key, set on each page': PAGE_ONLY,
157
+ }),
158
+ ...environmentKeys(board?.environments, `boards[${index}].environments`),
159
+ ...pageKeys(board?.pages, `boards[${index}].pages`),
160
+ ])
161
+ : []),
162
+ ]
163
+ return found.slice(0, max)
164
+ }
165
+
166
+ // One warning as a line: `"viewport" is not a config key (did you mean "viewports"?); it is ignored.`
167
+ export function formatKeyWarning({ path, key, suggestion, belongs }) {
168
+ const where = path === key ? `"${key}"` : `"${key}" at ${path}`
169
+ if (belongs) return `${where} is ignored here: "${belongs.key}" is ${belongs.label}.`
170
+ const meant = suggestion ? ` Did you mean "${suggestion}"?` : ''
171
+ return `${where} is not a config key, so it is ignored.${meant}`
172
+ }
173
+
174
+ // The lines a command prints for a config's unknown keys, or [].
175
+ export function keyWarningLines(warnings, { file = null } = {}) {
176
+ if (!warnings?.length) return []
177
+ return [
178
+ `Warning: ${file ? `${file} has` : 'the config has'} ${warnings.length === 1 ? 'a key' : `${warnings.length} keys`} Shapewall does not use (docs/config.md lists them):`,
179
+ ...warnings.map((warning) => ` ${formatKeyWarning(warning)}`),
180
+ ]
181
+ }
182
+
183
+ // A required key that is missing while a near miss of it is there: the
184
+ // hint for its "got undefined" problem (keys are case-sensitive).
185
+ // { warning, hint } or null.
186
+ export function missingKeyHint(warnings, path) {
187
+ const near = warnings.find((warning) => warning.suggestion && `${warning.path.replace(/[^.[\]]+$/, '')}${warning.suggestion}` === path)
188
+ if (!near) return null
189
+ const why = near.key.toLowerCase() === near.suggestion.toLowerCase() ? 'keys are case-sensitive, so rename' : 'rename'
190
+ return { warning: near, hint: `the config has "${near.key}"; ${why} it to "${near.suggestion}"` }
191
+ }
@@ -11,6 +11,7 @@
11
11
  import fs from 'node:fs'
12
12
  import path from 'node:path'
13
13
  import { loadConfig } from './config.js'
14
+ import { formatKeyWarning } from './config-keys.js'
14
15
 
15
16
  export const RELOADED_KEYS = [
16
17
  'title',
@@ -40,7 +41,7 @@ export function reloadConfig(config, { load = loadConfig } = {}) {
40
41
  const applied = RELOADED_KEYS.filter((key) => !same(config[key], next[key]))
41
42
  const restart = RESTART_KEYS.filter((key) => !same(config[key], next[key]))
42
43
  for (const key of applied) config[key] = next[key]
43
- return { applied, restart }
44
+ return { applied, restart, warnings: next.warnings || [] }
44
45
  }
45
46
 
46
47
  // Starts watching; returns stop(). `log` gets one line per reload.
@@ -62,6 +63,8 @@ export function watchConfig(config, { log = () => {}, server = null } = {}) {
62
63
  }
63
64
  if (result.applied.length) log(`Config reloaded: ${result.applied.join(', ')}. Refresh the board to see it.`)
64
65
  if (result.restart.length) log(`Config: restart serve to apply ${result.restart.join(', ')}.`)
66
+ // A typo stays a warning: the edit is applied, and the log says what was ignored.
67
+ for (const warning of result.warnings) log(`Config: ${formatKeyWarning(warning)}`)
65
68
  }
66
69
  try {
67
70
  watcher = fs.watch(path.dirname(config.file), (event, file) => {
package/src/config.js CHANGED
@@ -13,6 +13,7 @@ import { cliCommand } from './invocation.js'
13
13
  import { normalizeBudgets } from './checks/budgets.js'
14
14
  import { CAPTURE_PACING_DEFAULTS, CAPTURE_PACING_MAX } from './capture/pacing.js'
15
15
  import { validateCi } from './ci/settings.js'
16
+ import { configKeyWarnings, formatKeyWarning, missingKeyHint } from './config-keys.js'
16
17
 
17
18
  export const CONFIG_FILE = 'shapewall.config.json'
18
19
  export const ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/
@@ -945,8 +946,11 @@ export function normalizeConfig(raw, { dir = process.cwd(), file = null, env = p
945
946
  pageIds: boards.flatMap((board) => board.pages.map((page) => page.id)),
946
947
  viewportNames: [...new Set([...Object.keys(viewports || {}), ...boards.flatMap((board) => Object.keys(board.viewports || {}))])],
947
948
  })
948
- if (problems.length) throw new ConfigError(problems, file)
949
- return {
949
+ // Keys the loader does not read (config-keys.js): a near miss of a key
950
+ // that is then missing ("baseURL") is named in that key's problem.
951
+ const keyWarnings = configKeyWarnings(raw, { max: 100 })
952
+ if (problems.length) throw new ConfigError(withKeyHints(problems, keyWarnings), file)
953
+ const config = {
950
954
  file,
951
955
  dir,
952
956
  title: text(raw.title, 120) || 'Shapewall',
@@ -970,6 +974,33 @@ export function normalizeConfig(raw, { dir = process.cwd(), file = null, env = p
970
974
  boards,
971
975
  notifications,
972
976
  }
977
+ // Not enumerable: the config's own settings stay what they were for
978
+ // anything that compares or copies them.
979
+ Object.defineProperty(config, 'warnings', { value: keyWarnings.slice(0, 20), enumerable: false })
980
+ return config
981
+ }
982
+
983
+ // A problem about a missing key gets the near miss the config has instead.
984
+ // The other unknown keys follow, so the config can be fixed in one pass.
985
+ function withKeyHints(problems, keyWarnings) {
986
+ if (!keyWarnings.length) return problems
987
+ const used = new Set()
988
+ const hinted = problems.map((problem) => {
989
+ const at = problem.indexOf(': ')
990
+ const near = at > 0 ? missingKeyHint(keyWarnings, problem.slice(0, at)) : null
991
+ if (!near) return problem
992
+ used.add(near.warning)
993
+ return problem.includes('(got undefined)')
994
+ ? problem.replace('(got undefined)', `(got undefined: ${near.hint})`)
995
+ : `${problem} (${near.hint})`
996
+ })
997
+ return [
998
+ ...hinted,
999
+ ...keyWarnings
1000
+ .filter((warning) => !used.has(warning))
1001
+ .slice(0, 20)
1002
+ .map(formatKeyWarning),
1003
+ ]
973
1004
  }
974
1005
 
975
1006
  export function findConfigFile(explicit, cwd = process.cwd()) {