shapewall 0.7.3 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +121 -0
- package/README.md +7 -3
- package/bin/shapewall.js +2 -1
- package/dist/agent/package-lock.json +130 -72
- package/dist/client/assets/BoardChat-BawjlTc7.js +27 -0
- package/dist/client/assets/{BuzzDialog-DwEAN6va.js → BuzzDialog-DnjF36OB.js} +1 -1
- package/dist/client/assets/ChecksPanel-DRFcFhCj.js +1 -0
- package/dist/client/assets/{History-Cp4QRJti.js → History-FzpzGmXZ.js} +1 -1
- package/dist/client/assets/LocalSettings-BGFl4VKr.js +1 -0
- package/dist/client/assets/{Management-B-x1faV8.js → Management-BGdmGtby.js} +1 -1
- package/dist/client/assets/QuickConnect-CiVmxi0l.js +1 -0
- package/dist/client/assets/{ShareDialog-CdLdd6WQ.js → ShareDialog-D0tmOGcQ.js} +2 -2
- package/dist/client/assets/{app-update-dialog-BneaJeqQ.js → app-update-dialog-BQxVHa5e.js} +1 -1
- package/dist/client/assets/{circle-x-D5MkDLJk.js → circle-x-Dxsku6s6.js} +1 -1
- package/dist/client/assets/error-reports-sdk-COuSIAQO.js +15 -0
- package/dist/client/assets/index-B_m65HWT.css +2 -0
- package/dist/client/assets/index-C1ZwriJU.js +37 -0
- package/dist/client/assets/{play--xrZ7VCR.js → play-vJhLsLhL.js} +1 -1
- package/dist/client/assets/{refresh-cw-B-npxKae.js → refresh-cw-TbGHlgDq.js} +1 -1
- package/dist/client/assets/ui-CogdFhRH.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-uKpz8EwR.js → LocalAccountsApp-ntQzkgTS.js} +1 -1
- package/dist/console/assets/{LocalConsole-XeqnTeRB.js → LocalConsole-Rg-MTvSJ.js} +2 -2
- package/dist/console/assets/{LocalUsage-Br3Ddp7_.js → LocalUsage-BGCSfmBU.js} +1 -1
- package/dist/console/assets/{app-update-dialog-h11DnNZi.js → app-update-dialog-CEhV7th4.js} +1 -1
- package/dist/console/assets/app-version-BiMzvHaD.js +1 -0
- package/dist/console/assets/console-BD5_Gha1.js +11 -0
- package/dist/console/assets/console-PWt8SxrJ.css +2 -0
- package/dist/console/assets/error-reports-sdk-COuSIAQO.js +15 -0
- package/dist/console/assets/local-agents-UprGVyLj.js +6 -0
- package/dist/console/assets/minus-Cnq0kKnu.js +1 -0
- package/dist/console/assets/{tailnet-DJGcztR5.js → tailnet-Cqtbptzq.js} +2 -2
- package/dist/console/assets/theme-CB-cwoG6.js +1 -0
- package/dist/console/assets/ui-HgfwUo3E.js +41 -0
- package/dist/console/assets/{usage-fzmilDTS.js → usage-BCIwgDP9.js} +2 -2
- package/dist/console/assets/{usage-DjmUlnXL.js → usage-CeY6XnGX.js} +1 -1
- package/dist/console/build-info.json +1 -1
- package/dist/console/console.html +8 -8
- package/docs/README.md +64 -0
- package/docs/agent-hardening.md +3 -3
- package/docs/agent-recipes.md +3 -3
- package/docs/agent-workflow.md +6 -4
- package/docs/agents.md +25 -16
- package/docs/architecture.md +9 -2
- package/docs/config.md +53 -25
- package/docs/deployment.md +19 -3
- package/docs/github.md +1 -1
- package/docs/hosted.md +265 -70
- package/docs/local-accounts.md +1 -1
- package/docs/performance.md +3 -2
- package/docs/pull-requests.md +1 -1
- package/docs/starter-agent.md +4 -4
- package/docs/where-to-run.md +1 -1
- package/package.json +5 -2
- package/src/agent/backends/acp.js +39 -9
- package/src/capture/capture.js +35 -5
- package/src/capture/destination.js +67 -0
- package/src/capture/load-errors.js +82 -0
- package/src/checks/cli.js +41 -5
- package/src/cli/args.js +1 -0
- package/src/cli/capture.js +5 -0
- package/src/cli/comments.js +41 -3
- package/src/cli/help.js +4 -1
- package/src/cli/init.js +8 -4
- package/src/cli/misc.js +3 -3
- package/src/cli/serve.js +37 -6
- package/src/comment-fields.js +5 -0
- package/src/comments-cli.js +26 -5
- package/src/config-keys.js +191 -0
- package/src/config-reload.js +4 -1
- package/src/config.js +33 -2
- package/src/doctor.js +188 -39
- package/src/error-scrub.js +135 -0
- package/src/error-tracking.js +105 -0
- package/src/feedback.js +36 -2
- package/src/hosted/app.js +9 -3
- package/src/hosted/auth.js +14 -8
- package/src/hosted/board-routes.js +6 -6
- package/src/hosted/db.js +50 -0
- package/src/hosted/pages.js +16 -7
- package/src/hosted/server.js +4 -0
- package/src/hosted/token-api.js +17 -1
- package/src/hosted/usage-shape.js +1 -1
- package/src/missing-package.js +11 -0
- package/src/ports.js +35 -0
- package/src/serve-state.js +16 -0
- package/src/server/app.js +18 -14
- package/src/server/local-console.js +7 -3
- package/src/watch.js +6 -0
- package/dist/client/assets/BoardChat-BVbIXN0v.js +0 -27
- package/dist/client/assets/ChecksPanel-BJmSzge1.js +0 -1
- package/dist/client/assets/LocalSettings-Bt52or8s.js +0 -1
- package/dist/client/assets/QuickConnect-C6sW-MA7.js +0 -1
- package/dist/client/assets/index-C-pM8Kf2.js +0 -37
- package/dist/client/assets/index-C2_XIPRO.css +0 -2
- package/dist/client/assets/ui-2lMx-4bc.js +0 -41
- package/dist/console/assets/app-version-IdaEWb4n.js +0 -1
- package/dist/console/assets/console-BDuWmrw9.js +0 -11
- package/dist/console/assets/console-BGRSS8Ru.css +0 -2
- package/dist/console/assets/local-agents-BkSN9lXJ.js +0 -6
- package/dist/console/assets/minus-887msXez.js +0 -1
- package/dist/console/assets/theme-CPfJOmcz.js +0 -1
- package/dist/console/assets/ui-DnyJhoQU.js +0 -41
package/docs/agents.md
CHANGED
|
@@ -158,7 +158,7 @@ init`, which from 0.7.0 also adds `.shapewall/agent-usage*.jsonl` by name. In a
|
|
|
158
158
|
|
|
159
159
|
## Name and icon
|
|
160
160
|
|
|
161
|
-
Every connected agent has a name you choose and an icon, so a board with two agents reads "
|
|
161
|
+
Every connected agent has a name you choose and an icon, so a board with two agents reads "Reviewer" and "Fixer", not "Claude Code"
|
|
162
162
|
twice. Both are display only: they change nothing an agent runs with.
|
|
163
163
|
|
|
164
164
|
- **At Connect.** The **Allow this?** confirmation of a one-click Connect (in the Agent panel and on the Agents page) has a **Name**
|
|
@@ -181,7 +181,7 @@ twice. Both are display only: they change nothing an agent runs with.
|
|
|
181
181
|
are in `THIRD_PARTY.md`. A colour (one of eight) tints a built-in avatar or the initials, never a mark or a picture.
|
|
182
182
|
- **An uploaded picture** is a PNG, JPEG or WebP of up to 2 MB. The board crops it to a square and sends a 256 by 256 PNG; the server
|
|
183
183
|
checks it byte by byte, decodes it and writes the pixels out again, the same way as a profile photo
|
|
184
|
-
([
|
|
184
|
+
([Local accounts and photos](local-accounts.md#profile-images)), so no metadata and never an SVG is stored. It is kept next to the agent
|
|
185
185
|
settings (`agent-icons/<hash>.png` beside `agents.json`, private to you), served only as an image (`GET /api/agent/icons/<hash>`,
|
|
186
186
|
`image/png`, `nosniff`, cached by its content hash), and removed when no agent uses it any more.
|
|
187
187
|
|
|
@@ -261,7 +261,7 @@ remote mode has the same feedback tools. Shared `--chat` boards never gain these
|
|
|
261
261
|
is checked again on each turn, and trusted and untrusted ACP sessions are separate. Approving a permission, stopping an owner turn, or clearing its thread requires the same owner capability, including while its ACP session is idle. `--no-capture` hides Fix and removes recapture tools.
|
|
262
262
|
|
|
263
263
|
For an external coding session, open **Chat settings** in the chat panel: **Use with Claude Code / Codex** shows copyable MCP setup
|
|
264
|
-
commands (before an agent is connected, the same commands are folded under the connect options). See [agent
|
|
264
|
+
commands (before an agent is connected, the same commands are folded under the connect options). See [The agent workflow](agent-workflow.md#mcp-server-shapewall-mcp).
|
|
265
265
|
|
|
266
266
|
## Undo an agent's change
|
|
267
267
|
|
|
@@ -707,7 +707,15 @@ Older Gemini CLI versions call the flag `--experimental-acp` (still accepted, de
|
|
|
707
707
|
the panel shows a card with the agent's options (**Allow**, **Reject**, and any "always" choices it offers). An edit or a write
|
|
708
708
|
shows its diff on the card, computed by Shapewall from the file as it is and the new text (the first 80 lines or 8 KB, with **Show
|
|
709
709
|
the whole diff** for up to 1500 lines or 64 KB). No answer within 2 minutes counts as a deny, and so does Stop. Whether the agent asks at all is the agent's own setting (Claude Code's permission mode,
|
|
710
|
-
Codex's approval policy, goose's mode): Shapewall does not change it.
|
|
710
|
+
Codex's approval policy, goose's mode): Shapewall does not change it. One-click **Connect** saves the bare command
|
|
711
|
+
(`claude-agent-acp`), so the agent starts in whatever mode its own settings give it, and some adapters start in one that acts without
|
|
712
|
+
asking (`claude-agent-acp` 0.106.0 starts a new session in `auto` when no `permissions.defaultMode` is set).
|
|
713
|
+
- **The mode in effect.** The panel's line about a local agent says it runs under its own permission settings. Once its session has
|
|
714
|
+
started and it reports a mode, the line names it: **Auto, which acts without asking** (any mode whose name says so: auto, accept
|
|
715
|
+
edits, bypass, full access, yolo and the like), **Default: it asks here before an edit or a command its own settings do not already
|
|
716
|
+
allow** (Claude Code's `default`, goose's `approve`), **Plan: it reads and answers** (Claude Code's `plan`, Codex's `read-only`,
|
|
717
|
+
goose's `chat`), or just the mode's name for any other. To be asked first, pick an asking mode in the composer's options, or set
|
|
718
|
+
one in the agent's own settings ([Restrict the agent's own tools](#restrict-the-agents-own-tools)).
|
|
711
719
|
|
|
712
720
|
### What the agent may do through Shapewall
|
|
713
721
|
|
|
@@ -746,12 +754,13 @@ quote each comment in the same `<shapewall-data trust="untrusted">` element.
|
|
|
746
754
|
The agent works with its own tools under its own settings, and Shapewall cannot sandbox them. Run it the way you would run it on a repo
|
|
747
755
|
full of other people's text:
|
|
748
756
|
|
|
749
|
-
- **Claude Code** (`claude-agent-acp`) follows your Claude Code settings.
|
|
750
|
-
edits and commands) or `plan` (read-only), never `
|
|
757
|
+
- **Claude Code** (`claude-agent-acp`) follows your Claude Code settings. Set `permissions.defaultMode` to `default` (asks before
|
|
758
|
+
edits and commands your allow rules do not cover) or `plan` (read-only), never `auto`, `acceptEdits` or `bypassPermissions`. Set
|
|
759
|
+
it explicitly: with none set, `claude-agent-acp` 0.106.0 starts in `auto`, which acts without asking. A separate config folder for Shapewall works too:
|
|
751
760
|
`CLAUDE_CONFIG_DIR` is passed to the agent.
|
|
752
761
|
- **Codex** (`codex-acp`) follows `~/.codex/config.toml` (or `CODEX_HOME`). Use `sandbox_mode = "workspace-write"` (or
|
|
753
762
|
`"read-only"`) with `approval_policy = "on-request"`, never `danger-full-access`.
|
|
754
|
-
- **goose** loads every extension enabled in its profile (browser control, say). Give it a profile of its own with only the developer
|
|
763
|
+
- **goose** asks only in `GOOSE_MODE=approve` (or `smart_approve`); its default, `auto`, acts without asking. It also loads every extension enabled in its profile (browser control, say). Give it a profile of its own with only the developer
|
|
755
764
|
extension, and start it with that extension named:
|
|
756
765
|
|
|
757
766
|
```sh
|
|
@@ -791,8 +800,8 @@ What the bridge protects against, and what it does not:
|
|
|
791
800
|
- **Who can chat:** anyone who can reach a board with chat can drive the agent, with your login, on your machine. `shapewall serve`
|
|
792
801
|
keeps chat off for boards shared beyond this machine unless you pass `--chat`, and with an ACP agent it refuses to start a shared
|
|
793
802
|
board with `--chat` unless you also pass `--allow-remote-agent`: that combination is remote command execution as you, for anyone
|
|
794
|
-
who reaches the board. For shared boards, use the sandboxed starter agent
|
|
795
|
-
[
|
|
803
|
+
who reaches the board. For shared boards, use the [sandboxed starter agent](starter-agent.md), and see
|
|
804
|
+
[Agent hardening](agent-hardening.md).
|
|
796
805
|
- **Not covered:** the agent's own tools and its own sandbox (or lack of one), what its model provider sees, and anything you allow.
|
|
797
806
|
A command you approve runs as you in the project, so the project's own config still applies to it (a repo's `.git/config` can make
|
|
798
807
|
`git status` run a program): approve commands only in repos you trust.
|
|
@@ -903,8 +912,8 @@ What the bridge protects against, and what it does not:
|
|
|
903
912
|
own name (**Effort**, **Thinking**), and anything else it offers (a mode such as Ask or Plan) under **More options**. When the panel
|
|
904
913
|
is too narrow for them, one control holds every option in sections. They come from an ACP agent's own session (`session/new`
|
|
905
914
|
config options and its older modes), or the model list an OpenAI-compatible endpoint reports at `/models`. Never a permission or
|
|
906
|
-
sandbox setting, and never a mode that acts without asking (bypass, auto, yolo and the like)
|
|
907
|
-
|
|
915
|
+
sandbox setting, and never a switch to a mode that acts without asking (bypass, auto, yolo and the like). A session that is
|
|
916
|
+
already in such a mode (its own settings started it there) keeps it until you pick another, and the panel's line says so. Values show the agent's real names: a value that is just the agent's default says **Default
|
|
908
917
|
model**, or the model it says it currently is. The keyboard works as in any menu: the current choice has the focus when it opens,
|
|
909
918
|
the arrows and Home and End move, Escape closes it back to its button.
|
|
910
919
|
- **Options before the first message.** As soon as the panel is open and on screen for the owner, a new chat (New chat included)
|
|
@@ -1009,14 +1018,14 @@ Markdown to share it.
|
|
|
1009
1018
|
|
|
1010
1019
|
## Board tools
|
|
1011
1020
|
|
|
1012
|
-
Endpoint models that support function calling get `list_pages`, `list_comments` and `get_comment`. These tools read the board's config and comments without sending local file paths. Trusted owner turns additionally get `reply_to_comment`, `set_comment_status`, `resolve_comment` and, with captures enabled, `recapture_pages`. Those tools accept board-local ids, never file paths or commands. Endpoint models cannot edit project files. To edit code, connect a coding agent over ACP or use `shapewall mcp` or `shapewall watch` ([agent
|
|
1021
|
+
Endpoint models that support function calling get `list_pages`, `list_comments` and `get_comment`. These tools read the board's config and comments without sending local file paths. Trusted owner turns additionally get `reply_to_comment`, `set_comment_status`, `resolve_comment` and, with captures enabled, `recapture_pages`. Those tools accept board-local ids, never file paths or commands. Endpoint models cannot edit project files. To edit code, connect a coding agent over ACP or use `shapewall mcp` or `shapewall watch` ([The agent workflow](agent-workflow.md)).
|
|
1013
1022
|
|
|
1014
1023
|
Agents with only a shell, and chat bots that relay a board to people, use the CLI: `shapewall comments get|add|reply|resolve|status`
|
|
1015
1024
|
(all with `--json`; `comments` and `comments get` also take `--for-agent`, each comment quoted as untrusted `<shapewall-data>` for a
|
|
1016
1025
|
model to read), `shapewall comments --since ID|TIME` for what is new, and `shapewall events --follow --json` for a live stream of
|
|
1017
1026
|
every comment event from every process that never claims anything (`shapewall watch --no-claim` likewise). While `shapewall serve` runs,
|
|
1018
|
-
it sends the notifications for all of those changes ([agent
|
|
1019
|
-
[
|
|
1027
|
+
it sends the notifications for all of those changes ([The agent workflow](agent-workflow.md#a-chat-bot-telegram-slack-discord),
|
|
1028
|
+
[Notifications](notifications.md#events)).
|
|
1020
1029
|
|
|
1021
1030
|
An ACP agent reads the project with its own tools; board data comes with each message. On trusted owner turns, its ACP session also receives a Shapewall stdio MCP server scoped to this board. It provides board reads plus replies, agent status, resolution and optional recapture, with no GitHub actions. Ask it to call `recapture_pages` with any other configured pages it changed; Shapewall automatically recaptures the comment page after the turn.
|
|
1022
1031
|
|
|
@@ -1034,7 +1043,7 @@ Anyone who can comment can write text that a model will read. Shapewall keeps th
|
|
|
1034
1043
|
That lowers the risk; it does not remove it. Models can still be talked into a wrong answer, so treat answers about untrusted comments
|
|
1035
1044
|
with care, and do not point a chat at a board you share with strangers using a key that has other powers.
|
|
1036
1045
|
|
|
1037
|
-
Connecting an agent to a board other people can write on? Read [
|
|
1046
|
+
Connecting an agent to a board other people can write on? Read [Agent hardening](agent-hardening.md) first (also as a printable
|
|
1038
1047
|
[PDF](https://shapewall.com/downloads/shapewall-agent-hardening.pdf)): how injected text reaches an agent, least privilege, a sandbox checklist and what to do if something goes wrong.
|
|
1039
1048
|
|
|
1040
1049
|
## Sharing a board
|
|
@@ -1131,5 +1140,5 @@ chosen, expiresAt }`, state `pending`, then `approved`, `denied`, `expired` or `
|
|
|
1131
1140
|
## Shared boards
|
|
1132
1141
|
|
|
1133
1142
|
The chat runs the agent as you. For boards where not everyone who comments should drive an agent on your machine, use the
|
|
1134
|
-
[starter
|
|
1143
|
+
[Sandboxed starter agent](starter-agent.md): work on a comment runs in a container with only a fresh worktree, an egress allow list, fixed tools, a trigger gate, budgets, and a branch as
|
|
1135
1144
|
the output.
|
package/docs/architecture.md
CHANGED
|
@@ -167,7 +167,9 @@ the same way. Scrolling inside a `nowheel` element (the frame bar, a live page b
|
|
|
167
167
|
- Journeys fade the cards that are not in the journey, put numbered badges on the ones that are, and fly the camera to each step. A
|
|
168
168
|
branching journey is shown one path at a time (`resolvePath` with the branches picked); the other branches' arrows are dashed.
|
|
169
169
|
- Compare mode lays two frames per viewport side by side (one per environment) and shows screenshots only, with the cached diff mask
|
|
170
|
-
over the second.
|
|
170
|
+
over the second. A variant keeps its single frame there, beside its page's pair: it is one capture of one idea, with no second
|
|
171
|
+
environment to compare it against. New comments are off while comparing (a comment belongs to a page, not to one environment, so
|
|
172
|
+
which capture a click meant is unanswerable); the compare bar says so, and replies, resolving and "jump to comment" all work.
|
|
171
173
|
- Each frame's label (viewport, environment, live) sits in a strip between the card header and the frame, never on the captured page.
|
|
172
174
|
- The selected card's action bar belongs to one view: switching viewport, compare or a journey, and Fit view, clear the selection, and
|
|
173
175
|
the bar hides while the frame is a thumbnail on screen (its longer side under 160 px). Tapping a thumbnail flies to it first, leaving
|
|
@@ -205,7 +207,12 @@ count, and clicking it zooms in until they part (`clusterPins` in `client/src/bo
|
|
|
205
207
|
a kit `HoverCard`. Resolved threads are hidden by the Open filter, which is the toggle for showing them.
|
|
206
208
|
|
|
207
209
|
C (or the Comment tool, in the board tools at the bottom of the canvas, or Comment on the selected page's bar, which also names that page in the hint) turns comment mode on; a click drops a draft pin and an inline composer (`ComposerPopover`) opens beside
|
|
208
|
-
it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The
|
|
210
|
+
it: Enter posts, Shift+Enter adds a line, Esc cancels and stays in comment mode, @ suggests people. The composer, the reply box and
|
|
211
|
+
the edit box have a microphone where the browser has speech recognition (`client/src/board/DictationButton.jsx`): the browser's
|
|
212
|
+
`SpeechRecognition` writes at the caret, the rules for joining words to the text around them and the session states are pure
|
|
213
|
+
(`client/src/board/dictation.js`, tested in `test/comment-dictation.test.js`), and `hooks/useCommentDictation.js` drives one
|
|
214
|
+
recognizer at a time and releases it on posting, Esc, unmount and a hidden tab. Shapewall never receives the audio; the browser's
|
|
215
|
+
speech service does the transcription. The open thread is a popover at
|
|
209
216
|
its pin (`ThreadPopover`): resolve, previous and next (also the arrow keys), and a more menu (copy link, edit, ask agent, GitHub,
|
|
210
217
|
history, delete), then the messages with reactions and an inline reply box. Both are Radix popovers anchored to a virtual element
|
|
211
218
|
that reads the pin's position every frame, bounded by the canvas, so they follow pan and zoom, flip to stay on screen and hide when
|
package/docs/config.md
CHANGED
|
@@ -10,11 +10,21 @@ each board (including a board's own `viewports`, `block`, `setup` and `auth`), `
|
|
|
10
10
|
in the serve log and the board keeps the last good config. `outputDir`, `boardUrl`, `auth`, `browser`, `liveHtml`, `agent`,
|
|
11
11
|
`starterAgent`, `notifications` and `github` still need a restart (the log says so).
|
|
12
12
|
|
|
13
|
+
`checks` and `ci` are in neither list, so an edit to either is silently not picked up and the log says nothing about it. Restart
|
|
14
|
+
`serve` for a `checks` change to reach the board's **Run checks**; `ci` is read by `shapewall ci` in its own run, so a running board
|
|
15
|
+
never uses it anyway.
|
|
16
|
+
|
|
17
|
+
A key Shapewall does not use (a typo like `"viewport"` for `"viewports"`, or a page key such as `waitFor` set at the top level) is
|
|
18
|
+
ignored, and `shapewall doctor`, `capture` and `serve` warn about it with the key it most likely meant; the config still loads.
|
|
19
|
+
Unknown keys are refused outright only inside `capturePacing`, `checks`, `setup`, `ci`, an action's options and a page's `seo`,
|
|
20
|
+
plus the secret and command key lists in `agent` and `github`. A required key under the wrong case (`"baseURL"`) is an error that
|
|
21
|
+
says to rename it. `$schema` is allowed anywhere.
|
|
22
|
+
|
|
13
23
|
## Top level
|
|
14
24
|
|
|
15
25
|
| Key | Type | Default | Notes |
|
|
16
26
|
| --------------- | --------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
17
|
-
| `title` | string | `"Shapewall"` |
|
|
27
|
+
| `title` | string | `"Shapewall"` | The config's title, on the board and in exports and hosted pushes. In a single-board config the board takes it too; a board with none is titled by its id. |
|
|
18
28
|
| `id` | string | `"site"` | Board id for single-board configs. Lowercase letters, digits, dashes. |
|
|
19
29
|
| `baseUrl` | http(s) URL | required | Where pages are loaded from. May include a base path: `http://localhost:3000/app`. |
|
|
20
30
|
| `publicUrl` | http(s) URL | none | Used for "Open page" links and to rewrite links in live HTML. |
|
|
@@ -29,18 +39,19 @@ in the serve log and the board keeps the last good config. `outputDir`, `boardUr
|
|
|
29
39
|
| `liveHtml` | boolean | `true` | `false` captures screenshots only. |
|
|
30
40
|
| `versions` | 0-50 | `5` | Previous captures kept per page and viewport, for before/after. `0` keeps none. |
|
|
31
41
|
| `boardUrl` | http(s) URL | the running `serve` address | Where people open the board, for links in notifications and GitHub issues. Without it, links use a running `shapewall serve` for this config, else port 4600. |
|
|
32
|
-
| `environments` | Environment[] | none | The same pages at other base URLs, for compare mode. See below.
|
|
33
|
-
| `journeys` | Journey[] | none | Named page sequences, which may fork. See [
|
|
42
|
+
| `environments` | Environment[] | none | The same pages at other base URLs, for compare mode. 1 to 8 of them. See below. |
|
|
43
|
+
| `journeys` | Journey[] | none | Named page sequences, which may fork. See [Journeys and links](journeys.md). |
|
|
34
44
|
| `auth` | object | none | See below. |
|
|
35
45
|
| `browser` | object | Playwright's Chromium | `{ "channel": "chrome" }` or `{ "executablePath": "/path/to/chrome" }` (absolute, outside the project). |
|
|
36
46
|
| `groups` | string[] | order of first use | Group order on the board. |
|
|
37
47
|
| `pages` | Page[] | required (or `boards`) | See below. |
|
|
38
48
|
| `boards` | Board[] | none | Several boards in one file, instead of top-level `pages`. |
|
|
39
|
-
| `notifications` | object | off | Webhook, Slack, Discord and email for comment events. See [
|
|
49
|
+
| `notifications` | object | off | Webhook, Slack, Discord and email for comment events. See [Notifications](notifications.md). |
|
|
40
50
|
| `github` | object | none | GitHub connect: `repo`, `boardUrl`, `labels`. See [GitHub](#github) below. |
|
|
41
51
|
| `agent` | object | none | The board chat's model endpoint. See [Agent](#agent) below. |
|
|
42
|
-
| `starterAgent` | object | none | The sandboxed starter agent: who may dispatch work, tests, budgets. See [starter
|
|
52
|
+
| `starterAgent` | object | none | The sandboxed starter agent: who may dispatch work, tests, budgets. See [Sandboxed starter agent](starter-agent.md). |
|
|
43
53
|
| `sitemap` | URL, file or object | none | Default source for `shapewall sitemap`. See [Sitemap import](#sitemap-import). |
|
|
54
|
+
| `checks` | object | none | Defaults for page checks. Only `seo` and `budgets` are accepted. See [Checks SEO](#checks-seo) and [Checks budgets](#checks-budgets) below. |
|
|
44
55
|
| `ci` | object | none | Capture on pull requests: threshold, pages, ignore selectors, build and serve commands. See [CI](#ci) below. |
|
|
45
56
|
|
|
46
57
|
Environment overrides: `SHAPEWALL_BROWSER_CHANNEL`, `SHAPEWALL_BROWSER_PATH`.
|
|
@@ -58,11 +69,11 @@ Environment overrides: `SHAPEWALL_BROWSER_CHANNEL`, `SHAPEWALL_BROWSER_PATH`.
|
|
|
58
69
|
| `group` | string | Card group on the board. Defaults to `Pages`. |
|
|
59
70
|
| `note` | string | Up to 200 characters, shown on the card and with its comments: "Sample data", "Signed-out state". |
|
|
60
71
|
| `waitFor` | selector | Must be visible before the shot. |
|
|
61
|
-
| `actions` | Action[] | Run in order after loading, before the shot.
|
|
72
|
+
| `actions` | Action[] | Run in order after loading, before the shot. At most 30. |
|
|
62
73
|
| `viewports` | string[] | A subset of the configured viewports for this page. |
|
|
63
74
|
| `expectStatus` | number or number[] | An error page captured on purpose, e.g. `404` or `[404, 410]`. It is captured like any page; another status is the failure. |
|
|
64
75
|
| `errorSelectors` | string[] | Optional known error-state CSS selectors for checks. At most 10 selectors of 500 characters each. Visible matches produce a reliability finding; no page-text guessing. |
|
|
65
|
-
| `seo` | object |
|
|
76
|
+
| `seo` | object | An object whose only key is a boolean `indexable`. `{ "indexable": false }` skips public SEO diagnostics even with `--seo`; omit it for public pages. SEO is off without `--seo`. |
|
|
66
77
|
| `timeout` | ms | This page's budget for loading, `waitFor` and its actions, 1000-300000. Replaces `timeouts.page` for it, and lets its `wait` and `hold` actions run that long. |
|
|
67
78
|
| `localStorage` | object | Seeds for this page, on top of the board's. See [localStorage seeds](#localstorage-seeds). |
|
|
68
79
|
| `frameHeight` | number or object | This page's own frame height, 240-8000: one number for all its viewports, or `{ "desktop": 900, "phone": 844 }`. The browser window stays the viewport's. See [Viewports](#viewports). |
|
|
@@ -203,8 +214,9 @@ A board for a guest-first app and a canvas game might read:
|
|
|
203
214
|
|
|
204
215
|
## Viewports
|
|
205
216
|
|
|
206
|
-
`viewports` (top level, and per board) is keyed by name. `desktop`, `tablet` and `phone` are built in;
|
|
207
|
-
|
|
217
|
+
`viewports` (top level, and per board) is keyed by name. `desktop`, `tablet` and `phone` are built in; a name of your own works too
|
|
218
|
+
(`phone-landscape`, `kiosk`), as long as it is lowercase letters, digits and dashes, starts with a letter and is at most 32
|
|
219
|
+
characters: `Kiosk` and `4k` are rejected. Up to 8.
|
|
208
220
|
|
|
209
221
|
| Key | Notes |
|
|
210
222
|
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
@@ -242,6 +254,7 @@ heights.
|
|
|
242
254
|
- `"analytics"` is a built-in list: Google Analytics and Tag Manager, Plausible, Umami Cloud, Cloudflare Web Analytics and RUM, Segment,
|
|
243
255
|
Hotjar, Clarity, Mixpanel, Amplitude, PostHog, Heap, FullStory, Fathom, Simple Analytics, GoatCounter, and the Meta, Bing, LinkedIn,
|
|
244
256
|
X, TikTok and HubSpot pixels. A self-hosted analytics endpoint needs its own pattern (`"*/umami/*"`).
|
|
257
|
+
- A list holds at most 50 entries, each at most 300 characters and without whitespace.
|
|
245
258
|
|
|
246
259
|
The top-level list applies to every board; a board's `block` adds to it. Blocked requests are not network failures in the capture
|
|
247
260
|
warnings or in page checks. Page checks apply the same list.
|
|
@@ -254,9 +267,10 @@ warnings or in page checks. Page checks apply the same list.
|
|
|
254
267
|
{ "localStorage": { "game.trailerSeen": "1", "settings": { "music": false } } }
|
|
255
268
|
```
|
|
256
269
|
|
|
257
|
-
Strings are stored as they are; numbers, booleans, objects and arrays as JSON.
|
|
258
|
-
|
|
259
|
-
|
|
270
|
+
Strings are stored as they are; numbers, booleans, objects and arrays as JSON. Each object takes at most 50 keys, a key at most 200
|
|
271
|
+
characters and a stored value at most 20000. A page's keys win over its board's, a board's over the top level's. They are set on
|
|
272
|
+
every load of that origin in the shot. Use them for flags an app checks at start (a tutorial seen, a saved setting) instead of
|
|
273
|
+
clicking through to set them.
|
|
260
274
|
|
|
261
275
|
## Setup (shared state)
|
|
262
276
|
|
|
@@ -275,7 +289,7 @@ and the pages in its scope start from the browser state it left: cookies, localS
|
|
|
275
289
|
}
|
|
276
290
|
```
|
|
277
291
|
|
|
278
|
-
- `actions` (required): any page actions, including `viewports` guards and `optional`.
|
|
292
|
+
- `actions` (required): any page actions, including `viewports` guards and `optional`. At most 30, as on a page.
|
|
279
293
|
- `path`: where it starts, default `/`.
|
|
280
294
|
- `groups` and `pages`: its scope. Without either, every page of the board uses it; with them, only pages in those groups or with
|
|
281
295
|
those ids (marketing pages keep a clean first visit).
|
|
@@ -311,8 +325,8 @@ page only.
|
|
|
311
325
|
- With more than `--limit` pages (default 100, at most 1000), the shallowest are kept, so the top of the site wins over deep archives.
|
|
312
326
|
- `--board ID` adds them to one board of a multi-board config. Nothing is captured; run `shapewall capture` next.
|
|
313
327
|
|
|
314
|
-
To set the source once, add `sitemap` to the config
|
|
315
|
-
`init --sitemap` records it:
|
|
328
|
+
To set the source once, add `sitemap` to the config, or, in a multi-board config, to each board inside `boards[]` (a top-level
|
|
329
|
+
`sitemap` beside `boards` is an error). `shapewall sitemap` with no argument reads it, and `init --sitemap` records it:
|
|
316
330
|
|
|
317
331
|
```json
|
|
318
332
|
{ "sitemap": { "source": "https://www.example.com/sitemap.xml", "limit": 50, "exclude": ["/tag/"], "group": "Site" } }
|
|
@@ -393,13 +407,13 @@ Versions are kept for the default environment only.
|
|
|
393
407
|
`repo` (`owner/name`), `boardUrl` (where the board is served, for links from issues; default `http://127.0.0.1:4600/`), `labels` (up to
|
|
394
408
|
10, put on new issues), `board` (the board that bare `shapewall:<id>` markers mean) and `apiUrl` (GitHub Enterprise Server). Top level
|
|
395
409
|
only. The token comes from `SHAPEWALL_GITHUB_TOKEN` or `GITHUB_TOKEN` and the webhook secret from `SHAPEWALL_GITHUB_WEBHOOK_SECRET`; a
|
|
396
|
-
`token` or `
|
|
397
|
-
`SHAPEWALL_GITHUB_API_URL`. See [
|
|
410
|
+
`token`, `webhookSecret` or `secret` key here is an error. Environment overrides: `SHAPEWALL_GITHUB_REPO`, `SHAPEWALL_BOARD_URL`,
|
|
411
|
+
`SHAPEWALL_GITHUB_API_URL`. See [GitHub connect](github.md).
|
|
398
412
|
|
|
399
413
|
## CI
|
|
400
414
|
|
|
401
415
|
Capture on every pull request: what `shapewall ci` and the workflow from `shapewall init --ci` read. See
|
|
402
|
-
[pull
|
|
416
|
+
[Capture on pull requests](pull-requests.md).
|
|
403
417
|
|
|
404
418
|
```json
|
|
405
419
|
{
|
|
@@ -419,10 +433,10 @@ Capture on every pull request: what `shapewall ci` and the workflow from `shapew
|
|
|
419
433
|
| `threshold` | 0-1 | `0.00001` | Share of pixels below which a shot counts as unchanged (0.00001 is 0.001%). A size change always counts. `--threshold` overrides it. |
|
|
420
434
|
| `pages` | string[] | every page | Page ids to compare (an allow-list), in the config's order. |
|
|
421
435
|
| `viewports` | string[] | each page's own | Viewport names to compare. |
|
|
422
|
-
| `ignore` | string[] | none | CSS selectors hidden (`visibility: hidden`) on both sides before each shot: clocks, ads, random content. Up to 50.
|
|
436
|
+
| `ignore` | string[] | none | CSS selectors hidden (`visibility: hidden`) on both sides before each shot: clocks, ads, random content. Up to 50, each at most 300 characters. |
|
|
423
437
|
| `images` | string | `"links"` | `"links"`: the comment links to the workflow artifact. `"branch"`: thumbnails committed to a `shapewall-ci` branch and shown inline (public repositories only; needs `contents: write`). |
|
|
424
438
|
| `maxPages` | 1-500 | `50` | Compare at most this many pages. `--max-pages` overrides it. |
|
|
425
|
-
| `start` | object | none | Build and serve mode: `install`, `build` and `serve` commands, the `url` serve listens on, and `timeout` in ms (default 180000).
|
|
439
|
+
| `start` | object | none | Build and serve mode: `install`, `build` and `serve` commands, the `url` serve listens on, and `timeout` in ms (1000 to 1800000, default 180000). With `start`, `serve` is required. |
|
|
426
440
|
|
|
427
441
|
`start` commands are argv arrays (`["npm", "run", "build"]`): a program name found on `PATH`, then its arguments, run without a shell.
|
|
428
442
|
A string is an error, and so are paths (`./build.sh`, so a config cannot name a program the repository ships), shells and launchers
|
|
@@ -438,10 +452,15 @@ from `shapewall ci capture --allow-start` inside a CI job (`GITHUB_ACTIONS` or `
|
|
|
438
452
|
```
|
|
439
453
|
|
|
440
454
|
The board chat's endpoint: any OpenAI-compatible chat completions API. `baseUrl` and `model` are required to connect; `apiKeyEnv` (the
|
|
441
|
-
variable holding the key, default `SHAPEWALL_AGENT_API_KEY`), `label` (the name shown for it; a connected agent's name and icon are set on the Agents page, see [
|
|
442
|
-
`temperature` and `backend`
|
|
455
|
+
variable holding the key, default `SHAPEWALL_AGENT_API_KEY`), `label` (the name shown for it; a connected agent's name and icon are set on the Agents page, see [Chat with an agent](agents.md#name-and-icon)), `vision` (default `true`), `tools` (default `true`), `maxTokens`,
|
|
456
|
+
`temperature` (0 to 2) and `backend` are optional. `maxTokens` is a whole number from 1 to 200000. `backend` is
|
|
457
|
+
`"openai-compatible"` (the default) or `"acp"`, which chats with an agent CLI over ACP instead; that command comes from
|
|
458
|
+
`serve --agent-acp`, `SHAPEWALL_AGENT_ACP` or the host's saved agent settings, never from the config. Top level only. An `apiKey`,
|
|
459
|
+
`key`, `token`, `secret` or `password` key here is an error, and so is any key that could name a command to run (`command`, `cmd`,
|
|
460
|
+
`exec`, `acp`, `acpCommand`, `program`, `args`, `argv`, `env`), because a committed config would run it on the machine of whoever
|
|
461
|
+
chats from that repo. `apiKeyEnv` may only name `SHAPEWALL_AGENT_*` or a `*_API_KEY`
|
|
443
462
|
variable. A key goes only to this machine, a known hosted API, or a host confirmed in `SHAPEWALL_AGENT_KEY_HOSTS`.
|
|
444
|
-
Environment overrides: `SHAPEWALL_AGENT_BASE_URL`, `SHAPEWALL_AGENT_MODEL`. See [
|
|
463
|
+
Environment overrides: `SHAPEWALL_AGENT_BASE_URL`, `SHAPEWALL_AGENT_MODEL`. See [Chat with an agent](agents.md).
|
|
445
464
|
|
|
446
465
|
How fixes run, both off by default and also on the Agents page of the Workspace Console (saved settings win over these):
|
|
447
466
|
`branchMode` (`true` runs an agent CLI's fixes on a branch of their own) with `branchPrefix` (default `"shapewall/"`), see
|
|
@@ -450,6 +469,11 @@ How fixes run, both off by default and also on the Agents page of the Workspace
|
|
|
450
469
|
|
|
451
470
|
## Auth
|
|
452
471
|
|
|
472
|
+
A page that needs a sign-in usually redirects to the sign-in page, and without a login a capture is a picture of that page. Each
|
|
473
|
+
shot keeps the URL it landed on (`finalUrl` in `capture --json`, with `redirected: true` when it is not the page asked for), the
|
|
474
|
+
capture line says "landed on /login/, not /app/", the capture ends with a warning that points here, and the board marks the card
|
|
475
|
+
"Redirected". `shapewall checks` prints the same as a warning.
|
|
476
|
+
|
|
453
477
|
Never put credentials in the config. Two options:
|
|
454
478
|
|
|
455
479
|
**Guided manual sign-in.** Run this on the desktop that will capture the site:
|
|
@@ -482,8 +506,12 @@ record and capture locally, then use the normal capture-push workflow instead of
|
|
|
482
506
|
|
|
483
507
|
**Login script.** An ES module whose default export signs in. It runs once per capture; its cookies and storage are reused for every page.
|
|
484
508
|
|
|
485
|
-
|
|
486
|
-
|
|
509
|
+
When the page being captured is loaded from a public host, the capture browser refuses that page's own requests to loopback, private
|
|
510
|
+
and internal hosts, including a public name that resolves to one, so a public page cannot make the browser fetch from this machine or
|
|
511
|
+
its network (a router page, a local dev server, cloud metadata). The `baseUrl` itself is never refused, and a `baseUrl` that is
|
|
512
|
+
already local or private -- the usual dev site -- keeps all of its requests, including those to other hosts on your network. So the
|
|
513
|
+
guard bounds what a public page may reach through the capture browser; it is not a check on where a config may point. Read a config
|
|
514
|
+
you did not write before you capture with it.
|
|
487
515
|
|
|
488
516
|
A login script is code: `shapewall capture`, the board's Capture button and page checks run it on your machine, as you, with your
|
|
489
517
|
environment. Capture prints a line the first time it runs one. Only use a config with `auth.loginScript` from a repo you trust, and read
|
package/docs/deployment.md
CHANGED
|
@@ -78,13 +78,13 @@ Any proxy works (nginx with `auth_basic`, an SSO proxy such as oauth2-proxy, a T
|
|
|
78
78
|
- Anyone who can reach the board can read every capture and comment and, unless you pass `--read-only` or `--no-capture`, add comments
|
|
79
79
|
and start captures.
|
|
80
80
|
- The board chat spends your model key, so it is off on a shared board unless you pass `--chat` (with a rate limit, a cap on answers at
|
|
81
|
-
once and a storage quota per board). See [
|
|
81
|
+
once and a storage quota per board). See [Chat with an agent](agents.md#sharing-a-board).
|
|
82
82
|
- The comment author is a free-text name, not an identity. If you need accountability, put identity in the proxy and its logs.
|
|
83
83
|
- Binding to a non-loopback address (`--host 0.0.0.0`) without a proxy exposes the board unauthenticated; Shapewall prints a warning. With
|
|
84
84
|
a non-loopback `--host` and no allowed host names, the Host check is off.
|
|
85
85
|
- With GitHub connect, anyone who can use the board can open issues with the server's token. A GitHub webhook
|
|
86
86
|
(`POST /api/github/webhook`, only when `SHAPEWALL_GITHUB_WEBHOOK_SECRET` is set) must reach the board without the proxy's login; it is
|
|
87
|
-
protected by its signature instead. See [
|
|
87
|
+
protected by its signature instead. See [GitHub connect](github.md#webhook).
|
|
88
88
|
- `SHAPEWALL_ALLOWED_HOSTS` (comma-separated) adds names the same way as `--allowed-host`, and keeps the Host check on for a non-loopback
|
|
89
89
|
`--host`. The value `*` turns the check off on purpose, for when the proxy in front already restricts the Host.
|
|
90
90
|
|
|
@@ -137,13 +137,29 @@ stay read-only.
|
|
|
137
137
|
The demo on shapewall.com goes further: `node scripts/demo-export.js` exports with the demo client (`npm run build:demo`, into
|
|
138
138
|
`dist/demo-app`), which bundles the board and the hosted console with an in-browser backend (`client/src/demo/`). Visitors get a
|
|
139
139
|
fictional workspace with people in every role, invites, share links, tokens, an audit log and a scripted agent in the chat, switch
|
|
140
|
-
roles with View as, and keep their changes in localStorage. Nothing is sent to a server.
|
|
140
|
+
roles with View as, and keep their changes in localStorage. Nothing they do is sent to a server.
|
|
141
141
|
|
|
142
142
|
Serve the board from its folder with the trailing slash (`/demo/`, not `/demo`): its URLs are relative. If the host sends
|
|
143
143
|
`X-Frame-Options` or a `frame-ancestors` policy, let the board frame its own `data/**/*.html` files (same origin).
|
|
144
144
|
|
|
145
145
|
Treat an export like the site itself: if the captured pages are not public, do not publish the export publicly either.
|
|
146
146
|
|
|
147
|
+
## Error reports (opt-in)
|
|
148
|
+
|
|
149
|
+
Off by default: Shapewall has no telemetry, no usage stats and no update check, and it never sends anything to the Shapewall team. If
|
|
150
|
+
you want your own server's errors reported to an error tracker you run or use (Sentry, GlitchTip or anything that accepts a Sentry DSN),
|
|
151
|
+
set its DSN before `shapewall serve` or `shapewall hosted` starts:
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
SHAPEWALL_ERROR_DSN=https://<public key>@errors.example.com/<project id>
|
|
155
|
+
SHAPEWALL_ERROR_ENVIRONMENT=production # optional, default production
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The server then reports its own unhandled errors, and the pages it serves report browser errors to the same DSN (their CSP allows that
|
|
159
|
+
one origin). Without the variable the error-reporting SDK is never loaded, on the server or in the browser. A report holds the error, its
|
|
160
|
+
stack trace, the URL path, the browser or Node version and the release. It never holds board, page or comment content, request bodies,
|
|
161
|
+
cookies, headers other than the user agent, query strings, user identities, local variables or console output.
|
|
162
|
+
|
|
147
163
|
## Updates
|
|
148
164
|
|
|
149
165
|
The small version below the UI opens **About & Updates**. Updates are manual: update the same way you installed, or give the board an
|
package/docs/github.md
CHANGED
|
@@ -94,7 +94,7 @@ Every delivery must carry a valid `X-Hub-Signature-256` for the secret (checked
|
|
|
94
94
|
nothing. `ping` answers 200; `pull_request` events of the configured repo link and resolve as above; other events and other repos are
|
|
95
95
|
acknowledged and ignored. The webhook needs no token: the event carries the pull request. A `--read-only` server refuses deliveries.
|
|
96
96
|
|
|
97
|
-
The board's Host check still applies, so add the public name with `--allowed-host` (see [
|
|
97
|
+
The board's Host check still applies, so add the public name with `--allowed-host` (see [Deployment and self-hosting](deployment.md)). If an
|
|
98
98
|
authenticating proxy sits in front of the board, let `POST /api/github/webhook` through without the login; the signature is what protects
|
|
99
99
|
it.
|
|
100
100
|
|