shapewall 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +35 -1
  3. package/dist/agent/package-lock.json +2 -2
  4. package/dist/client/assets/BoardChat-CupOxioV.js +27 -0
  5. package/dist/client/assets/{BuzzDialog-CZdwIQLF.js → BuzzDialog-Ds7Thpfe.js} +1 -1
  6. package/dist/client/assets/ChecksPanel-BqrS02Ih.js +1 -0
  7. package/dist/client/assets/History-CQG3NQOC.js +1 -0
  8. package/dist/client/assets/{LocalSettings-B5gtfKEl.js → LocalSettings-CSNMhNyV.js} +1 -1
  9. package/dist/client/assets/{Management-BxEUZAmI.js → Management-CJVNAqAW.js} +1 -1
  10. package/dist/client/assets/QuickConnect-B-4pUgXH.js +1 -0
  11. package/dist/client/assets/{ShareDialog-CdVAreaw.js → ShareDialog-BouvNraR.js} +2 -2
  12. package/dist/client/assets/{app-update-dialog-BONq9YFp.js → app-update-dialog-rhaw0MRk.js} +1 -1
  13. package/dist/client/assets/{circle-x-BmT6vHKl.js → circle-x-PRxj7kPi.js} +1 -1
  14. package/dist/client/assets/index-CXtuJi1K.css +2 -0
  15. package/dist/client/assets/index-DKOCIQiq.js +37 -0
  16. package/dist/client/assets/{refresh-cw-ugt3cWKH.js → refresh-cw-aeOBDuGQ.js} +1 -1
  17. package/dist/client/assets/{square-_KG6tM5A.js → shield-check-DuPBJ6H_.js} +1 -1
  18. package/dist/client/assets/ui-Cg4TTrec.js +41 -0
  19. package/dist/client/build-info.json +1 -1
  20. package/dist/client/index.html +3 -3
  21. package/dist/client/sw.js +2 -2
  22. package/dist/console/assets/LocalAccountsApp-DOKZI6Lt.js +1 -0
  23. package/dist/console/assets/LocalConsole-DXzldLW9.js +1 -0
  24. package/dist/console/assets/{app-update-dialog-o4QY_jL9.js → app-update-dialog-CrqIMEwN.js} +1 -1
  25. package/dist/console/assets/console-76WovHlh.js +55 -0
  26. package/dist/console/assets/console-Fp4k9iyx.css +2 -0
  27. package/dist/console/build-info.json +1 -1
  28. package/dist/console/console.html +2 -2
  29. package/docs/agent-hardening.md +19 -0
  30. package/docs/agent-workflow.md +33 -0
  31. package/docs/agents.md +112 -0
  32. package/docs/config.md +41 -0
  33. package/docs/deployment.md +3 -0
  34. package/docs/hosted.md +10 -0
  35. package/docs/pull-requests.md +192 -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 +254 -25
  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 +238 -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 +33 -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,192 @@
1
+ # Capture on pull requests
2
+
3
+ Shapewall can capture your pages on every pull request and keep one comment on it up to date:
4
+
5
+ > **Shapewall: 4 of 23 pages changed**
6
+ >
7
+ > | Page | Screen size | Pixels changed |
8
+ > | ------------------ | ----------------- | -------------- |
9
+ > | Pricing (/pricing) | desktop 1440x2200 | 3.21% |
10
+ > | Pricing (/pricing) | phone 390x1800 | 5.80% |
11
+
12
+ It captures the base branch (before) and the pull request (after) with your normal config (pages, viewports, actions, setup and auth),
13
+ compares them page by page and viewport by viewport with the same pixel diff as compare mode, and links to the before, after and diff
14
+ images. Each push updates the same comment. When nothing changed, the comment says so in one collapsed line. When a page could not be
15
+ captured, the comment says which one and why. It is opt in: nothing runs until you commit the workflow, and it never fails the pull
16
+ request unless you ask it to.
17
+
18
+ ## Set it up
19
+
20
+ In the repository, with a `shapewall.config.json` at its root:
21
+
22
+ ```sh
23
+ npx shapewall init --ci
24
+ git add .github/workflows/shapewall.yml && git commit -m "Capture pages on pull requests"
25
+ ```
26
+
27
+ `init --ci` writes `.github/workflows/shapewall.yml` (it never replaces an existing one without `--ci --force`, and never touches the
28
+ config). The workflow needs one decision: where the "after" site comes from.
29
+
30
+ ### Build and serve mode (the default)
31
+
32
+ The job checks out the base branch and the pull request side by side and, in each, installs, builds and serves your site with the
33
+ commands in `ci.start`, waits for it to answer, and captures it:
34
+
35
+ ```json
36
+ {
37
+ "ci": {
38
+ "start": {
39
+ "install": ["npm", "ci"],
40
+ "build": ["npm", "run", "build"],
41
+ "serve": ["npm", "start"],
42
+ "url": "http://127.0.0.1:3000",
43
+ "timeout": 180000
44
+ }
45
+ }
46
+ }
47
+ ```
48
+
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
+ 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.
52
+
53
+ ### Preview URL mode
54
+
55
+ If your host builds a deploy preview for each pull request, capture that instead and skip the build. Set `SHAPEWALL_PREVIEW_URL` in
56
+ the workflow's `env`:
57
+
58
+ ```yaml
59
+ # Netlify-style deploy previews
60
+ SHAPEWALL_PREVIEW_URL: https://deploy-preview-${{ github.event.pull_request.number }}--YOUR-SITE.netlify.app
61
+ # Vercel branch URLs: the branch name, lower case, with "/" as "-"
62
+ SHAPEWALL_PREVIEW_URL: https://YOUR-PROJECT-git-${{ github.head_ref }}-YOUR-TEAM.vercel.app
63
+ ```
64
+
65
+ The job waits up to 10 minutes for the preview to answer, then compares it with `SHAPEWALL_BASE_URL`, or with the config's `baseUrl`
66
+ (often production) when that is empty. A preview that answers before the new build is live gives an old "after": if your host keeps
67
+ serving the previous deploy while it builds, wait in a step of your own until the page shows the new commit.
68
+
69
+ ## What the job does
70
+
71
+ The workflow has two jobs. The capture job builds and captures with a read-only token; the comment job writes the comment and
72
+ never sees the pull request's code.
73
+
74
+ **Capture** (`contents: read` only, no `GITHUB_TOKEN` in any step):
75
+
76
+ 1. Checks out the pull request (and the base branch in build and serve mode) into `head/` and `base/`, with
77
+ `persist-credentials: false`.
78
+ 2. Installs the pinned Shapewall and Playwright once, with `npm install --ignore-scripts` in the runner's temp folder, with no user
79
+ npm config: the pull request's `.npmrc` and `package.json` have no say. Every later step runs from that folder and calls the tools
80
+ by absolute path, pointing at the checkout with `--config` and `--checkout`.
81
+ 3. `shapewall ci enabled`: stops here when the config says `"ci": { "enabled": false }` or the title has `[skip shapewall]`.
82
+ 4. Installs Chromium with the Playwright version this Shapewall captures with, and its system libraries. The browser download is cached.
83
+ 5. Captures both sides (`shapewall ci capture` or `shapewall ci capture-compare --head-url`), then compares them.
84
+ 6. Uploads the result folder, with a copy of `shapewall.config.json`, as the `shapewall-ci` workflow artifact (kept 14 days).
85
+
86
+ **Comment** (`contents: read` and `pull-requests: write`): no checkout. It downloads the artifact, installs Shapewall the same way
87
+ and runs `shapewall ci comment` on the result, which it treats as data. Only this step gets `GITHUB_TOKEN`.
88
+
89
+ The workflow runs on `pull_request` only (never `pull_request_target`), one run per pull request (a new push cancels the one still
90
+ going) and a 25 minute capture timeout.
91
+
92
+ ## The result folder
93
+
94
+ `shapewall ci capture-compare --out DIR` writes:
95
+
96
+ - `summary.json`: schema `shapewall-ci-summary`, version 1. Totals (pages, changed pages, shots, changed, unchanged and failed shots,
97
+ new and removed pages), then each page and viewport: `status` (`changed`, `unchanged`, `new`, `removed` or `failed`), `changed`,
98
+ `ratio` (share of pixels changed), `changedPixels`, `dimensionsChanged` with both sizes, image paths, the error and any capture
99
+ warnings. Also `failures` and `warnings` lists.
100
+ - `summary.md`: the comment body.
101
+ - `images/<page>.<viewport>/`: `before.png`, `after.png`, `diff.png` (the after shot faded, changed pixels in red) and a 320 pixel wide
102
+ `.thumb.png` of each, for changed shots only.
103
+
104
+ A shot counts as changed when its share of changed pixels reaches `ci.threshold` (default 0.001, that is 0.1%) or its size changed.
105
+ A page that answers 404 before and loads after is a new page; the other way round, a removed page.
106
+
107
+ You can run it on your own machine too:
108
+
109
+ ```sh
110
+ npx shapewall ci capture-compare --base-url https://www.example.com --head-url http://localhost:3000 --out shapewall-ci
111
+ npx shapewall ci capture-compare --base-dir before/ --head-dir after/ --out shapewall-ci # two capture folders
112
+ ```
113
+
114
+ A capture folder is what `shapewall capture` writes (`.shapewall/<board>/captures/`) or what `shapewall ci capture --url URL --out DIR`
115
+ writes. `ci.ignore` is applied while capturing, so it has no effect on folders captured without it.
116
+
117
+ ## Images in the comment
118
+
119
+ A pull request comment cannot show files from a workflow artifact, so by default the comment links to the artifact (a zip download
120
+ for anyone who can see the run). Nothing is committed and no other service is used.
121
+
122
+ With `"ci": { "images": "branch" }`, the comment shows thumbnails inline: the job commits the images to an orphan branch named
123
+ `shapewall-ci` (under `pr-<number>/<commit>/`) and embeds them from it. The trade-offs:
124
+
125
+ - Public repositories only. Shapewall checks and falls back to links in a private repository, because the raw URLs would expose the
126
+ images.
127
+ - The images are public and stay in the branch history until you delete the branch. Delete it any time; old comments then lose their
128
+ pictures.
129
+ - The comment job needs `contents: write` in its `permissions` to push the branch. Without it, the comment falls back to links and
130
+ says why.
131
+
132
+ ## Turning it off
133
+
134
+ - For good: delete `.github/workflows/shapewall.yml`.
135
+ - For a while, from the config: `"ci": { "enabled": false }`. The job then stops after the check step, before installing anything.
136
+ - For one pull request: put `[skip shapewall]` in its title. The job is skipped (the title is read when the run starts, so edit it
137
+ before you push).
138
+
139
+ ## Pull requests from forks
140
+
141
+ GitHub gives a fork's pull request a read-only token, so it cannot comment. Shapewall sees that (from the event, or a 403 when it
142
+ writes) and puts the summary in the job summary (the run's page) instead, without failing. The workflow uses `pull_request`, so a
143
+ fork's code never runs with your secrets or a write token.
144
+
145
+ ## Costs in CI minutes
146
+
147
+ Most of a run is setup: the Chromium download (about a minute the first time, cached after that) plus the system libraries, then, in
148
+ build and serve mode, two installs and two builds. Capturing is quick: roughly one to three seconds per page and viewport, with the
149
+ config's `concurrency` shots at a time. Keep it small with `ci.pages` (an allow-list), `ci.viewports` and `ci.maxPages` (default
150
+ 50). Concurrency cancels the run of an older push.
151
+
152
+ ## Flaky shots
153
+
154
+ The capture is already deterministic where it can be: fixed viewport sizes, light color scheme, reduced motion, images awaited, and
155
+ for pull requests also web fonts loaded and the text caret hidden. What is left is usually your content:
156
+
157
+ - Clocks, dates, counters, ads, random avatars: list them in `ci.ignore` (CSS selectors). They are hidden (`visibility: hidden`, so the
158
+ layout stays put) before the shot, on both sides.
159
+ - Third-party embeds and analytics: block them with `block` in the config.
160
+ - Animations a reduced-motion setting does not stop: wait for them with a `waitFor` or `waitForFunction` action on the page.
161
+ - Small rendering noise: raise `ci.threshold`, for example to 0.005.
162
+
163
+ ## Privacy
164
+
165
+ The comment holds page titles, paths, screen sizes and percentages. The images are in the workflow artifact, which anyone who can see
166
+ the repository's runs can download: in a public repository, that is everyone. With `images: "branch"` they are also in a public
167
+ branch. Do not capture pages with private data this way in a public repository. Page titles and errors are written into the comment as
168
+ plain text: markdown, HTML and @mentions in them are neutralised.
169
+
170
+ ## Security notes
171
+
172
+ - `ci.start` runs only from `shapewall ci capture --allow-start`, and only inside a CI job (`GITHUB_ACTIONS` or `CI` set to `true`). A
173
+ config in a cloned repository never makes a Shapewall command on your own machine run something.
174
+ - Each command is an argv array: a string is refused (it would need a shell), as are paths (a program inside the repository), shells
175
+ and launchers such as `sh`, `bash`, `env`, `sudo` and `xargs` that would turn the array back into a shell string. The commands get the
176
+ job's environment without `GITHUB_TOKEN` and the Actions runtime tokens.
177
+ - The token goes only to `api.github.com`, or to an API URL the environment names (`SHAPEWALL_GITHUB_API_URL`, or `GITHUB_API_URL`,
178
+ which the runner sets on GitHub Enterprise Server). An `apiUrl` that only the config names gets no token, and redirects are refused.
179
+ - Pull request text (title, branch name) never reaches a `run:` line of the workflow: it is used in `if:` conditions and `env` only.
180
+
181
+ ## Commands
182
+
183
+ ```text
184
+ shapewall ci capture-compare --base-url URL --head-url URL | --base-dir DIR --head-dir DIR
185
+ [--out DIR] [--threshold RATIO] [--max-pages N] [--fail-on-change] [--json]
186
+ shapewall ci capture --out DIR --url URL | --allow-start [--checkout DIR]
187
+ shapewall ci comment [--dir DIR] [--artifact-url URL] [--repo OWNER/NAME --pull N] [--json]
188
+ shapewall ci enabled writes enabled=true|false to $GITHUB_OUTPUT
189
+ shapewall ci wait --url URL [--timeout SECONDS]
190
+ ```
191
+
192
+ `capture-compare` exits 0 whatever it found (3 with `--fail-on-change` when something changed, 1 on a usage or config error).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shapewall",
3
- "version": "0.2.4",
3
+ "version": "0.3.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",
@@ -46,6 +46,7 @@
46
46
  "docs/local-accounts.md",
47
47
  "docs/notifications.md",
48
48
  "docs/page-checks.md",
49
+ "docs/pull-requests.md",
49
50
  "docs/performance.md",
50
51
  "docs/starter-agent.md",
51
52
  "docs/updates.md",
@@ -493,9 +493,11 @@ function shownPath(root, file) {
493
493
 
494
494
  // One agent process and its ACP session (one chat thread).
495
495
  class AcpProcess {
496
- constructor({ argv, label, env, sandbox, limits, log, thread, onGone, mcpServers = [] }) {
496
+ constructor({ argv, label, env, sandbox, limits, log, thread, onGone, mcpServers = [], extraEnv = {} }) {
497
497
  Object.assign(this, { argv, label, sandbox, limits, log, thread, onGone, mcpServers })
498
- this.env = agentEnv(env)
498
+ // `extraEnv`: set by Shapewall itself, never by the agent (branch mode's
499
+ // GIT_CEILING_DIRECTORIES), for the agent and the terminals it runs.
500
+ this.env = { ...agentEnv(env), ...extraEnv }
499
501
  this.root = sandbox.root
500
502
  this.state = 'starting'
501
503
  this.stderr = ''
@@ -1275,6 +1277,11 @@ export function createAcpBackend(
1275
1277
  ) {
1276
1278
  const limit = { ...ACP_DEFAULTS, ...limits }
1277
1279
  const sandbox = createSandbox({ root, protect, sensitivePaths })
1280
+ // A turn with a working folder of its own (agent branch mode: a worktree)
1281
+ // gets a sandbox rooted there, made for that turn's process only.
1282
+ const sandboxFor = (workdir) =>
1283
+ workdir ? createSandbox({ root: workdir.root, protect: workdir.protect || [], sensitivePaths: workdir.sensitivePaths || [] }) : sandbox
1284
+ const rootOf = (workdir) => (workdir ? fs.realpathSync(workdir.root) : sandbox.root)
1278
1285
  const processes = new Map()
1279
1286
  // Agents still starting (initialize, session/new): counted and stopped too.
1280
1287
  const starting = new Set()
@@ -1293,13 +1300,14 @@ export function createAcpBackend(
1293
1300
  idle[0].kill('evicted')
1294
1301
  }
1295
1302
 
1296
- const start = async (thread, signal, { evict = true } = {}) => {
1303
+ const start = async (thread, signal, { evict = true, workdir = null } = {}) => {
1297
1304
  evictFor(evict)
1298
1305
  const agent = new AcpProcess({
1299
1306
  argv: settings.acp.argv,
1300
1307
  label: settings.label,
1301
1308
  env,
1302
- sandbox,
1309
+ sandbox: sandboxFor(workdir),
1310
+ extraEnv: workdir?.env || {},
1303
1311
  limits: limit,
1304
1312
  log,
1305
1313
  thread,
@@ -1352,15 +1360,24 @@ export function createAcpBackend(
1352
1360
  // `choices`: the composer's options for this chat ({ configId: value },
1353
1361
  // owner turns only), applied before the prompt. The turn then reports
1354
1362
  // the model and thinking level it runs with (the answer's meta line).
1355
- async *stream({ messages, signal, thread = 'default', choices = null }) {
1363
+ // `workdir`: { root, env, protect, sensitivePaths } for a turn that works
1364
+ // in a folder of its own (branch mode): the thread's agent runs there,
1365
+ // started afresh when its session was in another folder.
1366
+ async *stream({ messages, signal, thread = 'default', choices = null, workdir = null }) {
1356
1367
  if (signal?.aborted) return
1357
1368
  await preparing.get(thread)?.catch(() => {})
1358
1369
  let agent = processes.get(thread)
1359
1370
  if (agent?.turn) await agent.settled()
1360
1371
  agent = processes.get(thread)
1372
+ if (agent && agent.state === 'ready' && agent.root !== rootOf(workdir)) {
1373
+ agent.kill('workdir')
1374
+ await agent.settled()
1375
+ await agent.stoppingPromise
1376
+ agent = null
1377
+ }
1361
1378
  if (!agent || agent.state !== 'ready') {
1362
1379
  yield { type: 'status', text: `Starting ${settings.label}` }
1363
- agent = await start(thread, signal)
1380
+ agent = await start(thread, signal, { workdir })
1364
1381
  }
1365
1382
  if (signal?.aborted) {
1366
1383
  agent.kill('aborted')
@@ -0,0 +1,45 @@
1
+ // Batch fixes: several open comments fixed one after another, each as an
2
+ // ordinary Fix with agent (its own run record, approvals and Undo, and in
3
+ // branch mode its own branch). Opt-in per project, capped.
4
+ //
5
+ // The setting `agent.batchFixes` ({ enabled, max }) lives in
6
+ // shapewall.config.json or the saved agent settings (agents.json, which win);
7
+ // `max` is at most BATCH_MAX_CEILING.
8
+ //
9
+ // The queue (createBatchQueue) knows nothing about HTTP or agents: routes.js
10
+ // hands it `runItem`, which starts one fix through the single-fix route
11
+ // itself. One batch per board at a time; items run in order, one at a time.
12
+ // It stops when the person cancels (the running item is stopped the normal
13
+ // way, the rest are skipped) or after two failures in a row; an approval
14
+ // left unanswered makes it wait, shown as `waiting` with the card.
15
+
16
+ import { userAgentEntry } from './user-settings.js'
17
+ import { BATCH_DEFAULTS, BATCH_MAX_CEILING, cleanBatchFixes } from './batch-queue.js'
18
+
19
+ export { BATCH_DEFAULTS, BATCH_FAILURES_STOP, BATCH_MAX_CEILING, BatchError, cleanBatchFixes, createBatchQueue } from './batch-queue.js'
20
+
21
+ const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
22
+
23
+ // `agent.batchFixes` in shapewall.config.json, only when given.
24
+ export function validateBatchConfig(raw, problems) {
25
+ if (!isObject(raw) || raw.batchFixes === undefined) return {}
26
+ const { value, problems: found } = cleanBatchFixes(raw.batchFixes, 'agent.batchFixes')
27
+ problems.push(...found)
28
+ return value ? { batchFixes: value } : {}
29
+ }
30
+
31
+ // What is in effect: { enabled, max, sources: { enabled, max } } (settings | config | null).
32
+ export function batchFixSettings(config, env = process.env) {
33
+ const repo = isObject(config.agent?.batchFixes) ? config.agent.batchFixes : {}
34
+ const saved = (config.dir ? userAgentEntry(config.dir, env).entry?.batchFixes : null) || {}
35
+ const pick = (key) =>
36
+ saved[key] !== undefined ? [saved[key], 'settings'] : repo[key] !== undefined ? [repo[key], 'config'] : [BATCH_DEFAULTS[key], null]
37
+ const [enabled, enabledSource] = pick('enabled')
38
+ const [max, maxSource] = pick('max')
39
+ return {
40
+ enabled: enabled === true,
41
+ max: Math.min(BATCH_MAX_CEILING, Math.max(1, Number.isInteger(max) ? max : BATCH_DEFAULTS.max)),
42
+ ceiling: BATCH_MAX_CEILING,
43
+ sources: { enabled: enabledSource, max: maxSource },
44
+ }
45
+ }
@@ -0,0 +1,204 @@
1
+ // The batch queue and the batchFixes value check, with nothing from Node:
2
+ // the server (batch-fixes.js, routes.js) and the demo backend
3
+ // (client/src/demo/backend/batch.js) run the same queue.
4
+
5
+ export const BATCH_MAX_CEILING = 20
6
+ export const BATCH_DEFAULTS = Object.freeze({ enabled: false, max: 5 })
7
+ export const BATCH_FAILURES_STOP = 2
8
+ const KEEP_FINISHED_MS = 24 * 60 * 60 * 1000
9
+
10
+ const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
11
+
12
+ // { enabled?, max? } checked: { value, problems }. Unknown keys are refused.
13
+ export function cleanBatchFixes(raw, label = 'batchFixes') {
14
+ const problems = []
15
+ if (!isObject(raw)) return { value: null, problems: [`${label}: an object such as { "enabled": true, "max": 5 }`] }
16
+ const value = {}
17
+ for (const key of Object.keys(raw)) if (!['enabled', 'max'].includes(key)) problems.push(`${label}.${key}: not a setting`)
18
+ if (raw.enabled !== undefined) {
19
+ if (typeof raw.enabled !== 'boolean') problems.push(`${label}.enabled: true or false`)
20
+ else value.enabled = raw.enabled
21
+ }
22
+ if (raw.max !== undefined) {
23
+ if (!Number.isInteger(raw.max) || raw.max < 1 || raw.max > BATCH_MAX_CEILING)
24
+ problems.push(`${label}.max: a whole number from 1 to ${BATCH_MAX_CEILING}`)
25
+ else value.max = raw.max
26
+ }
27
+ return { value: problems.length ? null : value, problems }
28
+ }
29
+
30
+ export class BatchError extends Error {
31
+ constructor(status, code, message) {
32
+ super(message)
33
+ this.status = status
34
+ this.code = code
35
+ }
36
+ }
37
+
38
+ // `runItem(boardId, commentId, { onApproval })` starts one fix and returns
39
+ // { done: Promise<{ fixed, message? }>, cancel() }. `onApproval(card|null)`:
40
+ // the running fix waits for (or no longer waits for) the person's OK.
41
+ // `onChange(boardId)`: the batch's state changed (routes.js tells the
42
+ // open views). `now`: the clock, for tests.
43
+ export function createBatchQueue({ runItem, onChange = () => {}, now = () => Date.now(), log = () => {} }) {
44
+ const batches = new Map()
45
+ let serial = 0
46
+ let closed = false
47
+
48
+ const changed = (batch) => {
49
+ batch.updatedAt = new Date(now()).toISOString()
50
+ try {
51
+ onChange(batch.boardId)
52
+ } catch (error) {
53
+ log(`batch fixes: ${error.message}`)
54
+ }
55
+ }
56
+ const view = (batch) =>
57
+ batch && {
58
+ id: batch.id,
59
+ boardId: batch.boardId,
60
+ state: batch.state,
61
+ stopReason: batch.stopReason,
62
+ agent: batch.agent,
63
+ max: batch.max,
64
+ requested: batch.requested,
65
+ startedAt: batch.startedAt,
66
+ updatedAt: batch.updatedAt,
67
+ finishedAt: batch.finishedAt,
68
+ current: batch.items.findIndex((item) => item.state === 'running'),
69
+ waiting: batch.waiting,
70
+ items: batch.items.map((item) => ({ ...item })),
71
+ counts: Object.fromEntries(
72
+ ['waiting', 'running', 'fixed', 'failed', 'skipped'].map((state) => [
73
+ state,
74
+ batch.items.filter((item) => item.state === state).length,
75
+ ]),
76
+ ),
77
+ }
78
+ const running = (batch) => batch && ['running', 'waiting'].includes(batch.state)
79
+
80
+ const finish = (batch, state, stopReason = null) => {
81
+ for (const item of batch.items) if (item.state === 'waiting') item.state = 'skipped'
82
+ batch.state = state
83
+ batch.stopReason = stopReason
84
+ batch.waiting = null
85
+ batch.finishedAt = new Date(now()).toISOString()
86
+ changed(batch)
87
+ }
88
+
89
+ const loop = async (batch) => {
90
+ let failures = 0
91
+ for (const item of batch.items) {
92
+ if (batch.cancelled || closed) break
93
+ item.state = 'running'
94
+ item.startedAt = new Date(now()).toISOString()
95
+ changed(batch)
96
+ let result
97
+ try {
98
+ const started = await runItem(batch.boardId, item.commentId, {
99
+ onApproval: (card) => {
100
+ batch.waiting = card ? { commentId: item.commentId, threadId: `comment-${item.commentId}`, card } : null
101
+ batch.state = card ? 'waiting' : 'running'
102
+ changed(batch)
103
+ },
104
+ })
105
+ batch.cancelCurrent = started.cancel
106
+ if (batch.cancelled) started.cancel()
107
+ result = await started.done
108
+ } catch (error) {
109
+ result = { fixed: false, message: error.message || 'The fix did not start.' }
110
+ } finally {
111
+ batch.cancelCurrent = null
112
+ batch.waiting = null
113
+ if (batch.state === 'waiting') batch.state = 'running'
114
+ }
115
+ item.finishedAt = new Date(now()).toISOString()
116
+ if (result?.skipped) {
117
+ item.state = 'skipped'
118
+ item.message = result.message || null
119
+ } else if (batch.cancelled) {
120
+ item.state = result?.fixed ? 'fixed' : 'skipped'
121
+ item.message = result?.fixed ? null : 'Stopped when the batch was cancelled.'
122
+ } else {
123
+ item.state = result?.fixed ? 'fixed' : 'failed'
124
+ item.message = result?.message || null
125
+ }
126
+ changed(batch)
127
+ if (item.state === 'failed') failures += 1
128
+ else if (item.state === 'fixed') failures = 0
129
+ if (failures >= BATCH_FAILURES_STOP) return finish(batch, 'stopped', 'failures')
130
+ }
131
+ if (batch.cancelled || closed) return finish(batch, 'cancelled', 'cancelled')
132
+ finish(batch, 'done')
133
+ }
134
+
135
+ return {
136
+ // { boardId, commentIds (checked, in order), max, agent }: the batch view.
137
+ // Ids beyond `max` are not queued (`requested` says how many were asked).
138
+ start({ boardId, commentIds, max, agent = null }) {
139
+ if (closed) throw new BatchError(503, 'stopping', 'The server is stopping.')
140
+ if (running(batches.get(boardId)))
141
+ throw new BatchError(409, 'batch_running', 'A batch of fixes is already running on this board. Wait for it or cancel it first.')
142
+ if (!Array.isArray(commentIds) || !commentIds.length) throw new BatchError(400, 'bad_batch', 'Choose at least one open comment.')
143
+ const ids = [...new Set(commentIds)]
144
+ const batch = {
145
+ id: `batch-${now().toString(36)}-${++serial}`,
146
+ boardId,
147
+ state: 'running',
148
+ stopReason: null,
149
+ agent,
150
+ max,
151
+ requested: ids.length,
152
+ startedAt: new Date(now()).toISOString(),
153
+ updatedAt: null,
154
+ finishedAt: null,
155
+ waiting: null,
156
+ cancelled: false,
157
+ cancelCurrent: null,
158
+ items: ids.slice(0, max).map((commentId) => ({ commentId, state: 'waiting', message: null, startedAt: null, finishedAt: null })),
159
+ }
160
+ batches.set(boardId, batch)
161
+ changed(batch)
162
+ batch.promise = loop(batch).catch((error) => {
163
+ log(`batch fixes: ${error.stack || error.message}`)
164
+ finish(batch, 'stopped', 'error')
165
+ })
166
+ return view(batch)
167
+ },
168
+ // The board's batch (running, or the last one for a day), or null.
169
+ state(boardId) {
170
+ const batch = batches.get(boardId)
171
+ if (batch && !running(batch) && batch.finishedAt && now() - Date.parse(batch.finishedAt) > KEEP_FINISHED_MS) {
172
+ batches.delete(boardId)
173
+ return null
174
+ }
175
+ return view(batch) || null
176
+ },
177
+ running: (boardId) => running(batches.get(boardId)),
178
+ anyRunning: () => [...batches.values()].some(running),
179
+ // Cancel: the running item is stopped the normal way, the rest are skipped.
180
+ cancel(boardId) {
181
+ const batch = batches.get(boardId)
182
+ if (!running(batch)) throw new BatchError(409, 'no_batch', 'No batch of fixes is running on this board.')
183
+ batch.cancelled = true
184
+ batch.cancelCurrent?.()
185
+ changed(batch)
186
+ return view(batch)
187
+ },
188
+ // The person dismissed a finished batch's summary.
189
+ clear(boardId) {
190
+ if (running(batches.get(boardId))) throw new BatchError(409, 'batch_running', 'Cancel the batch first.')
191
+ batches.delete(boardId)
192
+ },
193
+ // Resolves when the board's batch has finished (tests, shutdown).
194
+ settled: (boardId) => batches.get(boardId)?.promise || Promise.resolve(),
195
+ close() {
196
+ closed = true
197
+ for (const batch of batches.values()) {
198
+ if (!running(batch)) continue
199
+ batch.cancelled = true
200
+ batch.cancelCurrent?.()
201
+ }
202
+ },
203
+ }
204
+ }