shapewall 0.8.0 → 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 (76) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +5 -2
  3. package/bin/shapewall.js +2 -1
  4. package/dist/agent/package-lock.json +2 -2
  5. package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
  6. package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
  7. package/dist/client/assets/{History-C_NAxaRl.js → History-FzpzGmXZ.js} +1 -1
  8. package/dist/client/assets/{LocalSettings-W5Ze9ks7.js → LocalSettings-BGFl4VKr.js} +1 -1
  9. package/dist/client/assets/{Management-CXGSi6gI.js → Management-BGdmGtby.js} +1 -1
  10. package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
  11. package/dist/client/assets/{app-update-dialog-DNL0kP9U.js → app-update-dialog-BQxVHa5e.js} +1 -1
  12. package/dist/client/assets/index-B_m65HWT.css +2 -0
  13. package/dist/client/assets/{index-DTXjDgcg.js → index-C1ZwriJU.js} +19 -19
  14. package/dist/client/build-info.json +1 -1
  15. package/dist/client/index.html +2 -2
  16. package/dist/client/sw.js +2 -2
  17. package/dist/console/assets/{LocalAccountsApp-Z0gEJ74C.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
  18. package/dist/console/assets/{LocalConsole-DzHNISE9.js → LocalConsole-Rg-MTvSJ.js} +1 -1
  19. package/dist/console/assets/{app-update-dialog-CQsUPrMX.js → app-update-dialog-CEhV7th4.js} +1 -1
  20. package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
  21. package/dist/console/assets/console-BD5_Gha1.js +11 -0
  22. package/dist/console/assets/console-PWt8SxrJ.css +2 -0
  23. package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
  24. package/dist/console/assets/{tailnet-C2QPbIIC.js → tailnet-Cqtbptzq.js} +2 -2
  25. package/dist/console/assets/{usage-BDt6IQh1.js → usage-BCIwgDP9.js} +2 -2
  26. package/dist/console/build-info.json +1 -1
  27. package/dist/console/console.html +5 -5
  28. package/docs/README.md +64 -0
  29. package/docs/agent-hardening.md +3 -3
  30. package/docs/agent-recipes.md +3 -3
  31. package/docs/agent-workflow.md +6 -4
  32. package/docs/agents.md +25 -16
  33. package/docs/architecture.md +6 -1
  34. package/docs/config.md +53 -25
  35. package/docs/deployment.md +2 -2
  36. package/docs/github.md +1 -1
  37. package/docs/hosted.md +265 -70
  38. package/docs/local-accounts.md +1 -1
  39. package/docs/performance.md +3 -2
  40. package/docs/pull-requests.md +1 -1
  41. package/docs/starter-agent.md +4 -4
  42. package/docs/where-to-run.md +1 -1
  43. package/package.json +3 -2
  44. package/src/agent/backends/acp.js +39 -9
  45. package/src/capture/capture.js +35 -5
  46. package/src/capture/destination.js +67 -0
  47. package/src/capture/load-errors.js +82 -0
  48. package/src/checks/cli.js +41 -5
  49. package/src/cli/args.js +1 -0
  50. package/src/cli/capture.js +5 -0
  51. package/src/cli/comments.js +41 -3
  52. package/src/cli/help.js +4 -1
  53. package/src/cli/init.js +8 -4
  54. package/src/cli/misc.js +3 -3
  55. package/src/cli/serve.js +34 -6
  56. package/src/comment-fields.js +5 -0
  57. package/src/comments-cli.js +26 -5
  58. package/src/config-keys.js +191 -0
  59. package/src/config-reload.js +4 -1
  60. package/src/config.js +33 -2
  61. package/src/doctor.js +188 -39
  62. package/src/hosted/auth.js +14 -8
  63. package/src/hosted/db.js +50 -0
  64. package/src/hosted/pages.js +5 -1
  65. package/src/missing-package.js +11 -0
  66. package/src/ports.js +35 -0
  67. package/src/serve-state.js +16 -0
  68. package/src/watch.js +6 -0
  69. package/dist/client/assets/BoardChat-DG08cvD0.js +0 -27
  70. package/dist/client/assets/ChecksPanel-BD7GniTp.js +0 -1
  71. package/dist/client/assets/QuickConnect-Cta4dT3n.js +0 -1
  72. package/dist/client/assets/index-CBrmVq4n.css +0 -2
  73. package/dist/console/assets/app-version-CP0o1L1_.js +0 -1
  74. package/dist/console/assets/console-DIWY1goy.css +0 -2
  75. package/dist/console/assets/console-DYqhjwPS.js +0 -11
  76. package/dist/console/assets/local-agents-D7Jd9P7A.js +0 -6
@@ -1,7 +1,7 @@
1
1
  # Local accounts and profile images
2
2
 
3
3
  Local accounts are opt-in. Ordinary `shapewall serve` keeps its existing access model and does not create an account database.
4
- Use Node 22.13 or newer and start with `shapewall serve --accounts`. On a loopback listener its fixed origin uses `localhost` and
4
+ Use Node 22.19 or newer and start with `shapewall serve --accounts`. On a loopback listener its fixed origin uses `localhost` and
5
5
  the serving port. Passkeys require a hostname; IP origins are rejected. Existing IP bookmarks redirect to the configured account
6
6
  hostname. Behind a proxy, pass `--accounts-origin https://wall.example.test` or set `SHAPEWALL_ACCOUNTS_ORIGIN`.
7
7
  `SHAPEWALL_ACCOUNTS=1` also enables the feature. A non-loopback account origin must use HTTPS. Changing the origin later requires
@@ -19,8 +19,9 @@ otherwise the installed Chrome is discovered. An unsupported browser channel
19
19
  fails honestly. An optional `--browser-version` requires an exact installed
20
20
  browser version for reproducible CI comparisons.
21
21
 
22
- Run audits through the machine's capped browser wrapper, for example
23
- `browser-slot node ...` in local tooling. Each navigation gets its own private
22
+ An audit launches a full Chrome, so give it a bounded share of the machine
23
+ rather than running it beside a capture or a build: a container, a cgroup or a
24
+ CI job with its own memory and CPU limits. Each navigation gets its own private
24
25
  browser profile beneath the configured output directory. The runner closes the
25
26
  browser and removes this profile on success or failure.
26
27
 
@@ -48,7 +48,7 @@ commands in `ci.start`, waits for it to answer, and captures it:
48
48
 
49
49
  Each command is an argv array: a program found on `PATH` and its arguments, run without a shell. `url` is the local address the serve
50
50
  command listens on; `timeout` (default 180000 ms) bounds each step and the wait for the site. Both sides use the config of the pull
51
- request, so they are captured the same way. See [config.md](config.md#ci) for every `ci` setting.
51
+ request, so they are captured the same way. See [Config reference](config.md#ci) for every `ci` setting.
52
52
 
53
53
  ### Preview URL mode
54
54
 
@@ -4,7 +4,7 @@
4
4
  checkout of your repo (with no `.git` in it), runs your tests, replies on the comment and leaves the change on a new branch (and, if you ask, a pull request). It is
5
5
  meant for **shared boards**, where the people writing comments are not all people you would hand a shell to.
6
6
 
7
- The board chat ([agents.md](agents.md)) runs an agent _as you_, on your machine. The starter agent assumes the comment may be hostile and
7
+ The board chat ([Chat with an agent](agents.md)) runs an agent _as you_, on your machine. The starter agent assumes the comment may be hostile and
8
8
  puts walls around the agent instead: the container, an egress allow list, a fixed set of tools, a trigger gate, budgets and branch-only
9
9
  output. This page says what each wall does and, as plainly, what it does not.
10
10
 
@@ -78,7 +78,7 @@ Who counts as a member depends on the board:
78
78
  - **Hosted boards** (`--remote`): the account handle the server attests (`authorHandle`, `reply.handle`). Display names never count.
79
79
  - **Local boards**: the author name as typed. A local board has no accounts, so this is only as strong as who can reach the board. On
80
80
  a board shared through a proxy, anyone who can comment can type a trusted name: put real authentication in front (see
81
- [deployment.md](deployment.md)) or use a hosted board.
81
+ [Deployment and self-hosting](deployment.md)) or use a hosted board.
82
82
 
83
83
  A comment is claimed with a compare-and-set on its agent status, so two runs never take the same comment. `--retry` takes one whose
84
84
  status is `done` or `needs-human`.
@@ -226,7 +226,7 @@ branch is pushed is a flag: `--git-remote`, `--fork-remote`).
226
226
  | `--fork-remote NAME` | | With `--pr`: push to this remote (your fork) and open the pull request from it. |
227
227
  | `--remote URL` | | A hosted board instead of the local one (`run` and `watch`). |
228
228
 
229
- The model endpoint and key follow the chat's rules ([agents.md](agents.md)): a config cannot send your key to a host you did not
229
+ The model endpoint and key follow the chat's rules ([Chat with an agent](agents.md)): a config cannot send your key to a host you did not
230
230
  confirm. The starter agent always uses the OpenAI-compatible endpoint, never the chat's ACP agent.
231
231
 
232
232
  ## Threat model
@@ -321,5 +321,5 @@ connect configured. The existing push guard still blocks CI/workflow-sensitive
321
321
  changes unless explicitly allowed by the runner. The GitHub credential remains
322
322
  on the runner; it is never uploaded with the board or given to the sandbox.
323
323
  Comments and captures are untrusted text. A shell-capable agent with a readable
324
- token remains a prompt-injection risk: read [agent-hardening.md](agent-hardening.md)
324
+ token remains a prompt-injection risk: read [Agent hardening](agent-hardening.md)
325
325
  and keep both server claim budgets and per-run turns/tokens/minutes limits.
@@ -38,7 +38,7 @@ shapewall hosted --data ./hosted-data --tailscale
38
38
  ```
39
39
 
40
40
  One server for all your projects: passkey accounts, workspaces, invites, roles, share links and live presence. It runs on any machine
41
- that stays on: a spare computer at home, a server in the office, a small cloud machine. It needs Node 22.13 or newer and little else:
41
+ that stays on: a spare computer at home, a server in the office, a small cloud machine. It needs Node 22.19 or newer and little else:
42
42
  it stores and serves boards, and runs no browser and no agent. The full guide is [the hosted operator guide](hosted.md).
43
43
 
44
44
  **Tailscale is the recommended way to reach it.** With `--tailscale` the server gets a private HTTPS address on the machine's tailnet
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shapewall",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Every page of your site on one zoomable wall: desktop and phone captures, sandboxed live HTML, and element-anchored comments your coding agent can read.",
5
5
  "license": "Apache-2.0 AND FSL-1.1-ALv2",
6
6
  "author": "Dan Baruch",
@@ -29,6 +29,7 @@
29
29
  "THIRD_PARTY.md",
30
30
  "CHANGELOG.md",
31
31
  "Dockerfile.agent",
32
+ "docs/README.md",
32
33
  "docs/agent-hardening.md",
33
34
  "docs/agent-recipes.md",
34
35
  "docs/agent-workflow.md",
@@ -54,7 +55,7 @@
54
55
  "docs/images"
55
56
  ],
56
57
  "engines": {
57
- "node": ">=22"
58
+ "node": ">=22.19.0"
58
59
  },
59
60
  "scripts": {
60
61
  "dev": "vite",
@@ -247,8 +247,9 @@ export function sessionChoices(session) {
247
247
  // the agent lists them (model, thinking level, mode, then any other), with
248
248
  // display text made showable and bounded. Never a credential, path, command
249
249
  // or permission setting, and never a mode or value that lets the agent act
250
- // without asking (bypass, yolo, accept edits, full access, ...): the panel
251
- // promises that the agent asks before it changes files or runs commands.
250
+ // without asking (bypass, yolo, accept edits, full access, ...): the menu
251
+ // never offers a switch to one. The mode the session is in now is listed
252
+ // even when it is one of those, so the panel can say so.
252
253
  // An agent that reports its modes the older way (session/new `modes`, set
253
254
  // with session/set_mode) gets the same "mode" option, id MODE_OPTION_ID.
254
255
  const OPTION_VALUES_MAX = 60
@@ -271,13 +272,38 @@ const optionValues = (list) =>
271
272
  ...(item.description ? { description: showable(String(item.description)).slice(0, 160) } : {}),
272
273
  }))
273
274
 
275
+ // What a mode lets the agent do on its own, when that can be told: 'acts'
276
+ // (changes files or runs commands without asking), 'asks' (asks before an
277
+ // edit or a command its own settings do not already allow) or 'reads' (does
278
+ // not change files). Known agents by their modes' ids (read from each
279
+ // adapter's source); any agent by a name that says it acts without asking.
280
+ // Otherwise null: the panel then names the mode and says nothing more.
281
+ const MODE_PERMISSIONS = {
282
+ claude: { default: 'asks', plan: 'reads' },
283
+ codex: { 'read-only': 'reads' },
284
+ goose: { approve: 'asks', chat: 'reads' },
285
+ }
286
+ export function modePermission(kind, value, name = '') {
287
+ if (UNSAFE_VALUE_RE.test(`${value} ${name}`)) return 'acts'
288
+ return MODE_PERMISSIONS[kind]?.[value] || null
289
+ }
290
+ const withPermissions = (kind, values) =>
291
+ values.map((item) => {
292
+ const permission = modePermission(kind, item.value, item.name)
293
+ return permission ? { ...item, permission } : item
294
+ })
295
+
296
+ const modeValues = (category, kind, values) => (category === 'mode' ? withPermissions(kind, values) : values)
297
+
274
298
  // Only the current value and safe ones of a mode or an uncategorised option.
275
299
  const safeValues = (category, values, current) =>
276
300
  ['model', 'thought_level'].includes(category)
277
301
  ? values
278
302
  : values.filter((item) => item.value === current || !UNSAFE_VALUE_RE.test(`${item.value} ${item.name}`))
279
303
 
280
- export function sessionOptions(configOptions, modes = null) {
304
+ // `kind`: the agent (acpAgentKind), for what each mode lets it do
305
+ // (modePermission); a mode's values then carry `permission` when known.
306
+ export function sessionOptions(configOptions, modes = null, kind = null) {
281
307
  const out = (Array.isArray(configOptions) ? configOptions : [])
282
308
  .filter(
283
309
  (option) =>
@@ -294,7 +320,7 @@ export function sessionOptions(configOptions, modes = null) {
294
320
  name: showable(String(option.name || option.category || option.id)).slice(0, 60),
295
321
  ...(option.description ? { description: showable(String(option.description)).slice(0, 160) } : {}),
296
322
  currentValue: option.currentValue,
297
- values: safeValues(category, optionValues(option.options), option.currentValue),
323
+ values: modeValues(category, kind, safeValues(category, optionValues(option.options), option.currentValue)),
298
324
  }
299
325
  })
300
326
  const available = Array.isArray(modes?.availableModes) ? modes.availableModes : []
@@ -304,10 +330,14 @@ export function sessionOptions(configOptions, modes = null) {
304
330
  category: 'mode',
305
331
  name: 'Mode',
306
332
  currentValue: modes.currentModeId,
307
- values: safeValues(
333
+ values: modeValues(
308
334
  'mode',
309
- optionValues(available.map((item) => ({ value: item?.id, name: item?.name, description: item?.description }))),
310
- modes.currentModeId,
335
+ kind,
336
+ safeValues(
337
+ 'mode',
338
+ optionValues(available.map((item) => ({ value: item?.id, name: item?.name, description: item?.description }))),
339
+ modes.currentModeId,
340
+ ),
311
341
  ),
312
342
  })
313
343
  }
@@ -801,7 +831,7 @@ class AcpProcess {
801
831
  this.configOptions = Array.isArray(session.configOptions) ? session.configOptions : []
802
832
  this.modes = session.modes && typeof session.modes === 'object' ? session.modes : null
803
833
  // As the session started, before any chat's choices: what a new chat starts from.
804
- this.startOptions = sessionOptions(this.configOptions, this.modes)
834
+ this.startOptions = sessionOptions(this.configOptions, this.modes, acpAgentKind(this.argv))
805
835
  this.state = 'ready'
806
836
  if (this.asks) await this.askingMode()
807
837
  } catch (error) {
@@ -1336,7 +1366,7 @@ class AcpProcess {
1336
1366
 
1337
1367
  // The composer's option menus, as sessionOptions lists them.
1338
1368
  options() {
1339
- return sessionOptions(this.configOptions, this.modes)
1369
+ return sessionOptions(this.configOptions, this.modes, acpAgentKind(this.argv))
1340
1370
  }
1341
1371
  // The same menus with the values the session started with (the agent's
1342
1372
  // defaults): what the options cache keeps for the next new chat.
@@ -43,9 +43,19 @@ import { observeCaptureNetwork, captureWarningText } from './network-summary.js'
43
43
  import { capturePacer } from './pacing.js'
44
44
  import { StepError, isTimeout, runActions, seconds, stepFailure } from './actions.js'
45
45
  import { installRequestRules, seedLocalStorage } from './requests.js'
46
+ import { landedElsewhere, landedNote, landedWarning } from './destination.js'
47
+ import { allFailedHint, netErrorCode, netErrorKind, plainLoadError } from './load-errors.js'
46
48
 
47
- // A navigation timeout says so plainly; other load errors keep their own first line.
48
- const loadFailure = (error, timeout) => (isTimeout(error) ? new StepError(`loading the page timed out after ${seconds(timeout)}`) : error)
49
+ // A navigation timeout says so plainly, and so does a network error
50
+ // (load-errors.js); other load errors keep their own first line.
51
+ const loadFailure = (error, timeout, url) => {
52
+ if (isTimeout(error)) return new StepError(`loading the page timed out after ${seconds(timeout)}`)
53
+ const plain = plainLoadError(error?.message, url)
54
+ if (!plain) return error
55
+ const failure = new StepError(plain)
56
+ failure.netError = netErrorKind(netErrorCode(error?.message))
57
+ return failure
58
+ }
49
59
 
50
60
  const IMAGE_WAIT_MS = 8000
51
61
 
@@ -158,6 +168,7 @@ export async function shootPage({
158
168
  }) {
159
169
  const began = Date.now()
160
170
  let httpStatus = null
171
+ let finalUrl = null
161
172
  let finishNetwork = null,
162
173
  networkSummary = null
163
174
  let skipped = []
@@ -192,7 +203,7 @@ export async function shootPage({
192
203
  if (response.status() < 400) responses.set(response.url().split('#')[0], response)
193
204
  })
194
205
  const response = await page.goto(url, { waitUntil: 'load', timeout: pageTimeout }).catch((error) => {
195
- throw cancelled ? error : loadFailure(error, pageTimeout)
206
+ throw cancelled ? error : loadFailure(error, pageTimeout, url)
196
207
  })
197
208
  httpStatus = response ? response.status() : null
198
209
  // An error page on purpose ("expectStatus": 404) is captured like any
@@ -223,6 +234,9 @@ export async function shootPage({
223
234
  // A short pause for late renders, decodes and transitions.
224
235
  await sleep(400)
225
236
  stage = 'the screenshot'
237
+ // Where the shot really is: a redirect (to a sign-in page, say) or a
238
+ // client-side navigation may have moved it from the page asked for.
239
+ finalUrl = page.url()
226
240
  // The DevTools protocol can scale a clip, which Playwright's own
227
241
  // screenshot cannot: the thumbnail is the same frame, smaller.
228
242
  const cdp = await context.newCDPSession(page)
@@ -272,6 +286,8 @@ export async function shootPage({
272
286
  return {
273
287
  status: 'ok',
274
288
  url,
289
+ finalUrl,
290
+ ...(landedElsewhere(url, finalUrl) ? { redirected: true } : {}),
275
291
  httpStatus,
276
292
  networkSummary,
277
293
  ...(pageConfig.expectStatus?.length ? { expectedStatus: true } : {}),
@@ -288,6 +304,7 @@ export async function shootPage({
288
304
  url,
289
305
  httpStatus,
290
306
  networkSummary: networkSummary || finishNetwork?.() || null,
307
+ ...(!cancelled && error?.netError ? { netError: error.netError } : {}),
291
308
  error: message.slice(0, 300),
292
309
  ms: Date.now() - began,
293
310
  }
@@ -614,9 +631,11 @@ export async function runCapture({
614
631
  ? ` (skipped optional action${entry.skippedActions.length === 1 ? '' : 's'} ${entry.skippedActions.join(', ')})`
615
632
  : ''
616
633
  log(
617
- ` ${entry.status === 'ok' ? 'ok ' : 'FAIL'} ${page.id} ${viewportName} ${entry.status === 'ok' ? `${entry.ms} ms${expectedNote}${skippedNote}${liveNote}${warningNote}` : entry.error}`,
634
+ ` ${entry.status === 'ok' ? 'ok ' : 'FAIL'} ${page.id} ${viewportName} ${entry.status === 'ok' ? `${entry.ms} ms${landedNote(entry.url, entry.finalUrl)}${expectedNote}${skippedNote}${liveNote}${warningNote}` : entry.error}`,
618
635
  )
619
636
  })
637
+ const ranEntries = () => tasks.map(({ page, viewportName }) => manifest.pages[page.id][viewportName])
638
+ const failedHint = () => allFailedHint(ranEntries(), baseUrl)
620
639
  let linksChecked = 0
621
640
  if (linkCheck) {
622
641
  let context = null
@@ -652,7 +671,10 @@ export async function runCapture({
652
671
  manifest.durationMs = Date.now() - started
653
672
  writeJsonAtomic(path.join(workDir, 'manifest.json'), manifest)
654
673
  if (!partial) {
655
- if (status.failed === status.total) throw new Error('every shot failed; the previous captures were kept')
674
+ if (status.failed === status.total) {
675
+ const hint = failedHint()
676
+ throw new Error(`every shot failed; the previous captures were kept.${hint ? ` ${hint}` : ''}`)
677
+ }
656
678
  const old = `${finalDir}.prev`
657
679
  fs.rmSync(old, { recursive: true, force: true })
658
680
  if (fs.existsSync(finalDir)) fs.renameSync(finalDir, old)
@@ -691,6 +713,9 @@ export async function runCapture({
691
713
  page: page.id,
692
714
  viewport: viewportName,
693
715
  url: entry.url,
716
+ // Where the shot landed (null when it failed): differs from url after a redirect.
717
+ finalUrl: entry.finalUrl || null,
718
+ redirected: Boolean(entry.redirected),
694
719
  status: entry.status,
695
720
  httpStatus: entry.httpStatus ?? null,
696
721
  expectedStatus: Boolean(entry.expectedStatus),
@@ -708,6 +733,11 @@ export async function runCapture({
708
733
  log(`Broken links: ${brokenLinks.length} ("${cliCommand('links --broken')}" lists them)`)
709
734
  for (const line of formatBroken(brokenLinks, { max: 10 })) log(line)
710
735
  }
736
+ for (const line of landedWarning(shots)) log(line)
737
+ if (partial) {
738
+ const hint = failedHint()
739
+ if (hint) log(hint)
740
+ }
711
741
  return {
712
742
  ok: status.failed === 0,
713
743
  board: board.id,
@@ -0,0 +1,67 @@
1
+ // Where a shot ended up. A page that redirects (most often to a sign-in
2
+ // page) is captured as whatever it landed on, so each shot keeps its final
3
+ // URL, and capture says so when it is not the page that was asked for.
4
+
5
+ import { cliCommand } from '../invocation.js'
6
+
7
+ export const AUTH_DOCS = 'docs/config.md#auth'
8
+
9
+ const parse = (value) => {
10
+ try {
11
+ return new URL(String(value))
12
+ } catch {
13
+ return null
14
+ }
15
+ }
16
+ // "/app" and "/app/" are one page: a trailing-slash redirect is not a move.
17
+ const trimSlash = (pathname) => (pathname.length > 1 ? pathname.replace(/\/+$/, '') : pathname)
18
+
19
+ // The final URL when the shot landed somewhere other than `requested` (another
20
+ // origin, or another path), else null. The hash and the query are not
21
+ // compared: a site that adds a tracking parameter has not moved the page.
22
+ export function landedElsewhere(requested, final) {
23
+ const from = parse(requested)
24
+ const to = parse(final)
25
+ if (!from || !to) return null
26
+ if (from.origin !== to.origin || trimSlash(from.pathname) !== trimSlash(to.pathname)) return to.href
27
+ return null
28
+ }
29
+
30
+ // How a final URL is shown: its path (and query) on the same origin, the
31
+ // whole URL on another one.
32
+ export function shownDestination(requested, final) {
33
+ const from = parse(requested)
34
+ const to = parse(final)
35
+ if (!to) return String(final)
36
+ return from && from.origin === to.origin ? `${to.pathname}${to.search}` : `${to.origin}${to.pathname}`
37
+ }
38
+
39
+ const looksLikeSignIn = (url) => /(^|[/._-])(log-?in|sign-?in|auth|sso|session|account)s?([/._?-]|$)/i.test(parse(url)?.pathname || '')
40
+
41
+ // The note on one shot's line: " (landed on /login/, not /app/)".
42
+ export function landedNote(requested, final) {
43
+ if (!landedElsewhere(requested, final)) return ''
44
+ return ` (landed on ${shownDestination(requested, final)}, not ${shownDestination(requested, requested)})`
45
+ }
46
+
47
+ // The warning after a capture when any shot landed elsewhere: plain lines,
48
+ // or [] when none did.
49
+ export function landedWarning(shots) {
50
+ const moved = shots.filter((shot) => shot.status === 'ok' && shot.redirected)
51
+ if (!moved.length) return []
52
+ const signIn = moved.some((shot) => looksLikeSignIn(shot.finalUrl))
53
+ const lines = [
54
+ `Warning: ${moved.length} shot${moved.length === 1 ? '' : 's'} landed on another page than the one asked for, and the board shows ${moved.length === 1 ? 'it' : 'them'} under the requested page's title:`,
55
+ ...moved
56
+ .slice(0, 10)
57
+ .map((shot) => ` ${shot.page} ${shot.viewport}: ${shotPath(shot)} -> ${shownDestination(shot.url, shot.finalUrl)}`),
58
+ ]
59
+ if (moved.length > 10) lines.push(` and ${moved.length - 10} more`)
60
+ lines.push(
61
+ signIn
62
+ ? `That looks like a sign-in redirect. Record a login with "${cliCommand('auth record')}" (see Auth in ${AUTH_DOCS}), then capture again.`
63
+ : `If it is a sign-in redirect, record a login with "${cliCommand('auth record')}" (see Auth in ${AUTH_DOCS}); if the page moved, update its path in the config.`,
64
+ )
65
+ return lines
66
+ }
67
+ const shotPath = (shot) => shownDestination(shot.url, shot.url)
@@ -0,0 +1,82 @@
1
+ // A page that did not load, in plain words. Playwright says
2
+ // "page.goto: net::ERR_CONNECTION_REFUSED at http://...": the shot's line
3
+ // says what that means and what to do next, the way init does
4
+ // ("connection refused (is the site running?)").
5
+
6
+ import { cliCommand } from '../invocation.js'
7
+
8
+ const parse = (value) => {
9
+ try {
10
+ return new URL(String(value))
11
+ } catch {
12
+ return null
13
+ }
14
+ }
15
+
16
+ // The Chromium network error in a message ("ERR_CONNECTION_REFUSED"), or null.
17
+ export function netErrorCode(message) {
18
+ return /\bnet::(ERR_[A-Z0-9_]+)/.exec(String(message || ''))?.[1] || null
19
+ }
20
+
21
+ const KINDS = [
22
+ [/^ERR_CONNECTION_REFUSED$/, 'refused'],
23
+ [/^ERR_NAME_NOT_RESOLVED$|^ERR_NAME_RESOLUTION_FAILED$/, 'dns'],
24
+ [/^ERR_CONNECTION_(RESET|CLOSED|ABORTED|FAILED)$|^ERR_EMPTY_RESPONSE$/, 'reset'],
25
+ [/^ERR_(CONNECTION_)?TIMED_OUT$/, 'timeout'],
26
+ [/^ERR_(ADDRESS_UNREACHABLE|INTERNET_DISCONNECTED|NETWORK_CHANGED|NETWORK_ACCESS_DENIED)$/, 'network'],
27
+ [/^ERR_CERT_|^ERR_SSL_/, 'tls'],
28
+ [/^ERR_TOO_MANY_REDIRECTS$/, 'redirects'],
29
+ [/^ERR_ABORTED$/, 'aborted'],
30
+ ]
31
+ export function netErrorKind(code) {
32
+ if (!code) return null
33
+ return KINDS.find(([pattern]) => pattern.test(code))?.[1] || 'other'
34
+ }
35
+
36
+ // The shot's error line for a failed load, or null when the message is not a
37
+ // network error (it is then shown as it is).
38
+ export function plainLoadError(message, url) {
39
+ const code = netErrorCode(message)
40
+ if (!code) return null
41
+ const where = parse(url)
42
+ const site = where ? where.origin : String(url)
43
+ switch (netErrorKind(code)) {
44
+ case 'refused':
45
+ return `connection refused at ${site} (is the site running?)`
46
+ case 'dns':
47
+ return `host not found: ${where?.hostname || site} (check baseUrl)`
48
+ case 'reset':
49
+ return `the connection to ${site} closed before the page loaded (${code})`
50
+ case 'timeout':
51
+ return `connecting to ${site} timed out (${code})`
52
+ case 'network':
53
+ return `${site} is not reachable from this machine (${code})`
54
+ case 'tls':
55
+ return `the TLS certificate of ${site} was not accepted (${code})`
56
+ case 'redirects':
57
+ return `${url} redirects in a loop (${code})`
58
+ case 'aborted':
59
+ return `the browser stopped loading ${url} (${code}): a download or a page that navigated away while loading`
60
+ default:
61
+ return `the page did not load (${code})`
62
+ }
63
+ }
64
+
65
+ // One line after a run where every shot failed to load for the same
66
+ // network reason: what to do next. null otherwise.
67
+ export function allFailedHint(shots, baseUrl) {
68
+ const failed = shots.filter((shot) => shot.status !== 'ok')
69
+ if (!failed.length || failed.length !== shots.length) return null
70
+ const kinds = new Set(failed.map((shot) => shot.netError || null))
71
+ if (kinds.size !== 1) return null
72
+ const [kind] = kinds
73
+ if (kind === 'refused')
74
+ return `Nothing answered at ${baseUrl}. Start your site (or fix baseUrl in shapewall.config.json), then capture again. "${cliCommand('doctor')}" checks it.`
75
+ if (kind === 'dns')
76
+ return `The host in baseUrl (${baseUrl}) does not resolve. Check it in shapewall.config.json (a typo, or a host only another network knows).`
77
+ if (kind === 'timeout' || kind === 'network')
78
+ return `${baseUrl} is not reachable from this machine. Check that the site is up and that this machine can reach it.`
79
+ if (kind === 'tls')
80
+ return `The browser did not accept the TLS certificate of ${baseUrl}. For a local certificate, use the http URL or install the certificate for this machine.`
81
+ return null
82
+ }
package/src/checks/cli.js CHANGED
@@ -40,16 +40,52 @@ export async function checksCommand(config, positional, flags, out, err = () =>
40
40
  }
41
41
  const failed = reports.filter((r) => r.state === 'failed').length
42
42
  const stopped = reports.stopped
43
+ if (flags.json) {
44
+ out(JSON.stringify({ schemaVersion: 1, reports, ...(stopped ? { stopped } : {}) }, null, 2))
45
+ return stopped ? CHECKS_STOPPED_EXIT : failed ? 2 : 0
46
+ }
47
+ const { lines, views } = warningLines(reports)
48
+ const warned = views ? ` ${views} with warnings.` : ''
43
49
  out(
44
- flags.json
45
- ? JSON.stringify({ schemaVersion: 1, reports, ...(stopped ? { stopped } : {}) }, null, 2)
46
- : stopped
47
- ? `Stopped after ${stopped.checked} of ${stopped.total} page views. ${failed} failed. Page views not checked keep their earlier results.`
48
- : `Checked ${reports.length} page views. ${failed} failed. Reports are local and were not sent to an agent.`,
50
+ stopped
51
+ ? `Stopped after ${stopped.checked} of ${stopped.total} page views. ${failed} failed.${warned} Page views not checked keep their earlier results.`
52
+ : `Checked ${reports.length} page views. ${failed} failed.${warned} Reports are local and were not sent to an agent.`,
49
53
  )
54
+ for (const line of lines) out(line)
50
55
  return stopped ? CHECKS_STOPPED_EXIT : failed ? 2 : 0
51
56
  }
52
57
 
58
+ // Findings of severity "warning" are worth reading in the terminal, not only
59
+ // in --json and on the board: one line each, with its next step. Advisories
60
+ // are counted. { lines, views }: views = page views with a warning.
61
+ const WARNINGS_SHOWN = 20
62
+ const NEXT_STEPS = {
63
+ // A sign-in redirect is the usual cause: say where logins are set up.
64
+ 'destination-changed': 'If it is a sign-in page, record a login (Auth in docs/config.md); if the page moved, update its path.',
65
+ }
66
+ export function warningLines(reports) {
67
+ const rows = []
68
+ let advisories = 0
69
+ let views = 0
70
+ for (const report of reports || []) {
71
+ const findings = Array.isArray(report?.findings) ? report.findings : []
72
+ const warnings = findings.filter((item) => item?.severity === 'warning')
73
+ advisories += findings.filter((item) => item?.severity === 'advisory').length
74
+ if (warnings.length) views += 1
75
+ for (const item of warnings) {
76
+ const step = NEXT_STEPS[item.id] || item.nextAction
77
+ rows.push(` warning ${report.pageId} ${report.viewport?.name || ''}: ${item.title}.${step ? ` ${step}` : ''}`)
78
+ }
79
+ }
80
+ const lines = rows.slice(0, WARNINGS_SHOWN)
81
+ if (rows.length > WARNINGS_SHOWN) lines.push(` and ${rows.length - WARNINGS_SHOWN} more warnings`)
82
+ if (rows.length || advisories)
83
+ lines.push(
84
+ `${advisories ? `${advisories} advisor${advisories === 1 ? 'y' : 'ies'} not shown. ` : ''}Every finding is in --json and on the board's Checks.`,
85
+ )
86
+ return { lines, views }
87
+ }
88
+
53
89
  const STOP_SIGNALS = ['SIGTERM', 'SIGINT']
54
90
  // Exit code of a run that was stopped before every page view was checked.
55
91
  export const CHECKS_STOPPED_EXIT = 3
package/src/cli/args.js CHANGED
@@ -141,6 +141,7 @@ export const COMMAND_FLAGS = {
141
141
  'body',
142
142
  'author',
143
143
  'board',
144
+ 'yes',
144
145
  ...REMOTE_FLAGS,
145
146
  ],
146
147
  events: ['follow', 'since', 'limit', 'json', 'board'],
@@ -6,6 +6,7 @@ import { readManifest } from '../store.js'
6
6
  import { cliCommand } from '../invocation.js'
7
7
  import { formatBroken } from '../broken-links.js'
8
8
  import { pageLinks } from '../links.js'
9
+ import { keyWarningLines } from '../config-keys.js'
9
10
 
10
11
  // `capture`: one line per shot and a summary; with --json the summary is one
11
12
  // JSON document on stdout and the progress lines go to stderr. --yes is
@@ -13,6 +14,8 @@ import { pageLinks } from '../links.js'
13
14
  export async function capture(flags, out, err) {
14
15
  const config = loadConfig(flags.config)
15
16
  const json = Boolean(flags.json)
17
+ // Keys the config has but Shapewall does not use (a typo, most often).
18
+ for (const line of keyWarningLines(config.warnings)) (json ? err : out)(line)
16
19
  const result = await runCapture({
17
20
  config,
18
21
  boardId: flags.board,
@@ -36,6 +39,8 @@ export async function capture(flags, out, err) {
36
39
  durationMs: result.durationMs,
37
40
  dir: result.dir,
38
41
  failedShots: result.shots.filter((shot) => shot.status !== 'ok'),
42
+ // Shots that landed on another page than the one asked for (a sign-in redirect, say).
43
+ redirectedShots: result.shots.filter((shot) => shot.redirected),
39
44
  shots: result.shots,
40
45
  linksChecked: result.linksChecked,
41
46
  brokenLinks: result.brokenLinks,
@@ -1,9 +1,9 @@
1
- // `shapewall comments`: list, get, add, selectors, resolve, reopen, reply and status.
1
+ // `shapewall comments`: list, get, add, selectors, resolve, reopen, reply, status and delete.
2
2
 
3
3
  import { getBoard, loadConfig } from '../config.js'
4
4
  import { addComment, authorFlag, listSelectors, showComment, sinceFilter } from '../comments-cli.js'
5
5
  import { feedback, formatFeedback, formatFeedbackForAgent, untrustedJson } from '../feedback.js'
6
- import { AGENT_STATUSES, addReply, setAgentStatus, updateComment } from '../store.js'
6
+ import { AGENT_STATUSES, addReply, deleteComment, getComment, setAgentStatus, updateComment } from '../store.js'
7
7
  import { mentionFlag, withNotifications } from './notify.js'
8
8
 
9
9
  // Changes (resolve, reply, ...) send their notifications before the command exits.
@@ -81,5 +81,43 @@ async function commentAction(config, positional, flags, out, err) {
81
81
  out(flags.json ? JSON.stringify({ comment }, null, 2) : `#${comment.id} agent status: ${comment.agentStatus || 'none'}`)
82
82
  return
83
83
  }
84
- throw new Error(`unknown comments action "${action}" (list, get, add, selectors, resolve, reopen, reply, status)`)
84
+ if (action === 'delete') return removeComment(config, board, positional[1], flags, out)
85
+ throw new Error(`unknown comments action "${action}" (list, get, add, selectors, resolve, reopen, reply, status, delete)`)
86
+ }
87
+
88
+ // `comments delete ID [--yes]`: the board's Delete thread, from a terminal.
89
+ // It removes the comment, its replies and its images for good, so it asks
90
+ // first; --yes skips the question, and without a terminal to ask in it is
91
+ // required.
92
+ export async function removeComment(config, board, id, flags, out, { ask = askYesNo, interactive = Boolean(process.stdin.isTTY) } = {}) {
93
+ if (!id) throw new Error('usage: shapewall comments delete ID [--yes]')
94
+ const comment = getComment(config, board.id, id)
95
+ const page = board.pages.find((item) => item.id === comment.pageId)
96
+ const replies = comment.replies?.length || 0
97
+ const what = `#${comment.id} on ${page?.title || comment.pageId}${replies ? `, with its ${replies} repl${replies === 1 ? 'y' : 'ies'}` : ''}`
98
+ if (!flags.yes) {
99
+ if (!interactive) throw new Error(`comments delete removes ${what} for good. Add --yes to confirm (there is no terminal to ask in).`)
100
+ const excerpt = String(comment.body || '')
101
+ .replace(/\s+/g, ' ')
102
+ .trim()
103
+ .slice(0, 80)
104
+ const yes = await ask(`Delete ${what}${excerpt ? ` ("${excerpt}")` : ''}? This cannot be undone. [y/N] `)
105
+ if (!yes) {
106
+ out('Nothing deleted.')
107
+ return 1
108
+ }
109
+ }
110
+ await deleteComment(config, board.id, comment.id)
111
+ out(flags.json ? JSON.stringify({ deleted: comment.id }, null, 2) : `Deleted ${what}.`)
112
+ return 0
113
+ }
114
+
115
+ async function askYesNo(question) {
116
+ const { createInterface } = await import('node:readline/promises')
117
+ const rl = createInterface({ input: process.stdin, output: process.stderr })
118
+ try {
119
+ return /^y(es)?$/i.test((await rl.question(question)).trim())
120
+ } finally {
121
+ rl.close()
122
+ }
85
123
  }
package/src/cli/help.js CHANGED
@@ -109,6 +109,8 @@ export const SECTIONS = {
109
109
  comments reopen ID reopen a comment [--author NAME] [--json]
110
110
  comments reply ID add a reply --body TEXT [--author NAME (default agent)] [--json]
111
111
  comments status ID S agent status: ${AGENT_STATUSES.join(', ')} or clear [--note TEXT] [--author NAME] [--json]
112
+ comments delete ID delete a comment, its replies and its images for good; asks first
113
+ [--yes (do not ask; needed without a terminal)] [--json]
112
114
  --board ID board (default: the first); --remote URL for a hosted board (see push)`,
113
115
  events: ` events comment events from every process (the shared log); never claims anything
114
116
  --follow keep printing new events until Ctrl+C
@@ -122,7 +124,8 @@ export const SECTIONS = {
122
124
  --board ID | --env ID | --json`,
123
125
  watch: ` watch hand each new open comment to an agent (runs until Ctrl+C)
124
126
  --exec "CMD ARGS" run this command per comment (comment JSON on stdin; no shell)
125
- without --exec, print one JSON line per comment
127
+ without --exec, print one JSON line per comment and mark it queued
128
+ (the reader sets its status with "comments status"; --no-claim marks none)
126
129
  --concurrency N commands at once, 1 to 4 (default 1)
127
130
  --recapture recapture the comment page after a successful --exec (local only)
128
131
  --new-only skip comments that exist when the watch starts