shapewall 0.2.3 → 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.
- package/CHANGELOG.md +48 -0
- package/README.md +35 -1
- package/dist/agent/package-lock.json +2 -2
- package/dist/client/assets/BoardChat-CupOxioV.js +27 -0
- package/dist/client/assets/{BuzzDialog-CZdwIQLF.js → BuzzDialog-Ds7Thpfe.js} +1 -1
- package/dist/client/assets/ChecksPanel-BqrS02Ih.js +1 -0
- package/dist/client/assets/History-CQG3NQOC.js +1 -0
- package/dist/client/assets/{LocalSettings-CvlVtNY_.js → LocalSettings-CSNMhNyV.js} +1 -1
- package/dist/client/assets/{Management-DOJkFY_o.js → Management-CJVNAqAW.js} +1 -1
- package/dist/client/assets/QuickConnect-B-4pUgXH.js +1 -0
- package/dist/client/assets/{ShareDialog-CdVAreaw.js → ShareDialog-BouvNraR.js} +2 -2
- package/dist/client/assets/{app-update-dialog-Dox9-LWv.js → app-update-dialog-rhaw0MRk.js} +1 -1
- package/dist/client/assets/{circle-x-BmT6vHKl.js → circle-x-PRxj7kPi.js} +1 -1
- package/dist/client/assets/index-CXtuJi1K.css +2 -0
- package/dist/client/assets/index-DKOCIQiq.js +37 -0
- package/dist/client/assets/{refresh-cw-ugt3cWKH.js → refresh-cw-aeOBDuGQ.js} +1 -1
- package/dist/client/assets/{square-_KG6tM5A.js → shield-check-DuPBJ6H_.js} +1 -1
- package/dist/client/assets/ui-Cg4TTrec.js +41 -0
- package/dist/client/build-info.json +1 -1
- package/dist/client/index.html +3 -3
- package/dist/client/sw.js +2 -2
- package/dist/console/assets/LocalAccountsApp-DOKZI6Lt.js +1 -0
- package/dist/console/assets/LocalConsole-DXzldLW9.js +1 -0
- package/dist/console/assets/app-update-dialog-CrqIMEwN.js +1 -0
- package/dist/console/assets/console-76WovHlh.js +55 -0
- package/dist/console/assets/console-Fp4k9iyx.css +2 -0
- package/dist/console/build-info.json +1 -1
- package/dist/console/console.html +2 -2
- package/docs/agent-hardening.md +19 -0
- package/docs/agent-workflow.md +33 -0
- package/docs/agents.md +112 -0
- package/docs/config.md +41 -0
- package/docs/deployment.md +3 -0
- package/docs/design-system.md +13 -5
- package/docs/hosted.md +10 -0
- package/docs/journeys.md +13 -1
- package/docs/pull-requests.md +192 -0
- package/package.json +2 -1
- package/src/agent/backends/acp.js +35 -6
- package/src/agent/batch-fixes.js +45 -0
- package/src/agent/batch-queue.js +204 -0
- package/src/agent/branch-mode.js +753 -0
- package/src/agent/config.js +6 -0
- package/src/agent/fix-prompt.js +5 -0
- package/src/agent/manage.js +1 -1
- package/src/agent/routes.js +901 -186
- package/src/agent/run.js +8 -1
- package/src/agent/settings-events.js +103 -0
- package/src/agent/settings-routes.js +92 -2
- package/src/agent/starter/worktree.js +254 -25
- package/src/agent/threads.js +2 -7
- package/src/agent/tools.js +51 -0
- package/src/agent/user-settings.js +33 -2
- package/src/ci/capture.js +103 -0
- package/src/ci/compare.js +267 -0
- package/src/ci/github.js +307 -0
- package/src/ci/images.js +76 -0
- package/src/ci/settings.js +211 -0
- package/src/ci/start.js +148 -0
- package/src/ci/summary.js +262 -0
- package/src/ci/workflow.js +238 -0
- package/src/cli/args.js +24 -1
- package/src/cli/ci.js +229 -0
- package/src/cli/help.js +23 -1
- package/src/cli/init.js +33 -1
- package/src/cli.js +6 -2
- package/src/comment-drawing.js +161 -0
- package/src/comment-fields.js +51 -0
- package/src/comment-media.js +528 -0
- package/src/config.js +7 -0
- package/src/doctor.js +23 -0
- package/src/export.js +8 -0
- package/src/feedback.js +89 -12
- package/src/github.js +3 -3
- package/src/hosted/admin.js +36 -4
- package/src/hosted/app.js +5 -0
- package/src/hosted/board-routes.js +63 -7
- package/src/hosted/clean-worker.js +22 -4
- package/src/hosted/cleaner.js +4 -1
- package/src/hosted/comment-files.js +200 -0
- package/src/hosted/comments.js +68 -15
- package/src/hosted/db.js +32 -0
- package/src/hosted/guest-view.js +9 -0
- package/src/hosted/import.js +213 -18
- package/src/hosted/operator.js +3 -1
- package/src/hosted/projects.js +3 -2
- package/src/hosted/push.js +6 -3
- package/src/hosted/retention.js +18 -0
- package/src/hosted/tenancy.js +1 -0
- package/src/hosted/token-api.js +110 -9
- package/src/image-sniff.js +11 -0
- package/src/mcp.js +48 -3
- package/src/remote/remote-mcp.js +2 -2
- package/src/remote/remote.js +6 -2
- package/src/remote/share.js +77 -7
- package/src/server/app.js +18 -1
- package/src/store.js +119 -33
- package/src/watch.js +4 -0
- package/dist/client/assets/BoardChat-C88k4s-W.js +0 -28
- package/dist/client/assets/ChecksPanel-B54chcLA.js +0 -1
- package/dist/client/assets/History-CVVuuxUK.js +0 -1
- package/dist/client/assets/QuickConnect-D40mj4Ry.js +0 -1
- package/dist/client/assets/index-CwvFfwU0.js +0 -29
- package/dist/client/assets/index-UIYSPHoh.css +0 -2
- package/dist/client/assets/ui-BAGBTB_P.js +0 -41
- package/dist/console/assets/LocalAccountsApp-4MtW1QlZ.js +0 -1
- package/dist/console/assets/LocalConsole-CgKqYa8i.js +0 -1
- package/dist/console/assets/app-update-dialog-S2Yyc7Pw.js +0 -1
- package/dist/console/assets/console-BPmBRIoz.js +0 -51
- package/dist/console/assets/console-DgVrGRMD.css +0 -2
package/docs/hosted.md
CHANGED
|
@@ -331,6 +331,16 @@ at the first refused request instead of failing quietly; opening a board you can
|
|
|
331
331
|
this board" page (still a 404), with "Sign in as someone else" and "Back to your workspaces". Guests' comments are text only: an
|
|
332
332
|
`@agent` in one is not a mention.
|
|
333
333
|
|
|
334
|
+
Comments and replies can carry up to 4 images (PNG, JPEG, WebP or GIF, 5 MB each) and a drawing (boxes, arrows and pen strokes), as
|
|
335
|
+
on a local board. The server checks each image by its bytes and cleans it in the same worker pool as pushed files (PNGs re-encoded,
|
|
336
|
+
metadata stripped from the others), then stores it in the database, not in the board folder, so a push never removes it. Images count
|
|
337
|
+
against the workspace's storage quota (a comment over it is refused with `quota_exceeded`, and pushes count them too) and are deleted
|
|
338
|
+
with their comment, project or workspace. They are served only to people who can see that comment, as images with `nosniff` and a
|
|
339
|
+
sandbox CSP, never as a page. Share link guests can draw but cannot attach images. Agents get each image and the drawing rendered on
|
|
340
|
+
its capture (`files.images`, `files.markup`) as token API URLs. The workspace export holds the images (`comment-files/`) and lists
|
|
341
|
+
them in `comments.json`; `shapewall share` moves a local comment's images (one request each, cleaned and counted like uploads) and
|
|
342
|
+
its drawing. Backups hold them, since they are in the database.
|
|
343
|
+
|
|
334
344
|
## Agents
|
|
335
345
|
|
|
336
346
|
```sh
|
package/docs/journeys.md
CHANGED
|
@@ -91,7 +91,7 @@ page id, any step after a page can be a fork:
|
|
|
91
91
|
|
|
92
92
|
## Journeys made on the board
|
|
93
93
|
|
|
94
|
-
Pick **New journey** in the
|
|
94
|
+
Pick **New journey** in the toolbar's **Views** menu or the command palette (on a phone: the **...** menu), then click pages in the order people visit them. Name the
|
|
95
95
|
journey and save. Journeys made this way are stored in `.shapewall/<board>/journeys.json`, with the same atomic writes and file lock as
|
|
96
96
|
comments, and can be edited or deleted from the journey bar. If a page leaves the config, its steps drop out of the journey (a fork left
|
|
97
97
|
with one branch becomes that branch's steps).
|
|
@@ -117,6 +117,18 @@ The same structure is in `shapewall journeys --json`, the MCP tool `list_journey
|
|
|
117
117
|
|
|
118
118
|
## Stepping through
|
|
119
119
|
|
|
120
|
+
Open a journey from any of these; they all show the same one:
|
|
121
|
+
|
|
122
|
+
- **Views** in the toolbar: its **Journeys** group lists every journey with its steps (or paths), and **None** shows all pages again.
|
|
123
|
+
With more than eight, the list scrolls and has a filter. While a journey is open the button shows its name, and its **x** leaves it.
|
|
124
|
+
- The sidebar: expanded, its **Pages | Journeys** switch; the **Journeys** tab lists **None** (show all pages) and every journey with
|
|
125
|
+
its steps, the open one highlighted, a filter past eight and **New journey** where you can make one. The tab you chose is kept in this
|
|
126
|
+
browser; opening a journey elsewhere does not switch it, but the **Journeys** tab shows a dot while one is open. Collapsed, the
|
|
127
|
+
**Journeys** icon (with the same dot) opens that list beside the rail.
|
|
128
|
+
- The command palette (Ctrl/Cmd+K): type the journey's name.
|
|
129
|
+
- **J** opens the next journey, **Shift+J** the previous one; past the last one the board shows all pages again.
|
|
130
|
+
- On a phone: the **...** menu's **Journeys** group.
|
|
131
|
+
|
|
120
132
|
Selecting a journey highlights its pages with numbered badges, draws arrows between consecutive steps and fades everything else. The
|
|
121
133
|
journey bar steps through it:
|
|
122
134
|
|
|
@@ -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.
|
|
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",
|
|
@@ -309,6 +309,13 @@ async function reserveProcessSlot(processPool, agent, signal, { evict = true } =
|
|
|
309
309
|
if (signal?.aborted) throw new AgentError('agent_stopped', 'The agent start was cancelled.', 409)
|
|
310
310
|
if (processPool.epoch !== epoch) throw new AgentError('agent_start', 'The server is stopping.')
|
|
311
311
|
processPool.agents.add(agent)
|
|
312
|
+
processPool.changed?.()
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
// The pool's agents changed (one started, became ready or went away): the
|
|
316
|
+
// open views refetch the agents' states (routes.js processPool.changed).
|
|
317
|
+
function poolChanged(processPool) {
|
|
318
|
+
processPool?.changed?.()
|
|
312
319
|
}
|
|
313
320
|
|
|
314
321
|
// A queue a turn's events go into and the backend's stream reads from.
|
|
@@ -486,9 +493,11 @@ function shownPath(root, file) {
|
|
|
486
493
|
|
|
487
494
|
// One agent process and its ACP session (one chat thread).
|
|
488
495
|
class AcpProcess {
|
|
489
|
-
constructor({ argv, label, env, sandbox, limits, log, thread, onGone, mcpServers = [] }) {
|
|
496
|
+
constructor({ argv, label, env, sandbox, limits, log, thread, onGone, mcpServers = [], extraEnv = {} }) {
|
|
490
497
|
Object.assign(this, { argv, label, sandbox, limits, log, thread, onGone, mcpServers })
|
|
491
|
-
|
|
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 }
|
|
492
501
|
this.root = sandbox.root
|
|
493
502
|
this.state = 'starting'
|
|
494
503
|
this.stderr = ''
|
|
@@ -1268,6 +1277,11 @@ export function createAcpBackend(
|
|
|
1268
1277
|
) {
|
|
1269
1278
|
const limit = { ...ACP_DEFAULTS, ...limits }
|
|
1270
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)
|
|
1271
1285
|
const processes = new Map()
|
|
1272
1286
|
// Agents still starting (initialize, session/new): counted and stopped too.
|
|
1273
1287
|
const starting = new Set()
|
|
@@ -1286,13 +1300,14 @@ export function createAcpBackend(
|
|
|
1286
1300
|
idle[0].kill('evicted')
|
|
1287
1301
|
}
|
|
1288
1302
|
|
|
1289
|
-
const start = async (thread, signal, { evict = true } = {}) => {
|
|
1303
|
+
const start = async (thread, signal, { evict = true, workdir = null } = {}) => {
|
|
1290
1304
|
evictFor(evict)
|
|
1291
1305
|
const agent = new AcpProcess({
|
|
1292
1306
|
argv: settings.acp.argv,
|
|
1293
1307
|
label: settings.label,
|
|
1294
1308
|
env,
|
|
1295
|
-
sandbox,
|
|
1309
|
+
sandbox: sandboxFor(workdir),
|
|
1310
|
+
extraEnv: workdir?.env || {},
|
|
1296
1311
|
limits: limit,
|
|
1297
1312
|
log,
|
|
1298
1313
|
thread,
|
|
@@ -1300,6 +1315,7 @@ export function createAcpBackend(
|
|
|
1300
1315
|
onGone: (item) => {
|
|
1301
1316
|
if (item.stopped || !item.pid) processPool?.agents.delete(item)
|
|
1302
1317
|
if (processes.get(item.thread) === item) processes.delete(item.thread)
|
|
1318
|
+
poolChanged(processPool)
|
|
1303
1319
|
},
|
|
1304
1320
|
})
|
|
1305
1321
|
if (closed) throw new AgentError('agent_start', 'The server is stopping.')
|
|
@@ -1320,6 +1336,8 @@ export function createAcpBackend(
|
|
|
1320
1336
|
} finally {
|
|
1321
1337
|
starting.delete(agent)
|
|
1322
1338
|
if (agent.stopped || !agent.pid) processPool?.agents.delete(agent)
|
|
1339
|
+
// Ready now, or gone.
|
|
1340
|
+
poolChanged(processPool)
|
|
1323
1341
|
}
|
|
1324
1342
|
if (closed) {
|
|
1325
1343
|
agent.kill('shutdown')
|
|
@@ -1342,15 +1360,24 @@ export function createAcpBackend(
|
|
|
1342
1360
|
// `choices`: the composer's options for this chat ({ configId: value },
|
|
1343
1361
|
// owner turns only), applied before the prompt. The turn then reports
|
|
1344
1362
|
// the model and thinking level it runs with (the answer's meta line).
|
|
1345
|
-
|
|
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 }) {
|
|
1346
1367
|
if (signal?.aborted) return
|
|
1347
1368
|
await preparing.get(thread)?.catch(() => {})
|
|
1348
1369
|
let agent = processes.get(thread)
|
|
1349
1370
|
if (agent?.turn) await agent.settled()
|
|
1350
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
|
+
}
|
|
1351
1378
|
if (!agent || agent.state !== 'ready') {
|
|
1352
1379
|
yield { type: 'status', text: `Starting ${settings.label}` }
|
|
1353
|
-
agent = await start(thread, signal)
|
|
1380
|
+
agent = await start(thread, signal, { workdir })
|
|
1354
1381
|
}
|
|
1355
1382
|
if (signal?.aborted) {
|
|
1356
1383
|
agent.kill('aborted')
|
|
@@ -1455,6 +1482,7 @@ export async function acpHandshake(settings, { env = process.env, root, timeoutM
|
|
|
1455
1482
|
thread: 'doctor',
|
|
1456
1483
|
onGone: (item) => {
|
|
1457
1484
|
if (item.stopped || !item.pid) processPool?.agents.delete(item)
|
|
1485
|
+
poolChanged(processPool)
|
|
1458
1486
|
},
|
|
1459
1487
|
})
|
|
1460
1488
|
try {
|
|
@@ -1469,5 +1497,6 @@ export async function acpHandshake(settings, { env = process.env, root, timeoutM
|
|
|
1469
1497
|
// spawn can fail without an exit event; a dead child with no pid has
|
|
1470
1498
|
// no process left to release its reservation through onGone.
|
|
1471
1499
|
if (agent.stopped || !agent.pid) processPool?.agents.delete(agent)
|
|
1500
|
+
poolChanged(processPool)
|
|
1472
1501
|
}
|
|
1473
1502
|
}
|
|
@@ -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
|
+
}
|