Compare commits
404 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
4d3b1e9f62 | ||
|
|
0c24e0e656 | ||
|
|
419e41fee5 | ||
|
|
ed17833ab7 | ||
|
|
b8487b028b | ||
|
|
1fb4254291 | ||
|
|
42ab223e79 | ||
|
|
358da17aeb | ||
|
|
4ef3aa1f90 | ||
|
|
3541c9bda3 | ||
|
|
5735e7c7d5 | ||
|
|
8fabf87b8a | ||
|
|
f1f284a0f9 | ||
|
|
e47d4ae6cf | ||
|
|
d6ac0aeb4b | ||
|
|
d8137c17d4 | ||
|
|
c1e8e57e29 | ||
|
|
7bd0eaaaee | ||
|
|
35c4081529 | ||
|
|
b729a8a605 | ||
|
|
73843dbf26 | ||
|
|
1d2e7e87fa | ||
|
|
8deb56ff0b | ||
|
|
31de2ff90f | ||
|
|
baba524caf | ||
|
|
1d481bb02d | ||
|
|
2dbee30530 | ||
|
|
980ba48764 | ||
|
|
9195bc4822 | ||
|
|
f1d22353ca | ||
|
|
9ff6e1a2e8 | ||
|
|
dce002ee45 | ||
|
|
fbbfce0702 | ||
|
|
e54be76cf0 | ||
|
|
54617f78d1 | ||
|
|
446a77efbf | ||
|
|
e0016e0c0d | ||
|
|
8751f92230 | ||
|
|
c4d0bbecc4 | ||
|
|
15d3e6fb8d | ||
|
|
cd91cf2e64 | ||
|
|
701ce8979d | ||
|
|
3a725469c6 | ||
|
|
13ab905f8d | ||
|
|
274dff4458 | ||
|
|
f4613fd26b | ||
|
|
6e8cead959 | ||
|
|
0aa38db8b5 | ||
|
|
b1f85c2177 | ||
|
|
75669b343f | ||
|
|
0bef6b3098 | ||
|
|
d00e2c8d6f | ||
|
|
a3ce097455 | ||
|
|
a9381165c7 | ||
|
|
eed91c821a | ||
|
|
a0dde086d2 | ||
|
|
ae13e4dd41 | ||
|
|
0e97113a4f | ||
|
|
be9170af53 | ||
|
|
f1cebf1d70 | ||
|
|
09a5338d9a | ||
|
|
d320733510 | ||
|
|
dcd0ae5338 | ||
|
|
093529d45c | ||
|
|
fdc2094ffc | ||
|
|
7a209dee9a | ||
|
|
1173a5c5a2 | ||
|
|
e114492bbe | ||
|
|
67f7164302 | ||
|
|
52c9c7eb18 | ||
|
|
9afe95ccef | ||
|
|
293400e61f | ||
|
|
b8c177fca8 | ||
|
|
9db6a66ca4 | ||
| 593f99ac70 | |||
| 5eb866b37a | |||
| fd51f1f523 | |||
| ed696bc74e | |||
| 31d019fcc5 | |||
| 1ae1a9553f | |||
| 45017039b2 | |||
| 52e854a19e | |||
| 275e70b42d | |||
| cd20540f13 | |||
| 659969b9ac | |||
| 1df2e31dea | |||
| e81cfde7b2 | |||
| 5f62cd6b92 | |||
| 95eed7ad98 | |||
| f232076531 | |||
| b8638aac66 | |||
| 8969806dc8 | |||
| 36f3410896 | |||
| d13340672f | |||
| aba512800e | |||
| 68e1d36fd5 | |||
| 48e87b7543 | |||
| db88fb15f2 | |||
| 3e29e6042e | |||
| 9975cf4b52 | |||
| 7e2c01172f | |||
| ee0bbc27f8 | |||
| 6e0d4bbca7 | |||
| 52204e171d | |||
| 9ea3159ba2 | |||
| da6bfa9e48 | |||
| 399ba5fb60 | |||
| 0c73c8d4f1 | |||
| 4fd2ed07eb | |||
| b996a8fc83 | |||
| 83f76cc3f7 | |||
|
|
7efb9ed7ad | ||
|
|
2acf8e46c4 | ||
|
|
7b25fcff55 | ||
|
|
1bfe0514f8 | ||
|
|
533d0d2fcd | ||
|
|
db86b51a51 | ||
|
|
2bf9081c1b | ||
|
|
935e4bf64f | ||
|
|
f8fa0f1b4b | ||
|
|
495319ee21 | ||
|
|
5df1ec27cf | ||
|
|
7e5d2c74af | ||
|
|
3198bbe1aa | ||
|
|
7819c6746c | ||
|
|
6f9b77033f | ||
|
|
a0242808a0 | ||
|
|
9232dc1048 | ||
|
|
a917966d31 | ||
|
|
99abe88b6a | ||
|
|
16a20088a3 | ||
|
|
8ebfedf64c | ||
|
|
609caa4f3f | ||
|
|
ef47baf0a1 | ||
|
|
aba678b196 | ||
|
|
5db032f52f | ||
|
|
928ae0097d | ||
|
|
c755209964 | ||
|
|
31acec420a | ||
|
|
d9d57c7411 | ||
|
|
8a600ca704 | ||
|
|
903859a131 | ||
|
|
9fa740e8b7 | ||
|
|
895248eef2 | ||
|
|
27c98bf22a | ||
|
|
5aa846c5e8 | ||
|
|
f9255272c0 | ||
|
|
1b1a553fb6 | ||
|
|
95cced94fc | ||
|
|
71dc0485ee | ||
|
|
8c6b3171a8 | ||
|
|
7490a310ce | ||
|
|
439a994aac | ||
|
|
7b8d205613 | ||
|
|
1846e98c0f | ||
|
|
7049dffd9a | ||
|
|
94c47268b5 | ||
|
|
6875627fdf | ||
|
|
201fd0fbf9 | ||
|
|
211687f439 | ||
|
|
ef164dda8e | ||
|
|
143b4dbdca | ||
|
|
8edc869963 | ||
|
|
6d14f71ae5 | ||
|
|
9c11b7064d | ||
|
|
6e99b1886a | ||
|
|
9d299a4455 | ||
|
|
5ce50bedfb | ||
|
|
9637100ffa | ||
|
|
fec697bb15 | ||
|
|
1f968994e1 | ||
|
|
0e951270aa | ||
|
|
a0ac2a1ee7 | ||
|
|
c2e56ef339 | ||
|
|
8d562004cb | ||
|
|
97abc77b14 | ||
|
|
133c3cfd1c | ||
|
|
c7a485177e | ||
|
|
3d72923617 | ||
|
|
fbe9816a50 | ||
|
|
eb8a0280ca | ||
|
|
513793a13d | ||
|
|
96750982f2 | ||
|
|
5905e2b2e8 | ||
|
|
7199b26bb7 | ||
|
|
c59b3e61ed | ||
|
|
81c81c0c7d | ||
|
|
298c81d701 | ||
|
|
e1d5110b29 | ||
|
|
617e15dcf0 | ||
|
|
0528e6661a | ||
|
|
5c0722429b | ||
|
|
1bb2ecf9cc | ||
|
|
3bfdc8616e | ||
|
|
d434b8ed19 | ||
|
|
835bf3f74c | ||
|
|
e9504b1ece | ||
|
|
e245b54ad9 | ||
|
|
00c8fac080 | ||
|
|
bd36b18729 | ||
|
|
80d03e741a | ||
|
|
122aa0786e | ||
|
|
eba9567614 | ||
|
|
1cc47f6d83 | ||
|
|
35d27d2e03 | ||
|
|
01a316a96c | ||
|
|
7bf3399a69 | ||
|
|
d581da5c92 | ||
|
|
3ce8a36742 | ||
|
|
145251481b | ||
|
|
335f8e608e | ||
|
|
0785336a50 | ||
|
|
2c67f46aee | ||
|
|
7e6c42638c | ||
|
|
d166f1c308 | ||
|
|
d2ce3a2c3b | ||
|
|
617eaef78e | ||
|
|
1e38cb2da2 | ||
|
|
dd6890e905 | ||
|
|
770aa1e216 | ||
|
|
94f3699cc4 | ||
|
|
b6180a7dac | ||
|
|
03fc292c8b | ||
|
|
21aa4e575f | ||
|
|
6ea43bb120 | ||
|
|
4cd35c9d66 | ||
|
|
561a56c768 | ||
|
|
399efed845 | ||
|
|
2035563fc7 | ||
|
|
8afc9bbc3e | ||
|
|
d1be8aa54d | ||
|
|
762f0ae9aa | ||
|
|
5da9387427 | ||
|
|
f3032950be | ||
|
|
a4b32b14e6 | ||
|
|
b113e12215 | ||
|
|
8a3ac87abb | ||
|
|
079ef3e61e | ||
|
|
6389479906 | ||
|
|
d50a1575ca | ||
|
|
0301dc2ae4 | ||
|
|
b40c519747 | ||
|
|
f1236743ae | ||
|
|
baa0f20eb2 | ||
|
|
00607d165d | ||
|
|
d6f490a9ab | ||
|
|
159cd5ecf4 | ||
|
|
2d28c9485c | ||
|
|
677e30f6f5 | ||
|
|
76288cd9e8 | ||
|
|
f6d4c67314 | ||
|
|
024fd82732 | ||
|
|
c739a7dd06 | ||
|
|
211be60648 | ||
|
|
65e0cdd1fa | ||
|
|
ba39bb1125 | ||
|
|
999054b0bd | ||
|
|
87921c27f6 | ||
|
|
a9237c8ec3 | ||
|
|
7b60c17138 | ||
|
|
75a0dea0a5 | ||
|
|
e6b3aa2222 | ||
|
|
754ab5423a | ||
|
|
7b193032c8 | ||
|
|
2f3eba0cb1 | ||
|
|
9977e31ac9 | ||
|
|
07673e4f30 | ||
|
|
9b72439533 | ||
|
|
60551485ed | ||
|
|
d30ef5de47 | ||
|
|
16318b0c4a | ||
|
|
06ac86409a | ||
|
|
74c8146c46 | ||
|
|
dfc6127009 | ||
|
|
bad273b753 | ||
|
|
df2ba57e7b | ||
|
|
a231309721 | ||
|
|
7de774b0b3 | ||
|
|
9109e5b139 | ||
|
|
b93a6de20e | ||
|
|
b5f1ed202a | ||
|
|
8e8e0642b0 | ||
|
|
13324e7f01 | ||
|
|
678eac4637 | ||
|
|
7e8a19399d | ||
|
|
c4b1ac4076 | ||
|
|
0418900122 | ||
|
|
b91eadb5b6 | ||
|
|
96a7012ece | ||
|
|
d024ab4bb8 | ||
|
|
8093587696 | ||
|
|
a462bf12c9 | ||
|
|
9b23e877a6 | ||
|
|
e7eda88ddd | ||
|
|
77ac19a57c | ||
|
|
69c1fea766 | ||
|
|
f1f1d55fa7 | ||
|
|
e8d3d724f5 | ||
|
|
4916ee3d43 | ||
|
|
51ec2f9daa | ||
|
|
ec6a1955fc | ||
|
|
824e3d5882 | ||
|
|
ac9f6db03e | ||
|
|
c48301ef7e | ||
|
|
4449066fa6 | ||
|
|
b651a67356 | ||
|
|
e51df97db8 | ||
|
|
0e5bb0c44f | ||
|
|
bac8e7ef22 | ||
|
|
83a952a74b | ||
|
|
545c0b4350 | ||
|
|
13aa5f3227 | ||
|
|
860c41d829 | ||
|
|
6c606c666b | ||
|
|
6b9becd994 | ||
|
|
653d95a5b9 | ||
|
|
8cb56a4c51 | ||
|
|
c8a22e3e84 | ||
|
|
75e19dc153 | ||
|
|
64452a4919 | ||
|
|
291b18fb1e | ||
|
|
4957e5ce25 | ||
|
|
ba8432cfb8 | ||
|
|
61d10436c7 | ||
|
|
202d38ba3c | ||
|
|
10fec478be | ||
|
|
2da42e93f9 | ||
|
|
bb7e14bce9 | ||
|
|
4914cade5a | ||
|
|
f3f87f3cc4 | ||
|
|
3520d5d480 | ||
|
|
f91d70d05e | ||
|
|
6efb9a4997 | ||
|
|
4d75695582 | ||
|
|
795c4f6b29 | ||
|
|
e34d113c80 | ||
|
|
6294ac4141 | ||
|
|
53c0a65a43 | ||
|
|
39c59b8329 | ||
|
|
8476a65aa0 | ||
|
|
825a3fd2da | ||
|
|
36092f542c | ||
|
|
ebdfd78ab4 | ||
|
|
6ea2cb70e0 | ||
|
|
8c9c967c88 | ||
|
|
1a487bc644 | ||
|
|
8bc18c90b6 | ||
|
|
70e4b4183c | ||
|
|
a95a014b52 | ||
|
|
a941ab2394 | ||
|
|
017e0e9a6a | ||
|
|
2bef465ecd | ||
|
|
d788d12785 | ||
|
|
341a3a51a1 | ||
|
|
b5a20996c1 | ||
|
|
1488276bd2 | ||
| 3cc42f5079 | |||
| 1468344460 | |||
| 040187deb9 | |||
| bba6539883 | |||
| 9094bf9ad9 | |||
| 06a144e19f | |||
| 23238ccd47 | |||
| 3f52b1ab49 | |||
| 415a09333b | |||
| 876f0f09f2 | |||
| 9e29d6ff9b | |||
| 63d05e8acb | |||
| 2cea3127cc | |||
| 8416f10849 | |||
| 200c664a4b | |||
| 41d145dde1 | |||
| f5931d5698 | |||
| 3938ebbddd | |||
| 1173f35f80 | |||
| 88fbfb7b39 | |||
| 0db030598e | |||
| bd23a82f22 | |||
| a7df0caaa3 | |||
| 14979e7009 | |||
| df2a0753c7 | |||
| 2cc3c1728b | |||
| 69d5a24fa8 | |||
| 2ac8663fe7 | |||
| 126c0866fc | |||
| b8aa5d881c | |||
| 7c4dbb1252 | |||
| adf5cccc4a | |||
| 6472f2861e | |||
| 9fe489084c | |||
| 175e469587 | |||
| 0e187cfb6a | |||
| 1583651783 | |||
| 468af06c86 | |||
| d660cd05fa | |||
| 5471b66b8f | |||
| 676ca539aa | |||
| 2b7174d406 | |||
| 1259f5bd1d | |||
| 32141f803a | |||
| 8b4817fa0a | |||
| cffa49642c | |||
| f098ffdbf9 | |||
| a9a7f58eed |
@@ -192,6 +192,7 @@ Validated in Phase 18.1: Payment Gateway Subscriptions
|
||||
| OIDC on wristband with golang-jwt v5, not zitadel/oidc (Phase 19.4, `notes/2026-10-19-oidc-on-wristband-golang-jwt.md`) | wristband already owned the OAuth flows and PHP-compatible encoding; zitadel's own storage and routing would fight both. go-oidc and x/oauth2 are test-only, for relying-party interop | ✓ Good (Phase 19.4 UAT, 2026-10-20) |
|
||||
| PHP OIDC parity is recorded at the WavePath cutover, not in Phase 19.4 (D-14 amended) | The harness ships and replays Go-side; recording needs the live PHP site, and WavePath's provider must not move until the replay is green | — Pending (todo `2026-10-19-record-php-oidc-parity-against-wavepath`) |
|
||||
| Administrators and Roles live in cabana as an internal pseudo-plugin; privilege rules run in the save transaction; contributed Administrators Runs are wrapped with `guardOutranked` | WinterCMS screens were missing and 19.7 needs the record-action seam; a delegated editor must not outrank the target or capture a code-declared role | ✓ Good (Phase 19.6.1 UAT 26/26, 2026-10-22) |
|
||||
| MCP OAuth advertises one scope list, puts the MCP subject on the request, and stores one consent row per user and client (Phase 32.1) | Declared member-token scopes join the wristband and pier lists; an empty wristband list stays the five fixed names. `Implies` expands only for OAuth MCP subjects. A decision replaces the stored scopes, revoke deletes that client's MCP codes, and the one-time backfill rolls back as a no-op | ✓ Good (framework v0.5.2, sm-oauthserver-plugin v0.1.4, sm-user-plugin v0.1.16; vue-oauth-layer v0.1.0 is local only, 2026-10-28) |
|
||||
|
||||
## Evolution
|
||||
|
||||
@@ -211,4 +212,4 @@ This document evolves at phase transitions and milestone boundaries.
|
||||
4. Update Context with current state
|
||||
|
||||
---
|
||||
*Last updated: 2026-10-22 after Phase 19.6.1 completion*
|
||||
*Last updated: 2026-10-28 after Phase 32.1 completion*
|
||||
|
||||
@@ -46,7 +46,9 @@ Decimal phases appear between their surrounding integers in numeric order.
|
||||
- [ ] **Phase 19.8: Console commands overhaul** - `diary` logging module, Artisan-grade global flags, help and `list` in `bonfire`, sweep of every command
|
||||
- [ ] **Phase 20: Demo instance with every shared plugin** - Add the chat family (chat, channels, video calls, chatbots, forum, herald, friends) to the live demo from Phase 19.4.1
|
||||
- [ ] **Phase 30: Płytarium cutover** - Parity harness green, both real clients run unchanged in production
|
||||
- [ ] **Phase 31: Chat polish against WavePath clients** - Replay WavePath's chat traffic through `tide` against the ported chat plugins until green
|
||||
- [ ] **Phase 31: Chat polish against WavePath clients** - `tide` additions, `sm-wavepath-app`, the full PHP recording of WavePath's community routes and the foundation slice green
|
||||
- [ ] **Phase 31.1: WavePath messaging parity** (INSERTED) - Group chat, channels, DMs, threads, commands and attachments replay green
|
||||
- [ ] **Phase 31.2: WavePath satellites parity and close-out** (INSERTED) - Presence, push, webhooks, bot, video, guests, forums and notes; zero pending
|
||||
|
||||
## Phase Details
|
||||
|
||||
@@ -1270,7 +1272,7 @@ Plans:
|
||||
3. An S3 blob driver can be selected through framework config, so the application does not import it. `/api-docs` and `/api-docs.json` can be served. Turnstile verification middleware is available.
|
||||
4. The touched modules' READMEs and `docs/` pages are updated. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 6/6 plans executed
|
||||
**Plans:** 8/9 plans executed
|
||||
|
||||
Plans:
|
||||
**Wave 1**
|
||||
@@ -1533,10 +1535,33 @@ Plans:
|
||||
3. The demo is deployed publicly: the frontend is open, `/backend` is not reachable from the public internet, and the site carries a "want to see the backend? contact Golem15" call to action.
|
||||
4. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 0 plans
|
||||
**Plans:** 6/6 plans executed
|
||||
|
||||
Plans:
|
||||
- [ ] TBD (run /msd-plan-phase 20 to break down)
|
||||
**Wave 1**
|
||||
- [x] 20-01-PLAN.md — shared plugin release: siblings fast-forwarded, chat and forum pre-save seams (D-18), new sm-moderation-plugin (D-17), go.mod fixes, eight tags after go-ahead
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
- [x] 20-02-PLAN.md — demo backend: oauthserver bump (folded todo), eight plugins mounted by tag, demo context and channel adapter, bootstrap endpoints, realtime for members, slash commands, moderation wiring, EN/PL seed and reset, Centrifugo namespaces, local LiveKit
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
- [x] 20-03-PLAN.md — vue-chat-layer v0.1.0 (bm port, channels, threads, pins, command picker, link embeds) and /chat, floating panel, Chat tour card in vue-demo-app
|
||||
|
||||
**Wave 4** *(blocked on Wave 3 completion)*
|
||||
- [x] 20-04-PLAN.md — vue-forum-layer, vue-userfriends-layer, vue-chatvideo-layer v0.1.0 (DM-only call button), their pages and tour cards, herald VAPID config without UI
|
||||
|
||||
**Wave 5** *(blocked on Wave 4 completion)*
|
||||
- [x] 20-05-PLAN.md — rome deploy: the demo's own LiveKit, Vuurmuur rule (checkpoint), nginx, .env keys, Centrifugo, release, DEPLOY.md, check-deploy and check-live
|
||||
|
||||
**Wave 6** *(blocked on Wave 5 completion)*
|
||||
- [x] 20-06-PLAN.md — unit tests (Go, layers, site), two-browser chat and DM call checks, phase gate and live verification
|
||||
|
||||
**Wave 7** *(gap closure, code review)*
|
||||
- [x] 20-07-PLAN.md — filter hardening (CR-02, CR-03): normalised text and canonical link hosts in sm-moderation-plugin, rendered-HTML check in sm-forum-plugin, bypass regression tests
|
||||
- [x] 20-08-PLAN.md — call and session fixes (CR-01, WR-01, WR-04, WR-05): useCall cancellation, join confirmation, failed-connect end, chat link guard, logout reset
|
||||
|
||||
**Wave 8** *(blocked on Wave 7 completion)*
|
||||
- [ ] 20-09-PLAN.md — release, redeploy and recheck: suites, patch tags, demo bumps, rome deploy, live bypass and call probes, changelog posts, disposition ledger
|
||||
|
||||
### Phase 30: Płytarium cutover
|
||||
|
||||
@@ -1556,22 +1581,86 @@ Plans:
|
||||
|
||||
### Phase 31: Chat polish against WavePath clients
|
||||
|
||||
**Goal:** The ported chat and chat satellites carry WavePath's chat traffic exactly as PHP does. The chat routes that WavePath's clients call are recorded with `tide`, replayed against the Go plugins and fixed until green, so that chat, the core feature of WavePath, is not the risk in the WavePath migration.
|
||||
**Goal:** WavePath's community traffic is recorded from the PHP backend with `tide` and replayed against a Go app, so that chat, the core feature of WavePath, is not the risk in the WavePath migration. This phase delivers the harness and the corpus: the `tide` additions, the `sm-wavepath-app` skeleton, the local PHP stack and scenario, the full PHP recording, and the foundation slice (groups, members, invites, friends, realtime authorization) ported and green. Phases 31.1 and 31.2 port the rest of the corpus (split at planning, 2026-11-13).
|
||||
**Mode:** mvp
|
||||
**Depends on:** Phase 19, Phase 19.1, Phase 30 (formerly Phase 19.2; moved 2026-10-18 so the `tide` recording is made just before the WavePath migration, while the PHP routes still move)
|
||||
**Repos:** `sm-chat-plugin`, `sm-chatchannels-plugin` and the satellite repos; `summercms.go` only for `lighthouse` or `tide` gaps
|
||||
**Depends on:** Phase 19, Phase 19.1 (formerly Phase 19.2; the Phase 30 dependency was sequencing only and is dropped, 31 D-05)
|
||||
**Repos:** `sm-wavepath-app` (new); `sm-chat-plugin`, `sm-chatchannels-plugin`, `sm-chatbots-plugin`, `sm-chatvideo-plugin`, `sm-forum-plugin`, `sm-herald-plugin`, `sm-userfriends-plugin`; `sm-user-plugin` (additive only); `summercms.go` only for `tide` or `lighthouse` gaps; `sm-demo-app`, `sm-bm-app` and the vue layers to follow shared-plugin changes; `sm-oauthserver-plugin` for the OIDC parity recording
|
||||
**Requirements**: TBD
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. A `tide` corpus of the chat, channel, thread, video-room and push routes, recorded from the PHP backend through `vue-wavepath-app`, `wavepath-mcp` and `hubot-wavepath`, replays green against the Go plugins.
|
||||
2. Realtime events on the `chat`, `video` and `presence:` namespaces match the PHP broadcasts recorded by the `tide` Centrifugo recorder.
|
||||
3. Behaviour stays neutral to the other consumers of these plugins (QuestStream, Horoskopia, Portal). Framework READMEs and docs still name no application.
|
||||
1. A `tide` corpus of the whole community surface (31 D-09: every route under `/_wave/api/v1/community`, the guest, push, bot and token routes and the webhook, 196 routes) is recorded from the PHP backend through `vue-wavepath-app` and `hubot-wavepath`, with hand-written cases for the routes no client calls, and replays green against PHP itself.
|
||||
2. Every writing case of the corpus has a broadcast golden with all publications PHP sent for it, on any namespace (31 D-10), and outbound vendor calls are recorded as upstream sidecars.
|
||||
3. The foundation slice (groups, members, invites, join, friends, realtime authorization) is `ported` in `sm-wavepath-app` and replays green, broadcasts included. A gate script reports the pending count of the remaining routes and fails closed.
|
||||
4. Behaviour stays neutral to the other consumers of these plugins: `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions (31 D-14). Framework READMEs and docs still name no application.
|
||||
5. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 11 plans
|
||||
|
||||
Plans:
|
||||
|
||||
**Wave 1**
|
||||
- [ ] 31-01-PLAN.md — Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference
|
||||
- [ ] 31-03-PLAN.md — `sm-wavepath-app` skeleton and fail-closed isolated PHP parity stack
|
||||
- [ ] 31-09-PLAN.md — Folded `vue-chat-layer` slash-command parity fix
|
||||
- [ ] 31-10-PLAN.md — Folded additive moderation seams for users, friend groups and attachment filenames
|
||||
|
||||
**Wave 2**
|
||||
- [ ] 31-02-PLAN.md — Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring
|
||||
- [ ] 31-08-PLAN.md — Folded OIDC PHP parity recording in `sm-oauthserver-plugin`
|
||||
|
||||
**Wave 3**
|
||||
- [ ] 31-04-PLAN.md — Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate
|
||||
|
||||
**Wave 4**
|
||||
- [ ] 31-05-PLAN.md — Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay
|
||||
|
||||
**Wave 5**
|
||||
- [ ] 31-06-PLAN.md — Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime
|
||||
|
||||
**Wave 6**
|
||||
- [ ] 31-07-PLAN.md — Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate
|
||||
|
||||
**Wave 7**
|
||||
- [ ] 31-11-PLAN.md — Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices
|
||||
|
||||
### Phase 31.1: WavePath messaging parity (INSERTED)
|
||||
|
||||
**Goal:** The messaging routes of the WavePath corpus recorded in Phase 31 replay green against Go: group chat, channels, direct messages, threads, commands, reactions, emoji, preferences, pins and attachments, including the attachment streaming delta with Range support (31 D-12) released in `sm-chat-plugin`.
|
||||
**Mode:** mvp
|
||||
**Depends on:** Phase 31
|
||||
**Repos:** `sm-wavepath-app`; the shared chat plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and the vue layers to follow
|
||||
**Requirements**: TBD
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. Every group chat, channel, DM, thread, command, reaction, emoji, preference, pin and attachment route of the corpus is `ported` with passing cases, and its broadcast goldens are asserted.
|
||||
2. Attachment downloads answer Range requests as PHP does (206, 416, `Accept-Ranges`), released as a `sm-chat-plugin` patch tag with a changelog post.
|
||||
3. `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions before each plugin tag (31 D-14).
|
||||
4. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 0 plans
|
||||
|
||||
Plans:
|
||||
- [ ] TBD (run /msd-plan-phase 31 to break down)
|
||||
- [ ] TBD (run /msd-plan-phase 31.1 to break down)
|
||||
|
||||
### Phase 31.2: WavePath satellites parity and close-out (INSERTED)
|
||||
|
||||
**Goal:** The rest of the WavePath corpus replays green against Go and the corpus closes at zero pending (31 D-15): presence and status, notifications and push, link unfurl, webhooks, bot REST with the token guard, search, video and guests, forums and shared notes (on a minimal, provisional diary read model).
|
||||
**Mode:** mvp
|
||||
**Depends on:** Phase 31.1
|
||||
**Repos:** `sm-wavepath-app`; the shared plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and the vue layers to follow
|
||||
**Requirements**: TBD
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. Every corpus route is `ported` with passing cases and every broadcast golden and upstream sidecar is asserted. The only non-matching cases are signed entries in the accepted-differences file (31 D-13).
|
||||
2. The fail-closed gate script in `sm-wavepath-app` passes at zero pending and checks that `sm-bm-app` and `sm-demo-app` build and pass (31 D-15).
|
||||
3. The security review of the app plugin (guest access, bot and token authentication, webhook, access resolvers) is done and its findings are resolved.
|
||||
4. The re-record with a drift report can be run unattended (31 D-06).
|
||||
5. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 0 plans
|
||||
|
||||
Plans:
|
||||
- [ ] TBD (run /msd-plan-phase 31.2 to break down)
|
||||
|
||||
### Phase 32: SEO foundation
|
||||
|
||||
@@ -1595,7 +1684,7 @@ Plans:
|
||||
4. Every SEO operation in the admin is available as an MCP tool, and a batch change can be previewed with dry-run and undone from history.
|
||||
5. The framework release with the seams is tagged, and the new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 5/6 plans executed
|
||||
**Plans:** 6/6 plans executed
|
||||
|
||||
Plans:
|
||||
**Wave 1**
|
||||
@@ -1614,7 +1703,36 @@ Plans:
|
||||
- [x] 32-05-PLAN.md — /_seo/api/v1 management API and MCP tools, batch dry-run, undo, CSV, demo mount proof, check-phase32.sh
|
||||
|
||||
**Wave 6** *(blocked on Wave 5 completion)*
|
||||
- [ ] 32-06-PLAN.md — unit tests, additive and compat proof, framework patch release, plugin tags, demo mount, changelog
|
||||
- [x] 32-06-PLAN.md — unit tests, additive and compat proof, framework patch release, plugin tags, demo mount, changelog
|
||||
|
||||
### Phase 32.1: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (INSERTED)
|
||||
|
||||
**Goal:** As an application whose plugins declare their own member token scopes, I want an agent connected to `/mcp` over OAuth to get the same tools, attribution and revocation as one using a personal token, so that OAuth sign-in can be switched on in production. A consuming app's agent-access work found three gaps (its D-36, D-37 and D-38); all three are additive and ship as patch releases of the framework (0.5.x) and `sm-oauthserver-plugin`.
|
||||
**Requirements**: TBD
|
||||
**Depends on:** Phase 19.4 (OIDC provider on wristband), Phase 19.7 (generic MCP module)
|
||||
**Plans:** 5/5 plans complete
|
||||
|
||||
**Success Criteria** (what must be TRUE):
|
||||
1. Scopes a plugin declares through `pact.HasFrontendTokenScopes` can be requested, consented to and granted over MCP OAuth: the wristband metadata and authorize allow-list and pier's protected-resource scopes include them, so a tool route behind `user.scope:<declared>` lists and runs for an OAuth agent granted that scope. Today the list is fixed to `read`, `write`, `ai`, `offline_access` (and `backend`).
|
||||
2. A route run by an MCP tool call can read the MCP subject (guard, user, client ID, token id) from its request context through an accessor, so an application records the OAuth client of a write; a personal-token call's credential keeps carrying the token id (sm-user-plugin v0.1.14).
|
||||
3. `sm-oauthserver-plugin` records a consent for MCP grants, so the existing per-client revoke ends one agent's grant and its MCP sessions without touching the user's other agents.
|
||||
4. Module READMEs and `docs/` pages describe the three changes; the framework and `sm-oauthserver-plugin` get patch tags.
|
||||
|
||||
Plans:
|
||||
**Wave 1**
|
||||
- [x] 32.1-01-PLAN.md — Framework seam: catalog, MCPCall, one advertised scope list
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
- [x] 32.1-02-PLAN.md — sm-user-plugin from v0.1.14: publish the catalog and Implies for OAuth subjects
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
- [x] 32.1-03-PLAN.md — sm-oauthserver-plugin: consent replace, revoke, backfill
|
||||
|
||||
**Wave 4** *(blocked on Wave 3 completion)*
|
||||
- [x] 32.1-04-PLAN.md — vue-oauth-layer /connect checkboxes
|
||||
|
||||
**Wave 5** *(blocked on Wave 4 completion)*
|
||||
- [x] 32.1-05-PLAN.md — Unit tests, then the release checkpoint
|
||||
|
||||
### Phase 33: SEO output, audit and content
|
||||
|
||||
@@ -1640,10 +1758,78 @@ Plans:
|
||||
3. The crawler reports SEO issues per URL, and each issue can be fixed through MCP.
|
||||
4. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 0 plans
|
||||
**Plans:** 16/16 plans executed
|
||||
|
||||
Plans:
|
||||
- [ ] TBD (run /msd-plan-phase 33 to break down)
|
||||
**Wave 1**
|
||||
- [x] 33-01-PLAN.md — framework: additive content descriptor fields and per-request field options, check-phase33.sh, v0.5.2 release log (no tag)
|
||||
- [x] 33-07-PLAN.md — vue-seo-layer (new repository): CMS head and one JSON-LD graph, redirect/410 enforcement, root files, 404 report, shared purge route
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
- [x] 33-02-PLAN.md — sm-journal-plugin: per-site H1 setting on every write path, editor J1–J4, descriptor facts, journal-author type, MCP tools
|
||||
- [x] 33-03-PLAN.md — sm-sitemap-plugin: sitemap index with per-type files, slot table, real lastmod, hreflang, filter contract (breaking, D-32)
|
||||
- [x] 33-08-PLAN.md — vue-seo-layer: SSR build guard, noindex routes, route report, drift check, breadcrumbs, pagination, HTML sitemap
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
- [x] 33-04-PLAN.md — sm-sitemap-plugin: image and News sitemaps, IndexNow, HTML-sitemap API, MCP tools
|
||||
- [x] 33-09-PLAN.md — journal, menu and FAQ layers on the SEO layer: headings in both H1 modes, one link per card, body links, breadcrumbs, pagination, related posts
|
||||
|
||||
**Wave 4** *(blocked on Wave 3 completion)*
|
||||
- [x] 33-05-PLAN.md — sm-seo-plugin I: sitemap filter, page registry with route report, site endpoint, llms.txt, Links settings, purge after writes
|
||||
|
||||
**Wave 5** *(blocked on Wave 4 completion)*
|
||||
- [x] 33-06-PLAN.md — sm-seo-plugin II: JSON-LD @graph, publisher, schema fields (E8/E9), breadcrumbs, hreflang, pagination; chromedp and webp legitimacy checkpoint
|
||||
|
||||
**Wave 6** *(blocked on Wave 5 completion)*
|
||||
- [x] 33-10-PLAN.md — sm-seo-plugin: crawler with optional rendered comparison (chromedp), issue report with fix routes, Site audit and Crawls, MCP tools
|
||||
|
||||
**Wave 7** *(blocked on Wave 6 completion)*
|
||||
- [x] 33-11-PLAN.md — internal linking and media: auto-links, link suggestions (E10), WebP variants with srcset
|
||||
|
||||
**Wave 8** *(blocked on Wave 7 completion)*
|
||||
- [x] 33-12-PLAN.md — apps I: demo end to end on local links, summercms.io patches, sm-bm-app noindex (D-72)
|
||||
- [x] 33-13-PLAN.md — grzybyfunkcjonalne.pl on the new sitemap format and the SEO layer; uat deploy by decision
|
||||
|
||||
**Wave 9** *(blocked on Wave 8 completion)*
|
||||
- [x] 33-14-PLAN.md — unit tests, check-phase33.sh --all, release tags in order, app re-pins, changelog post
|
||||
|
||||
**Wave 10** *(gap closure after the 33-14 release checkpoint; 33-14 Task 4 resumes after both)*
|
||||
- [x] 33-15-PLAN.md — Go plugins: route report noindex paths and the filter (G1), Journal descriptors per translated locale (G3), crawl lifecycle and addresses, sitemap IndexNow/lock/lastmod/migration/headings, Journal content fixes
|
||||
- [x] 33-16-PLAN.md — Nuxt layers: route report noindex paths (G1), HTML sitemap pages (redirect, catch-all, i18n), root files 503, post article meta, journal pagination routes, link: release guard and versions
|
||||
|
||||
### Phase 34: Plugin marketplace
|
||||
|
||||
**Goal:** People browse the public Golem15 plugins at summercms.io/marketplace and add one to their application with a single command, `summer plugin:install <id>`. The same command installs private plugins straight from a git URL without contacting summercms.io. The admin SPA gains a read-only Plugins screen listing installed plugins and searching the marketplace, which shows the install command with a copy button. v1 has no paid plugins, no developer registration and no installs from the admin panel.
|
||||
**Requirements**: TBD
|
||||
**Depends on:** Nothing technical; ordered after Phase 33
|
||||
**Repos:** `summercms.go` (manifest spec and validation, `plugin:install`, cabana Plugins screen and boardwalk views), `sm-summercmsio-app` and its `golem15.summercms` site plugin (registry API, ingestion, admin presentation fields), `vue-summercmsio-app` (marketplace pages), and a `plugin.yaml` in each public `sm-*-plugin` repo.
|
||||
**Context:** decisions in `.planning/notes/2026-10-29-plugin-marketplace.md`; open question on `--module` for private git URLs in `.planning/research/questions.md`.
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
1. Every public `sm-*-plugin` repo carries a `plugin.yaml` manifest (ID, module path, name, description, required framework version, required plugins) that the framework validates, and anyone can fetch the repo anonymously.
|
||||
2. summercms.io ingests manifest, README and versions when a plugin is tagged, serves them through a registry API, and renders /marketplace with list, search, category and detail pages; category, featured, screenshots and icon are edited in the summercms.io admin.
|
||||
3. `summer plugin:install golem15.<name>` resolves the plugin through the registry and installs it as a Go module (`--source` checks it out as a submodule); `summer plugin:install <git-url>` installs from the repo alone as a submodule. Both register the plugin like `plugin:add` and check framework and plugin requirements.
|
||||
4. The admin Plugins screen lists installed plugins with versions and available updates, and its Marketplace tab searches the registry and shows the install command with a copy button.
|
||||
5. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 6/6 plans executed
|
||||
|
||||
Plans:
|
||||
**Wave 1**
|
||||
- [x] 34-01-PLAN.md — kiosk module: plugin.yaml format, `summer plugin:manifest [--check]`, const-resolving ID reader, registry v1 wire types, PluginInfo/FrameworkVersion baked by summer build (wave 1)
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
- [x] 34-03-PLAN.md — summercms.io registry: tables, pull ingester, /api/registry/v1, admin curation, `registry` scope ingest-now, hourly schedule, /marketplace pages, deploy, changelog-post.py hooks (wave 2)
|
||||
- [x] 34-04-PLAN.md — `summer plugin:install` (module, --source, git URL) and `summer plugin:update`, `plugins.registry_url`, go.work overrides (wave 2)
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
- [x] 34-05-PLAN.md — admin Plugins screen: cabana endpoints, backend.view_plugins, Installed + Marketplace tabs with copy, openapi and dist (wave 3)
|
||||
|
||||
**Wave 4** *(blocked on Wave 3 completion)*
|
||||
- [x] 34-02-PLAN.md — plugin.yaml and TestPluginManifest in every public sm-*-plugin repo, framework minimum v0.6.0, app pointer bumps after Jakub's push (wave 4)
|
||||
|
||||
**Wave 5** *(blocked on Wave 4 completion)*
|
||||
- [x] 34-06-PLAN.md — unit tests across all repos, scripts/check-phase34.sh, release ledger and validation map (wave 5)
|
||||
|
||||
## Progress
|
||||
|
||||
@@ -1695,11 +1881,12 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
|
||||
| 19.6.1. Backend Administrators screen (INSERTED) | 5/5 | Complete | 2026-10-22 |
|
||||
| 19.7. Generic MCP module | 9/9 | In Progress| |
|
||||
| 19.8. Console commands overhaul (INSERTED) | 6/6 | In Progress| |
|
||||
| 20. Demo instance with every shared plugin | 0/TBD | Not started | - |
|
||||
| 20. Demo instance with every shared plugin | 6/6 | In Progress| |
|
||||
| 30. Płytarium cutover | 0/TBD | Not started | - |
|
||||
| 31. Chat polish against WavePath clients | 0/TBD | Not started | - |
|
||||
| 32. SEO foundation | 5/6 | In Progress| |
|
||||
| 33. SEO output, audit and content | 0/TBD | Not started | - |
|
||||
| 32. SEO foundation | 6/6 | In Progress| |
|
||||
| 33. SEO output, audit and content | 16/16 | In Progress| |
|
||||
| 34. Plugin marketplace | 6/6 | In Progress| |
|
||||
|
||||
## Backlog
|
||||
|
||||
@@ -1723,3 +1910,58 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
|
||||
|
||||
Plans:
|
||||
- [ ] TBD (promote with /gsd-review-backlog when ready)
|
||||
|
||||
### Phase 999.2: SEO follow-ups after Phase 33, for v0.6.2 (BACKLOG)
|
||||
|
||||
**Goal:** Clear what Phase 33 deferred:
|
||||
- the journal-tag drift warning while tag pages are off (G2), which needs an additive ContentDescriptor field such as `Routable` and signpost.Activate accepting a type without a URL pattern;
|
||||
- the deferred warnings and info items in 33-REVIEW.md and 33-REVIEW-GAPFIX.md, listed under "Deferred" in 33-15 and 33-16:
|
||||
- sitemap: types sharing a group slug, no 50 MB byte guard, Additional addresses on another host;
|
||||
- seo: long crawls held in memory and running past the job timeout, recheck inside an open transaction;
|
||||
- journal layer: card image `sizes`, the sitemap group home crumb;
|
||||
- journal plugin: the author login in URLs, the alt batch with locale "" next to the default locale, the settings API's own url check;
|
||||
- a post-release mode for `check-phase33.sh --consumers`;
|
||||
- the grzyby DEPLOY.md Verify line expecting `X-Robots-Tag: index, follow`;
|
||||
- a decision for untranslated locale addresses, which still serve default-locale content under their own canonical: point the canonical at the default locale, or answer 404.
|
||||
|
||||
**Requirements:** TBD
|
||||
**Plans:** 0 plans
|
||||
|
||||
Plans:
|
||||
- [ ] TBD (promote with /msd-review-backlog when ready)
|
||||
|
||||
### Phase 35: Mail templates and layouts editor
|
||||
|
||||
**Goal:** Administrators edit every mail the application sends from the admin panel, as in WinterCMS's Mail templates screen. System mail and the templates plugins register through `pact.HasMailTemplates` appear in a list. Each template can get a database override of its subject and body, and the override can be reset to the file version. Layouts become admin-editable records assigned to templates, with a few predefined layouts seeded. Images can be uploaded and placed in layouts and templates. postcard renders the override when one exists, otherwise the plugin's file, so mail that already works keeps working.
|
||||
**Requirements**: TBD
|
||||
**Depends on:** Phase 34
|
||||
**Context:** postcard already loads plugin templates and layouts from `views/mail/` (`pact.HasMailTemplates`, `postcard.BootPlugin`); this phase adds the editable database layer, admin screens and image handling on top. To confirm in discussion: partials (WinterCMS mail partials), preview and test send, per-locale variants, and whether the screens live in cabana or in a plugin.
|
||||
**Plans:** 9/9 plans complete
|
||||
|
||||
Plans:
|
||||
**Wave 1**
|
||||
- [x] 35-01-PLAN.md — pact `HasMailPartials`, postcard-owned mail tables and migrations, per-send override lookup with file fallback, partials, sample vars, Branding CSS, index sync, Editor API, docs
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
- [x] 35-02-PLAN.md — cabana Settings → Mail screens, two permission codes, reset/delete rules, drift notice and diff, server field types, preview and own-address test send, OpenAPI, en/pl copy
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
- [x] 35-03-PLAN.md — admin SPA: CodeMirror decision note and checkpoint, codeeditor/colour/image fields, image picker, mail preview and test send, rebuilt dist
|
||||
|
||||
**Wave 4** *(blocked on Wave 3 completion)*
|
||||
- [x] 35-04-PLAN.md — unit tests for the D-21 list and `scripts/check-phase35.sh` (incl. user and paymentgateway mail tests)
|
||||
|
||||
**Wave 5** *(gap closure G-35-1, blocked on Wave 4 completion)*
|
||||
- [x] 35-05-PLAN.md — one admin record per mail template with a locale switcher, fallback-locale versions, send resolution of `<template>-<locale>`, decision note superseding D-05
|
||||
|
||||
**Wave 6** *(gap closure G-35-8, blocked on Wave 5 completion)*
|
||||
- [x] 35-06-PLAN.md — finished default/system/minimal layouts (logo or site name header, card, footer), Branding site name, CSS inlining via go-premailer with a per-layout opt-out, decision note superseding D-10
|
||||
|
||||
**Wave 7** *(gap closure, blocked on Wave 6 completion)*
|
||||
- [x] 35-07-PLAN.md — unit tests for both gaps and `scripts/check-phase35.sh` with a read-only scratch-modfile consumers stage
|
||||
|
||||
**Wave 8** *(gap closure CR-01, blocked on Wave 7 completion)*
|
||||
- [x] 35-08-PLAN.md — URL-scheme check on decoded attribute values instead of the whole document, a site name never stops a send (dropped with a warning) and an unsafe one is refused on the Branding form, the inlined result never stops mail, literal footer (CR-01, WR-01, WR-05), decision note
|
||||
|
||||
**Wave 9** *(gap closure tests, blocked on Wave 8 completion)*
|
||||
- [x] 35-09-PLAN.md — regression and unit tests for CR-01, WR-01 and WR-05, new names required by `scripts/check-phase35.sh` (plus the IN-03 self-test fix), validation map
|
||||
|
||||
@@ -1,19 +1,20 @@
|
||||
---
|
||||
msd_state_version: "1.0"
|
||||
milestone: v1.0
|
||||
current_phase: "19.7"
|
||||
current_phase_name: Generic MCP module (INSERTED)
|
||||
status: verifying
|
||||
stopped_at: Phase 32 context gathered
|
||||
last_updated: "2026-10-25T21:26:24.117Z"
|
||||
last_activity: 2026-10-23
|
||||
last_activity_desc: "Completed 19.7-08: plugin gap closure, E-1 logo, E-2 member token scopes; paused before 19.7-09"
|
||||
state_head: 9a76c7ec1c0c17e93e00086231af78648eb40c43
|
||||
current_phase: 30
|
||||
current_phase_name: Płytarium cutover
|
||||
status: planning
|
||||
stopped_at: Phase 35 complete, ready to plan Phase 30
|
||||
last_updated: "2026-11-16T09:05:22.965Z"
|
||||
last_activity: 2026-11-16
|
||||
last_activity_desc: Phase 35 complete (UAT 14/14), transitioned to Phase 30
|
||||
state_head: 0c24e0e656c7bbb218e97abeeb8b1ccc43bbc97b
|
||||
progress:
|
||||
total_phases: 47
|
||||
total_phases: 52
|
||||
completed_phases: 37
|
||||
total_plans: 242
|
||||
completed_plans: 238
|
||||
total_plans: 304
|
||||
completed_plans: 293
|
||||
percent: 77
|
||||
gsd_state_version: "1.0"
|
||||
milestone_name: milestone
|
||||
---
|
||||
@@ -25,22 +26,22 @@ milestone_name: milestone
|
||||
See: .planning/PROJECT.md (updated 2026-10-22)
|
||||
|
||||
**Core value:** An existing WinterCMS-shaped app can be ported plugin by plugin to a single Go binary without its frontend noticing: the PHP version's API contract is the acceptance test.
|
||||
**Current focus:** Phase 19.7 — Generic MCP module (INSERTED)
|
||||
**Current focus:** Phase 35 — Mail templates and layouts editor
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 19.7 (Generic MCP module (INSERTED)) — EXECUTING
|
||||
Plan: 5 of 5
|
||||
Status: Phase complete — ready for verification
|
||||
Last activity: 2026-10-23 — Phase 19.7 execution started
|
||||
Phase: 30 — Płytarium cutover
|
||||
Plan: Not started
|
||||
Status: Ready to plan
|
||||
Last activity: 2026-11-16 — Phase 35 complete (UAT 14/14), transitioned to Phase 30
|
||||
|
||||
Progress: [████████░░] 82%
|
||||
Progress: [████████░░] 77%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
|
||||
- Total plans completed: 115
|
||||
- Total plans completed: 124
|
||||
- Average duration: 21 min
|
||||
- Total execution time: 104 min
|
||||
|
||||
@@ -68,6 +69,7 @@ Progress: [████████░░] 82%
|
||||
| 19.4 | 4 | - | - |
|
||||
| 19.5 | 5 | - | - |
|
||||
| 19.6.1 | 5 | - | - |
|
||||
| 35 | 9 | - | - |
|
||||
|
||||
**Recent Trend:**
|
||||
|
||||
@@ -278,6 +280,50 @@ Progress: [████████░░] 82%
|
||||
| Phase 19.6.1 P05 | 4 min | 2 tasks | 7 files |
|
||||
| Phase 19.7 P01 | 52 min | 5 tasks | 64 files |
|
||||
| Phase 19.7 P02 | 38 min | 4 tasks | 36 files |
|
||||
| Phase 19.6 P01 | 61min | 5 tasks | 33 files |
|
||||
| Phase 19.6 P02 | 25min | 3 tasks | 47 files |
|
||||
| Phase 19.6 P03 | 100min | 6 tasks | 52 files |
|
||||
| Phase 19.6 P04 | 96 min | 6 tasks | 40 files |
|
||||
| Phase 32 P01 | 32 min | 4 tasks | 17 files |
|
||||
| Phase 32 P02 | 37 min | 4 tasks | 34 files |
|
||||
| Phase 32 P03 | 48 min | 5 tasks | 89 files |
|
||||
| Phase 32 P04 | 43 min | 4 tasks | 66 files |
|
||||
| Phase 32 P05 | 45 min | 4 tasks | 51 files |
|
||||
| Phase 32 P06 | 1h 25m | 5 tasks | 47 files |
|
||||
| Phase 32.1 P01 | 12 min | 3 tasks | 18 files |
|
||||
| Phase 32.1 P02 | 17 min | 2 tasks | 6 files |
|
||||
| Phase 32.1 P03 | 24 min | 4 tasks | 17 files |
|
||||
| Phase 32.1 P04 | 14 min | 2 tasks | 13 files |
|
||||
| Phase 34 P01 | 22 min | 5 tasks | 44 files |
|
||||
| Phase 34 P03 | 51 min | 4 tasks | 70 files |
|
||||
| Phase 34 P04 | 34 min | 4 tasks | 14 files |
|
||||
| Phase 34 P05 | 28min | 3 tasks | 33 files |
|
||||
| Phase 34 P02 | 25min | 5 tasks | 82 files |
|
||||
| Phase 34 P06 | 40min | 5 tasks | 25 files |
|
||||
| Phase 33 P01 | 22 min | 4 tasks | 19 files |
|
||||
| Phase 33 P07 | 25min | 4 tasks | 57 files |
|
||||
| Phase 33 P02 | 60 min | 4 tasks | 63 files |
|
||||
| Phase 33 P03 | 43min | 4 tasks | 78 files |
|
||||
| Phase 33 P08 | 27min | 3 tasks | 68 files |
|
||||
| Phase 33 P04 | 30min | 3 tasks | 38 files |
|
||||
| Phase 33 P05 | 70min | 3 tasks | 61 files |
|
||||
| Phase 33 P09 | 51min | 4 tasks | 88 files |
|
||||
| Phase 33 P06 | 105min | 4 tasks | 45 files |
|
||||
| Phase 33 P10 | 75min | 4 tasks | 65 files |
|
||||
| Phase 33 P11 | 75min | 4 tasks | 72 files |
|
||||
| Phase 33 P12 | 50min | 3 tasks | 12 files |
|
||||
| Phase 33 P13 | 105min | 4 tasks | 6 files |
|
||||
| Phase 33 P16 | 19min | 4 tasks | 41 files |
|
||||
| Phase 33 P15 | 2h15m | 6 tasks | 70 files |
|
||||
| Phase 35 P01 | 55 min | 5 tasks | 30 files |
|
||||
| Phase 35 P02 | 77 | 4 tasks | 66 files |
|
||||
| Phase 35 P03 | 22min | 6 tasks | 47 files |
|
||||
| Phase 35 P04 | 90 | 4 tasks | 40 files |
|
||||
| Phase 35 P05 | 28 min | 3 tasks | 29 files |
|
||||
| Phase 35 P06 | 33 min | 3 tasks | 34 files |
|
||||
| Phase 35 P07 | 49 min | 3 tasks | 11 files |
|
||||
| Phase 35 P08 | 24 min | 3 tasks | 22 files |
|
||||
| Phase 35 P09 | 31min | 3 tasks | 6 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -317,6 +363,11 @@ Progress: [████████░░] 82%
|
||||
- Phase 32 added: SEO foundation: per-record and global SEO, structured data per page type, sitemap boost and HTML sitemap, pagination, redirects, robots.txt, canonical, meta robots, social tags, headings, hreflang, noindex policy, SSR for headless frontends
|
||||
- Phase 32 edited: narrowed to framework seams and sm-seo-plugin core (split decided 2026-10-25)
|
||||
- Phase 33 added: SEO output, audit and content; large phase, lean-planning exception
|
||||
- Phase 32.1 inserted after Phase 32: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (requested by a consuming app's agent-access work) (URGENT)
|
||||
- Phase 34 added: Plugin marketplace: summercms.io/marketplace, summer plugin:install (registry ID or git URL), read-only admin Plugins screen
|
||||
- Phase 35 added: Mail templates and layouts editor: DB overrides of plugin-registered mail, editable seeded layouts, images; integer phase so follow-ups land as 35.x
|
||||
- Phase 31.1 inserted after Phase 31: Phase 31 split at planning (2026-11-13): messaging routes of the WavePath community corpus
|
||||
- Phase 31.2 inserted after Phase 31: Phase 31 split at planning (2026-11-13): satellites, zero-pending gate (31 D-15) and security review
|
||||
|
||||
### Decisions
|
||||
|
||||
@@ -954,6 +1005,134 @@ Recent decisions affecting current work:
|
||||
- [Phase 19.7]: Once the user confirms all in-flight msd-quick tasks are finished: release the framework as the next v0.4.x patch (carrying the quick patches and 19.7 work so far) and tag the held user-plugin fixes; plugins may be tagged mid-phase. Framework v0.5.0 stays reserved for full MCP usability at phase 19.7 completion — User decision 2026-10-23: plugins can be tagged now, framework 0.5 means the MCP phase is finished; wait for the user's word that the last quick agent is done
|
||||
- [Phase 19.7]: 19.7-02: pier serves 2025-11-25 clients through its own session router over StreamableServerTransport (Redis-shared sessions, D-25) and 2026-07-28 clients through the SDK stateless handler; plan 02 closed without a tag, pier ships opt-in in v0.4.4 (summercms_mcp tag plus mcp.enabled, default off)
|
||||
- [Phase 19.7]: Released framework v0.4.4 (e2759d6, changelog id 39) and sm-user-plugin v0.1.9 (3828a65; requires v0.4.3); sm-demo-app bumped to user v0.1.9 locally (a25444e, unpushed). Other apps not bumped yet — User go-ahead 2026-10-23 after all quick tasks finished; all release gates green at e2759d6
|
||||
- [Phase 19.6]: 19.6-01: sm-user-plugin seams built on v0.1.11 (origin/master 50da92c), not v0.1.5; plan 04's additive check uses base 50da92c
|
||||
- [Phase 19.6]: 19.6-01: the D-07 password-change hook is the existing classes.AccessRevokedEvent (fired in-transaction by reset, change and admin set) with the new (*AccessRevokedEvent).PasswordChanged(); no separate PasswordChangedEvent. sm-mfa-plugin (plan 02) listens to AccessRevokedEvent
|
||||
- [Phase 19.6]: 19.6-01: device table migration ID is 202610260001_create_device_auth_sessions (after 202610220001 backend links); golem15.user.frontend_url is reused, new keys golem15.user.device_auth.auth_url and .ttl_minutes
|
||||
- [Phase 19.6]: 19.6-02: sm-mfa-plugin listens on AccessRevokedEvent with PasswordChanged() for D-07 and deletes trusted devices in the password write's transaction
|
||||
- [Phase 19.6]: 19.6-02: failure cap ignores the caller's in-flight attempt (FailureCapReached inFlight), TOTP step acceptance is a guarded UPDATE in the completion transaction
|
||||
- [Phase 19.6]: 19.6-02: sm-mfa-plugin migrations 202610220001..05; 202610220006 reserved for plan 03 WebAuthn credentials
|
||||
- [Phase 19.6]: 19.6-03: sm-demo-app mounts golem15.mfa v0.1.0 (optional, totp and email, social sign-ins unchallenged, no webauthn on the demo); the private sm-mfa-plugin repo means the demo's module-mode release build needs git.golem15.com credentials or a public repo (deferred, user decides)
|
||||
- [Phase 19.6]: An empty mfa settings list falls back to the configuration (sm-mfa-plugin 71d8f27, released as v0.1.1)
|
||||
- [Phase 19.6]: Finding F-1 (activate-by-code skips the second factor when require_activation is off) deferred by the user; todo 2026-10-26-activate-by-code-second-factor
|
||||
- [Phase 32]: D-91 Go shape is the yaml-document form: AdminFormExtension.Fields (AdminFS path) or FieldsYAML (bytes built at boot) carries a fields.yaml-format document with before:/after:/zone: and a tabs: list; pact.AdminFormTab/AdminFormField are not published
|
||||
- [Phase 32]: Form extension Hide is static for every administrator; Permissions/Visible gate the extension's own fields on schema, show and save
|
||||
- [Phase 32]: Form extension Save runs after the owner's FormAfter* hooks in the save transaction on every create/update of a visible extension; Load runs on show and in the save response
|
||||
- [Phase 32]: 32-02: D-92/D-93 Go shapes adopted as planned (P-07 to P-10, incl. optional Match/MatchPath)
|
||||
- [Phase 32]: 32-02: RecordChange.Locale empty = record's own row; no-op saves fire with empty Changes; reorder fires per moved node
|
||||
- [Phase 32]: 32-02: signpost MatchPath = first exact match in registration order, else first inexact; Records without func = empty page
|
||||
- [Phase 32]: 32-02: journal-tag with golem15.journal.tag_pages false resolves to nothing, empty URLs, never matches
|
||||
- [Phase 32]: 32-04: redirect writes go through one service path (SaveRedirect, AddressChanged, ResolveNotFound) with a save-time loop simulation; resolve is the one-hop redirect decision (normalisation, redirects, strict URLs, then SEO)
|
||||
- [Phase 32]: 32-04: the robots.txt editor, tester and AI bot switches are fields of the plugin's own form extension on golem15.seo.robots, because an owner-form widget may fill built-in scalar fields only
|
||||
- [Phase 32]: SEO management API: every admin operation is an MCP tool on a /_seo/api/v1 route with golem15.seo.manage; AdminOperations + parity test guard drift
|
||||
- [Phase 32]: Batches run in one transaction with per-change savepoints; dry run rolls back, a refused change refuses the whole batch
|
||||
- [Phase 32]: Undo restores through the service with undo_stale/undo_loop/undo_gone guards; an undo is itself a revision
|
||||
- [Phase 32]: Import apply token: gzip file + fingerprint signed with HMAC-SHA256 under an app.key-derived key; apply re-runs the preview (transfer.stale)
|
||||
- [Phase 32]: Demo mount waits for the plugin tag: 32-05-demo-mount.patch carries the mount and the two demo SEO tests for plan 32-06
|
||||
- [Phase 32]: Released SummerCMS v0.5.1, sm-journal-plugin v0.2.5 and sm-seo-plugin v0.1.0 (pushed); sm-demo-app mounts golem15.seo v0.1.0 (pushed, not deployed)
|
||||
- [Phase 32]: check-phase32 additive stage compares with the newest tag not containing HEAD, so a post-release run compares with the previous release
|
||||
- [Phase 32.1]: Empty MCP Options.ScopesSupported resolves to read, write, ai, offline_access, backend; a non-empty list, including DefaultOptions, is used as given
|
||||
- [Phase 32.1]: Advertised scopes are pact.MCPAdvertisedScopes, not a new method on pact.MCPTokenVerifier
|
||||
- [Phase 32.1]: Stateless tool calls set callInfo.stateless so MCPCall.SessionID stays empty
|
||||
- [Phase 32.1]: Implies tests live in the sm-user-plugin root package so go test . runs them
|
||||
- [Phase 32.1]: OAuth Implies tests load a principal from an in-memory SQL driver so go test -short does not skip
|
||||
- [Phase 32.1]: 32.1-03 backfill is write-noop-rollback: live MCP grants get a consent row, and Rollback returns nil so a down migration does not delete consents created later.
|
||||
- [Phase 32.1]: vue-oauth-layer /connect locks read in the UI, omits scopes when consent is already stored, and refetches on 409 backend_link_changed. The new repo is on main with no remote and no tag.
|
||||
- [Phase 34]: kiosk module: plugin.yaml format, registry v1 wire types and version rules exist once in Go; Task 1 answered as-planned (P34-01..P34-04, v0.6.0 framework minimum)
|
||||
- [Phase 34]: kiosk.ReadIdentity resolves constant plugin IDs statically (go/parser + go list -m), shared with plugin:add
|
||||
- [Phase 34]: summer build bakes PluginInfo and FrameworkVersion into plugins.gen.go; generated main calls party.Describe before Activate; metadata failures warn and fall back to IDs
|
||||
- [Phase 34]: 34-03: the registry API encodes only kiosk wire types; ingest-now and admin live in the site plugin golem15.summercms
|
||||
- [Phase 34]: 34-03: registry token scope declares GET, HEAD and POST (the framework requires GET in every scope)
|
||||
- [Phase 34]: 34-03: sm-summercmsio-app go.mod requires summercms v0.6.0 with the site plugin; release needs the v0.6.0 tag and a main.go/plugins.gen.go regeneration
|
||||
- [Phase 34]: 34-03: marketplace categories content, users, commerce, communication, seo, tools are a contract between the site plugin and the marketplace pages
|
||||
- [Phase 34]: plugin:install picks the newest release the effective framework allows and never moves the framework; plugin:update applies what resolves and reports the rest
|
||||
- [Phase 34]: go.work overrides for submodule plugins: app replace target, versioned replace for workspace modules (Go refuses whole-path replaces of them), else a version pin that follows the app's require
|
||||
- [Phase 34]: 34-05: the Plugins settings entry is added by Registry.Metadata only when backend.view_plugins is declared, the code plugins is free and the principal is allowed (SettingsEntry.Path opens /system/plugins)
|
||||
- [Phase 34]: 34-05: cabana builds the registry catalog in Activate; registry calls run detached from the request with a 4 s timeout, 4 concurrent lookups, cache 5/15/1 min, and failures are a payload status, never a non-200
|
||||
- [Phase 34]: 34-05: marketplace entries are limited to plugin-ID-shaped IDs and https icons because the ID ends up in a copied shell command
|
||||
- [Phase 34]: 34-02 Task 4 answered defer: no app submodule pointer bumps in phase 34; 32 pending gitlinks (5 apps) and the chat/chatbots/chatchannels rebase blockers go to the 34-06 release ledger
|
||||
- [Phase 34]: 34-02: research F8 applied to chatbots, chatchannels and chatvideo (sm-chat-plugin v0.0.0 -> v0.1.3, local replace kept)
|
||||
- [Phase 34]: Release: every plugin with a 34-02 plugin.yaml plus sm-summercmsio-plugin gets the next patch tag (v0.1.0 if untagged); no /changelog/plugins posts, the v0.6.0 post and tag message list the bumps
|
||||
- [Phase 34]: check-phase34.sh skips sm-user-plugin TestRegisterCORSPath via PHASE34_PLUGIN_SKIP (pre-existing, needs an app around it)
|
||||
- [Phase 33]: 33-01 Task 1: P33-01 descriptor fields and P33-02 FormFieldType.RequestOptions adopted as planned (no renames)
|
||||
- [Phase 33]: 33-01 Task 1: WR-02 accepted, pact.RecordSaved.Locale stays the request locale's primary tag (released in v0.5.2)
|
||||
- [Phase 33]: 33-01 Task 1: Phase 33 delivers SummerCMS v0.6.1 (patch, additive); additive and marker stages compare with v0.6.0; plan mentions of v0.5.1/v0.5.2 mean v0.6.0/v0.6.1
|
||||
- [Phase 33]: 33-07 Task 1 (Jakub 2026-11-04): the shared layer is vue-seo-layer, extended in place from v0.1.1 (no tea repo creation in 33-14; next layer tag v0.2.0)
|
||||
- [Phase 33]: 33-07: seo.cms is an alias of public.seo.enabled; v0.1.1 config keys and behaviour preserved
|
||||
- [Phase 33]: 33-07: root-file proxies and the root_files rule apply only after a v0.2.0 site answer; older or unreachable backends keep v0.1.1 behaviour
|
||||
- [Phase 33]: 33-02: Journal H1 setting default on; EffectiveH1ToH2 = settings row, else golem15.journal.content_h1_to_h2, else true; conversion on every Journal rich-text write path (admin, API/MCP, markdown, import, category pillar text)
|
||||
- [Phase 33]: 33-02: images/alt defaults dry_run false, fix-headings dry_run true; editor schema keeps H5/H6 while the toolbar offers H2-H4 (or H1-H4)
|
||||
- [Phase 33]: 33-02: MediaFileName slugs both the editor upload and POST /media/upload (D-85); response shape unchanged
|
||||
- [Phase 33]: 33-03 Task 1 answered as-proposed (Jakub 2026-11-04): /sitemap.xml index, /sitemap-<slug>-<n>.xml via /_sitemap/files/{file}, XSL removed, one settings singleton, definitions table kept unread
|
||||
- [Phase 33]: 33-03: sitemap Filter/Listing seam lives in git.golem15.com/golem15/sm-sitemap-plugin/contract (no init); SEO implements contract.Filter, sitemap publishes classes.Listing as contract.Listing
|
||||
- [Phase 33]: 33-03: sitemap settings validation runs in the controller FormBeforeUpdate (cabana turns BeforeValidate errors into 500)
|
||||
- [Phase 33]: 33-03: additional address lastmod is a YYYY-MM-DD text field until cabana repeaters accept a datepicker (deferred)
|
||||
- [Phase 33]: 33-08: the vue-seo-layer build guard runs when pages are resolved (nitro:config fires first); production build and generate fail, nuxt dev and prepare only warn
|
||||
- [Phase 33]: 33-08: vue-seo-layer app/utils helpers are seo-prefixed (seoPaginationWindow, seoPageHref) because vue-journal-layer auto-imports its own paginationWindow
|
||||
- [Phase 33]: 33-08: HTML sitemap pages answer 404 unless the CMS site answer has the HTML sitemap on for the locale, 503 with the backend unreachable; an app page at the same path wins
|
||||
- [Phase 33]: 33-04: the HTML sitemap API answers the contract vue-seo-layer 33-08 reads (groups by file slug: key, slug, title, total, more, entries with children; group page: group, title, page, pages, entries)
|
||||
- [Phase 33]: 33-04: the HTML sitemap address per locale is a JSONB map (html_paths) edited through the plugin's form extension, not the translation writer
|
||||
- [Phase 33]: 33-04: News sources is a taglist with custom tags plus a partial listing the values (type:<key>, category:<key>:<id>), checked on save, because taglist options are fixed YAML
|
||||
- [Phase 33]: 33-04: IndexNow retries 429, 5xx and network errors within five attempts; 400, 403 and 422 are recorded without retry; requests only in production
|
||||
- [Phase 33]: 33-05: Registry addresses and names per locale live in urls/titles JSONB through the plugin's own form extension (fields url and title), so Match finds a page by any locale's address
|
||||
- [Phase 33]: 33-05: The registry content type is labelled Site page (pages.type), not Page, to avoid a duplicate SEO settings tab label
|
||||
- [Phase 33]: 33-05: The sitemap filter decides on production values and also excludes addresses the address rules would 301 (reason redirect)
|
||||
- [Phase 33]: 33-05: robots.txt names the sitemap plugin's index (ListingSettings.IndexURL) unless golem15.seo.robots_sitemaps is set
|
||||
- [Phase 33]: 33-05: sm-sitemap-plugin contract.ListingSettings.TypesOff (additive) feeds P1 status.excluded_type
|
||||
- [Phase 33]: 33-05: Site-cache purge after SEO writes is queued in Service.Record once per transaction (kind seo)
|
||||
- [Phase 33]: 33-09: vue-journal-layer, vue-menu-layer and vue-faq-layer extend vue-seo-layer through a link dependency during development (33-14 pins the git tag); the journal layer drops @nuxtjs/seo and its sitemap source
|
||||
- [Phase 33]: 33-09: the post title is h1 while the Journal API reports content_h1_to_h2 on (or absent) and p.journal-post__title while off; journal.postTitleTag overrides; category pillar text follows the category row's setting
|
||||
- [Phase 33]: 33-09: the deprecated POST /api/__journal__/cache/purge keeps its own helpers: a bare import of vue-seo-layer's .ts library would be externalized by Nitro in git-installed apps
|
||||
- [Phase 33]: 33-09: Journal related posts opt-in (golem15.journal.related_mode scored, related_count 3-6); scored mode adds previous_in_category/next_in_category; default answer unchanged
|
||||
- [Phase 33]: 33-09: an app without pages that extends vue-seo-layer sets seo.htmlSitemap false, else the sitemap pages turn the router on
|
||||
- [Phase 33]: 33-06 Task 4: chromedp approved, pin v0.21.0; gen2brain/webp approved, pin v0.6.4 (Jakub 2026-11-04)
|
||||
- [Phase 33]: 33-06: every JSON-LD graph carries the full WebSite and publisher nodes
|
||||
- [Phase 33]: 33-06: site answer home_crumb is {name, url, names} (layer reads name/url; names per locale)
|
||||
- [Phase 33]: 33-10: chromedp v0.21.0 renders the optional raw-versus-rendered comparison; Chrome's host-resolver-rules list the site hosts first and MAP * ~NOTFOUND last (first matching rule wins)
|
||||
- [Phase 33]: 33-10: GET /_seo/api/v1/issues reads stored issues (CMS checks refreshed until the first crawl, then the newest crawl's) and defaults to status open
|
||||
- [Phase 33]: 33-10: crawl issues route to the record type's Tools for content, to seo_ tools for data, else fix code with details.what; no issue has neither
|
||||
- [Phase 33]: 33-10: the Site audit status filter cannot default to Open (cabana filters have no default); ignored rows are badged, the API defaults to open
|
||||
- [Phase 33]: 33-11: gen2brain/webp pinned at v0.6.4 in the framework (modules/lagoon/attach/webp only); its fallback is wasm2go-transpiled libwebp, not wazero; importing it makes binaries glibc-dynamic unless built with -tags nodynamic (33-14 decides per app)
|
||||
- [Phase 33]: 33-11: auto-link locale stored as '' for every locale (not NULL); history subject autolink purges every page (*)
|
||||
- [Phase 33]: 33-11: E10 internal links omitted for collection and profile kinds and the page registry (Words is a per-record fact)
|
||||
- [Phase 33]: 33-11: Journal variants carry the original's source_width/source_height on each featured_images[].variants entry; no foreign key to system_files
|
||||
- [Phase 33]: 33-12: the demo keeps cookie-based Polish (D-13); its /pl/ alternates and sitemap addresses answer 404, so moving to prefix_except_default is a decision for 33-14 before the demo patches are applied
|
||||
- [Phase 33]: 33-12: demo sitemaps go through Nuxt (vue-seo-layer root files); nginx has no /sitemap*, /_sitemap or /_seo location and check-deploy.sh refuses one
|
||||
- [Phase 33]: 33-13: grzybyfunkcjonalne.pl deploys after the tags, to production (no separate uat since the 2026-10-31 cutover); en off and the copied Additional addresses removed at the 33-14 release checkpoint
|
||||
- [Phase 33]: 33-14: the demo moves to prefix_except_default (English at /, Polish at /pl/), reversing D-13
|
||||
- [Phase 33]: 33-16: vue-seo-layer adds its HTML sitemap pages from a pages:resolved hook registered on ready, after @nuxtjs/i18n has localised the routes (modules:done ran before i18n's handler)
|
||||
- [Phase 33]: 33-16: the route report drops every noindex entry before cutting routes, so the JSON body stays within the older plugin's 4,113,024 bytes
|
||||
- [Phase 33]: 33-16: HTML sitemap pages are not registered over an app catch-all unless seo.htmlSitemap.overCatchAll; an app with only app.vue needs no htmlSitemap: false
|
||||
- [Phase 33]: 33-15: the route report's noindex key replaces the stored noindex set (golem15_seo_noindex_paths) and the SEO sitemap filter leaves those paths out with reason noindex; a changed set asks for a rebuild through contract.Rebuilder
|
||||
- [Phase 33]: 33-15: Journal descriptors give a locale a URL only when the record has content in it (posts/categories by own translation, tags/authors through a translated published post, default locale always); menu Resolve unchanged
|
||||
- [Phase 33]: 33-15: a crawl's job owns its terminal status (cancel records cancel_requested_at), finishes on a detached 10-minute context, writes heartbeat_at every minute; RecoverStale ends running rows without a heartbeat for 10 minutes
|
||||
- [Phase 33]: 33-15: sitemap rebuilds run under pg_advisory_xact_lock(hashtext('golem15.sitemap.rebuild')) around settings, collect and apply; apply never writes a content row's lastmod
|
||||
- [Phase 33]: 33-15: G2 (journal-tag pattern while tag pages are off) deferred to v0.6.2: signpost.Activate refuses a type without a DefaultPattern starting with /
|
||||
- [Phase 35]: 35-01 Task 1 answered as-planned: P35-01 schema, P35-02 partial syntax and built-ins, P35-03 sample.* keys, P35-04 layout CSS slot and logoUrl, P35-05 names adopted without changes
|
||||
- [Phase 35]: 35-01: postcard logs 'override failed, sending the file version' only when the file version then renders; when both fail, the file version's error is returned as before
|
||||
- [Phase 35]: 35-01: a partial call in a body leaves the token MAILPARTIAL + 32 hex nonce + X<n>X, swapped in one pass after goldmark; raw HTML stays disabled for bodies
|
||||
- [Phase 35]: 35-01: Editor.Validate refuses a template body whose source holds a script, iframe, object or embed tag, because Markdown would drop it silently at send
|
||||
- [Phase 35]: 35-01: Branding (compiled CSS and logoUrl) also applies to the file version sent after a failing override; an invalid stored colour keeps mail.brandCss with a warning
|
||||
- [Phase 35]: 35-01: pact has five row states; cabana keeps only three until 35-02 updates rowStateOrder and docs/backend/lists-and-filters.md
|
||||
- [Phase 35]: Image list/pick allows either mail permission; upload and Mail images singleton need system.manage_mail_layouts — Planner call for picker split (D-03 / UI-SPEC C4)
|
||||
- [Phase 35]: Test-send is interactive-only; recipient is always the signed-in administrator email; limit 5/10min via cooler.Attempter — D-16/D-17 and research Pattern 7
|
||||
- [Phase 35]: GET /mail/images documents AdminMailImagesResponse so meta.canUpload validates under OpenAPI conformance — SuccessMeta cannot carry canUpload; MarketplaceResponse pattern
|
||||
- [Phase 35]: Task 3 approved all seven CodeMirror pins including @codemirror/view@6.43.15
|
||||
- [Phase 35]: CodeMirror loads only from codeeditor/editor.ts; meta package and indentWithTab unused
|
||||
- [Phase 35]: check-phase35 consumers stage runs sibling plugin mail tests read-only against this checkout — D-21 gate must prove core plugins unchanged without writing their trees
|
||||
- [Phase 35]: D-05 superseded (G-35-1): a mail template is one admin record; locale versions are rows grouped by base_code (migration 202611130001) and opened through a locale switcher (meta.localeVariants); note 2026-11-13-mail-template-locale-groups
|
||||
- [Phase 35]: postcard resolves a missing <template>-<locale> (two-letter tag, optional subtag, longest registered base) to own customization > base customization > base file; names with files send unchanged
|
||||
- [Phase 35]: cabana mail locales = translator locales plus TranslationWriter enabled locales; default = writer default else translator locale; templates list one row per template, locale filter removed
|
||||
- [Phase 35]: 35-06: postcard inlines mail CSS at render with github.com/vanng822/go-premailer v1.38.0 (default options), opt-out via disable_auto_inline_css (layout header key, layouts column, layout form switch); supersedes D-10's inlining claim
|
||||
- [Phase 35]: 35-06: Branding gains Site name (site_name, Brand.SiteName); empty uses the display name of mail.from; default and system layouts show logo or name in the header and a © year name footer
|
||||
- [Phase 35]: 35-06: 35-01's default.htm-unchanged gate lifted; default layout is WinterCMS's default layout on new built-in header and footer partials
|
||||
- [Phase 35]: 35-07: check-phase35.sh consumers run each core plugin through a scratch -modfile (sibling go.sum merged with the framework's, GOWORK=off, GOPROXY=off) and refuse a sibling that is dirty before or after
|
||||
- [Phase 35]: 35-07: G-35-8 recorded as framework-closed with the plugin part deferred; UAT test 8 re-run scoped to the built-in layouts (default, system) with logo, site name and the button partial
|
||||
- [Phase 35]: 35-07: Branding site name with a URL scheme stays an open item; TestMailBrandSiteName pins the current behaviour (saved, preview refused)
|
||||
- [Phase 35]: 35-08: postcard checks URL schemes only in decoded URL-bearing attributes, CSS, comments and meta content (x/net/html tokenizer); text is not a URL, so prose site names no longer stop mail (CR-01)
|
||||
- [Phase 35]: 35-08: postcard.UnsafeText (new exported API) drops unsafe site names at render with a value-free rate-limited warning and backs the Branding 422 on site_name (mail.brand.site_name_unsafe)
|
||||
- [Phase 35]: 35-08: an inlined result that fails the safety check is sent un-inlined with the inline:<layout> warning; the footer partial's text argument prints the site name literally
|
||||
- [Phase 35]: 35-08: cabana settings Put localizes BeforeValidate refusal phrase keys, as controller saves do
|
||||
- [Phase 35]: 35-09: the mail screens test env reads mail.from from its configuration (default unchanged) so a mutate hook sets the sender
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -999,6 +1178,10 @@ Recent decisions affecting current work:
|
||||
- pending: push sm-user-plugin — 12.1-05 Task 3 condition (c) failed (`git ls-remote --tags origin v0.1.3` empty). Push summercms.go master and annotated tag v0.1.3 (local on df5cace) first, then the plugin, then fonoteka.go. Recorded in 12.1-05-SUMMARY.md.
|
||||
- 16.2-05 open UAT items: re-save HTML post 1 untouched (D-03 evidence vacuous), D-19 category edit check, root vhost install (frame-src), unpublish/delete test post 105
|
||||
- Phase 19.4: review warnings WR-01..06 are open (19.4-REVIEW-DISPOSITION.md); WR-01 (a replayed code does not revoke rotated refresh tokens) must be fixed before any client enables refresh. Release still pending: tag summercms, bump sm-oauthserver-plugin go.mod to sm-user-plugin v0.1.1 / summercms v0.2.4.
|
||||
- 19.6-03 Task 6 (1): sm-demo-app plugins/golem15/user carries another session's uncommitted move to v0.1.11; user decision needed before bumping it to v0.1.12
|
||||
- 19.6-04 Task 5: go-ahead to release sm-mfa-plugin fix 71d8f27 (v0.1.1, demo and bm bumps) and a decision on finding F-1 (activate-by-code without the second factor when require_activation is off)
|
||||
- 33-02 deferred: lagoon.Validate rejects string/url rule tokens, so the Journal admin settings save answers 500 (pre-existing); framework fix needed for the Headings and links switch in the admin
|
||||
- 33-14 Task 3 release checkpoint: awaiting Jakub's go-ahead (versions, pushes, posts, deploys)
|
||||
|
||||
### Quick Tasks Completed
|
||||
|
||||
@@ -1059,6 +1242,36 @@ Recent decisions affecting current work:
|
||||
| 261022-wah | User plugin opt-in golem15.user.jwt.token_cookie (default off) sets the HttpOnly auth.cookie session cookie on /login, /register and /activate-by-code instead of the body token; a /refresh carried by the auth.cookie cookie rewrites it (sm-user-plugin 846087d, 8bdf2c7, ships v0.5.0; verified) | 2026-10-22 | 846087d, 8bdf2c7 (sm-user-plugin) | [261022-wah-opt-in-httponly-session-cookie-on-user-p](./quick/261022-wah-opt-in-httponly-session-cookie-on-user-p/) |
|
||||
| 261022-x7a | User plugin golem15.user.password.public_routes (default true): false leaves POST /login, /forgot-password and /reset-password unregistered so they 404 like unknown paths; /register and the rest unchanged (sm-user-plugin 3828a65, ships v0.5.0; verified) | 2026-10-22 | e5dd457 | [261022-x7a-user-plugin-golem15-user-password-public](./quick/261022-x7a-user-plugin-golem15-user-password-public/) |
|
||||
| 55 | fix(cabana): backend subject events reach pier as *pact.MCPSubjectChanged after commit | 2026-10-23 | 7c43820 | — |
|
||||
| 261028-fsq | sm-user-plugin MCPDispatch credential carries the personal token id (plugin a1b78b8) | 2026-10-28 | 7c4dbb1 | [261028-fsq-sm-user-plugin-mcpdispatch-credential-ca](./quick/261028-fsq-sm-user-plugin-mcpdispatch-credential-ca/) |
|
||||
| 261028-pq8 | Fix the four internal/build scaffolder todos (make:plugin vendor path, make:admin-controller output, scaffold header and make:command deps, same-second migration order) | 2026-10-28 | 8bc18c9 | [261028-pq8-fix-the-four-internal-build-scaffolder-t](./quick/261028-pq8-fix-the-four-internal-build-scaffolder-t/) |
|
||||
| 261028-r16 | Fix the two lagoon todos: stored-upload extension from sniffed MIME (tests + deploy note) and the lagoon README after-commit callback order | 2026-10-28 | 36092f5 | [261028-r16-fix-the-two-lagoon-todos-derive-stored-u](./quick/261028-r16-fix-the-two-lagoon-todos-derive-stored-u/) |
|
||||
| fast | ensureToolchain keeps an existing toolchain line instead of adding a second one | 2026-10-28 | 6ea2cb7 | — |
|
||||
| 261028-rqb | Admin SPA reload on deploy (todo .planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md, admin half only; site half already shipped in vue-demo-app): boardwalk exposes a build version derived from the embedded dist (header like X-Summer-Build on admin API responses and/or a version endpoint), the admin SPA records the version it booted with and shows a non-blocking reload banner when a newer build is seen (focus/visibility/interval check), plus a reload-once guard on Vite chunk-load errors (vite:preloadError + sessionStorage flag); unit tests; boardwalk README; rebuild admin and commit modules/boardwalk/dist (scripts/check-admin-dist.sh must pass) | 2026-10-28 | c8a22e3 | .planning/quick/261028-rqb-admin-spa-reload-on-deploy-todo-planning-todos-pending-2026 |
|
||||
| 261028-rqc | Quiet plugin boot logs on console commands like --help, framework side only (todo .planning/todos/pending/2026-10-21-quiet-plugin-boot-logs-on-console-commands.md): help/list/completion style commands must not print plugin Register/Boot Info logs (e.g. raise the default console log level for non-serve introspection commands or defer Boot for them), without hiding logs for serve/worker/migrate; no sm-* plugin edits (plugin-side Info->Debug changes are a separate follow-up); docs for the behaviour | 2026-10-28 | 6c606c6 | .planning/quick/261028-rqc-quiet-plugin-boot-logs-on-console-commands-like-help-framewo |
|
||||
| 261028-rqd | Console review info findings IN-01..IN-13 and the delegate signal exit code 128+n (todo .planning/todos/pending/2026-10-22-console-review-info-findings.md, review .planning/phases/19.8-console-commands-overhaul/19.8-REVIEW.md); all 14 verified still open on 2026-10-28 in modules/bonfire, modules/diary, cmd/summer, scripts/check-phase19.8.sh; fix each, keep behaviour backward compatible, update docs/console pages and TestDelegateExitCodePassthrough for 128+n | 2026-10-28 | 202d38b | .planning/quick/261028-rqd-console-review-info-findings-in-01-in-13-and-the-delegate-si |
|
||||
| 261028-rqe | attach.Store writes non-inline types with a non-rendering disposition (todo .planning/todos/pending/2026-10-28-attach-store-public-content-type.md): in modules/lagoon/attach/store.go pass Content-Disposition attachment (blob.WriterOptions) for anything not in an inline-safe raster allow-list (jpeg, png, gif, webp, avif), keep the DB ContentType unchanged, additive and non-breaking; tests; lagoon README and docs/services/storage.md deploy note updated | 2026-10-28 | 4957e5c | .planning/quick/261028-rqe-attach-store-writes-non-inline-types-with-a-non-rendering-di |
|
||||
| 261028-rqf | Audit-log successful admin action runs with the admin id (todo .planning/todos/pending/admin-action-audit-log.md): in modules/cabana/actions.go runAction log success with admin_id (bouncer.User(ctx).ID), controller, action and kind (toolbar/field), matching the existing bulk/record action log fields; tests | 2026-10-28 | 61d1043 | .planning/quick/261028-rqf-audit-log-successful-admin-action-runs-with-the-admin-id-tod |
|
||||
| 261028-rqg | Show the administrators holding a role on the Roles screen (todo .planning/todos/pending/roles-screen-holders-list.md, origin .planning/phases/19.6.1-backend-administrators-screen/19.6.1-UAT.md:44): read-only list of holders on the Roles form/preview in modules/cabana backend_roles_admin.go (and admin SPA if needed), superusers hidden from non-superuser editors (D-03), assignment stays on the Administrators form; tests; if admin/ changes, rebuild and commit modules/boardwalk/dist | 2026-10-28 | 653d95a | .planning/quick/261028-rqg-show-the-administrators-holding-a-role-on-the-roles-screen-t |
|
||||
| 261028-wqu | summercms.io Changelog dropdown (Framework/Plugins): /changelog = framework category, /changelog/plugins = plugins category; changelog-post.py categories + backfill (sm-summercmsio-app 29dd1b3) | 2026-10-28 | bac8e7e | [261028-wqu-summercms-io-changelog-dropdown-framewor](./quick/261028-wqu-summercms-io-changelog-dropdown-framewor/) |
|
||||
| 261029-1r3 | Derive the summercms.io landing version from go.mod | 2026-10-29 | app b688a80 | [261029-1r3-derive-the-summercms-io-landing-version-](./quick/261029-1r3-derive-the-summercms-io-landing-version-/) |
|
||||
| 261029-d9j | User plugin mail locale: normalize Accept-Language, configurable fallback, Polish subjects | 2026-10-29 | user 6bf219f | [261029-d9j-user-plugin-mail-locale-normalize-accept](./quick/261029-d9j-user-plugin-mail-locale-normalize-accept/) |
|
||||
| 261105-din | Fix 32.1 CR-01: serialize MCP consent allow with revoke under LockUserGrants (sm-oauthserver-plugin 21f5985) | 2026-11-05 | 8c6b317 | [261105-din-fix-32-1-cr-01-serialize-mcp-consent-all](./quick/261105-din-fix-32-1-cr-01-serialize-mcp-consent-all/) |
|
||||
| 261105-eab | Fix OIDC grant flows racing revoke: resume, refresh, exchange under LockUserGrants (sm-oauthserver-plugin 7b9899f) | 2026-11-05 | f925527 | [261105-eab-fix-oidc-consent-decide-race-with-revoke](./quick/261105-eab-fix-oidc-consent-decide-race-with-revoke/) |
|
||||
| 261105-oc5 | 2FA hardening (todos 2026-10-26-activate-by-code-second-factor.md and 2026-10-26-mfa-factor-changes-need-reauth.md): sm-user-plugin ActivateByCode runs CheckLoginGates after VerifyActivationCode (finding F-1); sm-mfa-plugin requires password confirmation on factor-changing routes (WR-05) and vue-demo-app security.vue asks for the password | 2026-11-05 | b179e6b | .planning/quick/261105-oc5-2fa-hardening |
|
||||
| 261105-oc6 | Chatchannels pin policy (todo chatchannels-pin-policy.md): sm-chatchannels-plugin PinMessage/UnpinMessage require CanManageContext or an optional contracts.PinPolicy, and verify the message belongs to the channel conversation; sm-demo-app answers the policy from its moderator group | 2026-11-05 | a042536 | .planning/quick/261105-oc6-chatchannels-pin-policy |
|
||||
| 261105-oc7 | Chatvideo hardening (todos chatvideo-live-membership.md, chatvideo-dm-only-host-hook.md, chatvideo-incoming-handle-leak.md): sm-chatvideo-plugin honours LiveMembership and removes banned participants from the LiveKit room, adds an optional CanStartCall host hook for a DM-only rule; vue-chatvideo-layer useIncomingCalls closes stale session handles | 2026-11-05 | f996156 | .planning/quick/261105-oc7-chatvideo-hardening |
|
||||
| 261105-oc8 | lagoon/attach StaticHandler and StaticHandlerPublic send the stored Content-Disposition and X-Content-Type-Options nosniff (todo 2026-10-28-attach-static-handler-disposition.md) | 2026-11-05 | 27c98bf | .planning/quick/261105-oc8-lagoon-attach-statichandler-and-statichandlerpublic-send-the |
|
||||
| 261105-oc9 | sm-demo-app hardening (todos check-local-jwt-out-of-argv.md, demo-chat-members-read-only.md, demo-nginx-livekit-rtc-only.md, demo-seed-moderation-lists-once.md, demo-vapid-runbook-pipefail.md) | 2026-11-05 | 9595606 | .planning/quick/261105-oc9-sm-demo-app-hardening |
|
||||
| 261106-d20 | fonoteka.go uploads named after the sniffed type and stored with attach.UploadWriterOptions; framework exports attach.UploadWriterOptions (todos 2026-10-28-fonoteka-uploads-use-disk-extension.md, 2026-11-06-blob-writers-set-content-disposition.md) | 2026-11-06 | 903859a | [261106-d20-fix-stored-xss-in-fonoteka-go-uploads-an](./quick/261106-d20-fix-stored-xss-in-fonoteka-go-uploads-an/) |
|
||||
| 261106-dv0 | shared plugins log boot details at Debug: paymentgateway operators registered, paymentgatewaysubscriptions registries collected through diary.For (todo 2026-10-28-plugins-log-boot-details-at-debug.md) | 2026-11-06 | 8a88b86, 1df6a26 | [261106-dv0-plugin-boot-logs-at-debug](./quick/261106-dv0-plugin-boot-logs-at-debug/) |
|
||||
| 261106-e5v | purge token rename leftovers: grzybyfunkcjonalne check-deploy refuses NUXT_SITE_* keys, journal/menu/faq READMEs name NUXT_CACHE_PURGE_TOKEN (todo 2026-10-20-rename-site-cache-purge-env-in-consumers.md) | 2026-11-06 | 4e2cf0c, f61c90a, 128a33d, a53511b | [261106-e5v-purge-token-rename-leftovers](./quick/261106-e5v-purge-token-rename-leftovers/) |
|
||||
| 261106-jhk | wristband MCP authorize drops OIDC identity scopes (openid, profile, email) so the ChatGPT connector can connect | 2026-11-06 | aba678b | [261106-jhk-wristband-mcp-authorize-ignores-oidc-ide](./quick/261106-jhk-wristband-mcp-authorize-ignores-oidc-ide/) |
|
||||
| 261106-kt1 | pier MCP 401 challenge names only resource_metadata, so clients request the advertised scopes (write included) | 2026-11-06 | 609caa4 | [261106-kt1-pier-mcp-401-challenge-drops-the-fixed-r](./quick/261106-kt1-pier-mcp-401-challenge-drops-the-fixed-r/) |
|
||||
| 261106-kt2 | deferred:purge, migrate* and queue:clear reuse the app's published database, so the in-server scheduler no longer fails with duplicate provider for *sql.DB | 2026-11-06 | 99abe88 | [261106-kt2-lagoon-deferred-purge-fails-in-the-sched](./quick/261106-kt2-lagoon-deferred-purge-fails-in-the-sched/) |
|
||||
| 261108-pe4 | beachcomber highlights and field projection: Query.IncludeFields/ExcludeFields/Highlight, SearchResult.Hits (plain-text segments), HighlightSearcher + SupportsHighlights; Typesense parses v1 highlights | 2026-11-08 | 7819c67 | [261108-pe4-beachcomber-highlights-and-field-project](./quick/261108-pe4-beachcomber-highlights-and-field-project/) |
|
||||
| 261114-p5m | Fix CR-02 residual: quoted end tags in raw-text elements bypass the postcard scheme check | 2026-11-14 | f1f284a0 | [261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra](./quick/261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra/) |
|
||||
| 261114-p5n | Style the user and paymentgateway plugin mail layouts like the postcard default layout | 2026-11-14 | 4ef3aa1f | [261114-p5n-style-the-user-and-paymentgateway-plugin](./quick/261114-p5n-style-the-user-and-paymentgateway-plugin/) |
|
||||
| 261115-cha | Let a mail template use another plugin's layout by full code (G-35-9) | 2026-11-15 | b8487b02 | [261115-cha-let-a-mail-template-use-another-plugin-s](./quick/261115-cha-let-a-mail-template-use-another-plugin-s/) |
|
||||
|
||||
## Deferred Items
|
||||
|
||||
@@ -1070,6 +1283,6 @@ Items acknowledged and carried forward from previous milestone close:
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-10-24T14:47:37.432Z
|
||||
Stopped at: Phase 32 context gathered
|
||||
Resume file: .planning/phases/32-seo-foundation/32-CONTEXT.md
|
||||
Last session: 2026-11-14T15:08:11.773Z
|
||||
Stopped at: Phase 35 complete, ready to plan Phase 30
|
||||
Resume file: None
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
schema_version: 1
|
||||
open_count: 20
|
||||
open_count: 26
|
||||
waived_count: 0
|
||||
fixed_count: 7
|
||||
total_count: 27
|
||||
last_updated: 2026-10-22T14:44:56.679Z
|
||||
fixed_count: 9
|
||||
total_count: 35
|
||||
last_updated: 2026-11-04T19:19:01.124Z
|
||||
---
|
||||
|
||||
# Broken Windows Ledger
|
||||
@@ -42,6 +42,14 @@ last_updated: 2026-10-22T14:44:56.679Z
|
||||
| 25 | 19.7 | deviation | modules/cabana | | 19.7-01: admin route inventories (phase09Routes, tokenRouteClasses, CSRF walk 35, phase10 want list, conformCases) extended for the two account contribution routes | open | | 2026-10-22T14:44:56.218Z | |
|
||||
| 26 | 19.7 | deviation | modules/cabana | | 19.7-01: TestRecordActionPromptRun added on Postgres to prove Run receives the trimmed prompt value | open | | 2026-10-22T14:44:56.449Z | |
|
||||
| 27 | 19.7 | unrun-verify | scripts/check-phase19.6.1.sh | | 19.7-01: check-phase19.6.1.sh --all stopped by the host (memory pressure) after the cabana and surf Postgres suites passed; re-run on the Docker host | open | | 2026-10-22T14:44:56.679Z | |
|
||||
| 28 | 33 | deviation | modules/lagoon/validate.go | | 33-02: lagoon.Validate rejects the string and url rule tokens, so the Journal admin settings save answers 500 (pre-existing); the Headings and links switch is saved through the settings API/MCP until fixed | open | | 2026-11-04T09:39:12.905Z | |
|
||||
| 29 | 33 | stub | contract/contract.go | | sm-sitemap-plugin: contract.ListingSettings HTMLEnabled, HTMLPaths, HTMLPageSize and KeyFile stay zero and golem15_sitemap_urls.images stays [] until 33-04 adds the HTML sitemap, IndexNow and image settings | fixed | | 2026-11-04T10:26:56.754Z | 2026-11-04T11:41:58.774Z |
|
||||
| 30 | 33 | deviation | models/settings/fields.yaml | | sm-sitemap-plugin: the Additional addresses lastmod is a text field read as YYYY-MM-DD (server-checked, errors.lastmod) because the framework repeater accepts no datepicker column; swap to a datepicker once cabana supports it in repeaters | open | | 2026-11-04T10:26:56.940Z | |
|
||||
| 31 | 33 | deviation | models/settings/fields.yaml | | sm-sitemap-plugin: News sources is a taglist with custom tags and no options (values listed by the news_sources partial, server-checked) because cabana taglist options are a fixed YAML list and form extensions take no taglist; switch to options from the article types and categories once the framework offers per-request taglist options | open | | 2026-11-04T11:42:13.158Z | |
|
||||
| 32 | 33 | deviation | controllers/issues/config_filter.yaml | | sm-seo-plugin: the Site audit status filter cannot default to Open (cabana list filters have no default value), so the list shows ignored issues too, badged Ignored; GET /_seo/api/v1/issues and seo_list_issues default to status open; set the default once cabana filters accept one | open | | 2026-11-04T15:03:28.372Z | |
|
||||
| 33 | 33 | deviation | controllers/issues/_issue_details.htm | | sm-seo-plugin: P7 shows Open the page and the Rich Results Test as labelled addresses, not links, because the partial allowlist keeps only same-origin hrefs; make them links once partials may carry an external link (new tab) | open | | 2026-11-04T15:03:28.619Z | |
|
||||
| 34 | 33 | deviation | vue-demo-app/nuxt.config.ts | | 33-12: the demo serves Polish by cookie at one address (no_prefix), but the CMS names /pl/... alternates and sitemap addresses, which answer 404; i18n strategy decision before 33-14 applies the demo patches | open | | 2026-11-04T17:10:13.946Z | |
|
||||
| 35 | 33 | todo | sm-sitemap-plugin/classes/rebuild.go | | 33-12: additional addresses are not de-duplicated against content records (migrated /, /blog, /faq listed twice on rome-like data); the demo DEPLOY step works around it | fixed | | 2026-11-04T17:10:14.144Z | 2026-11-04T19:19:01.124Z |
|
||||
|
||||
````json
|
||||
[
|
||||
@@ -395,6 +403,110 @@ last_updated: 2026-10-22T14:44:56.679Z
|
||||
"recorded_at": "2026-10-22T14:44:56.679Z",
|
||||
"resolved_at": null,
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 28,
|
||||
"kind": "deviation",
|
||||
"phase": "33",
|
||||
"file": "modules/lagoon/validate.go",
|
||||
"line": null,
|
||||
"description": "33-02: lagoon.Validate rejects the string and url rule tokens, so the Journal admin settings save answers 500 (pre-existing); the Headings and links switch is saved through the settings API/MCP until fixed",
|
||||
"status": "open",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T09:39:12.905Z",
|
||||
"resolved_at": null,
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 29,
|
||||
"kind": "stub",
|
||||
"phase": "33",
|
||||
"file": "contract/contract.go",
|
||||
"line": null,
|
||||
"description": "sm-sitemap-plugin: contract.ListingSettings HTMLEnabled, HTMLPaths, HTMLPageSize and KeyFile stay zero and golem15_sitemap_urls.images stays [] until 33-04 adds the HTML sitemap, IndexNow and image settings",
|
||||
"status": "fixed",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T10:26:56.754Z",
|
||||
"resolved_at": "2026-11-04T11:41:58.774Z",
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 30,
|
||||
"kind": "deviation",
|
||||
"phase": "33",
|
||||
"file": "models/settings/fields.yaml",
|
||||
"line": null,
|
||||
"description": "sm-sitemap-plugin: the Additional addresses lastmod is a text field read as YYYY-MM-DD (server-checked, errors.lastmod) because the framework repeater accepts no datepicker column; swap to a datepicker once cabana supports it in repeaters",
|
||||
"status": "open",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T10:26:56.940Z",
|
||||
"resolved_at": null,
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 31,
|
||||
"kind": "deviation",
|
||||
"phase": "33",
|
||||
"file": "models/settings/fields.yaml",
|
||||
"line": null,
|
||||
"description": "sm-sitemap-plugin: News sources is a taglist with custom tags and no options (values listed by the news_sources partial, server-checked) because cabana taglist options are a fixed YAML list and form extensions take no taglist; switch to options from the article types and categories once the framework offers per-request taglist options",
|
||||
"status": "open",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T11:42:13.158Z",
|
||||
"resolved_at": null,
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 32,
|
||||
"kind": "deviation",
|
||||
"phase": "33",
|
||||
"file": "controllers/issues/config_filter.yaml",
|
||||
"line": null,
|
||||
"description": "sm-seo-plugin: the Site audit status filter cannot default to Open (cabana list filters have no default value), so the list shows ignored issues too, badged Ignored; GET /_seo/api/v1/issues and seo_list_issues default to status open; set the default once cabana filters accept one",
|
||||
"status": "open",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T15:03:28.372Z",
|
||||
"resolved_at": null,
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 33,
|
||||
"kind": "deviation",
|
||||
"phase": "33",
|
||||
"file": "controllers/issues/_issue_details.htm",
|
||||
"line": null,
|
||||
"description": "sm-seo-plugin: P7 shows Open the page and the Rich Results Test as labelled addresses, not links, because the partial allowlist keeps only same-origin hrefs; make them links once partials may carry an external link (new tab)",
|
||||
"status": "open",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T15:03:28.619Z",
|
||||
"resolved_at": null,
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 34,
|
||||
"kind": "deviation",
|
||||
"phase": "33",
|
||||
"file": "vue-demo-app/nuxt.config.ts",
|
||||
"line": null,
|
||||
"description": "33-12: the demo serves Polish by cookie at one address (no_prefix), but the CMS names /pl/... alternates and sitemap addresses, which answer 404; i18n strategy decision before 33-14 applies the demo patches",
|
||||
"status": "open",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T17:10:13.946Z",
|
||||
"resolved_at": null,
|
||||
"milestone": "v1.0"
|
||||
},
|
||||
{
|
||||
"id": 35,
|
||||
"kind": "todo",
|
||||
"phase": "33",
|
||||
"file": "sm-sitemap-plugin/classes/rebuild.go",
|
||||
"line": null,
|
||||
"description": "33-12: additional addresses are not de-duplicated against content records (migrated /, /blog, /faq listed twice on rome-like data); the demo DEPLOY step works around it",
|
||||
"status": "fixed",
|
||||
"reason": "",
|
||||
"recorded_at": "2026-11-04T17:10:14.144Z",
|
||||
"resolved_at": "2026-11-04T19:19:01.124Z",
|
||||
"milestone": "v1.0"
|
||||
}
|
||||
]
|
||||
````
|
||||
|
||||
146
.planning/debug/mail-layouts-unstyled.md
Normal file
146
.planning/debug/mail-layouts-unstyled.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
status: diagnosed
|
||||
trigger: "UAT gap G-35-8: logo doesn't appear, only kind of proper layout is System layout (logo doesn't show, Aktywuj konto on activate email doesn't seem to be a button, totally unstyled), other layouts sucks, I expect beautiful and working out of box layouts after this phase."
|
||||
created: 2026-11-13T00:00:00Z
|
||||
updated: 2026-11-13T16:05:00Z
|
||||
goal: find_root_cause_only
|
||||
---
|
||||
|
||||
## Current Focus
|
||||
|
||||
bug_class: Bohrbug (deterministic; reproduced outside the SPA with a scratch render, every run)
|
||||
hypothesis: CONFIRMED — the Phase 35 plumbing works (logoUrl var, brand CSS, button partial), but no shipped content consumes it: no layout prints {{ .logoUrl }}, plugin templates use plain Markdown links instead of the button partial, and the default + plugin layouts are bare stubs without Winter's wrapper/header/card/footer structure.
|
||||
test: scratch render of golem15.user::mail.activate across user/system/default/minimal layouts with a Brand carrying LogoURL
|
||||
expecting: logo URL count 0 and `class="button` count 0 in all layouts (observed); button partial call renders a styled button (observed)
|
||||
next_action: return ROOT CAUSE FOUND (diagnose-only mode)
|
||||
|
||||
reasoning_checkpoint:
|
||||
hypothesis: "Logo/buttons/structure are missing because the shipped layout and template files never reference logoUrl, the button partial, or the wrapper/header/footer classes the brand CSS styles — not because of preview, URL or CSS-delivery failures."
|
||||
confirming_evidence:
|
||||
- "grep: logoUrl appears in no .htm layout in postcard, sm-user-plugin or sm-paymentgateway-plugin; only in docs and test-only overrides"
|
||||
- "scratch render: 0 logo occurrences, 0 class=button in all 4 layouts; brand CSS with saved colour present"
|
||||
- "same render with {{ partial \"button\" ... }} produces class=\"button button-primary\""
|
||||
- "plugin layouts are `<div class=\"layout-user|layout-paymentgateway\">{{ .Content }}</div>` (stubs from phases 07-03/18-04); default.htm is `<div class=\"content-body\">` and 35-01 forbade touching it"
|
||||
falsification_test: "Adding `{{ if .logoUrl }}<img src=\"{{ .logoUrl }}\">{{ end }}` to a layout and rendering with the same Brand must show the logo URL; if it did not, the wiring would be at fault. brand_smoke_test 'logo' subtest already shows it does."
|
||||
fix_rationale: "Ship finished layouts (Winter default port with header/logo + footer; logo in system) and switch plugin CTAs to the button partial — addresses missing consumers, which is the root cause; plumbing needs no change."
|
||||
blind_spots: "Did not drive the actual SPA preview with an admin session (used the same postcard render path directly); did not test real mail clients for <style>-only CSS (inlining gap is from Winter parity + known client behaviour, not observed here)."
|
||||
candidate_causes:
|
||||
- "code (framework): built-in layouts lack logo slot/header/footer; default layout bare; no CSS inliner"
|
||||
- "code (plugins): templates use Markdown links; layouts are stubs"
|
||||
- "config/environment: logo URL base / public file / CSP / sandbox — eliminated"
|
||||
- "data: demo DB has customized user layout + activate overrides (masks file fixes during verification, not a cause)"
|
||||
and_gate: "yes — an out-of-box finished mail needs (a) a layout with structure and logo slot AND (b) templates calling the button partial AND (c) brand CSS for those classes (present); real-client rendering additionally needs (d) CSS inlining. Each missing piece alone produces part of the symptom."
|
||||
|
||||
## Symptoms
|
||||
|
||||
expected: Mail preview renders the template inside a polished, working layout out of the box: branding logo shows, CTA links (e.g. "Aktywuj konto" in user activate) render as styled buttons, every shipped layout (system and plugin layouts like user, paymentgateway) looks finished.
|
||||
actual: Logo does not appear (system and plugin layouts). "Aktywuj konto" is a plain link, not a button. Only the System layout looks somewhat proper; plugin layouts (user, paymentgateway) are unstyled.
|
||||
errors: none reported
|
||||
reproduction: sm-demo-app at http://127.0.0.1:8097/smbackend -> mail templates editor -> preview golem15.user::mail.activate (and paymentgateway templates); branding colours + logo saved beforehand.
|
||||
started: Phase 35 UAT (first time this feature exists)
|
||||
extra: test-send text body "Cześć **[Name]**.\n\n[Aktywuj konto]([Link])\n\nKod: [Code]" — template body is markdown with a link.
|
||||
|
||||
## Eliminated
|
||||
|
||||
- hypothesis: sandboxed preview iframe (sandbox="") or the admin CSP blocks the logo image / inline styles
|
||||
evidence: sandbox="" does not block images or <style>; admin CSP has no img-src/style-src/default-src; no COEP/CORP; brand CSS demonstrably present in output. The logo <img> is simply absent from the rendered HTML.
|
||||
timestamp: 2026-11-13T15:40Z
|
||||
|
||||
- hypothesis: logo URL is not resolved (file not public, no public_url/app.url, wrong partition key)
|
||||
evidence: brand row has logo_file_id 556, is_public; computed URL returns 200 image/png; no "mail branding logo" warning in go.log
|
||||
timestamp: 2026-11-13T15:42Z
|
||||
|
||||
- hypothesis: logoUrl is not passed to layouts during preview (preview data wiring)
|
||||
evidence: Editor.render -> m.options(ov.Brand) sets opts.logoURL; renderParts passes "logoUrl" to text and HTML wrappers (templates.go:620,630); test overrides that print it get the URL (brand_smoke_test)
|
||||
timestamp: 2026-11-13T15:43Z
|
||||
|
||||
- hypothesis: plugin layouts don't receive the brand CSS
|
||||
evidence: user.htm and paymentgateway.htm both contain <style>{{ .brandCss }}{{ .css }}</style>; repro output contains the compiled brand CSS with the saved #2974d6
|
||||
timestamp: 2026-11-13T15:45Z
|
||||
|
||||
- hypothesis: postcard cannot render buttons (no button partial / unstyled)
|
||||
evidence: built-in button partial renders class="button button-primary" and brand.css.tmpl styles .button-primary/.positive/.negative with brand colours
|
||||
timestamp: 2026-11-13T15:47Z
|
||||
|
||||
## Evidence
|
||||
|
||||
- timestamp: 2026-11-13T15:30Z
|
||||
checked: knowledge base (.planning/debug/knowledge-base.md) and resolved sessions
|
||||
found: no knowledge-base.md; resolved sessions unrelated (avatar bucket, category content, etc.)
|
||||
implication: no known-pattern candidate
|
||||
|
||||
- timestamp: 2026-11-13T15:32Z
|
||||
checked: modules/postcard/assets/{default,system,minimal}.htm
|
||||
found: none of the three built-in layouts references {{ .logoUrl }}. default.htm body is only `<div class="content-body">{{ .Content }}</div>` (no wrapper table, no header, no footer, class content-body has no CSS rule in brand.css.tmpl). system.htm has the Winter wrapper/content/body/inner-body/content-cell tables + subcopy partial but no header row/logo and no footer row. minimal.htm is bare body.
|
||||
implication: logo can never appear in any built-in layout; default layout has no card/header/footer structure so it looks unstyled
|
||||
|
||||
- timestamp: 2026-11-13T15:33Z
|
||||
checked: grep logoUrl across postcard, docs, admin, sm-user-plugin, sm-paymentgateway-plugin
|
||||
found: logoUrl only exists as render var (templates.go:620,630), in README/docs examples (`{{ if .logoUrl }}<img ...>{{ end }}`) and in test-only layout overrides (brand_smoke_test.go:220,329). No shipped .htm layout uses it.
|
||||
implication: the logo plumbing (store.go -> Brand.LogoURL -> opts.logoURL -> layout var) is wired, but the consumer (a layout that prints it) was never shipped. Tests prove the variable reaches a layout only via test overrides.
|
||||
|
||||
- timestamp: 2026-11-13T15:35Z
|
||||
checked: ../sm-demo-app/plugins/golem15/user/views/mail/layouts/user.htm and paymentgateway/views/mail/layouts/paymentgateway.htm (identical to ../sm-user-plugin, ../sm-paymentgateway-plugin)
|
||||
found: both are bare: `<style>{{ .brandCss }}{{ .css }}</style>` + `<div class="layout-user">{{ .Content }}</div>` / `<div class="layout-paymentgateway">`. No wrapper/inner-body tables, no header/logo, no footer. Classes layout-user / layout-paymentgateway have no CSS rule anywhere. user.htm text wrap is `-- {{ .Content }} --`.
|
||||
implication: plugin layouts only get the brand CSS element rules (body bg #f5f8fa, p/a/h colours) — content sits flush on the grey page background with no white card, header or footer: "unstyled"
|
||||
|
||||
- timestamp: 2026-11-13T15:36Z
|
||||
checked: user activate.htm / activate-en.htm / restore / invite templates
|
||||
found: CTA is plain Markdown link `[Aktywuj konto]({{ .Link }})`; no `{{ partial "button" ... }}` call. layout = "user".
|
||||
implication: goldmark renders a plain <a>; brand CSS styles <a> only with link colour; nothing makes it a button
|
||||
|
||||
- timestamp: 2026-11-13T15:40Z
|
||||
checked: admin/src/components/form/fields/MailPreviewField.vue + modules/boardwalk/boardwalk.go SetSecurityHeaders
|
||||
found: preview iframe is `sandbox=""` + srcdoc. Admin CSP = "frame-ancestors 'none'; base-uri 'none'; object-src 'none'; script-src 'self'; form-action 'self'; frame-src 'none'" — no default-src/img-src/style-src. No COEP header anywhere; uploads send no CORP.
|
||||
implication: sandbox/CSP do not block <img> or inline <style> in the srcdoc preview
|
||||
|
||||
- timestamp: 2026-11-13T15:42Z
|
||||
checked: demo DB (docker sm-demo-pg) system_mail_brand_settings, system_files id 556; curl of the computed logo URL
|
||||
found: brand row 1 saved (button_primary_bg #2974d6, logo_file_id 556 -> 72368e60b987f6aab7c025.png, is_public t). URL from attach.AbsolutePublicURL(app.url + storage.uploads.public_path_prefix + partition key) = http://127.0.0.1:8097/storage/app/uploads/public/723/68e/60b/72368e60b987f6aab7c025.png -> HTTP 200 image/png. go.log has no "mail branding logo" warning.
|
||||
implication: logo URL resolution works; Brand.LogoURL is populated for preview and send
|
||||
|
||||
- timestamp: 2026-11-13T15:45Z
|
||||
checked: scratch repro (scratchpad/mailrepro) — postcard.NewCatalog + Register(sm-user-plugin views) + NewMailer with an OverrideSource returning Brand{LogoURL: <above>, ButtonPrimaryBg #2974d6}; send golem15.user::mail.activate in file layout (user), system, default, minimal
|
||||
found: for all four layouts the HTML contains the compiled brand CSS (#2974d6 present) but 0 occurrences of the logo URL and 0 `class="button`. user layout body = `<div class="layout-user"><p>Cześć <strong>Jan</strong>.</p><p><a href="...">Aktywuj konto</a></p><p>Kod: 123456</p></div>`. system layout = Winter wrapper/inner-body card + subcopy, no header/logo, no footer.
|
||||
implication: reproduces all three symptoms deterministically outside the SPA (Bohrbug); preview path is not at fault
|
||||
|
||||
- timestamp: 2026-11-13T15:47Z
|
||||
checked: same repro with body `{{ partial "button" "url" .Link "body" "Aktywuj konto" }}` in the user layout
|
||||
found: renders `<table class="action">...<a href="..." class="button button-primary" target="_blank">Aktywuj konto</a>` and brand CSS has .button/.button-primary rules with the brand colour
|
||||
implication: button support exists and is styled; the CTA is a plain link only because the plugin templates don't call the partial
|
||||
|
||||
- timestamp: 2026-11-13T15:50Z
|
||||
checked: git show v0.6.4:modules/postcard/{partials.go,templates.go}; sm-user-plugin/go.mod, sm-paymentgateway-plugin/go.mod
|
||||
found: partials.go absent in v0.6.4; v0.6.4 execHTML parses with no FuncMap (no `partial`). Both plugins `require git.golem15.com/golem15/summercms v0.6.0`.
|
||||
implication: plugin templates can only adopt `{{ partial "button" }}` together with a require bump to the first tag containing phase 35; on <= v0.6.4 the call fails to parse at send ("function \"partial\" not defined")
|
||||
|
||||
- timestamp: 2026-11-13T15:52Z
|
||||
checked: .planning/phases/35-.../35-01-PLAN.md
|
||||
found: Task "Assets: port Winter's system layout and the four partials ... default.htm is not touched" with a gate `git diff a024280 --stat -- modules/postcard/assets/default.htm prints nothing`. Task 5 logo test uses "a layout using {{ .logoUrl }}" (test-only override, brand_smoke_test.go:220,329). Task 5 <done> claims "Saving Branding restyles every mail and shows the logo". Plugin layouts never in any phase-35 plan's files list.
|
||||
implication: the phase delivered the logo slot and partials as plumbing; no shipped layout or plugin template was updated to consume them, and verification checked the plumbing via test overrides, not out-of-box output
|
||||
|
||||
- timestamp: 2026-11-13T15:54Z
|
||||
checked: WinterCMS reference examples/golem15-wintercms-starter/modules/system/views/mail + classes/MailManager.php + plugins/golem15/user/views/mail/activate.htm
|
||||
found: Winter ships layout-default (wrapper + {% partial 'header' %} with subject + inner-body card + {% partial 'footer' %} "(c) year appName") and layout-system, partials header/footer/button/panel/promotion/subcopy/table. Winter user activate.htm uses `{% partial 'button' url=link type='positive' body %}Confirm account{% endpartial %}` and no plugin layout (default). MailManager::renderTemplate inlines CSS with TijsVerkoyen CssToInlineStyles (layout option disable_auto_inline_css). Winter brand settings have no logo.
|
||||
implication: postcard ported system layout and 4 partials but not Winter's default layout or header/footer partials; Go user templates dropped Winter's button partial; postcard never inlines CSS (only a <style> block) — fine for the browser preview, a parity gap for real mail clients
|
||||
|
||||
- timestamp: 2026-11-13T15:56Z
|
||||
checked: git history of plugin layouts; other plugins' mail
|
||||
found: sm-user-plugin layouts/user.htm from 63d6d04 (phase 07-03), paymentgateway layout from dee26dd (phase 18-04) — stubs predating Branding/partials. user.htm text wrap is `-- {{ .Content }} --`. 54 paymentgateway templates use layout paymentgateway with `[Zobacz zamówienie]({{ .orderUrl }}): {{ .orderUrl }}`. sm-mfa-plugin and sm-quizzes-plugin templates have no layout -> postcard default (bare div). KindBrand preview (Branding page) also renders in the default layout.
|
||||
implication: every out-of-box path except an explicit system-layout choice lands in a bare wrapper
|
||||
|
||||
- timestamp: 2026-11-13T15:58Z
|
||||
checked: demo DB system_mail_layouts / system_mail_templates
|
||||
found: golem15.user::mail.layouts.user is_custom=t (overridden during UAT test 5, no logoUrl); golem15.user::mail.activate is_custom=t (layout user). Other layouts not customized.
|
||||
implication: when verifying a fix on sm-demo-app, these two overrides must be reset or the new file versions won't show (drift notice instead)
|
||||
|
||||
## Resolution
|
||||
|
||||
root_cause: |
|
||||
(1) Logo: no shipped layout prints {{ .logoUrl }}. The variable is wired end to end (store.go builds an absolute URL that serves 200; mailer.options/Editor.render set opts.logoURL; renderParts passes "logoUrl" to both wrappers), but postcard's default/system/minimal and the plugin layouts user/paymentgateway never use it, there is no header partial, and brand.css.tmpl has no logo rule. Plan 35-01 tested the logo only through test-only layout overrides and pinned default.htm as untouched. The sandbox, CSP and URL resolution were ruled out.
|
||||
(2) CTA not a button: sm-user-plugin activate/restore/invite (+ -en) use the Markdown link [Aktywuj konto]({{ .Link }}), and the 54 paymentgateway templates use [Zobacz zamówienie]({{ .orderUrl }}): {{ .orderUrl }}. The Go port dropped Winter's {% partial 'button' %}. postcard's built-in button partial works and is styled with the brand colours, but no plugin calls it, and plugins can't until they require a framework tag with phase 35 (they require v0.6.0, and v0.6.4 has no partial func).
|
||||
(3) Unstyled plugin/default layouts: user.htm and paymentgateway.htm are stubs from phases 07-03 and 18-04 (<div class="layout-*">{{ .Content }}</div>). Neither class has a CSS rule, and neither layout has a wrapper, inner-body card, header or footer. The brand CSS only styles elements and Winter's wrapper classes, so the content sits flush on the grey body background. postcard's default.htm (used by mfa, quizzes and the Branding preview) is just as bare (<div class="content-body">), because only Winter's system layout was ported, not Winter's default layout with its header/footer partials. System looks "kind of proper" because it alone carries the Winter card structure, though it has no header/logo/footer and its content cell has zero horizontal padding.
|
||||
(4) Contributing, real sends only: postcard places the CSS in a <style> block and never inlines it (Winter runs CssToInlineStyles). The browser preview is fine, but mail clients that ignore or strip head styles will show unstyled mail even after the layouts are fixed.
|
||||
fix: (diagnose-only; see missing items in return)
|
||||
verification:
|
||||
files_changed: []
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
status: awaiting_human_verify
|
||||
status: resolved
|
||||
trigger: "User plugin logout: auth cookies not invalidated at once; requests keep authenticating ~60 min until token expiry (todo 2026-10-22-user-logout-cookie-stays-valid)"
|
||||
created: 2026-10-22T00:00:00Z
|
||||
updated: 2026-10-22T00:00:00Z
|
||||
@@ -42,3 +42,7 @@ The console layer (`modules/bonfire`) and the new logging module (`modules/diary
|
||||
- Removing the stack later means rewriting bonfire's widgets and diary's console handler; D-01 and D-02 are rated costly for that reason.
|
||||
- Plugins never import charm modules directly, so a later change of styling library touches only `modules/bonfire` and `modules/diary`.
|
||||
- A check in the plan's acceptance criteria (`go list` over every package's imports) keeps the import boundary honest.
|
||||
|
||||
## Addendum 2026-10-28: fang removed
|
||||
|
||||
`charm.land/fang/v2` was removed in quick 261028-rqd (console review finding IN-06). `fang.Execute` installs its own help function on the root just before `root.ExecuteContext`, so after `bonfire.Execute` the root's help function was no longer bonfire's list renderer, and cobra offers no per-root hook in between to restore it. bonfire had already switched off every fang feature except the error handler, so `bonfire.Execute` now runs `root.ExecuteContext` itself and renders errors with `RenderError` on the root's error stream. The only other thing fang did, enabling VT processing on Windows consoles, is done through `lipgloss.EnableLegacyWindowsANSI` on the output and error streams when they are files (a no-op off Windows). `go mod tidy` dropped fang and its exclusive transitive modules (mango, mango-cobra, mango-pflag, roff, x/exp/charmtone); no module was added. The list, help and error output stayed byte-identical (the goldens pass unchanged). The stack is now five charm modules plus colorprofile.
|
||||
|
||||
42
.planning/notes/2026-10-28-chromedp-rendered-crawl.md
Normal file
42
.planning/notes/2026-10-28-chromedp-rendered-crawl.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Decision: the site audit's rendered comparison uses chromedp, optionally
|
||||
|
||||
**Date:** 2026-10-28 (dependency approved 2026-11-04)
|
||||
**Status:** Accepted
|
||||
**Context:** Phase 33 (SEO output, audit and content, D-70), 33-CONTEXT.md "Rendered comparison (Jakub, 2026-10-28): optional chromedp", 33-RESEARCH.md Alternatives considered and Package Legitimacy Audit, plan 33-06 Task 4 (approval), plan 33-10 Task 4 (P33-55)
|
||||
|
||||
## Decision
|
||||
|
||||
The site audit's crawler (`sm-seo-plugin`, package `classes/crawl`) always checks the raw, server-rendered HTML. It compares a page's raw HTML with its JavaScript-rendered DOM only when an operator configures a Chrome or Chromium binary; without one every crawl records the comparison as skipped and says so (the crawl preview P6, `GET /_seo/api/v1/crawls/{id}` and the MCP tool `seo_get_crawl` answer `render {status: skipped}`).
|
||||
|
||||
- **`github.com/chromedp/chromedp` pinned at exactly v0.21.0.** Published 2026-10-11 (proxy.golang.org, origin `github.com/chromedp/chromedp` at tag `v0.21.0`, commit `7862adfd`), MIT. Approved by Jakub on 2026-11-04 (33-06 Task 4). v0.21.1 and v0.22.0 exist but were under two weeks old at approval and are deliberately not used. Its go.mod requires `github.com/chromedp/cdproto` v0.157.8 and `github.com/go-json-experiment/json`; nothing else.
|
||||
- **Why this library.** A maintained pure-Go client of the Chrome DevTools Protocol: no cgo, no Node runtime, no bundled browser. It drives an operator-installed Chrome or Chromium binary (RESEARCH Alternatives considered: a raw-HTML-only crawl misses content that appears only after JavaScript; a Node headless browser would add a second runtime to a single-binary deployment).
|
||||
- **What is compared** (D-70, P33-55): same-host links, an H1, or a substantial amount of text (at least 50 words and 20 % more) that appear only after JavaScript are reported as `content_js` with `details.check: rendered`. The raw HTML against the CMS record stays `details.check: cms` and runs on every crawl.
|
||||
- **Chrome is optional and operator-installed.** Production servers have none by default. The executable path is the Go config key `golem15.seo.crawl_chrome_path` (environment-overridable like every key); `golem15.seo.crawl_render_max` (default 200) caps the pages rendered per crawl, in crawl order. An empty path skips the comparison; a relative path, or one that is not an executable regular file, records the comparison as failed with a note. The crawl itself never fails because of the renderer.
|
||||
- **The path comes from config only, never from an admin setting or MCP.** Any holder of `golem15.seo.manage` can write the SEO settings and call the SEO tools; a writable executable path would let them make the server run an arbitrary binary (T-33-69).
|
||||
- **Plugin-only.** Only `sm-seo-plugin` requires chromedp. The framework go.mod does not (D-90: the framework gets no SEO code), and `grep chromedp go.mod` in summercms.go stays empty.
|
||||
|
||||
## The guard (P33-55)
|
||||
|
||||
Headless Chrome executes untrusted page JavaScript on the server, so it is held to the crawler's `fetchguard` limits:
|
||||
|
||||
- **Resolver pinning.** Before Chrome starts, the site host and its `www` twin are resolved and every address is checked with `fetchguard.IsPrivateAddr`; a private or reserved address refuses to start the renderer (render status failed, the note names the address) unless `golem15.seo.crawl_trusted` is true. The checked addresses go into `--host-resolver-rules` as `MAP <host> <address>` lines (one address per host, IPv4 first) followed by a final `MAP * ~NOTFOUND`, so every other host resolves to nothing and Chrome cannot re-resolve the site host to another address. Chrome applies the first rule that matches a host, so the catch-all must come last: with a leading `MAP * ~NOTFOUND` the site host itself fails with `ERR_NAME_NOT_RESOLVED` (checked against Chromium during 33-10; P33-55 had it leading).
|
||||
- **Request interception.** Every request is paused through the DevTools Fetch domain and continued only when it is `https` (`http` only in trusted mode) to the site host or its twin, or a `data:` or `blob:` URL; every other request fails with `BlockedByClient`. Third-party scripts, fonts, analytics and link-local metadata addresses are therefore never loaded.
|
||||
- **No state.** Each crawl uses a fresh temporary profile (`os.MkdirTemp`) removed when the renderer closes; no cookies, Authorization header, HTTP credentials or extensions; downloads denied. The crawler never signs in.
|
||||
- **Limits.** One tab renders at a time, 20 s per page, the DOM read with `OuterHTML` is capped at 5 MiB, and Chrome is closed when the crawl finishes, fails or is cancelled.
|
||||
- **Sandbox.** chromedp's default allocator flags are used without additions that weaken Chrome's sandbox (no `--no-sandbox`).
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
- **Raw HTML only.** No dependency and no browser on the server, but content and links that appear only after JavaScript go unreported, which D-70 asks the audit to find.
|
||||
- **`github.com/go-rod/rod`.** Also a pure-Go DevTools client, but it downloads a browser by itself by default and adds a larger API surface; chromedp's allocator takes an explicit executable path, which keeps the binary under operator control.
|
||||
- **A Node headless browser (Puppeteer, Playwright).** A second runtime next to the single binary.
|
||||
|
||||
## Package legitimacy
|
||||
|
||||
The package-legitimacy seam cannot check Go modules, so chromedp was gated by the blocking human check of plan 33-06 Task 4 and approved by Jakub (v0.21.0) before any `go get`. v0.21.0 resolves through proxy.golang.org with the origin above.
|
||||
|
||||
## Consequences
|
||||
|
||||
- `sm-seo-plugin/go.mod` requires `github.com/chromedp/chromedp v0.21.0` (and, through it, `github.com/chromedp/cdproto`); applications that mount the plugin get it through the plugin, and chromedp is compiled in whether or not a Chrome path is configured.
|
||||
- A site whose crawl should compare rendered pages installs Chrome or Chromium on the server and sets `golem15.seo.crawl_chrome_path`; nothing else changes.
|
||||
- If the library ever needs replacing, only `classes/crawl/render_chrome.go` changes: the crawler talks to the `crawl.Renderer` seam.
|
||||
50
.planning/notes/2026-10-28-webp-gen2brain.md
Normal file
50
.planning/notes/2026-10-28-webp-gen2brain.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Decision: WebP variants of attachment thumbnails through github.com/gen2brain/webp
|
||||
|
||||
**Date:** 2026-10-28 (dependency approved 2026-11-04)
|
||||
**Status:** Accepted
|
||||
**Context:** Phase 33 (SEO output, audit and content, D-85), 33-CONTEXT.md "Image formats (Jakub, 2026-10-28): WebP now, in Go", 33-RESEARCH.md Open Question 3 and Package Legitimacy Audit, plan 33-06 Task 4 (approval), plan 33-11 (P33-42, P33-43)
|
||||
|
||||
## Decision
|
||||
|
||||
Sites serve their featured images as `<picture>` with a WebP source and the original format as the `srcset` fallback. The WebP files are encoded in Go, once per thumbnail size, in a background job, never in the upload request. AVIF is deferred.
|
||||
|
||||
- **`github.com/gen2brain/webp` pinned at exactly v0.6.4.** Published 2026-07-01 (proxy.golang.org, origin `github.com/gen2brain/webp` at tag `v0.6.4`, commit `3dcf5268`), MIT (the bundled libwebp under its BSD licence, `lib/LICENSE.libwebp`). Approved by Jakub on 2026-11-04 (33-06 Task 4). Its go.mod requires `github.com/ebitengine/purego` v0.10.1 and nothing else.
|
||||
- **Why this library.** `golang.org/x/image/webp`, which `attach` already uses, decodes only; the standard library has no WebP encoder. cgo bindings to libwebp would break the cgo-free build of the single binary. gen2brain/webp encodes in Go without cgo.
|
||||
- **What is encoded.** Each thumbnail a caller asks for (`attach.File.ThumbKey` at a width, height and mode) gets one WebP variant next to it, at quality 80, under `attach.VariantKey(thumbKey, "webp")`. The original upload is never re-encoded, and images an editor inserts into a body keep their original file.
|
||||
- **Where it runs.** Journal's conga job `golem15.journal.image_variants` is dispatched after a featured image upload commits, and `journal:image-variants --all` backfills existing images. A slow or failing encode never fails the upload.
|
||||
|
||||
## How it runs (checked in the v0.6.4 module source, 2026-11-04)
|
||||
|
||||
- **First choice: the system libwebp through purego.** At init the package opens `libwebp.so` and `libwebpdemux.so` with `purego.Dlopen` (no cgo). On Linux this only works in a dynamically linked binary.
|
||||
- **Fallback: libwebp transpiled to Go.** When the libraries are missing (or with the build tag `nodynamic`), it uses libwebp compiled to WASM and then transpiled to plain Go source by wasm2go (`libwebp.go`, about 2.7 MB of generated Go). There is no WASM runtime at run time and no wazero; 33-CONTEXT's "WASM fallback" means this transpiled code. `webp.Dynamic()` reports which path is active.
|
||||
- **Linking consequence.** purego's no-cgo runtime support makes a binary that imports the package dynamically linked, even with `CGO_ENABLED=0`: the probe binary needed the ELF interpreter `/lib64/ld-linux-x86-64.so.2` and `libc.so.6`, `libdl.so.2` and `libpthread.so.0`. It runs on glibc hosts such as the Debian servers. It does not run in a `scratch` image, a distroless static image or on musl (Alpine). Building with `-tags nodynamic` keeps the binary statically linked and uses only the transpiled code (checked: `statically linked`, `Dynamic()` reports "dynamic disabled").
|
||||
- **Side effect.** The package registers a `webp` decoder with `image.RegisterFormat`, next to the one `golang.org/x/image/webp` registers. Both decode WebP, so `image.Decode` keeps working whichever one it picks.
|
||||
|
||||
## Benchmark
|
||||
|
||||
- **33-CONTEXT, 2026-10-28.** A 1200 px variant of a 2592×1754 photo: WebP 78 KB against JPEG q80 at 133 KB. Encoding took about 90 ms with the system libwebp and about 510 ms in the fallback. AVIF came out only about 6 % smaller than WebP, at 1.3× to 20× the CPU.
|
||||
- **Probe of v0.6.4 on 2026-11-04** (this workstation, a synthetic 1200×812 gradient, quality 80): about 17 ms through the system libwebp and about 90 ms in the transpiled fallback. WebP was 29.8 KB against 58.4 KB for JPEG q80. The two runs used different images and machines, so compare the paths with each other, not the numbers across runs.
|
||||
|
||||
## Where the code lives (P33-42)
|
||||
|
||||
- **Framework, generic media.** `modules/lagoon/attach/webp` (package `webp`): `Encode(w, img)` at quality 80 and `Variant(ctx, bucket, f, w, h, mode)`. `Variant` writes the variant next to the thumbnail, returns early when it exists, and deletes the key when an encode or close fails. In `attach` itself there is one generic helper, `attach.VariantKey(thumbKey, format)`.
|
||||
- **Why it is not SEO code.** A WebP variant of a thumbnail is a media format. It has nothing to do with SEO, and the framework gets no SEO wording (D-90). The addition is additive at patch level (D-106).
|
||||
- **Only binaries that import it link it.** `attach` does not import the sub-package, so a binary links gen2brain/webp, purego and the linking consequence above only when it imports `modules/lagoon/attach/webp`. In practice that means through sm-journal-plugin.
|
||||
- **The job lives in Journal.** Only plugins register conga jobs, and Journal owns the featured images and their variants table (`golem15_journal_image_variants`, P33-43).
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
- **AVIF through `github.com/gen2brain/avif`.** About 6 % smaller than WebP at 1.3× to 20× the CPU. Deferred.
|
||||
- **A Nuxt image pipeline (sharp).** New npm dependencies with a native module, and the encoding would move into the frontend server.
|
||||
- **cgo bindings to libwebp.** They break the cgo-free cross-compiled builds the applications use.
|
||||
- **Widths only, no new format.** This needs no dependency, but D-85 asks for a modern format.
|
||||
|
||||
## Package legitimacy
|
||||
|
||||
The package-legitimacy seam cannot check Go modules, so gen2brain/webp was gated by the blocking human check of plan 33-06 Task 4 and approved by Jakub at v0.6.4 before any `go get`. v0.6.4 resolves through proxy.golang.org with the origin above (`h1:SUDdmxADOAiPQ+5ylNmuHhuYf2dOi0KgKZHL5vpVCNU=`).
|
||||
|
||||
## Consequences
|
||||
|
||||
- The framework go.mod requires `github.com/gen2brain/webp v0.6.4` (and, through it, `github.com/ebitengine/purego v0.10.1`). Only packages under `modules/lagoon/attach/webp` import it.
|
||||
- An application that mounts sm-journal-plugin links the encoder. Its binary is dynamically linked against glibc unless it is built with `-tags nodynamic`. Installing libwebp on the server makes encoding about five times faster, and nothing else changes. The package opens the unversioned names `libwebp.so` and `libwebpdemux.so`, which Debian ships in `libwebp-dev`.
|
||||
- If the library ever needs replacing, only `modules/lagoon/attach/webp/webp.go` changes. Callers use `Encode` and `Variant`.
|
||||
44
.planning/notes/2026-10-29-plugin-marketplace.md
Normal file
44
.planning/notes/2026-10-29-plugin-marketplace.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Decision: Plugin marketplace on summercms.io and `summer plugin:install`
|
||||
|
||||
**Date:** 2026-10-29
|
||||
**Status:** Accepted (exploration)
|
||||
**Context:** `/msd-explore` session on summercms.io/marketplace, modelled on octobercms.com/marketplace
|
||||
|
||||
## Scope of v1
|
||||
|
||||
- The marketplace lists the public Golem15 plugins (`sm-*-plugin` repos that stay public). No paid plugins and no developer registration: Golem15 publishes every listing.
|
||||
- Its job is browsing plugins and getting the install command, nothing more.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Listing data: facts in the repo, presentation on summercms.io
|
||||
|
||||
- Each plugin repo carries a `plugin.yaml` manifest next to `plugin.go`: plugin ID, module path, name, description, required framework version, required plugins. The README and git tags (`vX.Y.Z`) complete the facts.
|
||||
- summercms.io ingests the manifest, README and tags when a plugin is tagged. The hook is the existing `scripts/changelog-post.py publish … --repo ../sm-<name>-plugin` step or a webhook.
|
||||
- Presentation fields (category, featured flag, screenshots, icon, sort order) are edited in the summercms.io admin, in the `golem15.summercms` site plugin.
|
||||
- Reason: install-critical data (module path, versions, requirements) cannot drift from the repo, while marketing details change without a plugin release. A repo manifest also leaves room for third-party submissions later (submit a repo URL).
|
||||
|
||||
### `summer plugin:install`
|
||||
|
||||
The form of the argument decides where the plugin comes from:
|
||||
|
||||
| Argument | Lookup | Default install mode | Override |
|
||||
|----------|--------|----------------------|----------|
|
||||
| Plugin ID, e.g. `golem15.journal` | summercms.io registry API: module path, versions, requirements | Go module (`require` in `go.mod`, `go mod download`) | `--source`: git submodule checkout at `plugins/<vendor>/<name>`, as `plugin:add` does today |
|
||||
| Git URL, e.g. `git@github.com:acme/sm-servers-plugin.git` | None. summercms.io is never contacted. ID and requirements come from the repo's `plugin.yaml`, module path from its `go.mod` | Git submodule checkout, which reuses the SSH access the user already has | `--module` (see the open research question on private modules) |
|
||||
|
||||
- Git URLs cover closed or private plugins from repositories the user has access to.
|
||||
- Both modes end with the same registration that `plugin:add` does (`summer.yaml`, `go.mod`, `go.work` where applicable), then `summer build`.
|
||||
- Precondition: public plugin repos on git.golem15.com fetch anonymously (HTTPS clone and `?go-get=1` meta). Confirmed as the intent for public plugins on 2026-10-29.
|
||||
|
||||
### Admin "Plugins" screen (read-only)
|
||||
|
||||
- **Installed** tab: the activated plugins from `backpack.App`, with version and description, and updates available compared against the registry.
|
||||
- **Marketplace** tab: searches the summercms.io registry and shows `summer plugin:install <id>` with a copy button. There is no install button.
|
||||
- The running binary never installs plugins. Plugins are compiled in; runtime loading stays rejected (`why-go-not-scala.md`, `.planning/research/FEATURES.md` anti-features). Queued installs and dev-mode live installs were considered and dropped as unnecessary for v1.
|
||||
|
||||
## Out of scope for v1
|
||||
|
||||
- Paid plugins, licensing, developer accounts and submissions.
|
||||
- Themes in the marketplace.
|
||||
- Installing from the admin panel.
|
||||
59
.planning/notes/2026-11-06-admin-code-editor-codemirror.md
Normal file
59
.planning/notes/2026-11-06-admin-code-editor-codemirror.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Decision: CodeMirror 6 for the admin `codeeditor` field
|
||||
|
||||
**Date:** 2026-11-06
|
||||
**Status:** Accepted pending human version check (Phase 35 plan 35-03 Task 3)
|
||||
**Relates to:** `.planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` (Why CodeMirror 6, Registry Safety), `.planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md` (Package Legitimacy Audit, Pitfall 5), `.planning/research/STACK.md`
|
||||
|
||||
## Decision
|
||||
|
||||
The admin SPA (`admin/package.json`) adds seven npm **runtime** dependencies with exact pins and a committed `package-lock.json`. They load only from `admin/src/components/form/codeeditor/editor.ts` via a dynamic import in `CodeEditorField.vue`, so CodeMirror lands in its own chunk (same pattern as TipTap).
|
||||
|
||||
| Package | Version | Use |
|
||||
|---------|---------|-----|
|
||||
| `@codemirror/state` | 6.7.6 | `EditorState` |
|
||||
| `@codemirror/view` | 6.43.15 | `EditorView`, `keymap`, `lineNumbers`, `MatchDecorator`, `ViewPlugin`, `lineWrapping`, `contentAttributes` |
|
||||
| `@codemirror/language` | 6.13.1 | `bracketMatching`, `HighlightStyle`, `syntaxHighlighting` |
|
||||
| `@codemirror/commands` | 6.11.1 | `history`, `historyKeymap`, `defaultKeymap` (without Mod-Enter) |
|
||||
| `@codemirror/lang-html` | 6.4.12 | `html()` grammar |
|
||||
| `@codemirror/lang-css` | 6.3.1 | `css()` grammar |
|
||||
| `@lezer/highlight` | 1.2.5 | `tags` for `HighlightStyle.define` (direct pin; UI-SPEC lists it as transitive) |
|
||||
|
||||
**Not used:** the `codemirror` meta package (`basicSetup`), and `indentWithTab` from `@codemirror/commands`.
|
||||
|
||||
**Keymap rule (research Pitfall 5):** extensions use `keymap.of([...historyKeymap, ...defaultKeymap.filter((b) => b.key !== 'Mod-Enter')])`. Tab is unbound so focus leaves the editor; Mod+S and Mod+Enter remain the form save hotkeys; Esc does not cancel the form.
|
||||
|
||||
## Why
|
||||
|
||||
- **MIT, modular, no workers.** CSP stays unchanged (`worker-src` not required). Accessible `contenteditable` surface.
|
||||
- **Rejected alternatives (UI-SPEC):** Monaco (size, workers), Ace (weaker a11y), a textarea overlay (caret sync), TipTap source mode (rich-text tool, not a code editor).
|
||||
|
||||
## Transitive packages
|
||||
|
||||
Pulled in by the pins above (not listed as direct dependencies unless already above):
|
||||
|
||||
- `@lezer/*` HTML/CSS grammars via `@codemirror/lang-html` / `@codemirror/lang-css`
|
||||
- `@codemirror/autocomplete` and `@codemirror/lang-javascript` via `@codemirror/lang-html`
|
||||
- `style-mod`, `w3c-keyname`, `crelt`
|
||||
- `@marijn/find-cluster-break` (transitive of `@codemirror/state`)
|
||||
|
||||
## Legitimacy
|
||||
|
||||
Re-checked with read-only `npm view <pkg>@<ver> dist.integrity` on 2026-11-13 before any install. Matches the Phase 35 research Package Legitimacy Audit (maintainer `marijn`, no `postinstall` scripts, high weekly downloads, official CodeMirror / lezer sources).
|
||||
|
||||
| Package | Version | `dist.integrity` | Notes |
|
||||
|---------|---------|------------------|-------|
|
||||
| `@codemirror/state` | 6.7.6 | `sha512-kAz+AncRtKuIknedxT1bq4XwXv4UowhbkHU1myPrtVb/jZtImWuV5BXzv5vK6i3kYACsdiZiQKFQQ5Mq7elW8w==` | [OK] |
|
||||
| `@codemirror/view` | 6.43.15 | `sha512-HHsfpqFeHyXLs983pSRe38Xajs0vFWZQ2BuX0m7Ki8w3jZ5iD8cuR3lBz2/5/X53Dhf32SBHKh6rtSTB6tKeGw==` | **[SUS] too-new** — published 2026-10-19 (18 days old on 2026-11-06 audit; past the project's 7-day cooldown). Same maintainer as every other CodeMirror pin. Human checkpoint before install. |
|
||||
| `@codemirror/language` | 6.13.1 | `sha512-zfvU2r3TyylQLMj/te+5CnQ0rSqZi8B1oTCBbQkagcLW4Xc6imab6qN+pEJhsuNOLaJqiRyBXp9UhWA1DhVvDw==` | [OK] |
|
||||
| `@codemirror/commands` | 6.11.1 | `sha512-O/4hG3SC1YwcmQ0d2UVNDs+AsaNWd1iHVxbTeEBuqH+6bExAiPK3iS/BvpY6rZGURALv4ZD3sIgcCmRvw3ehBg==` | [OK] |
|
||||
| `@codemirror/lang-html` | 6.4.12 | `sha512-pw2ReWKUqSkbvh76RAT4NYxiogRu+PWkR2ukAwO9uOgrm8uipkzjtKKtNpyeAQwHOqxEeSvAXZ6vr3AfyB9y/w==` | [OK] |
|
||||
| `@codemirror/lang-css` | 6.3.1 | `sha512-kr5fwBGiGtmz6l0LSJIbno9QrifNMUusivHbnA1H6Dmqy4HZFte3UAICix1VuKo0lMPKQr2rqB+0BkKi/S3Ejg==` | [OK]; also maintainer `adrianheine` |
|
||||
| `@lezer/highlight` | 1.2.5 | `sha512-O1GMVKgtf5YspFaRzpmqkVgMtIk2HG9uMAbH6wdAIdNh3TVzCsch/+cRi+6l2//UGDKe6NB9BW3cvuR5ezMQ0w==` | [OK] |
|
||||
|
||||
Install only after the Task 3 human gate: `npm --prefix admin install --save-exact` with exactly these pins, then `npm --prefix admin ci` against the committed lockfile. Lockfile integrity for each package must equal the values above.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Layout and partial HTML/CSS/text editing uses a real editor with Go `{{ ... }}` action highlighting (`cm-summer-action`), without changing the design-system colour tokens.
|
||||
- A load failure falls back to a monospace textarea that still saves (UI-SPEC C1).
|
||||
- `@codemirror/view` 6.43.15 may be replaced with 6.43.14 or older if the human checkpoint rejects the too-new flag; update this note and STACK.md in that case before installing.
|
||||
41
.planning/notes/2026-11-13-mail-layouts-css-inlining.md
Normal file
41
.planning/notes/2026-11-13-mail-layouts-css-inlining.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Decision: finished built-in mail layouts and CSS inlining through github.com/vanng822/go-premailer
|
||||
|
||||
**Date:** 2026-11-13
|
||||
**Status:** Accepted
|
||||
**Context:** Phase 35 UAT gap G-35-8 (35-UAT.md, test 8, severity major), debug session `.planning/debug/mail-layouts-unstyled.md`, Jakub's decision of 2026-11-13 (framework only; the plugin layouts and templates follow after the framework tag), plan 35-06
|
||||
|
||||
## What this supersedes
|
||||
|
||||
- **D-10's inlining claim.** 35-CONTEXT D-10 says the Branding colours "compile into the brand CSS slot that postcard already inlines". postcard never inlined: it placed the brand CSS and `mail.css` in the layout's style block and nothing more, so mail clients that drop style blocks showed unstyled mail. From this decision on, postcard inlines the CSS at render (below).
|
||||
- **35-01's "default.htm unchanged" gate.** Plan 35-01 kept `modules/postcard/assets/default.htm` byte-identical (a bare `content-body` block). That gate is lifted: the default layout is now WinterCMS's default layout (wrapper, header with the logo or the name, white card, copyright footer), built on two new built-in partials, `header` and `footer`.
|
||||
- **D-10's Branding fields.** Branding gains a **Site name** (`site_name` column, `postcard.Brand.SiteName`). Empty, it falls back to the display name of `mail.from` (`Acme` for `Acme <no-reply@acme.test>`). Layouts get it as `{{ .siteName }}`, next to `{{ .year }}`, the current year.
|
||||
|
||||
## Decision
|
||||
|
||||
- **`github.com/vanng822/go-premailer` pinned at exactly v1.38.0**, package `premailer`, with its default options: `RemoveClasses` false (class attributes stay, so plugin CSS hooks and the leftover style rules still match), `CssToAttributes` true (CSS widths and heights are mirrored to `width`/`height` attributes, as mail clients expect), `KeepBangImportant` false.
|
||||
- **Where it runs.** In postcard's render path (`renderParts`), so the admin preview, the test send and real sends get the same HTML: after the layout's HTML wrapper has rendered and passed `validateHTML`, the HTML goes through `NewPremailerFromString(...).Transform()`, and the result is checked by `validateHTML` again. The plain-text part is never touched.
|
||||
- **What it does.** It collects the rules of the document's style elements (the brand CSS, the layout's own CSS and `mail.css`), applies them to the matching elements by specificity, removes the style elements, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element in the head, marked `!important`. The DOCTYPE line is kept.
|
||||
- **Error fallback.** An inliner error (or a panic inside it, recovered) never stops mail: the un-inlined HTML is sent with its style block, and a warning keyed `inline:<layout code>` is logged at most once per warn interval (D-14 spirit).
|
||||
- **Opt-out, with WinterCMS's option name.** A file layout opts out with the header key `disable_auto_inline_css` (`true`, `1` or `yes`, any case); a database layout with the boolean column `disable_auto_inline_css` of `system_mail_layouts` (migration `202611130003_mail_layout_disable_auto_inline_css`), edited by a switch on the layout form's CSS tab. An opted-out layout keeps only its style block. The built-in layouts all inline. This matches `MailManager::renderTemplate` in WinterCMS, which runs CssToInlineStyles unless the layout's `disable_auto_inline_css` option is set.
|
||||
|
||||
## Facts checked (2026-11-13)
|
||||
|
||||
- **Versions and dates.** `go list -m -versions` lists v1.38.0 as the latest tag. proxy.golang.org reports v1.38.0 published 2026-11-04T18:13:54Z (origin `https://github.com/vanng822/go-premailer`, tag `refs/tags/v1.38.0`, commit `98a25222c9ea2827cfc13dd8f162976703574435`), nine days before this decision and past the 7-day cooldown; v1.37.0 was published 2026-10-02, so releases come roughly monthly. Module sum `h1:nYXopG+L6lcRV6dEAemLLE71bihun3gxgfNJZ9iYm1Q=`, go.mod sum `h1:6Jcm7sYO8ON3J/IIlox2fWq+YPgGopwx7VbETlZRZtY=`, both verified against the checksum database by `go mod download`.
|
||||
- **Licence and maintainer.** MIT (`LICENSE`: Copyright (c) 2015 Nguyen Van Nhu); maintained by its author since 2015. pkg.go.dev listed 246 importing packages at planning time.
|
||||
- **Its requirements.** `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, `golang.org/x/net` v0.62.0 (and `github.com/stretchr/testify` for its own tests). Its go.mod says `go 1.26.0`; this repository is at go 1.27.0.
|
||||
- **What MVS changes here** (dry run of `go get` and `go mod tidy` on a scratch copy of go.mod): `golang.org/x/net` v0.58.0 to v0.62.0, `golang.org/x/crypto` v0.57.0 to v0.58.0, `golang.org/x/text` v0.42.0 to v0.43.0, `golang.org/x/term` v0.46.0 to v0.47.0, and the indirect `golang.org/x/sys` v0.48.0 to v0.49.0 and `golang.org/x/sync` v0.23.0 to v0.24.0.
|
||||
- **Modules `go mod tidy` adds as indirect.** `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/andybalholm/cascadia` v1.3.4, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, and through html2text's table rendering `github.com/olekukonko/tablewriter` v1.0.7, `github.com/olekukonko/errors` v1.1.0, `github.com/olekukonko/ll` v0.0.9, `github.com/fatih/color` v1.18.0, `github.com/mattn/go-colorable` v0.1.14, `github.com/mattn/go-isatty` v0.0.20 and `github.com/ssor/bom` v0.0.0-20170718123548-6386211fdfcf. `github.com/gorilla/css` v1.0.1 was already in the module graph.
|
||||
- **Fit check** (the default layout with the brand CSS and a media query in `mail.css`, before the go.mod change, through a scratch modfile): the DOCTYPE line was kept, class attributes were kept, the button link carried `background-color:#d66829` in its style attribute, the media query stayed in a style element, and the output passed `validateHTML`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The framework go.mod requires `github.com/vanng822/go-premailer v1.38.0`; only `modules/postcard/inline.go` imports it. Every binary that links postcard links it, goquery, cascadia, html2text and tablewriter.
|
||||
- **Follow-up for consumers.** Applications and plugins that build against this checkout with a `replace` (sm-demo-app, sm-user-plugin, sm-paymentgateway-plugin and others) need `go mod tidy` to get the new go.sum lines; until then `go build` and `go test` in them report missing go.sum entries. Their trees are not changed in 35-06; the bump comes after the framework tag.
|
||||
- The style block of an inlined message holds only the leftover rules, not the brand CSS and `mail.css`. Tests and tools that read the style block for the brand CSS read the style attributes instead, or use a layout that opts out.
|
||||
- A CSS value an administrator writes is copied into style attributes. `validateHTML` runs on the inlined HTML, so a `javascript:`, `vbscript:` or `data:` address that reaches an attribute fails the render as before (and a failing override falls back to the file version, D-14).
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
- **An in-house inliner on `golang.org/x/net/html` with douceur and cascadia.** No new top-level module, but postcard would own selector specificity, cascade order, `!important`, media-query leftovers and the attribute mirroring, with their edge cases.
|
||||
- **`github.com/aymerick/douceur/inliner`.** Unmaintained since 2016.
|
||||
- **No inlining.** The UAT gap stays for every client that drops style blocks (several webmail clients and Outlook variants).
|
||||
33
.planning/notes/2026-11-13-mail-template-locale-groups.md
Normal file
33
.planning/notes/2026-11-13-mail-template-locale-groups.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Decision: one admin record per mail template, locale versions behind a switcher
|
||||
|
||||
**Date:** 2026-11-13
|
||||
**Status:** Accepted (shipped in Phase 35 plan 35-05)
|
||||
**Context:** `.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md` gap G-35-1 (UAT test 1, major): "each locale is a separate entry in backend is absolute disaster ... imagine site with 50 locales". User decision of 2026-11-13 confirming the gap-closure plans.
|
||||
**Relates to:** `35-CONTEXT.md` D-05, D-06, D-07, D-13, D-16; `35-UI-SPEC.md` C16; `modules/postcard/README.md` ("Locale variants", "Index rows, drift and reset"); `modules/cabana/README.md` (mail screens).
|
||||
|
||||
## Context
|
||||
|
||||
D-05 ("locale variants stay separate templates") made `postcard.SyncIndex` write one `system_mail_templates` row per file (`activate.htm`, `activate-en.htm`), and the cabana Mail templates list showed each row with a locale column and a locale filter. There was no grouping key and no per-locale editing inside one record, so N locales gave N list rows per template, and a locale that ships no file could not be customized at all.
|
||||
|
||||
## Decision
|
||||
|
||||
D-05 is superseded. A mail template is one admin record; its locale versions are edited behind a locale switcher in the template form. As shipped:
|
||||
|
||||
- **Group key.** `system_mail_templates.base_code` (migration `202611130001_mail_template_base_code`, nullable, indexed). It is the code with its locale suffix stripped, by the same rule as `postcard.TemplateLocale` (suffix after a dash in the last dotted segment, one of the mail locales): `postcard.TemplateBase`. A code without such a suffix is its own base. `postcard.SyncIndex` writes it on every template row.
|
||||
- **Mail locales** (cabana). The phrasebook translator's `Locales("")` plus, when a `cabana.TranslationWriter` is published and answers, its `EnabledLocales`. The default locale is the writer's `DefaultLocale`, else the translator's `Locale()`. The index syncs again when this set changes, so a 50-locale site (locales enabled through a translate plugin) gets 50 entries in the switcher without a restart.
|
||||
- **Fallback-locale rows.** `postcard.EnsureLocaleRows` gives every base template a row `<base>-<locale>` for every mail locale except the default that ships no file: source, description, subject, body, layout and `file_hash` from the base file, `base_code` the base. The default locale gets no row: the unsuffixed file is its version. Rows are created at sync for all templates and on show for the shown template; nothing is deleted.
|
||||
- **Variant set and order** (`cabana.RecordMeta.LocaleVariants`, `cabana.RecordLocaleVariant`, on the show and update responses of the mail templates screen only). Default (the unsuffixed file, label `mail.template.locale_default`), then by locale code: every locale with its own file, every other mail locale except the default, and any customized row of a locale that is no longer enabled. A group whose base has no file (only `x-en.htm` shipped) has no Default and no fallback rows. Labels and state words are translated on the server.
|
||||
- **What a fallback row shows.** Until it is customized, its form shows the default-locale version as it is sent now (the base row's effective subject, body and layout, its customization when there is one). Saving makes it customized with `base_hash` = the base file's hash.
|
||||
- **Per-locale customize / reset / drift (D-06, D-07).** Each version is its own row with its own `is_custom`, `base_hash` and `file_hash`. A fallback row's `file_hash` follows the base file, so "File changed" shows on it when the base file changes. `postcard.ResetOverride` accepts a fallback-locale code and returns it to the base file. Saves, preview and test send go through `postcard.Editor` exactly as before (D-13, D-16).
|
||||
- **Send resolution** (postcard, independent of any locale list, so `queue:work` needs no cabana). A name with its own file renders exactly as before. A name the catalog does not hold, of the form `<base>-<tag>` where `<base>` is a registered template and `<tag>` is a two-letter language optionally followed by `-` or `_` and a 2-8 character alphanumeric subtag (case-insensitive, the longest registered base wins), renders the base file with: the name's own customized row, else the base's customized row, else the base file. Any other unknown name keeps the "postcard: unknown template <name>" error. `postcard.Catalog.TemplateFor` exposes the resolved file. Core plugins are unaffected: sm-user-plugin and sm-paymentgateway-plugin send names that have files, and `scripts/check-phase35.sh --consumers` passes unchanged.
|
||||
- **List.** One row per template (the base row, or the lowest code when only variants ship), a Customized locales column (Default and locale codes of the customized versions, at most three then +N), Customized / File changed badges aggregated over the group, and the status filter applied to the whole template. The locale filter is removed.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
- **Multilingual fields (`mltext` / `mlmarkdown`) in one record.** One row would hold every locale's subject and body, but there would be no per-locale layout, reset or drift, and the send path would need a translate store.
|
||||
- **A form-level `?locale=` query parameter.** The switcher would edit one record under a locale parameter; FormView would change for every controller, and the per-locale state would still need rows.
|
||||
- **Rows for a locale created only on its first save.** A locale not yet customized could not be opened, so the switcher could not list it.
|
||||
|
||||
## Follow-up (outside this phase)
|
||||
|
||||
- Plugins that want per-locale admin versions pass `<template>-<locale>` for every locale they serve. sm-user-plugin's `classes.MailTemplate` maps only `en` today; postcard already resolves a locale without a file to the default-locale version, so passing the suffix for every locale is safe. This belongs to the plugin follow-up after the framework tag.
|
||||
79
.planning/notes/2026-11-14-mail-url-scheme-check.md
Normal file
79
.planning/notes/2026-11-14-mail-url-scheme-check.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# Decision: postcard checks URL schemes in decoded attribute values, never lets a site name stop a send, and prints the footer name literally
|
||||
|
||||
**Date:** 2026-11-14
|
||||
**Status:** Accepted; amended the same day by the review fixes of 35-REVIEW.md (re-review of 35-08/35-09): CR-01 residual, CR-02, WR-01, WR-02, WR-03 (see "Amendment" below); amended again by quick task 261114-p5m (CR-02 residual: an end tag inside a quoted attribute)
|
||||
**Context:** Phase 35 re-verification gap (35-VERIFICATION.md `gaps:`, the CR-01 regression), 35-REVIEW.md CR-01, WR-01 and WR-05, Jakub's decisions of 2026-11-14 (two plans: this fix in 35-08, then the regression and unit tests in 35-09; WR-01 and WR-05 bundled with CR-01), plan 35-08
|
||||
|
||||
## The problem
|
||||
|
||||
postcard's `validateHTML` ran `(?i)(?:javascript|vbscript|data):` over the whole rendered document. The built-in layouts print the site name (the Branding Site name, else the display name of `mail.from`) in the header and the footer, so a site name such as `Big Data: Summit` or a sender such as `"Metadata: Weekly" <x@example.com>` failed every send on the default and system layouts. The file version carries the same name, so the override-to-file fallback failed too, and the Editor refused every template and layout save while such a Branding name was stored. An application that sends mail today could stop sending password resets after upgrading, without anyone touching the admin.
|
||||
|
||||
Two related findings: the check read undecoded markup, so `href="javascript:..."` in a layout or partial override passed it and was sent as is when the layout opted out of inlining (WR-05), and an inlined result that failed the post-inline check stopped the message although the docs promise the inliner never does (WR-05). The footer rendered the copyright line, and with it the site name, as Markdown (WR-01).
|
||||
|
||||
## What this supersedes
|
||||
|
||||
- **35-RESEARCH.md Pitfall 8** ("keep the behaviour, it matches sends") and 35-PATTERNS.md "HTML safety gate: reuse them unchanged", for postcard. Prose is no longer treated as a URL.
|
||||
- **The postcard README sentence** saying that text such as `metadata:` is refused at save.
|
||||
- **The README sentence** saying an inlined result that fails the safety check fails the render.
|
||||
- **D-13 itself stands:** `javascript:`, `vbscript:` and `data:` URLs are still refused at save and at send, now also when they are entity-encoded.
|
||||
- `cabana.RenderMarkdown`'s own regexes (the admin Markdown preview) are out of scope and unchanged.
|
||||
|
||||
## Decision
|
||||
|
||||
### What the scheme check reads (`unsafeMarkup`, modules/postcard/safety.go)
|
||||
|
||||
The rendered HTML is read with `golang.org/x/net/html`'s tokenizer (already a direct framework requirement, used by seaglass, tide and cabana). The tokenizer lower-cases attribute names and decodes character references in attribute values (`:`, `:`, `:`, `j`), so the check sees what a mail client sees.
|
||||
|
||||
- **Single-URL attributes** (`urlAttributes`): `action`, `background`, `cite`, `codebase`, `data`, `dynsrc`, `formaction`, `href`, `icon`, `longdesc`, `lowsrc`, `manifest`, `poster`, `profile`, `src`, `usemap`, `xlink:href`, and the SVG animation targets `from`, `to`, `by`. A value is refused when, decoded, with every ASCII whitespace and control character (U+0000 to U+0020 and U+007F) removed and lower-cased, it starts with `javascript:`, `vbscript:` or `data:` (`hasDangerousScheme`). Removing whitespace closes tab- and newline-split schemes.
|
||||
- **List-valued attributes** (`urlListAttributes`: `srcset`, `ping`, `archive`, `values`), **`style` attributes**, the **`content` attribute of `meta` elements**, the **text of `style` elements** and **comment data**: refused when the existing `dangerousScheme` pattern matches anywhere in the decoded value with whitespace and control characters removed (`stripURLSpace`, shared with `hasDangerousScheme`; WR-01), so `values="java	script:..."` is refused. The conservative rule stays for CSS and lists, where prose does not belong.
|
||||
- **Raw-text elements and comments are checked as markup too** (CR-02). The tokenizer reads the content of `iframe`, `noembed`, `noframes`, `noscript`, `plaintext`, `script`, `style`, `textarea`, `title` and `xmp` as one text token, also after a self-closing start tag. A mail client may parse it as markup (it renders with scripting off, so `noscript` content is markup; inside `svg`/`math` these are foreign elements with markup children), so `unsafeMarkup` checks the raw source of that content, and the data of every comment (Outlook conditional comments), again as markup. Each nested check reads a strictly shorter text; nesting deeper than eight levels (`maxMarkupDepth`) is refused ("rendered HTML nests raw-text elements or comments too deeply"). The raw source, not the decoded text, is re-read, so `<a href=...>` in a `title` stays text. After this HTML reading, `unsafeMarkup` reads the same text once more as tags only (`unsafeTagReading`, quick 261114-p5m): x/net/html's tokenizer with `NextIsNotRawText()` called after every raw-text start tag, and the `<` of each `<!--` blanked to a space (same length, so snippets point into the original). Attribute quoting alone decides where a tag ends, so `<svg><style><a title="</style>" href="javascript:...">` and `<!--[if mso]><a title="-->" href="javascript:...">` are refused. The same attribute checks and messages apply (`unsafeAttrs`, shared by both readings). Both readings run at every depth, both are linear, and the depth limit is unchanged.
|
||||
- **Text content is not checked for schemes.** It is not a URL; a mail client does not follow it. `metadata:` or `Big Data: Summit` in a body, a header or a footer passes.
|
||||
- **Event handlers.** The raw-markup regex for `script`/`iframe`/`object`/`embed` tags stays as it is and runs first. Event handlers are attributes only: the tokenizer walk refuses any attribute whose name starts with `on`, with or without whitespace before it (`<img src="x"onerror=...>`), also inside raw-text elements and comments. The whole-document regex for whitespace-prefixed `on*=` is dropped (WR-02): it read text as well, so a variable such as `buy one = get one free` stopped its own message, and the footer's `© <year> Online=Shop` stopped every send (CR-01 residual).
|
||||
- **Error messages are unchanged** ("rendered HTML contains a dangerous URL scheme", "rendered HTML contains event handlers"). The snippet is the raw markup of the offending token, so an editor error shows the encoded form the administrator wrote.
|
||||
- **Draft layout CSS** is checked as the content of a style element, so the error stays on `content_css`.
|
||||
|
||||
### Site names never stop a send (`postcard.UnsafeText`, `siteNameFrom`, `layoutSiteName`)
|
||||
|
||||
- **`postcard.UnsafeText(s string) bool`** (exported, so cabana can refuse a name at save): a text is unsafe when, HTML-escaped with the standard library's `html.EscapeString` as html/template prints text and placed where the built-in layouts print it (after `© 2000 ` in a footer paragraph, in the header span and in the logo's `alt`; `printContext`, CR-01 residual), it fails the rendered-HTML checks, or when it holds a script URL (`scriptURLText`): `javascript:` or `vbscript:` at a scheme boundary (whitespace may follow the colon, since `javascript: alert(1)` still runs), or a data URL: `data:` at a scheme boundary, an optional MIME type and the `;` or `,` every data URL has (WR-03). A scheme boundary is the start of the text or a character that cannot belong to a URL scheme (anything but ASCII letters, digits, `+`, `.` and `-`). Escaped text is never markup, so since the handler regex is gone the rendered-HTML part refuses nothing a layout prints as text; it stays as a guard for a later check that depends on context. `Big Data: Summit`, `Metadata: Weekly`, `Metadata:Weekly`, `Data:Lab`, `Online=Shop` and `Shop onclick=x` are safe; `javascript:alert(1)`, `javascript: Acme`, `data:text/html,x` and `data:,x` are not.
|
||||
- **Render-time drop.** An unsafe Branding Site name is treated as empty, so the documented fallback applies (the display name of `mail.from`, if that one is safe); an unsafe `mail.from` display name gives no name. This holds on every render path: the file version, the override render built from it, the override-failure fallback and the editor. One warning per source per minute through the mailer's existing rate-limited `warn`, keyed `site_name:branding` or `site_name:mail.from`, message "postcard: site name left out of the layouts, it fails the mail safety check", with the source and never the value.
|
||||
- **The Branding preview** of an unsaved draft drops the name the same way, so the preview shows what would be sent; the save is what refuses it.
|
||||
- **Save rule.** cabana's `MailBrandSetting.BeforeValidate` refuses a name `postcard.UnsafeText` refuses: a 422 on `site_name` with `backend::lang.mail.brand.site_name_unsafe`, collected with the colour and logo details. Saving a template or a layout while an unsafe name is stored is not refused (the name is left out of the render).
|
||||
- **Copy** (`mail.brand.site_name_unsafe`): en "This name cannot be shown in mail. Remove addresses that start with javascript:, vbscript: or data:."; pl "Tej nazwy nie można pokazać w wiadomościach. Usuń adresy zaczynające się od javascript:, vbscript: lub data:." (the "text such as onclick=" clause was dropped with the handler regex, WR-02; 35-UI-SPEC.md and 35-08-PLAN.md still quote the 35-08 copy)
|
||||
|
||||
### The inliner never stops mail (WR-05 contradiction)
|
||||
|
||||
The documented behaviour wins. The check sees decoded attribute values and style element CSS before inlining, whether or not the layout sets `disable_auto_inline_css`. An inlined result that still fails it is treated like an inliner error: the un-inlined HTML, which passed the check, is sent with its style block, and a warning keyed `inline:<layout>` is logged ("postcard: inlined CSS failed the safety check, sending the style block only").
|
||||
|
||||
### The footer prints the name literally (WR-01)
|
||||
|
||||
The `footer` partial gains a `text` argument, printed as plain text (a paragraph through html/template in the HTML part, verbatim in the text part); `body` stays Markdown for callers that pass Markdown on purpose. The default and system layouts pass the copyright line as `text`, so `*Acme*`, `Acme <Studio>` and `[x](url)` appear as typed, escaped, as in the header. The footer partial shipped in 35-06 and is in no tag yet (the newest tag, v0.6.4, predates it), so no released override depends on the old call.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
- **Keep the whole-document regex and only guard the site name.** Body text and other configuration text (`metadata:` in a template body, a variable, a partial argument) would keep stopping sends.
|
||||
- **A bluemonday-based mail sanitizer.** It rewrites instead of refusing, and would need a mail allowlist for style elements, tables and layout attributes. The 2026-10-11 note scopes bluemonday to stored rich text; this check only locates attribute values with x/net/html and keeps postcard's refuse-and-fall-back contract.
|
||||
- **Failing the render when the inlined result fails the check** (the reviewer's alternative for WR-05). It stops mail that passed the check, contradicts the documented promise and D-14.
|
||||
- **Re-checking from a raw-text element's content start to the end of the document** (for the CR-02 residual). Inside the recursion it re-reads the rest of the document once per raw-text element and comment, which is quadratic or worse on hostile input.
|
||||
- **Using the x/net/html parse tree as the check.** It loses the raw snippet the editor shows, reads `xmp` and `noembed` as raw text and ends a conditional comment at the first `-->`, while CR-02 deliberately checks that content as markup.
|
||||
|
||||
## Residual risk accepted
|
||||
|
||||
- CSS escape sequences inside CSS (`\6a avascript:`) are not decoded. Mail clients do not run script URLs from CSS.
|
||||
- Re-reading raw-text element and comment content as markup over-refuses in the rare case where a client would read it as text (an HTML-context `textarea` holding markup, a CSS string holding `<a href="javascript:...">`). No mail markup needs either.
|
||||
- html/template escapes a template's literal `title` and `textarea` text itself, so an `<svg><title><a href=...>` in a layout or body is sent as escaped text; the check refuses the unescaped form wherever else it can appear.
|
||||
- The tag reading treats comment and raw-text content as markup with quotes honoured. An unbalanced quote inside a comment or raw-text element can therefore join later text into one tag, and text after it that looks like an attribute (`online=yes` after a stray quote) is refused although no reader sees a tag there. No mail markup leaves a quote open in a comment or a style element.
|
||||
|
||||
## Amendment (review fixes, 2026-11-14)
|
||||
|
||||
The re-review of 35-08/35-09 (35-REVIEW.md, f1d22353) and the re-verification (35-VERIFICATION.md) found two gaps in this decision, fixed in commits `fix(35): CR-01 ...` through `fix(35): WR-03 ...`:
|
||||
|
||||
- **CR-01 residual:** `UnsafeText` checked a name on its own, but the footer prints it after `© <year> `, which gave `Online=Shop` the whitespace the handler regex needed; every default/system send failed. First fixed by checking the name in its print context (`printContext`), then removed at the cause with the handler regex (WR-02), so such names are shown and saved.
|
||||
- **CR-02:** the tokenizer-only walk did not look inside raw-text elements, a regression against the pre-35-08 whole-document regex; now re-read as markup (above).
|
||||
- **WR-01:** whitespace stripping for every scheme check; **WR-03:** the data-URL shape for site names.
|
||||
- **CR-02 residual** (35-VERIFICATION.md truth 18, quick 261114-p5m): the re-check read raw-text content only up to the tokenizer's end tag, which an attribute value can contain (`<a title="</style>" href="javascript:...">`). Fixed by the tag reading above; the verifier's conditional-comment advisory (`-->` inside an attribute) is covered by the same reading.
|
||||
|
||||
## Consequences
|
||||
|
||||
- postcard imports `golang.org/x/net/html` (no go.mod change) and the standard library `html` package.
|
||||
- `postcard.UnsafeText` is new exported API; `Mailer`, `Catalog.Register` and `pact.HasMailTemplates` keep their signatures.
|
||||
- Fixtures that pinned prose as unsafe change with the code (editor, fallback, partials and override smoke tests); the 35-07 subtest that pinned an unsafe stored name is replaced by `TestMailBrandSiteName/unsafe_name_refused`.
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
phase: "11.2"
|
||||
slug: "ready-to-share-summercms-io-website-and-newsletter-plugin"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-11-05"
|
||||
---
|
||||
|
||||
# Phase 11.2 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail. The newsletter plugin was not built in this phase (moved to backlog 999.1); no threat in the register concerns it. Evidence roots: FW = `summercms.go`, APP = `../sm-summercmsio-app`, PLUG = `APP/plugins/golem15/summercms`, SITE = `APP/vue-summercmsio-app`. Verified against the current tree; later phases (changelog, marketplace, VPN admin) changed the app, and replaced prongs are noted. T-11.2-SC is declared in all three plans (19 rows, 17 IDs).
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| npm registry → build machine | third-party packages run during install and generate | tarballs, git deps, install scripts (high) |
|
||||
| en.json / terminal.json → rendered HTML | repository copy becomes public HTML | i18n strings, terminal commands (medium) |
|
||||
| page → visitor clipboard | the Copy button writes text visitors paste into a shell | six shell commands (low) |
|
||||
| page → third-party origins | any runtime request elsewhere leaks visitor data | IP, Referer (medium) |
|
||||
| internet → nginx (rome) | untrusted HTTP; TLS terminates here | all public requests (high) |
|
||||
| nginx → summercms-io on 127.0.0.1:8095 | proxied requests filtered by path and method | path, method, X-Forwarded-For (medium) |
|
||||
| request path → embedded file map | an untrusted path selects a file and may redirect | URL path, Location (high) |
|
||||
| site.yaml / CLI flags → docs header HTML | configured URL written into every docs page | site_url, site_label (medium) |
|
||||
| operator machine → rome | binary and config upload; secrets stay on the server | binary, config (medium) |
|
||||
| summercms.go → module proxy | a pushed tag becomes immutable public state | release tag (medium) |
|
||||
| test results → phase sign-off / env gates → integration tests | a gate misreading skips passes untested behaviour | test events, gate variables (medium) |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-11.2-01 | Tampering (XSS) | components rendering en.json | medium | mitigate | no v-html/innerHTML under SITE/app/; inline code via `<i18n-t>` | closed |
|
||||
| T-11.2-02 | Information disclosure (privacy) | font loading | medium | mitigate | `@nuxt/fonts` build-time download (SITE/nuxt.config.ts:40,64-71); SITE/tests/output.test.ts:218-231 asserts no Google font hosts; built output clean | closed |
|
||||
| T-11.2-03 | Tampering | Copy button payload | low | accept | AR-11.2-01 | closed |
|
||||
| T-11.2-04 | Information disclosure | PLUG static.go path resolution | high | mitigate | `path.Clean` + dot-segment 404 + preloaded map only, dotfiles never loaded (static.go:131-183); smoke.sh:230 and static_test.go:155-156 assert `/docs/.summer-docs` 404 | closed |
|
||||
| T-11.2-05 | Spoofing (open redirect) | /docs and extension-less redirects | medium | mitigate | constant `/docs/` redirect (plugin.go:86); redirect only to an existing mapped name (static.go:178-182); TestStaticRedirectLocations covers `//evil`, `../`, backslash | closed |
|
||||
| T-11.2-06 | Tampering (MIME sniffing) | static.go headers | low | mitigate | own content-type table first (static.go:30-60); `nosniff` on every file incl. 404s and scripts | closed |
|
||||
| T-11.2-07 | Elevation of privilege | admin exposure | high | mitigate | public nginx `/backend` → 404 (summercms.io.conf:74-76), binary on loopback, check-deploy.sh:129-130 guards the block; admin only on the VPN vhost (10.8.3.0/24). Replaced since: plugin now has admin controllers (Phase 34) and smoke.sh:225 expects 200 on the binary; the internet-facing control holds | closed |
|
||||
| T-11.2-08 | Information disclosure | DB password and app key | high | mitigate | empty secrets in committed config; `.env` gitignored, only `*.example` tracked; `.env` root:summercms 0640, never rsynced (DEPLOY.md:195,289) | closed |
|
||||
| T-11.2-09 | Tampering (XSS) | docs header site_url | medium | mitigate | `checkSiteURL` on yaml key and flag (internal/docsite/load.go:125,145-161,289); `html/template` with plain string; load_test.go rejects `javascript:` and `//` | closed |
|
||||
| T-11.2-10 | Tampering (clickjacking) | public pages | low | accept | AR-11.2-02 | closed |
|
||||
| T-11.2-11 | Information disclosure (transport) | nginx | high | mitigate | 80→443 301 except ACME, www→apex, certbot certs, HSTS (summercms.io.conf:20-63); binary binds 127.0.0.1:8095 | closed |
|
||||
| T-11.2-12 | Denial of service | nginx and binary | medium | mitigate | `limit_except GET HEAD` on `/` (:176-179); site routes GET-only (routes_test.go, smoke POST → 405); preloaded static files; supervisor restart | closed |
|
||||
| T-11.2-13 | Tampering / Repudiation | v0.1.0 tag | medium | mitigate | blocking-human checkpoint (11.2-02-PLAN.md:318) resolved as defer-tag; no v0.1.0 exists; all tags annotated; CLAUDE.md requires go-ahead | closed |
|
||||
| T-11.2-14 | Elevation of privilege | runtime account | medium | mitigate | nologin system user, dedicated Postgres role and DB, root-owned install root with only `storage/` writable (DEPLOY.md:173-182); supervisor `user=summercms` | closed |
|
||||
| T-11.2-15 | Repudiation (false green) | scripts/check-phase11.2.sh | medium | mitigate | detector refuses build failure, no-tests, skip, fail, zero tests, missing named tests (:58-120); unknown flag exits 2 | closed |
|
||||
| T-11.2-16 | Tampering (silent skip) | build-gated tests and terminal check | medium | mitigate | gate sets `SUMMERCMS_REQUIRE_BUILD=1` and `SUMMERCMS_TERMINAL_CHECK=1`; links_test.go `requireBuild` fails instead of skipping | closed |
|
||||
| T-11.2-SC (01) | Tampering | pnpm installs | high | mitigate | exact pins, committed lockfile (git deps locked to commits), build allow-list of three packages, `--frozen-lockfile` (APP/scripts/build.sh:121) | closed |
|
||||
| T-11.2-SC (02) | Tampering | dependency installs | high | mitigate | APP go.mod first-party only; PLUG direct requires (Phase 34) all already in FW go.mod at the same versions; go.sum committed; dirty-tree builds refused (build.sh:80-90) | closed |
|
||||
| T-11.2-SC (03) | Tampering | dependency installs | low | accept | AR-11.2-03 | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-11.2-01 | T-11.2-03 | Payload is the bundled terminal.json, identical to the visible lines; the page only writes to the clipboard and never reads it. | 11.2-01 PLAN | 2026-11-05 |
|
||||
| AR-11.2-02 | T-11.2-10 | Static marketing and docs pages with no state-changing actions; the admin CSP is deliberately not reused because it blocks Nuxt's inline scripts (D-07). | 11.2-02 PLAN | 2026-11-05 |
|
||||
| AR-11.2-03 | T-11.2-SC (03) | Tests use the stdlib and the existing node:test runner; no package is added; `pnpm install --frozen-lockfile` reuses 11.2-01's lockfile. | 11.2-03 PLAN | 2026-11-05 |
|
||||
|
||||
*Accepted risks do not resurface in future audit runs.*
|
||||
|
||||
---
|
||||
|
||||
## Notes (non-blocking)
|
||||
|
||||
- **Attack surface added after 11.2** (covered by later phases' registers): admin controllers on the binary behind the VPN vhost; `APP/DEPLOY.md:190` ("nginx refuses /backend, so nothing writes runtime config overrides") is stale now that the admin is reachable over the VPN — writes would still fail on the root-owned `config/`. New write routes: `/_journal/api/v1/` (token + throttle) and POST `/api/registry/v1/ingest` (T-34-15/16). Marketplace readme `v-html` is covered by T-34-13.
|
||||
- **Open review info items:** IN-01..IN-08 (11.2-REVIEW-DISPOSITION.md), none security-relevant beyond IN-07 (links_test.go follows redirects).
|
||||
- **UAT:** 11.2-UAT.md is still `testing` with tests 1-3 pending; the cutover test expects v0.1.0, which was never created (releases started at v0.1.1). Superseded rather than failed.
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-11-05 | 19 rows (17 IDs) | 19 | 0 | msd-security-auditor (ASVS L1, block_on high; repo contents only, no live-host checks) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
|
||||
**Approval:** verified 2026-11-05
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
phase: "16.2"
|
||||
slug: "plugin-provided-field-types-and-the-blog-editor-formwidget"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-10-28"
|
||||
---
|
||||
|
||||
# Phase 16.2 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail.
|
||||
|
||||
Paths are relative to the meta repo (`summercms.go/`, `sm-journal-plugin/`, `vue-journal-layer/`, `sm-grzybyfunkcjonalne-app/`). Code was checked at each repo's HEAD; for code that later moved (the site-cache purger now lives in `summercms.go/modules/cooler`), the 16.2 release commit `5eea57f` was checked too.
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| admin browser → cabana admin API | Save bodies, upload bodies and field-type requests (cookie or Bearer session) | field values in every locale, uploaded files |
|
||||
| plugin Go code → cabana | Decode, Load, ListValue and Upload run inside cabana's handlers and save transaction | decoded values, plugin errors and notices |
|
||||
| plugin element JS → admin SPA DOM | The element runs in the admin origin under CSP `script-src 'self'` | `value` property, plain attributes, `summer-upload` events |
|
||||
| stored post HTML → admin editor DOM | Imported or previously saved HTML is parsed into the editor | untrusted HTML |
|
||||
| admin save body → Journal Decode | Every locale's content value crosses here through cabana | HTML to sanitize |
|
||||
| editor upload → media bucket | User files become public URLs under `/storage/app/uploads/public` | image bytes, object keys |
|
||||
| Journal API `content_html` → site `v-html` | Stored HTML becomes page markup | HTML, embed placeholders |
|
||||
| site page → youtube-nocookie.com | The visitor's browser loads a third-party frame | referrer, visitor IP |
|
||||
| Go host → Nuxt (loopback HTTP) | Journal calls the layer purge route with a bearer token | purge token, slug |
|
||||
| internet → nginx → Nuxt | Visitors reach Nuxt with GET/HEAD only; nginx adds forwarding headers | requests, X-Forwarded-For |
|
||||
| npm registry → plugin build | `@tiptap/*` packages enter the committed bundle | third-party code |
|
||||
| executor → git origin / UAT server | Tags and pushes read by other repos; release runs next to the live Winter site | tags, binaries, `.env` secrets (server only) |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-16.2-01 | Spoofing | compileFieldTypes alias registry | high | mitigate | `summercms.go/modules/cabana/field_type.go:106` refuses core aliases, `:166-171` refuses a cross-plugin alias naming both owners, `:172` checkWidgetTag (prefix check `extension.go:346`) | closed |
|
||||
| T-16.2-02 | Tampering (stored XSS) | decodePluginFields | high | mitigate | `crud.go:830-852` runs it inside the save transaction; `field_type.go:465/489/511` decode host value and every locale; only skip is the served-value match `:539-541`, which writes nothing | closed |
|
||||
| T-16.2-03 | Elevation of Privilege | fieldUpload route | high | mitigate | `http.go:452` requireAjax; `field_type_upload.go:35` protect (guard and permissions `http.go:1216-1225`), `:49/:142-160` field/context check and 404 without Upload, `:124` loadRecord scope; `auth.go:253` SameSite=Strict | closed |
|
||||
| T-16.2-04 | Denial of Service | fieldUpload body | medium | mitigate | `field_type_upload.go:69` MaxBytesReader on `upload_bytes`, `:85/:168-177` exactly one part, `:200-204` 413 | closed |
|
||||
| T-16.2-05 | Information Disclosure | PluginField / element | high | mitigate | `admin/src/components/form/fields/PluginField.vue:63-65,76-84` value and plain attributes only, upload via SPA `api.POST` `:133`; test `admin/tests/form/PluginField.test.ts:103` | closed |
|
||||
| T-16.2-06 | Tampering | typeOptions to element | low | mitigate | `PluginField.vue:44,81` JSON attribute string; no `v-html` | closed |
|
||||
| T-16.2-07 | Information Disclosure | plugin errors | medium | mitigate | `field_type.go:669-686` only `*pact.FormFieldError` → 422; `:690-693` and `:727-729` opaque 500 | closed |
|
||||
| T-16.2-08 | Tampering | untouched skip | low | accept | See AR-16.2-01 | closed |
|
||||
| T-16.2-33 | Tampering (admin XSS) / DoS | save notices | medium | mitigate | `admin/src/components/form/FormField.vue:86`, `ui/Toast.vue:34` text interpolation only; `field_type.go:40-42,799,811` 10 notices per field/locale, 500 runes; test `FormField.test.ts:50` | closed |
|
||||
| T-16.2-09 | Elevation of Privilege (admin XSS) | rawHtml node view | high | mitigate | `sm-journal-plugin/assets/src/blogeditor/extensions.ts:301,315` textContent; parse in inert document `:270-273`; test `tests/blogeditor/smoke.test.ts:135` | closed |
|
||||
| T-16.2-10 | Tampering (stored XSS) | Source tab and pasted HTML | high | mitigate | `classes/blog_editor.go:164` SanitizeHTMLReport on every locale; admin `FormView.vue:478` adopts the stored value; layer `PostBody.vue:13` sanitizes again | closed |
|
||||
| T-16.2-11 | Tampering | link mark | medium | mitigate | `extensions.ts:42-63` isPolicyUrl (control chars removed first), `:545`; `element.ts:465,570`; tests `smoke.test.ts:417-424` | closed |
|
||||
| T-16.2-12 | Elevation of Privilege | bundle under admin CSP | medium | mitigate | no `eval(`/`new Function(` in `assets/dist/blogeditor.js`; `element.ts:202` `injectCSS: false`; CSS scoped under `golem15-journal-blogeditor` | closed |
|
||||
| T-16.2-13 | Information Disclosure | uploads | high | mitigate | `element.ts:559` dispatches `summer-upload {id, file}` only; no fetch, XHR, cookie or storage access in `assets/src/blogeditor` | closed |
|
||||
| T-16.2-14 | Tampering (stored XSS) | decodeBlogHTML (posts, categories) | high | mitigate | `blog_editor.go:154-166`; `models/post/fields.yaml:19`, `models/category/fields.yaml:28`; tests `posts_admin_smoke_test.go:360`, `categories_admin_editor_test.go:56` | closed |
|
||||
| T-16.2-31 | Tampering (stored XSS) | newHTMLPolicy editor-output extension | high | mitigate | `classes/format_html.go:63-72`, exactly four AllowAttrs added since `c60abc6`; 16.1 policy tests unchanged; `editor_policy_test.go:68` | closed |
|
||||
| T-16.2-34 | Denial of Service | SanitizeHTMLReport and removal notices | low | mitigate | `format_html.go:105` (`maxRemovalNames = 10`), `:145-153`; cabana cap (T-16.2-33) | closed |
|
||||
| T-16.2-15 | Tampering / Elevation | uploadBlogImage | high | mitigate | `media_store.go:89-93` allowlist without svg, `:20,98-104` 10240 KiB cap; `blog_editor.go:365-375` DetectContentType; staging vhost `:89` nosniff | closed |
|
||||
| T-16.2-16 | Tampering | upload keys | medium | mitigate | `blog_editor.go:129-147` folder check at boot, `:397-426` safeUploadName; `media_store.go:155,193-224` never overwrites | closed |
|
||||
| T-16.2-17 | Repudiation / contract | public posts and media routes | medium | mitigate | `controllers/api/posts_helpers.go`, `posts.go`, `routes.go` unchanged `c60abc6..5eea57f`; `api/media.go:43-63` keeps body and errors | closed |
|
||||
| T-16.2-18 | Information Disclosure | content_html companion writes | low | mitigate | `controllers/posts.go:216-224,271-308` written locales only, in the transaction | closed |
|
||||
| T-16.2-19 | Tampering (iframe injection) | expandEmbeds | high | mitigate | `vue-journal-layer/app/utils/embeds.ts:41` exact regex, `:51` provider allowlist, `:53` id pattern, `:29` fixed host | closed |
|
||||
| T-16.2-20 | Elevation of Privilege | sanitize-then-expand order | high | mitigate | `Journal/PostBody.vue:13`, `CategoryHeader.vue:11` `expandEmbeds(sanitizeJournalHtml(...))`, no other caller; gate `check-phase16.2.sh:123` | closed |
|
||||
| T-16.2-32 | Tampering (policy drift) | htmlGate.ts mirror | high | mitigate | `app/utils/htmlGate.ts:68-71,122-127`, only these rules since `294a8d8`; corpus copies identical (`cmp`) | closed |
|
||||
| T-16.2-21 | Information Disclosure (visitor privacy) | YouTube frame | low | mitigate | `embeds.ts:29,57-58` nocookie host, lazy, strict-origin-when-cross-origin; staging vhost `:93` frame-src (report-only; server install pending, WINDOWS 19) | closed |
|
||||
| T-16.2-22 | Tampering / Repudiation | layer tag and pushes | medium | mitigate | v0.2.0 annotated (`042b65d → 759e684`); `scripts/check-git-install.sh`; 04-SUMMARY records `check-git-install: ok` and pushed heads | closed |
|
||||
| T-16.2-23 | Tampering (false-green release) | release gate | medium | mitigate | 05-SUMMARY `release-gate-ok`, Docker-only suites listed, human reply "release v0.1.18" | closed |
|
||||
| T-16.2-24 | Tampering / Repudiation | annotated tag and pushes | high | mitigate | v0.1.18 annotated (`04dc5bd → f1d8a75`), contains plan 01 head `4adb48a`; binary sha256 matched; heads on origin | closed |
|
||||
| T-16.2-25 | Information Disclosure | credentials | high | mitigate | `sm-grzybyfunkcjonalne-app/DEPLOY.md:74` no `.env` rsync; no env file tracked; `.gitignore:5`; 05-SUMMARY no auth gates | closed |
|
||||
| T-16.2-26 | Tampering | UAT database and Winter site | medium | mitigate | 05-SUMMARY: SELECT-only checks, `.prev` rollback copies kept | closed |
|
||||
| T-16.2-35 | Tampering | UAT strip check | low | mitigate | Strip verified (05-SUMMARY edit-ok); test post `uat-16-2-blog-editor` (id 105) deleted by the user on 2026-10-28 | closed |
|
||||
| T-16.2-27 | Elevation of Privilege | sudo on the server | low | accept | See AR-16.2-02 | closed |
|
||||
| T-16.2-28 | Tampering | test isolation | low | mitigate | `sm-journal-plugin/vite.config.ts:38`; memblob, testcontainers; no ssh, curl or child_process in tests | closed |
|
||||
| T-16.2-29 | Repudiation (false green) | phase gate | medium | mitigate | `summercms.go/scripts/check-phase16.2.sh:143-270` detectors, `:376-450` self-test, `:570-586` NOT RUN and `PHASE162_REQUIRE_POSTGRES` | closed |
|
||||
| T-16.2-30 | Tampering (security regression) | strip, policy, permission tests | medium | mitigate | `check-phase16.2.sh:64-130` named tests, `:479-482` 16.1 policy tests pinned to `c60abc6`, `:502` corpus `cmp` | closed |
|
||||
| T-16.2-36 | Spoofing / DoS | layer purge route | medium | mitigate | `server/api/__journal__/cache/purge.post.ts:25-30`; `app/utils/siteCache.ts:39` 32-char minimum, `:40` proxied → 404, `:43` timingSafeEqual over sha256; staging vhost `:236-239` `limit_except`; 07-SUMMARY purge-ok `200 83 403 401` | closed |
|
||||
| T-16.2-37 | Information Disclosure | purge token | high | mitigate | log-capture tests `5eea57f:classes/site_cache_test.go:158-162`, now `modules/cooler/sitecache_test.go:257`; `DEPLOY.md:86,210-213` urandom/printf, `-H @-`; only `token-match` crossed ssh. See Follow-ups for a later leak path | closed |
|
||||
| T-16.2-38 | Tampering (stale content) | purge ordering | medium | mitigate | lagoon.AfterCommit `5eea57f:classes/site_cache.go:181`, now `cooler/sitecache.go:306`; tests `site_cache_admin_test.go:162,240` | closed |
|
||||
| T-16.2-39 | Denial of Service | admin save path | low | mitigate | 2 s WithTimeout(WithoutCancel) `cooler/sitecache.go:32,159`; tests `site_cache_admin_test.go:319,349` | closed |
|
||||
| T-16.2-40 | Information Disclosure | purge URL misconfiguration | medium | mitigate | `cooler/sitecache.go:82-109` (was `site_cache.go:57-84`): both-or-neither, no userinfo or fragment, http only to loopback, 32-char token | closed |
|
||||
| T-16.2-41 | Tampering (log injection) | layer purge log line | low | mitigate | `siteCache.ts:83` strips control chars, `:14` 200-char slug cap | closed |
|
||||
| T-16.2-42 | Tampering (cache poisoning) | Nitro route cache | medium | mitigate | `nuxt.config.ts:77` `cache: false`; `purge.post.ts:18` no-store; `testing/purge-check.mjs:175-184` | closed |
|
||||
| T-16.2-43 | Denial of Service | full route-cache purge | low | accept | See AR-16.2-03 | closed |
|
||||
| T-16.2-44 | Repudiation (false-green gate) | phase gate | medium | mitigate | `check-phase16.2.sh:72,88,93,557,565`; VALIDATION 07-T3 green with `PHASE162_REQUIRE_POSTGRES=1` | closed |
|
||||
| T-16.2-45 | Tampering / Repudiation | tags and pushes | high | mitigate | v0.1.20 (`ad7981f → aba063f`), layer v0.3.0 (`c09e0d0 → 25e9bfe`) match 07-SUMMARY; heads on origin; sha256 matched; site lockfile `3a920c7` resolves to `25e9bfe` | closed |
|
||||
| T-16.2-46 | Tampering | UAT database and Winter site | medium | mitigate | 07-SUMMARY: read-only snapshots, human-only data changes, deploy-ok `.prev` rollback checks | closed |
|
||||
| T-16.2-SC | Tampering | packages (all seven plans) | high | mitigate | 01, 03, 06: no dependency file changes; 02: exact `@tiptap/*` pins 3.31.4, committed lockfile, `scripts/check-dist.sh` rebuild diff, human "packages approved"; 04, 07: layer version bump and pin only, `node:crypto` only; 05: `build.sh:53` `--frozen-lockfile` | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-16.2-01 | T-16.2-08 | Submitting the served value only skips the write; the skip cannot store anything Decode did not already accept (`field_type.go:539-541`) | plan 16.2-01 threat model; reconfirmed by audit | 2026-10-28 |
|
||||
| AR-16.2-02 | T-16.2-27 | Server sudo is limited to `nginx -t`, nginx reload and supervisorctl (`DEPLOY.md:34`); the release used supervisorctl only | plan 16.2-05 threat model; reconfirmed by audit | 2026-10-28 |
|
||||
| AR-16.2-03 | T-16.2-43 | Only authenticated loopback callers can purge; admin saves are rare; each page re-renders once from the local API | plan 16.2-07 threat model; reconfirmed by audit | 2026-10-28 |
|
||||
|
||||
*Accepted risks do not resurface in future audit runs.*
|
||||
|
||||
---
|
||||
|
||||
## Follow-ups (outside the 16.2 register)
|
||||
|
||||
- **Purge token likely exposed on UAT (later regression, not 16.2 code).** The site app pins vue-journal-layer v0.4.0, which brings `@nuxtjs/seo` / nuxt-site-config; that copies every `NUXT_SITE_*` variable into page payloads, and `sm-grzybyfunkcjonalne-app/DEPLOY.md:86` names the token `NUXT_SITE_CACHE_PURGE_TOKEN`. Fixed in the layer at v0.6.0 (`e0cc871`). Not checked on the live server. Action: bump the pin to ≥ v0.6.0, rename to `NUXT_CACHE_PURGE_TOKEN`, rotate the token.
|
||||
- **Surface added after planning, no threat ID:** Blog Editor preview pane (empty-sandbox `srcdoc` iframe with CSP meta, `sm-journal-plugin/assets/src/blogeditor/preview.ts:6-14,190`, accepted in UAT test 5); admin "View site" link (`admin/src/components/shell/AppShell.vue:80-81`, `noopener noreferrer`); visitor X-Forwarded-For forwarded to Go on cached renders (`vue-journal-layer/server/plugins/journal-client-address.ts`, commit `03a90e9`).
|
||||
- **Housekeeping:** WINDOWS entry 19 still needs the staging vhost install (frame-src); the test-post part is done. 16.2-VALIDATION rows 07-T4..T6 still read pending although 07-SUMMARY records them as passed.
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-10-28 | 47 | 47 | 0 | msd-security-auditor (retroactive, State B); T-16.2-35 closed after the user deleted UAT post 105 |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
|
||||
**Approval:** verified 2026-10-28
|
||||
@@ -98,7 +98,7 @@ Post-plan attack surface from the quick tasks, mapped to existing entries: `pact
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-18.1-01 | T-18.1-04 | Reorder POST runs under the controller's protect; taglist adds no route and rides the existing saves | plan 18.1-01 (verified by audit) | 2026-10-16 |
|
||||
| AR-18.1-02 | T-18.1-40 | product_id and plan_code are Stripe ids and a plan code, not PII; TestJobArgsMinimal pins the key list and refuses PII | plan 18.1-07 (verified by audit) | 2026-10-16 |
|
||||
| AR-18.1-03 | T-18.1-22 | Toolbar admin actions (sync_all_to_stripe) are not audit-logged with the admin id on success; bulk actions are. The action needs manage_plans and pgsub logs each synced plan. Follow-up todo: admin action audit log (plugin or cabana extension) | user | 2026-10-16 |
|
||||
| AR-18.1-03 | T-18.1-22 | Toolbar admin actions (sync_all_to_stripe) are not audit-logged with the admin id on success; bulk actions are. The action needs manage_plans and pgsub logs each synced plan. Follow-up todo: admin action audit log (plugin or cabana extension) Resolved 2026-10-28 by quick 261028-rqf (61d1043): toolbar and field action runs are logged with admin_id on success. | user | 2026-10-16 |
|
||||
| AR-18.1-04 | T-18.1-43 | A Checkout Session already paid but whose webhook is not yet processed is complete, not open, so it is not expired; a second checkout in that window can bill twice. Detected by warnDuplicateOpen (Error log). Replaces the old 10-minute idempotency key, which covered only identical parameters | user (UAT row 5, quick 261016-myi) | 2026-10-16 |
|
||||
| AR-18.1-05 | T-18.1-39 | Session advisory locks hold a pooled connection; a capped MaxOpenConns or a re-entrant listener could starve the pool (review IN-02, open) | audit residual | 2026-10-16 |
|
||||
| AR-18.1-06 | T-18.1-24 | The customer API throttle keys on client IP in practice (JWT check runs inside the handler); no 429 test for this bucket | audit residual | 2026-10-16 |
|
||||
|
||||
87
.planning/phases/19-chat-and-chatchannels/19-SECURITY.md
Normal file
87
.planning/phases/19-chat-and-chatchannels/19-SECURITY.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
phase: "19"
|
||||
slug: "chat-and-chatchannels"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-10-28"
|
||||
---
|
||||
|
||||
# Phase 19 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail.
|
||||
|
||||
Implementation lives in the sibling repos `sm-chat-plugin` and `sm-chatchannels-plugin`; the user-namespace authorizer and `user.Deleting` event are in `sm-user-plugin` v0.1.2. Paths below are relative to the meta repo.
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| client → /_chat/api/v1, /_chatchannels/api/v1 | untrusted JSON, ids and multipart files cross jwt.auth | message bodies, attachment bytes, conversation ids |
|
||||
| ChatService write → Postgres | authenticated actor ids become conversation and message rows | user-authored content |
|
||||
| ChatService → lighthouse / Centrifugo | realtime payloads cross to subscribers | event payloads (ids only) |
|
||||
| Authorizer → subscribe | client-chosen channel string trusted only after participant check | channel names |
|
||||
| download handler → blob store | private system_files bytes leave only after a participation check | private attachments |
|
||||
| DM start → other users | unsolicited conversation creation | conversation rows |
|
||||
| ChannelService → resolver | host-installed access policy; default deny-all | context access decisions |
|
||||
| mention body → users.handle | untrusted @tokens become mention rows | user ids |
|
||||
| user delete → chat/channel tables | GDPR cascade must not leave prefs/members or wipe others' rows | personal data |
|
||||
| golden files / check-phase19.sh → CI | recorded PHP payloads and sibling paths become the acceptance oracle | test oracle |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-19-01 | Information disclosure | api/download.go, message GET | high | mitigate | `sm-chat-plugin/api/download.go` collapses missing/unauthorized to `writeNotFound`; `AttachmentForDownload` checks `CanView`; `TestAttachmentDownload` (http_tracer_test.go:340) | closed |
|
||||
| T-19-02 | Elevation of privilege | api/dm.go | medium | mitigate | `chat-dm` bucket Max 10 / minute (routes.go:69); `TestDMThrottle` in PG_CHAT_TESTS | closed |
|
||||
| T-19-03 | Tampering | classes/attachment_policy.go | high | mitigate | `MaxAttachments = 5`, `MaxAttachmentBytes`, `BannedExts` svg/html/xml + banned MIME list; `TestAttachmentPolicy` | closed |
|
||||
| T-19-04 | Information disclosure | lighthouse Bind payload | high | mitigate | ids-only broadcast payload; `TestChatTracer` (tracer_test.go:17) and golden_test.go fail if a publication contains `content` | closed |
|
||||
| T-19-05 | Elevation of privilege | classes/authorizer.go | high | mitigate | parses `chat:conversation:{id}` (one optional presence: prefix), `Denied("not a participant")`, capabilities `["prs"]`, checked per subscribe | closed |
|
||||
| T-19-06 | Elevation of privilege | classes/mention_parser.go | high | mitigate | `ResolveMentionedParticipantIDs` joins `golem15_chat_participants` for the conversation and excludes `senderID` (channel_service.go:1158) | closed |
|
||||
| T-19-07 | Information disclosure | user.Deleting → SeverUserFromContext | high | mitigate | `FireDeletingEvent` fires inside the delete tx (sm-user-plugin controllers/users_admin_controller.go:525); chatchannels `onUserDeleting` → `SeverUserFromContext`; `TestDeletingCascade` | closed |
|
||||
| T-19-08 | Denial of service | classes/search_indexer.go | medium | mitigate | index/deindex errors logged at Warn, never returned (fail-open); `TestSearchIndexer` | closed |
|
||||
| T-19-09 | Elevation of privilege | api/attachments.go pending field | high | mitigate | `PendingField(actorID)` = `chat-pending-{actorID}`; claiming another actor's pending row refused (classes/attachments.go:22) | closed |
|
||||
| T-19-10 | Elevation of privilege | user namespace authorizer | high | mitigate | sm-user-plugin `AuthorizeUser` allows only `user:{id}` for that user, rejects double presence/extra segments; `RegisterUserAuthorizer` skips if registered; `TestUserAuthorizer` in check-phase19.sh | closed |
|
||||
| T-19-11 | Denial of service | mention regex | medium | mitigate | RE2 `@([A-Za-z0-9_.-]{2,255})`, bounded, no nested quantifiers (mention_parser.go:8) | closed |
|
||||
| T-19-12 | Elevation of privilege | DenyAll + Boot Warn | medium | mitigate | `DenyAll` returns false for both methods; boot.go:64 Warns while resolver is deny-all | closed |
|
||||
| T-19-13 | Information disclosure | TestGoldenEvents | high | mitigate | golden_test.go:241 fails when a publication payload contains key `content` | closed |
|
||||
| T-19-14 | Elevation of privilege | mention resolve | high | mitigate | participant-only handle match (same query as T-19-06); `TestHandleMention` (sm-chatchannels-plugin http_tracer_test.go:37) | closed |
|
||||
| T-19-15 | Elevation of privilege | classes/service.go canSend | high | mitigate | `canSend` returns `isParticipant` only (service.go:304); `ErrNotParticipant` mapped to 404 (api/errors.go:57); `TestGapClosureSmoke`, `TestTeammateDMWriteIDOR` | closed |
|
||||
| T-19-16 | Tampering | user.Deleting → created_by CASCADE | high | mitigate | chat `onUserDeleting` → `ReassignCreatedBy` in the Deleting tx (boot.go:187, service.go:115); baseline CASCADE untouched | closed |
|
||||
| T-19-17 | Elevation of privilege | TestTeammateDMWriteIDOR + PG_CHAT_TESTS | high | mitigate | listed in `PG_CHAT_TESTS` and in the self-test required tokens of scripts/check-phase19.sh | closed |
|
||||
| T-19-18 | Tampering | TestDeletingCascade creator path | high | mitigate | test fires Deleting then `Unscoped` deletes Alice (http_tracer_test.go:301); `TestDeletingCascade` in `PG_CHATCHANNELS_TESTS` | closed |
|
||||
| T-19-SC | Tampering | go.mod requires, scripts/check-phase19.sh | high | mitigate | plugin direct requires (gormigrate, pgx, testcontainers, gocloud.dev, gorm) are the framework's pinned versions plus Golem15 modules; gate installs no packages and `--self-test` plants failures | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
No accepted risks.
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-10-28 | 19 | 19 | 0 | /msd-secure-phase (orchestrator, ASVS L1 grep verification) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
|
||||
**Approval:** verified 2026-10-28
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
phase: "19.3"
|
||||
slug: "framework-transport-and-infrastructure-for-wavepath"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-11-05"
|
||||
---
|
||||
|
||||
# Phase 19.3 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail. Framework paths are relative to the repo root (HEAD `7b8d205`); `seo/` = `../vue-seo-layer`. The shared Nuxt purge route moved after the phase from the faq, menu and journal layers into vue-seo-layer, which all three now extend; T-23, T-29, T-37 and T-43 were verified there. T-19.3-SC is declared once per plan (6 rows, one ID).
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| application to Redis | network hop carrying credentials in `redis.url` and shared counters other instances trust | Redis URL, cache entries, rate-limit counters (high) |
|
||||
| request data to cache and limiter keys | keys can derive from client IPs, user ids or request values | key material (medium) |
|
||||
| config and environment to boot | CORS, cookie, Turnstile, api-docs, `redis.url`, driver keys, `public_url` validated or reported before serving | config values, secrets (high) |
|
||||
| browser on a sibling subdomain / SPA origin to the API | credentialed cross-origin requests and the token cookie | session cookie, API answers (high) |
|
||||
| request to Turnstile middleware | untrusted token and body; siteverify crosses to Cloudflare | Turnstile token, secret (high) |
|
||||
| jsDelivr CDN to the api-docs page | third-party scripts executed in the app's origin | JS (medium) |
|
||||
| client upload to attach.Store | untrusted bytes and file name | file content, name (high) |
|
||||
| bucket or CDN to the browser | stored files served from the app's or a CDN's origin | files (medium) |
|
||||
| AWS environment to s3blob | credentials outside summer config | AWS credentials (medium) |
|
||||
| summer.yaml to go build | manifest values become command arguments | build tags (medium) |
|
||||
| Go app to the site's Nitro purge route | bearer-token POST over loopback or https after admin saves | purge token (high) |
|
||||
| network to the Nitro purge route | anyone who can reach the site can call the route | purge requests (medium) |
|
||||
| plugin hooks to the save transaction | hook errors roll back admin writes | hook results (low) |
|
||||
| Go module proxy to the build | a new test-only module enters go.sum | modules (medium) |
|
||||
| test harnesses to the network | httptest, miniredis and testcontainers only | test traffic (low) |
|
||||
| local checkouts to origin | tags and pushes every consumer reads | tags (medium) |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-19.3-01 | Information disclosure | cooler.OpenRedis, Install errors/logs | high | mitigate | cooler/redis.go:15,30-46 fixed error naming `redis.url`, parse error dropped, Addr-only endpoint log; TestOpenRedisRedactsSmoke | closed |
|
||||
| T-19.3-02 | Denial of service | RateLimitStore during outage | medium | mitigate | ratelimit.go:63-73 attempt timeout + fallback; 500 ms (cooler.go:56); once/min warner (:410-446); memory fallback (surf/serve.go:237) | closed |
|
||||
| T-19.3-03 | Tampering | Redis key space | medium | mitigate | `<prefix>cache:` / `<prefix>rl:` namespaces; SCAN with escaped glob + UNLINK, no FLUSHDB (rediscache.go:121-146). Residual IN-01 | closed |
|
||||
| T-19.3-04 | Denial of service | memory cache growth | medium | mitigate | memory.go:40-45 `MaximumSize`, <1 refused; cooler.go:51,304-312 | closed |
|
||||
| T-19.3-05 | Information disclosure | route:list/tests dialing Redis | low | mitigate | serve.go:83 only `installCooler` caller; router.go:556-566 lookup only; store_lookup_test.go:60 | closed |
|
||||
| T-19.3-06 | Information disclosure | CORS credentials + `*` | high | mitigate | surf/cors.go:50-51 enforced via LoadCORSConfig and LoadCORSProfiles; TestCORSCredentialsWildcardRefusedSmoke | closed |
|
||||
| T-19.3-07 | Tampering | shared-cache CORS answers | medium | mitigate | cors.go:240-281 Vary added before the allow check, preflight; :488-503 exact-origin echo | closed |
|
||||
| T-19.3-08 | Spoofing | token cookie attributes | high | mitigate | bouncer/cookie.go:85-116 Domain validity, production Secure, None requires Secure; HttpOnly hard-coded (:154,:172) | closed |
|
||||
| T-19.3-09 | Information disclosure | cookie Domain scope | medium | mitigate | cookie.go:82-90 host-only default, Domain opt-in; docs/services/authentication.md:95 | closed |
|
||||
| T-19.3-10 | Tampering | CSRF on refresh/logout | low | accept | AR-19.3-01. Residual IN-08 | closed |
|
||||
| T-19.3-11 | Spoofing | Turnstile with no secret | high | mitigate | bouncer/turnstile.go:111-119 production + no secret → 503, success required; production flag from config (router.go:732-733). Residual IN-11 | closed |
|
||||
| T-19.3-12 | Denial of service | slow siteverify | medium | mitigate | turnstile.go 5 s client + ctx, 4 KiB LimitReader | closed |
|
||||
| T-19.3-13 | Tampering | body consumed by Turnstile | medium | mitigate | turnstile.go:264-266 read once, restored; body limit wraps route middleware (router.go:513-515); TestTurnstileMiddlewareSmoke. Residual IN-05 | closed |
|
||||
| T-19.3-14 | Information disclosure | Turnstile secret/token in logs | high | mitigate | secret only in form body; url.Error unwrapped; log carries error text only (turnstile.go:120-241); TestTurnstileNeverLogsSecret | closed |
|
||||
| T-19.3-15 | Tampering | swagger-ui on jsDelivr | medium | mitigate | surf/apidocs.go:32-66 pinned 5.33.1 with sha384 SRI + crossorigin; nonce-only CSP (:208) | closed |
|
||||
| T-19.3-16 | Information disclosure | /api-docs surface | low | accept | AR-19.3-02 | closed |
|
||||
| T-19.3-17 | Tampering (XSS) | api_docs title/spec URL | medium | mitigate | apidocs.go `html/template` contextual escaping (:10,:55-81) | closed |
|
||||
| T-19.3-18 | Tampering / EoP | stored XSS via disk name | high | mitigate | lagoon/attach/diskext.go:39-77, store.go:170 `DiskExtension(sniffed, ext)`; inline.go:38-44 attachment disposition; storage.md:110-135; TestDiskExtensionTable. Residual IN-07 | closed |
|
||||
| T-19.3-19 | Information disclosure | public_url exposing files | medium | mitigate | 22-hex random names (store.go:294-300); boot Warn (bucket.go:157-161); storage.md:94 | closed |
|
||||
| T-19.3-20 | Tampering | build.tags reaching go build | medium | mitigate | internal/build/manifest.go:121-172 validation; build.go:58-78 `exec.CommandContext`, single `-tags=` arg, no shell | closed |
|
||||
| T-19.3-21 | Repudiation / misconfig | s3:// in an untagged binary | medium | mitigate | attach/bucket.go:106-137 refusal; s3_on.go/s3_off.go; build prints `build tags:` | closed |
|
||||
| T-19.3-22 | Information disclosure | AWS credentials | medium | mitigate | storage.md:78 no keys in bucket_url/config; no credential keys in attach | closed |
|
||||
| T-19.3-23 | DoS / Spoofing | shared Nitro purge route | medium | mitigate | seo/server/lib/siteCachePurge.ts:13,54-60 ≥32-char token else 404, proxied → 404, sha256 + timingSafeEqual; purge.post.ts:32-48; route `cache: false` | closed |
|
||||
| T-19.3-24 | Information disclosure | purge token in Go logs/errors | high | mitigate | cooler/sitecache.go errors/logs name keys, kind, slug, status, host+path only; assertNoToken in sitecache_test.go | closed |
|
||||
| T-19.3-25 | Information disclosure | token in clear on the network | high | mitigate | sitecache.go:97-132 user info refused, http only to loopback | closed |
|
||||
| T-19.3-26 | Denial of service | purge breaking saves | medium | mitigate | `WithoutCancel` + 2 s, `lagoon.AfterCommit`, errors logged only (sitecache.go:159,302-309); faq/menu 500-receiver tests | closed |
|
||||
| T-19.3-27 | Tampering | purge before commit | low | mitigate | AfterCommit (sitecache.go:302-309); `cabana.TxFromContext` in faq, menu, journal site_cache.go | closed |
|
||||
| T-19.3-28 | Tampering | ReorderAfterSave failing | low | accept | AR-19.3-03 | closed |
|
||||
| T-19.3-29 | Tampering | three route copies drifting | low | mitigate | superseded: single copy in vue-seo-layer, none left in faq/menu/journal; sha256 pins seo/tests/sitePurge.test.ts:26-39 | closed |
|
||||
| T-19.3-30 | Repudiation | gate passing on skipped tests | medium | mitigate | scripts/check-phase19.3.sh:195-285 fails on skip/zero/missing; self-test (:357+). See "Gate out of date" | closed |
|
||||
| T-19.3-31 | Tampering | unverified release | medium | mitigate | 19.3-05 checkpoint; v0.1.27 unmoved on origin, ancestor of v0.2.0 and origin/master | closed |
|
||||
| T-19.3-32 | Information disclosure | secret-in-logs tests | low | mitigate | TestTurnstileNeverLogsSecret, TestOpenRedisRedactsSmoke, assertNoToken | closed |
|
||||
| T-19.3-33 | Tampering | profiled-route refusals missing CORS/Vary | medium | mitigate | surf/router.go:462-530 profile wraps recovery/body limit/locale, :905-918 Vary merge; TestCORSProfileHeadersOnRefusals, TestCORSProfileVaryKeptWithHandlerVary | closed |
|
||||
| T-19.3-34 | Information disclosure | credentialed wildcard/unanchored origins | high | mitigate | cors.go:61-160 anchoring and wildcard host-label rules with probes, per profile; TestCORSCredentialedOriginRules, TestCORSAnchoredPatternNoSuffixMatch. Residual: multi-label public suffix (below) | closed |
|
||||
| T-19.3-35 | Information disclosure | token forwarded on redirect | high | mitigate | sitecache.go:109-115 `CheckRedirect` → `ErrUseLastResponse`; TestSiteCachePurgeNoRedirect | closed |
|
||||
| T-19.3-36 | Denial of service | synchronous per-row purges | medium | mitigate | single coalescing worker, Wait, Close drains (sitecache.go:212-277; cooler.go:123-131); async tests | closed |
|
||||
| T-19.3-37 | Spoofing | allowProxied reachable from the network | medium | mitigate | siteCachePurge.ts:55-59 token check first, `allowProxied !== true` → 404; default false (seo/nuxt.config.ts:58-71); docs/services/caching.md:215 | closed |
|
||||
| T-19.3-38 | Information disclosure | inferred insecure cookie in production | high | mitigate | cookie.go:107-112 error names `auth.cookie.secure` and `app.url`; TestLoadCookieConfigProductionInferredSecure | closed |
|
||||
| T-19.3-39 | Information disclosure | zero CookieConfig | medium | mitigate | cookie.go:273-287 zero → Secure, SameSite Lax, used by both handlers; TestZeroCookieConfigDefaults | closed |
|
||||
| T-19.3-40 | Elevation of privilege | api-docs CSP with host source | medium | mitigate | apidocs.go:65-67,208 nonce-only `script-src`; TestAPIDocsCSPNoHostSource | closed |
|
||||
| T-19.3-41 | Information disclosure | protected files in a public_url bucket | high | mitigate | attach/store.go:38-42,139-140 refused before body read; boot warning; every bucket via attach.OpenBucket; TestStoreProtectedNeedsPrivateBucket | closed |
|
||||
| T-19.3-42 | Spoofing | turnstile routes without a secret, unnoticed | medium | mitigate | router.go:710,739-758 one Warn with route count and production flag, never the secret; TestTurnstileEmptySecretWarnsAtBoot. Residual IN-11 | closed |
|
||||
| T-19.3-43 | Tampering | layer copies drifting | low | mitigate | superseded, as T-19.3-29 | closed |
|
||||
| T-19.3-44 | Tampering | unverified release / moved tag | medium | mitigate | 19.3-06 checkpoint; v0.2.0 contains 0c8109c and v0.1.27, on origin/master; v0.1.27 unmoved | closed |
|
||||
| T-19.3-SC (01) | Tampering | go-redis, otter installs | high | mitigate | decision note 2026-10-15-cooler-go-redis-otter.md precedes the go.mod commit; pinned v9.23.0 / v2.3.0 | closed |
|
||||
| T-19.3-SC (02) | Tampering | installs | high | mitigate | go.mod/go.sum unchanged across the plan; swagger-ui via SRI-pinned CDN | closed |
|
||||
| T-19.3-SC (03) | Tampering | s3blob / AWS SDK | high | mitigate | gocloud.dev v0.46.0; s3blob only behind `//go:build summercms_s3`; note precedes the go.mod commit | closed |
|
||||
| T-19.3-SC (04) | Tampering | installs | high | mitigate | framework go.mod unchanged; layer package.json version bumps only; plugin go.mod bumps add only modules the framework already pins | closed |
|
||||
| T-19.3-SC (05) | Tampering | miniredis install | high | mitigate | human approval recorded (19.3-05-SUMMARY:121-129); pinned v2.40.0; test-only imports | closed |
|
||||
| T-19.3-SC (06) | Tampering | installs | high | mitigate | go.mod/go.sum unchanged across the plan; layer commits bump versions only | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-19.3-01 | T-19.3-10 | Refresh only rotates a cookie (the answer is unreadable cross-origin unless CORS allows that origin); logout CSRF is a forced logout; routes are POST-only and the docs advise JSON or a custom header (authentication.md:97). | 19.3-02 PLAN | 2026-11-05 |
|
||||
| AR-19.3-02 | T-19.3-16 | /api-docs is off by default; the spec is the app's hand-written public surface (D-16); both routes are public by design (D-17). | 19.3-02 PLAN | 2026-11-05 |
|
||||
| AR-19.3-03 | T-19.3-28 | The hook runs inside the reorder transaction by design so its failure rolls the reorder back, as FormAfter hooks do; purge hooks never return errors. | 19.3-04 PLAN | 2026-11-05 |
|
||||
|
||||
*Accepted risks do not resurface in future audit runs.*
|
||||
|
||||
---
|
||||
|
||||
## Unregistered Flags and Residual Risk (non-blocking)
|
||||
|
||||
1. **Purge token was published in page payloads (fixed after the phase).** The phase's layer versions read the token from `NUXT_SITE_CACHE_PURGE_TOKEN`; nuxt-site-config copies every `NUXT_SITE_*` variable into the public site config. Fixed: the token is now `cachePurge.token` / `NUXT_CACHE_PURGE_TOKEN`, seo/server/plugins/site-cache-purge.ts strips the old keys, and docs/services/caching.md:207 says to rotate. **Action:** confirm every deployment that set the old variable has rotated its token.
|
||||
2. **Credentialed wildcard on a multi-label public suffix passes boot** (VERIFICATION advisory 1, next to T-19.3-34). `https://*.co.uk` is accepted: `wildcardHostLabel` accepts any non-empty remainder and the probes only cover `.invalid` and `.com`.
|
||||
3. **Second purge route.** The deprecated `vue-journal-layer/server/api/__journal__/cache/purge.post.ts` predates this phase, still ships, and is not covered by this register.
|
||||
4. Open review info items from 19.3-REVIEW-DISPOSITION: IN-01 (T-03), IN-05 (T-13), IN-07 (T-18), IN-08 (T-10), IN-11 (T-11/T-42: no log when a published verifier replaces a configured secret).
|
||||
|
||||
### Gate out of date
|
||||
|
||||
The layers stage of `scripts/check-phase19.3.sh` (lines 175-177, 524) still `cmp`s the purge files inside the faq, menu and journal layers, which moved to vue-seo-layer; that stage would now fail. No threat reopens; T-29/T-43 evidence now comes from vue-seo-layer.
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-11-05 | 50 rows (45 IDs) | 50 | 0 | msd-security-auditor (ASVS L1, block_on high; `go test -short` on cooler, bouncer, surf, lagoon/attach, internal/build: 28 named tests pass, 4 Docker-backed tests not run) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
- [ ] Old `NUXT_SITE_CACHE_PURGE_TOKEN` values rotated on every deployment that set them
|
||||
|
||||
**Approval:** verified 2026-11-05 (ASVS L1)
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
phase: "19.4.1"
|
||||
slug: "early-public-demo-on-demo-summercms-io"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-11-05"
|
||||
---
|
||||
|
||||
# Phase 19.4.1 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail. Static audit of repository contents (no SSH, no production requests, tests not re-run; test results from the phase gate log and VERIFICATION). Audited: sm-demo-app da03c06 (after Phases 20 and 33), vue-demo-app fe5d38d (the submodule; the sibling `../vue-demo-app` checkout is stale), framework v0.6.1 and the plugin tags go.mod requires. Roots: DEMO = `../sm-demo-app`, VUE = `DEMO/vue-demo-app`, PLG = `DEMO/plugins/golem15`, FW = `summercms.go`.
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| ROADMAP.md → client-facing deck | internal phase names include client applications | phase titles and summaries (high) |
|
||||
| local .env → demo:seed | visitor credentials enter the database | visitor email and password (high) |
|
||||
| local demo pages → committed screenshots | captures could show secrets or personal data | OIDC and admin PNGs (medium) |
|
||||
| seeded deck HTML → public deck API | rendered on a public origin | slide HTML (low) |
|
||||
| internet → nginx (demo.summercms.io) | only allow-listed prefixes reach Go; includes the public login-required `/smbackend` admin (user decision 2026-10-20) | all HTTP traffic, admin login (high) |
|
||||
| nginx → Go and Nuxt on loopback | trusted proxy 127.0.0.1/32 sets client IP headers | X-Forwarded-For, X-Real-IP (medium) |
|
||||
| build machine → module proxies and git.golem15.com | tags become immutable inputs for every consumer | plugin tags, go.sum (medium) |
|
||||
| build machine → rome over SSH | secrets generated on rome or piped, never logged | env values, binaries (high) |
|
||||
| Stripe → webhook | signed callbacks from the internet | events, Stripe-Signature (high) |
|
||||
| browser → `/_user/api/v1/register` and `/login` | anonymous, automatable sign-ups and credential attempts | credentials, Turnstile token (high) |
|
||||
| browser → `/_feedback/api/v1/{key}/submit` | anonymous free text with a public key | name, email, message (medium) |
|
||||
| Go → Cloudflare siteverify and G15Office | outbound calls carrying secrets | Turnstile secret, G15Office token (high) |
|
||||
| operator → demo:reset | destructive command on production data | `--force` (high) |
|
||||
| browser locale cookie → SSR | user-controlled input selecting content | locale value (low) |
|
||||
| registered user → `/_demo/api/v1/presentations` | untrusted HTML, markdown and settings stored | deck JSON (high) |
|
||||
| browser → `/api/realtime/token` and `/ws` | authenticated users obtain realtime credentials | JWT, Centrifugo token (high) |
|
||||
| Centrifugo → `/api/realtime/subscribe` | server-to-server over loopback | X-Centrifugo-Secret, user, channel (high) |
|
||||
| Go → Centrifugo HTTP API | publishes slide positions | API key, positions (medium) |
|
||||
| anonymous visitor → `/_demo/api/v1/quizzes` | public read of quiz metadata | slug, title, description, count (medium) |
|
||||
| test harness → Docker / test fixtures → repositories | throwaway database, test-only secrets | test data (low) |
|
||||
| check-live.sh → production origin | read-only probes | GETs plus one refused POST (low) |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-19.4.1-01 | Information disclosure | roadmap deck builder | high | mitigate | denylist + case-insensitive `leaks` (DEMO/plugins/demo/roadmap/names.go:8-26); leak check after curated overrides, leaking phases left out, final per-slide guard (deck.go:56-60,143-146); `TestRoadmapNoClientNames` | closed |
|
||||
| T-19.4.1-02 | Information disclosure | visitor credentials | high | mitigate | `golem15.demo.visitor.*` only, ≥8 chars, never printed (console/seed.go:101-141); empty defaults; dev.sh umask 077, prints key name only; `TestSeedVisitorFromConfig` | closed |
|
||||
| T-19.4.1-03 | Information disclosure | OIDC screenshots | medium | mitigate | capture-oidc.cjs uses the example client only, never opens the one-time secret screen; user reviewed the images (01 Task 4) | closed |
|
||||
| T-19.4.1-04 | Tampering | deck HTML | low | accept | AR-19.4.1-01 | closed |
|
||||
| T-19.4.1-05 | Denial of service | repeated seeding | low | mitigate | old image rows deleted in-tx after import, blobs after commit (console/roadmap_deck.go:109,136-155); `TestSeedRoadmapUpsert` | closed |
|
||||
| T-19.4.1-06 | Elevation of privilege | admin exposure | high | mitigate | **Re-scoped by the user's decision of 2026-10-20** (the plan's "SSH tunnel only" is superseded): `/backend` → 404 (nginx:78-80), `/smbackend` login-required; `login.max_attempts: 5 / 1 min`; ClientIP takes the rightmost untrusted XFF hop with the Cloudflare real-IP snippet; `X-Robots-Tag noindex`; `TestAdminLoginThrottle`; check-deploy.sh:245-259, check-live.sh:140-150 | closed |
|
||||
| T-19.4.1-07 | Information disclosure | secrets in repositories | high | mitigate | env examples empty; secret-pattern scan clean in both repos; values generated on rome, 0640 root:summercms-demo, admin password root 0600 (DEPLOY.md). Repo privacy is host-only | closed |
|
||||
| T-19.4.1-08 | Tampering | one-way plugin tags | medium | mitigate | all 11 phase tags resolve to the commits recorded in the SUMMARYs; scripts/check-pins.sh; `TestGoModRequiresTags` | closed |
|
||||
| T-19.4.1-09 | Spoofing | Stripe webhook | high | mitigate | signing secret required, `pgstripe.VerifySignature` on raw body (PLG/pgstripe/subscriptions/webhook.go:72-78); empty example. Value on rome is host-only | closed |
|
||||
| T-19.4.1-10 | Information disclosure | debug pages and permissive CORS | medium | mitigate | production `debug: false`; CORS only `https://demo.summercms.io`; supervisor `SUMMER_ENV="production"`; check-deploy.sh:183 | closed |
|
||||
| T-19.4.1-11 | Elevation of privilege | unintended Go routes | medium | mitigate | nginx allow-list, `/` GET/HEAD only; check-deploy.sh:268-279 refuses extra `/oauth`, `/.well-known`, `/api` and subscribe locations; PAT APIs `/api/v1/*` unrouted. Narrowed by Phase 19.7 (MCP paths) | closed |
|
||||
| T-19.4.1-12 | Denial of service | Nuxt site-cache purge | medium | mitigate | purge on 127.0.0.1:3098, no POST reaches Nuxt, route 404s proxied/401s bad token; payload token leak fixed in DEMO 866e58c (`NUXT_CACHE_PURGE_TOKEN`, check-deploy.sh:300-318, smoke checks) | closed |
|
||||
| T-19.4.1-13 | Information disclosure | credentials on public pages | high | mitigate | empty login fields cleared after submit; FAQ answer "credentials on request"; smoke.sh:256-268 fails on admin links or visitor credentials on 12 SSR pages; check-live `no_admin_link` | closed |
|
||||
| T-19.4.1-14 | Spoofing | TLS | medium | mitigate | 301 to HTTPS, certbot lineage, HSTS (nginx:50-67); check-live HSTS check. Certificate is host-only | closed |
|
||||
| T-19.4.1-15 | Denial of service | port collisions | low | mitigate | check-deploy.sh:179-243,364-371 port consistency; port probe on rome is host-only | closed |
|
||||
| T-19.4.1-16 | Spoofing | bot sign-ups and credential stuffing | high | mitigate | `turnstile: closed`; guard on `/login`, `/register` inside `throttle:user-api`; attempt_limit 5; production without secret → 503 (FW v0.6.1); check-live token-less register → 422; `TestDemoTurnstile` | closed |
|
||||
| T-19.4.1-17 | Tampering | shared sm-user-plugin behaviour | high | mitigate | default `turnstile: ""` adds nothing, invalid values fail boot (PLG/user/routes.go:63-79); `TestTurnstileRoutes`; no other app sets the key | closed |
|
||||
| T-19.4.1-18 | Denial of service | contact form spam | medium | mitigate | 10/min per client IP; field limits (message ≤5000); Origin allow-list; no mailer in feedback/demo code | closed |
|
||||
| T-19.4.1-19 | Information disclosure | Turnstile secret, G15Office token | high | mitigate | empty examples; build-machine secrets file mode 600; values piped over SSH stdin and checked by count only (DEPLOY.md:114-238). File modes host-only | closed |
|
||||
| T-19.4.1-20 | Tampering | demo:reset deleting kept data | high | mitigate | no-op without `--force`; explicit table list keeps admins, plans, settings, locales, sitemap, OAuth clients; one transaction, blobs after commit; schedule off by default; `TestResetKeepsPlans`; check-local.sh:262-281 | closed |
|
||||
| T-19.4.1-21 | Tampering | stored XSS via seed or author description | low | mitigate | AuthorCard text interpolation; PostBody `sanitizeJournalHtml` before v-html; curated seed | closed |
|
||||
| T-19.4.1-22 | Information disclosure | author payload | low | accept | AR-19.4.1-02 (rationale corrected) | closed |
|
||||
| T-19.4.1-23 | Tampering | locale cookie | low | accept | AR-19.4.1-03 | closed |
|
||||
| T-19.4.1-24 | Information disclosure | feedback widget key in the page | low | accept | AR-19.4.1-04 | closed |
|
||||
| T-19.4.1-25 | Tampering | stored XSS and phishing through user decks | high | mitigate | wrapper restricts themes, clears CSS/context, forces unpublished, resets id/hash, 403 on published decks (DEMO/plugins/demo/decks_api.go:38-120); bluemonday sanitize without `<a>` (PLG/presentations/classes/sanitize.go:21-51); reset wipes user decks; `TestDemoDeckWrites`. See residual 3 | closed |
|
||||
| T-19.4.1-26 | Elevation of privilege | cross-app realtime token reuse | high | mitigate | own Centrifugo with own HMAC secret; HMAC-tagged channels with per-subscribe DB ownership check (PLG/presentations/realtime.go:74-90); guarded token route. Owner-only access clause superseded by Phase 20 (chat community members) | closed |
|
||||
| T-19.4.1-27 | Spoofing | subscribe proxy | high | mitigate | no nginx location (enforced by check-deploy.sh:273-276, check-live); constant-time `X-Centrifugo-Secret` compare, empty refused (FW lighthouse/centrifugo/handlers.go:112-113); `TestRealtimeRoutes` | closed |
|
||||
| T-19.4.1-28 | Information disclosure | Centrifugo keys and remote key | high | mitigate | `CHANGE_ME_*` placeholders enforced by check-deploy.sh:213-219; empty env examples; generated on rome 0640; health prints only `api_key_set` | closed |
|
||||
| T-19.4.1-29 | Spoofing | WebSocket from other sites | medium | mitigate | `allowed_origins: ["https://demo.summercms.io"]`, no insecure/anonymous flags; check-live refuses a foreign Origin | closed |
|
||||
| T-19.4.1-30 | Denial of service | deck writes and token route | medium | mitigate | 256 KiB body, ≤60 slides, `throttle:20,1`; realtime bucket 120/min per user | closed |
|
||||
| T-19.4.1-31 | Information disclosure | quiz answers to anonymous visitors | medium | mitigate | public list returns slug, title, description, count only; quiz API behind `jwt.auth`; `TestDemoQuizList` | closed |
|
||||
| T-19.4.1-32 | Elevation of privilege | another user's decks | medium | mitigate | owner from JWT (`mineCaller`); no owner field, `DisallowUnknownFields`; queries scoped by owner_user_id | closed |
|
||||
| T-19.4.1-33 | Information disclosure | test fixtures and logs | medium | mitigate | test-only secrets; fake siteverify; smoke uses random tokens and passwords, never echoed | closed |
|
||||
| T-19.4.1-34 | Tampering | regression of mitigations from plans 01-04 | high | mitigate | pinning test per threat (T-01, 02, 05, 16, 17, 20, 25, 26, 27, 31; smoke/check-live for T-06, T-13); scripts/check-all.sh | closed |
|
||||
| T-19.4.1-35 | Denial of service | check-live against production | low | accept | AR-19.4.1-05 | closed |
|
||||
| T-19.4.1-SC | Tampering | npm/pip/cargo installs (plans 01-05) | high | mitigate | only `centrifuge 5.7.3` and `vitest 3.2.7` added, exact pins; `protobufjs: false`; `--frozen-lockfile`, `GOWORK=off`, `GOPRIVATE`; go.sum committed; no replace (go_mod_test.go:31) | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-19.4.1-01 | T-19.4.1-04 | Seeded content is curated in the repository and every field passes `classes.Clean` at render; text values are HTML-escaped by the builder (`para()` uses `esc()`). | 19.4.1-01 PLAN | 2026-11-05 |
|
||||
| AR-19.4.1-02 | T-19.4.1-22 | Plan rationale: "only subtitle, description and avatar are added; email and login data stay out of authorColumns." **Corrected:** `login` is selected (PLG/journal/controllers/api/authors.go:27-28) and published as `slug` when the author slug is empty. Holds in practice: the demo's only author is `summercms-team` (no superuser, no role, unusable password). A post by a real admin without an author slug would publish that admin's login name while `/smbackend` is public. | 19.4.1-03 PLAN (corrected by audit) | 2026-11-05 |
|
||||
| AR-19.4.1-03 | T-19.4.1-23 | Only en and pl are accepted by the i18n module; any other value falls back to the default. | 19.4.1-03 PLAN | 2026-11-05 |
|
||||
| AR-19.4.1-04 | T-19.4.1-24 | Public by design; the Origin allow-list and throttles gate it. | 19.4.1-03 PLAN | 2026-11-05 |
|
||||
| AR-19.4.1-05 | T-19.4.1-35 | A handful of GET requests and one refused POST per run, inside the existing throttles. | 19.4.1-05 PLAN | 2026-11-05 |
|
||||
|
||||
*Accepted risks do not resurface in future audit runs.*
|
||||
|
||||
---
|
||||
|
||||
## Residual Risk and Notes (non-blocking)
|
||||
|
||||
1. **T-06 register row is stale in 19.4.1-02-PLAN.md** ("admin only through an SSH tunnel"). The verified mitigation is the login-required public `/smbackend` described above (user decision 2026-10-20; 02-SUMMARY flag `auth-surface`, 03-SUMMARY "Threat model update").
|
||||
2. **Later phases changed mitigations:** T-11 (Phase 19.7 routes MCP and OAuth metadata paths; check-deploy enforces the narrower list) and T-26 (Phase 20 gives realtime tokens to chat community members; presentations channels still HMAC-tagged and ownership-checked). Belongs in those phases' audits.
|
||||
3. **The deck wrapper (T-25) is the only public deck write path while** nginx does not route `/api/v1/presentations` **and** demo users lack `golem15.presentations.access_presentations` (needed by the Phase 19.7 presentations MCP tools, incl. `presentations_publish` and deck CSS; no demo group grants it today). If either changes, users get a write path that skips the wrapper's CSS, publish and theme rules.
|
||||
4. **AR-19.4.1-02 wording** corrected above (author `login` published as slug).
|
||||
5. **Local-only admin password literal:** DEMO/scripts/dev.sh:48 `ADMIN_PASSWORD=AdminDemo123!` for the local dev admin, reused as a fallback in smoke-seo.sh:74. Not a production credential, but a committed literal in a private repo.
|
||||
6. **UAT:** 19.4.1-UAT.md is `testing` with 3 pending items. Item 1 (purge token in the payload) is fixed in 866e58c; DEPLOY.md:1046-1055 records the rotation on rome on 2026-10-20 (host-only). Items 2-3 are UAT, not threats.
|
||||
|
||||
### Host-only checks (not verifiable from the repos)
|
||||
|
||||
Repository privacy on git.golem15.com; rome file modes (`.env`, `site.env` 0640 root:summercms-demo, admin file 0600, centrifugo.json 0640); Stripe and Turnstile secrets present on rome; reset schedule off on rome; certbot certificate and Cloudflare real-IP snippet; port probe; purge-token rotation; build machine's 0600 secrets file.
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-11-05 | 36 | 36 | 0 | msd-security-auditor (ASVS L1, block_on high; static, repo contents only) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
- [ ] Host-only checks confirmed on rome / git.golem15.com
|
||||
|
||||
**Approval:** verified 2026-11-05 (ASVS L1, repository evidence)
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
phase: "19.6"
|
||||
slug: "two-factor-auth-and-device-flow-in-sm-user-plugin"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-10-28"
|
||||
---
|
||||
|
||||
# Phase 19.6 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail.
|
||||
|
||||
Implementation lives in sibling repos: **U** = sm-user-plugin (`fonoteka.go/plugins/golem15/user`), **M** = `sm-mfa-plugin`, **S** = `sm-sociallogin-plugin`, **D** = `sm-demo-app/vue-demo-app`; **F** = this repo. The detailed per-threat evidence (mutation checks, log-call sweep, D-14 passkey rules, D-18 hardening) is in `19.6-SECURITY-REVIEW.md`; this file is the register and sign-off.
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| first-factor login → token mint | a correct password must not yield a token while a second factor is pending | credentials, JWT |
|
||||
| sm-user-plugin → other plugins | gates, admin reset service and listeners run M's code inside U's requests and transactions | user ids, transaction handle |
|
||||
| unauthenticated device → devices/initiate, devices/status | anyone can create sessions and poll with a token | device token, short code, device name |
|
||||
| signed-in user → devices/authorize, list, revoke | a bearer JWT binds or ends device sessions | device session ids, jti |
|
||||
| JWT refresh → device revocation | a refreshed device token must stay revocable | jti lineage |
|
||||
| holder of a password → challenge routes | unauthenticated clients present challenge tokens and guessed codes | challenge token, TOTP/email/recovery codes |
|
||||
| signed-in user → management routes | a JWT changes the user's own factors | TOTP secrets, recovery codes, credentials |
|
||||
| plugin → database / mailer | secrets at rest; one-time codes leave by email | hashed tokens, encrypted secret, bcrypt codes |
|
||||
| browser authenticator / frontend origin → WebAuthn routes | attestations and assertions bound to server-side ceremony state, RP ID and origins | WebAuthn ceremony data |
|
||||
| anonymous client → passwordless routes | a passkey alone yields a token | assertion, JWT |
|
||||
| social provider callback → signIn | a social identity must not bypass an enabled second factor | provider identity, JWT |
|
||||
| administrator → Users screen, settings | privileged reset of a user's factors; global 2FA policy | settings values |
|
||||
| demo frontend → API | server-generated SVG rendered in the browser | QR SVG |
|
||||
| test results → phase verdict; releases → app pins | a skipped test must not pass; fixes must reach every pin | gate output, git refs |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-19.6-01 | Elevation of privilege | login gate consultation | high | mitigate | U `controllers/login_gates.go` `CheckLoginGates`, called from `Login` before restore/mint; gate error → opaque 500; `TestLoginGates`, `TestLoginGateOrder`, `TestLoginGateSmoke/gate_error` | closed |
|
||||
| T-19.6-02 | Tampering | soft-delete restore before second factor | medium | mitigate | restore after the gates; `TestLoginGateOrder/challenged_soft_deleted_stays_deleted` (U), `TestGate/deactivated_user_is_challenged_and_stays_deactivated` (M) | closed |
|
||||
| T-19.6-03 | Spoofing | trusted devices surviving a password change | medium | mitigate | `AccessRevokedEvent` in the write transaction (U); M `classes/admin.go` `OnAccessRevoked`; `TestPasswordChangedSources`, `TestRevocation` | closed |
|
||||
| T-19.6-04 | Elevation of privilege | Reset 2FA record action | medium | mitigate | U `classes/two_factor_admin.go` `PermissionResetTwoFactor` registered in `admin_permissions.go`, no default role; `TestResetTwoFactorAction`, `TestAdminReset` | closed |
|
||||
| T-19.6-05 | Tampering | short-code guessing | medium | mitigate | U `classes/device_auth.go` `NewDeviceShortCode` (crypto/rand, 31^8); guarded authorize UPDATE; `TestDeviceCodes`, `TestDeviceAuthorize` (mutation-checked) | closed |
|
||||
| T-19.6-06 | Spoofing | device-code phishing | medium | accept | D-12c, see AR-01 | closed |
|
||||
| T-19.6-07 | Elevation of privilege | device hand-over race | high | mitigate | U `controllers/devices.go:282,300` guarded `status = 'confirmed'` UPDATE; `TestDeviceHandOverConcurrent` (mutation-checked) | closed |
|
||||
| T-19.6-08 | Elevation of privilege | revoked device keeps refreshing | high | mitigate | U `classes/device_auth.go` `HandOverDeviceJTI`; revoke blacklists jti; `TestDeviceRevokeAfterRefresh`; `blacklist_grace` fork see AR-02 | closed |
|
||||
| T-19.6-09 | Information disclosure | device tokens at rest and in URLs | medium | mitigate | SHA-256 only; F `modules/surf/accesslog.go` logs no path; `TestDeviceTokensAtRest`; proxy logging see AR-05 | closed |
|
||||
| T-19.6-10 | Denial of service | initiate filling the table | low | mitigate | user-api bucket, bounded cleanup (≤500); `TestDeviceInitiate/cleanup_is_bounded` | closed |
|
||||
| T-19.6-11 | Tampering | attacker-chosen device_name | low | mitigate | ≤255 runes, 422; `TestDeviceInitiate/device_name` | closed |
|
||||
| T-19.6-12 | Tampering | core plugin contract | medium | mitigate | additive only; gate `--userplugin`, `--fonoteka` | closed |
|
||||
| T-19.6-13 | Spoofing | TOTP/email brute force | high | mitigate | M `classes/challenge.go` `FailureCapReached`, 2fa-verify bucket, 5 attempts; `TestFailureCap`, `TestRoutesAndBuckets` | closed |
|
||||
| T-19.6-14 | Tampering | parallel verifies | high | mitigate | M `classes/challenge.go:96,119` `completed_at IS NULL AND attempts < max_attempts`; `TestChallengeLifecycle/one_completion_when_factors_race` (mutation-checked) | closed |
|
||||
| T-19.6-15 | Spoofing | TOTP replay | medium | mitigate | M `classes/methods.go` `AcceptTOTPCounter`; `TestTOTP/replay` | closed |
|
||||
| T-19.6-16 | Spoofing | email downgrade of TOTP-only user | high | mitigate | M `classes/email.go` `SendEmailCode` gated on enabled email method; `TestEmailCode/gating` | closed |
|
||||
| T-19.6-17 | Denial of service | mail bombing | medium | mitigate | M `classes/email.go:83` `email_sends < 3`; `TestEmailCode/sends_replace_and_cap` (mutation-checked) | closed |
|
||||
| T-19.6-18 | Information disclosure | secrets at rest | high | mitigate | SHA-256 tokens, M `models/two_factor_method.go` `Secret lagoon.Encrypted`, bcrypt codes; `TestTokensAtRest` | closed |
|
||||
| T-19.6-19 | Information disclosure | logs and error strings | medium | mitigate | log-call sweep (SECURITY-REVIEW "Log calls"); `TestEmailCode/never_logged` | closed |
|
||||
| T-19.6-20 | Spoofing | stolen trusted-device token | medium | mitigate | M `classes/trusted.go`, `classes/gate.go`; `TestTrustedDevice`, `TestRevocation` | closed |
|
||||
| T-19.6-21 | Elevation of privilege | management routes on other users' rows | high | mitigate | JWT-scoped queries, digit `{id}`; `TestRoutesAndBuckets`, `TestWebAuthn/delete_scoped_to_the_owner` | closed |
|
||||
| T-19.6-22 | Information disclosure | recovery codes after creation | medium | mitigate | shown once, count route needs password; `TestRecovery/first_set_only_when_created`, `count_route` | closed |
|
||||
| T-19.6-23 | Denial of service | bcrypt CPU per wrong code | low | mitigate | M `classes/recovery.go` `NormalizeRecoveryCode` (≤32 chars); `TestRecoveryCodeFormat` | closed |
|
||||
| T-19.6-24 | Tampering | settings values | low | mitigate | M `models/settings.go` `BeforeValidate` allow-lists; defect fixed in M `71d8f27`, released v0.1.1; `TestSettings`, `TestPHPUser005` | closed |
|
||||
| T-19.6-25 | Spoofing | client-chosen TOTP secret at confirm | low | accept | PHP parity, see AR-03 | closed |
|
||||
| T-19.6-26 | Spoofing | client-supplied WebAuthn challenge | high | mitigate | server-side state in cooler, single-use `Pull`; `TestWebAuthnShapes/registration_state`, `TestWebAuthn/registration` | closed |
|
||||
| T-19.6-27 | Elevation of privilege | passkey login with second-factor-only credential (D-14) | high | mitigate | M `classes/passwordless.go` `ValidatePasskeyLogin` with UV, `passwordless` column check; `TestPasswordless` (mutation-checked); D-14 table in SECURITY-REVIEW | closed |
|
||||
| T-19.6-28 | Spoofing | cloned authenticator | medium | mitigate | `CloneWarning` refusal (M `classes/webauthn.go:506`, `classes/passwordless.go:110`); `TestWebAuthn/assertions` | closed |
|
||||
| T-19.6-29 | Spoofing | RP ID / origin misconfiguration | medium | mitigate | M `classes/config.go` `loadWebAuthnConfig`; `TestWebAuthnShapes`, `TestPasswordless/refused_foreign_origin` | closed |
|
||||
| T-19.6-30 | Elevation of privilege | social sign-in bypassing 2FA (D-09) | high | mitigate | S `classes/flow.go:343` `CheckLoginGates` with `LoginSourceSocial` before FinishLogin; `TestSocialGate`, `TestEveryLoginPathIsGated/social_sign_in` | closed |
|
||||
| T-19.6-31 | Elevation of privilege | passkey login of banned/suspended/inactive account | high | mitigate | M `classes/passwordless.go:126` `RejectIfThrottled` + activation check; `TestPasswordless/refused_banned`, `refused_suspended`, `refused_not_activated` | closed |
|
||||
| T-19.6-32 | Tampering | remote operations (plan 03 pushes) | medium | mitigate | process control: fetch + range check before every push, no force, no deploy (19.6-03-SUMMARY "Remote operations") | closed |
|
||||
| T-19.6-33 | Tampering | demo rendering QR SVG | low | mitigate | D `app/lib/twoFactor.ts` `svgDataUrl` (img data URL, no `v-html`); `twoFactor.test.ts` | closed |
|
||||
| T-19.6-34 | Information disclosure | user handle from numeric id (A4) | low | accept | see AR-04 | closed |
|
||||
| T-19.6-35 | Denial of service | ceremony state in memory cooler, multi-instance (A11) | low | accept | README; fails closed; see AR-06 | closed |
|
||||
| T-19.6-36 | Tampering | check-phase19.6.sh verdict | medium | mitigate | F `scripts/check-phase19.6.sh --self-test` (fail/skip/zero-match/missing-name detectors) | closed |
|
||||
| T-19.6-37 | Tampering | post-release fixes not reaching apps | medium | mitigate | `71d8f27` is an ancestor of M tag v0.1.1; pinned by sm-demo-app `9166a1e`, sm-bm-app `fe4e292` | closed |
|
||||
| T-19.6-38 | Elevation of privilege | token mint path bypassing 2FA | high | mitigate | M `login_paths_test.go` `TestEveryLoginPathIsGated` (every mint site listed); activate-by-code residual = F-1, see AR-07 | closed |
|
||||
| T-19.6-SC | Tampering | Go module installs (plans 01–04) | high | mitigate | M `go.mod`: pquerna/otp v1.5.0, boombuler/barcode v1.1.0, go-webauthn v0.18.2 (approved, `.planning/notes/2026-10-21-mfa-otp-webauthn.md`); `go list -deps` of M has no `gopkg.in/yaml.v3`; fonoteka.go `go.mod`/`go.sum` have no go-webauthn | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-01 | T-19.6-06 | Device-code phishing: D-12c keeps PHP's authorize-with-JWT rule; the device list shows name and IP and revoke signs the device out at once; the frontend must show device name and address before confirming. | user (D-12c, 19.6-CONTEXT) | 2026-10-26 |
|
||||
| AR-02 | T-19.6-08 | `blacklist_grace` > 0 lets two concurrent refreshes fork; only one jti is followed, so revoke misses the other until it expires. Default grace is 0; a password change ends both. | plan 01 (Pitfall 15) | 2026-10-26 |
|
||||
| AR-03 | T-19.6-25 | Client-chosen TOTP secret at confirm (PHP parity): own account only, base32 and 16–64 chars validated, a current code from the secret required. | plan 02 threat model | 2026-10-26 |
|
||||
| AR-04 | T-19.6-34 | PHP-compatible 8-byte user handle reveals only the internal user id to the user's own authenticator; keeps imported passkeys mappable. | plan 03 threat model (A4) | 2026-10-26 |
|
||||
| AR-05 | T-19.6-09 | Reverse proxies may log `devices/status/{token}`; the token lives five minutes and is single use (README). | plan 01 threat model | 2026-10-26 |
|
||||
| AR-06 | T-19.6-35 | With the memory cooler a WebAuthn ceremony must stay on one instance; multi-instance apps use the Redis cooler (README); ceremonies fail closed otherwise. | plan 03 threat model (A11) | 2026-10-26 |
|
||||
| AR-07 | T-19.6-38 (F-1) | activate-by-code mints a token without the second factor only when `require_activation: false` and the user enabled 2FA before activating; the mailed activation code stands in for the second factor once. Low impact, non-default config. Deferred; pinned by `TestEveryLoginPathIsGated/mint_sites`; todo `.planning/todos/pending/2026-10-26-activate-by-code-second-factor.md`. | user (plan 04 Task 5, option c) | 2026-10-26 |
|
||||
|
||||
*Accepted risks do not resurface in future audit runs.*
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-10-26 | 42 | 42 | 0 | plan 04 security review (`19.6-SECURITY-REVIEW.md`; mutation checks, `check-phase19.6.sh --all` with Docker) |
|
||||
| 2026-10-28 | 42 | 42 | 0 | /msd-secure-phase (L1 grep verification of cited mitigations in U, M, S, D, F; short-circuit: register authored at plan time, ASVS 1) |
|
||||
|
||||
Threat count: T-19.6-01..38 plus four T-19.6-SC rows (plans 01–04), merged into one row above.
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
|
||||
**Approval:** verified 2026-10-28
|
||||
@@ -45,7 +45,7 @@ A third fix found by the tests is functional, not a security gap: c29d228 `fix(p
|
||||
| T-19.7-07 | `payload` is accepted only for an action with a Prompt, only as a JSON string, trimmed, non-empty and capped in runes; every other record action still refuses a payload; a plain action runs with an empty Value. | F `cabana/actions.go:217`, `:256` | `TestRecordActionPromptSmoke`, `TestRecordActionPrompt`, `TestRecordActionPromptRun` (F) | verified |
|
||||
| T-19.7-08 | Contributed labels, statuses, messages and URLs render as text and attributes (no `v-html`); a URL opens with `noopener` and the visible link carries `rel="noopener noreferrer"`. | F `admin/src/components/account/AccountContributions.vue` | `admin/tests/account/AccountContributions.test.ts` ("Text, never HTML", URL attributes) (F) | corrected: fixed in 44835e4, 88559d5 (F); was verified (see Corrections) |
|
||||
| T-19.7-09 | wristband's authorize allow-list is exactly `Options.ScopesSupported`; the default server refuses `backend`; `openid` and unlisted scopes stay refused on the MCP flavour. | F `wristband/authorize.go:31`, `:231` | `TestMCPScopesSmoke`, `TestMCPScopes` (F) | verified |
|
||||
| T-19.7-10 | Every request re-verifies its bearer (`auth.RequireBearerToken` with pier's resolver); a session never replaces it; a failure is 401 with the RFC 9728 challenge and `scope="read"`. | F `pier/pier.go:235-260`; F `pier/identity.go:144` | `TestPierTracerSmoke` (bad bearer), `TestEndpointGuards` (stream ends after revocation), `TestMCPEndToEnd` "revoked token" (F, D) | verified |
|
||||
| T-19.7-10 | Every request re-verifies its bearer (`auth.RequireBearerToken` with pier's resolver); a session never replaces it; a failure is 401 with the RFC 9728 challenge naming only `resource_metadata` (no scope parameter since quick 261106-kt1, so clients request the PRM `scopes_supported`). | F `pier/pier.go:256-274`; F `pier/identity.go:144` | `TestPierTracerSmoke` (bad bearer, missing bearer), `TestEndpointGuards` (stream ends after revocation), `TestMCPEndToEnd` "revoked token" (F, D) | verified |
|
||||
| T-19.7-11 | The session record stores only the binding (`oauth:<client>:<user>` or the personal token id), compared on every POST, GET and DELETE (403 `session_binding`); ids from `rand.Text()`; sliding idle TTL; per-binding cap. | F `pier/session.go:143`, `:211`, `:242`, `:139` | `TestPierSessionsSmoke`, `TestSessions` (Redis and memory) (F) | verified |
|
||||
| T-19.7-12 | The inner request is built fresh (`httptest.NewRequestWithContext`) with no Authorization or Cookie; identity travels only in the marker; client address, X-Forwarded-For, X-Real-IP and Accept-Language are copied. | F `pier/dispatch.go:159-180` | `TestPierTracerSmoke` (echo route `auth: false`), `TestDispatch` (outer Cookie and Authorization absent) (F) | verified |
|
||||
| T-19.7-13 | A backend subject exists only with `backend` in the grant AND a link the resolver confirms per request (5 s cache), or an admin `g15_` token behind `mcp.allow_personal_tokens`; the read/write ceiling applies on top; list and call use the same `allowed`. | F `pier/identity.go:152`, `:187-198`; F `pier/filter.go:16`, `:37` | `TestToolsList` (no link, no backend tool; union with a link), `TestPierTracerSmoke` "personal tokens behind the flag", `TestMCPEndToEnd` (no backend tool without the scope) (F, D) | verified |
|
||||
|
||||
@@ -29,19 +29,19 @@ findings:
|
||||
title: "Process's plain path prints item names without Sanitize"
|
||||
- id: IN-10
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "console.Error during a live view writes straight to the terminal and tears the view"
|
||||
- id: IN-11
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "A blank line printed during a live view is dropped"
|
||||
- id: IN-12
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "Signal relay edge cases: a signal during view start-up, and Windows"
|
||||
- id: IN-13
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "A delegate's stderr always goes to os.Stderr, bypassing the root's error writer"
|
||||
- id: IN-14
|
||||
severity: info
|
||||
@@ -97,39 +97,39 @@ findings:
|
||||
title: "The wrong-directory hint repeats every argument, including a --password value, on stderr"
|
||||
- id: IN-01
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "A forced-color console drops HideOnTTY records even when stderr is not a terminal"
|
||||
- id: IN-02
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "PeekGlobals and cobra disagree on some argument forms"
|
||||
- id: IN-03
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "isUsage recognises cobra's unknown-command error by its text"
|
||||
- id: IN-04
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "The --json flag is read two different ways"
|
||||
- id: IN-05
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "summer's scaffolding result lines are now hidden by -q"
|
||||
- id: IN-06
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "fang replaces the root help function that NewRootIO installs"
|
||||
- id: IN-07
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "diary pulls the whole TUI stack into security modules"
|
||||
- id: IN-08
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "The console sanitizer passes raw C1 bytes through on its fast path"
|
||||
- id: IN-09
|
||||
severity: info
|
||||
disposition: deferred
|
||||
disposition: fixed
|
||||
title: "The phase gate names consuming applications"
|
||||
open: 0
|
||||
total: 32
|
||||
@@ -141,15 +141,15 @@ recorded: 2026-10-22T01:19:33.337Z
|
||||
| Finding | Severity | Disposition | Source |
|
||||
|---------|----------|-------------|--------|
|
||||
| WR-09 | warning | fixed | fix fce232d (quick 261022-4z8) |
|
||||
| WR-10 | warning | fixed | fix 17c722d (quick 261022-4z8); the exit-130 suggestion is deferred to todo .planning/todos/pending/2026-10-22-console-review-info-findings.md |
|
||||
| WR-10 | warning | fixed | fix 17c722d (quick 261022-4z8); follow-up bb7e14b (quick 261028-rqd): a delegate killed by a signal exits 128+n, silently for SIGINT and SIGTERM |
|
||||
| WR-11 | warning | fixed | fix 707372b (quick 261022-4z8) |
|
||||
| WR-12 | warning | fixed | fix 57a849d, reworked in 139f5e3 so that lagoon.Status stays plugin-only and migrate:status adds the framework sets itself (quick 261022-4z8) |
|
||||
| WR-13 | warning | fixed | fix 0691d26 (quick 261022-4z8) |
|
||||
| WR-14 | warning | fixed | fix 48e13f9 (quick 261022-4z8) |
|
||||
| IN-10 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md |
|
||||
| IN-11 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md |
|
||||
| IN-12 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md |
|
||||
| IN-13 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md |
|
||||
| IN-10 | info | fixed | fix 6efb9a4 (quick 261028-rqd) |
|
||||
| IN-11 | info | fixed | fix 4d75695 (quick 261028-rqd) |
|
||||
| IN-12 | info | fixed | fix f91d70d (quick 261028-rqd); part 2 (Windows) not changed, documented in raise's doc comment: Go cannot report another handler, and returning without exiting would swallow Ctrl+C |
|
||||
| IN-13 | info | fixed | fix 4914cad, bonfire.ErrWriter (quick 261028-rqd) |
|
||||
| IN-14 | info | fixed | docs 7c15095 (quick 261022-4z8) |
|
||||
| IN-15 | info | fixed | fix 1ac75ad (quick 261022-4z8) |
|
||||
| CR-01 | critical | fixed | fix b077dc3 (19.8-05) (not in the current review) |
|
||||
@@ -163,15 +163,15 @@ recorded: 2026-10-22T01:19:33.337Z
|
||||
| WR-06 | warning | fixed | fix 39677f1 (19.8-05) (not in the current review) |
|
||||
| WR-07 | warning | fixed | fix 020fe83 (19.8-05) (not in the current review); remainder WR-12 (fix 57a849d) |
|
||||
| WR-08 | warning | fixed | fix 9b62285 (19.8-05) (not in the current review); remainder WR-11 (fix 707372b) |
|
||||
| IN-01 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-02 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-03 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-04 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-05 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-06 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-07 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-08 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-09 | info | deferred | todo .planning/todos/pending/2026-10-22-console-review-info-findings.md (not in the current review) |
|
||||
| IN-01 | info | fixed | fix 3520d5d (quick 261028-rqd) (not in the current review) |
|
||||
| IN-02 | info | fixed | fix e34d113 (quick 261028-rqd) (not in the current review) |
|
||||
| IN-03 | info | fixed | fix 39c59b8 (quick 261028-rqd) (not in the current review) |
|
||||
| IN-04 | info | fixed | feat 795c4f6, bonfire.FlagBool (quick 261028-rqd); summer's flagTrue/flagBool and flare's flagSet keep their wider value sets for compatibility (not in the current review) |
|
||||
| IN-05 | info | fixed | docs 2da42e9 (quick 261028-rqd): documentation fix, the code is unchanged (0.4 shipped the lines; -q hiding them is now documented) (not in the current review) |
|
||||
| IN-06 | info | fixed | refactor 53c0a65, fang removed; planning docs 6294ac4 (quick 261028-rqd) (not in the current review) |
|
||||
| IN-07 | info | fixed | refactor f3f87f3, internal/consolekit (quick 261028-rqd) (not in the current review) |
|
||||
| IN-08 | info | fixed | fix 8476a65 (quick 261028-rqd) (not in the current review) |
|
||||
| IN-09 | info | fixed | fix 10fec47 (quick 261028-rqd) (not in the current review) |
|
||||
|
||||
Dispositions: `open` (recorded, not yet triaged), `fixed`, `skipped`, `deferred`.
|
||||
Set `deferred` by hand and put the reason in the Source cell; both are preserved. A `|` in the reason is kept as prose and escaped on the next run.
|
||||
|
||||
@@ -0,0 +1,421 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- ../sm-chat-plugin/events/events.go
|
||||
- ../sm-chat-plugin/contracts/rejection.go
|
||||
- ../sm-chat-plugin/classes/service.go
|
||||
- ../sm-chat-plugin/classes/writes.go
|
||||
- ../sm-chat-plugin/api/errors.go
|
||||
- ../sm-chat-plugin/saving_smoke_test.go
|
||||
- ../sm-chat-plugin/README.md
|
||||
- ../sm-forum-plugin/events/events.go
|
||||
- ../sm-forum-plugin/contracts/rejection.go
|
||||
- ../sm-forum-plugin/classes/forum_service.go
|
||||
- ../sm-forum-plugin/classes/lifecycle.go
|
||||
- ../sm-forum-plugin/api/errors.go
|
||||
- ../sm-forum-plugin/saving_smoke_test.go
|
||||
- ../sm-forum-plugin/README.md
|
||||
- ../sm-chatvideo-plugin/go.mod
|
||||
- ../sm-chatvideo-plugin/go.sum
|
||||
- ../sm-chatvideo-plugin/README.md
|
||||
- ../sm-herald-plugin/go.mod
|
||||
- ../sm-herald-plugin/go.sum
|
||||
- ../sm-herald-plugin/README.md
|
||||
- ../sm-userfriends-plugin/go.mod
|
||||
- ../sm-userfriends-plugin/go.sum
|
||||
- ../sm-userfriends-plugin/README.md
|
||||
- ../sm-moderation-plugin/.gitignore
|
||||
- ../sm-moderation-plugin/go.mod
|
||||
- ../sm-moderation-plugin/go.sum
|
||||
- ../sm-moderation-plugin/go.work
|
||||
- ../sm-moderation-plugin/plugin.go
|
||||
- ../sm-moderation-plugin/admin.go
|
||||
- ../sm-moderation-plugin/admin_permissions.go
|
||||
- ../sm-moderation-plugin/logger.go
|
||||
- ../sm-moderation-plugin/classes/filter.go
|
||||
- ../sm-moderation-plugin/classes/filter_smoke_test.go
|
||||
- ../sm-moderation-plugin/models/settings.go
|
||||
- ../sm-moderation-plugin/models/registry.go
|
||||
- ../sm-moderation-plugin/models/settings/fields.yaml
|
||||
- ../sm-moderation-plugin/updates/202610280001_create_golem15_moderation_settings.go
|
||||
- ../sm-moderation-plugin/updates/registry.go
|
||||
- ../sm-moderation-plugin/lang/en/lang.yaml
|
||||
- ../sm-moderation-plugin/lang/pl/lang.yaml
|
||||
- ../sm-moderation-plugin/config/config.yaml
|
||||
- ../sm-moderation-plugin/README.md
|
||||
autonomous: false
|
||||
requirements: [SC-1, D-17, D-18, D-19, D-20]
|
||||
estimate:
|
||||
tokens: 220000
|
||||
raw_tokens: 220000
|
||||
tasks: 6
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "D-18 (chat): with a festival listener on events.MessageSaving that returns contracts.Rejection{Field: \"content\", Message: m}, POST /_chat/api/v1/conversations/{id}/messages, POST /_chat/api/v1/messages/{id}/replies and PUT /_chat/api/v1/messages/{id} answer 422 {\"error\":\"Validation failed\",\"errors\":{\"content\":[m]}}; no golem15_chat_messages row is inserted or changed, MessageCreated and MessageUpdated do not fire and nothing is published."
|
||||
- "D-18 (forum): ForumService.CreateThread, Reply and EditPost fire events.PostSaving before breakwater.Render; a contracts.Rejection from a listener maps to the existing 422 envelope under errors.title or errors.body and nothing is persisted."
|
||||
- "D-18 (parity): with no MessageSaving or PostSaving listener every existing route, payload, status, table, migration ID and config key of sm-chat-plugin and sm-forum-plugin is unchanged; their php_method_map_test.go and golden_test.go pass without edits; the seams name no application and ship as patch-level additions."
|
||||
- "D-17: the new shared plugin golem15.moderation (module git.golem15.com/golem15/sm-moderation-plugin) publishes *classes.Filter at boot; Filter.Check returns a Violation for a banned word or phrase (case-insensitive, Unicode letter boundaries, Polish letters included) or a banned link (a listed domain, its subdomains, with or without scheme or www, and URL-prefix entries), and nil for clean text; the lists are the banned_words and banned_links textareas of its admin settings screen (singleton golem15_moderation_settings) behind the permission golem15.moderation.manage_settings; the plugin imports neither chat nor forum."
|
||||
- "SC-1: sm-chatvideo-plugin, sm-herald-plugin and sm-userfriends-plugin go.mod files keep only the framework replace and require sm-chat-plugin v0.1.3, sm-user-plugin v0.1.13 and summercms v0.5.1 where they depend on them; every one of the eight repos passes go vet and go test -short, and the five chat dependants build with GOWORK=off."
|
||||
- "SC-1 (release, after the Task 5 go-ahead): origin of each repo carries its new tag on the pushed HEAD that passed the checks: sm-chat-plugin v0.1.4 (patch, the seam), sm-chatchannels-plugin, sm-chatbots-plugin, sm-chatvideo-plugin, sm-forum-plugin, sm-herald-plugin, sm-userfriends-plugin and sm-moderation-plugin v0.1.0 (or the next free number read from the remote); a scratch module requiring all eight tags and summercms v0.5.1 builds with GOWORK=off."
|
||||
- "D-20 (D-19 superseded): this is plan 01 of the six plans confirmed at plan time; the chat family release precedes the demo backend (plan 02)."
|
||||
artifacts:
|
||||
- path: "../sm-chat-plugin/events/events.go"
|
||||
provides: "MessageSaving pre-save event and MessageSavingEventName"
|
||||
contains: "MessageSaving"
|
||||
- path: "../sm-chat-plugin/contracts/rejection.go"
|
||||
provides: "Rejection{Field, Message} error a pre-save listener returns"
|
||||
contains: "type Rejection struct"
|
||||
- path: "../sm-forum-plugin/events/events.go"
|
||||
provides: "PostSaving pre-save event and PostSavingEventName"
|
||||
contains: "PostSaving"
|
||||
- path: "../sm-forum-plugin/contracts/rejection.go"
|
||||
provides: "Rejection{Field, Message} for forum listeners"
|
||||
contains: "type Rejection struct"
|
||||
- path: "../sm-moderation-plugin/classes/filter.go"
|
||||
provides: "Filter, NewFilter, Check, Match, ParseList, Violation"
|
||||
contains: "func (f *Filter) Check"
|
||||
- path: "../sm-moderation-plugin/admin.go"
|
||||
provides: "moderation_settings settings item (HasSettings, HasLang)"
|
||||
contains: "moderation_settings"
|
||||
key_links:
|
||||
- from: "../sm-chat-plugin/classes/service.go"
|
||||
to: "../sm-chat-plugin/events/events.go"
|
||||
via: "SendMessageWith fires MessageSaving on s.bus before lagoon.Transaction"
|
||||
pattern: "MessageSaving\\{"
|
||||
- from: "../sm-chat-plugin/api/errors.go"
|
||||
to: "../sm-chat-plugin/contracts/rejection.go"
|
||||
via: "writeChatError maps errors.As(err, &contracts.Rejection) to writeValidation"
|
||||
pattern: "errors\\.As\\(err, &rej\\)"
|
||||
- from: "../sm-forum-plugin/classes/forum_service.go"
|
||||
to: "../sm-forum-plugin/events/events.go"
|
||||
via: "CreateThread and Reply fire PostSaving on s.bus before breakwater.Render"
|
||||
pattern: "PostSaving\\{"
|
||||
- from: "../sm-moderation-plugin/plugin.go"
|
||||
to: "../sm-moderation-plugin/classes/filter.go"
|
||||
via: "Boot publishes classes.NewFilter(db) through app.Publish inside lagoon.OnDatabase"
|
||||
pattern: "app\\.Publish"
|
||||
prohibitions:
|
||||
- statement: "No existing route, request or response field, status code, table, migration ID or config key of sm-chat-plugin or sm-forum-plugin changes; the seams are additive (WavePath parity, Phase 31)."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "sm-moderation-plugin depends on neither sm-chat-plugin nor sm-forum-plugin."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "No README, comment or identifier in the eight repos names a consuming application."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "Nothing is pushed, no remote repository is created and no tag is set before the Task 5 go-ahead."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here, see the planning return): `sm-demo-app` runs every shared Golem15 plugin collected so far in one binary, and its public Nuxt site shows them working: chat and channels with realtime, video calls, presentations, quizzes, journal, FAQ, subscriptions and the rest. Phase 19.4.1 deployed the demo early; this phase adds the chat family to that live instance.
|
||||
|
||||
This plan's slice (plan 1 of 6, wave 1, per D-20): the shared plugin release the demo needs before it can require the chat family by tag. Fast-forward the stale sibling checkouts, add the generic pre-save seams to chat and forum (D-18), create `sm-moderation-plugin` (D-17), fix the go.mod files that break module mode, and, after the user's go-ahead, push and tag all eight repositories.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Seam shape (D-18 discretion):** a festival "-ing" event fired before the write transaction, mirroring `user.Deleting` / `user.Deactivating` in sm-user-plugin. chat gets `events.MessageSaving`, forum a new `events` package with `events.PostSaving`. A listener refuses by returning the plugin's own `contracts.Rejection{Field, Message}`. Each plugin declares its own type, so forum does not import chat and neither imports moderation. The API maps `errors.As(err, &rej)` to the existing 422 envelope. Rationale: `festival.Bus.Fire` already returns the joined listener errors, chat already holds `s.bus`, forum holds an unused `Bus` field, and no service gains a new registration method. RESEARCH Pattern 2.
|
||||
- **Event names:** `MessageSavingEventName = "golem15.chat.message.saving"` and `PostSavingEventName = "golem15.forum.post.saving"`. They are Go-only seams with no PHP counterpart; the doc comments say so.
|
||||
- **Op values:** chat `OpCreate = "create"` and `OpUpdate = "update"`; forum `OpThread = "thread"`, `OpReply = "reply"` and `OpUpdate = "update"`.
|
||||
- **Moderation lists:** two textareas, one entry per line; an `enabled` switch defaults to true; at most 500 entries of at most 200 characters per list (validated in `BeforeValidate`). The filter reads the singleton row on every `Check` and recompiles its matchers only when the stored text changed. RE2's `\b` is ASCII-only, so word boundaries are built from `[^\p{L}\p{N}_]` to cover Polish letters.
|
||||
- **Violation message:** `Violation{Kind, Match, Message}`. Message comes from the plugin's lang files (`golem15.moderation::lang.violation.word` and `.link`, EN and PL) in the locale `towel.Locale(ctx)` carries, resolved through the framework's phrasebook. Without a locale it is English. The chat-family APIs answer in English today, so English is an acceptable fallback.
|
||||
- **Dependants require existing tags:** chatvideo, herald and userfriends require `sm-chat-plugin v0.1.3` (the newest tag before this plan), `sm-user-plugin v0.1.13` and `summercms v0.5.1`, the set RESEARCH compiled. That keeps their module-mode check independent of the new chat tag; minimal version selection gives the demo chat v0.1.4.
|
||||
- **Repository creation:** with the go-ahead, Claude creates `golem15/sm-moderation-plugin` on git.golem15.com with `tea` when `tea login list` shows a git.golem15.com login, using the same visibility as `sm-sitemap-plugin`. Otherwise the user creates it.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
## Artifacts this phase produces (this plan)
|
||||
|
||||
- sm-chat-plugin (v0.1.4): `events.MessageSaving`, `events.MessageSavingEventName`, `events.OpCreate`, `events.OpUpdate`, `contracts.Rejection` (`Error()`), the 422 mapping in `writeChatError`, smoke test `TestMessageSavingTracer` (`saving_smoke_test.go`), a README changelog entry v0.1.4.
|
||||
- sm-forum-plugin (v0.1.0): package `events` (`PostSaving`, `PostSavingEventName`, `OpThread`, `OpReply`, `OpUpdate`), `contracts.Rejection`, the 422 mapping in `writeForumError`, smoke test `TestPostSavingTracer`.
|
||||
- sm-moderation-plugin (new repo, v0.1.0): plugin `golem15.moderation`, package `moderation`, `classes.Filter`, `classes.NewFilter(db *gorm.DB) *Filter`, `(*Filter).Check(ctx context.Context, text string) (*Violation, error)`, `classes.Match(words, links []string, text string) *Violation`, `classes.ParseList(text string) []string`, `classes.Violation{Kind, Match, Message}`, `classes.KindWord`, `classes.KindLink`, table `golem15_moderation_settings` (migration `202610280001_create_golem15_moderation_settings`), settings item `moderation_settings`, permission `golem15.moderation.manage_settings`, config keys `golem15.moderation.max_entries` and `golem15.moderation.max_entry_length`, smoke test `TestFilterSmoke`.
|
||||
- go.mod fixes in sm-chatvideo-plugin, sm-herald-plugin and sm-userfriends-plugin.
|
||||
- Tags: chat v0.1.4; chatchannels, chatbots, chatvideo, forum, herald, userfriends and moderation v0.1.0 (numbers read from the remote at release time).
|
||||
- Full unit tests come in plan 06 (project rule).
|
||||
|
||||
<objective>
|
||||
Release the chat family so the demo can require it by tag: the D-18 pre-save seams in chat and forum, the D-17 moderation plugin, go.mod hygiene, and eight tags after the user's go-ahead.
|
||||
|
||||
Purpose: SC-1 needs `sm-demo-app` to build from tagged modules (19.4.1 D-03, `TestGoModRequiresTags`, `scripts/check-pins.sh`). D-17 and D-18 need the seams and the filter before plan 02 wires them. D-20 makes this plan 01 of six and supersedes D-19's earlier split.
|
||||
Output: commits and, after the go-ahead, pushes and tags in eight plugin repositories. No change in sm-demo-app, vue-demo-app or summercms.go code.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-RESEARCH.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-PATTERNS.md
|
||||
@.planning/notes/core-plugins-own-repos.md
|
||||
|
||||
Repos (siblings of summercms.go): ../sm-chat-plugin, ../sm-chatchannels-plugin, ../sm-chatbots-plugin (all three behind origin: fast-forward first), ../sm-chatvideo-plugin, ../sm-forum-plugin, ../sm-herald-plugin, ../sm-userfriends-plugin, and the new ../sm-moderation-plugin. Read-only references: ../sm-bm-app/plugins/golem15/{chat,chatchannels,chatbots} (the origin-main trees, for reading only), ../sm-sitemap-plugin (plugin and settings analog), ../sm-demo-app/plugins/golem15/user/classes/events.go (the "-ing" event analog).
|
||||
|
||||
Rules: no co-author tags in commits (user instruction overrides any attribution default); stage files by explicit path, never `git add -A`; one logical change per commit; nothing pushed, created or tagged before Task 5. Verify commands run from the framework root and address siblings with `go -C ../<repo>`. Plugin repos with a tracked go.work resolve their siblings through it (the seam-carrying ../sm-chat-plugin included). If the Docker socket is denied, run the Docker tests through `sudo -u golem` (CLAUDE.md).
|
||||
|
||||
<interfaces>
|
||||
chat (origin main 51c9e17 = v0.1.3, same tree as ../sm-bm-app/plugins/golem15/chat):
|
||||
- `classes.Service` fields `bus *festival.Bus` (from `Options.Bus`); `SendMessageWith(ctx, in SendInput) (*models.Message, error)` validates metadata, loads the conversation, checks `canSend`, trims content, returns `ErrEmptyMessage` when content and attachments are empty, then opens `lagoon.Transaction` and fires `events.MessageCreated` inside it (classes/service.go:287-345). `SendMessage` and `ReplyTo` (classes/attachments.go:218) funnel into it.
|
||||
- `EditMessage(ctx, actorID, messageID uint, content string) (*models.Message, error)` in classes/writes.go:248, after `CanEditMessage` (writes.go:202).
|
||||
- events/events.go: `MessageEvent{MessageID, ConversationID, ActorID uint; RootID *uint; Tx *gorm.DB}`, `MessageCreated`, `MessageUpdated`, `MessageDeleted`, consts `MessageCreatedEventName` etc.; the package doc says every event fires inside the transaction.
|
||||
- api/errors.go: `writeValidation(w, map[string][]string)`, `writeChatError(w, what, err)` (switch over errors.Is, default 500).
|
||||
- Test helpers: harness_test.go `bootChat`, `(*chatEnv).user`, `.count`, `.memory`, `.conversation(t, createdBy, typ, alias, contextID, participants...)`; http_tracer_test.go `bootWeb`, `(*webEnv).frontendToken`, `.call(t, method, path, token, body)`, `decodeObject`.
|
||||
forum (../sm-forum-plugin, origin main 2779341):
|
||||
- `classes.ForumService{bus *festival.Bus}` built in boot.go `bootService` with `Bus: app.Events`; `CreateThread(ctx, actorID, contextType, contextID, categoryID, title, body)` renders at forum_service.go:281, `Reply(...)` at :330, `EditPost(ctx, actorID, contextType, contextID, postID, body)` in classes/lifecycle.go:217. No `Fire(` call exists in the plugin today.
|
||||
- api/errors.go: `writeValidation`, `writeForumError` (ErrForbidden/ErrNotFound 404, ErrTitleRequired/ErrBodyRequired 422).
|
||||
- Test helpers: harness_test.go `bootForum`, `.user`, `.count`; http_tracer_test.go `bootWeb`, `.frontendToken`, `.call`.
|
||||
festival (framework): `(*Bus).Listen[T any](owner string, fn func(context.Context, T) error)`, `(*Bus).Fire[T any](ctx, event T) error` returns errors.Join of listener errors (callers use errors.As).
|
||||
sitemap analog: plugin.go (embed config, `pact.HasConfig/HasMigrations/HasModels`), admin.go (`Settings() []pact.SettingsItem` with Code, Label, Description, Category, Icon, Permissions, Form, NewModel; `AdminFS`, `LangFS`), admin_permissions.go (`Permissions() []pact.Permission`), models/settings.go (singleton row id 1, `*string` columns, `BeforeValidate` with a lang-key error), models/settings/fields.yaml, updates/202610110002_create_golem15_sitemap_settings.go (CREATE TABLE plus INSERT id 1), go.mod replace `git.golem15.com/golem15/summercms => ../summercms.go`, tracked go.work.
|
||||
go.mod today: chatvideo requires chat v0.0.0 and replaces chat and user with sibling paths; herald replaces user with ../fonoteka.go/plugins/golem15/user; userfriends requires chat pseudo-version v0.0.0-20261017200243-4d0e764ca443.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: a rejecting MessageSaving listener turns a chat send into the existing 422 envelope and nothing is stored</name>
|
||||
<reversibility rating="costly">D-18: the seam becomes a public plugin contract other consumers can start using; changing its shape later touches every listener.</reversibility>
|
||||
<precondition>`git -C ../sm-<name>-plugin status --porcelain` prints nothing for chat, chatchannels, chatbots, chatvideo, forum, herald and userfriends; `docker info` exits 0.</precondition>
|
||||
<files>../sm-chat-plugin/events/events.go, ../sm-chat-plugin/contracts/rejection.go, ../sm-chat-plugin/classes/service.go, ../sm-chat-plugin/classes/writes.go, ../sm-chat-plugin/api/errors.go, ../sm-chat-plugin/saving_smoke_test.go, ../sm-chat-plugin/README.md</files>
|
||||
<read_first>../sm-chat-plugin/classes/service.go (SendMessageWith, Options.Bus), ../sm-chat-plugin/classes/writes.go (EditMessage, CanEditMessage), ../sm-chat-plugin/classes/attachments.go (ReplyTo), ../sm-chat-plugin/events/events.go, ../sm-chat-plugin/api/errors.go, ../sm-chat-plugin/api/messages.go and api/replies.go, ../sm-chat-plugin/http_tracer_test.go and harness_test.go, ../sm-chat-plugin/php_method_map_test.go, ../sm-chat-plugin/README.md, ../sm-demo-app/plugins/golem15/user/classes/events.go (DeactivatingEvent doc style), modules/festival/bus.go, 20-RESEARCH.md (Pattern 2, Pitfall 1), 20-PATTERNS.md (Chat / forum pre-save seam)</read_first>
|
||||
<action>Per D-18 and D-20; wire one path end to end: listener, service, API, HTTP response, database unchanged.
|
||||
|
||||
1. Fast-forward every sibling first (RESEARCH Pitfall 1): for chat, chatchannels, chatbots, chatvideo, forum, herald and userfriends run `git -C ../<repo> pull --ff-only` and confirm `git -C ../<repo> rev-parse HEAD` equals the hash `git -C ../<repo> ls-remote origin refs/heads/main` prints (use the default branch each repo tracks). Record both hashes per repo for the SUMMARY. A non-fast-forward stops the task.
|
||||
2. events/events.go: keep the three existing events untouched. Add `MessageSavingEventName = "golem15.chat.message.saving"` on its own line and a `MessageSaving` struct with `ConversationID`, `ActorID` and `MessageID uint` (MessageID is 0 on create), `RootID *uint`, `Content string` and `Op string`, plus the constants `OpCreate = "create"` and `OpUpdate = "update"`. MessageSaving carries no Tx because it fires before the transaction. Rewrite the package doc: the three message events fire inside the transaction after the save; MessageSaving fires before it, has no PHP counterpart, and a listener error aborts the write; a listener refuses with contracts.Rejection.
|
||||
3. contracts/rejection.go: `type Rejection struct { Field, Message string }` with a value-receiver `Error() string` returning "golem15.chat: rejected " + Field + ": " + Message. The doc comment explains that listeners return the value (not a pointer) and callers match it with errors.As, because Fire joins listener errors.
|
||||
4. classes/service.go `SendMessageWith`: after the ErrEmptyMessage check and before `lagoon.Transaction`, when `s.bus != nil`, fire `&events.MessageSaving{Op: events.OpCreate, ConversationID, ActorID: senderID, RootID: rootID, Content: content}` (the trimmed content) and return `nil, err` on error. classes/writes.go `EditMessage`: after CanEditMessage allows the edit and the new content is validated, before its transaction, fire the same event with `Op: events.OpUpdate` and the MessageID. No other line of either method changes.
|
||||
5. api/errors.go `writeChatError`: before the existing switch, declare `var rej contracts.Rejection` and, when `errors.As(err, &rej)`, call `writeValidation(w, map[string][]string{field: {rej.Message}})` with field = rej.Field, or "content" when Field is empty, then return. The other branches stay byte-identical.
|
||||
6. saving_smoke_test.go `TestMessageSavingTracer` (Docker; skips under -short like the other HTTP tests): boot with bootWeb; register on the app's event bus a `*events.MessageSaving` listener returning `contracts.Rejection{Field: "content", Message: "not allowed"}` when Content contains the word "blocked"; create a group conversation with two participants through the harness; then
|
||||
- POST `/_chat/api/v1/conversations/{id}/messages` with content "this is blocked": 422, body errors.content equals ["not allowed"], and golem15_chat_messages has 0 rows;
|
||||
- POST the content "hello": 201, 1 row;
|
||||
- PUT `/_chat/api/v1/messages/{id}` with "blocked edit": 422, and the stored content is still "hello";
|
||||
- POST `/_chat/api/v1/messages/{id}/replies` with "blocked reply": 422, and the row count is still 1.
|
||||
7. README.md: in Features and API reference, add MessageSaving (when it fires, no Tx, Op values), MessageSavingEventName, OpCreate, OpUpdate and contracts.Rejection, with a neutral example host listener (`acme`). Add a changelog entry "v0.1.4: pre-save MessageSaving event and Rejection (additive; no listener means no change)". Name no consuming application.
|
||||
|
||||
Commit in ../sm-chat-plugin by path (`feat: pre-save MessageSaving event and Rejection`), README in the same commit. Do not push or tag.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-chat-plugin vet ./... && go -C ../sm-chat-plugin test -count=1 -short ./... && go -C ../sm-chat-plugin test -count=1 -run '^TestMessageSavingTracer$' -v . 2>&1 | grep -q -- '^--- PASS: TestMessageSavingTracer'</automated>
|
||||
<fails_when>Non-zero exit: vet or the short suite red (php_method_map or golden tests broken by the change), or no "--- PASS: TestMessageSavingTracer" line (Docker unavailable so it skipped, a 201 where 422 was expected, or a stored row after a refusal).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `go -C ../sm-chat-plugin test -count=1 ./...` (with Docker) passes, including the unchanged php_method_map_test.go and golden_test.go.
|
||||
- `git -C ../sm-chat-plugin diff HEAD~1 --stat -- php_method_map_test.go golden_test.go testdata` prints nothing.
|
||||
- `grep -c 'MessageSavingEventName = "golem15.chat.message.saving"' ../sm-chat-plugin/events/events.go` prints 1.
|
||||
- `grep -c 'errors.As(err, &rej)' ../sm-chat-plugin/api/errors.go` prints 1.
|
||||
- `grep -c 'v0.1.4' ../sm-chat-plugin/README.md` prints at least 1.
|
||||
- The SUMMARY records the before and after HEAD of all seven siblings, and each after-HEAD equals origin's default branch.
|
||||
</acceptance_criteria>
|
||||
<done>A host can refuse a chat message before it is stored, the client gets the existing 422 envelope, and without a listener chat behaves byte-identically.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: The forum gets the same seam: PostSaving before render on thread, reply and edit</name>
|
||||
<reversibility rating="costly">D-18: a new public event package and Rejection type in a WavePath port-target plugin; later consumers depend on the field names.</reversibility>
|
||||
<files>../sm-forum-plugin/events/events.go, ../sm-forum-plugin/contracts/rejection.go, ../sm-forum-plugin/classes/forum_service.go, ../sm-forum-plugin/classes/lifecycle.go, ../sm-forum-plugin/api/errors.go, ../sm-forum-plugin/saving_smoke_test.go, ../sm-forum-plugin/README.md</files>
|
||||
<read_first>../sm-forum-plugin/classes/forum_service.go (Options, New, CreateThread, Reply), ../sm-forum-plugin/classes/lifecycle.go (EditPost), ../sm-forum-plugin/boot.go (bootService passes app.Events), ../sm-forum-plugin/api/errors.go, ../sm-forum-plugin/api/threads.go and api/posts.go, ../sm-forum-plugin/http_tracer_test.go, harness_test.go and fixture_plugin_test.go (test access resolver), ../sm-forum-plugin/php_method_map_test.go, ../sm-forum-plugin/README.md, ../sm-chat-plugin/events/events.go and contracts/rejection.go (Task 1, for the shape)</read_first>
|
||||
<action>Per D-18.
|
||||
|
||||
- New package events (events/events.go):
|
||||
- `PostSavingEventName = "golem15.forum.post.saving"`;
|
||||
- `PostSaving` with `ContextType string`, `ContextID`, `ActorID`, `ThreadID` and `PostID uint`, `Title`, `Body` and `Op string`;
|
||||
- constants `OpThread = "thread"` (ThreadID 0, Title set), `OpReply = "reply"` and `OpUpdate = "update"`.
|
||||
- The package doc says forum fires no post-save events, PostSaving is a Go-only seam fired before render and persistence, and a listener error aborts the write.
|
||||
- contracts/rejection.go: the same shape as chat's, with "golem15.forum: rejected " in Error().
|
||||
- ForumService, all guarded by `s.bus != nil`, firing after the access and required-field checks and before `breakwater.Render`, returning the error unchanged:
|
||||
- CreateThread fires PostSaving with OpThread, the trimmed title and the body;
|
||||
- Reply fires it with OpReply, the ThreadID and the body;
|
||||
- EditPost (lifecycle.go) fires it with OpUpdate, the PostID, its ThreadID and the body.
|
||||
- api/errors.go `writeForumError`: before the switch, `errors.As(err, &rej)` writes 422 `{rej.Field: [rej.Message]}`, with field "body" when Field is empty.
|
||||
- saving_smoke_test.go `TestPostSavingTracer` (Docker): boot through bootWeb with the fixture resolver that allows posting; register a PostSaving listener rejecting Title or Body containing "blocked" (Field "title" or "body"). Then:
|
||||
- POST a thread whose title holds the word: 422 errors.title, no thread and no post row;
|
||||
- a clean thread: 201;
|
||||
- a reply whose body holds the word: 422 errors.body;
|
||||
- PUT the first post with the word: 422, and content_html is unchanged.
|
||||
- README: add Features "Pre-save seam" and the API reference rows (events.PostSaving, PostSavingEventName, Op constants, contracts.Rejection), and correct the Overview so it says forum fires only this pre-save event. Add a changelog line "v0.1.0: first tag; adds the pre-save PostSaving seam". Name no application.
|
||||
|
||||
Commit in ../sm-forum-plugin by path (`feat: pre-save PostSaving event and Rejection`). Do not push or tag.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-forum-plugin vet ./... && go -C ../sm-forum-plugin test -count=1 -short ./... && go -C ../sm-forum-plugin test -count=1 -run '^TestPostSavingTracer$' -v . 2>&1 | grep -q -- '^--- PASS: TestPostSavingTracer'</automated>
|
||||
<fails_when>Non-zero exit: vet or the short suite red, or no "--- PASS: TestPostSavingTracer" line (skipped without Docker, a refused write that still stored a row, or the wrong 422 field).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `go -C ../sm-forum-plugin test -count=1 ./...` passes with Docker, php_method_map_test.go and golden_test.go unedited (`git -C ../sm-forum-plugin diff HEAD~1 --stat -- php_method_map_test.go golden_test.go` prints nothing).
|
||||
- `grep -rn 'sm-chat-plugin' ../sm-forum-plugin/go.mod ../sm-forum-plugin/events ../sm-forum-plugin/contracts` prints nothing.
|
||||
- `grep -c 'PostSaving{' ../sm-forum-plugin/classes/forum_service.go` prints 2 and `grep -c 'PostSaving{' ../sm-forum-plugin/classes/lifecycle.go` prints 1.
|
||||
</acceptance_criteria>
|
||||
<done>Forum threads, replies and edits can be refused before render and storage with the existing 422 envelope; without a listener nothing changes.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: New shared plugin sm-moderation-plugin: banned words and links, editable in admin settings, published as a Filter</name>
|
||||
<files>../sm-moderation-plugin/.gitignore, ../sm-moderation-plugin/go.mod, ../sm-moderation-plugin/go.sum, ../sm-moderation-plugin/go.work, ../sm-moderation-plugin/plugin.go, ../sm-moderation-plugin/admin.go, ../sm-moderation-plugin/admin_permissions.go, ../sm-moderation-plugin/logger.go, ../sm-moderation-plugin/classes/filter.go, ../sm-moderation-plugin/classes/filter_smoke_test.go, ../sm-moderation-plugin/models/settings.go, ../sm-moderation-plugin/models/registry.go, ../sm-moderation-plugin/models/settings/fields.yaml, ../sm-moderation-plugin/updates/202610280001_create_golem15_moderation_settings.go, ../sm-moderation-plugin/updates/registry.go, ../sm-moderation-plugin/lang/en/lang.yaml, ../sm-moderation-plugin/lang/pl/lang.yaml, ../sm-moderation-plugin/config/config.yaml, ../sm-moderation-plugin/README.md</files>
|
||||
<read_first>../sm-sitemap-plugin/plugin.go, admin.go, admin_permissions.go, logger.go, models/settings.go, models/registry.go, models/settings/fields.yaml, updates/202610110002_create_golem15_sitemap_settings.go, updates/registry.go, lang/en/lang.yaml, config/config.yaml, go.mod, go.work, README.md (the whole plugin layout), modules/phrasebook/README.md and modules/towel/README.md (locale lookup), `summer help make:plugin` (scaffold option), .planning/notes/core-plugins-own-repos.md, 20-PATTERNS.md (sm-moderation-plugin)</read_first>
|
||||
<action>Per D-17. Create the repository at /media/nvme/dev/golem15/summercms.io/summercms/sm-moderation-plugin with `git init -b main`. Add no remote yet. Start from `summer make:plugin golem15.moderation` if it emits a standalone module layout, otherwise copy the sitemap layout. Module `git.golem15.com/golem15/sm-moderation-plugin`, package `moderation`, plugin ID `golem15.moderation`, `Requires()` nil, display name Moderation / Moderacja. Standard library plus gorm, gormigrate and framework modules only.
|
||||
|
||||
- go.mod: go 1.27.0, require `git.golem15.com/golem15/summercms v0.5.1` plus gorm and gormigrate at the versions sitemap's go.mod uses, and `replace git.golem15.com/golem15/summercms => ../summercms.go`. Run `go mod tidy`. Track a go.work with `use .` and the same replace, as sitemap does.
|
||||
- plugin.go: the interface assertions (party.Plugin, pact.HasConfig, pact.HasMigrations, pact.HasModels) and `//go:embed config`. Register keeps the app. Boot calls lagoon.OnDatabase and publishes `classes.NewFilter(db)` with `app.Publish`. The package doc says the plugin is a content filter other plugins' hosts wire into their pre-save seams, and that it imports no content plugin.
|
||||
- config/config.yaml: `max_entries: 500`, `max_entry_length: 200`.
|
||||
- models/settings.go: `Settings` singleton on `golem15_moderation_settings` (`ID uint`, `Enabled bool`, `BannedWords *string`, `BannedLinks *string`). `BeforeValidate` refuses:
|
||||
- a list longer than max_entries (lang key `golem15.moderation::lang.errors.too_many`);
|
||||
- an entry longer than max_entry_length (`errors.too_long`);
|
||||
- a link entry that is neither a host name nor an http(s) URL (`errors.link`).
|
||||
models/registry.go `All()`.
|
||||
- models/settings/fields.yaml: `enabled` (switch), `banned_words` (textarea, comment "one word or phrase per line"), `banned_links` (textarea, comment "one domain or URL per line; subdomains match"), with the sitemap header comment block.
|
||||
- updates/202610280001_create_golem15_moderation_settings.go: `CREATE TABLE IF NOT EXISTS golem15_moderation_settings (id INTEGER PRIMARY KEY, enabled BOOLEAN NOT NULL DEFAULT TRUE, banned_words TEXT NULL, banned_links TEXT NULL)` and `INSERT INTO golem15_moderation_settings (id) VALUES (1) ON CONFLICT (id) DO NOTHING`. Rollback drops the table. updates/registry.go `All()`.
|
||||
- admin.go: `Settings()` returns item Code `moderation_settings` (lang keys for label, description and category, Icon "shield", Permissions [`golem15.moderation.manage_settings`], Form `models/settings/fields.yaml`, NewModel), plus AdminFS and LangFS, with the sitemap assertions (AdminAssets, HasSettings, HasLang). admin_permissions.go declares the permission on the role list sitemap uses.
|
||||
- lang/en and lang/pl: plugin name, settings label, description and category, field labels and comments, `errors.*`, `violation.word` ("The text contains a word that is not allowed." / "Tekst zawiera niedozwolone słowo.") and `violation.link` ("The text contains a link that is not allowed." / "Tekst zawiera niedozwolony link.").
|
||||
- classes/filter.go:
|
||||
- `KindWord = "word"`, `KindLink = "link"`; `Violation{Kind, Match, Message string}`;
|
||||
- `ParseList(text string) []string` splits lines, trims them, lowercases them and drops empty lines and duplicates;
|
||||
- `Match(words, links []string, text string) *Violation` is pure and returns the first violation, words before links:
|
||||
- a word or phrase matches case-insensitively between non-letter, non-digit boundaries (built from `[^\p{L}\p{N}_]`, start or end of text) with regexp.QuoteMeta;
|
||||
- a link entry that is a host (example.com) matches any host in the text equal to it or ending in "." plus it: http(s) URLs, `www.` prefixes and bare domains (labels of letters, digits and hyphens with at least one dot);
|
||||
- an entry with a path matches a URL whose host and path start with it.
|
||||
- `NewFilter(db) *Filter`. `(*Filter).Check(ctx, text) (*Violation, error)` reads the singleton row, returns nil when Enabled is false, recompiles the matchers only when the stored text differs from the cached text (guard the cache with a sync.Mutex), and fills Message from the lang phrase for `towel.Locale(ctx)` through the framework phrasebook, falling back to the English text.
|
||||
- classes/filter_smoke_test.go `TestFilterSmoke` (pure, no Docker): "Spam here" against the word spam gives a word violation; "spamming" gives none; "Kup TANIO teraz" against the phrase "kup tanio" gives a word violation; "visit https://www.bad.example/x" and "bad.example" against the link bad.example give link violations; "good.example" gives none.
|
||||
- README.md in the standard plugin structure:
|
||||
- H1, one-sentence summary, import line, a `**Name:**` beach mnemonic, Overview, Features, Usage, API reference, Configuration (the two keys), Dependencies, Testing;
|
||||
- Usage shows a neutral host (`acme`) wiring Check into another plugin's pre-save event without importing it here.
|
||||
|
||||
Commit in ../sm-moderation-plugin (`feat: golem15.moderation banned word and link filter`). Do not create a remote, push or tag.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-moderation-plugin vet ./... && go -C ../sm-moderation-plugin test -count=1 -short ./... && go -C ../sm-moderation-plugin test -count=1 -run '^TestFilterSmoke$' -v ./classes 2>&1 | grep -q -- '^--- PASS: TestFilterSmoke'</automated>
|
||||
<fails_when>Non-zero exit: the module does not build or vet, the short suite fails, or no "--- PASS: TestFilterSmoke" line (a boundary or host rule wrong).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `go -C ../sm-moderation-plugin list -deps ./... | grep -cE 'sm-(chat|forum)-plugin'` prints 0.
|
||||
- `grep -c 'golem15_moderation_settings' ../sm-moderation-plugin/updates/202610280001_create_golem15_moderation_settings.go` prints at least 2.
|
||||
- `grep -c 'golem15.moderation.manage_settings' ../sm-moderation-plugin/admin_permissions.go` prints at least 1.
|
||||
- `grep -c '^\*\*Name:\*\*' ../sm-moderation-plugin/README.md` prints 1.
|
||||
- `git -C ../sm-moderation-plugin remote` prints nothing.
|
||||
</acceptance_criteria>
|
||||
<done>A shared, chat-agnostic moderation plugin exists locally: admins edit banned words and links in settings, and any host can call Filter.Check from a pre-save seam.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Module-mode hygiene: chatvideo, herald and userfriends require tags, and the whole family builds and tests</name>
|
||||
<files>../sm-chatvideo-plugin/go.mod, ../sm-chatvideo-plugin/go.sum, ../sm-chatvideo-plugin/README.md, ../sm-herald-plugin/go.mod, ../sm-herald-plugin/go.sum, ../sm-herald-plugin/README.md, ../sm-userfriends-plugin/go.mod, ../sm-userfriends-plugin/go.sum, ../sm-userfriends-plugin/README.md</files>
|
||||
<read_first>../sm-chatvideo-plugin/go.mod and go.work, ../sm-herald-plugin/go.mod and go.work, ../sm-userfriends-plugin/go.mod and go.work, ../sm-chatchannels-plugin/go.mod and ../sm-chatbots-plugin/go.mod (after the Task 1 fast-forward), ../sm-bm-app/plugins/golem15/chatbots/go.mod (the "drop sibling replaces" analog), each README's Dependencies section, 20-RESEARCH.md (Repo State and Tagging, Pitfall 2)</read_first>
|
||||
<action>Per SC-1 and RESEARCH Pitfall 2. With `GOWORK=off GOPRIVATE=git.golem15.com/*`, edit each go.mod:
|
||||
- sm-chatvideo-plugin: delete the sm-chat-plugin and sm-user-plugin replace lines. Require `git.golem15.com/golem15/sm-chat-plugin v0.1.3`, `sm-user-plugin v0.1.13` and `summercms v0.5.1`. Keep `replace git.golem15.com/golem15/summercms => ../summercms.go`.
|
||||
- sm-herald-plugin: delete the sm-user-plugin replace. Require sm-user-plugin v0.1.13 and summercms v0.5.1.
|
||||
- sm-userfriends-plugin: replace the chat pseudo-version with v0.1.3. Require sm-user-plugin v0.1.13 and summercms v0.5.1.
|
||||
- sm-chatchannels-plugin and sm-chatbots-plugin (fast-forwarded in Task 1): confirm their go.mod holds no replace other than the framework one and only tag requires. If either does not, fix it the same way and add it to this task's commits.
|
||||
Run `go mod tidy` in each changed repo (GOWORK=off). The tracked go.work files stay: they are development conveniences and module consumers ignore them. Update each changed README's Dependencies section with the required versions and add a changelog line "v0.1.0: first tag; requires tagged chat, user and SummerCMS modules" where the README keeps a changelog.
|
||||
|
||||
Then verify the family:
|
||||
- all eight repos (chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, moderation) pass `go vet ./...` and `go test -count=1 -short ./...` through their go.work;
|
||||
- chatchannels, chatbots, chatvideo, herald and userfriends pass `GOWORK=off go build ./...`, which resolves chat v0.1.3 and user v0.1.13 from git.golem15.com and proves no sibling path is needed.
|
||||
Grep the changed files of all eight repos for consuming application names (the sm-*-app repository names next to summercms.go, and their vendor prefixes) and remove any hit in the files this plan changed.
|
||||
|
||||
Commit per repo by path (`chore: require tagged chat, user and SummerCMS modules; drop sibling replaces`). Do not push or tag.</action>
|
||||
<verify>
|
||||
<automated>for r in sm-chat-plugin sm-chatchannels-plugin sm-chatbots-plugin sm-chatvideo-plugin sm-forum-plugin sm-herald-plugin sm-userfriends-plugin sm-moderation-plugin; do go -C ../$r vet ./... && go -C ../$r test -count=1 -short ./... || exit 1; done && for r in sm-chatchannels-plugin sm-chatbots-plugin sm-chatvideo-plugin sm-herald-plugin sm-userfriends-plugin; do GOWORK=off GOPRIVATE='git.golem15.com/*' go -C ../$r build ./... || exit 1; done</automated>
|
||||
<fails_when>Non-zero exit: any repo fails vet or its short suite, or a GOWORK=off build fails (for example "unknown revision v0.0.0" or a sibling replace path that no longer resolves).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -cE '^replace .*=> \.\./(sm-|fonoteka)' ../sm-chatvideo-plugin/go.mod ../sm-herald-plugin/go.mod ../sm-userfriends-plugin/go.mod` prints 0 for each file.
|
||||
- `grep -c 'v0.0.0' ../sm-chatvideo-plugin/go.mod ../sm-userfriends-plugin/go.mod` prints 0 for each file.
|
||||
- `grep -c 'sm-chat-plugin v0.1.3' ../sm-chatvideo-plugin/go.mod ../sm-userfriends-plugin/go.mod` prints 1 for each file.
|
||||
- `git -C ../sm-<repo> status --porcelain` prints nothing for all eight repos after the commits.
|
||||
</acceptance_criteria>
|
||||
<done>Every chat-family module resolves its dependencies by tag, so a demo build without go.work can require them.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 5: Go-ahead for the one-way release: create sm-moderation-plugin on git.golem15.com, push eight repositories and tag them</name>
|
||||
<read_first>The release table Claude prints before asking, one row per repository: current remote tags (`git ls-remote --tags origin`), the next free tag, the commit it will sit on, the commits it adds since the last tag, and why (seam, first tag, go.mod fix, new repo). Also whether `tea login list` shows a git.golem15.com login, and the visibility of sm-sitemap-plugin.</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user chose one option and it is recorded in the SUMMARY. With "release", git.golem15.com/golem15/sm-moderation-plugin exists (`git ls-remote git@git.golem15.com:golem15/sm-moderation-plugin.git` exits 0) before Task 6 pushes.
|
||||
</acceptance_criteria>
|
||||
<decision>Create the sm-moderation-plugin repository, push the commits of this plan and set the eight tags now?</decision>
|
||||
<context>A pushed Go module tag is cached by module proxies and can never point anywhere else (one-way, as 19.4.1 D-03). Tags freeze exactly the commits Tasks 1-4 verified. chat v0.1.4 is a patch: the seam is additive and WavePath's parity tests stay green (D-18). Plan 02 cannot mount the chat family by tag until this runs. Creating a repository on git.golem15.com and pushing need your go-ahead (CLAUDE.md).</context>
|
||||
<options>
|
||||
<option id="release">
|
||||
<name>Create the repository, push and tag</name>
|
||||
<pros>Plan 02 can mount all eight plugins by tag; other applications can adopt the seams and the filter.</pros>
|
||||
<cons>The tags are permanent; a mistake needs a new patch tag, not a moved tag.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>Nothing permanent happens.</pros>
|
||||
<cons>Plan 02 and every later plan are blocked; the demo cannot require the chat family.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<instructions>For "release": if Claude reported no tea login for git.golem15.com, create the repository golem15/sm-moderation-plugin (empty, same visibility as sm-sitemap-plugin, default branch main) in the git.golem15.com web UI first, then reply. Do not paste tokens into the chat.</instructions>
|
||||
<resume-signal>Reply "release" (add "repo ready" if you created the repository yourself) or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 6: Release: push, tag and prove the eight tags resolve in module mode</name>
|
||||
<reversibility rating="one-way">Pushed module tags are cached by proxies and every consumer's go.sum; they can only be superseded, never moved.</reversibility>
|
||||
<precondition>Task 5 resolved with "release"; `git ls-remote git@git.golem15.com:golem15/sm-moderation-plugin.git` exits 0 or `tea login list` lists git.golem15.com.</precondition>
|
||||
<files>../sm-moderation-plugin/README.md</files>
|
||||
<read_first>The Task 5 release table, each repository's README changelog, .planning/notes/core-plugins-own-repos.md</read_first>
|
||||
<action>Per SC-1 and D-17/D-18.
|
||||
1. If the repository does not exist yet, create it with `tea repo create --name sm-moderation-plugin --owner golem15` at sm-sitemap-plugin's visibility. Then `git -C ../sm-moderation-plugin remote add origin git@git.golem15.com:golem15/sm-moderation-plugin.git` and push main with upstream.
|
||||
2. Push the default branch of chat, forum, chatvideo, herald and userfriends (and chatchannels or chatbots only if Task 4 committed there). No force-push.
|
||||
3. Read the next free tag from `git ls-remote --tags origin` per repository: chat the next v0.1.x patch (v0.1.4 expected), the others v0.1.0 unless taken. Create annotated tags (`git tag -a <tag> -m "<one-line summary>"`) on the HEADs Tasks 1-4 verified, chat first. Push each tag. Confirm `git ls-remote origin refs/tags/<tag>^{}` equals the local HEAD.
|
||||
4. If the moderation README says no tag exists yet, fix it in a commit before tagging that repository, never after.
|
||||
5. Module-mode proof: in a fresh `mktemp -d` directory, `go mod init example.invalid/familycheck`, require all eight modules at their new tags plus `git.golem15.com/golem15/summercms v0.5.1`, write a main.go that blank-imports the eight plugin packages, then run `GOWORK=off GOPRIVATE=git.golem15.com/* GOFLAGS=-mod=mod go build ./...`. Delete the directory afterwards. The SUMMARY records every tag with its commit hash for plan 02.</action>
|
||||
<verify>
|
||||
<automated>for r in sm-chat-plugin sm-chatchannels-plugin sm-chatbots-plugin sm-chatvideo-plugin sm-forum-plugin sm-herald-plugin sm-userfriends-plugin sm-moderation-plugin; do t=$(git -C ../$r describe --tags --exact-match HEAD) && [ "$(git -C ../$r ls-remote origin "refs/tags/$t^{}" | cut -f1)" = "$(git -C ../$r rev-parse HEAD)" ] || exit 1; done</automated>
|
||||
<fails_when>Non-zero exit: a repository HEAD carries no tag (describe fails), or the remote tag is missing or points at a different commit than the local HEAD.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../sm-chat-plugin describe --tags --exact-match HEAD` prints a v0.1.x tag at least v0.1.4.
|
||||
- The scratch module build printed no error, and the SUMMARY lists the eight tags with commit hashes.
|
||||
- `git -C ../sm-<repo> status --porcelain` prints nothing in all eight repositories.
|
||||
</acceptance_criteria>
|
||||
<done>All eight chat-family modules are on git.golem15.com at verified tags and resolve together without go.work.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| chat/forum HTTP clients to the plugin APIs | message and post bodies are untrusted input; the seam runs on them before storage |
|
||||
| host listeners to plugin services | host code decides refusals; a listener error must not leak internals |
|
||||
| admin settings to the filter | administrators edit the lists that every message is matched against |
|
||||
| build machine to git.golem15.com and module proxies | tags become immutable inputs of every consumer |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-01 | Tampering | chat write paths that skip the seam | high | mitigate | MessageSaving fires in SendMessageWith (SendMessage, replies and ReplyTo funnel into it) and EditMessage; TestMessageSavingTracer covers send, reply and edit; plan 06 adds the full matrix |
|
||||
| T-20-02 | Information disclosure | listener errors surfacing in API bodies | medium | mitigate | only contracts.Rejection maps to 422 with its own Field and Message; any other listener error keeps the existing opaque 500 path of writeChatError and writeForumError |
|
||||
| T-20-03 | Denial of service | filter matching cost | medium | mitigate | RE2 linear-time regexps from QuoteMeta'd entries; at most 500 entries of at most 200 characters per list (BeforeValidate); matchers compiled once per list version |
|
||||
| T-20-04 | Elevation of privilege | moderation settings screen | medium | mitigate | settings item behind the permission golem15.moderation.manage_settings, granted to the same role as sitemap settings |
|
||||
| T-20-05 | Tampering | one-way module tags | medium | mitigate | tags only on HEADs that passed vet and tests in Tasks 1-4; next free number read from the remote; go-ahead at Task 5; ls-remote check and a GOWORK=off scratch build after pushing |
|
||||
| T-20-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package-manager install: Go modules are the project's own tagged repositories plus gorm and gormigrate at versions already in sm-sitemap-plugin's go.sum (GOPRIVATE, go.sum committed) |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: chat seam tracer green, chat parity tests unchanged, seven siblings at origin HEAD.
|
||||
- Task 2: forum seam tracer green, forum parity tests unchanged.
|
||||
- Task 3: moderation plugin builds, filter smoke green, no dependency on chat or forum.
|
||||
- Task 4: all eight repositories vet and test; five chat dependants build with GOWORK=off.
|
||||
- Task 5: go-ahead recorded.
|
||||
- Task 6: eight tags on origin equal to the verified HEADs; the scratch module builds them together.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
The chat family and the moderation plugin are released by tag (SC-1 prerequisite), with the D-18 seams additive and parity-safe and the D-17 filter shared and chat-agnostic.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-01-SUMMARY.md` when done: per repository the before and after HEAD, the tag and its commit, the go.mod changes, how the moderation repository was created, and the checkpoint answer.
|
||||
</output>
|
||||
@@ -0,0 +1,214 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 01
|
||||
subsystem: plugins
|
||||
tags: [chat, forum, moderation, go-modules, release, gitea]
|
||||
|
||||
requires:
|
||||
- phase: 19.4.1-early-public-demo-on-demo-summercms-io
|
||||
provides: live demo instance the chat family is added to
|
||||
- phase: 34
|
||||
provides: summercms v0.6.0 framework tag the family requires
|
||||
provides:
|
||||
- "sm-chat-plugin v0.1.5: events.MessageSaving pre-save event + contracts.Rejection (422 on refusal)"
|
||||
- "sm-forum-plugin v0.1.1: events.PostSaving pre-save event + contracts.Rejection (422 on refusal)"
|
||||
- "sm-moderation-plugin v0.1.0 (new public repo): golem15.moderation, *classes.Filter for banned words and links, admin settings screen"
|
||||
- "sm-chatvideo-plugin, sm-herald-plugin, sm-userfriends-plugin v0.1.1: go.mod on tagged chat/user/summercms, framework replace only"
|
||||
- "Eight chat-family module tags that resolve together with GOWORK=off against summercms v0.6.0"
|
||||
affects: [20-02, 20-03, 20-04, 20-05, 20-06, sm-demo-app]
|
||||
|
||||
actuals:
|
||||
tokens: 32150 # chars/4 over the realized diffs in the six changed sibling repos
|
||||
tasks: 6
|
||||
commits: 7 # measured: git rev-list over the sibling repos (chat 2, forum 1, moderation 1, chatvideo 1, herald 1, userfriends 1); summercms.go had 0 code commits
|
||||
plan_head_before: 677e30f6f53e9eab79d6cadd46b8b6e2843f5c61 # summercms.go; multi-repo plan, per-repo bases listed in the body
|
||||
plan_head_after: 677e30f6f53e9eab79d6cadd46b8b6e2843f5c61 # summercms.go before this SUMMARY commit
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Pre-save veto event: plugin fires <Thing>Saving on the bus before the transaction; a listener returning contracts.Rejection{Field, Message} maps to the existing 422 validation envelope, any other error keeps the opaque 500 path"
|
||||
- "Shared filter published as a typed service (app.Publish(*classes.Filter)) that consumers look up; the filter plugin imports none of its consumers"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../sm-moderation-plugin/plugin.go
|
||||
- ../sm-moderation-plugin/classes/filter.go
|
||||
- ../sm-moderation-plugin/models/settings.go
|
||||
- ../sm-moderation-plugin/admin.go
|
||||
- ../sm-chat-plugin/contracts/rejection.go
|
||||
- ../sm-forum-plugin/contracts/rejection.go
|
||||
modified:
|
||||
- ../sm-chat-plugin/events/events.go
|
||||
- ../sm-chat-plugin/classes/service.go
|
||||
- ../sm-chat-plugin/api/errors.go
|
||||
- ../sm-forum-plugin/events/events.go
|
||||
- ../sm-forum-plugin/classes/forum_service.go
|
||||
- ../sm-forum-plugin/api/errors.go
|
||||
- ../sm-chatvideo-plugin/go.mod
|
||||
- ../sm-herald-plugin/go.mod
|
||||
- ../sm-userfriends-plugin/go.mod
|
||||
|
||||
key-decisions:
|
||||
- "Task 5 checkpoint answered \"release\" by the user (2026-10-30): create sm-moderation-plugin, push and tag"
|
||||
- "Tag numbers moved up one because the marketplace manifest commits had already tagged chat v0.1.4 and the others v0.1.0; chat v0.1.5, forum/chatvideo/herald/userfriends v0.1.1, moderation v0.1.0"
|
||||
- "The family requires summercms v0.6.0, not the planned v0.5.1"
|
||||
- "sm-moderation-plugin is public, like sm-sitemap-plugin, default branch main"
|
||||
|
||||
patterns-established:
|
||||
- "Pre-save veto seam: events.<Thing>Saving + contracts.Rejection, additive and parity-safe"
|
||||
|
||||
requirements-completed: [SC-1, D-17, D-18, D-19, D-20]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Chat MessageSaving seam: a Rejection from a listener answers 422 on send, reply and edit, with no row written and no event or publish"
|
||||
requirement: "D-18"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-chat-plugin/saving_smoke_test.go#TestMessageSavingTracer"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "Forum PostSaving seam: CreateThread, Reply and EditPost fire PostSaving before render; a Rejection maps to 422 under title or body"
|
||||
requirement: "D-18"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-forum-plugin/saving_smoke_test.go"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "golem15.moderation Filter flags banned words and phrases (Unicode boundaries, Polish letters) and banned links (domain, subdomains, URL prefixes), nil for clean text"
|
||||
requirement: "D-17"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../sm-moderation-plugin/classes/filter_smoke_test.go#TestFilterSmoke"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "Eight chat-family tags pushed to git.golem15.com on the verified HEADs and resolving together in module mode"
|
||||
requirement: "SC-1"
|
||||
verification:
|
||||
- kind: other
|
||||
ref: "Task 6 verify loop: git describe --tags --exact-match HEAD == ls-remote refs/tags/<tag>^{} for all eight repos (exit 0)"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "scratch module, GOWORK=off GOPRIVATE='git.golem15.com/*' GOFLAGS=-mod=mod go build ./... (exit 0)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: 3min (Task 6 continuation; Tasks 1-5 ran in earlier sessions)
|
||||
completed: 2026-10-30
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 20 Plan 01: Chat Family Release Summary
|
||||
|
||||
**Chat and forum gained additive pre-save veto events (MessageSaving, PostSaving with contracts.Rejection → 422). The new shared golem15.moderation plugin publishes a banned word and link filter. All eight chat-family modules are tagged on git.golem15.com and build together with GOWORK=off against summercms v0.6.0.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** about 3 min for the Task 6 continuation (17:22–17:25 UTC); Tasks 1-5 ran in earlier sessions
|
||||
- **Started (continuation):** 2026-10-30T17:22:07Z
|
||||
- **Completed:** 2026-10-30T17:25Z
|
||||
- **Tasks:** 6/6 (Task 5 was the go-ahead decision)
|
||||
- **Files modified:** 45 across six sibling repos (chat 7, forum 7, chatvideo 3, herald 3, userfriends 4, moderation 21 new)
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- `sm-chat-plugin` v0.1.5: `events.MessageSaving` fires in `SendMessageWith` (send, reply, ReplyTo) and `EditMessage` before the transaction. `writeChatError` maps a `contracts.Rejection` to the existing 422 `{"error":"Validation failed","errors":{field:[msg]}}`. With no listener the behaviour is unchanged, and the parity and golden tests pass without edits.
|
||||
- `sm-forum-plugin` v0.1.1: `events.PostSaving` fires in `CreateThread`, `Reply` and `EditPost` before `breakwater.Render`. A Rejection lands under `errors.title` or `errors.body`.
|
||||
- `sm-moderation-plugin` v0.1.0 (new repo): `golem15.moderation` publishes `*classes.Filter` at boot. The lists come from the `banned_words` and `banned_links` textareas on its settings screen (singleton `golem15_moderation_settings`, permission `golem15.moderation.manage_settings`). It imports neither chat nor forum.
|
||||
- chatvideo, herald and userfriends v0.1.1: each go.mod now keeps only the framework replace and requires tagged chat/user/summercms modules.
|
||||
- Module-mode proof: a scratch module that requires the eight tags and summercms v0.6.0 and blank-imports all eight plugin packages built with `GOWORK=off`. It resolved sm-user-plugin v0.1.13 transitively.
|
||||
|
||||
## Release table (for plan 02)
|
||||
|
||||
| Repo | Before HEAD (origin) | After HEAD | Tag | Tag commit | Why |
|
||||
|------|----------------------|------------|-----|------------|-----|
|
||||
| sm-chat-plugin | db3b518 | 6275ae4 | v0.1.5 | 6275ae4c7cd80fdc5b0c07466ba65ca63b518503 | MessageSaving seam (patch) |
|
||||
| sm-chatchannels-plugin | 017843a | 017843a | v0.1.0 (existing) | 017843a | no new commits, not pushed or re-tagged |
|
||||
| sm-chatbots-plugin | 24eadf6 | 24eadf6 | v0.1.0 (existing) | 24eadf6 | no new commits, not pushed or re-tagged |
|
||||
| sm-chatvideo-plugin | 33ff4f5 | 0f08c35 | v0.1.1 | 0f08c35380d7505d591cef96ac80ef8d7649e70e | go.mod hygiene |
|
||||
| sm-forum-plugin | 36bd875 | 4e8a3c3 | v0.1.1 | 4e8a3c35e20698eaf8603ce68410ce7f02bc2674 | PostSaving seam |
|
||||
| sm-herald-plugin | db8a1bb | 82f070a | v0.1.1 | 82f070ac89dbd1a081aee282f121f1e186a65465 | go.mod hygiene |
|
||||
| sm-userfriends-plugin | 2f29b26 | 1c28db8 | v0.1.1 | 1c28db8a08a819290591a4e0365a751ebf8c913f | go.mod hygiene + plugin.yaml |
|
||||
| sm-moderation-plugin | (new) | d9791e2 | v0.1.0 | d9791e2ea53bcb7abbfbca65cfc79d817ad5f33b | first release |
|
||||
|
||||
All tags are annotated. Each was pushed separately, and `git ls-remote origin refs/tags/<tag>^{}` equals the local HEAD in every repo. All branch pushes were fast-forwards with no force. All eight working trees are clean.
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: chat MessageSaving seam**: `42f64eb` (feat), plus `6275ae4` (chore: no host application named in the CanDeleteMessage comment), in sm-chat-plugin
|
||||
2. **Task 2: forum PostSaving seam**: `4e8a3c3` (feat), sm-forum-plugin
|
||||
3. **Task 3: golem15.moderation plugin**: `d9791e2` (feat), sm-moderation-plugin
|
||||
4. **Task 4: go.mod hygiene**: sm-chatvideo-plugin `0f08c35`, sm-herald-plugin `82f070a`, sm-userfriends-plugin `1c28db8` (chore)
|
||||
5. **Task 5: go-ahead**: the user answered **"release"**
|
||||
6. **Task 6: release**: no code commit; repo created, five branches and moderation main pushed, six tags pushed, module-mode build proven
|
||||
|
||||
## go.mod changes (Task 4)
|
||||
|
||||
- **sm-chatvideo-plugin:** dropped `replace sm-chat-plugin => ../sm-chat-plugin` and `replace sm-user-plugin => ../fonoteka.go/plugins/golem15/user`; sm-user-plugin v0.1.2 → v0.1.13; keeps sm-chat-plugin v0.1.3 and summercms v0.6.0.
|
||||
- **sm-herald-plugin:** dropped `replace sm-user-plugin => ../fonoteka.go/plugins/golem15/user`; sm-user-plugin v0.1.1 → v0.1.13; summercms v0.6.0.
|
||||
- **sm-userfriends-plugin:** sm-chat-plugin pseudo-version `v0.0.0-20261017200243-4d0e764ca443` → v0.1.3; sm-user-plugin v0.1.1 → v0.1.13; summercms v0.6.0.
|
||||
- **sm-moderation-plugin:** requires summercms v0.6.0.
|
||||
- Every one of them keeps only `replace git.golem15.com/golem15/summercms => ../summercms.go`.
|
||||
|
||||
## How the moderation repository was created
|
||||
|
||||
`tea login list` showed a git.golem15.com login (user jakub). The API reported sm-sitemap-plugin as `"private":false`, default branch `main`. The repo was created with `tea repo create --login git.golem15.com --name sm-moderation-plugin --owner golem15` as a public repo (no `--private`), and the API confirmed `private:false`, `default_branch:main`. Then `git -C ../sm-moderation-plugin remote add origin git@git.golem15.com:golem15/sm-moderation-plugin.git` and `git push -u origin main`. `git ls-remote git@git.golem15.com:golem15/sm-moderation-plugin.git` exits 0 and shows d9791e2 on `refs/heads/main`. The local repo had been created in Task 3 with `git init -b main`.
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- Checkpoint answer: **"release"** (user, 2026-10-30).
|
||||
- The family requires summercms v0.6.0, the current framework tag, instead of the v0.5.1 the plan named.
|
||||
- chatchannels and chatbots keep their existing v0.1.0 tags on HEAD. They had no new commits, so they were neither pushed nor re-tagged.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
1. **Tag numbers moved up one.** Another session's marketplace manifest commits had already tagged sm-chat-plugin v0.1.4 and the other repos v0.1.0. The new tags are therefore chat v0.1.5 and forum/chatvideo/herald/userfriends v0.1.1. Moderation is v0.1.0 as planned, and chatchannels and chatbots stay on their existing v0.1.0. The tags were read from `git ls-remote --tags origin` immediately before tagging.
|
||||
2. **summercms stays v0.6.0** in every go.mod and in the scratch proof, not v0.5.1.
|
||||
3. **[Rule 2] Moderation got `plugin.yaml` and `manifest_test.go`** (`TestPluginManifest`), so the plugin matches the marketplace manifest convention that landed during the plan.
|
||||
4. **[Rule 3] userfriends `plugin.yaml` regenerated** because the go.mod change made the manifest check fail (commit 1c28db8).
|
||||
5. **No changelog lines for chatvideo, herald and userfriends.** Their READMEs have no changelog section.
|
||||
6. **App names removed** from a chat comment (`6275ae4`) and from the chat README, per the "framework code never names a consuming application" rule.
|
||||
7. **Added `(*Filter).SetTranslator`** to the moderation filter, so violation messages are localised through the host's translator.
|
||||
8. **Extra moderation exports** beyond the plan's list: `models.SetLimits`, `models.Limits`, `models.Lines`, `models.LinkEntry`, `models.ValidHost`, `models.DefaultSettings`, `models.Text`; root `PluginID`, `ConfigMaxEntries`, `ConfigMaxEntryLength`, `PermissionManageSettings`.
|
||||
9. **Task 4 acceptance check `grep -c v0.0.0` fails as written.** It matches only third-party `// indirect` pseudo-versions. No golem15 module is on a pseudo-version any more.
|
||||
|
||||
**Total deviations:** 9 (2 auto-fixed under Rules 2/3, the rest are renumbering, scope notes and documentation)
|
||||
**Impact on plan:** None on the goal. The seams stay additive, and plan 02 can mount all eight by tag.
|
||||
|
||||
## Follow-ups left alone (out of scope)
|
||||
|
||||
- The tracked `go.work` files in the sibling repos still point at `../fonoteka.go/plugins/golem15/user`. They only affect workspace builds, not module mode.
|
||||
- The forum and herald READMEs still say "v0.4.0 modules" in their Dependencies section.
|
||||
- `../sm-chat-plugin/classes/kind_test.go` is not gofmt'd. This predates the plan.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None in Task 6. Every push, tag push and ls-remote check succeeded on the first attempt. The proxy had not yet seen the new tags, and `GOPRIVATE='git.golem15.com/*'` made go fetch them directly.
|
||||
|
||||
## Threat notes
|
||||
|
||||
- T-20-03 (filter cost): one uncached `Match` at 2 lists × 500 entries × 200 characters takes about 36 ms, and the compiled matchers take about 8.8 KB. Matchers are compiled once per list version, so this cost is paid once per settings change, not per message.
|
||||
- T-20-05 (one-way tags): the tags sit on the HEADs that passed vet and tests in Tasks 1-4. They were confirmed free immediately before creation and verified on the remote afterwards.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Plan 02 can require the chat family by tag: chat v0.1.5, chatchannels v0.1.0, chatbots v0.1.0, chatvideo v0.1.1, forum v0.1.1, herald v0.1.1, userfriends v0.1.1, moderation v0.1.0, with summercms v0.6.0 and sm-user-plugin v0.1.13.
|
||||
- Plugin release posts on summercms.io/changelog/plugins for the six new tags are not written yet. Per CLAUDE.md, plugin tags get a post.
|
||||
|
||||
---
|
||||
*Phase: 20-demo-instance-with-every-shared-plugin*
|
||||
*Completed: 2026-10-30*
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- All eight repos: `git describe --tags --exact-match HEAD` matches `ls-remote refs/tags/<tag>^{}` (verify loop exit 0).
|
||||
- Commits 42f64eb, 6275ae4, 4e8a3c3, d9791e2, 0f08c35, 82f070a, 1c28db8 exist on origin/main of their repos.
|
||||
- `../sm-moderation-plugin/classes/filter.go`, `../sm-chat-plugin/contracts/rejection.go` and `../sm-forum-plugin/contracts/rejection.go` exist.
|
||||
@@ -0,0 +1,400 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: ["20-01"]
|
||||
files_modified:
|
||||
- ../sm-demo-app/.gitmodules
|
||||
- ../sm-demo-app/go.work
|
||||
- ../sm-demo-app/go.mod
|
||||
- ../sm-demo-app/go.sum
|
||||
- ../sm-demo-app/summer.yaml
|
||||
- ../sm-demo-app/plugins.gen.go
|
||||
- ../sm-demo-app/plugins/golem15/oauthserver
|
||||
- ../sm-demo-app/plugins/golem15/chat
|
||||
- ../sm-demo-app/plugins/golem15/chatchannels
|
||||
- ../sm-demo-app/plugins/golem15/chatbots
|
||||
- ../sm-demo-app/plugins/golem15/chatvideo
|
||||
- ../sm-demo-app/plugins/golem15/forum
|
||||
- ../sm-demo-app/plugins/golem15/herald
|
||||
- ../sm-demo-app/plugins/golem15/userfriends
|
||||
- ../sm-demo-app/plugins/golem15/moderation
|
||||
- ../sm-demo-app/config/golem15.chatvideo.yaml
|
||||
- ../sm-demo-app/plugins/demo/plugin.go
|
||||
- ../sm-demo-app/plugins/demo/config/config.yaml
|
||||
- ../sm-demo-app/plugins/demo/chat.go
|
||||
- ../sm-demo-app/plugins/demo/chat_api.go
|
||||
- ../sm-demo-app/plugins/demo/chatbots.go
|
||||
- ../sm-demo-app/plugins/demo/moderation.go
|
||||
- ../sm-demo-app/plugins/demo/realtime_access.go
|
||||
- ../sm-demo-app/plugins/demo/routes.go
|
||||
- ../sm-demo-app/plugins/demo/classes/chat_context.go
|
||||
- ../sm-demo-app/plugins/demo/classes/forum_access.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_chat.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_forum.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_friends.go
|
||||
- ../sm-demo-app/plugins/demo/console/reset.go
|
||||
- ../sm-demo-app/chat_smoke_test.go
|
||||
- ../sm-demo-app/boot_test.go
|
||||
- ../sm-demo-app/realtime_test.go
|
||||
- ../sm-demo-app/deploy/centrifugo.json.example
|
||||
- ../sm-demo-app/deploy/livekit.yaml.example
|
||||
- ../sm-demo-app/deploy/env.example
|
||||
- ../sm-demo-app/scripts/dev.sh
|
||||
- ../sm-demo-app/README.md
|
||||
- .planning/todos/pending/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md
|
||||
- .planning/todos/done/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md
|
||||
autonomous: true
|
||||
requirements: [SC-1, D-05, D-06, D-07, D-08, D-09, D-10, D-12, D-14, D-17, D-20, D-22, D-23]
|
||||
estimate:
|
||||
tokens: 320000
|
||||
raw_tokens: 320000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-1: sm-demo-app requires chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends and moderation at the plan 01 tags, mounts them as submodules at plugins/golem15/<name> checked out on those tags, lists them in summer.yaml before golem15.demo, and passes TestGoModRequiresTags, TestBootAllPlugins and scripts/check-pins.sh; scripts/build.sh dev builds."
|
||||
- "Folded todo: plugins/golem15/oauthserver sits on tag v0.1.3 (which contains b6a9586), go.mod requires sm-oauthserver-plugin v0.1.3, the change is one commit `chore: bump sm-oauthserver-plugin to v0.1.3`, and the todo file moves to .planning/todos/done with g15office task ssuyq2os set to Live."
|
||||
- "D-06: golem15.demo registers the chat context alias demo (id 1, broadcast chat:context:1) whose members are every activated, non-deleted, non-banned user, and the alias channel (chatchannels' ChannelAlias) that resolves a seeded channel's backing conversation to the same membership with broadcast chat:channel:{id}; both require live membership."
|
||||
- "D-07: channels exist only through demo:seed; the chatchannels access resolver answers CanManageContext false, so POST /_chatchannels/api/v1/contexts/demo/1/channels is refused for every member; a member can join and leave seeded channels and post in them."
|
||||
- "D-08: any member can open a DM with any other member through POST /_chat/api/v1/contexts/demo/1/dm; userfriends does not gate it."
|
||||
- "D-09: demo:seed creates persona users (no usable password) with EN and PL channel history, threads, reactions and pins, forum categories, threads and posts in EN and PL, friendships and a friend group, the demo-moderators user group and default moderation lists; a second run reports exists; demo:reset wipes every chat-family table in foreign-key order and reseeds, keeping golem15_moderation_settings and the userfriends context singleton."
|
||||
- "D-17: a banned word or link in a chat message (create, reply, edit) or a forum thread, reply or edit is refused with 422 through the demo's listeners on events.MessageSaving and events.PostSaving calling the published moderation Filter."
|
||||
- "D-22: members of the user group named by golem15.demo.chat.moderator_group (default demo-moderators) can delete other members' messages in channel conversations (CanModerateMessage) and manage forum posts (forum CanManage); the bootstrap reports moderator true for them; banning stays in the user admin."
|
||||
- "D-05: chatbots lists the demo's ephemeral slash commands in GET /_chatbots/api/v1/commands and POST /_chatbots/api/v1/dispatch answers them in ephemeral mode; there is no bot persona."
|
||||
- "D-12, D-23: config/golem15.chatvideo.yaml sets max_duration 900, max_participants 4, token_ttl 900 and screen_share false; the server does not restrict calls by conversation type (calls are limited to DMs by the UI, plan 04)."
|
||||
- "GET /_demo/api/v1/chat answers a member with {member, moderator, context, channels[], conversations[], limits} and GET /_demo/api/v1/chat/members with {members[]}; both need a JWT."
|
||||
- "GET /api/realtime/token answers 200 for any member (guard demo.realtime-access) and 401 without a JWT; Centrifugo's committed config has the namespaces presentations, chat, user and video with the subscribe proxy; scripts/dev.sh up starts a local LiveKit on 127.0.0.1:7890 (TCP 7891, UDP 7892) with keys written to .env only (D-10 locally)."
|
||||
- "D-14: the forum resolver lets every member read and post in context demo/1 and the seeded EN and PL categories are listed by GET /_forum/api/v1/contexts/demo/1/categories."
|
||||
artifacts:
|
||||
- path: "../sm-demo-app/plugins/demo/classes/chat_context.go"
|
||||
provides: "DemoContext, ChannelContext adapter, ChatAccess resolver, membership query"
|
||||
contains: "ChatContextType"
|
||||
- path: "../sm-demo-app/plugins/demo/chat.go"
|
||||
provides: "registerChat: registry aliases demo and channel, resolvers, limits"
|
||||
contains: "ChannelAlias"
|
||||
- path: "../sm-demo-app/plugins/demo/chat_api.go"
|
||||
provides: "GET /_demo/api/v1/chat and /chat/members (host bootstrap contract)"
|
||||
contains: "/chat/members"
|
||||
- path: "../sm-demo-app/plugins/demo/moderation.go"
|
||||
provides: "MessageSaving and PostSaving listeners calling the moderation Filter"
|
||||
contains: "MessageSaving"
|
||||
- path: "../sm-demo-app/plugins/demo/realtime_access.go"
|
||||
provides: "demo.realtime-access middleware"
|
||||
contains: "demo.realtime-access"
|
||||
- path: "../sm-demo-app/plugins/demo/console/seed_chat.go"
|
||||
provides: "persona users, channels, messages, threads, reactions, pins (EN/PL)"
|
||||
contains: "persona"
|
||||
- path: "../sm-demo-app/deploy/livekit.yaml.example"
|
||||
provides: "LiveKit config template: port 7890, tcp 7891, udp mux 7892, room caps"
|
||||
contains: "udp_port: 7892"
|
||||
- path: "../sm-demo-app/chat_smoke_test.go"
|
||||
provides: "TestDemoChatTracer, TestDemoModerationSmoke, TestSeedChatSmoke"
|
||||
contains: "TestDemoChatTracer"
|
||||
key_links:
|
||||
- from: "../sm-demo-app/plugins/demo/chat.go"
|
||||
to: "../sm-demo-app/plugins/golem15/chat/contracts/registry.go"
|
||||
via: "reg.Add(p.ID(), chatcontracts.Registration{Alias: chanmodels.ChannelAlias, ...})"
|
||||
pattern: "Alias: +chanmodels\\.ChannelAlias"
|
||||
- from: "../sm-demo-app/plugins/demo/moderation.go"
|
||||
to: "../sm-demo-app/plugins/golem15/moderation/classes/filter.go"
|
||||
via: "app.Lookup[*modclasses.Filter]() then Check(ctx, content)"
|
||||
pattern: "Check\\(ctx"
|
||||
- from: "../sm-demo-app/plugins/demo/routes.go"
|
||||
to: "../sm-demo-app/plugins/demo/realtime_access.go"
|
||||
via: "lighthouse.Mount UserAuth surf.Use(\"jwt.auth\", \"demo.realtime-access\", bucketRealtime)"
|
||||
pattern: "demo\\.realtime-access"
|
||||
- from: "../sm-demo-app/plugins/demo/console/reset.go"
|
||||
to: "../sm-demo-app/plugins/demo/console/seed_chat.go"
|
||||
via: "resetTables lists the chat-family tables before users; runSeed reseeds them"
|
||||
pattern: "golem15_chat_messages"
|
||||
prohibitions:
|
||||
- statement: "No file inside a plugin submodule is edited from sm-demo-app; shared plugin fixes go to the plugin repos (plan 01 pattern) and need a new tag."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "go.mod carries no replace directive and no pseudo-version for a golem15 module."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "No LiveKit key, VAPID key or persona password appears in a committed file or in command output; .env holds them."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "Nothing is pushed in this plan (plan 05 pushes with the deploy go-ahead)."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): `sm-demo-app` runs every shared Golem15 plugin in one binary, and its public Nuxt site shows them working; this phase adds the chat family to the live demo from Phase 19.4.1.
|
||||
|
||||
This plan's slice (plan 2 of 6, wave 2, per D-20): the demo backend. After it, a registered demo member can read and post in seeded channels, DM anyone, use slash commands, read and post in the forum and manage friends through the plugins' APIs. Moderation refuses banned content, and a local LiveKit can mint calls. Nothing in the Nuxt site changes yet (plans 03 and 04).
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Contexts (D-06):** alias `demo`, id 1, group name "General", broadcast `chat:context:1`. Alias `channel` (chatchannels' `models.ChannelAlias`, legacy class `models.ChannelMorphName`) loads the channel by id, with broadcast `chat:channel:{id}`. Neither broadcast is subscribable, because AuthorizeChat admits only `chat:conversation:{id}`. Both implement `contracts.LiveMembership` (true) and `contracts.MessageModerator` (moderator group, non-DM conversations only), as bm does.
|
||||
- **Joining a channel (RESEARCH assumption A3):** the layer opens a channel with `GET /_chat/api/v1/contexts/channel/{channelId}/conversation`, whose GetGroupChat lazy-joins a context member. The tracer test proves it. If it does not join, the bootstrap adds the caller as participant of each joined channel with chat's `AddUserToGroupChat`, and the SUMMARY records which path holds.
|
||||
- **Personas (discretion):** four, Ada and Ben (English) and Ola and Tomek (Polish). Emails are `<name>@personas.demo.invalid` (RFC 2606, undeliverable). Each gets a random bcrypt hash that is never printed, so nobody can log in as a persona. Channels: `general` (#general), `announcements` (#announcements), `ogolny` (#ogólny, Polish). About 15 to 25 messages per language with two threads, reactions and one pin per channel. Persona Ada sends a welcome DM to the visitor account when golem15.demo.visitor.email is set.
|
||||
- **Seeding writes:** raw SQL in the existing seed style (`insertID`, `exists`), or a ChannelService instance built with a seed-only resolver and no bus or realtime, for the channel rows. The demo's own resolver refuses CanManageContext (RESEARCH Anti-Patterns), so it cannot seed. Forum posts store content_html from `breakwater.Render`, the plugin's own renderer.
|
||||
- **Moderator group (D-22):** user group code `demo-moderators` (config `golem15.demo.chat.moderator_group`), created by the seed with no members. demo:reset wipes memberships with the users, so moderators are reassigned after a reset.
|
||||
- **Slash commands (D-05 discretion):** `/demo` explains what the demo shows and `/tour` lists the site sections with their paths. Both are ephemeral, English and Polish chosen from the actor's locale when known (else English). `/help` is chatbots' built-in.
|
||||
- **Bootstrap contract:** bm's `/_bm/api/v1/chat` shape with `general` replaced by `channels[]`. Each channel is `{id, slug, name, conversation_id, joined, unread, mentions}`. vue-chat-layer documents this contract under a neutral name (plan 03).
|
||||
- **Local LiveKit (D-10 locally):** ports 7890/7891/7892, the same as rome (RESEARCH Pitfall 7), so dev and production configs differ only in keys and external IP. `livekit_url` locally is `ws://127.0.0.1:7890`.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
## Artifacts this phase produces (this plan)
|
||||
|
||||
- Submodules `plugins/golem15/{chat,chatchannels,chatbots,chatvideo,forum,herald,userfriends,moderation}`; summer.yaml entries; go.mod requires at the plan 01 tags; sm-oauthserver-plugin v0.1.3.
|
||||
- golem15.demo: `classes.DemoContext`, `classes.ChannelContext`, `classes.ChatAccess`, `classes.ForumAccess`, `classes.ChatContextType = "demo"`, `classes.ChatContextID = 1`, `classes.ChatBroadcastChannel = "chat:context:1"`, `classes.ChannelBroadcastChannel(id uint) string`, `classes.MemberIDs`; `(*Plugin).registerChat`; `MiddlewareRealtimeAccess = "demo.realtime-access"` with `pact.HasMiddleware`; routes `GET /_demo/api/v1/chat` and `GET /_demo/api/v1/chat/members`; slash commands `/demo` and `/tour`; seam listeners for `chatevents.MessageSaving` and `forumevents.PostSaving`.
|
||||
- Config keys: `golem15.demo.chat.moderator_group` (default `demo-moderators`), `golem15.demo.chat.max_embeds` (default 3); `config/golem15.chatvideo.yaml` (`livekit_url`, `livekit_admin_url`, `max_duration: 900`, `max_participants: 4`, `token_ttl: 900`, `screen_share: false`).
|
||||
- demo:seed steps: `chat personas`, `chat channels and history (en)`, `chat channels and history (pl)`, `forum categories and threads (en, pl)`, `friends and group`, `moderator group demo-moderators`, `moderation lists`; demo:reset table list extended.
|
||||
- Deploy and dev: `deploy/livekit.yaml.example`, Centrifugo namespaces `chat`, `user`, `video`; `scripts/dev.sh` LiveKit start and stop (pid name `livekit`); env keys `SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_KEY` and `SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_SECRET` (names only in env.example).
|
||||
- Smoke tests: `TestDemoChatTracer`, `TestDemoModerationSmoke`, `TestSeedChatSmoke` (chat_smoke_test.go). Full unit tests come in plan 06.
|
||||
|
||||
<objective>
|
||||
Mount the released chat family in sm-demo-app and give it a demo host: community context, channel adapter, resolvers, bootstrap endpoints, realtime for every member, moderation wiring, slash commands, EN/PL showcase seed with reset, and a local LiveKit.
|
||||
|
||||
Purpose: SC-1 (builds with every shared plugin; demo:seed fills each), D-05 to D-09, D-12, D-14, D-17, D-22, D-23 on the server side, and the folded oauthserver todo. Plans 03 and 04 build the site UI on top of these endpoints.
|
||||
Output: commits in ../sm-demo-app (code) and one planning commit in summercms.go (the todo move). Nothing pushed.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-RESEARCH.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-PATTERNS.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-01-SUMMARY.md
|
||||
@.planning/todos/pending/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md
|
||||
@.planning/G15OFFICE.md
|
||||
|
||||
Repo: ../sm-demo-app (all code edits). Read-only: the mounted plugin submodules, ../sm-bm-app/plugins/jz/bm (host analog), ../sm-bm-app/deploy/centrifugo/bm-config.json (namespace options).
|
||||
|
||||
Rules: no co-author tags; stage by explicit path; one `feat: mount golem15.<id> <tag>` commit per plugin (precedent 9451b31: submodule, .gitmodules, go.work, go.mod, go.sum, summer.yaml, plugins.gen.go, boot_test.go); planning files in their own commit in summercms.go. Other sessions (Phase 33) may have uncommitted edits in sm-demo-app or vue-demo-app: check `git status --porcelain` before each commit, never stage or revert files this plan did not change, and stop if a file this plan must change carries foreign edits. Verify commands run from the framework root with `go -C ../sm-demo-app` and scripts by path (they cd to their own root). Docker tests: if the socket is denied, run through `sudo -u golem`.
|
||||
|
||||
<interfaces>
|
||||
Host analog ../sm-bm-app/plugins/jz/bm:
|
||||
- chat.go: `registerChat` (HasPlugin guard, `app.Lookup[*chatcontracts.Registry]()`, `reg.Add(p.ID(), chatcontracts.Registration{Alias, Loader})`, `lagoon.OnDatabase` then `app.Lookup[*chanclasses.ChannelService]()` and `SetAccessResolver`; `installChatLimits` via `svc.SetMaxMessageBytes`).
|
||||
- classes/chat_context.go: assertions `chatcontracts.Context`, `MessageModerator`, `LiveMembership`, `chancontracts.AccessResolver`; methods ID, Type, ChatEnabled, GroupName, BroadcastChannel, CanActFor (`chatcontracts.DefaultCanActFor`), CanOverseeChats, CanModerateMessage, RequireLiveMembership, HasMember, Members; `ChatContextLoader`; member query joins users_groups and user_groups.
|
||||
- realtime_access.go: `MiddlewareRealtimeAccess`, `Middlewares() map[string]pact.Middleware`, `realtimeAccess`, `writeRealtimeGuard`.
|
||||
- controllers/api/chat.go: bootstrap JSON structs (member, moderator, context, general, conversations, limits; members with id, name, surname, handle, is_bot).
|
||||
chatchannels: `models.ChannelAlias = "channel"`, `models.ChannelMorphName`, `models.Channel{ContextType, Name, Slug, Visibility...}`; `chancontracts.AccessResolver{CanAccessContext, CanManageContext}`; `ChannelService.CreateChannel` gated by CanManageContext (channel_service.go:136); `JoinChannel` only upserts a pref row (:959).
|
||||
chat: `Service.GetGroupChat(ctx, actorID, alias, contextID)`, `AddUserToGroupChat(ctx, userID, alias, contextID)`, `GetConversationsForUser`, `GetAvailableDmRecipients`, `SetMaxMessageBytes`, `MaxMessageBytes`; events `MessageSaving` and `contracts.Rejection` (plan 01).
|
||||
forum: `forum.Plugin.SetAccessResolver`, `contracts.AccessResolver` (CanRead, CanPost, CanManage, CanManageContext), `ForumService.RegisterContext(alias, legacyPHPClass)`, events `PostSaving`, `contracts.Rejection` (plan 01).
|
||||
chatbots: `contracts.SlashCommand{Trigger, Description, IsAvailable, Handle}`, `classes.Ephemeral(payload)`, `(*classes.Registry).Register` (help is reserved), Registry published in chatbots' OnDatabase hook.
|
||||
moderation: `*classes.Filter` published at boot, `Check(ctx, text) (*Violation, error)` (plan 01).
|
||||
chatvideo config keys (config/config.yaml of the plugin): livekit_url, livekit_api_key, livekit_api_secret, max_duration, token_ttl, livekit_admin_url, max_participants, screen_share; env `SUMMER_GOLEM15__CHATVIDEO__*` or PHP names `LIVEKIT_*`.
|
||||
sm-demo-app today: plugins/demo/plugin.go (Requires, Boot calls wireRealtime), routes.go (`APIPrefix`, `mountRealtime` limited to presentations with `presentations.realtime-owner`), console/seed.go (`runSeed` step table, `created`, `insertID`, `exists`), console/reset.go (`resetTables`, children first), boot_test.go (`wantPlugins`, routed prefixes), realtime_test.go (`TestRealtimeRoutes`, `wantNamespaces`), testmain_test.go (`bootDemo`), go_mod_test.go, scripts/dev.sh (`ensure_env`, `start_centrifugo`, `claim_port`, `up`/`down`/`status`), deploy/centrifugo.json.example (namespaces array with `subscribe_proxy_enabled`).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: a registered member reads the chat bootstrap and posts in the seeded #general channel through the chat API</name>
|
||||
<precondition>The plan 01 SUMMARY lists the eight tags and `git ls-remote --tags git@git.golem15.com:golem15/sm-chat-plugin.git` shows the chat tag; `git -C ../sm-demo-app status --porcelain` shows nothing except ` M plugins/golem15/oauthserver`; `docker info` exits 0.</precondition>
|
||||
<files>../sm-demo-app/plugins/golem15/oauthserver, ../sm-demo-app/.gitmodules, ../sm-demo-app/go.work, ../sm-demo-app/go.mod, ../sm-demo-app/go.sum, ../sm-demo-app/summer.yaml, ../sm-demo-app/plugins.gen.go, ../sm-demo-app/plugins/golem15/chat, ../sm-demo-app/plugins/golem15/chatchannels, ../sm-demo-app/plugins/demo/plugin.go, ../sm-demo-app/plugins/demo/chat.go, ../sm-demo-app/plugins/demo/classes/chat_context.go, ../sm-demo-app/plugins/demo/chat_api.go, ../sm-demo-app/plugins/demo/routes.go, ../sm-demo-app/plugins/demo/console/seed.go, ../sm-demo-app/plugins/demo/console/seed_chat.go, ../sm-demo-app/boot_test.go, ../sm-demo-app/chat_smoke_test.go, .planning/todos/pending/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md, .planning/todos/done/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md</files>
|
||||
<read_first>../sm-demo-app/summer.yaml, go.mod, go.work, .gitmodules, plugins.gen.go, `git -C ../sm-demo-app show 9451b31 --stat` (mount commit shape), ../sm-demo-app/plugins/demo/plugin.go, routes.go, console/seed.go, ../sm-demo-app/boot_test.go, testmain_test.go, internal/demotest/postgres.go, ../sm-bm-app/plugins/jz/bm/chat.go, classes/chat_context.go, controllers/api/chat.go, ../sm-demo-app/plugins/golem15/chat/contracts/*.go and classes/writes.go (GetGroupChat, AddUserToGroupChat) after mounting, ../sm-demo-app/plugins/golem15/chatchannels/models/channel.go, classes/channel_service.go (CreateChannel, JoinChannel), contracts/*.go, ../sm-demo-app/scripts/check-pins.sh, the folded todo, .planning/G15OFFICE.md</read_first>
|
||||
<action>Per D-06, D-07, SC-1 and the folded todo.
|
||||
|
||||
1. Folded todo first:
|
||||
- `git -C ../sm-demo-app/plugins/golem15/oauthserver fetch --tags`, confirm `git merge-base --is-ancestor b6a9586 v0.1.3`, then check out v0.1.3;
|
||||
- in ../sm-demo-app run `GOWORK=off GOPRIVATE=git.golem15.com/* go get git.golem15.com/golem15/sm-oauthserver-plugin@v0.1.3` and `go mod tidy`;
|
||||
- commit the gitlink with go.mod and go.sum as `chore: bump sm-oauthserver-plugin to v0.1.3`.
|
||||
In summercms.go, `git mv` the todo to .planning/todos/done/, add a "Done in Phase 20 plan 02" line, and commit it as a planning commit. Move g15office task ssuyq2os to Live with a one-line comment, as .planning/G15OFFICE.md describes.
|
||||
2. Mount chat and chatchannels at their plan 01 tags:
|
||||
- `git submodule add -b main git@git.golem15.com:golem15/sm-<name>-plugin.git plugins/golem15/<name>`, then check out the tag;
|
||||
- add both to go.work `use`, and run `GOWORK=off go get <module>@<tag>` plus `go mod tidy`;
|
||||
- add summer.yaml entries after golem15.user (chat, then chatchannels) and before golem15.demo;
|
||||
- regenerate plugins.gen.go the way 9451b31 did (the summer build generator);
|
||||
- append the IDs to boot_test.go wantPlugins and `/_chat/api/v1` and `/_chatchannels/api/v1` to its routed prefixes.
|
||||
One `feat: mount golem15.<id> <tag>` commit per plugin.
|
||||
3. plugins/demo/classes/chat_context.go, ported from bm's chat_context.go:
|
||||
- constants ChatContextType "demo", ChatContextID 1, ChatGroupName "General", ChatBroadcastChannel "chat:context:1", and `ChannelBroadcastChannel(id)` returning "chat:channel:{id}";
|
||||
- `MemberIDs(ctx, db)` and `IsMember(ctx, db, userID)`: users that are activated, have no deleted_at and are not banned (use the user plugin's own ban column; read its models);
|
||||
- DemoContext and ChannelContext implement chatcontracts.Context, MessageModerator and LiveMembership. CanModerateMessage is true only for a member of the moderator group in a non-DM conversation. RequireLiveMembership returns true;
|
||||
- ChatAccess (chancontracts.AccessResolver): CanAccessContext is true for a member when the type is "demo" and the id is 1; CanManageContext is always false (D-07);
|
||||
- keep bm's `WithMembership` and `MemberFunc` injection so tests can stub membership.
|
||||
4. plugins/demo/chat.go `registerChat(app)`, called from Boot after wireRealtime:
|
||||
- with the HasPlugin guard, register alias demo (loader returns DemoContext for id 1 and the unknown-context error otherwise) and alias `chanmodels.ChannelAlias` with `LegacyPHPClass: chanmodels.ChannelMorphName` (loader reads the channel row by id and returns ChannelContext);
|
||||
- in lagoon.OnDatabase, install ChatAccess on the ChannelService.
|
||||
Requires() gains golem15.chat and golem15.chatchannels. Config keys go into plugins/demo/config/config.yaml in Task 2.
|
||||
5. console/seed_chat.go: a step `chat channels and history (en)` that, in this task, creates only #general in context demo/1 (channel row plus backing conversation, exactly the rows CreateChannel writes, through a seed-only resolver or raw SQL) and one welcome message from the first admin or a persona. It is idempotent by slug. Add it to the runSeed step table.
|
||||
6. plugins/demo/chat_api.go: `GET /_demo/api/v1/chat` behind `jwt.auth` and `throttle:120,1`, mounted from Routes. For a member it answers `{member: true, moderator, context: {type: "demo", id: 1}, channels: [{id, slug, name, conversation_id, joined, unread, mentions}], conversations: [DMs as bm's chatConversationJSON], limits: {max_files, max_bytes, max_embeds}}`. For a non-member it answers `{member: false}`. Errors use `wire.WriteJSON` with `{"error": ...}`.
|
||||
7. chat_smoke_test.go `TestDemoChatTracer` (Docker): bootDemo, run demo:seed, create and activate a user, then with its JWT:
|
||||
- GET /_demo/api/v1/chat shows #general with a conversation_id;
|
||||
- GET /_chat/api/v1/contexts/channel/{channelId}/conversation answers 200;
|
||||
- POST /_chat/api/v1/conversations/{conversation_id}/messages answers 201;
|
||||
- GET .../messages contains the text;
|
||||
- POST /_chatchannels/api/v1/contexts/demo/1/channels is refused (403 or 404).
|
||||
If the lazy join does not make the user a participant, implement the AddUserToGroupChat fallback in the bootstrap and record it.
|
||||
|
||||
Commit the host wiring and the test as `feat: demo chat context, channel adapter and bootstrap`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-demo-app vet . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -short . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -run '^(TestDemoChatTracer|TestGoModRequiresTags|TestBootAllPlugins)$' -v . 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 3 && ../sm-demo-app/scripts/check-pins.sh</automated>
|
||||
<fails_when>Non-zero exit: vet or the short suite red; fewer than three "--- PASS" lines (a replace or pseudo-version in go.mod, a plugin not activated, a missing route prefix, the member cannot post, or the channel create was allowed); or check-pins prints a mismatch line instead of "check-pins: ok".</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../sm-demo-app log --oneline -6` shows `chore: bump sm-oauthserver-plugin to v0.1.3`, `feat: mount golem15.chat`, `feat: mount golem15.chatchannels` and the host commit, each separate.
|
||||
- `git -C ../sm-demo-app submodule status plugins/golem15/oauthserver plugins/golem15/chat plugins/golem15/chatchannels` shows no leading `+` and each describes as its tag.
|
||||
- `test -f .planning/todos/done/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md && ! test -e .planning/todos/pending/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md` exits 0.
|
||||
- `grep -c 'Alias: *chanmodels.ChannelAlias' ../sm-demo-app/plugins/demo/chat.go` prints 1.
|
||||
</acceptance_criteria>
|
||||
<done>A demo member can open the seeded #general channel and post in it through the shared chat API, from a build that requires every module by tag.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: The rest of the family is mounted and wired: forum, friends, slash commands, video config, herald, and moderation refusing banned content</name>
|
||||
<files>../sm-demo-app/.gitmodules, ../sm-demo-app/go.work, ../sm-demo-app/go.mod, ../sm-demo-app/go.sum, ../sm-demo-app/summer.yaml, ../sm-demo-app/plugins.gen.go, ../sm-demo-app/plugins/golem15/chatbots, ../sm-demo-app/plugins/golem15/chatvideo, ../sm-demo-app/plugins/golem15/forum, ../sm-demo-app/plugins/golem15/herald, ../sm-demo-app/plugins/golem15/userfriends, ../sm-demo-app/plugins/golem15/moderation, ../sm-demo-app/config/golem15.chatvideo.yaml, ../sm-demo-app/plugins/demo/plugin.go, ../sm-demo-app/plugins/demo/config/config.yaml, ../sm-demo-app/plugins/demo/chat.go, ../sm-demo-app/plugins/demo/chatbots.go, ../sm-demo-app/plugins/demo/moderation.go, ../sm-demo-app/plugins/demo/classes/forum_access.go, ../sm-demo-app/boot_test.go, ../sm-demo-app/chat_smoke_test.go</files>
|
||||
<read_first>../sm-demo-app/plugins/golem15/forum/README.md, boot.go, contracts/access_resolver.go, ../sm-demo-app/plugins/golem15/chatbots/README.md, contracts/slash_command.go, classes/registry.go, classes/result.go, boot.go, ../sm-demo-app/plugins/golem15/chatvideo/README.md and config/config.yaml, ../sm-demo-app/plugins/golem15/herald/README.md and config/config.yaml, ../sm-demo-app/plugins/golem15/userfriends/README.md, ../sm-demo-app/plugins/golem15/moderation/README.md and classes/filter.go, ../sm-demo-app/plugins/golem15/chat/events/events.go and contracts/rejection.go, ../sm-demo-app/plugins/golem15/forum/events/events.go and contracts/rejection.go, ../sm-demo-app/plugins/demo/chat.go (Task 1), ../sm-bm-app/plugins/jz/bm/chat.go (config key block)</read_first>
|
||||
<action>Per D-05, D-08, D-12, D-14, D-17, D-22, D-23, SC-1.
|
||||
|
||||
1. Mount chatbots, chatvideo, forum, herald, userfriends and moderation at their plan 01 tags as in Task 1, one `feat: mount golem15.<id> <tag>` commit each. Order in summer.yaml: chatbots and chatvideo after chatchannels; forum, herald and userfriends after them (userfriends after chat, so it sees the chat registry at Boot); moderation; all before golem15.demo. Extend boot_test.go wantPlugins and its prefixes: /_chatbots/api/v1, /_chatvideo/api/v1, /_forum/api/v1, /_herald/api/v1, /_userfriends/api/v1 and /_demo/api/v1/chat.
|
||||
2. config/golem15.chatvideo.yaml (D-12, D-23): livekit_url "ws://127.0.0.1:7890", livekit_admin_url "http://127.0.0.1:7890", max_duration 900, max_participants 4, token_ttl 900, screen_share false. API key and secret come only from the environment. Herald gets no committed config: its keys come from .env (plan 04).
|
||||
3. plugins/demo/config/config.yaml: `chat: {moderator_group: demo-moderators, max_embeds: 3}`. chat.go reads them as in bm's config key block and reports the limits in the bootstrap (max_bytes from the chat service's MaxMessageBytes).
|
||||
4. Forum (D-14, D-22): classes/forum_access.go `ForumAccess`. CanRead and CanPost are true for a member when the context is demo/1; CanManage and CanManageContext are true for members of the moderator group. registerChat looks up `*forum.Plugin` and calls SetAccessResolver, and registers the context alias demo with the forum service when its API requires registration (check ListCategories on an unregistered alias).
|
||||
5. DMs (D-08): nothing to add beyond DemoContext.HasMember. Verify in the smoke test that two members open a DM with POST /_chat/api/v1/contexts/demo/1/dm.
|
||||
6. chatbots.go (D-05): `/demo` and `/tour` implement contracts.SlashCommand with IsAvailable true for any non-zero actor and Handle returning classes.Ephemeral with a short text (/tour lists /blog, /presentations, /quizzes, /subscriptions, /faq, /chat, /forum, /friends). Register them in lagoon.OnDatabase after chatbots published its Registry; a missing registry is a boot error naming the summer.yaml order.
|
||||
7. moderation.go (D-17): in Boot, `app.Events.Listen[*chatevents.MessageSaving](p.ID(), ...)` looks up `*modclasses.Filter` per event and returns `chatcontracts.Rejection{Field: "content", Message: v.Message}` when Check finds a violation. `app.Events.Listen[*forumevents.PostSaving]` checks Title (Field "title"), then Body (Field "body"), returning `forumcontracts.Rejection`. A Check error is returned as is (500). A missing filter is a boot error, because golem15.demo requires golem15.moderation.
|
||||
8. plugin.go Requires() lists every plugin whose tables the seed or reset writes or that the demo wires: chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, moderation, plus the existing ones. The package doc mentions the chat host.
|
||||
9. chat_smoke_test.go `TestDemoModerationSmoke` (Docker): seed, then set golem15_moderation_settings banned_words to "blockedword" and banned_links to "bad.example". A member's message "this has blockedword" in #general answers 422 errors.content; a forum thread titled "visit bad.example" in a seeded category answers 422 errors.title; a clean message answers 201. Also assert the DM open from step 5 and that GET /_chatbots/api/v1/commands lists demo and tour.
|
||||
|
||||
Commit wiring (`feat: demo hosts forum, friends, slash commands and moderation`) separately from the six mount commits.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-demo-app vet . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -short . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -run '^(TestDemoModerationSmoke|TestBootAllPlugins|TestGoModRequiresTags|TestDemoChatTracer)$' -v . 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 4 && ../sm-demo-app/scripts/check-pins.sh && ../sm-demo-app/scripts/build.sh dev</automated>
|
||||
<fails_when>Non-zero exit: vet or short suite red; fewer than four "--- PASS" lines (banned content stored, a plugin not activated, a prefix not routed, a go.mod rule broken); check-pins reports a mismatch; or the dev build fails.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -cE '^ - id: golem15\.(chat|chatchannels|chatbots|chatvideo|forum|herald|userfriends|moderation)$' ../sm-demo-app/summer.yaml` prints 8.
|
||||
- `grep -c 'max_participants: 4' ../sm-demo-app/config/golem15.chatvideo.yaml` prints 1 and `grep -c 'max_duration: 900' ../sm-demo-app/config/golem15.chatvideo.yaml` prints 1.
|
||||
- `grep -rn 'livekit_api_secret: *"[^"]' ../sm-demo-app/config` prints nothing (no committed secret).
|
||||
- `git -C ../sm-demo-app status --porcelain -- plugins/golem15` prints nothing (submodules clean, on tags).
|
||||
</acceptance_criteria>
|
||||
<done>Every chat-family plugin boots in the demo with its host policy; banned words and links are refused in chat and forum; slash commands answer; video is configured with the D-12 caps.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: demo:seed fills chat, forum and friends with EN and PL showcase data, and demo:reset wipes and reseeds all of it</name>
|
||||
<files>../sm-demo-app/plugins/demo/console/seed.go, ../sm-demo-app/plugins/demo/console/seed_chat.go, ../sm-demo-app/plugins/demo/console/seed_forum.go, ../sm-demo-app/plugins/demo/console/seed_friends.go, ../sm-demo-app/plugins/demo/console/reset.go, ../sm-demo-app/chat_smoke_test.go</files>
|
||||
<read_first>../sm-demo-app/plugins/demo/console/seed.go (step table, created, insertID, exists, visitor), seed_locales.go, reset.go (resetTables order and comments), ../sm-demo-app/reset_test.go and seed_test.go, the baseline migrations of every mounted chat-family plugin (../sm-demo-app/plugins/golem15/{chat,chatchannels,chatbots,chatvideo,forum,herald,userfriends}/updates/*.go) for table names and foreign keys, ../sm-demo-app/plugins/golem15/chatchannels/models (pins, mentions, members, prefs), ../sm-demo-app/plugins/golem15/chat/models (message, reaction, thread summary), modules/breakwater/README.md, 20-RESEARCH.md (Pitfall 10, Anti-Patterns)</read_first>
|
||||
<action>Per D-09, D-14, D-15 (data), D-22, D-17.
|
||||
|
||||
- seed_chat.go:
|
||||
- `chat personas`: Ada, Ben, Ola and Tomek, as decided above. Each is activated, has a random password hash that is never printed, and is skipped when the email exists.
|
||||
- `chat channels and history (en)`: #general and #announcements, with English history from the personas, two threads (root plus 2 to 4 replies, keeping chat's thread summary rows consistent the way the service writes them), reactions on a few messages using the keys chat allows (GET /reactions catalog in the plugin), and one pin per channel in chatchannels' pins table.
|
||||
- `chat channels and history (pl)`: #ogólny (slug ogolny) with Polish history, a thread, reactions and a pin.
|
||||
- A welcome DM from Ada to the visitor when golem15.demo.visitor.email is set (skipped otherwise).
|
||||
- Rows are written in created order with timestamps spread over the last few days. Messages are inserted directly: no realtime, no jobs, no events. Steps are idempotent by channel slug and persona email.
|
||||
- seed_forum.go `forum categories and threads (en, pl)`: categories "General discussion" and "Show and tell" (EN) and "Rozmowy" (PL) in context demo/1, two or three threads each with replies by personas. content is Markdown and content_html comes from `breakwater.Render`. Idempotent by category slug.
|
||||
- seed_friends.go `friends and group`: accepted friendships among the personas, one pending request from Ola to the visitor when set, and a friend group "Demo crew" owned by Ada with Ben and Tomek as members. Use userfriends' tables and the context singleton id 1. Idempotent.
|
||||
- seed.go: steps `moderator group demo-moderators` (a user_groups row with the configured code and name "Demo moderators", no members) and `moderation lists` (when banned_words and banned_links are both empty, fill a short, mild default list of common spam words and one link-shortener domain; otherwise "exists"). Order the new steps after the visitor and before the roadmap decks.
|
||||
- reset.go `resetTables` (RESEARCH Pitfall 10), children first, all before `users`:
|
||||
- chatvideo participants, then sessions;
|
||||
- chat reactions, thread mutes, thread summaries, messages, participants, conversations;
|
||||
- chatchannels mentions, pins, members, prefs, user context prefs, personal categories, channels, categories;
|
||||
- forum thread reads, posts, threads, categories;
|
||||
- userfriends group bans, invites, group members, groups, friendships;
|
||||
- herald push subscriptions;
|
||||
- chatbots bot flags.
|
||||
Use the exact table names from the migrations. Keep golem15_moderation_settings and golem15_userfriends_contexts. Update the comment and the command description. Remove the chat-family uploads (chat attachments in system_files) the same way the reset already removes other owners' attachments, keeping resetKeptAttachments.
|
||||
- chat_smoke_test.go `TestSeedChatSmoke` (Docker): seed with a visitor email.
|
||||
- Three channels exist, #ogólny holds Polish text, at least one thread root has replies, at least one reaction and one pin exist, the forum has three categories with posts whose content_html is non-empty, there are at least three accepted friendships and the group "Demo crew", and the visitor has a DM.
|
||||
- A second seed run reports every new step as "exists".
|
||||
- demo:reset --force empties golem15_chat_messages before reseeding and leaves golem15_moderation_settings unchanged.
|
||||
|
||||
Commit `feat: seed and reset the chat family (EN/PL)`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-demo-app vet . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -run '^(TestSeedChatSmoke|TestResetKeepsPlans|TestSeedRoadmapUpsert)$' -v . 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 3</automated>
|
||||
<fails_when>Non-zero exit or fewer than three "--- PASS" lines: seed not idempotent, a missing EN/PL item, a foreign-key violation in the reset order, moderation settings wiped, or the existing reset and roadmap tests broken.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'golem15_chat_messages' ../sm-demo-app/plugins/demo/console/reset.go` prints at least 1, and TestSeedChatSmoke asserts the moderation settings row is identical before and after demo:reset --force.
|
||||
- `grep -c 'personas.demo.invalid' ../sm-demo-app/plugins/demo/console/seed_chat.go` prints at least 1.
|
||||
- Running `../sm-demo-app/scripts/dev.sh seed` twice against the local stack prints no "created" for the new steps on the second run.
|
||||
</acceptance_criteria>
|
||||
<done>A fresh or reset demo shows lived-in EN and PL channels, threads, reactions, pins, forum threads, friendships and a friend group, and the reset job keeps it that way.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Every member gets realtime, the layers get their members endpoint, and dev runs Centrifugo namespaces and a local LiveKit</name>
|
||||
<files>../sm-demo-app/plugins/demo/realtime_access.go, ../sm-demo-app/plugins/demo/routes.go, ../sm-demo-app/plugins/demo/plugin.go, ../sm-demo-app/plugins/demo/chat_api.go, ../sm-demo-app/realtime_test.go, ../sm-demo-app/deploy/centrifugo.json.example, ../sm-demo-app/deploy/livekit.yaml.example, ../sm-demo-app/deploy/env.example, ../sm-demo-app/scripts/dev.sh, ../sm-demo-app/README.md</files>
|
||||
<read_first>../sm-bm-app/plugins/jz/bm/realtime_access.go, ../sm-demo-app/plugins/demo/routes.go (mountRealtime), realtime.go, ../sm-demo-app/realtime_test.go (TestRealtimeRoutes, wantNamespaces, realtimeApp), ../sm-bm-app/deploy/centrifugo/bm-config.json (chat, user and video namespace options), ../sm-demo-app/deploy/centrifugo.json.example, ../sm-demo-app/scripts/dev.sh (ensure_env, start_centrifugo, claim_port, up, down, status, the usage header), ../sm-demo-app/deploy/env.example, ../sm-demo-app/README.md, ../sm-demo-app/plugins/golem15/chatvideo/README.md (keys, admin URL, TrustedMode), 20-RESEARCH.md (Pitfalls 4, 5, 7; LiveKit config block)</read_first>
|
||||
<action>Per D-10 (locally), D-06, SC-1.
|
||||
|
||||
1. realtime_access.go: `MiddlewareRealtimeAccess = "demo.realtime-access"`, exported through `Middlewares() map[string]pact.Middleware` (assert pact.HasMiddleware in plugin.go). The guard reads `bouncer.User(r.Context())`: no user gives 401, a database not yet published gives 503, and a user for whom classes.IsMember is true passes. Otherwise it falls back to the presentations owner guard looked up once (sync.Once) by name, as bm does. routes.go mountRealtime mounts when golem15.presentations or golem15.chat is active, with `UserAuth: surf.Use("jwt.auth", MiddlewareRealtimeAccess, bucketRealtime)`. Update its doc comment.
|
||||
2. realtime_test.go: the token route's expected middleware becomes ["jwt.auth", "demo.realtime-access", "throttle:golem15.demo.realtime"], and wantNamespaces gains the namespaces the chat, chatvideo and user plugins register. Plan 06 adds the member/non-member cases.
|
||||
3. chat_api.go `GET /_demo/api/v1/chat/members` (jwt.auth, throttle:120,1) answers `{members: [{id, name, surname, handle, is_bot}]}` for every member except the caller, as bm's ChatMembers does (handle from the user plugin's username or a slug of the name; is_bot false). A non-member gets 403.
|
||||
4. deploy/centrifugo.json.example: add namespaces `chat` (presence, join_leave, force_push_join_leave, allow_presence_for_subscriber and subscribe_proxy_enabled, with the option names bm's config uses translated to this file's v6 format), `user` (subscribe_proxy_enabled) and `video` (subscribe_proxy_enabled). Run `centrifugo checkconfig -c deploy/centrifugo.json.example`, then diff the option names against `centrifugo defaultconfig`, because checkconfig misses misspelt names. Update the _comment lines.
|
||||
5. deploy/livekit.yaml.example (RESEARCH LiveKit block):
|
||||
- port 7890, bind_addresses [127.0.0.1];
|
||||
- rtc tcp_port 7891, udp_port 7892 (UDP mux only, no port-range keys), use_external_ip true and a comment that local runs set it false;
|
||||
- room max_participants 4, empty_timeout 120, departure_timeout 20;
|
||||
- keys with one placeholder pair (CHANGE_ME_KEY: CHANGE_ME_SECRET);
|
||||
- a header comment naming rome's path /srv/summercms-demo/livekit.yaml (0640 root:summercms-demo), the supervisor program plan 05 adds, and the env keys.
|
||||
6. scripts/dev.sh:
|
||||
- LIVEKIT=${LIVEKIT:-$(command -v livekit-server || true)};
|
||||
- ensure_env appends SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_KEY and SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_SECRET (random, umask 077, never echoed) when missing;
|
||||
- `livekit_config` writes logs/livekit.yaml from the example with the .env keys and use_external_ip false;
|
||||
- `start_livekit` claims ports 7890 and 7891, starts `livekit-server --config logs/livekit.yaml` under the pid name livekit with output to logs/livekit.log, waits for http://127.0.0.1:7890/ and warns and continues without video when the binary is missing;
|
||||
- up starts it after Centrifugo, down, destroy and status include livekit, and the header usage lines mention it.
|
||||
7. deploy/env.example: the two LiveKit key names with empty values and a comment. README.md: a "Chat family" section covering the mounted plugins, the contexts, the bootstrap contract of /_demo/api/v1/chat and /chat/members, the seed data, the moderator group, slash commands and local LiveKit.
|
||||
|
||||
Commit `feat: realtime for every demo member, members endpoint, Centrifugo namespaces and local LiveKit`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-demo-app vet . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -short . ./plugins/demo/... && centrifugo checkconfig -c ../sm-demo-app/deploy/centrifugo.json.example && ../sm-demo-app/scripts/dev.sh up && curl -fsS http://127.0.0.1:7890/ >/dev/null && ../sm-demo-app/scripts/check-local.sh realtime</automated>
|
||||
<fails_when>Non-zero exit: vet or the short suite red (TestRealtimeRoutes middleware or namespaces), checkconfig refuses the Centrifugo file, dev.sh up fails to start a service, LiveKit does not answer on 127.0.0.1:7890, or check-local realtime reports a non-200 token for the visitor or a token without a JWT.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '"name": "chat"' ../sm-demo-app/deploy/centrifugo.json.example` prints 1, and the same for "user" and "video".
|
||||
- `grep -v '^\s*#' ../sm-demo-app/deploy/livekit.yaml.example | grep -cE 'port_range_(start|end)'` prints 0, and `grep -c 'udp_port: 7892' ../sm-demo-app/deploy/livekit.yaml.example` prints 1.
|
||||
- With the local stack up, `curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $VISITOR_JWT" http://127.0.0.1:8097/api/realtime/token` prints 200 (JWT from the login API).
|
||||
- `grep -c 'LIVEKIT_API_SECRET=' ../sm-demo-app/deploy/env.example` prints 1 and that line has no value after the equals sign.
|
||||
</acceptance_criteria>
|
||||
<done>Every demo member gets a realtime token and the member list, Centrifugo knows the chat namespaces, and a local LiveKit runs with the dev stack.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| browser to /_demo, /_chat, /_chatchannels, /_forum, /_userfriends, /_chatbots, /_chatvideo | every request untrusted; actor only from the JWT |
|
||||
| Centrifugo subscribe proxy to Go | channel names come from clients; authorizers decide |
|
||||
| seed and reset commands to the database | trusted operator commands; persona accounts must stay unusable |
|
||||
| Go to LiveKit RoomService on loopback | admin calls with the API secret |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-06 | Elevation of privilege | channel creation by members | high | mitigate | ChatAccess.CanManageContext is always false; TestDemoChatTracer asserts POST channels is refused (D-07) |
|
||||
| T-20-07 | Information disclosure | subscribing to other conversations | high | mitigate | broadcast channels chat:context:1 and chat:channel:{id} are not subscribable (AuthorizeChat admits only chat:conversation:{id}); user:{id} only to itself (user plugin authorizer); video:session:{id} only to session participants |
|
||||
| T-20-08 | Spoofing | persona accounts | medium | mitigate | random password hashes never printed, emails under .invalid, so no login and no mail; reset wipes and recreates them |
|
||||
| T-20-09 | Elevation of privilege | moderator rights | medium | mitigate | moderator group membership only through the user admin (D-22); CanModerateMessage limited to non-DM conversations; banned users fail HasMember with live membership on |
|
||||
| T-20-10 | Tampering | spam and abuse in public chat and forum | high | mitigate | moderation listeners on both seams (TestDemoModerationSmoke), plugin buckets (chat-api, chat-dm, forum-api, video-initiate), Turnstile on register (19.4.1), reset job |
|
||||
| T-20-11 | Denial of service | realtime token minting for every member | low | mitigate | guard needs a JWT of a live member, per-user bucket golem15.demo.realtime 120/min unchanged |
|
||||
| T-20-12 | Information disclosure | LiveKit and VAPID secrets | high | mitigate | values only in .env (dev.sh writes them with umask 077, never echoed); env.example holds names; config files hold no secret (acceptance grep) |
|
||||
| T-20-13 | Denial of service | stale chat-family rows after reset | low | mitigate | reset table list in FK order covering every chat-family table; TestSeedChatSmoke checks messages are emptied |
|
||||
| T-20-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package-manager install in this plan; Go modules are the project's tagged plugins from plan 01 (go.sum committed, GOPRIVATE) |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: tracer test, go.mod tags, boot test, check-pins.
|
||||
- Task 2: moderation smoke, boot and go.mod tests, check-pins, dev build.
|
||||
- Task 3: seed smoke, reset and roadmap tests.
|
||||
- Task 4: short suite, Centrifugo checkconfig, dev stack up with LiveKit, check-local realtime.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
sm-demo-app builds with every shared plugin including the chat family, and demo:seed fills each with EN/PL showcase data (SC-1). The demo hosts one community where every member can chat, DM, post in the forum and befriend others, with moderation, slash commands and video configured (D-05 to D-09, D-12, D-14, D-17, D-22, D-23).
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-02-SUMMARY.md` when done: mount commits with tags, which channel join path holds (lazy join or bootstrap), persona and channel names, the reset table order, the Centrifugo option names used, and any boot warnings left by plugins (for example herald's presence gate).
|
||||
</output>
|
||||
@@ -0,0 +1,311 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 02
|
||||
subsystem: sm-demo-app
|
||||
tags: [chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, moderation, livekit, centrifugo, seed]
|
||||
|
||||
requires:
|
||||
- phase: 20-01
|
||||
provides: the eight chat-family tags (chat v0.1.5 with MessageSaving, forum v0.1.1 with PostSaving, moderation v0.1.0 Filter)
|
||||
provides:
|
||||
- "sm-demo-app mounts chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends and moderation at their tags"
|
||||
- "golem15.demo hosts the chat family: contexts demo/1 and channel/{id}, channel and forum access policies, moderation seams, slash commands /demo and /tour"
|
||||
- "Host bootstrap contract GET /_demo/api/v1/chat and GET /_demo/api/v1/chat/members (for vue-chat-layer, plan 03)"
|
||||
- "demo.realtime-access: every community member gets a realtime token"
|
||||
- "demo:seed EN/PL showcase data for chat, forum and friends; demo:reset covers every chat-family table"
|
||||
- "Local LiveKit in scripts/dev.sh; deploy/livekit.yaml.example and Centrifugo namespaces chat, user, video (for plan 05)"
|
||||
affects: [20-03, 20-04, 20-05, 20-06]
|
||||
|
||||
actuals:
|
||||
tokens: 36500 # chars/4 over the realized sm-demo-app diff 56c1141..f4ed2c2 without go.sum (146079 chars)
|
||||
tasks: 4
|
||||
commits: 1 # MEASURED in summercms.go: git rev-list --count plan_head_before..HEAD (the todo move); sm-demo-app: 12 (git rev-list --count 56c1141..f4ed2c2)
|
||||
plan_head_before: 159cd5ecf4aac6e48c2579c68c19addb7633cfce # summercms.go
|
||||
plan_head_after: d6f490a9abcaf4322aec5a072f7842b8f0d3d2c3 # summercms.go before this SUMMARY commit; sm-demo-app 56c1141 -> f4ed2c2
|
||||
|
||||
tech-stack:
|
||||
added:
|
||||
- "github.com/livekit/server-sdk-go/v2 v2.19.0 and github.com/SherClockHolmes/webpush-go v1.4.0 (transitive, through chatvideo and herald)"
|
||||
patterns:
|
||||
- "Channel-as-context adapter: the host registers chatchannels' `channel` alias on chat's registry so a channel's backing conversation resolves"
|
||||
- "Host wiring in lagoon.OnDatabase after each plugin published its service (ChannelService, ForumService, chatbots Registry, moderation Filter); a missing service is a boot error naming the summer.yaml order"
|
||||
- "Pre-save veto listeners (MessageSaving, PostSaving) look up the moderation Filter per event"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../sm-demo-app/plugins/demo/classes/chat_context.go
|
||||
- ../sm-demo-app/plugins/demo/classes/forum_access.go
|
||||
- ../sm-demo-app/plugins/demo/chat.go
|
||||
- ../sm-demo-app/plugins/demo/chat_api.go
|
||||
- ../sm-demo-app/plugins/demo/chatbots.go
|
||||
- ../sm-demo-app/plugins/demo/moderation.go
|
||||
- ../sm-demo-app/plugins/demo/realtime_access.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_chat.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_forum.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_friends.go
|
||||
- ../sm-demo-app/chat_smoke_test.go
|
||||
- ../sm-demo-app/config/golem15.chatvideo.yaml
|
||||
- ../sm-demo-app/config/golem15.chat.yaml
|
||||
- ../sm-demo-app/config/env/production/golem15.chatvideo.yaml
|
||||
- ../sm-demo-app/deploy/livekit.yaml.example
|
||||
modified:
|
||||
- ../sm-demo-app/summer.yaml
|
||||
- ../sm-demo-app/go.mod
|
||||
- ../sm-demo-app/go.work
|
||||
- ../sm-demo-app/.gitmodules
|
||||
- ../sm-demo-app/plugins.gen.go
|
||||
- ../sm-demo-app/plugins/demo/plugin.go
|
||||
- ../sm-demo-app/plugins/demo/routes.go
|
||||
- ../sm-demo-app/plugins/demo/config/config.yaml
|
||||
- ../sm-demo-app/plugins/demo/console/seed.go
|
||||
- ../sm-demo-app/plugins/demo/console/reset.go
|
||||
- ../sm-demo-app/boot_test.go
|
||||
- ../sm-demo-app/realtime_test.go
|
||||
- ../sm-demo-app/deploy/centrifugo.json.example
|
||||
- ../sm-demo-app/deploy/env.example
|
||||
- ../sm-demo-app/scripts/dev.sh
|
||||
- ../sm-demo-app/README.md
|
||||
- .planning/todos/done/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md
|
||||
|
||||
key-decisions:
|
||||
- "Folded oauthserver/journal todo closed without a commit in sm-demo-app: 2133309 and 5ec5941 had already moved oauthserver to v0.1.6 (contains b6a9586) and journal to v0.2.6; not moved back to v0.1.3"
|
||||
- "Channel join path: GetGroupChat's lazy join holds (opening GET /_chat/api/v1/contexts/channel/{id}/conversation adds the participant row); the bootstrap joins nobody"
|
||||
- "Bootstrap channels[].joined is 'has not left' (chatchannels prefs.has_left); left channels stay listed with joined false"
|
||||
- "Chat attachments capped at 5 MiB per message (config/golem15.chat.yaml max_message_bytes 5242880), reported as limits.max_bytes"
|
||||
- "Forum CanManage and CanManageContext both go to the moderator group, as the plan says; forum needs no RegisterContext for listing or posting"
|
||||
- "Production livekit_url wss://demo.summercms.io/livekit lives in config/env/production/golem15.chatvideo.yaml"
|
||||
|
||||
patterns-established:
|
||||
- "Seed steps write chat rows by raw SQL in created order and call chat's own jobs.Work to keep thread summaries consistent"
|
||||
|
||||
requirements-completed: [SC-1, D-05, D-06, D-07, D-08, D-09, D-10, D-12, D-14, D-17, D-20, D-22, D-23]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "A registered member reads the bootstrap, opens seeded #general (lazy join), posts and reads back through the chat API; channel creation refused; members endpoint excludes the caller"
|
||||
requirement: "D-06, D-07"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-demo-app/chat_smoke_test.go#TestDemoChatTracer"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "Banned word in a chat message -> 422 errors.content, banned link in a forum title -> 422 errors.title, clean content stored; DM between two members; /demo and /tour listed and ephemeral"
|
||||
requirement: "D-17, D-08, D-05"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-demo-app/chat_smoke_test.go#TestDemoModerationSmoke"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "demo:seed EN/PL chat, forum, friends, moderator group, moderation lists; second run all exists; demo:reset --force wipes and reseeds, keeps moderation settings and the userfriends context"
|
||||
requirement: "D-09, D-22"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-demo-app/chat_smoke_test.go#TestSeedChatSmoke"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "scripts/dev.sh seed twice against the local Postgres: every new step 'created', then 'exists'"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "Every plugin activates, prefixes routed, go.mod tags only, pins match"
|
||||
requirement: "SC-1"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-demo-app/boot_test.go#TestBootAllPlugins, go_mod_test.go#TestGoModRequiresTags, scripts/check-pins.sh (25 modules), scripts/build.sh dev"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D5
|
||||
description: "Realtime token for any member (401 without JWT), Centrifugo namespaces, local LiveKit on 7890/7891/7892"
|
||||
requirement: "D-10, D-06"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-demo-app/realtime_test.go#TestRealtimeRoutes"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "dev.sh start_livekit (curl 127.0.0.1:7890 200); new binary on 127.0.0.1:8197: GO_ADDR=127.0.0.1:8197 scripts/check-local.sh realtime ok; fresh registered member: token, /chat, /chat/members 200"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: 33min
|
||||
completed: 2026-10-30
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 20 Plan 02: Demo backend for the chat family Summary
|
||||
|
||||
**sm-demo-app mounts all eight chat-family plugins at their tags and golem15.demo hosts them as one community. Every registered member can post in the seeded EN/PL channels, DM anyone, use /demo and /tour, post in the forum and get a realtime token. Moderation refuses banned words and links with 422, and a local LiveKit runs from scripts/dev.sh.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** about 33 min
|
||||
- **Started:** 2026-10-30T17:37:25Z
|
||||
- **Completed:** 2026-10-30T18:10:23Z
|
||||
- **Tasks:** 4/4
|
||||
- **Files modified:** 40 in sm-demo-app (2902 insertions, 111 deletions), 1 in summercms.go
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Eight `feat: mount golem15.<id> <tag>` commits. `summer.yaml` lists chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends and moderation after golem15.user and before golem15.demo. Every submodule describes as its tag, and `check-pins` reports ok for 25 modules.
|
||||
- Host types in `plugins/demo/classes`:
|
||||
- `DemoContext` (demo/1, `chat:context:1`).
|
||||
- `ChannelContext` (alias `channel`, `chat:channel:{id}`).
|
||||
- `ChatAccess`: members may access demo/1 and `CanManageContext` is always false.
|
||||
- `ForumAccess`.
|
||||
- `MemberIDs`, `IsMember` and `IsModerator`.
|
||||
- Membership means activated, not deleted and not banned (`user_throttle.is_banned`).
|
||||
- The bootstrap `GET /_demo/api/v1/chat` returns `{member, moderator, context, channels[], conversations[], limits}` and `/chat/members` returns `{members[]}`. Both need a JWT and are throttled at 120 a minute.
|
||||
- Listeners on MessageSaving and PostSaving call the moderation Filter. `/demo` and `/tour` answer ephemerally, in EN or PL from `preferred_locale`.
|
||||
- demo:seed adds eight steps. demo:reset clears 27 more tables in foreign-key order.
|
||||
- `demo.realtime-access` guards the token route. Centrifugo gets the namespaces chat, user and video. `deploy/livekit.yaml.example` is added, dev.sh starts and stops a local LiveKit, and the README has a chat family section.
|
||||
|
||||
## Task Commits
|
||||
|
||||
| # | Task | Repo | Commit | Message |
|
||||
|---|------|------|--------|---------|
|
||||
| 1 | Folded todo | summercms.go | d6f490a | docs(20-02): close the sm-demo-app journal/oauthserver pointer todo |
|
||||
| 1 | Mount chat | sm-demo-app | 7815001 | feat: mount golem15.chat v0.1.5 |
|
||||
| 1 | Mount chatchannels | sm-demo-app | 6edfae5 | feat: mount golem15.chatchannels v0.1.0 |
|
||||
| 1 | Tracer host wiring | sm-demo-app | 58ba678 | feat: demo chat context, channel adapter and bootstrap |
|
||||
| 2 | Mount chatbots | sm-demo-app | 47c7833 | feat: mount golem15.chatbots v0.1.0 |
|
||||
| 2 | Mount chatvideo | sm-demo-app | 5076d8c | feat: mount golem15.chatvideo v0.1.1 |
|
||||
| 2 | Mount forum | sm-demo-app | 2dea441 | feat: mount golem15.forum v0.1.1 |
|
||||
| 2 | Mount herald | sm-demo-app | 64d37a2 | feat: mount golem15.herald v0.1.1 |
|
||||
| 2 | Mount userfriends | sm-demo-app | a78c543 | feat: mount golem15.userfriends v0.1.1 |
|
||||
| 2 | Mount moderation | sm-demo-app | 864a14b | feat: mount golem15.moderation v0.1.0 |
|
||||
| 2 | Wiring | sm-demo-app | b03fe83 | feat: demo hosts forum, friends, slash commands and moderation |
|
||||
| 3 | Seed and reset | sm-demo-app | 4a94565 | feat: seed and reset the chat family (EN/PL) |
|
||||
| 4 | Realtime, members, deploy, dev | sm-demo-app | f4ed2c2 | feat: realtime for every demo member, members endpoint, Centrifugo namespaces and local LiveKit |
|
||||
|
||||
Nothing was pushed, tagged or deployed. No file inside a plugin submodule was edited.
|
||||
|
||||
## Details for later plans
|
||||
|
||||
**Channel join path:** the lazy join holds. `GET /_chat/api/v1/contexts/channel/{channelId}/conversation` reaches chat's `GetGroupChat`, which adds the caller as a participant of the existing backing conversation. TestDemoChatTracer asserts the participant row. The bootstrap fallback (`AddUserToGroupChat`) was not needed.
|
||||
|
||||
**Personas:** Ada Hart and Ben Carter (en), Ola Nowak and Tomek Wiśniewski (pl). Emails are `<key>@personas.demo.invalid`. Each gets a random bcrypt hash of 32 random bytes, never printed, and a handle from the user plugin's `AssignHandle`.
|
||||
|
||||
**Channels:**
|
||||
|
||||
| Channel | Slug | Language | Messages | Thread roots | Pins |
|
||||
|---------|------|----------|----------|--------------|------|
|
||||
| #general (default) | `general` | en | 13 | 2 | 1 |
|
||||
| #announcements | `announcements` | en | 5 | 1 | 1 |
|
||||
| #ogólny | `ogolny` | pl | 15 | 1 | 1 |
|
||||
|
||||
All three channels have reactions. Ada sends the visitor a welcome DM.
|
||||
|
||||
**Forum:** "General discussion" (`general-discussion`) and "Show and tell" (`show-and-tell`) in English and "Rozmowy" (`rozmowy`) in Polish, with 2, 2 and 3 threads and `content_html` from `breakwater.Render`.
|
||||
|
||||
**Friends:** accepted friendships ada-ben, ada-ola, ben-tomek and ola-tomek. Ola has a pending request to the visitor. The group "Demo crew" has Ada as owner and Ben and Tomek as members.
|
||||
|
||||
**Moderation defaults** (only while both lists are empty): words `buy followers`, `casino bonus`, `free crypto` and `viagra`; link `bit.ly`.
|
||||
|
||||
**Reset table order** (inserted before `users`, children first):
|
||||
1. chatvideo participants, sessions
|
||||
2. chatchannels channel_mentions, channel_pins, channel_members, channel_user_prefs, user_context_prefs, personal_categories, channels, channel_categories
|
||||
3. chat reactions, thread_mutes, thread_summaries, messages, participants, conversations
|
||||
4. forum thread_reads, posts, threads, categories
|
||||
5. userfriends group_bans, group_invites, group_members, groups, friendships
|
||||
6. herald push_subscriptions
|
||||
7. chatbots bot_flags
|
||||
|
||||
Chatchannels comes before chat because channels hang off their backing conversations. The reset keeps `golem15_moderation_settings`, `user_groups` (the moderator group) and `golem15_userfriends_contexts`. Chat attachments were already covered: the reset removes every `system_files` owner except the kept ones.
|
||||
|
||||
**Centrifugo option names** (v6.5.1, checked against `centrifugo defaultconfig`):
|
||||
- `chat`: `presence`, `join_leave`, `force_push_join_leave`, `allow_presence_for_subscriber` and `subscribe_proxy_enabled`.
|
||||
- `user` and `video`: `subscribe_proxy_enabled` only.
|
||||
|
||||
**Boot warnings left by plugins** (`dev.sh seed`):
|
||||
- The chatchannels and forum deny-all warnings fire from the plugins' own database hooks before golem15.demo's hook installs the resolvers, so they are expected.
|
||||
- `golem15.chatbots: BotAuthResolver is deny-all`. The demo has no bot persona.
|
||||
- `golem15.herald: PresenceGate is deny-all` and `golem15.herald: VAPID keys are missing`. Plan 04 handles these.
|
||||
|
||||
## Decisions Made
|
||||
|
||||
See the key-decisions list in the frontmatter. The plan's own discretion items (aliases, personas, slugs, commands, ports) were applied as written.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Folded todo needed no sm-demo-app commit**
|
||||
- **Found during:** Task 1 step 1
|
||||
- **Issue:** go.mod already required sm-oauthserver-plugin v0.1.6 and sm-journal-plugin v0.2.6 (2133309, 5ec5941), and the oauthserver checkout contains b6a9586. Bumping to v0.1.3 would have been a downgrade.
|
||||
- **Fix:** No `chore: bump sm-oauthserver-plugin to v0.1.3` commit. The todo moved to done with a note (d6f490a).
|
||||
|
||||
**2. [Rule 3 - Blocking] realtime_test.go namespaces updated in the mount commits**
|
||||
- **Found during:** Task 1 and Task 2 (mount chatvideo)
|
||||
- **Issue:** chat registers the `chat` namespace and chatvideo registers `video`, so the short suite failed.
|
||||
- **Fix:** `wantNamespaces` was extended in 58ba678 and 5076d8c, so `go test -short` stays green at every commit.
|
||||
|
||||
**3. [Rule 3 - Blocking] boot_test.go realtime subtest expected the old guard**
|
||||
- **Found during:** Task 4
|
||||
- **Fix:** It now expects `demo.realtime-access`, in f4ed2c2.
|
||||
|
||||
**4. [Rule 2 - Missing critical] Chat attachment cap**
|
||||
- **Issue:** chat's `max_message_bytes` defaults to 0 (no total limit) on a public demo, and the bootstrap reported 0.
|
||||
- **Fix:** `config/golem15.chat.yaml` sets 5 MiB per message (5 × the 1 MiB upload body limit), in b03fe83.
|
||||
|
||||
**5. [Rule 2] Production LiveKit URL**
|
||||
- **Fix:** Added `config/env/production/golem15.chatvideo.yaml` with `livekit_url: wss://demo.summercms.io/livekit`, so the committed `ws://127.0.0.1:7890` applies locally only (f4ed2c2).
|
||||
|
||||
**6. Scope order changes**
|
||||
- The `chat personas` step landed in Task 1, because #general's welcome message needs a sender. `users` can't send as a backend admin.
|
||||
- `/chat/members` assertions were added to TestDemoChatTracer in Task 4.
|
||||
|
||||
**7. The `pact.HasMiddleware` assertion sits in plugin.go**, as the plan asks. The middleware itself is in realtime_access.go.
|
||||
|
||||
**8. Forum RegisterContext not called.** Its only consumer is `forum:rewrite-context-types`. Listing and posting work without it.
|
||||
|
||||
### Verification adjustments
|
||||
|
||||
- **The Task 4 verify command `centrifugo checkconfig -c deploy/centrifugo.json.example` cannot pass as written.** Centrifugo picks the config type from the file extension ("Unsupported Config Type example"). I ran it on a `.json` copy instead, the way `scripts/check-deploy.sh` does. checkconfig passed, check-deploy passed, and every option name is in `centrifugo defaultconfig`.
|
||||
- **`scripts/dev.sh up` was not run as a whole.** The dev ports are held by stale processes that dev.sh did not start in this session and cannot stop:
|
||||
- Centrifugo on 8011 (pid 212066, Oct 22)
|
||||
- Go on 8097, run as user golem (pid 3405714, Oct 24)
|
||||
- Nuxt on 3020 from a cursor-agent session (pid 3776486, Oct 27)
|
||||
|
||||
Their pid files are stale, so `claim_port` would refuse, and killing other sessions' processes was out of bounds. What I verified instead:
|
||||
- **LiveKit:** started with dev.sh's own `ensure_env` and `start_livekit` functions. `curl 127.0.0.1:7890/` answered 200, TCP 7890/7891 and UDP 7892 were listening, `logs/livekit.yaml` is mode 600 with no CHANGE_ME left and `use_external_ip: false`.
|
||||
- **Realtime:** the new binary ran on 127.0.0.1:8197 against the local Postgres, and `GO_ADDR=127.0.0.1:8197 scripts/check-local.sh realtime` printed ok. A freshly registered member got 200 from the token route, `/_demo/api/v1/chat` and `/chat/members`.
|
||||
- **Seed:** `scripts/dev.sh seed` ran twice. The new steps were `created`, then `exists`.
|
||||
- Both of my processes were stopped afterwards.
|
||||
- **Mistake made and fixed:** my first attempt sourced dev.sh's functions from the scratchpad. Its `cd "$(dirname "$0")/.."` then landed in the meta repo `..`, where it wrote `.env`, `logs/` and `storage/app/uploads/public`. All three had been created seconds earlier by that run, and I removed them. Nothing else in the meta repo was touched.
|
||||
|
||||
**Total deviations:** 8 plus 2 verification adjustments. **Impact:** none on the plan goal.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- **g15office MCP unavailable** (connection timed out in this session). Task ssuyq2os (the folded todo) was **not** moved to Live and got no comment, and the Phase 20 task xo463rwk got no comment either. The orchestrator or the user needs to do both.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None. Every endpoint reads live data. The bootstrap reports `is_bot: false` for everyone on purpose, because the demo has no bot persona (D-05).
|
||||
|
||||
## Threat Flags
|
||||
|
||||
| Flag | File | Description |
|
||||
|------|------|-------------|
|
||||
| threat_flag: endpoint | ../sm-demo-app/plugins/demo/chat_api.go | `/chat/members` lists every member's name, surname and handle to any member (planned in T-20 scope; no email or id beyond the user id) |
|
||||
| threat_flag: config | ../sm-demo-app/config/golem15.chat.yaml | Upload cap 5 MiB per message on the public demo (mitigation, not new surface) |
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None for this plan. Plan 05 needs the LiveKit key pair on rome (`deploy/env.example`).
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Plan 03 (vue-chat-layer) can build on `GET /_demo/api/v1/chat` and `/chat/members` as documented in sm-demo-app README "Chat family". Channels are opened with `GET /_chat/api/v1/contexts/channel/{id}/conversation`.
|
||||
- Plan 05 deploys `deploy/livekit.yaml.example`, the Centrifugo namespaces (restart summercms-demo-centrifugo), nginx `/livekit/` and the Go allow-list, and the herald VAPID keys.
|
||||
|
||||
---
|
||||
*Phase: 20-demo-instance-with-every-shared-plugin*
|
||||
*Completed: 2026-10-30*
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- All 15 created files listed under key-files exist, and the todo is under `.planning/todos/done/`.
|
||||
- sm-demo-app commits 7815001, 6edfae5, 58ba678, 47c7833, 5076d8c, 2dea441, 64d37a2, a78c543, 864a14b, b03fe83, 4a94565, f4ed2c2 and summercms.go d6f490a exist.
|
||||
- `git -C ../sm-demo-app submodule status` shows no `+` or `-`, and the sm-demo-app working tree is clean (`--ignore-submodules=none`).
|
||||
@@ -0,0 +1,446 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 03
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on: ["20-02"]
|
||||
files_modified:
|
||||
- ../vue-chat-layer/.gitignore
|
||||
- ../vue-chat-layer/.nvmrc
|
||||
- ../vue-chat-layer/package.json
|
||||
- ../vue-chat-layer/pnpm-lock.yaml
|
||||
- ../vue-chat-layer/pnpm-workspace.yaml
|
||||
- ../vue-chat-layer/tsconfig.json
|
||||
- ../vue-chat-layer/nuxt.config.ts
|
||||
- ../vue-chat-layer/vitest.config.ts
|
||||
- ../vue-chat-layer/README.md
|
||||
- ../vue-chat-layer/.playground/nuxt.config.ts
|
||||
- ../vue-chat-layer/.playground/app/app.vue
|
||||
- ../vue-chat-layer/app/lib/client.ts
|
||||
- ../vue-chat-layer/app/lib/types.ts
|
||||
- ../vue-chat-layer/app/lib/realtime.ts
|
||||
- ../vue-chat-layer/app/lib/chatEvents.ts
|
||||
- ../vue-chat-layer/app/lib/chatFormat.ts
|
||||
- ../vue-chat-layer/app/lib/chatText.ts
|
||||
- ../vue-chat-layer/app/lib/chatUnread.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.ts
|
||||
- ../vue-chat-layer/app/lib/format.ts
|
||||
- ../vue-chat-layer/app/lib/media.ts
|
||||
- ../vue-chat-layer/app/lib/tabs.ts
|
||||
- ../vue-chat-layer/app/composables/useChatApi.ts
|
||||
- ../vue-chat-layer/app/composables/useChat.ts
|
||||
- ../vue-chat-layer/app/composables/useChatNotice.ts
|
||||
- ../vue-chat-layer/app/components/Chat/Page.vue
|
||||
- ../vue-chat-layer/app/components/Chat/ChannelList.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Panel.vue
|
||||
- ../vue-chat-layer/app/components/Chat/MessageList.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Message.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Composer.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Header.vue
|
||||
- ../vue-chat-layer/app/components/Chat/DmList.vue
|
||||
- ../vue-chat-layer/app/components/Chat/MemberPicker.vue
|
||||
- ../vue-chat-layer/app/components/Chat/MentionPopup.vue
|
||||
- ../vue-chat-layer/app/components/Chat/ReactionBar.vue
|
||||
- ../vue-chat-layer/app/components/Chat/LinkEmbed.vue
|
||||
- ../vue-chat-layer/app/components/Chat/StagingChips.vue
|
||||
- ../vue-chat-layer/app/components/Chat/DeleteDialog.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Avatar.vue
|
||||
- ../vue-chat-layer/app/components/Chat/ThreadPane.vue
|
||||
- ../vue-chat-layer/app/components/Chat/PinsPanel.vue
|
||||
- ../vue-chat-layer/app/components/Chat/CommandPicker.vue
|
||||
- ../vue-chat-layer/app/components/Chat/FloatingPanel.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Icon.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Notices.vue
|
||||
- ../vue-chat-layer/app/assets/css/chat-tokens.css
|
||||
- ../vue-chat-layer/app/assets/css/chat-base.css
|
||||
- ../vue-chat-layer/i18n/locales/en.json
|
||||
- ../vue-chat-layer/i18n/locales/pl.json
|
||||
- ../vue-chat-layer/tests/smoke.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/package.json
|
||||
- ../sm-demo-app/vue-demo-app/pnpm-lock.yaml
|
||||
- ../sm-demo-app/vue-demo-app/nuxt.config.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/layouts/default.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/chat.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/TourCard.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/lib/realtime.ts
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
|
||||
- ../sm-demo-app/scripts/check-chat.cjs
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/smoke.sh
|
||||
autonomous: false
|
||||
requirements: [SC-2, D-01, D-02, D-03, D-04, D-05, D-07, D-20, D-22, D-23]
|
||||
estimate:
|
||||
tokens: 380000
|
||||
raw_tokens: 380000
|
||||
tasks: 6
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "D-01: vue-chat-layer is a new shared Nuxt layer (own repository, tag v0.1.0) ported from the bm SPA's chat components, store, API client and chat libraries, with no Pinia (state is useState composables), no bm entity embeds and no name of a consuming application; host specifics enter only through runtime config (public.chat.hostApiBase), the $chatAuth hook, slots and the link-embed renderer registry."
|
||||
- "D-02: on /chat a logged-in member sees the seeded channels in a sidebar, opens one, reads history, sends and edits messages, replies in threads (thread pane), sees typing, unread and mention counts, adds and removes reactions, attaches files, mentions members with @, picks a DM partner from the member picker, deletes own messages (moderators also others' in channels, D-22) through the delete dialog, sees channel pins and sees URLs as links with a generic link embed."
|
||||
- "D-03: every page of vue-demo-app shows a floating chat panel (DM list and unread badge) for logged-in users (not on /chat and not on the full-screen deck pages); the homepage tour has a Chat card; the site is EN and PL."
|
||||
- "D-04: an anonymous visitor on /chat sees a description and a register-to-chat link to /register?next=/chat; there is no read-only preview, and the floating panel is not rendered."
|
||||
- "D-05: typing / at the start of the composer opens a command picker filled from GET /_chatbots/api/v1/commands; choosing or sending a command calls POST /_chatbots/api/v1/dispatch and shows the ephemeral answer only to the sender; there is no chatbots layer."
|
||||
- "D-07: the layer offers no channel creation UI; members join and leave seeded channels."
|
||||
- "D-23 (extension point): the conversation header exposes a slot that the layer renders only for DM conversations, so a call button placed there (plan 04) appears only in DMs."
|
||||
- "SC-2: messages from another member arrive without reload through the shared Centrifuge client (one connection per page, shared with the presentations remote through vue-demo-app's app/lib/realtime.ts re-export)."
|
||||
- "After the Task 5 go-ahead, git.golem15.com/golem15/vue-chat-layer exists with tag v0.1.0 and vue-demo-app pins git+https://git.golem15.com/golem15/vue-chat-layer.git#v0.1.0 in a committed package.json and pnpm-lock.yaml."
|
||||
artifacts:
|
||||
- path: "../vue-chat-layer/nuxt.config.ts"
|
||||
provides: "layer config: runtimeConfig chat.apiBase, public.chat.hostApiBase, css, i18n registration (no routes, no route rules)"
|
||||
contains: "hostApiBase"
|
||||
- path: "../vue-chat-layer/app/composables/useChat.ts"
|
||||
provides: "useState-based chat store (channels, DMs, threads, unread, typing, realtime)"
|
||||
contains: "useState"
|
||||
- path: "../vue-chat-layer/app/lib/realtime.ts"
|
||||
provides: "one shared Centrifuge client with connect, subscribe, presence, openChannel and onUserEvent"
|
||||
contains: "onUserEvent"
|
||||
- path: "../vue-chat-layer/app/lib/linkEmbeds.ts"
|
||||
provides: "linkify and the link-embed renderer registry (registerEmbedRenderer)"
|
||||
contains: "registerEmbedRenderer"
|
||||
- path: "../vue-chat-layer/app/components/Chat/CommandPicker.vue"
|
||||
provides: "slash command picker over the chatbots catalog and dispatch"
|
||||
contains: "dispatch"
|
||||
- path: "../sm-demo-app/vue-demo-app/app/pages/chat.vue"
|
||||
provides: "/chat: ChatPage for members, register prompt for anonymous visitors"
|
||||
contains: "registerToChat"
|
||||
- path: "../sm-demo-app/scripts/check-chat.cjs"
|
||||
provides: "Playwright check: the visitor sends a message in #general on /chat"
|
||||
contains: "check-chat: ok"
|
||||
key_links:
|
||||
- from: "../vue-chat-layer/app/composables/useChatApi.ts"
|
||||
to: "../sm-demo-app/vue-demo-app/app/plugins/auth.ts"
|
||||
via: "the layer reads useNuxtApp().$chatAuth {token, refresh, unauthorized}; the app provides it"
|
||||
pattern: "chatAuth"
|
||||
- from: "../vue-chat-layer/app/composables/useChat.ts"
|
||||
to: "../sm-demo-app/plugins/demo/chat_api.go"
|
||||
via: "bootstrap GET {public.chat.hostApiBase}/chat and /chat/members"
|
||||
pattern: "hostApiBase"
|
||||
- from: "../sm-demo-app/vue-demo-app/app/lib/realtime.ts"
|
||||
to: "../vue-chat-layer/app/lib/realtime.ts"
|
||||
via: "re-export so presentations and chat share one connection"
|
||||
pattern: "vue-chat-layer/app/lib/realtime"
|
||||
- from: "../sm-demo-app/vue-demo-app/app/layouts/default.vue"
|
||||
to: "../vue-chat-layer/app/components/Chat/FloatingPanel.vue"
|
||||
via: "ClientOnly ChatFloatingPanel when logged in"
|
||||
pattern: "ChatFloatingPanel"
|
||||
prohibitions:
|
||||
- statement: "vue-chat-layer names no consuming application and has no default host bootstrap path."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "No message, name or attachment field is rendered with v-html except the escaped output of the ported chatText renderer."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "No Pinia and no new npm package except those already pinned in the workspace (centrifuge 5.7.3, @nuxtjs/i18n 10.4.0, vitest 3.2.7, nuxt 4.4.8, vue 3.5.35, typescript 5.9.3)."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "Nothing is pushed and no repository is created before the Task 5 go-ahead; vue-demo-app is not pushed in this plan (plan 05)."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): the demo's public Nuxt site shows the shared plugins working, chat and channels with realtime included, through the shared layers.
|
||||
|
||||
This plan's slice (plan 3 of 6, wave 3, per D-20): `vue-chat-layer` v0.1.0, ported from bm's chat SPA and widened to several channels, threads, pins, a command picker and generic link embeds, then used in vue-demo-app as `/chat`, a floating panel and a tour card, in EN and PL.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Layout of the layer:** pure modules in `app/lib/` (imported explicitly, never auto-imported, so generic names like `initials` cannot clash with an app's utils). Composables `useChat`, `useChatApi` and `useChatNotice` in `app/composables/`. Components in `app/components/Chat/`, auto-registered with the `Chat` prefix (`ChatPage`, `ChatFloatingPanel`). The layer ships components; the app owns routes, page copy and the anonymous prompt (as vue-paymentgateway-layer does).
|
||||
- **Host contract:** `runtimeConfig.public.chat.hostApiBase` defaults to an empty string, and the layer refuses to bootstrap without it, with a console error naming the key. vue-demo-app sets `/_demo/api/v1`. The README documents the `GET {hostApiBase}/chat` and `/chat/members` JSON shapes as the contract any host implements, under neutral names.
|
||||
- **Auth hook:** `$chatAuth` with `token(): string | null`, `refresh(): Promise<string | null>` and `unauthorized(): void`. One refresh-and-retry on 401 (bm's client renews through `/_user/api/v1/fetch`), then `unauthorized()`.
|
||||
- **Store:** bm's Pinia setup store becomes a module-level composable over `useState` keys prefixed `chat:` (19.4.1 no-Pinia rule). `general`/`generalId` become `channels[]` and `activeId`.
|
||||
- **Realtime:** bm's current `lib/realtime.ts` (shared client) is ported with `onUserEvent(handler)`, so other layers (chatvideo, plan 04) get `user:{me}` events they do not own without a second subscription. vue-demo-app's `app/lib/realtime.ts` becomes a re-export, so the presentations remote and chat share one WebSocket.
|
||||
- **Embeds:** bm's entity embeds and picker are dropped. URLs in text are linkified (escaped, `rel="noopener noreferrer nofollow"`, `target="_blank"`). A message with a URL shows a `ChatLinkEmbed` card with host and path; there is no unfurl backend. `registerEmbedRenderer(match, component)` lets a host render its own entity links (D-01 extension point).
|
||||
- **Extension slots:** `conversation-actions` in ChatHeader, rendered only for `type === 'dm'` (D-23), and `sidebar-footer` in ChannelList (the friends link, plan 04).
|
||||
- **Floating panel:** hidden on `/chat`, `/p/**` and `/presentations/**` (full-screen decks) and for anonymous visitors.
|
||||
- **Development pin:** while the layer has no remote, vue-demo-app depends on `link:../../vue-chat-layer`, committed with the first vue-demo-app commit so every commit builds on this machine. Task 6 replaces it with the tag pin; vue-demo-app is pushed only in plan 05, after the swap, so no pushed commit needs the local path.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
## Artifacts this phase produces (this plan)
|
||||
|
||||
- Repository `vue-chat-layer` (tag v0.1.0):
|
||||
- components `ChatPage`, `ChatChannelList`, `ChatPanel`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatHeader`, `ChatDmList`, `ChatMemberPicker`, `ChatMentionPopup`, `ChatReactionBar`, `ChatLinkEmbed`, `ChatStagingChips`, `ChatDeleteDialog`, `ChatAvatar`, `ChatThreadPane`, `ChatPinsPanel`, `ChatCommandPicker`, `ChatFloatingPanel`, `ChatIcon`, `ChatNotices`;
|
||||
- composables `useChat`, `useChatApi`, `useChatNotice`;
|
||||
- lib exports: `createChatClient`, `REALTIME_WS_PATH`, `connect`, `subscribe`, `presence`, `openChannel`, `onUserEvent`, `disconnect`, `linkify`, `registerEmbedRenderer`, `embedRendererFor`, and the ported chatEvents, chatFormat, chatText and chatUnread functions;
|
||||
- runtime config `chat.apiBase` (`NUXT_CHAT_API_BASE`), `public.chat.apiBase`, `public.chat.channelsApiBase`, `public.chat.botsApiBase`, `public.chat.hostApiBase`;
|
||||
- Nuxt plugin hook `$chatAuth`; slots `conversation-actions` and `sidebar-footer`; i18n keys under `chat.*` (EN and PL);
|
||||
- smoke test `tests/smoke.test.ts`.
|
||||
- vue-demo-app: page `/chat`, the floating panel in the default layout, Chat tour card (TourCard icon `chat`), i18n keys `chat.*` and `tour.chat.*`, goPaths `/_chat`, `/_chatchannels`, `/_chatbots`, ChatPage inside ClientOnly (the page itself is server-rendered so the banner and the anonymous prompt are in the HTML), `chatAuth` provided in app/plugins/auth.ts, app/lib/realtime.ts re-exporting the layer client.
|
||||
- sm-demo-app: `scripts/check-chat.cjs`, check-local check `chat`, check-local `tour` expecting the Chat card, smoke.sh covering `/chat`.
|
||||
|
||||
<objective>
|
||||
Build and release vue-chat-layer v0.1.0 and put chat on the demo site: `/chat`, the floating panel, the Chat tour card and the anonymous prompt, in EN and PL.
|
||||
|
||||
Purpose: SC-2 (chat and channels with realtime on the public site), D-01 to D-05, D-07 (no channel creation), D-22 (moderator delete) and the D-23 extension point plan 04 uses.
|
||||
Output: a new repository vue-chat-layer (pushed and tagged after the go-ahead), commits in ../sm-demo-app/vue-demo-app (the submodule; not pushed) and ../sm-demo-app (scripts; not pushed).
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-RESEARCH.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-PATTERNS.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-02-SUMMARY.md
|
||||
|
||||
Repos: new ../vue-chat-layer; ../sm-demo-app/vue-demo-app (the submodule, origin golem15/vue-demo-app; never the stale ../vue-demo-app sibling); ../sm-demo-app (scripts). Read-only port source: ../sm-bm-app/frontend/src (components/chat/*, stores/chat.ts and chat.test.ts, api/chat.ts, api/types.ts, lib/chat*.ts, lib/realtime.ts, lib/format.ts, lib/media.ts, lib/tabs.ts, components/Icon.vue). Layer conventions: ../vue-faq-layer and ../vue-paymentgateway-layer.
|
||||
|
||||
Rules: no co-author tags; stage by explicit path; the layer repository gets no remote before Task 5; vue-demo-app is committed in its own repository (never staged from sm-demo-app) and not pushed here; check `git -C ../sm-demo-app/vue-demo-app status --porcelain` before each commit and leave other sessions' edits alone (Phase 33 also edits nuxt.config.ts). The local dev stack runs with `../sm-demo-app/scripts/dev.sh up` (Go 127.0.0.1:8097, Nuxt 127.0.0.1:3020, Centrifugo, LiveKit). Playwright is the global install (`NODE_PATH="$(npm root -g)"`, scripts/lib/browser.cjs).
|
||||
|
||||
<interfaces>
|
||||
Host bootstrap (plan 02, ../sm-demo-app/plugins/demo/chat_api.go): GET /_demo/api/v1/chat gives {member, moderator, context: {type, id}, channels: [{id, slug, name, conversation_id, joined, unread, mentions}], conversations: [{id, type: "dm", other_user_id, unread, last_message: {id, sender_id, content, created_at}}], limits: {max_files, max_bytes, max_embeds}}; GET /_demo/api/v1/chat/members gives {members: [{id, name, surname, handle, is_bot}]}.
|
||||
chat API /_chat/api/v1: GET|POST /contexts/{type}/{id}/conversation; GET|POST /conversations/{id}/messages; POST /conversations/{id}/read, /typing, /mute; GET|PUT|DELETE /messages/{id}; GET /reactions; POST /messages/{id}/reactions; DELETE /messages/{id}/reactions/{key}; GET|POST /messages/{id}/replies; PUT /threads/{rootId}/mute; POST /attachments (multipart, body limit); GET /attachments/{messageId}/{fileId}; POST /contexts/{type}/{id}/dm. 422 envelope {"error":"Validation failed","errors":{field:[msg]}}, other refusals {"error": msg}, IDOR 404.
|
||||
chatchannels /_chatchannels/api/v1/contexts/demo/1: GET channels, POST channels/{id}/join and /leave, GET|POST channels/{id}/pins, DELETE channels/{id}/pins/{messageId}, GET channels/{id}/mentions, GET mentions.
|
||||
chatbots /_chatbots/api/v1: GET /commands gives {commands: [{trigger, description}]}; POST /dispatch {input} gives {mode, payload}; unknown gives 422 errors.input.
|
||||
Realtime: token GET /api/realtime/token; WebSocket /ws; channels user:{me} (chat:message, typing, read, unread, deleted, reacted, updated events per bm's chatEvents.ts; video:* from chatvideo), chat:conversation:{id}.
|
||||
vue-demo-app today: nuxt.config.ts (`goPaths`, `extends`, `runtimeConfig`, `routeRules`, `robots.disallow: goPaths`), app/plugins/auth.ts (`paymentGatewayAuth`), app/utils/authCookie.ts (`DEMO_TOKEN_COOKIE`), app/composables/useDemoAuth.ts (`loggedIn`), app/pages/quizzes/index.vue (anonymous prompt with `registerLink` and `quiz.registerToTake`), app/pages/index.vue (`stops`, TourCard), app/components/TourCard.vue (`icon` union, `ICONS` paths), app/lib/realtime.ts (openChannel subset of bm's file), vitest.config.ts (app/**/*.test.ts), package.json (centrifuge 5.7.3, layers pinned by git+https tag).
|
||||
Layer analogs: ../vue-faq-layer/nuxt.config.ts (currentDir, absolute paths, runtimeConfig), ../vue-paymentgateway-layer/nuxt.config.ts (i18n:registerModule for EN/PL), app/composables/usePaymentGatewayApi.ts (auth hook through useNuxtApp), package.json (main nuxt.config.ts, peerDependencies nuxt 4.4.8, engines node >=22.18).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: a logged-in visitor opens /chat, picks #general from the seeded channels and sends a message that appears; an anonymous visitor gets the register prompt</name>
|
||||
<reversibility rating="costly">D-01: a public layer with tagged releases that later sites pin; its runtime-config keys, auth hook and bootstrap contract become a contract.</reversibility>
|
||||
<precondition>The plan 02 SUMMARY exists; `../sm-demo-app/scripts/dev.sh up` brings the stack up and `curl -fsS http://127.0.0.1:8097/_demo/api/v1/roadmap` answers; `git -C ../sm-demo-app/vue-demo-app status --porcelain` lists no file this task changes.</precondition>
|
||||
<files>../vue-chat-layer/.gitignore, ../vue-chat-layer/.nvmrc, ../vue-chat-layer/package.json, ../vue-chat-layer/pnpm-lock.yaml, ../vue-chat-layer/pnpm-workspace.yaml, ../vue-chat-layer/tsconfig.json, ../vue-chat-layer/nuxt.config.ts, ../vue-chat-layer/vitest.config.ts, ../vue-chat-layer/.playground/nuxt.config.ts, ../vue-chat-layer/.playground/app/app.vue, ../vue-chat-layer/app/lib/client.ts, ../vue-chat-layer/app/lib/types.ts, ../vue-chat-layer/app/composables/useChatApi.ts, ../vue-chat-layer/app/composables/useChat.ts, ../vue-chat-layer/app/components/Chat/Page.vue, ../vue-chat-layer/app/components/Chat/ChannelList.vue, ../vue-chat-layer/app/components/Chat/MessageList.vue, ../vue-chat-layer/app/components/Chat/Composer.vue, ../vue-chat-layer/tests/smoke.test.ts, ../sm-demo-app/vue-demo-app/package.json, ../sm-demo-app/vue-demo-app/nuxt.config.ts, ../sm-demo-app/vue-demo-app/app/plugins/auth.ts, ../sm-demo-app/vue-demo-app/app/pages/chat.vue, ../sm-demo-app/vue-demo-app/i18n/locales/en.json, ../sm-demo-app/vue-demo-app/i18n/locales/pl.json, ../sm-demo-app/scripts/check-chat.cjs, ../sm-demo-app/scripts/check-local.sh</files>
|
||||
<read_first>../vue-faq-layer/{nuxt.config.ts,package.json,pnpm-workspace.yaml,tsconfig.json,.gitignore,.nvmrc,.playground/nuxt.config.ts}, ../vue-paymentgateway-layer/nuxt.config.ts and app/composables/usePaymentGatewayApi.ts and app/utils/client.ts, ../sm-bm-app/frontend/src/api/chat.ts and api/types.ts, ../sm-bm-app/frontend/src/stores/chat.ts (bootstrap, open, send), ../sm-bm-app/frontend/src/components/chat/{ChatPanel,MessageList,ChatComposer}.vue, ../sm-demo-app/plugins/demo/chat_api.go, ../sm-demo-app/vue-demo-app/{nuxt.config.ts,package.json,app/plugins/auth.ts,app/pages/quizzes/index.vue,app/composables/useDemoAuth.ts,app/utils/authCookie.ts,i18n/locales/en.json}, ../sm-demo-app/scripts/check-local.sh (visitor_jwt, check_remote, ALL_CHECKS), ../sm-demo-app/scripts/check-remote.cjs and scripts/lib/browser.cjs, 20-PATTERNS.md (vue-chat-layer)</read_first>
|
||||
<action>Per D-01, D-04, D-07, SC-2. One path through every layer: app page, layer component, store, client, host bootstrap, chat API, database, back to the list.
|
||||
|
||||
1. Create the repository: `git init -b main` at /media/nvme/dev/golem15/summercms.io/summercms/vue-chat-layer with the vue-faq-layer files (.gitignore, .nvmrc, tsconfig.json, pnpm-workspace.yaml allowing the same builds plus `protobufjs: false`).
|
||||
- package.json: name vue-chat-layer, version 0.1.0, private, type module, main ./nuxt.config.ts, engines node >=22.18, peerDependencies nuxt 4.4.8;
|
||||
- dependencies centrifuge 5.7.3 and @nuxtjs/i18n 10.4.0; devDependencies nuxt 4.4.8, vue 3.5.35, typescript 5.9.3, vitest 3.2.7;
|
||||
- scripts test (`vitest run`), dev (`nuxi dev .playground`), build:playground and dev:prepare.
|
||||
Run pnpm install.
|
||||
2. nuxt.config.ts:
|
||||
- the header comment says an app consumes it with `extends: ['vue-chat-layer']`, provides `$chatAuth` and sets `public.chat.hostApiBase`; currentDir with absolute paths;
|
||||
- runtimeConfig.chat.apiBase for SSR (`http://127.0.0.1:8096/_chat/api/v1`, NUXT_CHAT_API_BASE);
|
||||
- public.chat: apiBase `/_chat/api/v1`, channelsApiBase `/_chatchannels/api/v1`, botsApiBase `/_chatbots/api/v1`, hostApiBase empty;
|
||||
- no pages and no route rules: the app owns its routes and wraps the chat components in ClientOnly (the components touch window and WebSocket, RESEARCH Pitfall 9);
|
||||
- the i18n:registerModule block of vue-paymentgateway-layer for en and pl (strings come in Task 3; create empty-object locale files now if the module needs them).
|
||||
3. app/lib/client.ts: `createChatClient({ bases, auth, fetch })`, pure and Nuxt-free so tests import it. It builds URLs, sends Bearer from `auth.token()`, retries once after `auth.refresh()` on 401 and then calls `auth.unauthorized()`, and turns the 422 envelope into a typed `ChatApiError` with field errors. Methods for the tracer: `bootstrap()`, `members()`, `openConversation(type, id)`, `messages(conversationId, opts)` and `send(conversationId, body)`. app/lib/types.ts holds the bootstrap and message types ported from bm's api/types.ts. app/composables/useChatApi.ts binds the client to runtime config and `useNuxtApp().$chatAuth`, following usePaymentGatewayApi.
|
||||
4. app/composables/useChat.ts, minimal for now, over `useState('chat:…')`: `start()` loads the bootstrap (and logs a console error, then stops, when hostApiBase is empty); `channels`; `activeId`; `open(channel)` calls openConversation('channel', channel.id) then messages; `send(text)`.
|
||||
5. Components ChatPage (sidebar plus pane), ChatChannelList (channel names, no create button), ChatMessageList (plain text in this task) and ChatComposer (textarea plus send). No v-html.
|
||||
6. vue-demo-app:
|
||||
- run `pnpm --dir ../sm-demo-app/vue-demo-app add vue-chat-layer@link:../../vue-chat-layer` (development pin, committed with this task's vue-demo-app commit; Task 6 swaps it for the tag before any push);
|
||||
- nuxt.config.ts: append 'vue-chat-layer' to extends; add '/_chat', '/_chatchannels' and '/_chatbots' to goPaths; set `public.chat.hostApiBase: '/_demo/api/v1'` and `chat.apiBase` from `api`; no route rule for /chat (the page is server-rendered with the chat inside ClientOnly, so smoke.sh still sees the banner and the prompt);
|
||||
- app/plugins/auth.ts provides `chatAuth: { token, refresh, unauthorized }`. token reads DEMO_TOKEN_COOKIE. refresh calls the user plugin's refresh endpoint that the login flow uses (read useDemoAuth) and stores the new token. unauthorized clears the cookie;
|
||||
- app/pages/chat.vue: for loggedIn, `<ClientOnly><ChatPage /></ClientOnly>`; otherwise a description and a `NuxtLink class="button"` to `{ path: '/register', query: { next: '/chat' } }` labelled `t('chat.registerToChat')`, as the quizzes page does. useSeoMeta with title and description;
|
||||
- i18n en and pl: chat.title, chat.lead and chat.registerToChat.
|
||||
7. sm-demo-app/scripts/check-chat.cjs (CommonJS, Playwright, modeled on check-remote.cjs):
|
||||
- `--base` (Nuxt origin) and DEMO_JWT from the environment;
|
||||
- sets the DEMO_TOKEN_COOKIE cookie with the JWT, opens {base}/chat, clicks the channel whose name is general and sends a unique text;
|
||||
- waits up to 10 s for the text in the message list, then fails on a console error or a 4xx/5xx response from /_chat;
|
||||
- opens {base}/chat in a fresh context without the cookie and asserts the register link to /register?next=/chat;
|
||||
- prints `check-chat: ok`.
|
||||
check-local.sh gets `check_chat`, which takes visitor_jwt and runs the script as check_remote does, and `chat` in ALL_CHECKS plus the header list.
|
||||
8. tests/smoke.test.ts (vitest): createChatClient builds `/_chat/api/v1/conversations/7/messages`, sends the Bearer header, retries once on 401 after refresh and maps a 422 body to field errors.
|
||||
|
||||
Commit vue-chat-layer (`feat: chat layer tracer: bootstrap, channel list, messages, composer`). Commit vue-demo-app package.json, pnpm-lock.yaml (link pin), nuxt.config.ts, auth.ts, chat.vue and locales by path (`feat: /chat page on vue-chat-layer`). Commit sm-demo-app scripts (`test: check-chat browser check`).</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chat-layer test && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/dev.sh up && ../sm-demo-app/scripts/check-local.sh chat</automated>
|
||||
<fails_when>Non-zero exit: the layer smoke test fails; the Nuxt build fails (layer not resolved, type or template error); the stack does not come up; or check-local prints "check-local: chat failed" (the sent text does not appear, /_chat answered 4xx/5xx, or the anonymous page lacks the register link).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../vue-chat-layer remote` prints nothing.
|
||||
- `grep -c "hostApiBase: ''" ../vue-chat-layer/nuxt.config.ts` prints 1.
|
||||
- `grep -rniE 'sm-bm|jz\.bm|_demo/api' ../vue-chat-layer/app ../vue-chat-layer/nuxt.config.ts ../vue-chat-layer/README.md 2>/dev/null | wc -l` prints 0.
|
||||
- `grep -c "'/_chat'" ../sm-demo-app/vue-demo-app/nuxt.config.ts` prints 1.
|
||||
- `node -p "require('../sm-demo-app/vue-demo-app/package.json').dependencies['vue-chat-layer']"` prints `link:../../vue-chat-layer` (the development pin, swapped in Task 6).
|
||||
</acceptance_criteria>
|
||||
<done>A visitor can chat in #general on the local demo site through the new layer, and an anonymous visitor is invited to register.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: The bm chat experience on the layer: realtime, DMs, member picker, mentions, unread counts and typing</name>
|
||||
<files>../vue-chat-layer/app/lib/realtime.ts, ../vue-chat-layer/app/lib/chatEvents.ts, ../vue-chat-layer/app/lib/chatFormat.ts, ../vue-chat-layer/app/lib/chatText.ts, ../vue-chat-layer/app/lib/chatUnread.ts, ../vue-chat-layer/app/lib/format.ts, ../vue-chat-layer/app/lib/media.ts, ../vue-chat-layer/app/lib/tabs.ts, ../vue-chat-layer/app/lib/client.ts, ../vue-chat-layer/app/composables/useChat.ts, ../vue-chat-layer/app/composables/useChatNotice.ts, ../vue-chat-layer/app/components/Chat/Panel.vue, ../vue-chat-layer/app/components/Chat/MessageList.vue, ../vue-chat-layer/app/components/Chat/Message.vue, ../vue-chat-layer/app/components/Chat/Composer.vue, ../vue-chat-layer/app/components/Chat/Header.vue, ../vue-chat-layer/app/components/Chat/DmList.vue, ../vue-chat-layer/app/components/Chat/MemberPicker.vue, ../vue-chat-layer/app/components/Chat/MentionPopup.vue, ../vue-chat-layer/app/components/Chat/Avatar.vue, ../vue-chat-layer/app/components/Chat/Icon.vue, ../vue-chat-layer/app/components/Chat/Notices.vue, ../vue-chat-layer/app/components/Chat/Page.vue, ../sm-demo-app/vue-demo-app/app/lib/realtime.ts</files>
|
||||
<read_first>../sm-bm-app/frontend/src/stores/chat.ts (whole store), stores/chat.test.ts, lib/realtime.ts, lib/chatEvents.ts, lib/chatFormat.ts, lib/chatText.ts, lib/chatUnread.ts, lib/format.ts, lib/media.ts, lib/tabs.ts, components/Icon.vue, components/chat/{ChatPanel,MessageList,ChatMessage,ChatComposer,ChatHeader,DmList,MemberPicker,MentionPopup,Avatar}.vue, ../sm-demo-app/vue-demo-app/app/lib/realtime.ts and realtime.test.ts, app/pages/presentations/[slug]/index.vue and pilot.vue (openChannel callers), ../vue-chat-layer/app/composables/useChat.ts (Task 1), 20-RESEARCH.md (Pattern 3, Pitfall 9)</read_first>
|
||||
<action>Per D-01, D-02, SC-2.
|
||||
|
||||
- Port bm's lib/realtime.ts into app/lib/realtime.ts. It keeps the same exports (REALTIME_WS_PATH, tokenFailureIsFinal, wsURL, connect, subscribe, presence, onConnection, onUnavailable, realtimeState, realtimeUnavailable, disconnect, openChannel). The token is fetched from `/api/realtime/token` with the `$chatAuth` token through a setter `setRealtimeAuth(getToken)`, so the module stays Nuxt-free. `centrifuge` is loaded with a dynamic import. Add `onUserEvent(handler): () => void`: the chat store's `user:{me}` subscription hands every event it does not handle to the registered handlers, so a second layer never subscribes to `user:{me}` itself.
|
||||
- Port chatEvents, chatFormat, chatText and chatUnread unchanged except for import paths, and the helpers they need from format, media and tabs. The bm tests come in plan 06. chatText's renderer escapes before it marks mentions; keep it the only raw-HTML binding in the layer.
|
||||
- useChat: port bm's store as a composable over useState. Replace `general` and `generalId` with `channels`, `activeId` and a `kind` ('channel' or 'dm') for the open conversation. Keep:
|
||||
- DMs (`conversations`; `openDm(userId)` through POST /contexts/demo/1/dm, using the context from the bootstrap);
|
||||
- the member list from `/chat/members`;
|
||||
- unread and mention counts, read marks and typing, with bm's polling fallback when realtime is unavailable (15 s open conversation, 60 s counts);
|
||||
- realtime start for a member session, edits and deletions from events.
|
||||
Channel join and leave call chatchannels join and leave and refresh the bootstrap. Errors go to useChatNotice (a small toast state rendered by ChatNotices inside ChatPage and the floating panel), replacing bm's toast store.
|
||||
- Port the components ChatPanel, ChatMessageList, ChatMessage (text through chatText, attachment rendering in Task 3), ChatComposer (mention popup, Enter to send, Shift+Enter newline), ChatHeader (unread and mention badges), ChatDmList, ChatMemberPicker, ChatMentionPopup and ChatAvatar, plus ChatIcon with the icons they use. ChatPage composes sidebar (channels, DMs, a new-DM button opening the member picker) and pane. Strip every bm-specific element (entity embeds, deadline pins, the student app's tabs) or leave a named slot in its place.
|
||||
- vue-demo-app app/lib/realtime.ts becomes a re-export of `vue-chat-layer/app/lib/realtime` (with a comment), and the app plugin calls `setRealtimeAuth` with the DEMO_TOKEN_COOKIE reader. If the existing app/lib/realtime.test.ts fails against the shared client, replace it with bm's current realtime.test.ts, adjusted only in import paths.
|
||||
|
||||
Commit vue-chat-layer (`feat: port the chat store, realtime client and components`) and vue-demo-app (`refactor: share the chat layer's realtime client`).</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chat-layer test && pnpm --dir ../sm-demo-app/vue-demo-app test && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/check-local.sh chat realtime remote</automated>
|
||||
<fails_when>Non-zero exit: layer smoke or vue-demo-app vitest red (the realtime re-export broke the presentations tests), the build fails, or check-local reports chat, realtime or remote failed (the presentations remote no longer works through the shared client).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'export function onUserEvent' ../vue-chat-layer/app/lib/realtime.ts` prints 1.
|
||||
- `grep -rn "from 'pinia'" ../vue-chat-layer/app | wc -l` prints 0.
|
||||
- `grep -c 'vue-chat-layer/app/lib/realtime' ../sm-demo-app/vue-demo-app/app/lib/realtime.ts` prints 1.
|
||||
- `grep -rn 'v-html' ../vue-chat-layer/app/components | grep -v 'renderChatText\|rendered' | wc -l` prints 0.
|
||||
</acceptance_criteria>
|
||||
<done>The layer behaves like bm's chat across several channels and DMs, live, with one shared realtime connection on every page.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Threads, pins, reactions, attachments, moderator delete, link embeds and the slash command picker</name>
|
||||
<files>../vue-chat-layer/app/components/Chat/ThreadPane.vue, ../vue-chat-layer/app/components/Chat/PinsPanel.vue, ../vue-chat-layer/app/components/Chat/ReactionBar.vue, ../vue-chat-layer/app/components/Chat/StagingChips.vue, ../vue-chat-layer/app/components/Chat/DeleteDialog.vue, ../vue-chat-layer/app/components/Chat/LinkEmbed.vue, ../vue-chat-layer/app/components/Chat/CommandPicker.vue, ../vue-chat-layer/app/components/Chat/Message.vue, ../vue-chat-layer/app/components/Chat/Composer.vue, ../vue-chat-layer/app/components/Chat/Header.vue, ../vue-chat-layer/app/components/Chat/ChannelList.vue, ../vue-chat-layer/app/lib/linkEmbeds.ts, ../vue-chat-layer/app/lib/client.ts, ../vue-chat-layer/app/composables/useChat.ts, ../vue-chat-layer/app/assets/css/chat-tokens.css, ../vue-chat-layer/app/assets/css/chat-base.css, ../vue-chat-layer/i18n/locales/en.json, ../vue-chat-layer/i18n/locales/pl.json, ../vue-chat-layer/nuxt.config.ts, ../vue-chat-layer/README.md</files>
|
||||
<read_first>../sm-bm-app/frontend/src/components/chat/{ReactionBar,StagingChips,DeleteDialog,ChatMessage,ChatComposer,EmbedCard}.vue, ../sm-bm-app/frontend/src/lib/embeds.ts (what to drop), ../sm-demo-app/plugins/golem15/chat/README.md (replies, thread mute, reactions catalog, attachments and limits), ../sm-demo-app/plugins/golem15/chatchannels/README.md (pins, mentions), ../sm-demo-app/plugins/golem15/chatbots/README.md and api/commands.go, ../vue-paymentgateway-layer/{README.md,app/assets/css/pg-tokens.css}, ../vue-faq-layer/README.md (layer README structure), 20-RESEARCH.md (Open Question 4, Anti-Patterns)</read_first>
|
||||
<action>Per D-02, D-05, D-22, D-23, D-01.
|
||||
|
||||
- Threads: a reply count on root messages opens ChatThreadPane, which lists replies (GET /messages/{id}/replies), posts replies (POST /messages/{id}/replies) and mutes the thread (PUT /threads/{rootId}/mute). Realtime reply events update the count.
|
||||
- Pins: ChatPinsPanel, opened from the header of a channel, lists GET .../channels/{id}/pins. Pin and unpin show only when the API allows it: a refused pin shows a notice and hides the action for the session.
|
||||
- Reactions: ChatReactionBar ported, with the keys from GET /reactions.
|
||||
- Attachments: ChatStagingChips ported. Uploads go to POST /attachments within the bootstrap limits (max_files, max_bytes), and the message shows a download link (GET /attachments/{messageId}/{fileId} with the auth header, fetched as a blob).
|
||||
- Delete: ChatDeleteDialog ported. Own messages always; others' only when the bootstrap's moderator is true and the conversation is a channel (D-22).
|
||||
- Edits: an Edit action on own messages through PUT /messages/{id}.
|
||||
- Link embeds: app/lib/linkEmbeds.ts with `linkify(escapedHtml)`, `registerEmbedRenderer(match: (url: URL) => boolean, component)` and `embedRendererFor(url)`. ChatMessage renders the first URL of a message with a registered renderer or with ChatLinkEmbed (host and path, no fetch). max_embeds caps the cards.
|
||||
- Commands (D-05): typing "/" at the start of the composer opens ChatCommandPicker, filled from GET /commands (cached per session) and filtered by prefix. Sending a "/" message calls POST /dispatch with {input} instead of posting. An ephemeral answer renders as a local, dismissable, sender-only system row with the payload text (escaped); a 422 shows the error.
|
||||
- Slots: ChatHeader renders `<slot name="conversation-actions" :conversation>` only when the open conversation is a DM (D-23). ChatChannelList renders `<slot name="sidebar-footer" />`. ChatPage forwards both slots.
|
||||
- Styling: chat-tokens.css and chat-base.css (neutral tokens an app overrides, as pg-tokens.css does), registered in nuxt.config.ts css with absolute paths.
|
||||
- i18n: every UI string of the layer in en and pl under `chat.*`. The app's own copy stays in the app.
|
||||
- README.md in the layer structure of vue-faq-layer and vue-paymentgateway-layer:
|
||||
- install by tag; extends;
|
||||
- the `$chatAuth` hook; the runtime-config keys;
|
||||
- the host bootstrap contract (the two JSON shapes with a neutral `acme` host);
|
||||
- slots, `registerEmbedRenderer`, `onUserEvent`;
|
||||
- client-only rendering (wrap ChatPage and ChatFloatingPanel in ClientOnly); testing.
|
||||
Name no consuming application.
|
||||
|
||||
Commit vue-chat-layer (`feat: threads, pins, reactions, attachments, link embeds and the command picker`).</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chat-layer test && pnpm --dir ../vue-chat-layer run build:playground && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/check-local.sh chat</automated>
|
||||
<fails_when>Non-zero exit: the layer smoke test, the playground build or the app build fails, or check-local prints "check-local: chat failed".</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'conversation-actions' ../vue-chat-layer/app/components/Chat/Header.vue` prints at least 1, and the slot sits inside a condition on the DM type (`grep -c "type === 'dm'" ../vue-chat-layer/app/components/Chat/Header.vue` prints at least 1).
|
||||
- `grep -c 'export function registerEmbedRenderer' ../vue-chat-layer/app/lib/linkEmbeds.ts` prints 1.
|
||||
- `grep -c '/dispatch' ../vue-chat-layer/app/lib/client.ts` prints at least 1.
|
||||
- `node -e "const a=require('../vue-chat-layer/i18n/locales/en.json'),b=require('../vue-chat-layer/i18n/locales/pl.json');const k=o=>Object.entries(o).flatMap(([x,v])=>typeof v==='object'?k(v).map(y=>x+'.'+y):[x]);const d=k(a).filter(x=>!k(b).includes(x));if(d.length){console.error(d);process.exit(1)}"` exits 0 (PL covers every EN key).
|
||||
- In a manual run on the local stack, a "/demo" command in the composer shows the ephemeral answer and nothing is posted to the channel (recorded in the SUMMARY).
|
||||
</acceptance_criteria>
|
||||
<done>The layer has the full D-02 feature set plus the slash command picker and the extension points other layers and hosts plug into.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Chat everywhere on the demo site: floating panel, Chat tour card, EN/PL copy and updated checks</name>
|
||||
<files>../vue-chat-layer/app/components/Chat/FloatingPanel.vue, ../sm-demo-app/vue-demo-app/app/layouts/default.vue, ../sm-demo-app/vue-demo-app/app/pages/index.vue, ../sm-demo-app/vue-demo-app/app/components/TourCard.vue, ../sm-demo-app/vue-demo-app/app/pages/chat.vue, ../sm-demo-app/vue-demo-app/i18n/locales/en.json, ../sm-demo-app/vue-demo-app/i18n/locales/pl.json, ../sm-demo-app/scripts/check-local.sh, ../sm-demo-app/scripts/smoke.sh</files>
|
||||
<read_first>../sm-demo-app/vue-demo-app/app/layouts/default.vue, app/pages/index.vue (stops, TourCard), app/components/TourCard.vue (icon union, ICONS), app/composables/useDemoAuth.ts, i18n/locales/en.json and pl.json (tour.*), ../sm-demo-app/scripts/check-local.sh (check_tour, card_titles), ../sm-demo-app/scripts/smoke.sh (page loop at line 237), ../sm-bm-app/frontend/src/components/chat/DmList.vue</read_first>
|
||||
<action>Per D-03, D-04.
|
||||
- Layer ChatFloatingPanel: a corner button with the total unread badge (DMs plus channel mentions). It opens a compact panel with ChatDmList and the open DM's message list and composer, and has a link to the full chat page whose path comes from a `chatPath` prop (default '/chat'). It starts the chat store only for a member and renders nothing otherwise.
|
||||
- vue-demo-app default.vue: inside `<ClientOnly>`, render `<ChatFloatingPanel>` when loggedIn and the route is not /chat, /p/** or /presentations/**.
|
||||
- index.vue: a Chat stop `{ key: 'chat', to: '/chat' }` after quizzes. TourCard gets an outline chat icon in ICONS and 'chat' in the icon union. en and pl get tour.chat.title and tour.chat.text, and the tour heading text matches the new count ("Seven things to try" / the Polish equivalent).
|
||||
- chat.vue: final copy (EN/PL) explaining channels, DMs, threads and slash commands, plus the register prompt.
|
||||
- check-local.sh check_tour expects Chat (EN) and Czat (PL) among the cards and seven cards. smoke.sh adds /chat to the page loop (banner present; the anonymous prompt link to /register?next=%2Fchat in the HTML).
|
||||
|
||||
Commit the layer (`feat: floating chat panel`), vue-demo-app (`feat: floating chat panel, Chat tour card`) and sm-demo-app scripts separately.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chat-layer test && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/check-local.sh tour chat</automated>
|
||||
<fails_when>Non-zero exit: build or tests fail, or check-local reports tour failed (missing Chat or Czat card, wrong card count) or chat failed.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'ChatFloatingPanel' ../sm-demo-app/vue-demo-app/app/layouts/default.vue` prints 1 and the element sits inside ClientOnly.
|
||||
- `grep -c "key: 'chat'" ../sm-demo-app/vue-demo-app/app/pages/index.vue` prints 1.
|
||||
- `grep -c '/chat' ../sm-demo-app/scripts/smoke.sh` prints at least 1.
|
||||
</acceptance_criteria>
|
||||
<done>Chat is reachable from every page for members and from the tour for everyone, in EN and PL.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 5: Go-ahead to create vue-chat-layer on git.golem15.com, push it and tag v0.1.0</name>
|
||||
<read_first>Claude's summary before asking: `git -C ../vue-chat-layer log --oneline`, the README's install line, the visibility of vue-faq-layer on git.golem15.com (consumers install layers over git+https), whether `tea login list` shows a git.golem15.com login, and the result of the Task 4 checks.</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user chose one option and it is recorded in the SUMMARY; with "release", `git ls-remote https://git.golem15.com/golem15/vue-chat-layer.git` exits 0 before Task 6 pushes, or Task 6 creates it with tea.
|
||||
</acceptance_criteria>
|
||||
<decision>Create the vue-chat-layer repository, push main and tag v0.1.0 now?</decision>
|
||||
<context>D-01 rates the layer costly: later sites pin it by tag, so v0.1.0 freezes the hook, runtime-config and bootstrap contract shown in the README. A pushed tag must not move. vue-demo-app can only pin the layer by tag after this; until then it builds from a local link that cannot be pushed. Repository creation and pushes need your go-ahead (CLAUDE.md).</context>
|
||||
<options>
|
||||
<option id="release">
|
||||
<name>Create, push and tag v0.1.0</name>
|
||||
<pros>vue-demo-app pins the tag and plan 04 can build vue-chatvideo-layer against it.</pros>
|
||||
<cons>The v0.1.0 contract is public; changes need v0.1.1 or v0.2.0.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>The layer's contract can still change freely.</pros>
|
||||
<cons>Plan 04 (chatvideo extends the chat contract) and the deploy are blocked; vue-demo-app keeps a local link pin, so it cannot be pushed.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<instructions>For "release" without a tea login: create golem15/vue-chat-layer (empty, default branch main, same visibility as vue-faq-layer) in the git.golem15.com web UI, then reply. Do not paste tokens.</instructions>
|
||||
<resume-signal>Reply "release" (add "repo ready" if you created it) or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 6: Release vue-chat-layer v0.1.0 and pin it in vue-demo-app</name>
|
||||
<reversibility rating="one-way">A pushed layer tag is installed by consumers' lockfiles; it can be superseded but must never move.</reversibility>
|
||||
<precondition>Task 5 resolved with "release".</precondition>
|
||||
<files>../vue-chat-layer/README.md, ../sm-demo-app/vue-demo-app/package.json, ../sm-demo-app/vue-demo-app/pnpm-lock.yaml</files>
|
||||
<read_first>../vue-chat-layer/README.md, ../sm-demo-app/vue-demo-app/package.json (other layer pins), the Task 5 answer</read_first>
|
||||
<action>Per D-01.
|
||||
1. If the repository is missing, create it with `tea repo create --name vue-chat-layer --owner golem15` at vue-faq-layer's visibility.
|
||||
2. Add the remote `git@git.golem15.com:golem15/vue-chat-layer.git` and push main.
|
||||
3. If the README's install line says no tag exists yet, fix it before tagging. Create the annotated tag v0.1.0, push it, and confirm `git ls-remote origin refs/tags/v0.1.0^{}` equals HEAD.
|
||||
4. In vue-demo-app run `pnpm add "vue-chat-layer@git+https://git.golem15.com/golem15/vue-chat-layer.git#v0.1.0"` (replacing the link pin), then build and test.
|
||||
5. Commit package.json and pnpm-lock.yaml (`feat: pin vue-chat-layer v0.1.0`). Do not push vue-demo-app (plan 05).</action>
|
||||
<verify>
|
||||
<automated>[ "$(git -C ../vue-chat-layer ls-remote origin 'refs/tags/v0.1.0^{}' | cut -f1)" = "$(git -C ../vue-chat-layer rev-parse HEAD)" ] && grep -q 'vue-chat-layer.git#v0.1.0' ../sm-demo-app/vue-demo-app/package.json && pnpm --dir ../sm-demo-app/vue-demo-app test && pnpm --dir ../sm-demo-app/vue-demo-app run build</automated>
|
||||
<fails_when>Non-zero exit: the remote tag is missing or differs from HEAD, package.json still holds the link pin, or the vue-demo-app tests or build fail against the tagged layer.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `node -p "require('../sm-demo-app/vue-demo-app/package.json').dependencies['vue-chat-layer']"` prints `git+https://git.golem15.com/golem15/vue-chat-layer.git#v0.1.0`.
|
||||
- `git -C ../sm-demo-app/vue-demo-app status --porcelain -- package.json pnpm-lock.yaml` prints nothing.
|
||||
- `../sm-demo-app/scripts/check-local.sh chat tour` prints `check-local: ok chat tour`.
|
||||
</acceptance_criteria>
|
||||
<done>vue-chat-layer v0.1.0 is published and the demo site builds against the tag.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| other members' messages, names and URLs to the browser | untrusted content rendered in every member's page |
|
||||
| browser to the chat-family APIs | JWT bearer from the demo cookie; actor fixed server-side |
|
||||
| browser to Centrifugo | connection token per member; subscriptions authorized server-side |
|
||||
| pnpm install from git.golem15.com | the layer tag becomes an input of every consuming site |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-14 | Tampering | stored XSS through message text, names or URLs | high | mitigate | text rendered through the ported chatText renderer that escapes before marking mentions; linkify runs on escaped HTML and only emits http(s) anchors with rel noopener noreferrer nofollow; names and payloads are text bindings; acceptance grep limits v-html to the renderer output |
|
||||
| T-20-15 | Information disclosure | JWT handling in the layer | medium | mitigate | the token comes only from the app's $chatAuth hook (cookie reader), is sent as a Bearer header to same-origin paths, never stored by the layer, and cleared through unauthorized() after a failed refresh |
|
||||
| T-20-16 | Information disclosure | attachment downloads | medium | mitigate | downloads go through GET /attachments/{messageId}/{fileId} with the Bearer header (participants only server-side); no public URL is built |
|
||||
| T-20-17 | Spoofing | slash command answers | low | mitigate | ephemeral answers are rendered locally as escaped text marked as a system row and never posted as the user |
|
||||
| T-20-18 | Tampering | layer supply chain | medium | mitigate | the layer pins exact versions already audited in the workspace (centrifuge 5.7.3, @nuxtjs/i18n 10.4.0); vue-demo-app pins the layer by tag with a committed lockfile |
|
||||
| T-20-19 | Denial of service | realtime connections | low | mitigate | one shared Centrifuge client per page (re-export in vue-demo-app); polling fallback intervals of 15 s and 60 s from bm |
|
||||
| T-20-SC | Tampering | npm installs | high | mitigate | no new package: centrifuge 5.7.3 was audited in 19.4.1 (protobufjs postinstall disabled in pnpm-workspace.yaml); @nuxtjs/i18n 10.4.0, vitest 3.2.7, nuxt, vue and typescript are the pins already in the workspace lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: layer smoke, app build, check-local chat (browser send, anonymous prompt).
|
||||
- Task 2: layer and app vitest, build, check-local chat, realtime and remote.
|
||||
- Task 3: layer smoke, playground build, app build, check-local chat, PL key coverage.
|
||||
- Task 4: build, check-local tour and chat, smoke.sh page list.
|
||||
- Task 5: go-ahead recorded.
|
||||
- Task 6: remote tag equals HEAD, vue-demo-app builds against the tag.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
The public demo site has `/chat` with channels, DMs, threads, pins, reactions, attachments, mentions, typing, unread counts, link embeds and slash commands working live (SC-2, D-01 to D-05), a floating panel for members and an invitation for visitors. vue-chat-layer v0.1.0 is a reusable, app-neutral layer.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-03-SUMMARY.md` when done: the layer's public API (runtime keys, hook, slots, exports), what was stripped from bm and why, the refresh endpoint used by chatAuth, which realtime test file is used in vue-demo-app, the tag and commit, and the checkpoint answer.
|
||||
</output>
|
||||
@@ -0,0 +1,298 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 03
|
||||
subsystem: vue-chat-layer, vue-demo-app
|
||||
tags: [chat, nuxt-layer, realtime, centrifuge, i18n, slash-commands, threads, pins]
|
||||
|
||||
requires:
|
||||
- phase: 20-02
|
||||
provides: "Host bootstrap GET /_demo/api/v1/chat and /chat/members, the chat family mounted, realtime for every member"
|
||||
provides:
|
||||
- "vue-chat-layer v0.1.0 on git.golem15.com (public), tag v0.1.0 = c465414"
|
||||
- "The page's one Centrifuge client with onUserEvent, shared by the chat and the presentations remote"
|
||||
- "vue-demo-app /chat, the floating chat panel, the Chat tour card, EN/PL"
|
||||
- "check-local chat (check-chat.cjs), tour with seven cards, smoke.sh /chat"
|
||||
affects: [20-04, 20-05, 20-06]
|
||||
|
||||
actuals:
|
||||
tokens: 80100 # chars/4: layer tracked files without the lockfile (279087) + vue-demo-app diff 44a5229..3fe8018 without the lockfile (30546) + sm-demo-app scripts diff f4ed2c2..b4fc7dc (10832)
|
||||
tasks: 6
|
||||
commits: 0 # MEASURED in summercms.go before this SUMMARY commit (docs only here); code commits: vue-chat-layer 4, vue-demo-app 4, sm-demo-app 2
|
||||
plan_head_before: baa0f20eb2cd316cb3424fe6b4fd957d079713c0 # summercms.go
|
||||
plan_head_after: baa0f20eb2cd316cb3424fe6b4fd957d079713c0 # summercms.go before this SUMMARY commit
|
||||
|
||||
tech-stack:
|
||||
added:
|
||||
- "vue-chat-layer (new shared Nuxt layer) with centrifuge 5.7.3 and @nuxtjs/i18n 10.4.0; vitest 3.2.7, nuxt 4.4.8, vue 3.5.35, typescript 5.9.3 as dev deps (all versions already pinned in the workspace)"
|
||||
patterns:
|
||||
- "Store as a composable over useState keys prefixed chat:, one reactive store per Nuxt app (no Pinia)"
|
||||
- "Auth hook $chatAuth {token, refresh, unauthorized, userId?}; pure Nuxt-free client in app/lib, imported explicitly"
|
||||
- "One realtime client per page; other layers get user:{me} events through onUserEvent"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../vue-chat-layer/nuxt.config.ts
|
||||
- ../vue-chat-layer/README.md
|
||||
- ../vue-chat-layer/app/lib/client.ts
|
||||
- ../vue-chat-layer/app/lib/realtime.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.ts
|
||||
- ../vue-chat-layer/app/composables/useChat.ts
|
||||
- ../vue-chat-layer/app/components/Chat/FloatingPanel.vue
|
||||
- ../vue-chat-layer/app/components/Chat/CommandPicker.vue
|
||||
- ../vue-chat-layer/app/components/Chat/ThreadPane.vue
|
||||
- ../vue-chat-layer/app/assets/css/chat-tokens.css
|
||||
- ../vue-chat-layer/tests/smoke.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/chat.vue
|
||||
- ../sm-demo-app/scripts/check-chat.cjs
|
||||
modified:
|
||||
- ../sm-demo-app/vue-demo-app/package.json
|
||||
- ../sm-demo-app/vue-demo-app/pnpm-lock.yaml
|
||||
- ../sm-demo-app/vue-demo-app/nuxt.config.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/lib/realtime.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/lib/realtime.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/vitest.config.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/layouts/default.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/TourCard.vue
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/smoke.sh
|
||||
|
||||
key-decisions:
|
||||
- "Task 5 checkpoint answer: release. golem15/vue-chat-layer created public with tea (same visibility as vue-faq-layer), main pushed, annotated tag v0.1.0 on c465414"
|
||||
- "The layer reads the caller's user id from the JWT's numeric sub claim; an optional $chatAuth.userId() overrides it"
|
||||
- "vue-demo-app chatAuth.refresh posts to POST /_user/api/v1/refresh and stores the rotated token through lib/api/client.ts tokens (document.cookie)"
|
||||
- "Ported libs keep bm's signatures with optional localized copy and setFormatLocale (defaults pl-PL / Europe/Warsaw), so bm's tests port unchanged in plan 06"
|
||||
- "Slash command answers render through renderChatText, the only v-html besides message bodies"
|
||||
|
||||
patterns-established:
|
||||
- "A layer's realtime client is re-exported by the app (export * from 'vue-chat-layer/app/lib/realtime'); vitest inlines the layer and dedupes centrifuge"
|
||||
|
||||
requirements-completed: [SC-2, D-01, D-02, D-03, D-04, D-05, D-07, D-20, D-22, D-23]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "A logged-in visitor opens #general on /chat and a message sent from the composer appears; anonymous /chat has the register link to /register?next=/chat and no chat"
|
||||
requirement: "D-02, D-04"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "../sm-demo-app/scripts/check-chat.cjs (check-local.sh chat)"
|
||||
status: pass
|
||||
- kind: smoke
|
||||
ref: "../sm-demo-app/scripts/smoke.sh (/chat in the page loop, register prompt, no chat in the HTML)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "The chat client sends the bearer, refreshes once on 401, calls unauthorized after a failed refresh, maps 422 to field errors"
|
||||
requirement: "D-01"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../vue-chat-layer/tests/smoke.test.ts"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "One shared Centrifuge client: the presentations remote and the chat ride one socket; bm's realtime test passes against it"
|
||||
requirement: "SC-2"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../sm-demo-app/vue-demo-app/app/lib/realtime.test.ts"
|
||||
status: pass
|
||||
- kind: e2e
|
||||
ref: "check-local.sh realtime remote"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "Live delivery, /demo command (ephemeral, nothing posted), unknown command row, link card, reaction, thread reply and live thread reply, pins, attachment upload and send, DM from the picker, edit, delete, PL UI, floating panel badge and DM reply, panel hidden on /chat and decks"
|
||||
requirement: "SC-2, D-02, D-03, D-05"
|
||||
verification:
|
||||
- kind: manual
|
||||
ref: "Playwright probes against the local stack with two members (scratchpad live.cjs, features.cjs, floating.cjs)"
|
||||
status: pass
|
||||
human_judgment: true
|
||||
- id: D5
|
||||
description: "Tour has seven cards with Chat (EN) and Czat (PL); vue-demo-app builds and tests against the tag"
|
||||
requirement: "D-03, D-01"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "check-local.sh chat tour after the tag pin"
|
||||
status: pass
|
||||
- kind: build
|
||||
ref: "pnpm --dir ../sm-demo-app/vue-demo-app test (209) && run build"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: 52min
|
||||
completed: 2026-10-31
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 20 Plan 03: vue-chat-layer v0.1.0 and chat on the demo site Summary
|
||||
|
||||
**vue-chat-layer v0.1.0 is released on git.golem15.com. It carries bm's chat ported to a Pinia-free Nuxt layer and widened to several channels, threads, pins, link cards and a slash command picker. The demo site now has /chat for members, a register prompt for visitors, a floating DM panel on every page and a Chat tour card, in EN and PL.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** about 52 min
|
||||
- **Started:** 2026-10-31T12:27Z
|
||||
- **Completed:** 2026-10-31T13:19Z
|
||||
- **Tasks:** 6/6. Task 5 was the checkpoint, answered "release".
|
||||
- **Files:** vue-chat-layer has 52 tracked files without the lockfile. vue-demo-app has 13 files changed (436 insertions, 147 deletions). sm-demo-app scripts have 3 files changed.
|
||||
|
||||
## The layer's public API (v0.1.0)
|
||||
|
||||
**Runtime config:**
|
||||
|
||||
| Key | Env | Purpose |
|
||||
|-----|-----|---------|
|
||||
| `chat.apiBase` | `NUXT_CHAT_API_BASE` | Server-side base of the chat API |
|
||||
| `public.chat.apiBase` | | `/_chat/api/v1` |
|
||||
| `public.chat.channelsApiBase` | | `/_chatchannels/api/v1` |
|
||||
| `public.chat.botsApiBase` | | `/_chatbots/api/v1` |
|
||||
| `public.chat.hostApiBase` | | `''`. With an empty value the chat does not start, and a console error names the key |
|
||||
|
||||
**Hook:** `$chatAuth` with `token()`, `refresh()`, `unauthorized()` and an optional `userId()`.
|
||||
|
||||
**Host contract:** `GET {hostApiBase}/chat` and `GET {hostApiBase}/chat/members`. The README documents both with a neutral `acme` host.
|
||||
|
||||
**Slots:**
|
||||
- `conversation-actions`, with `{ conversation }`. It renders only for a DM, in `ChatHeader`, `ChatPanel`, `ChatPage` and `ChatFloatingPanel`.
|
||||
- `sidebar-footer`, in `ChatChannelList` and `ChatPage`.
|
||||
|
||||
**Components:** `ChatPage`, `ChatFloatingPanel` (prop `chatPath`), `ChatChannelList`, `ChatDmList`, `ChatPanel`, `ChatHeader`, `ChatMessageList`, `ChatMessage`, `ChatComposer`, `ChatThreadPane`, `ChatPinsPanel`, `ChatReactionBar`, `ChatStagingChips`, `ChatDeleteDialog`, `ChatMemberPicker`, `ChatMentionPopup`, `ChatCommandPicker`, `ChatLinkEmbed`, `ChatAvatar`, `ChatIcon` and `ChatNotices`.
|
||||
|
||||
**Composables:** `useChat`, `useChatApi` (with `useChatAuth` and `useChatConfig`) and `useChatNotice`.
|
||||
|
||||
**Library exports:**
|
||||
- `client.ts`: `createChatClient`, `ChatApiError`, `userIdFromToken`.
|
||||
- `realtime.ts`: `REALTIME_WS_PATH`, `connect`, `subscribe`, `presence`, `openChannel`, `onUserEvent`, `dispatchUserEvent`, `setRealtimeAuth`, `disconnect`, `onConnection`, `onUnavailable`.
|
||||
- `linkEmbeds.ts`: `linkify`, `messageUrls`, `registerEmbedRenderer`, `embedRendererFor`.
|
||||
- The ported `chatEvents`, `chatFormat`, `chatText` and `chatUnread`, plus `format` (`setFormatLocale`), `attachments`, `markdown`, `media` and `tabs`.
|
||||
|
||||
**Copy:** EN and PL under `chat.*`, 131 keys. PL covers every EN key.
|
||||
|
||||
## What was stripped from bm and why
|
||||
|
||||
- **bm's embeds and the embed picker were dropped** (`deadline`, `class` and `reading`, plus `EmbedPicker`, `EmbedCard`, `lib/embeds.ts` and the paste-to-embed logic). They are bm entities. In their place:
|
||||
- A generic link card shows the host and path, with no fetch.
|
||||
- `registerEmbedRenderer` lets a host render its own entity links (the D-01 extension point).
|
||||
- **The single `# ogólny` model became `channels[]`, `activeId` and `kind`.** bm's "Czat roku" tab layout became a sidebar plus pane. Threads, pins and the command picker are new.
|
||||
- **The Pinia stores went away.** `useChat` became `useState` and `useToast` became `useChatNotice`.
|
||||
- **The bm cached membership flag in localStorage and its BM bootstrap paths were removed.** Every string went to i18n.
|
||||
|
||||
## Task Commits
|
||||
|
||||
| # | Repo | Commit | Message |
|
||||
|---|------|--------|---------|
|
||||
| 1 | vue-chat-layer | fa6f995 | feat: chat layer tracer: bootstrap, channel list, messages, composer |
|
||||
| 1 | vue-demo-app | 5b7648f | feat: /chat page on vue-chat-layer |
|
||||
| 1 | sm-demo-app | b6ece43 | test: check-chat browser check |
|
||||
| 2 | vue-chat-layer | 5d58153 | feat: port the chat store, realtime client and components |
|
||||
| 2 | vue-demo-app | ae3dbfc | refactor: share the chat layer's realtime client |
|
||||
| 3 | vue-chat-layer | 269c75b | feat: threads, pins, reactions, attachments, link embeds and the command picker |
|
||||
| 4 | vue-chat-layer | c465414 | feat: floating chat panel |
|
||||
| 4 | vue-demo-app | 8636aa3 | feat: floating chat panel, Chat tour card |
|
||||
| 4 | sm-demo-app | b4fc7dc | test: tour expects the Chat card, smoke covers /chat |
|
||||
| 6 | vue-chat-layer | tag v0.1.0 (1e6a907, peels to c465414) | vue-chat-layer v0.1.0 |
|
||||
| 6 | vue-demo-app | 3fe8018 | feat: pin vue-chat-layer v0.1.0 |
|
||||
|
||||
**Pushed:** only vue-chat-layer `main` and the tag `v0.1.0`. They went to the new public repository `git@git.golem15.com:golem15/vue-chat-layer.git`, created with `tea repo create`. `git ls-remote origin 'refs/tags/v0.1.0^{}'` equals HEAD c465414.
|
||||
|
||||
**Not pushed:** vue-demo-app and sm-demo-app (plan 05). sm-demo-app shows the moved `vue-demo-app` submodule pointer as uncommitted; plan 05 bumps it.
|
||||
|
||||
## Checkpoint answer
|
||||
|
||||
Task 5: **release**. The user gave the go-ahead to create the repository, push main and tag v0.1.0.
|
||||
|
||||
## Verification
|
||||
|
||||
- **Layer:** `pnpm test` passes 6/6, and `pnpm build:playground` builds.
|
||||
- **vue-demo-app:** `pnpm test` passes 209/209 and `pnpm run build` builds, both against the link pin and against the tag.
|
||||
- **check-local.sh:** these runs all printed ok.
|
||||
- `chat` (Task 1)
|
||||
- `chat realtime remote` (Task 2)
|
||||
- `chat` (Task 3)
|
||||
- `tour chat realtime remote` (Task 4)
|
||||
- `chat tour` after the tag pin (Task 6)
|
||||
- **smoke.sh:** `smoke: ok` with /chat included.
|
||||
- **Manual (Task 3 criterion):** `/demo` typed in the #general composer opened the picker, and Enter showed the ephemeral answer. The channel had 18 messages before and 18 after, so nothing was posted.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - Missing critical] The caller's user id**
|
||||
- **Found during:** Task 2.
|
||||
- **Issue:** The demo bootstrap and `/chat/members` do not include the caller. The store needs the id for `user:{me}` and for telling its own messages apart.
|
||||
- **Fix:** `userIdFromToken` reads the JWT's numeric `sub` claim. An optional `$chatAuth.userId()` overrides it. Documented in the README. Commit 5d58153.
|
||||
|
||||
**2. Refresh endpoint**
|
||||
- useDemoAuth has no refresh.
|
||||
- `chatAuth.refresh` calls `POST /_user/api/v1/refresh` with the bearer token. The user plugin answers the rotated token in the body.
|
||||
- The token is stored through `lib/api/client.ts` `tokens` (`document.cookie`), because the hook runs outside a component's setup, where `useCookie` fails. Commits 5b7648f and ae3dbfc.
|
||||
|
||||
**3. [Rule 3 - Blocking] Realtime test and vitest config**
|
||||
- vue-demo-app's `app/lib/realtime.test.ts` is now bm's current realtime test against the shared client. Two adjustments go beyond import paths:
|
||||
- The token route is a stubbed `fetch` instead of a mocked `@/api/client`, because the layer fetches the token itself.
|
||||
- The 503 case asserts `{status: 503}`, since the error is now `RealtimeTokenError`.
|
||||
- `vitest.config.ts` (outside Task 2's file list) got `resolve.dedupe: ['centrifuge']` and `test.server.deps.inline: ['vue-chat-layer']`. With these the mock applies, and the tag-installed layer's TypeScript is transformed. Commit ae3dbfc.
|
||||
|
||||
**4. Extra layer files and the shape of the ported libs**
|
||||
- Two files are outside the plan's list:
|
||||
- `app/lib/markdown.ts`: `escapeHtml`, `safeUrl` and `formatSpans`, for chatText.
|
||||
- `app/lib/attachments.ts`: `checkFiles`.
|
||||
- The ported libs keep bm's signatures, with optional localized copy. `setFormatLocale` configures the format locale; its defaults stay pl-PL and Europe/Warsaw, so bm's tests port unchanged in plan 06. The components set the app's locale and the browser's time zone.
|
||||
- `chatEvents` adds an optional `rootId` to created events, so replies stay out of the main list.
|
||||
|
||||
**5. Ephemeral answers**
|
||||
- Slash command answers render through `renderChatText`. This keeps the prohibition: `v-html` is used only for the escaped renderer output.
|
||||
- `linkify` is exported but not used by the components.
|
||||
|
||||
**6. Naming and copy**
|
||||
- The app's `chat.*` keys (`eyebrow`, `title`, `lead`, `slashHint`, `anonymous`, `registerToChat`) avoid the layer's `chat.*` tree. The layer's own title key is `chat.name`.
|
||||
- `{'@'}` escapes @ in the app copy, because a bare @ is vue-i18n link syntax.
|
||||
- /chat also has a Log in link next to the register link.
|
||||
|
||||
**7. Dev-stack note**
|
||||
- Running `nuxt build` while `nuxt dev` is up makes the dev server loop on "Another Nuxt dev is already running".
|
||||
- The stack was restarted with `dev.sh down` and `dev.sh up` after each build.
|
||||
|
||||
**8. Pins**
|
||||
- The visitor was allowed to pin in #general, and the pin succeeded.
|
||||
- The refused-pin path (a notice, then the action hidden for the session) is in the code but was not exercised.
|
||||
|
||||
**Total deviations:** 8. **Impact:** none on the plan goal.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None. Link cards are generic by design (D-01; there is no unfurl backend).
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- **vue-tsc on the playground** (run with summercms.go/admin's vue-tsc, not a gate) reports only `noUncheckedIndexedAccess` errors (the "possibly undefined" kind). They are mostly in the modules ported from bm and come from the source. Builds don't typecheck.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
| Flag | File | Description |
|
||||
|------|------|-------------|
|
||||
| threat_flag: supply-chain | ../sm-demo-app/vue-demo-app/package.json | New git dependency vue-chat-layer pinned by tag v0.1.0 (commit c465414 in the lockfile), as planned in T-20-18 |
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- **Plan 04** (vue-chatvideo-layer) can extend `vue-chat-layer#v0.1.0`:
|
||||
- Call button: put it in the `conversation-actions` slot, which renders for DMs only.
|
||||
- `video:*` events: listen through `onUserEvent`.
|
||||
- Session channels: subscribe through the shared `subscribe`.
|
||||
- **Plan 05** needs to know:
|
||||
- vue-demo-app is ready to push. Its `package.json` and lockfile pin the tag, with no local path.
|
||||
- The sm-demo-app submodule pointer bump is still to do.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- The listed files exist in their repos: vue-chat-layer, vue-demo-app and sm-demo-app scripts.
|
||||
- Commits exist:
|
||||
- vue-chat-layer: fa6f995, 5d58153, 269c75b, c465414.
|
||||
- vue-demo-app: 5b7648f, ae3dbfc, 8636aa3, 3fe8018.
|
||||
- sm-demo-app: b6ece43, b4fc7dc.
|
||||
- The remote tag v0.1.0 peels to c465414.
|
||||
@@ -0,0 +1,517 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 4
|
||||
depends_on: ["20-03"]
|
||||
files_modified:
|
||||
- ../vue-forum-layer/.gitignore
|
||||
- ../vue-forum-layer/.nvmrc
|
||||
- ../vue-forum-layer/package.json
|
||||
- ../vue-forum-layer/pnpm-lock.yaml
|
||||
- ../vue-forum-layer/pnpm-workspace.yaml
|
||||
- ../vue-forum-layer/tsconfig.json
|
||||
- ../vue-forum-layer/nuxt.config.ts
|
||||
- ../vue-forum-layer/README.md
|
||||
- ../vue-forum-layer/.playground/nuxt.config.ts
|
||||
- ../vue-forum-layer/.playground/app/app.vue
|
||||
- ../vue-forum-layer/app/utils/forumClient.ts
|
||||
- ../vue-forum-layer/app/composables/useForumApi.ts
|
||||
- ../vue-forum-layer/app/composables/useForum.ts
|
||||
- ../vue-forum-layer/app/components/Forum/Page.vue
|
||||
- ../vue-forum-layer/app/components/Forum/CategoryList.vue
|
||||
- ../vue-forum-layer/app/components/Forum/ThreadList.vue
|
||||
- ../vue-forum-layer/app/components/Forum/Thread.vue
|
||||
- ../vue-forum-layer/app/components/Forum/PostEditor.vue
|
||||
- ../vue-forum-layer/app/assets/css/forum-base.css
|
||||
- ../vue-forum-layer/i18n/locales/en.json
|
||||
- ../vue-forum-layer/i18n/locales/pl.json
|
||||
- ../vue-forum-layer/tests/client.test.ts
|
||||
- ../vue-userfriends-layer/.gitignore
|
||||
- ../vue-userfriends-layer/.nvmrc
|
||||
- ../vue-userfriends-layer/package.json
|
||||
- ../vue-userfriends-layer/pnpm-lock.yaml
|
||||
- ../vue-userfriends-layer/pnpm-workspace.yaml
|
||||
- ../vue-userfriends-layer/tsconfig.json
|
||||
- ../vue-userfriends-layer/nuxt.config.ts
|
||||
- ../vue-userfriends-layer/README.md
|
||||
- ../vue-userfriends-layer/.playground/nuxt.config.ts
|
||||
- ../vue-userfriends-layer/.playground/app/app.vue
|
||||
- ../vue-userfriends-layer/app/utils/friendsClient.ts
|
||||
- ../vue-userfriends-layer/app/composables/useFriendsApi.ts
|
||||
- ../vue-userfriends-layer/app/composables/useFriends.ts
|
||||
- ../vue-userfriends-layer/app/components/Friends/Page.vue
|
||||
- ../vue-userfriends-layer/app/components/Friends/List.vue
|
||||
- ../vue-userfriends-layer/app/components/Friends/Requests.vue
|
||||
- ../vue-userfriends-layer/app/components/Friends/Groups.vue
|
||||
- ../vue-userfriends-layer/app/components/Friends/AddFriend.vue
|
||||
- ../vue-userfriends-layer/app/assets/css/friends-base.css
|
||||
- ../vue-userfriends-layer/i18n/locales/en.json
|
||||
- ../vue-userfriends-layer/i18n/locales/pl.json
|
||||
- ../vue-userfriends-layer/tests/client.test.ts
|
||||
- ../vue-chatvideo-layer/.gitignore
|
||||
- ../vue-chatvideo-layer/.nvmrc
|
||||
- ../vue-chatvideo-layer/package.json
|
||||
- ../vue-chatvideo-layer/pnpm-lock.yaml
|
||||
- ../vue-chatvideo-layer/pnpm-workspace.yaml
|
||||
- ../vue-chatvideo-layer/tsconfig.json
|
||||
- ../vue-chatvideo-layer/nuxt.config.ts
|
||||
- ../vue-chatvideo-layer/README.md
|
||||
- ../vue-chatvideo-layer/.playground/nuxt.config.ts
|
||||
- ../vue-chatvideo-layer/.playground/app/app.vue
|
||||
- ../vue-chatvideo-layer/app/lib/videoClient.ts
|
||||
- ../vue-chatvideo-layer/app/lib/callMachine.ts
|
||||
- ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/Call.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/Tile.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/CallButton.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue
|
||||
- ../vue-chatvideo-layer/app/assets/css/chatvideo-base.css
|
||||
- ../vue-chatvideo-layer/i18n/locales/en.json
|
||||
- ../vue-chatvideo-layer/i18n/locales/pl.json
|
||||
- ../vue-chatvideo-layer/tests/callMachine.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/package.json
|
||||
- ../sm-demo-app/vue-demo-app/pnpm-lock.yaml
|
||||
- ../sm-demo-app/vue-demo-app/nuxt.config.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/layouts/default.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/forum/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/forum/t/[id].vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/friends.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/chat.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/account/security.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/TourCard.vue
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/smoke.sh
|
||||
- ../sm-demo-app/scripts/dev.sh
|
||||
- ../sm-demo-app/deploy/env.example
|
||||
- ../sm-demo-app/README.md
|
||||
- .planning/phases/20-demo-instance-with-every-shared-plugin/COVERAGE.md
|
||||
autonomous: false
|
||||
requirements: [SC-2, D-11, D-12, D-13, D-14, D-15, D-16, D-20, D-21, D-22, D-23]
|
||||
estimate:
|
||||
tokens: 380000
|
||||
raw_tokens: 380000
|
||||
tasks: 7
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "D-14, D-21: /forum shows a member the seeded EN and PL categories and their threads; a thread page lists posts as the server's content_html; a member creates a thread, replies, edits own posts and deletes own posts (moderators any post, D-22); an anonymous visitor on /forum and on a thread URL sees a description and a register-to-join link (/register?next=...), and no forum API call is made without a JWT."
|
||||
- "D-15: /friends shows a member their friends, incoming and sent requests (accept, reject, cancel, unfriend) and friend groups (list, create, join, leave, members); a member sends a request to another member chosen from the app-provided directory; /friends is linked from the chat sidebar (sidebar-footer slot) and from the account area (header link and /account/security)."
|
||||
- "D-11, D-23: the call button (ChatvideoCallButton) appears only in DM conversations through vue-chat-layer's conversation-actions slot; there is no call button in channels; the server is not changed to refuse channel calls."
|
||||
- "D-13: /call/{conversation} is a minimal call page: own camera, remote tiles, mute, camera toggle and leave, built on livekit-client loaded with a dynamic import; an incoming video:call:incoming event (received through vue-chat-layer's onUserEvent, no second user:{me} subscription) shows an accept/decline prompt on every page for members."
|
||||
- "D-12: the call page shows the D-12 caps' effects (a started call ends at the server's max_duration; a fifth participant is refused by LiveKit's room cap) without client-side limits of its own."
|
||||
- "D-16: herald runs with VAPID keys from .env (SUMMER_GOLEM15__HERALD__VAPID__PUBLIC_KEY, __PRIVATE_KEY, __SUBJECT; dev.sh generates them with herald:vapid-generate, never printing them) and there is no subscribe UI; /_herald is not added to vue-demo-app goPaths."
|
||||
- "The homepage tour has Forum, Friends and Calls cards next to Chat (ten cards, EN and PL)."
|
||||
- "livekit-client is installed only after the blocking human-verify checkpoint, at an exact version the user confirmed."
|
||||
- "After the Task 6 go-ahead, vue-forum-layer, vue-userfriends-layer and vue-chatvideo-layer exist on git.golem15.com with tag v0.1.0 each, and vue-demo-app pins all three by git+https tag in a committed package.json and pnpm-lock.yaml."
|
||||
artifacts:
|
||||
- path: "../vue-forum-layer/app/components/Forum/Page.vue"
|
||||
provides: "categories and thread list of one forum context"
|
||||
contains: "contextType"
|
||||
- path: "../vue-userfriends-layer/app/components/Friends/Page.vue"
|
||||
provides: "friends, requests and groups"
|
||||
contains: "Requests"
|
||||
- path: "../vue-chatvideo-layer/app/lib/callMachine.ts"
|
||||
provides: "pure call state machine (idle, starting, connecting, connected, ended, failed)"
|
||||
contains: "connected"
|
||||
- path: "../vue-chatvideo-layer/app/composables/useCall.ts"
|
||||
provides: "LiveKit room lifecycle over the chatvideo API, dynamic import of livekit-client"
|
||||
contains: "import('livekit-client')"
|
||||
- path: "../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue"
|
||||
provides: "/call/{conversation} page"
|
||||
contains: "ChatvideoCall"
|
||||
- path: ".planning/phases/20-demo-instance-with-every-shared-plugin/COVERAGE.md"
|
||||
provides: "API coverage decisions for livekit-client, LiveKit server, Centrifugo and Web Push"
|
||||
contains: "livekit-client"
|
||||
key_links:
|
||||
- from: "../sm-demo-app/vue-demo-app/app/pages/chat.vue"
|
||||
to: "../vue-chatvideo-layer/app/components/Chatvideo/CallButton.vue"
|
||||
via: "template #conversation-actions renders ChatvideoCallButton (DM only, D-23)"
|
||||
pattern: "conversation-actions"
|
||||
- from: "../vue-chatvideo-layer/app/composables/useIncomingCalls.ts"
|
||||
to: "../vue-chat-layer/app/lib/realtime.ts"
|
||||
via: "onUserEvent receives video:call:incoming from the chat store's user:{me} subscription"
|
||||
pattern: "onUserEvent"
|
||||
- from: "../vue-chatvideo-layer/app/composables/useCall.ts"
|
||||
to: "../sm-demo-app/plugins/golem15/chatvideo/api/video.go"
|
||||
via: "POST /_chatvideo/api/v1/conversations/{id}/video/start or /join gives {livekit_url, token}"
|
||||
pattern: "video/(start|join)"
|
||||
- from: "../sm-demo-app/vue-demo-app/app/plugins/auth.ts"
|
||||
to: "../vue-forum-layer/app/composables/useForumApi.ts"
|
||||
via: "provide forumAuth and userfriendsAuth token getters (chatvideo reuses chatAuth)"
|
||||
pattern: "forumAuth"
|
||||
prohibitions:
|
||||
- statement: "None of the three layers names a consuming application or carries a default host path."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "Forum post HTML is rendered only from the server's content_html; user Markdown is never rendered client-side."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "livekit-client is not added to any package.json before the Task 3 checkpoint is approved."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "No push, repository creation or tag before the Task 6 go-ahead; vue-demo-app and sm-demo-app are not pushed (plan 05)."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): the demo's public Nuxt site shows the shared plugins working through shared layers, video calls included.
|
||||
|
||||
This plan's slice (plan 4 of 6, wave 4, per D-20): three new shared layers at v0.1.0 (`vue-forum-layer`, `vue-userfriends-layer`, `vue-chatvideo-layer`), their pages and tour cards in vue-demo-app, and herald's VAPID configuration without UI.
|
||||
|
||||
**Wave note (deviation from D-20, recorded):** D-20 lets plans 03 and 04 run in parallel after plan 02. This plan still depends on plan 03 and runs after it, for two reasons:
|
||||
1. It consumes plan 03's vue-chat-layer outputs: vue-chatvideo-layer imports the shared realtime client (`onUserEvent`, `subscribe`) and renders its call button in vue-chat-layer's DM-only `conversation-actions` slot (D-23), and the friends link goes into its `sidebar-footer` slot.
|
||||
2. Both plans edit the same vue-demo-app files (package.json, pnpm-lock.yaml, nuxt.config.ts, app/plugins/auth.ts, app/pages/index.vue, the locales) in one checkout. Parallel execution runs without worktrees, so the two plans would collide in the same wave.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Layer shape:** like vue-faq-layer and vue-paymentgateway-layer. A Nuxt-free client in `app/utils/*Client.ts` (tested with `node --test`), an auth-hook composable, components with a directory prefix (`Forum*`, `Friends*`, `Chatvideo*`), EN/PL strings through `i18n:registerModule`, and no pages or route rules: the app owns routes and wraps client-side parts in ClientOnly.
|
||||
- **Auth hooks:** `$forumAuth` and `$userfriendsAuth` are token getters, the vue-paymentgateway-layer shape. vue-chatvideo-layer reuses vue-chat-layer's `$chatAuth`, because it has a peer dependency on that layer.
|
||||
- **Forum context:** props `contextType` and `contextId`; vue-demo-app passes `demo` and `1`. Thread URLs are built by an app-supplied `threadPath(id)` prop. Markdown is written in a textarea with the server preview endpoint (`POST /contexts/{type}/{id}/preview`); nothing is rendered client-side.
|
||||
- **Friend directory:** the layer takes an optional `$userfriendsDirectory(): Promise<{id, name}[]>` hook for the add-friend picker and falls back to a username field (the API accepts user_id, username or email). vue-demo-app provides the directory from `GET /_demo/api/v1/chat/members`.
|
||||
- **chatvideo and chat:** vue-chatvideo-layer lists vue-chat-layer v0.1.0 as a peer dependency and dev dependency, without `extends`. The app extends both, so the chat layer is not loaded twice. It imports `onUserEvent` and `subscribe` from `vue-chat-layer/app/lib/realtime`.
|
||||
- **Call flow:** the call button starts (`video/start`) and navigates to `/call/{conversation}`. The call page joins (`video/join`) when it was not the starter and connects with the returned `livekit_url` and `token`. Leave calls `video/leave` then `room.disconnect()`. An incoming call prompt offers Accept (navigate) and Decline (`video/leave`; the service publishes video:call:declined for a participant who never joined; Task 4 confirms this in video_service.go). Screen share stays off (D-13 minimal, `screen_share: false`).
|
||||
- **Profile link (D-15):** the demo has no profile page. The account area stands for it: a "Friends" header link for members next to "Security", and a link on /account/security.
|
||||
- **Tour:** ten cards (Journal, Presentations, Quizzes, Chat, Forum, Friends, Calls, Payments, FAQ, Accounts). The Calls card links to /chat with text saying calls start from a DM.
|
||||
- **Development pins:** `link:` dependencies to the three local checkouts until Task 7 swaps them for tags, as in plan 03.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
## Artifacts this phase produces (this plan)
|
||||
|
||||
- Repository `vue-forum-layer` v0.1.0:
|
||||
- components `ForumPage`, `ForumCategoryList`, `ForumThreadList`, `ForumThread`, `ForumPostEditor`;
|
||||
- composables `useForum`, `useForumApi`; client `createForumClient`;
|
||||
- runtime keys `forum.apiBase` (`NUXT_FORUM_API_BASE`) and `public.forum.apiBase`; hook `$forumAuth`; i18n `forum.*`.
|
||||
- Repository `vue-userfriends-layer` v0.1.0:
|
||||
- components `FriendsPage`, `FriendsList`, `FriendsRequests`, `FriendsGroups`, `FriendsAddFriend`;
|
||||
- composables `useFriends`, `useFriendsApi`; client `createFriendsClient`;
|
||||
- runtime keys `userfriends.apiBase` and `public.userfriends.apiBase`; hooks `$userfriendsAuth` and `$userfriendsDirectory`; i18n `friends.*`.
|
||||
- Repository `vue-chatvideo-layer` v0.1.0:
|
||||
- components `ChatvideoCall`, `ChatvideoTile`, `ChatvideoCallButton`, `ChatvideoIncomingCall`;
|
||||
- composables `useCall`, `useIncomingCalls`; lib `createVideoClient`, `callMachine` (`initialCallState`, `transition`);
|
||||
- runtime key `public.chatvideo.apiBase`; prop `callPath`; i18n `chatvideo.*`; dependency `livekit-client` at the confirmed exact version.
|
||||
- vue-demo-app:
|
||||
- pages `/forum`, `/forum/t/[id]`, `/friends`, `/call/[conversation]`;
|
||||
- ChatvideoIncomingCall in the default layout; the call button in /chat's conversation-actions slot; the friends link in /chat's sidebar-footer slot, the header and /account/security;
|
||||
- tour cards forum, friends and calls; goPaths `/_forum`, `/_userfriends`, `/_chatvideo`; hooks `forumAuth`, `userfriendsAuth`, `userfriendsDirectory`.
|
||||
- sm-demo-app: check-local checks `forum`, `friends`, `call`, `herald`; tour expects ten cards; smoke.sh pages /forum and /friends; dev.sh VAPID generation; env keys `SUMMER_GOLEM15__HERALD__VAPID__PUBLIC_KEY`, `__PRIVATE_KEY`, `__SUBJECT` (names only in env.example).
|
||||
- `.planning/phases/20-demo-instance-with-every-shared-plugin/COVERAGE.md` (API coverage matrix).
|
||||
|
||||
<objective>
|
||||
Build and release the forum, friends and video-call layers, put their pages and tour cards on the demo site, and configure herald's VAPID keys without UI.
|
||||
|
||||
Purpose: SC-2 (video calls and the other plugins visible through shared layers), D-11, D-12, D-13, D-14, D-15, D-16, D-21, D-22 (forum moderation), D-23.
|
||||
Output: three new repositories (pushed and tagged after the go-ahead), commits in vue-demo-app and sm-demo-app (not pushed), and the phase COVERAGE.md.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-RESEARCH.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-PATTERNS.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-03-SUMMARY.md
|
||||
|
||||
Repos: new ../vue-forum-layer, ../vue-userfriends-layer and ../vue-chatvideo-layer; ../sm-demo-app/vue-demo-app (submodule); ../sm-demo-app. Layer analogs: ../vue-faq-layer (structure, node --test, client in app/utils), ../vue-paymentgateway-layer (auth hook, i18n registration), ../vue-chat-layer (plan 03: slots, onUserEvent, $chatAuth).
|
||||
|
||||
Rules: as in plan 03 (no co-author tags, stage by path, no remote before the go-ahead, vue-demo-app committed in its own repository and not pushed, check for other sessions' edits before each commit). The local stack: `../sm-demo-app/scripts/dev.sh up` with LiveKit on 127.0.0.1:7890.
|
||||
|
||||
Size (accepted under D-20): seven tasks over three new layer repositories are above the usual per-plan budget, but the user confirmed exactly six plans (D-20, the lean-planning rule in CLAUDE.md), so this plan is not split. After Task 4 is committed, write a progress note into a draft `20-04-SUMMARY.md` (Tasks 1 to 4 with their commits, the approved livekit-client version, the decline endpoint, open points) so a context reset resumes from Task 5.
|
||||
|
||||
<interfaces>
|
||||
forum API /_forum/api/v1 (JWT, forum-api 120/min): GET /contexts/{type}/{id}/categories; GET /contexts/{type}/{id}/categories/{categoryId}/threads; POST same (create thread {title, body}); GET /contexts/{type}/{id}/threads; GET /contexts/{type}/{id}/threads/{threadId}/posts; POST same (reply {body}); PUT /contexts/{type}/{id}/posts/{postId} ({body}); DELETE /contexts/{type}/{id}/posts/{postId}; DELETE /contexts/{type}/{id}/threads/{threadId}; POST /contexts/{type}/{id}/threads/{threadId}/read; GET /contexts/{type}/{id}/unread; POST /contexts/{type}/{id}/preview. Posts carry content_html (server-rendered with breakwater). 422 envelope as chat.
|
||||
userfriends API /_userfriends/api/v1 (JWT; userfriends-api 120/min, community-join 10/min): GET /friends, /friends/requests, /friends/sent; POST /friends/request ({user_id} or {username} or {email}); POST /friends/requests/{id}/accept; DELETE /friends/requests/{id}; DELETE /friends/sent/{id}; DELETE /friends/{userId}; GET|POST /groups; GET|PUT|DELETE /groups/{id}; POST /groups/{id}/join, /leave; GET|POST /groups/{id}/members; DELETE /groups/{id}/members/{userId}; GET|POST|DELETE /groups/{id}/invite; GET|POST /groups/join/{code}.
|
||||
chatvideo API /_chatvideo/api/v1 (JWT): POST /conversations/{id}/video/start (video-initiate 5/min) and /join give {livekit_url, token, ...}; POST /leave, /end; GET /status. Realtime: video:call:incoming on user:{id}; video:call:accepted, declined, ended and participant events on video:session:{id}.
|
||||
vue-chat-layer v0.1.0 (plan 03): slots conversation-actions (DM only) and sidebar-footer on ChatPage; `onUserEvent(handler)`, `subscribe(channel, hooks)` in `vue-chat-layer/app/lib/realtime`; `$chatAuth {token, refresh, unauthorized}`.
|
||||
herald: keys golem15.herald.vapid.{subject, public_key, private_key}; env SUMMER_GOLEM15__HERALD__VAPID__*; command herald:vapid-generate (--json prints {"public_key", "private_key"}; -q quiet).
|
||||
vue-demo-app (after plan 03): app/pages/chat.vue (ChatPage in ClientOnly), app/layouts/default.vue (ChatFloatingPanel), app/pages/index.vue (stops with chat), app/components/TourCard.vue, app/components/SiteHeader.vue (links mine and security), app/pages/account/security.vue, app/plugins/auth.ts (paymentGatewayAuth, chatAuth).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: a member opens /forum, sees the seeded categories, opens a thread and posts a reply that the server renders; an anonymous visitor gets the register prompt</name>
|
||||
<precondition>The plan 03 SUMMARY records vue-chat-layer v0.1.0 on git.golem15.com; `../sm-demo-app/scripts/dev.sh up` is running; `git -C ../sm-demo-app/vue-demo-app status --porcelain` lists no file this task changes.</precondition>
|
||||
<files>../vue-forum-layer/.gitignore, ../vue-forum-layer/.nvmrc, ../vue-forum-layer/package.json, ../vue-forum-layer/pnpm-lock.yaml, ../vue-forum-layer/pnpm-workspace.yaml, ../vue-forum-layer/tsconfig.json, ../vue-forum-layer/nuxt.config.ts, ../vue-forum-layer/README.md, ../vue-forum-layer/.playground/nuxt.config.ts, ../vue-forum-layer/.playground/app/app.vue, ../vue-forum-layer/app/utils/forumClient.ts, ../vue-forum-layer/app/composables/useForumApi.ts, ../vue-forum-layer/app/composables/useForum.ts, ../vue-forum-layer/app/components/Forum/Page.vue, ../vue-forum-layer/app/components/Forum/CategoryList.vue, ../vue-forum-layer/app/components/Forum/ThreadList.vue, ../vue-forum-layer/app/components/Forum/Thread.vue, ../vue-forum-layer/app/components/Forum/PostEditor.vue, ../vue-forum-layer/app/assets/css/forum-base.css, ../vue-forum-layer/i18n/locales/en.json, ../vue-forum-layer/i18n/locales/pl.json, ../vue-forum-layer/tests/client.test.ts, ../sm-demo-app/vue-demo-app/package.json, ../sm-demo-app/vue-demo-app/nuxt.config.ts, ../sm-demo-app/vue-demo-app/app/plugins/auth.ts, ../sm-demo-app/vue-demo-app/app/pages/forum/index.vue, ../sm-demo-app/vue-demo-app/app/pages/forum/t/[id].vue, ../sm-demo-app/vue-demo-app/i18n/locales/en.json, ../sm-demo-app/vue-demo-app/i18n/locales/pl.json, ../sm-demo-app/scripts/check-local.sh, ../sm-demo-app/scripts/smoke.sh</files>
|
||||
<read_first>../vue-faq-layer/{nuxt.config.ts,package.json,README.md,app/utils/client.ts,app/composables/useFaqApi.ts,tests/client.test.ts}, ../vue-paymentgateway-layer/{nuxt.config.ts,app/composables/usePaymentGatewayApi.ts}, ../sm-demo-app/plugins/golem15/forum/README.md and api/*.go (payloads), ../sm-demo-app/plugins/demo/classes/forum_access.go, ../sm-demo-app/vue-demo-app/{nuxt.config.ts,app/plugins/auth.ts,app/pages/chat.vue,app/pages/quizzes/index.vue}, ../sm-demo-app/scripts/check-local.sh (visitor_jwt, json_has, ALL_CHECKS) and smoke.sh (page loop)</read_first>
|
||||
<action>Per D-14, D-21, D-22, SC-2.
|
||||
|
||||
1. Create ../vue-forum-layer (`git init -b main`) with the vue-faq-layer skeleton:
|
||||
- package.json: name vue-forum-layer, version 0.1.0, main nuxt.config.ts, peer nuxt 4.4.8, dependency @nuxtjs/i18n 10.4.0, dev deps nuxt, vue and typescript at the workspace pins, test `node --test --test-reporter=tap tests/*.test.ts`;
|
||||
- nuxt.config.ts: header comment, currentDir, runtimeConfig `forum.apiBase` (NUXT_FORUM_API_BASE) and `public.forum.apiBase: '/_forum/api/v1'`, the EN/PL i18n registration, absolute css path.
|
||||
2. app/utils/forumClient.ts `createForumClient({ base, token, fetch })`: categories, threads (per category and all), posts, createThread, reply, editPost, deletePost, deleteThread, markRead, unread and preview, each building `/contexts/{type}/{id}/...` paths, plus the 422 field-error mapping. app/composables/useForumApi.ts binds it to runtime config and `$forumAuth`. useForum keeps the selected category, the threads, and the open thread and posts.
|
||||
3. Components:
|
||||
- ForumPage (props contextType, contextId, threadPath(id)): ForumCategoryList plus ForumThreadList with a "new thread" ForumPostEditor;
|
||||
- ForumThread (props contextType, contextId, threadId): each post renders the server's content_html as raw HTML (the only raw-HTML binding in the layer), with author and date, reply editor, Edit and Delete on own posts and on all posts when the API reports manage rights (a refused delete hides the action);
|
||||
- ForumPostEditor: textarea plus a server preview button.
|
||||
Mark the thread read on open.
|
||||
4. vue-demo-app:
|
||||
- run `pnpm add vue-forum-layer@link:../../vue-forum-layer` (development pin, committed; Task 7 swaps it for the tag before any push);
|
||||
- nuxt.config.ts: extends gains 'vue-forum-layer'; goPaths gains '/_forum'; `forum.apiBase` comes from `api`;
|
||||
- auth.ts provides `forumAuth`;
|
||||
- app/pages/forum/index.vue and forum/t/[id].vue: for members, ClientOnly ForumPage and ForumThread with context demo/1 and `threadPath: id => '/forum/t/' + id`; for anonymous visitors, a server-rendered description and a register link with next set to the current path (D-21, the chat page pattern). useSeoMeta on both;
|
||||
- EN/PL copy: forum.title, forum.lead and forum.registerToJoin.
|
||||
5. check-local.sh `check_forum`:
|
||||
- with the visitor JWT, GET /_forum/api/v1/contexts/demo/1/categories answers 200 with at least three categories;
|
||||
- POST a reply to the first thread answers 201 and its content_html holds a rendered paragraph;
|
||||
- GET $NUXT/forum without a cookie holds the register link with next=%2Fforum.
|
||||
Add it to ALL_CHECKS. smoke.sh adds /forum to the page loop.
|
||||
6. tests/client.test.ts: URL building for every method, the Bearer header, and the 422 mapping.
|
||||
|
||||
Commit the layer (`feat: forum layer: categories, threads and Markdown posts`), vue-demo-app (package.json and pnpm-lock.yaml with the link pin, pages, config, auth and locales) and sm-demo-app scripts separately.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-forum-layer test && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/dev.sh up && ../sm-demo-app/scripts/check-local.sh forum</automated>
|
||||
<fails_when>Non-zero exit: the forum client tests fail, the Nuxt build fails, the stack does not start, or check-local prints "check-local: forum failed" (categories missing, the reply not rendered, or no register link for anonymous visitors).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -rniE 'golem15\.demo|sm-demo|demo/1' ../vue-forum-layer/app ../vue-forum-layer/nuxt.config.ts ../vue-forum-layer/README.md | wc -l` prints 0.
|
||||
- `grep -rn 'v-html' ../vue-forum-layer/app/components | grep -vc 'content_html'` prints 0.
|
||||
- `grep -c "'/_forum'" ../sm-demo-app/vue-demo-app/nuxt.config.ts` prints 1.
|
||||
</acceptance_criteria>
|
||||
<done>Members read and post in the seeded forum on the demo site through a new shared layer; anonymous visitors are invited to register.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Friends: list, requests and groups on /friends, linked from the chat sidebar and the account area</name>
|
||||
<files>../vue-userfriends-layer/.gitignore, ../vue-userfriends-layer/.nvmrc, ../vue-userfriends-layer/package.json, ../vue-userfriends-layer/pnpm-lock.yaml, ../vue-userfriends-layer/pnpm-workspace.yaml, ../vue-userfriends-layer/tsconfig.json, ../vue-userfriends-layer/nuxt.config.ts, ../vue-userfriends-layer/README.md, ../vue-userfriends-layer/.playground/nuxt.config.ts, ../vue-userfriends-layer/.playground/app/app.vue, ../vue-userfriends-layer/app/utils/friendsClient.ts, ../vue-userfriends-layer/app/composables/useFriendsApi.ts, ../vue-userfriends-layer/app/composables/useFriends.ts, ../vue-userfriends-layer/app/components/Friends/Page.vue, ../vue-userfriends-layer/app/components/Friends/List.vue, ../vue-userfriends-layer/app/components/Friends/Requests.vue, ../vue-userfriends-layer/app/components/Friends/Groups.vue, ../vue-userfriends-layer/app/components/Friends/AddFriend.vue, ../vue-userfriends-layer/app/assets/css/friends-base.css, ../vue-userfriends-layer/i18n/locales/en.json, ../vue-userfriends-layer/i18n/locales/pl.json, ../vue-userfriends-layer/tests/client.test.ts, ../sm-demo-app/vue-demo-app/package.json, ../sm-demo-app/vue-demo-app/nuxt.config.ts, ../sm-demo-app/vue-demo-app/app/plugins/auth.ts, ../sm-demo-app/vue-demo-app/app/pages/friends.vue, ../sm-demo-app/vue-demo-app/app/pages/chat.vue, ../sm-demo-app/vue-demo-app/app/pages/account/security.vue, ../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue, ../sm-demo-app/vue-demo-app/i18n/locales/en.json, ../sm-demo-app/vue-demo-app/i18n/locales/pl.json, ../sm-demo-app/scripts/check-local.sh, ../sm-demo-app/scripts/smoke.sh</files>
|
||||
<read_first>../sm-demo-app/plugins/golem15/userfriends/README.md and api/friends.go and api/groups.go (bodies, 422 behaviour), ../vue-forum-layer (Task 1, same skeleton), ../vue-chat-layer/README.md (sidebar-footer slot), ../sm-demo-app/vue-demo-app/{app/pages/chat.vue,app/components/SiteHeader.vue,app/pages/account/security.vue,app/plugins/auth.ts}, ../sm-demo-app/plugins/demo/chat_api.go (members endpoint)</read_first>
|
||||
<action>Per D-15.
|
||||
- Create ../vue-userfriends-layer with the Task 1 skeleton (runtime `userfriends.apiBase`, `public.userfriends.apiBase: '/_userfriends/api/v1'`).
|
||||
- app/utils/friendsClient.ts `createFriendsClient`: friends, incoming, sent, request({user_id} or {username}), accept, reject, cancel, unfriend, groups, group, createGroup, updateGroup, deleteGroup, join, leave, members, kick, invite, joinByCode. useFriendsApi binds `$userfriendsAuth`.
|
||||
- Components:
|
||||
- FriendsList: friends with Unfriend;
|
||||
- FriendsRequests: incoming with Accept and Reject, sent with Cancel;
|
||||
- FriendsAddFriend: picks from `$userfriendsDirectory()` when provided, else a username field; the generic 422 shows the server message;
|
||||
- FriendsGroups: my groups, create (name, visibility as the API allows), join by code, leave, member list;
|
||||
- FriendsPage: all four in sections.
|
||||
- vue-demo-app:
|
||||
- pnpm link dependency; extends 'vue-userfriends-layer'; goPaths '/_userfriends'; runtime config;
|
||||
- auth.ts provides `userfriendsAuth` and `userfriendsDirectory` (GET /_demo/api/v1/chat/members with the JWT, mapped to {id, name: name plus surname});
|
||||
- app/pages/friends.vue: ClientOnly FriendsPage for members, the register prompt for anonymous visitors;
|
||||
- chat.vue passes `<template #sidebar-footer>` with a NuxtLink to /friends;
|
||||
- SiteHeader shows "Friends" for members next to Security, and account/security.vue links to /friends;
|
||||
- EN/PL copy.
|
||||
- check-local.sh `check_friends`, repeatable without touching seed data:
|
||||
- with the visitor JWT, GET /_userfriends/api/v1/friends/requests lists the seeded pending request (read-only);
|
||||
- two fresh users from the throwaway registration helper (extend it so the caller also gets the e-mail it registered): A sends POST /friends/request with {email: B's e-mail} and gets 2xx, B finds the request in GET /friends/requests and accepts it with 2xx, and A's GET /friends lists B.
|
||||
Add it to ALL_CHECKS. smoke.sh adds /friends.
|
||||
- tests/client.test.ts: URL building, Bearer header, 422 mapping.
|
||||
|
||||
Commit the layer, vue-demo-app (with the link pin) and the scripts separately.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-userfriends-layer test && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/check-local.sh friends forum chat</automated>
|
||||
<fails_when>Non-zero exit: the friends client tests or the build fail, or check-local reports friends, forum or chat failed (the seeded request missing, accept refused, or the chat page broken by the slot).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'sidebar-footer' ../sm-demo-app/vue-demo-app/app/pages/chat.vue` prints 1.
|
||||
- `grep -c "to=\"/friends\"" ../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue` prints 1.
|
||||
- `grep -rniE 'golem15\.demo|sm-demo|_demo/api' ../vue-userfriends-layer/app ../vue-userfriends-layer/nuxt.config.ts ../vue-userfriends-layer/README.md | wc -l` prints 0.
|
||||
</acceptance_criteria>
|
||||
<done>Members manage friends, requests and friend groups on /friends, reachable from the chat sidebar and the account area.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 3: Package legitimacy check before installing livekit-client</name>
|
||||
<read_first>20-RESEARCH.md Package Legitimacy Audit (livekit-client flagged [SUS] too-new for its latest release; assumption A7), the output Claude prints before asking: `npm view livekit-client versions --json | tail -15`, `npm view livekit-client time --json` for the last five versions, `npm view livekit-client repository.url maintainers dist-tags scripts --json`, and the proposed exact version (the newest release at least 7 days old)</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user approved a named exact version (recorded in the SUMMARY) or rejected the package; Task 4 installs only that version with `--save-exact`.
|
||||
</acceptance_criteria>
|
||||
<what-built>Nothing is installed yet. Claude proposes an exact livekit-client version for vue-chatvideo-layer, the client SDK the minimal call page (D-13) is built on.</what-built>
|
||||
<how-to-verify>
|
||||
1. Open https://www.npmjs.com/package/livekit-client and check that the publisher and maintainers are the LiveKit organization and the repository is github.com/livekit/client-sdk-js.
|
||||
2. Check that the proposed version exists, is at least 7 days old and that `scripts` shows no install or postinstall hook.
|
||||
3. Check the client SDK's server compatibility notes for LiveKit server 1.13.1 (the rome and local binary).
|
||||
</how-to-verify>
|
||||
<resume-signal>Reply "approved <version>" or "rejected" with the reason.</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Video calls from DMs: the call button, the minimal call page and incoming-call prompts</name>
|
||||
<precondition>Task 3 answered "approved <version>"; LiveKit answers on http://127.0.0.1:7890/ (dev stack).</precondition>
|
||||
<files>../vue-chatvideo-layer/.gitignore, ../vue-chatvideo-layer/.nvmrc, ../vue-chatvideo-layer/package.json, ../vue-chatvideo-layer/pnpm-lock.yaml, ../vue-chatvideo-layer/pnpm-workspace.yaml, ../vue-chatvideo-layer/tsconfig.json, ../vue-chatvideo-layer/nuxt.config.ts, ../vue-chatvideo-layer/README.md, ../vue-chatvideo-layer/.playground/nuxt.config.ts, ../vue-chatvideo-layer/.playground/app/app.vue, ../vue-chatvideo-layer/app/lib/videoClient.ts, ../vue-chatvideo-layer/app/lib/callMachine.ts, ../vue-chatvideo-layer/app/composables/useCall.ts, ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts, ../vue-chatvideo-layer/app/components/Chatvideo/Call.vue, ../vue-chatvideo-layer/app/components/Chatvideo/Tile.vue, ../vue-chatvideo-layer/app/components/Chatvideo/CallButton.vue, ../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue, ../vue-chatvideo-layer/app/assets/css/chatvideo-base.css, ../vue-chatvideo-layer/i18n/locales/en.json, ../vue-chatvideo-layer/i18n/locales/pl.json, ../vue-chatvideo-layer/tests/callMachine.test.ts, ../sm-demo-app/vue-demo-app/package.json, ../sm-demo-app/vue-demo-app/nuxt.config.ts, ../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue, ../sm-demo-app/vue-demo-app/app/pages/chat.vue, ../sm-demo-app/vue-demo-app/app/layouts/default.vue, ../sm-demo-app/vue-demo-app/i18n/locales/en.json, ../sm-demo-app/vue-demo-app/i18n/locales/pl.json, ../sm-demo-app/scripts/check-local.sh, .planning/phases/20-demo-instance-with-every-shared-plugin/COVERAGE.md</files>
|
||||
<read_first>../sm-demo-app/plugins/golem15/chatvideo/README.md, api/video.go, classes/video_service.go (Start, Join, Leave, End, declined path), classes/notifier.go (event names), ../vue-chat-layer/app/lib/realtime.ts (onUserEvent, subscribe) and README.md (slots), the livekit-client README and API docs for the approved version (Room, RoomEvent, Track, connect, localParticipant.setCameraEnabled and setMicrophoneEnabled, track attach and detach; through Context7 or ctx7 when available), ../sm-demo-app/vue-demo-app/{app/pages/chat.vue,app/layouts/default.vue}, .planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/COVERAGE.md (matrix format), 20-RESEARCH.md (Pitfalls 8 and 9, assumption A1)</read_first>
|
||||
<action>Per D-11, D-12, D-13, D-23.
|
||||
|
||||
1. Create ../vue-chatvideo-layer with the skeleton:
|
||||
- dependencies `livekit-client@<approved>` installed with `--save-exact`, and @nuxtjs/i18n 10.4.0;
|
||||
- peerDependencies nuxt 4.4.8 and `vue-chat-layer: "^0.1.0"`; devDependency vue-chat-layer at the git+https v0.1.0 tag for the playground;
|
||||
- test script `vitest run` with vitest 3.2.7;
|
||||
- runtime `public.chatvideo.apiBase: '/_chatvideo/api/v1'`;
|
||||
- no `extends` of vue-chat-layer (the app extends both).
|
||||
2. app/lib/callMachine.ts (pure): states idle, starting, connecting, connected, ended and failed, and `transition(state, event)` for the events start, joined(token, url), connected, participantJoined, participantLeft, mute, unmute, cameraOff, cameraOn, leave, ended(reason) and error(code). Mute and camera flags live in the state. Token errors (401, 403, 404, 422 too many participants) map to failed with a reason key.
|
||||
3. app/lib/videoClient.ts: start, join, leave, end and status over `/conversations/{id}/video/...` with the `$chatAuth` token getter.
|
||||
4. app/composables/useCall.ts:
|
||||
- drives the machine; on start or join, `await import('livekit-client')`, creates a Room (adaptiveStream and dynacast on), connects with livekit_url and token, and enables camera and microphone;
|
||||
- maps RoomEvent participant and track events to tiles and attaches and detaches tracks to video elements;
|
||||
- offers mute and camera toggles through the local participant, and leave (disconnect, then POST leave);
|
||||
- subscribes to the session channel through vue-chat-layer's `subscribe` for ended and declined events, with the channel name always built by an exported helper `videoSessionChannel(id)` in app/lib/videoClient.ts, and disconnects on route leave and pagehide.
|
||||
useIncomingCalls registers `onUserEvent` for `video:call:incoming` (never its own user:{me} subscription) and exposes the pending call.
|
||||
5. Components:
|
||||
- ChatvideoCall (prop conversationId, start boolean): own camera tile, remote tiles (ChatvideoTile), mute, camera and leave buttons, the state text and failure messages from i18n;
|
||||
- ChatvideoCallButton (props conversationId and callPath(id)): starts and navigates;
|
||||
- ChatvideoIncomingCall: the caller name from the event payload, Accept (navigate to callPath) and Decline (POST leave; confirm in video_service.go that this publishes declined for a participant who never joined, else use the endpoint that does).
|
||||
No screen share (D-13).
|
||||
6. vue-demo-app:
|
||||
- pnpm link dependency; extends gains 'vue-chatvideo-layer' after 'vue-chat-layer'; goPaths '/_chatvideo';
|
||||
- app/pages/call/[conversation].vue: ClientOnly ChatvideoCall for members (start when the query has start=1), the register prompt otherwise;
|
||||
- chat.vue `<template #conversation-actions="{ conversation }">` renders ChatvideoCallButton with callPath `id => '/call/' + id + '?start=1'` (the slot only renders in DMs, D-23);
|
||||
- default.vue renders ClientOnly ChatvideoIncomingCall for members;
|
||||
- EN/PL copy (call.title, call.registerToCall).
|
||||
7. check-local.sh `check_call`:
|
||||
- with the visitor JWT, POST /_chat/api/v1/contexts/demo/1/dm to a persona gives the DM id;
|
||||
- POST /_chatvideo/api/v1/conversations/{dm}/video/start answers 2xx with livekit_url and token;
|
||||
- GET http://127.0.0.1:7890/rtc/validate?access_token=<token> answers 200 (LiveKit accepts the token, proving the keys and the room);
|
||||
- POST .../video/end answers 2xx.
|
||||
Add `call` to ALL_CHECKS.
|
||||
8. tests/callMachine.test.ts (smoke): start, joined, connected, mute, leave and ended; a 422 start ends in failed with the too-many reason.
|
||||
9. COVERAGE.md in the phase directory (format of 19.4.1's):
|
||||
- livekit-client capabilities (Room connect and disconnect, publish camera and microphone, subscribe and attach remote tracks, mute and unmute, camera toggle, participant events, connection state and reconnection, adaptiveStream and dynacast INTEGRATE; screen share, data channel, device selection, E2EE, recording and egress, simulcast tuning, audio-only mode OPT-OUT, each with a reason);
|
||||
- LiveKit server through chatvideo (room create and delete, token mint, list participants, reconcile INTEGRATE; egress, ingress, SIP and webhooks OPT-OUT);
|
||||
- Centrifugo (the chat, user and video namespaces with presence on chat INTEGRATE; history, recovery and client publish OPT-OUT);
|
||||
- Web Push through herald (VAPID keys and the public key route INTEGRATE; subscribe UI and push on chat events OPT-OUT, deferred per D-16).
|
||||
|
||||
Commit the layer, vue-demo-app (with the link pin), the scripts and COVERAGE.md (planning commit) separately.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chatvideo-layer test && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/check-local.sh call chat</automated>
|
||||
<fails_when>Non-zero exit: the call machine tests fail, the build fails (livekit-client not resolvable or a type error), or check-local reports call failed (start refused, no token or livekit_url, LiveKit's rtc/validate not 200) or chat failed.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c "import('livekit-client')" ../vue-chatvideo-layer/app/composables/useCall.ts` prints 1 and `grep -rn "^import .*from 'livekit-client'" ../vue-chatvideo-layer/app | grep -vc 'import type'` prints 0 (no static runtime import).
|
||||
- `grep -rn 'subscribe(' ../vue-chatvideo-layer/app | grep -vc 'videoSessionChannel'` prints 0 (the layer's only subscriptions are session channels; incoming calls come through onUserEvent).
|
||||
- `node -p "require('../vue-chatvideo-layer/package.json').dependencies['livekit-client']"` prints the approved version with no range character.
|
||||
- `grep -c 'conversation-actions' ../sm-demo-app/vue-demo-app/app/pages/chat.vue` prints 1.
|
||||
- COVERAGE.md has a reason on every OPT-OUT row (`grep -c 'OPT-OUT | *|' .planning/phases/20-demo-instance-with-every-shared-plugin/COVERAGE.md` prints 0).
|
||||
</acceptance_criteria>
|
||||
<done>A member can start a video call from a DM, the other member gets an accept prompt on any page, and both meet on a minimal call page served by LiveKit.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 5: Herald's VAPID keys without UI, and the Forum, Friends and Calls tour cards</name>
|
||||
<files>../sm-demo-app/scripts/dev.sh, ../sm-demo-app/deploy/env.example, ../sm-demo-app/README.md, ../sm-demo-app/vue-demo-app/app/pages/index.vue, ../sm-demo-app/vue-demo-app/app/components/TourCard.vue, ../sm-demo-app/vue-demo-app/i18n/locales/en.json, ../sm-demo-app/vue-demo-app/i18n/locales/pl.json, ../sm-demo-app/scripts/check-local.sh</files>
|
||||
<read_first>../sm-demo-app/plugins/golem15/herald/README.md (keys, herald:vapid-generate, presence gate warning), ../sm-demo-app/scripts/dev.sh (ensure_env, build, up), ../sm-demo-app/deploy/env.example, ../sm-demo-app/vue-demo-app/app/pages/index.vue, app/components/TourCard.vue, i18n/locales/*.json (tour.*), ../sm-demo-app/scripts/check-local.sh (check_tour)</read_first>
|
||||
<action>Per D-16 and the tour part of D-03.
|
||||
- dev.sh: after build in `up` and `seed`, when .env lacks SUMMER_GOLEM15__HERALD__VAPID__PUBLIC_KEY, run `./bin/demo herald:vapid-generate --json -q`, append SUMMER_GOLEM15__HERALD__VAPID__PUBLIC_KEY and __PRIVATE_KEY from the JSON (python3 parse, umask 077, values never echoed) and SUMMER_GOLEM15__HERALD__VAPID__SUBJECT=mailto:demo@example.test. Print only "added the herald VAPID keys to .env".
|
||||
- deploy/env.example: the three herald key names with empty values and a comment (generated on rome with herald:vapid-generate; no subscribe UI in this phase, D-16). README "Chat family" section: herald is mounted without UI.
|
||||
- Tour:
|
||||
- index.vue stops in order journal, presentations, quizzes, chat, forum (/forum), friends (/friends), calls (/chat with text tour.calls.text), payments, faq, accounts;
|
||||
- TourCard icons forum, friends and calls added to the union and ICONS (outline, 24-unit grid, currentColor);
|
||||
- en and pl tour.forum, tour.friends and tour.calls titles and texts, and the heading for ten cards.
|
||||
- check-local.sh check_tour expects ten cards including Forum, Friends and Calls (EN) and their Polish titles. New `check_herald`: GET $GO/_herald/api/v1/push/vapid-public-key answers 401 without a JWT and 200 with the visitor's JWT and a non-empty publicKey (json_has); add `herald` to ALL_CHECKS and the header list.
|
||||
|
||||
Commit sm-demo-app (dev.sh, env.example, README, check-local) and vue-demo-app (tour) separately.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/dev.sh up && grep -q '^SUMMER_GOLEM15__HERALD__VAPID__PUBLIC_KEY=.' ../sm-demo-app/.env && ../sm-demo-app/scripts/check-local.sh herald tour</automated>
|
||||
<fails_when>Non-zero exit: the build fails, dev.sh does not write the VAPID public key into .env, or check-local reports herald failed (the public-key route is not 200 with a non-empty publicKey for the visitor, or not 401 without a JWT) or tour failed (card count or titles wrong).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'HERALD__VAPID__PRIVATE_KEY=' ../sm-demo-app/deploy/env.example` prints 1, with no value after the equals sign.
|
||||
- `grep -c "'/_herald'" ../sm-demo-app/vue-demo-app/nuxt.config.ts` prints 0.
|
||||
- `grep -cE "key: '(forum|friends|calls)'" ../sm-demo-app/vue-demo-app/app/pages/index.vue` prints 3.
|
||||
- dev.sh output contains no line with a key value (manual look at the `up` output, recorded in the SUMMARY).
|
||||
</acceptance_criteria>
|
||||
<done>Herald runs with VAPID keys and no UI, and the tour shows all ten features in EN and PL.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 6: Go-ahead to create the forum, friends and video-call layer repositories, push them and tag v0.1.0</name>
|
||||
<read_first>Claude's summary: `git log --oneline` of the three layers, their README install lines, vue-faq-layer's visibility, whether `tea login list` shows a git.golem15.com login, the livekit-client version approved in Task 3, and the results of check-local forum friends call tour chat.</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user chose one option and it is recorded in the SUMMARY; with "release", the three repositories exist on git.golem15.com (`git ls-remote` exits 0 for each) before Task 7 pushes, or Task 7 creates them with tea.
|
||||
</acceptance_criteria>
|
||||
<decision>Create vue-forum-layer, vue-userfriends-layer and vue-chatvideo-layer on git.golem15.com, push main and tag v0.1.0 each?</decision>
|
||||
<context>Each layer is public with tagged releases that later sites pin (like D-01 for chat). v0.1.0 freezes their hooks, props and runtime keys. vue-chatvideo-layer's peer dependency on vue-chat-layer ^0.1.0 is part of its contract. vue-demo-app can pin them only after this. Repository creation and pushes need your go-ahead.</context>
|
||||
<options>
|
||||
<option id="release">
|
||||
<name>Create, push and tag all three</name>
|
||||
<pros>vue-demo-app pins the tags; the deploy (plan 05) can build.</pros>
|
||||
<cons>The v0.1.0 contracts are public.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>Contracts stay open for changes.</pros>
|
||||
<cons>The deploy is blocked; vue-demo-app keeps local link pins, so it cannot be pushed.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<instructions>For "release" without a tea login: create the three repositories (empty, default branch main, vue-faq-layer's visibility) in the git.golem15.com web UI, then reply. Do not paste tokens.</instructions>
|
||||
<resume-signal>Reply "release" (add "repos ready" if you created them) or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 7: Release the three layers v0.1.0 and pin them in vue-demo-app</name>
|
||||
<reversibility rating="one-way">Pushed layer tags are installed by consumers' lockfiles; they can be superseded but must never move.</reversibility>
|
||||
<precondition>Task 6 resolved with "release".</precondition>
|
||||
<files>../vue-forum-layer/README.md, ../vue-userfriends-layer/README.md, ../vue-chatvideo-layer/README.md, ../sm-demo-app/vue-demo-app/package.json, ../sm-demo-app/vue-demo-app/pnpm-lock.yaml</files>
|
||||
<read_first>The three READMEs, ../sm-demo-app/vue-demo-app/package.json, the Task 6 answer</read_first>
|
||||
<action>For each of the three layers:
|
||||
- create the repository with tea if missing, at vue-faq-layer's visibility;
|
||||
- add the origin `git@git.golem15.com:golem15/<layer>.git` and push main;
|
||||
- fix a README install line that says the tag does not exist before tagging;
|
||||
- create the annotated tag v0.1.0, push it and check `ls-remote` against HEAD.
|
||||
Then in vue-demo-app run `pnpm add` with the three `git+https://git.golem15.com/golem15/<layer>.git#v0.1.0` specs (replacing the link pins), run the tests and the build, and commit package.json and pnpm-lock.yaml (`feat: pin the forum, friends and video-call layers v0.1.0`). Do not push vue-demo-app.</action>
|
||||
<verify>
|
||||
<automated>for l in vue-forum-layer vue-userfriends-layer vue-chatvideo-layer; do [ "$(git -C ../$l ls-remote origin 'refs/tags/v0.1.0^{}' | cut -f1)" = "$(git -C ../$l rev-parse HEAD)" ] || exit 1; grep -q "$l.git#v0.1.0" ../sm-demo-app/vue-demo-app/package.json || exit 1; done && pnpm --dir ../sm-demo-app/vue-demo-app test && pnpm --dir ../sm-demo-app/vue-demo-app run build && ../sm-demo-app/scripts/check-local.sh forum friends call chat tour</automated>
|
||||
<fails_when>Non-zero exit: a remote tag is missing or differs from HEAD, a tag pin is missing from package.json, the vue-demo-app tests or build fail, or a check-local check fails against the tagged layers.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../sm-demo-app/vue-demo-app status --porcelain -- package.json pnpm-lock.yaml` prints nothing.
|
||||
- `node -p "Object.values(require('../sm-demo-app/vue-demo-app/package.json').dependencies).filter(v=>v.startsWith('link')).length"` prints 0.
|
||||
</acceptance_criteria>
|
||||
<done>Forum, friends and video-call layers are published at v0.1.0 and the demo site builds against all tagged layers.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| forum posts and friend names to other members' browsers | untrusted content |
|
||||
| browser to LiveKit (signal through nginx, media direct) | WebRTC with a short-lived join token |
|
||||
| realtime events to the incoming-call prompt | payloads from the server about other users |
|
||||
| npm registry to the chatvideo layer | a new third-party dependency (livekit-client) |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-20 | Tampering | forum stored XSS | high | mitigate | posts render only content_html, which the server sanitizes on write with breakwater (D-18 of the forum port); Markdown is previewed through the server endpoint; acceptance grep limits v-html to content_html |
|
||||
| T-20-21 | Spoofing | call joins | high | mitigate | tokens are minted by chatvideo only for conversation participants (sessionForActor) with token_ttl 900; the client never builds tokens; LiveKit room max_participants 4 (D-12) |
|
||||
| T-20-22 | Information disclosure | camera and microphone | medium | mitigate | media starts only after an explicit start or accept on the call page; leave and pagehide disconnect and stop local tracks |
|
||||
| T-20-23 | Tampering | incoming-call payloads | low | mitigate | caller names render as text bindings; Accept navigates only to the app's callPath built from the numeric conversation id |
|
||||
| T-20-24 | Denial of service | call spam | medium | mitigate | server bucket video-initiate 5/min, max_duration 900 and the reconcile job (D-12); calls only offered in DMs (D-23) |
|
||||
| T-20-25 | Information disclosure | friend enumeration | low | mitigate | the API's generic 422 for refused requests is shown as is; the directory lists demo members only (the same set the chat member picker shows) |
|
||||
| T-20-26 | Information disclosure | VAPID private key | high | mitigate | generated into .env only (umask 077, never echoed); env.example holds names; /_herald is not routed by the site's goPaths |
|
||||
| T-20-SC | Tampering | npm installs | high | mitigate | livekit-client installed only after the blocking human-verify legitimacy checkpoint (Task 3, gate blocking-human, never auto-approved) at an exact version with no install scripts; every other package is an existing workspace pin |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: forum client tests, app build, check-local forum.
|
||||
- Task 2: friends client tests, build, check-local friends forum chat.
|
||||
- Task 3: livekit-client version approved by the user.
|
||||
- Task 4: call machine tests, build, check-local call chat, COVERAGE.md complete.
|
||||
- Task 5: build, VAPID keys in .env, herald route present, check-local tour.
|
||||
- Task 6: go-ahead recorded.
|
||||
- Task 7: three remote tags equal HEAD; vue-demo-app tests, build and checks green on tags.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
The demo site shows the forum, friends and DM video calls through three new shared layers (SC-2, D-11 to D-15, D-21, D-23), herald is configured without UI (D-16), and the tour lists every feature.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-04-SUMMARY.md` when done: the approved livekit-client version, the decline endpoint used, each layer's public API, the three tags and commits, and both checkpoint answers.
|
||||
</output>
|
||||
@@ -0,0 +1,303 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 04
|
||||
subsystem: vue-forum-layer, vue-userfriends-layer, vue-chatvideo-layer, vue-demo-app, sm-demo-app
|
||||
tags: [forum, friends, video-calls, livekit, nuxt-layer, herald, vapid, tour, i18n]
|
||||
|
||||
requires:
|
||||
- phase: 20-02
|
||||
provides: "Chat family mounted in sm-demo-app, seeded forum and friends, local LiveKit, Centrifugo namespaces chat/user/video, GET /_demo/api/v1/chat/members"
|
||||
- phase: 20-03
|
||||
provides: "vue-chat-layer v0.1.0: conversation-actions (DM only) and sidebar-footer slots, onUserEvent and subscribe on the page's one realtime client, $chatAuth"
|
||||
provides:
|
||||
- "vue-forum-layer v0.1.0 on git.golem15.com (public), tag v0.1.0 = dcd6549"
|
||||
- "vue-userfriends-layer v0.1.0 on git.golem15.com (public), tag v0.1.0 = bcc8e99"
|
||||
- "vue-chatvideo-layer v0.1.0 on git.golem15.com (public), tag v0.1.0 = 75e9a40, livekit-client 2.23.0 exact"
|
||||
- "vue-demo-app /forum, /forum/t/{id}, /friends, /call/{conversation}, the DM call button, the incoming-call prompt, ten tour cards, all three layers pinned by tag"
|
||||
- "sm-demo-app check-local forum, friends, call, herald; tour expects ten cards; smoke.sh covers /forum and /friends; dev.sh writes herald's VAPID keys into .env"
|
||||
- "Phase COVERAGE.md (livekit-client, LiveKit server, Centrifugo, Web Push)"
|
||||
affects: [20-05, 20-06]
|
||||
|
||||
actuals:
|
||||
tokens: 56900 # chars/4: the three layers' tracked files without lockfiles (56107 + 54654 + 63266) + vue-demo-app diff 3fe8018..9357711 without the lockfile (28917) + sm-demo-app diff b4fc7dc..fc23b4c in scripts, README and deploy (19375) + COVERAGE.md (5418) = 227737 chars
|
||||
tasks: 7
|
||||
commits: 1 # MEASURED in summercms.go: git rev-list --count b40c519..0301dc2 (COVERAGE.md) before this SUMMARY commit; code commits: vue-forum-layer 1, vue-userfriends-layer 1, vue-chatvideo-layer 1, vue-demo-app 5, sm-demo-app 4
|
||||
plan_head_before: b40c519 # summercms.go
|
||||
plan_head_after: 0301dc2ae48607c69847b3300ec844f80cad25d3 # summercms.go before this SUMMARY commit
|
||||
|
||||
tech-stack:
|
||||
added:
|
||||
- "livekit-client 2.23.0 (exact, vue-chatvideo-layer dependency; approved at the Task 3 checkpoint)"
|
||||
- "vue-forum-layer, vue-userfriends-layer, vue-chatvideo-layer (new shared Nuxt layers); every other package is an existing workspace pin (@nuxtjs/i18n 10.4.0, nuxt 4.4.8, vue 3.5.35, typescript 5.9.3, vitest 3.2.7)"
|
||||
patterns:
|
||||
- "Layer clients in app/utils carry a layer prefix on every export (forumError, friendTarget), because Nuxt auto-imports app/utils into the app"
|
||||
- "A companion layer (vue-chatvideo-layer) takes vue-chat-layer as a peer dependency, does not extend it, and dedupes it in Vite so the realtime module stays one instance"
|
||||
- "Token getter hooks per layer ($forumAuth, $userfriendsAuth), optional data hook ($userfriendsDirectory), $chatAuth reused by the companion layer"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../vue-forum-layer/app/utils/forumClient.ts
|
||||
- ../vue-forum-layer/app/components/Forum/Thread.vue
|
||||
- ../vue-forum-layer/README.md
|
||||
- ../vue-userfriends-layer/app/utils/friendsClient.ts
|
||||
- ../vue-userfriends-layer/app/components/Friends/Groups.vue
|
||||
- ../vue-userfriends-layer/README.md
|
||||
- ../vue-chatvideo-layer/app/lib/callMachine.ts
|
||||
- ../vue-chatvideo-layer/app/lib/videoClient.ts
|
||||
- ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts
|
||||
- ../vue-chatvideo-layer/README.md
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/forum/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/forum/t/[id].vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/friends.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue
|
||||
- .planning/phases/20-demo-instance-with-every-shared-plugin/COVERAGE.md
|
||||
modified:
|
||||
- ../sm-demo-app/vue-demo-app/package.json
|
||||
- ../sm-demo-app/vue-demo-app/pnpm-lock.yaml
|
||||
- ../sm-demo-app/vue-demo-app/nuxt.config.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/chat.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/account/security.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/layouts/default.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/TourCard.vue
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/smoke.sh
|
||||
- ../sm-demo-app/scripts/dev.sh
|
||||
- ../sm-demo-app/deploy/env.example
|
||||
- ../sm-demo-app/README.md
|
||||
|
||||
key-decisions:
|
||||
- "Task 3 checkpoint: the user approved livekit-client 2.23.0 (repository github.com/livekit/client-sdk-js, npm maintainer thedavidzhao, no install or postinstall hooks, npm provenance attestations, published 2026-10-16, 15 days old; compatibility with LiveKit server 1.13.1 not checked separately, the local 1.13.1 calls work)"
|
||||
- "Task 6 checkpoint: release. The subagent's tea repo create was refused by the permission system; the orchestrator, after the user's go-ahead in manual mode, created the three repositories public, pushed main and the annotated tags v0.1.0 (remote tags equal HEAD)"
|
||||
- "Decline posts video/leave: no chatvideo path publishes video:call:declined; the caller shows a did-not-answer note for a participant who left without joining"
|
||||
- "The last one out ends the call (video/end instead of video/leave), so the next start rings again"
|
||||
- "The call button's start answer is handed to the call page in memory (one start per call, no token in the URL)"
|
||||
- "Forum manage rights come from the host: ForumThread canManage, filled by the demo from the chat bootstrap's moderator flag"
|
||||
|
||||
patterns-established:
|
||||
- "check-local throwaway_user prints e-mail and JWT; LiveKit join tokens are validated with GET /rtc/validate, the token passed to curl through a config on stdin"
|
||||
|
||||
requirements-completed: [SC-2, D-11, D-12, D-13, D-14, D-15, D-16, D-20, D-21, D-22, D-23]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Members read the seeded EN/PL forum, create threads, reply, preview, edit and delete own posts; anonymous /forum has the register link to /register?next=/forum and no forum"
|
||||
requirement: "D-14, D-21, D-22"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "../sm-demo-app/scripts/check-local.sh forum"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "../vue-forum-layer/tests/client.test.ts"
|
||||
status: pass
|
||||
- kind: manual
|
||||
ref: "Playwright probe (scratchpad forum.cjs): categories, thread, preview, reply, edit, delete, new thread, no console error"
|
||||
status: pass
|
||||
human_judgment: true
|
||||
- id: D2
|
||||
description: "Friends, requests (accept, reject, cancel), unfriend, groups (create, invite code, join by code, leave); /friends linked from the chat sidebar, the header and /account/security"
|
||||
requirement: "D-15"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "../sm-demo-app/scripts/check-local.sh friends"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "../vue-userfriends-layer/tests/client.test.ts"
|
||||
status: pass
|
||||
- kind: manual
|
||||
ref: "Playwright probe (scratchpad friends.cjs) with two throwaway members"
|
||||
status: pass
|
||||
human_judgment: true
|
||||
- id: D3
|
||||
description: "DM-only call button; start, LiveKit token accepted, end; two members in a call with remote video, mute and camera off seen remotely, decline note, prompt cleared when the caller hangs up, server end ends the page's call"
|
||||
requirement: "D-11, D-12, D-13, D-23"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "../sm-demo-app/scripts/check-local.sh call"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "../vue-chatvideo-layer/tests/callMachine.test.ts"
|
||||
status: pass
|
||||
- kind: manual
|
||||
ref: "Playwright probe (scratchpad call.cjs) with fake media, against the link pins"
|
||||
status: pass
|
||||
human_judgment: true
|
||||
- id: D4
|
||||
description: "Herald VAPID keys in .env without printing them; public-key route 401 without and 200 with a JWT; no /_herald in goPaths"
|
||||
requirement: "D-16"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "../sm-demo-app/scripts/check-local.sh herald"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D5
|
||||
description: "Ten tour cards in EN and PL; vue-demo-app tests and build against the three tags"
|
||||
requirement: "D-03, D-20"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "check-local.sh tour; forum friends call chat tour after the tag pin"
|
||||
status: pass
|
||||
- kind: build
|
||||
ref: "pnpm --dir ../sm-demo-app/vue-demo-app test (209) && run build"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: about 2 h of work (14:13 to 15:15 for Tasks 1 to 5, then the release checkpoint and Task 7 until 20:03)
|
||||
completed: 2026-10-31
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 20 Plan 04: forum, friends and video-call layers v0.1.0 on the demo site Summary
|
||||
|
||||
**Three new shared layers are released at v0.1.0: vue-forum-layer (categories, threads, Markdown posts from the server's content_html), vue-userfriends-layer (friends, requests, groups with invite codes) and vue-chatvideo-layer (DM calls on livekit-client 2.23.0, loaded on demand). The demo site has /forum, /friends, /call/{conversation}, a call button in DM headers, an incoming-call prompt on every page, ten tour cards, and herald runs with VAPID keys and no UI.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Tasks:** 7/7. Task 3 (package legitimacy) and Task 6 (release go-ahead) were checkpoints answered by the user.
|
||||
- **Files:** vue-forum-layer 22, vue-userfriends-layer 22 and vue-chatvideo-layer 22 tracked files; vue-demo-app 5 commits; sm-demo-app 4 commits.
|
||||
|
||||
## The layers' public API (v0.1.0)
|
||||
|
||||
**vue-forum-layer**
|
||||
- Runtime config: `forum.apiBase` (`NUXT_FORUM_API_BASE`), `public.forum.apiBase` (`/_forum/api/v1`).
|
||||
- Hook: `$forumAuth` (token getter).
|
||||
- Components: `ForumPage` (contextType, contextId, threadPath), `ForumThread` (contextType, contextId, threadId, canManage, backPath), `ForumCategoryList`, `ForumThreadList`, `ForumPostEditor` (submit, preview, withTitle, …).
|
||||
- Composables: `useForum`, `useForumApi`, `useForumAuth`. Client: `createForumClient`, `ForumApiError`, `forumContextPath`, `forumError`.
|
||||
- Copy: `forum.*` EN and PL.
|
||||
|
||||
**vue-userfriends-layer**
|
||||
- Runtime config: `userfriends.apiBase`, `public.userfriends.apiBase` (`/_userfriends/api/v1`).
|
||||
- Hooks: `$userfriendsAuth` (token getter), optional `$userfriendsDirectory(): Promise<{id, name}[]>`.
|
||||
- Components: `FriendsPage`, `FriendsList`, `FriendsRequests`, `FriendsAddFriend`, `FriendsGroups`.
|
||||
- Composables: `useFriends` (useState keys `userfriends:*`), `useFriendsApi`, `useFriendsAuth`, `useFriendsDirectory`. Client: `createFriendsClient`, `FriendsApiError`, `friendTarget`, `friendsError`.
|
||||
- Copy: `friends.*` EN and PL.
|
||||
|
||||
**vue-chatvideo-layer**
|
||||
- Peer dependency `vue-chat-layer ^0.1.0` (not extended; the app extends both, chat first). Dependency `livekit-client` 2.23.0 exact.
|
||||
- Runtime config: `public.chatvideo.apiBase` (`/_chatvideo/api/v1`). Auth: vue-chat-layer's `$chatAuth`.
|
||||
- Components: `ChatvideoCallButton` (conversationId, callPath), `ChatvideoCall` (conversationId, start, backPath), `ChatvideoTile`, `ChatvideoIncomingCall` (callPath).
|
||||
- Composables: `useCall`, `useVideoClient`, `useIncomingCalls` (`RING_MS` 45 s).
|
||||
- Lib: `callMachine` (`initialCallState`, `transition`, `isLive`, `failureReason`), `videoClient` (`createVideoClient`, `VideoApiError`, `videoSessionChannel`, `videoPath`, `videoEvent`, `parseIncomingCall`, `rememberStart`, `takeStart`).
|
||||
- Copy: `chatvideo.*` EN and PL, reason keys `chatvideo.reason.*`.
|
||||
|
||||
## Task Commits
|
||||
|
||||
| # | Repo | Commit | Message |
|
||||
|---|------|--------|---------|
|
||||
| 1 | vue-forum-layer | dcd6549 | feat: forum layer: categories, threads and Markdown posts |
|
||||
| 1 | vue-demo-app | 2473517 | feat: /forum and /forum/t/{id} on vue-forum-layer |
|
||||
| 1 | sm-demo-app | c4a9cfc | test: check-local forum, smoke covers /forum |
|
||||
| 2 | vue-userfriends-layer | bcc8e99 | feat: friends layer: friends, requests and friend groups |
|
||||
| 2 | vue-demo-app | 4edc81f | feat: /friends on vue-userfriends-layer, linked from the chat and the account |
|
||||
| 2 | sm-demo-app | c2208e9 | test: check-local friends, smoke covers /friends |
|
||||
| 3 | — | — | checkpoint: approved livekit-client 2.23.0 |
|
||||
| 4 | vue-chatvideo-layer | 75e9a40 | feat: video-call layer: DM calls on LiveKit |
|
||||
| 4 | vue-demo-app | 1db4394 | feat: DM video calls on vue-chatvideo-layer |
|
||||
| 4 | sm-demo-app | c669717 | test: check-local call (DM start, LiveKit token validation, end) |
|
||||
| 4 | summercms.go | 0301dc2 | docs(20-04): API coverage of livekit-client, LiveKit, Centrifugo and Web Push |
|
||||
| 5 | sm-demo-app | fc23b4c | feat: herald VAPID keys without UI, check-local herald and the ten-card tour |
|
||||
| 5 | vue-demo-app | cc8d330 | feat: Forum, Friends and Calls tour cards |
|
||||
| 6 | — | — | checkpoint: release |
|
||||
| 7 | vue-forum-layer, vue-userfriends-layer, vue-chatvideo-layer | tags v0.1.0 | created, pushed and tagged by the orchestrator (below) |
|
||||
| 7 | vue-demo-app | 9357711 | feat: pin the forum, friends and video-call layers v0.1.0 |
|
||||
|
||||
**Release (Task 7).** The subagent's `tea repo create` was refused by the permission system ("Create Public Surface"), so nothing was created from the subagent. After the user's go-ahead (in manual permission mode), the orchestrator created `golem15/vue-forum-layer`, `golem15/vue-userfriends-layer` and `golem15/vue-chatvideo-layer` public (vue-faq-layer's visibility), pushed `main` and the annotated tags `v0.1.0`. `ls-remote 'refs/tags/v0.1.0^{}'` equals HEAD for each: dcd6549, bcc8e99, 75e9a40. The subagent then pinned the tags in vue-demo-app.
|
||||
|
||||
**Not pushed:** vue-demo-app and sm-demo-app (plan 05). sm-demo-app shows the moved `vue-demo-app` submodule pointer as uncommitted.
|
||||
|
||||
## Checkpoint answers
|
||||
|
||||
- **Task 3:** approved livekit-client 2.23.0. Facts checked by the orchestrator: repository github.com/livekit/client-sdk-js, npm maintainer thedavidzhao, no install or postinstall hooks, npm provenance attestations, published 2026-10-16 (15 days old). Compatibility with LiveKit server 1.13.1 was not checked from the release notes; calls on the local 1.13.1 work. Installed with `--save-exact`; lockfile integrity `sha512-j9Kg86nJ…`.
|
||||
- **Task 6:** release.
|
||||
|
||||
## Verification
|
||||
|
||||
- **Layers:** forum `pnpm test` 7/7, friends 6/6, chatvideo vitest 10/10; `pnpm build:playground` builds for all three.
|
||||
- **vue-demo-app:** `pnpm test` 209/209 and `pnpm run build` after every task and against the tags.
|
||||
- **check-local.sh:** `forum` (Task 1), `friends forum chat` (Task 2), `call chat` (Task 4), `herald tour` (Task 5), `forum friends call chat tour herald` and `back remote realtime quizzes journal` (before the release), `forum friends call chat tour` against the tags (Task 7): all ok.
|
||||
- **smoke.sh:** `smoke: ok`, with /forum and /friends in the page loop and their anonymous prompts.
|
||||
- **Browser probes** (Playwright, throwaway members, fake media, against the link pins): the forum, friends and call flows listed in the coverage block passed with no console error. Against the tags, the call probe's ring step failed five times in a row because the stale servers took every incoming-call broadcast (environment notes); the tagged install itself resolves one vue-chat-layer copy (one entry in `node_modules/.pnpm`) and passes check-local call and chat.
|
||||
- **Task 5 manual check:** `dev.sh up` printed only "added the herald VAPID keys to .env"; no line of the output holds a key value. A second `dev.sh seed` added nothing. The plan's `grep .env` was blocked by the secret-read hook; `check-local herald` (200 with a non-empty publicKey) shows the key is loaded.
|
||||
- **Acceptance greps:** all print the expected values (no consuming-app names in the layers, v-html only on content_html, one `import('livekit-client')`, no static runtime import, every `subscribe(` line uses `videoSessionChannel`, exact livekit pin, one `conversation-actions`, one `sidebar-footer`, one `to="/friends"` in SiteHeader, no `'/_herald'`, three tour keys, `HERALD__VAPID__PRIVATE_KEY=` once and empty, no OPT-OUT row without a reason, no link pins left).
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Decline has no declined event on the server**
|
||||
- **Found during:** Task 4 (read video_service.go as the plan asked).
|
||||
- **Issue:** `Notifier.Declined` exists, but no VideoService path calls it; `Leave` publishes `video:participant:left`. No endpoint publishes `video:call:declined`.
|
||||
- **Fix:** Decline posts `video/leave`. The caller's page treats `video:participant:left` (and `video:call:declined`, should it ever come) for a participant who never connected as a decline and shows "did not answer". The shared plugin is unchanged (follow-up below).
|
||||
- **Commit:** 75e9a40.
|
||||
|
||||
**2. [Rule 1 - Bug] A left-open session never rings again**
|
||||
- **Found during:** Task 4.
|
||||
- **Issue:** `start` answers the live session without a new `video:call:incoming` when one exists. If both members only posted `leave`, the session stayed open until the reconcile job, and the next call from the DM would not ring.
|
||||
- **Fix:** Leave posts `video/end` when nobody else is in the room (the last one out ends the call), else `video/leave`. Both use `keepalive` so pagehide still sends them.
|
||||
- **Commit:** 75e9a40.
|
||||
|
||||
**3. [Rule 2 - Missing critical] One start per call**
|
||||
- **Issue:** The plan has both the button and the call page start the call; `video-initiate` allows 5 starts a minute.
|
||||
- **Fix:** The button keeps its start answer in memory for 60 s (`rememberStart`), and the page takes it once (`takeStart`) before starting itself. The join token never goes into a URL.
|
||||
- **Commit:** 75e9a40.
|
||||
|
||||
**4. Forum manage rights from the host**
|
||||
- The forum API does not report manage rights. `ForumThread` takes `canManage`; the demo thread page fills it from `GET /_demo/api/v1/chat`'s `moderator` flag (the same group the forum policy checks). A refused action hides itself for the session.
|
||||
- **Commit:** dcd6549, 2473517.
|
||||
|
||||
**5. [Rule 3 - Blocking] Auto-import collisions**
|
||||
- Nuxt auto-imports `app/utils` into the app, so the layers' generic helper names would collide. Exports carry the layer's prefix: `forumError`, `forumContextPath`, `friendsError`, `friendTarget`.
|
||||
- **Commit:** dcd6549, bcc8e99.
|
||||
|
||||
**6. [Rule 3 - Blocking] One vue-chat-layer copy**
|
||||
- With the development `link:` pin, the linked checkout's own `node_modules/vue-chat-layer` (its dev dependency) would be a second realtime module that never hears the chat's events. vue-chatvideo-layer's nuxt.config sets `vite.resolve.dedupe: ['vue-chat-layer']`. With the link pin the incoming-call prompt works; with the tag install pnpm resolves the peer to the app's copy.
|
||||
- **Commit:** 75e9a40.
|
||||
|
||||
**7. Smaller additions**
|
||||
- check-local.sh: `throwaway_user` (e-mail and JWT) with `throwaway_jwt` on top of it; `check_call` reads Ada's id from `/chat/members`.
|
||||
- smoke.sh: the anonymous prompts of /forum and /friends are checked, not only the page loop.
|
||||
- `ensure_vapid` runs at the end of `seed()`, so `up` and `seed` both cover it.
|
||||
- The add-friend picker hides current friends and people with a pending request.
|
||||
- App copy lives under `forum.*`, `friends.*` and `call.*` next to the layers' trees (distinct keys), plus `header.friends`, `chat.friendsLink` and `security.friendsLink`.
|
||||
- The plan's draft progress SUMMARY after Task 4 was skipped on the orchestrator's instruction; this SUMMARY is the only one.
|
||||
|
||||
**Total deviations:** 7. **Impact:** none on the plan goal; 1 and 2 make the call flow work with the plugin as it is.
|
||||
|
||||
## Follow-ups
|
||||
|
||||
- **sm-chatvideo-plugin:** `Notifier.Declined` is never called. A decline route (or `Leave` publishing `video:call:declined` for a participant still in status invited) would let the layer drop its participant-left inference. Not needed for this phase.
|
||||
- **Herald:** the boot warning "PresenceGate is deny-all; the host must SetPresenceGate" remains; it matters only once push is sent (D-16 defers the subscribe UI).
|
||||
|
||||
## Environment notes
|
||||
|
||||
- **Stale demo servers share the local database.** `./bin/demo serve` pid 684528 (user jin, 127.0.0.1:8099, since Oct 22, in sm-demo-app) and pid 2918923 (user golem, 0.0.0.0:8096, since Oct 20) run River workers on `127.0.0.1:55540/summercms_demo` and take `summer.broadcast` jobs. Since the release, the current server ran 7 of about 50 broadcasts; the stale ones ran the rest, and their pushes do not reach the current Centrifugo clients. A Node test without a browser received 4 of 6 incoming-call pushes earlier; later the browser ring step failed 5 runs in a row. They were left running (not approved to stop). Stop them before plan 06's browser tests.
|
||||
- **Headless Chrome** sometimes hits `ERR_NETWORK_CHANGED` (the host's network interfaces change, likely docker), which breaks page loads in probes.
|
||||
- **Vite dev re-optimization:** the first `check-local chat` after adding a layer got a 504 "Outdated Optimize Dep" and passed on the rerun (dev server only).
|
||||
- **Local secrets in a tool log:** while diagnosing, the Centrifugo `PROXY_SECRET`, `TOKEN_SECRET` and `API_KEY` from pid 684528's environment were printed into the session's tool output. They are local development values and were never committed; removing the `SUMMER_REALTIME__CENTRIFUGO__*` lines from `.env` and running `dev.sh up` rotates them.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
| Flag | File | Description |
|
||||
|------|------|-------------|
|
||||
| threat_flag: supply-chain | ../vue-chatvideo-layer/package.json | New third-party dependency livekit-client 2.23.0 (exact), installed after the Task 3 checkpoint as planned in T-20-SC |
|
||||
| threat_flag: supply-chain | ../sm-demo-app/vue-demo-app/package.json | Three new git dependencies pinned by tag v0.1.0 (commits dcd6549, bcc8e99, 75e9a40 in the lockfile) |
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- **Plan 05:** vue-demo-app pins every layer by tag and has no link pin, so it can be pushed. The sm-demo-app submodule pointer bump is still to do. The deploy needs `/_forum`, `/_userfriends` and `/_chatvideo` routed to Go in nginx (not `/_herald`), the herald VAPID keys in rome's `.env`, and LiveKit reachable at the production `livekit_url`.
|
||||
- **Plan 06:** the call machine and the three clients have unit tests to extend; browser checks of the call flow need the stale servers stopped.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- Layer commits exist: vue-forum-layer dcd6549, vue-userfriends-layer bcc8e99, vue-chatvideo-layer 75e9a40; remote tags v0.1.0 peel to them.
|
||||
- vue-demo-app: 2473517, 4edc81f, 1db4394, cc8d330, 9357711. sm-demo-app: c4a9cfc, c2208e9, c669717, fc23b4c. summercms.go: 0301dc2.
|
||||
- The key files listed above exist in their repos.
|
||||
@@ -0,0 +1,359 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 05
|
||||
type: execute
|
||||
wave: 5
|
||||
depends_on: ["20-02", "20-03", "20-04"]
|
||||
files_modified:
|
||||
- ../sm-demo-app/deploy/nginx/demo.summercms.io.conf
|
||||
- ../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf
|
||||
- ../sm-demo-app/deploy/livekit.yaml.example
|
||||
- ../sm-demo-app/deploy/env.example
|
||||
- ../sm-demo-app/config/env/production/golem15.chatvideo.yaml
|
||||
- ../sm-demo-app/scripts/check-deploy.sh
|
||||
- ../sm-demo-app/scripts/check-live.sh
|
||||
- ../sm-demo-app/DEPLOY.md
|
||||
- ../sm-demo-app/README.md
|
||||
- ../sm-demo-app/vue-demo-app
|
||||
autonomous: false
|
||||
requirements: [SC-2, SC-3, D-10, D-12, D-16, D-20, D-21]
|
||||
estimate:
|
||||
tokens: 240000
|
||||
raw_tokens: 240000
|
||||
tasks: 6
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "D-10: rome runs the demo's own LiveKit 1.13.1 under supervisor as summercms-demo-livekit (user summercms-demo, config /srv/summercms-demo/livekit.yaml, 0640 root:summercms-demo, own key pair also in /srv/summercms-demo/.env), signal on 127.0.0.1:7890 behind nginx location /livekit/, ICE TCP 7891 and UDP mux 7892 on the public address; it does not touch WavePath's LiveKit (7880, 7881, 50000-60000) or its keys."
|
||||
- "D-10: Vuurmuur on rome allows TCP 7891 and UDP 7892 from the internet to the firewall through a rule the user approved; DEPLOY.md documents the service, the rule, how to verify it and how to remove it."
|
||||
- "D-12: the deployed LiveKit has room max_participants 4, empty_timeout 120 and departure_timeout 20; production chatvideo config keeps max_duration 900 and max_participants 4; the chatvideo reconcile job runs every 5 minutes inside serve."
|
||||
- "D-16: rome's .env holds herald VAPID keys generated on rome with herald:vapid-generate; /_herald is not routed by nginx."
|
||||
- "SC-3: after the release https://demo.summercms.io serves /chat, /forum, /friends and /call/{id} with the banner and the backend call to action; /backend and /backend/x answer 404; anonymous /chat and /forum show the register prompt (D-04, D-21); the admin stays at /smbackend as decided in 19.4.1."
|
||||
- "SC-2: on the live demo the chat-family APIs answer 401 without a JWT under /_chat, /_chatchannels, /_chatbots, /_chatvideo, /_forum and /_userfriends, /livekit/rtc/validate reaches LiveKit, /ws upgrades to Centrifugo, and the Centrifugo config on rome has the chat, user and video namespaces."
|
||||
- "scripts/check-deploy.sh proves locally that nginx, supervisor, livekit.yaml.example and the production chatvideo config agree on ports (7890, 7891, 7892) and caps, that each chat-family prefix goes to the Go port and that /_herald is not routed; scripts/check-live.sh https://demo.summercms.io prints check-live: ok after the release."
|
||||
- "vue-demo-app's master is pushed before sm-demo-app's pointer bump commit; sm-demo-app is pushed with the go-ahead; robots.txt on the live site disallows the new API prefixes."
|
||||
artifacts:
|
||||
- path: "../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf"
|
||||
provides: "supervisor program summercms-demo-livekit"
|
||||
contains: "program:summercms-demo-livekit"
|
||||
- path: "../sm-demo-app/deploy/nginx/demo.summercms.io.conf"
|
||||
provides: "Go locations for the chat family and the /livekit/ WebSocket location"
|
||||
contains: "location ^~ /livekit/"
|
||||
- path: "../sm-demo-app/config/env/production/golem15.chatvideo.yaml"
|
||||
provides: "production livekit_url and livekit_admin_url"
|
||||
contains: "wss://demo.summercms.io/livekit"
|
||||
- path: "../sm-demo-app/DEPLOY.md"
|
||||
provides: "LiveKit, firewall, chat family release, verify and rollback"
|
||||
contains: "summercms-demo-livekit"
|
||||
key_links:
|
||||
- from: "../sm-demo-app/deploy/nginx/demo.summercms.io.conf"
|
||||
to: "../sm-demo-app/deploy/livekit.yaml.example"
|
||||
via: "proxy_pass http://127.0.0.1:7890/ equals LiveKit port 7890 (check-deploy compares)"
|
||||
pattern: "127\\.0\\.0\\.1:7890"
|
||||
- from: "../sm-demo-app/config/env/production/golem15.chatvideo.yaml"
|
||||
to: "../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf"
|
||||
via: "livekit_admin_url http://127.0.0.1:7890 is the program's signal port"
|
||||
pattern: "livekit_admin_url"
|
||||
- from: "../sm-demo-app/scripts/check-live.sh"
|
||||
to: "../sm-demo-app/deploy/nginx/demo.summercms.io.conf"
|
||||
via: "live 401s under the chat-family prefixes and LiveKit's answer on /livekit/rtc/validate"
|
||||
pattern: "/livekit/rtc/validate"
|
||||
prohibitions:
|
||||
- statement: "No change to WavePath's LiveKit program, its config /etc/livekit/livekit.yaml or its ports, and no second key on its server."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "No secret value (LiveKit, VAPID, Centrifugo) appears in a committed file, the SUMMARY, a log line or a command line; values are generated on rome."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "No push, rome change or firewall change happens before its checkpoint is answered; raw iptables is never used (Vuurmuur manages rome's INPUT chain)."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): the demo is deployed publicly with the chat family, the frontend open, `/backend` unreachable and the backend call to action shown.
|
||||
|
||||
This plan's slice (plan 5 of 6, wave 5, per D-20): the rome deploy of everything plans 01 to 04 built. That means the demo's own LiveKit under supervisor, the Vuurmuur rule for its media ports (a checkpoint, shared production host), nginx locations, `.env` keys (LiveKit, VAPID), the Centrifugo namespaces, the release, DEPLOY.md, and the check-deploy and check-live extensions.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Media path (D-10 discretion):** ICE over the UDP mux port 7892 with ICE-TCP 7891 as fallback, and no embedded TURN. nginx `stream` with `ssl_preread` would restructure every 443 vhost on a shared host (RESEARCH Alternatives). If NAT'd browsers fail in plan 06's live check, the fallback recorded in DEPLOY.md is LiveKit's embedded TURN on UDP 3478 and TLS 5349 with a DNS-only host name, which needs a new checkpoint.
|
||||
- **Signal path:** same origin under `/livekit` (`livekit_url: wss://demo.summercms.io/livekit`). livekit-client appends `/rtc`, so nginx `location ^~ /livekit/` proxies to `http://127.0.0.1:7890/` with the WebSocket upgrade headers, `proxy_read_timeout 7d` and `proxy_buffering off`, as lk.wavepath.org does. Go talks to the RoomService on loopback (`livekit_admin_url: http://127.0.0.1:7890`).
|
||||
- **ICE reveals rome's public address** despite Cloudflare. This is accepted, because rome already exposes services on that address (RESEARCH Security Domain). DEPLOY.md says so.
|
||||
- **Admin stays at /smbackend** (19.4.1's decision change of 2026-10-20, RESEARCH Open Question 1). `/backend` stays 404. The deploy checkpoint restates it.
|
||||
- **Robots:** the new prefixes go into SEO › robots.txt on rome (the DEPLOY.md "SEO" procedure). `/_herald` stays unrouted and so needs no line.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
## Artifacts this phase produces (this plan)
|
||||
|
||||
- Supervisor program `summercms-demo-livekit` (`deploy/supervisor/summercms-demo-livekit.conf`); rome files `/srv/summercms-demo/livekit.yaml` and `/etc/supervisor/conf.d/summercms-demo-livekit.conf`.
|
||||
- nginx locations `^~ /_chat/`, `^~ /_chatchannels/`, `^~ /_chatbots/`, `^~ /_chatvideo/`, `^~ /_forum/`, `^~ /_userfriends/` (Go, 127.0.0.1:8098) and `^~ /livekit/` (LiveKit, 127.0.0.1:7890).
|
||||
- `config/env/production/golem15.chatvideo.yaml` (`livekit_url`, `livekit_admin_url`).
|
||||
- env keys on rome: `SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_KEY`, `SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_SECRET`, `SUMMER_GOLEM15__HERALD__VAPID__PUBLIC_KEY`, `__PRIVATE_KEY`, `__SUBJECT` (names only in git).
|
||||
- Vuurmuur service `summercms-demo-livekit` and its rule (rome).
|
||||
- check-deploy.sh LiveKit and chat-family checks; check-live.sh chat-family checks; DEPLOY.md sections "LiveKit (the demo's own)", "Firewall (Vuurmuur)", "Chat family"; the sm-demo-app pointer bump of vue-demo-app.
|
||||
|
||||
<objective>
|
||||
Deploy the chat family to the live demo on rome: LiveKit, firewall, nginx, keys, Centrifugo namespaces and the release, with the checks and the runbook to keep it repeatable.
|
||||
|
||||
Purpose: SC-3 (deployed publicly, /backend unreachable, call to action) and the live half of SC-2, D-10, D-12 and D-16 on rome.
|
||||
Output: commits in ../sm-demo-app, pushes of vue-demo-app and sm-demo-app, and changes on rome, all after the go-ahead.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-RESEARCH.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-02-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-04-SUMMARY.md
|
||||
|
||||
Repo: ../sm-demo-app (deploy files, scripts, DEPLOY.md), its submodule vue-demo-app (push only). Host: rome over `ssh -p 2222 debian@10.8.3.118` (passwordless sudo; the `rome` alias does not resolve here), with the variables `$RSH` and `$ROME` used in DEPLOY.md. Read-only on rome: WavePath's `/etc/livekit/livekit.yaml` and `wavepath-livekit` program, `/etc/vuurmuur/services`, `/etc/vuurmuur/rules/rules.conf`.
|
||||
|
||||
Rules: no co-author tags; stage by explicit path; push vue-demo-app first, then commit and push the pointer bump in sm-demo-app (core-plugins-own-repos note); secrets are generated on rome with `openssl rand` or `herald:vapid-generate` and written by remote commands that never echo values; follow DEPLOY.md's Build, Upload and Release sections; nothing changes on rome and nothing is pushed before Task 3's answer; the firewall changes only after Task 5's answer.
|
||||
|
||||
<interfaces>
|
||||
sm-demo-app deploy today: deploy/nginx/demo.summercms.io.conf (one `location ^~ /_<prefix>/` per Go prefix with proxy_pass http://127.0.0.1:8098, `location = /ws` to Centrifugo 8010 with Upgrade headers, `location ^~ /backend { return 404; }`, `/smbackend` to Go), deploy/supervisor/summercms-demo-centrifugo.conf (program shape), deploy/centrifugo.json.example (namespaces from plan 02), deploy/livekit.yaml.example (plan 02), scripts/check-deploy.sh (nginx -t in a temp prefix, supervisor parse, port agreement, prints "check-deploy: ok"), scripts/check-live.sh (bad, get, header, ws_upgrade helpers; prints "check-live: ok"), DEPLOY.md (Overview, Launch checklist, One-time server setup, Realtime, MCP endpoint, SEO, Build, Upload, Release, Verify, Rollback, Reset, Secrets).
|
||||
RESEARCH facts: rome LiveKit 1.13.1 at /usr/local/bin/livekit-server; WavePath's program uses 7880, 7881/tcp and 50000-60000/udp; ports 7890-7892 were free on 2026-10-28 (re-check with `ss -ltnup`); rome's INPUT policy is DROP under Vuurmuur (vrmr NFLOG prefixes); a Vuurmuur service Livekit exists but no rule uses it.
|
||||
LiveKit validate endpoint: GET /rtc/validate answers 401 without a token and 200 with a valid one.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: the deploy files carry one chat-family release end to end, proven locally by check-deploy before rome is touched</name>
|
||||
<precondition>The plan 04 SUMMARY records the three layer tags pinned in vue-demo-app; `git -C ../sm-demo-app status --porcelain` and `git -C ../sm-demo-app/vue-demo-app status --porcelain` list no foreign edit in the files of this task.</precondition>
|
||||
<files>../sm-demo-app/deploy/nginx/demo.summercms.io.conf, ../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf, ../sm-demo-app/deploy/livekit.yaml.example, ../sm-demo-app/deploy/env.example, ../sm-demo-app/config/env/production/golem15.chatvideo.yaml, ../sm-demo-app/scripts/check-deploy.sh, ../sm-demo-app/scripts/check-live.sh, ../sm-demo-app/DEPLOY.md, ../sm-demo-app/README.md</files>
|
||||
<read_first>../sm-demo-app/deploy/nginx/demo.summercms.io.conf (whole file), deploy/supervisor/summercms-demo-centrifugo.conf, deploy/livekit.yaml.example, deploy/env.example, config/env/production/*.yaml, scripts/check-deploy.sh (whole file), scripts/check-live.sh (whole file), DEPLOY.md (whole file), 20-RESEARCH.md (Pitfalls 6, 7, 8, 11; Supervisor program and LiveKit config blocks)</read_first>
|
||||
<action>Per D-10, D-12, D-16, SC-2, SC-3.
|
||||
- nginx: add `location ^~ /_chat/`, `/_chatchannels/`, `/_chatbots/`, `/_chatvideo/`, `/_forum/` and `/_userfriends/` with the exact /_demo/ block, and `client_max_body_size 2m` on /_chat/ for attachments (chat's 1 MiB upload limit plus multipart overhead). Add `location ^~ /livekit/` with proxy_pass `http://127.0.0.1:7890/`, `proxy_http_version 1.1`, the Upgrade and Connection headers, Host and X-Forwarded headers, `proxy_read_timeout 7d`, `proxy_send_timeout 7d` and `proxy_buffering off`, and a comment that media bypasses nginx. Update the `/api/realtime/token` comment: every demo member now gets a token (demo.realtime-access). Add nothing for /_herald.
|
||||
- deploy/supervisor/summercms-demo-livekit.conf: RESEARCH's program block, with a header comment in the Centrifugo file's style (ports, config path and mode, binary, that WavePath's instance is separate).
|
||||
- deploy/livekit.yaml.example: confirm or adjust the plan 02 file so production uses `use_external_ip: true`, and comment the rome install command.
|
||||
- config/env/production/golem15.chatvideo.yaml: `livekit_url: "wss://demo.summercms.io/livekit"`, `livekit_admin_url: "http://127.0.0.1:7890"`.
|
||||
- deploy/env.example: the herald subject key with its comment, if plan 04 left it out.
|
||||
- check-deploy.sh, new checks with header lines:
|
||||
- summercms-demo-livekit.conf parses and declares its program with the user summercms-demo;
|
||||
- LiveKit ports agree: the example's `port` equals the nginx /livekit/ proxy_pass port and the production livekit_admin_url port; `rtc.tcp_port` 7891 and `rtc.udp_port` 7892 are set, no port_range key is set, and bind_addresses is 127.0.0.1;
|
||||
- room.max_participants equals config/golem15.chatvideo.yaml max_participants (D-12, D-23);
|
||||
- each of the six chat-family prefixes is a location proxied to the Go port;
|
||||
- no location routes /_herald;
|
||||
- the example holds placeholder keys only.
|
||||
Parse YAML with python3 as the script already does for JSON, and fail with one line per mismatch.
|
||||
- check-live.sh, new checks with header lines:
|
||||
- /chat, /forum and /friends answer 200 with the banner and a register link (D-04, D-21);
|
||||
- GET /_chatchannels/api/v1/contexts/demo/1/channels, /_forum/api/v1/contexts/demo/1/categories, /_userfriends/api/v1/friends, /_chatbots/api/v1/commands and /_chatvideo/api/v1/conversations/1/video/status answer 401;
|
||||
- GET /livekit/rtc/validate answers 401 (or 400) from LiveKit, not Nuxt's HTML 404 (the body is not text/html);
|
||||
- GET /_herald/api/v1/push/vapid-public-key does not answer JSON from Go;
|
||||
- robots.txt holds `Disallow: /_chat` and `Disallow: /_forum`.
|
||||
- DEPLOY.md:
|
||||
- Overview: ports 7890-7892, the new program;
|
||||
- One-time server setup "LiveKit (the demo's own)": install the config with generated keys, the supervisor program, verify with curl on 127.0.0.1:7890;
|
||||
- "Firewall (Vuurmuur)": the service definition (TCP 7891, UDP 7892), the rule from any to the firewall, `vuurmuur_script` apply and reload, verification with `ss -lunp` and `iptables -S | grep 789`, and removal;
|
||||
- "Chat family": the .env keys, the Centrifugo namespaces and when to restart Centrifugo, the VAPID keys, the robots.txt lines to add;
|
||||
- Verify: the new check-live items;
|
||||
- Rollback: stopping summercms-demo-livekit turns calls off only;
|
||||
- Reset: the chat family is included.
|
||||
README links to the new sections.
|
||||
|
||||
Commit `feat: deploy files for the chat family and the demo's LiveKit`.</action>
|
||||
<verify>
|
||||
<automated>../sm-demo-app/scripts/check-deploy.sh 2>&1 | tail -1 | grep -qx 'check-deploy: ok' && bash -n ../sm-demo-app/scripts/check-live.sh</automated>
|
||||
<fails_when>The last line is not "check-deploy: ok" (nginx -t fails with the new locations, a port or cap mismatch, a missing prefix, a routed /_herald, or a supervisor parse error), or check-live.sh has a syntax error.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'location ^~ /livekit/' ../sm-demo-app/deploy/nginx/demo.summercms.io.conf` prints 1.
|
||||
- `grep -cE 'location \^~ /_(chat|chatchannels|chatbots|chatvideo|forum|userfriends)/' ../sm-demo-app/deploy/nginx/demo.summercms.io.conf` prints 6.
|
||||
- `grep -c '\[program:summercms-demo-livekit\]' ../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf` prints 1.
|
||||
- `grep -c 'Vuurmuur' ../sm-demo-app/DEPLOY.md` prints at least 2.
|
||||
</acceptance_criteria>
|
||||
<done>The repository holds every file the rome release needs, and the local check proves they agree.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Read rome's current state and prepare the release build without changing rome</name>
|
||||
<files>../sm-demo-app/DEPLOY.md</files>
|
||||
<read_first>../sm-demo-app/DEPLOY.md (Build, Upload, Release, Secrets), ../sm-demo-app/scripts/build.sh, .planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/19.4.1-02-SUMMARY.md (first deploy notes)</read_first>
|
||||
<action>Per D-10 and SC-3. Read-only on rome:
|
||||
- `ss -ltnup` filtered on 7890, 7891 and 7892 (free?);
|
||||
- `supervisorctl status`;
|
||||
- `grep -c` for each new key name in /srv/summercms-demo/.env (counts only, never values);
|
||||
- whether /srv/summercms-demo/centrifugo.json lists the chat namespace (`grep -c '"chat"'`);
|
||||
- `ls /etc/vuurmuur/services` and `grep -n Livekit /etc/vuurmuur/rules/rules.conf` (no edit);
|
||||
- `/usr/local/bin/livekit-server --version`.
|
||||
Locally:
|
||||
- `scripts/check-pins.sh`, `scripts/build.sh release` (refuses a dirty tree or off-tag submodules) and `scripts/smoke.sh` against the release build as DEPLOY.md's Build section says;
|
||||
- `git -C vue-demo-app status` (the commits from plans 03 and 04 are local only) and `git log origin/master..master` in both repositories.
|
||||
Record everything in a deploy table for the Task 3 question. If a port is taken, pick the next free trio and update the deploy files and check-deploy in a commit before asking. If DEPLOY.md's Build steps no longer match the scripts, fix them in DEPLOY.md.</action>
|
||||
<verify>
|
||||
<automated>../sm-demo-app/scripts/check-pins.sh && ../sm-demo-app/scripts/build.sh release && ../sm-demo-app/scripts/smoke.sh</automated>
|
||||
<fails_when>Non-zero exit: a submodule off its go.mod tag, the release build refuses (dirty tree, stale ROADMAP snapshot) or fails to compile without go.work, or smoke.sh reports a missing banner, an admin path or a credential on a rendered page.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- The SUMMARY's deploy table lists rome's listeners on 7890-7892 (or the chosen trio), the supervisor programs, which env keys exist (counts only), whether centrifugo.json has the chat namespace, the LiveKit version and the unpushed commits per repository.
|
||||
- No file on rome changed (no sudo write command was run).
|
||||
</acceptance_criteria>
|
||||
<done>The release build is ready and the go-ahead question rests on rome's actual state.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 3: Go-ahead to push the demo and deploy the chat family to rome</name>
|
||||
<read_first>The Task 2 deploy table; ../sm-demo-app/DEPLOY.md sections "LiveKit (the demo's own)", "Chat family" and "Release"</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user chose one option and it is recorded in the SUMMARY.
|
||||
</acceptance_criteria>
|
||||
<decision>Push vue-demo-app and sm-demo-app and release the chat family on rome now (LiveKit program, keys, nginx, Centrifugo namespaces, binary and site)?</decision>
|
||||
<context>The release changes a shared production host: a new supervisor program (summercms-demo-livekit on 127.0.0.1:7890), new .env keys generated on rome (LiveKit and VAPID), an nginx reload for the demo vhost, a Centrifugo restart for the demo's own instance, a migration of the chat-family tables and demo:seed. WavePath's LiveKit and keys are not touched. The admin stays at /smbackend with login (19.4.1's decision) and /backend stays 404. Media ports stay closed until the separate firewall question (Task 5), so calls connect only after that. Rollback is in DEPLOY.md (previous binary and site; stop the LiveKit program).</context>
|
||||
<options>
|
||||
<option id="deploy">
|
||||
<name>Push and deploy</name>
|
||||
<pros>Chat, forum and friends go live; calls follow after the firewall rule.</pros>
|
||||
<cons>Changes rome; the new tables are migrated (not reversed on rollback).</cons>
|
||||
</option>
|
||||
<option id="push-only">
|
||||
<name>Push the repositories, deploy later</name>
|
||||
<pros>Code is on origin and reviewed; rome is unchanged.</pros>
|
||||
<cons>SC-3 stays open; plan 06's live verification waits.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>Nothing leaves this machine.</pros>
|
||||
<cons>The phase cannot verify live.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "deploy", "push-only" or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Release: push, install LiveKit and keys on rome, roll out the binary and site, and check the live demo</name>
|
||||
<precondition>Task 3 answered "deploy" (or "push-only", which runs steps 1 and 2 only).</precondition>
|
||||
<files>../sm-demo-app/vue-demo-app, ../sm-demo-app/DEPLOY.md</files>
|
||||
<read_first>../sm-demo-app/DEPLOY.md (whole runbook), the Task 2 deploy table</read_first>
|
||||
<action>Per D-10, D-12, D-16, SC-2, SC-3.
|
||||
1. Push vue-demo-app master, then in sm-demo-app commit the pointer bump `chore: bump vue-demo-app (chat, forum, friends, calls)` and push sm-demo-app.
|
||||
2. Confirm both remotes equal local HEAD (`git ls-remote`).
|
||||
3. On rome, following DEPLOY.md. Never echo or log a value; write secrets with remote heredocs fed from `openssl rand` inside the remote shell.
|
||||
- Generate a LiveKit key and secret.
|
||||
- Install /srv/summercms-demo/livekit.yaml (0640 root:summercms-demo) from the example with them, and append the same values to .env as the SUMMER_GOLEM15__CHATVIDEO__ keys.
|
||||
- Run `herald:vapid-generate --json -q` with the new binary on rome and append the VAPID keys. Set the subject to the demo's contact address from ~/.config/summercms/demo-secrets.env, sent over SSH stdin.
|
||||
- Update /srv/summercms-demo/centrifugo.json: merge the chat, user and video namespaces from the example while keeping its secrets, run `centrifugo checkconfig`, and restart summercms-demo-centrifugo.
|
||||
- Install and start summercms-demo-livekit (reread, update, status RUNNING) and check that `curl -s http://127.0.0.1:7890/` answers OK on rome.
|
||||
- Upload and release the build per DEPLOY.md (migrate, demo:seed, swap, restart), then install the nginx file and reload.
|
||||
- Add the robots.txt lines for the six prefixes through SEO › robots.txt (DEPLOY.md "SEO"; through an SSH tunnel to the admin with the credentials in /root/summercms-demo-admin.txt, or the seo MCP tools with the administrator's connector). If neither path works unattended, list it for the user in Task 6.
|
||||
4. Run `scripts/check-live.sh https://demo.summercms.io`. The /livekit/rtc/validate check passes without the firewall rule, because signalling goes through nginx.
|
||||
5. Record in DEPLOY.md any step that differed from the runbook.</action>
|
||||
<verify>
|
||||
<automated>[ "$(git -C ../sm-demo-app ls-remote origin refs/heads/master | cut -f1)" = "$(git -C ../sm-demo-app rev-parse HEAD)" ] && ../sm-demo-app/scripts/check-live.sh https://demo.summercms.io 2>&1 | tail -1 | grep -qx 'check-live: ok'</automated>
|
||||
<fails_when>sm-demo-app's remote master differs from HEAD (not pushed), or check-live's last line is not "check-live: ok" (a chat-family prefix not 401, /livekit not reaching LiveKit, /backend not 404, missing banner or call to action, robots lines missing, or /ws not 101).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `ssh -p 2222 debian@10.8.3.118 sudo supervisorctl status summercms-demo-livekit` shows RUNNING.
|
||||
- `ssh -p 2222 debian@10.8.3.118 'sudo grep -c "^SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_SECRET=." /srv/summercms-demo/.env'` prints 1 (count only).
|
||||
- `ssh -p 2222 debian@10.8.3.118 sudo supervisorctl status wavepath-livekit` shows the same uptime it showed in Task 2 (not restarted).
|
||||
- The SUMMARY holds no secret value.
|
||||
</acceptance_criteria>
|
||||
<done>The chat family is live on demo.summercms.io: chat, forum, friends and the call signalling path answer, with WavePath's services untouched.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 5: Go-ahead for the Vuurmuur rule that opens LiveKit's media ports on rome</name>
|
||||
<read_first>DEPLOY.md "Firewall (Vuurmuur)"; the read-only output Claude prints: the proposed service file content (TCP 7891, UDP 7892), the proposed rule line, the current rules.conf lines around the Livekit service, and `iptables -S | grep -c vrmr` before the change</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user chose one option and it is recorded in the SUMMARY.
|
||||
</acceptance_criteria>
|
||||
<decision>Open TCP 7891 and UDP 7892 on rome for the demo's LiveKit through Vuurmuur?</decision>
|
||||
<context>rome's INPUT chain is managed by Vuurmuur with policy DROP; raw iptables rules would be overwritten. Without this rule calls signal but never connect media. The rule only admits traffic to the demo's LiveKit ports (the program binds media on the public address; signalling stays on loopback behind nginx). It is reversible: removing the rule and reloading Vuurmuur closes the ports. WavePath's own Livekit service definition stays unused and unchanged.</context>
|
||||
<options>
|
||||
<option id="claude-applies">
|
||||
<name>Claude applies the rule</name>
|
||||
<pros>Done now, with the verification commands from DEPLOY.md.</pros>
|
||||
<cons>A change to the shared host's firewall made by the agent.</cons>
|
||||
</option>
|
||||
<option id="user-applies">
|
||||
<name>I apply it myself</name>
|
||||
<pros>You make the firewall change on the shared host.</pros>
|
||||
<cons>Calls stay disconnected until you reply that it is done.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>The firewall stays as it is.</pros>
|
||||
<cons>Video calls do not connect on the live demo (D-10 open); plan 06's call check is skipped.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<instructions>For "user-applies": follow DEPLOY.md "Firewall (Vuurmuur)" and reply "firewall done".</instructions>
|
||||
<resume-signal>Reply "claude-applies", "firewall done" or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 6: Apply and verify the media ports, and hand the live demo to plan 06</name>
|
||||
<precondition>Task 5 answered "claude-applies" or "firewall done".</precondition>
|
||||
<files>../sm-demo-app/DEPLOY.md</files>
|
||||
<read_first>DEPLOY.md "Firewall (Vuurmuur)", the Task 5 answer</read_first>
|
||||
<action>Per D-10.
|
||||
- For "claude-applies": on rome, add the service file /etc/vuurmuur/services/summercms-demo-livekit (TCP 7891, UDP 7892) and the rule line from DEPLOY.md, apply with Vuurmuur's own tooling (`vuurmuur_script` apply and reload, never raw iptables), and back up rules.conf first to rules.conf.bak-<date>.
|
||||
- Either way, verify:
|
||||
- `sudo iptables -S | grep -E '7891|7892'` shows ACCEPT rules with the vrmr prefix;
|
||||
- `ss -lunp | grep 7892` shows livekit-server;
|
||||
- from this machine, `nc -zv -w 3 <rome public address> 7891` connects (UDP is verified by the live call in plan 06).
|
||||
- Note in DEPLOY.md the date applied and the backup path.
|
||||
- If robots.txt could not be updated unattended in Task 4, list the exact lines for the user in the SUMMARY.
|
||||
Commit any DEPLOY.md change (`docs: record the LiveKit firewall rule`), then push sm-demo-app.</action>
|
||||
<verify>
|
||||
<automated>ssh -p 2222 debian@10.8.3.118 "sudo iptables -S | grep -cE 'dport (7891|7892)'" | grep -qvx 0 && nc -zv -w 3 54.36.173.176 7891</automated>
|
||||
<fails_when>The iptables count is 0 (Vuurmuur did not apply the rule), or the TCP connect to 7891 on the public address times out or is refused.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `ssh -p 2222 debian@10.8.3.118 test -f /etc/vuurmuur/services/summercms-demo-livekit` exits 0.
|
||||
- `../sm-demo-app/scripts/check-live.sh https://demo.summercms.io` still prints `check-live: ok`.
|
||||
- The SUMMARY states whether robots.txt was updated and lists any item left for the user.
|
||||
</acceptance_criteria>
|
||||
<done>LiveKit's media ports are reachable from the internet through Vuurmuur and the live demo passes its checks.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| internet to nginx (Cloudflare) on demo.summercms.io | untrusted HTTP and WebSocket, now including /livekit/ and six API prefixes |
|
||||
| internet to rome's public address on 7891/tcp and 7892/udp | WebRTC media straight to LiveKit, bypassing Cloudflare |
|
||||
| build machine to rome over SSH | secrets generated on rome, never transferred |
|
||||
| demo services to WavePath services on the same host | must stay isolated |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-27 | Elevation of privilege | LiveKit co-tenancy with WavePath | high | mitigate | own instance, own key pair, own ports and config file (D-10); no key added to /etc/livekit/livekit.yaml; Task 4 asserts wavepath-livekit was not restarted |
|
||||
| T-20-28 | Information disclosure | LiveKit, VAPID and Centrifugo secrets | high | mitigate | generated on rome inside the remote shell, written to 0640 root:summercms-demo files, never echoed; repository files hold names and placeholders; check-deploy fails on non-placeholder keys in the example |
|
||||
| T-20-29 | Denial of service | open media ports | medium | mitigate | only TCP 7891 and UDP 7892 via a Vuurmuur rule the user approved; room max_participants 4, empty_timeout 120, departure_timeout 20, max_duration 900 with reconcile (D-12) |
|
||||
| T-20-30 | Information disclosure | origin IP through ICE candidates | low | accept | rome already exposes services on its public address; recorded in DEPLOY.md |
|
||||
| T-20-31 | Elevation of privilege | unintended Go routes | medium | mitigate | nginx allow-list gains exactly six prefixes and /livekit/; /_herald stays unrouted; check-deploy asserts both; /backend 404 unchanged |
|
||||
| T-20-32 | Tampering | firewall drift | medium | mitigate | changes only through Vuurmuur with a dated backup of rules.conf; DEPLOY.md documents removal |
|
||||
| T-20-33 | Denial of service | release breaking the live demo | medium | mitigate | release build and smoke before the go-ahead (Task 2); DEPLOY.md rollback keeps bin/demo.prev and site/.output.prev; check-live after release |
|
||||
| T-20-34 | Spoofing | signalling WebSocket | low | mitigate | LiveKit validates every join token (HS256, token_ttl 900) minted only for conversation participants by chatvideo |
|
||||
| T-20-SC | Tampering | npm/pip/cargo installs | high | mitigate | no new package: the release installs vue-demo-app's frozen lockfile (layers pinned by tag, livekit-client approved in plan 04) and Go modules by tag with go.sum |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: check-deploy ok with the new locations, program and port agreement.
|
||||
- Task 2: check-pins, release build and smoke; rome read-only table.
|
||||
- Task 3: go-ahead recorded.
|
||||
- Task 4: remotes pushed; check-live ok on https://demo.summercms.io; LiveKit running; WavePath untouched.
|
||||
- Task 5: firewall decision recorded.
|
||||
- Task 6: iptables shows the Vuurmuur rule; TCP 7891 reachable; check-live still ok.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
The chat family runs on the public demo with its own LiveKit and open media ports, /backend refused and the call to action shown (SC-3), with a runbook and checks that make the next release routine.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-05-SUMMARY.md` when done: the deploy table (no secret values), ports used, the commits pushed, what changed on rome, both checkpoint answers, the robots.txt state, and anything left for the user.
|
||||
</output>
|
||||
@@ -0,0 +1,162 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 05
|
||||
subsystem: sm-demo-app deploy, rome
|
||||
tags: [deploy, rome, livekit, vuurmuur, nginx, centrifugo, herald, vapid, robots, check-live]
|
||||
|
||||
requires:
|
||||
- phase: 20-02
|
||||
provides: "chat family mounted in sm-demo-app, deploy/livekit.yaml.example, Centrifugo namespaces in the example, production livekit_url"
|
||||
- phase: 20-03
|
||||
provides: "vue-chat-layer v0.1.0 pinned in vue-demo-app"
|
||||
- phase: 20-04
|
||||
provides: "forum, friends and video-call layers v0.1.0 pinned in vue-demo-app, herald VAPID handling in dev.sh"
|
||||
provides:
|
||||
- "demo.summercms.io serves /chat, /forum, /friends and /call/{id} with the banner and register prompts; the chat-family APIs answer 401 without a JWT"
|
||||
- "The demo's own LiveKit 1.13.1 on rome (supervisor program summercms-demo-livekit, 127.0.0.1:7890 behind nginx /livekit/, media 7891/tcp and 7892/udp open through Vuurmuur)"
|
||||
- "Centrifugo namespaces chat, user, video on rome; herald VAPID keys in rome's .env; robots.txt disallows the new prefixes"
|
||||
- "scripts/check-deploy.sh LiveKit and chat-family checks; scripts/check-live.sh chat-family checks; DEPLOY.md runbooks for LiveKit, the firewall and the chat family"
|
||||
affects: [20-06]
|
||||
|
||||
actuals:
|
||||
tokens: 14800 # chars/4 over sm-demo-app fc23b4c..f2e35c1 without the ROADMAP snapshot and the gitlink (59224 chars)
|
||||
tasks: 6
|
||||
commits: 0 # MEASURED in summercms.go: git rev-list --count 6389479..HEAD before this SUMMARY commit (docs-only plan here); sm-demo-app: 6 (git rev-list --count fc23b4c..f2e35c1)
|
||||
plan_head_before: 63894799065795c54d91e40094692cf4f0cbe419 # summercms.go
|
||||
plan_head_after: 63894799065795c54d91e40094692cf4f0cbe419 # summercms.go before this SUMMARY commit; sm-demo-app fc23b4c -> f2e35c1, vue-demo-app 44a5229 -> 9357711 (pushed)
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Secrets generated on rome go into files through bash builtins and stdin only (printf, tee), never as a process argument"
|
||||
- "Shared-host supervisor changes name the program (supervisorctl update <name>), so no other program restarts"
|
||||
- "Admin-only settings changed unattended through rome's loopback admin API, the password read on rome into a 0700 temp dir"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf
|
||||
modified:
|
||||
- ../sm-demo-app/deploy/nginx/demo.summercms.io.conf
|
||||
- ../sm-demo-app/deploy/livekit.yaml.example
|
||||
- ../sm-demo-app/config/env/production/golem15.chatvideo.yaml
|
||||
- ../sm-demo-app/scripts/check-deploy.sh
|
||||
- ../sm-demo-app/scripts/check-live.sh
|
||||
- ../sm-demo-app/DEPLOY.md
|
||||
- ../sm-demo-app/README.md
|
||||
- ../sm-demo-app/plugins/demo/content/ROADMAP.md
|
||||
- ../sm-demo-app/vue-demo-app
|
||||
|
||||
key-decisions:
|
||||
- "Task 3 checkpoint: deploy (push both repositories and release the chat family on rome)"
|
||||
- "Task 5 checkpoint: firewall done; the user applied the Vuurmuur rule as service sm-demo-livekit (7891/tcp, 7892/udp), rule on line 1 of rules.conf"
|
||||
- "Media path: ICE over the UDP mux 7892 with ICE-TCP 7891, no embedded TURN; TURN on 3478/5349 with a DNS-only host is the recorded fallback"
|
||||
- "Admin stays at /smbackend with login; /backend answers 404"
|
||||
- "robots.txt updated through PUT /_seo/api/v1/robots on rome's loopback (admin bearer token), not by hand"
|
||||
- "VAPID subject mailto:DEMO_ADMIN_EMAIL from the build machine's secrets file"
|
||||
|
||||
requirements-completed: [SC-2, SC-3, D-10, D-12, D-16, D-20, D-21]
|
||||
|
||||
duration: about 5 h of work over two sessions (2026-10-31 evening to 2026-11-01 18:40), with three checkpoints and the user's own firewall change
|
||||
completed: 2026-11-01
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 20 Plan 05: chat family deployed on demo.summercms.io with its own LiveKit Summary
|
||||
|
||||
**The chat family runs on the public demo: https://demo.summercms.io serves /chat, /forum, /friends and /call/{id} with the banner and register prompts, every chat-family API answers 401 without a JWT, /livekit/rtc/validate reaches the demo's own LiveKit 1.13.1 (supervisor program summercms-demo-livekit, separate from WavePath's), Centrifugo has the chat, user and video namespaces, herald has VAPID keys without a route, and Vuurmuur admits LiveKit's media on 7891/tcp and 7892/udp. `check-live.sh https://demo.summercms.io` prints `check-live: ok`.**
|
||||
|
||||
## Task Commits
|
||||
|
||||
| # | Repo | Commit | Message |
|
||||
|---|------|--------|---------|
|
||||
| 1 | sm-demo-app | b5c639e | feat: deploy files for the chat family and the demo's LiveKit |
|
||||
| 2 | sm-demo-app | cf08fb5 | fix: check-live tells an unrouted /_herald by its 404, not its type |
|
||||
| 3 | — | — | checkpoint: deploy |
|
||||
| 4 | vue-demo-app | (push) | 44a5229..9357711 pushed to origin master |
|
||||
| 4 | sm-demo-app | c399bfd | chore: bump vue-demo-app (chat, forum, friends, calls) |
|
||||
| 4 | sm-demo-app | 6d726b4 | chore: sync the roadmap snapshot |
|
||||
| 4 | sm-demo-app | fcd8d95 | docs: record the chat-family release on rome |
|
||||
| 5 | — | — | checkpoint: firewall done (applied by the user) |
|
||||
| 6 | sm-demo-app | f2e35c1 | docs: record the LiveKit firewall rule |
|
||||
|
||||
**Pushed:** vue-demo-app master = 9357711 (`ls-remote` equals local HEAD, and sm-demo-app's gitlink points to it); sm-demo-app master = f2e35c1 (`ls-remote` equals local HEAD). Push order: vue-demo-app first, then the pointer bump.
|
||||
|
||||
## Deploy table (Task 2, rome read-only, 2026-10-31/11-01; no secret values)
|
||||
|
||||
| Item | State before the release |
|
||||
|------|--------------------------|
|
||||
| Listeners on 7890, 7891, 7892 | none (free); the trio was kept |
|
||||
| WavePath LiveKit | `wavepath-livekit` RUNNING pid 1104; 127.0.0.1:7880, *:7881, UDP 50000-60000 |
|
||||
| LiveKit binary | `/usr/local/bin/livekit-server` 1.13.1 |
|
||||
| Demo programs | summercms-demo, summercms-demo-site, summercms-demo-centrifugo RUNNING; no summercms-demo-livekit, conf or livekit.yaml |
|
||||
| `.env` key counts | CHATVIDEO__LIVEKIT_API_KEY 0, __LIVEKIT_API_SECRET 0, HERALD__VAPID__PUBLIC_KEY 0, __PRIVATE_KEY 0, __SUBJECT 0 |
|
||||
| centrifugo.json | namespaces `["presentations"]` only (chat 0, user 0, video 0); Centrifugo v6.5.1 |
|
||||
| Vuurmuur | 0.8.1, INPUT policy DROP, 62 vrmr lines, 15 rules, service Livekit unused, 0 rules for 789x |
|
||||
| Unpushed | sm-demo-app 19 commits (plans 02-04) + this plan's; vue-demo-app 9 commits |
|
||||
|
||||
## Ports used
|
||||
|
||||
7890/tcp on 127.0.0.1 (signal and RoomService, behind nginx `location ^~ /livekit/` and `livekit_admin_url`), 7891/tcp on all addresses (ICE-TCP), 7892/udp on every interface including 54.36.173.176 (ICE UDP mux). No collision with Go 8098, Nuxt 3098, Centrifugo 8010 or WavePath's 7880/7881/50000-60000 (check-deploy asserts it).
|
||||
|
||||
## What changed on rome (2026-11-01)
|
||||
|
||||
- **LiveKit:** `/srv/summercms-demo/livekit.yaml` (0640 root:summercms-demo, own key pair generated on rome), the same pair in `.env` (secret line count 1), `/etc/supervisor/conf.d/summercms-demo-livekit.conf`, program started alone with `supervisorctl update summercms-demo-livekit`. `curl 127.0.0.1:7890/` answers OK, `/rtc/validate` 401.
|
||||
- **Centrifugo:** namespaces `["presentations","chat","user","video"]`, `checkconfig` passed, summercms-demo-centrifugo restarted. Backup `/srv/summercms-demo/centrifugo.json.bak-2026-11-01`.
|
||||
- **VAPID:** public key, private key and subject `mailto:` + DEMO_ADMIN_EMAIL appended to `.env` (count 3, values non-empty: 87 and 43 characters), generated with `bin/demo.new herald:vapid-generate --json -q`.
|
||||
- **Release** `c49fabf46c88` (sm-demo-app 6d726b4): 9 migrations (the chat family's tables), demo:seed created channels and history EN/PL, the visitor's welcome DM, forum categories and threads, friends and group, the moderator group demo-moderators and the moderation lists; binary and site swapped (`bin/demo.prev` 21e6abc585e6, `site/.output.prev`), summercms-demo and summercms-demo-site restarted, `websockets:health` reports the API key set.
|
||||
- **nginx:** the new vhost installed, `nginx -t` passed, reloaded. Previous vhost `/root/demo.summercms.io.nginx.bak-2026-11-01`.
|
||||
- **robots.txt:** `Disallow:` /_chat, /_chatchannels, /_chatbots, /_chatvideo, /_forum, /_userfriends and /livekit appended through `PUT /_seo/api/v1/robots` on loopback (bot switches untouched); the live file shows them with the Sitemap line. Previous rules `/root/summercms-demo-seo-robots.bak-2026-11-01.json`.
|
||||
- **Firewall (by the user):** service `/etc/vuurmuur/services/sm-demo-livekit` (`RANGE="6;7891*1024:65535"`, `RANGE="17;7892*1024:65535"`, no COMMENT), rule `Accept service sm-demo-livekit from any to firewall(any) options log,loglimit="30"` on line 1 of rules.conf. `iptables -S` shows NFLOG `vrmr: ACCEPT` and NEWACCEPT for `--dport 7891` and `--dport 7892` (66 vrmr lines, 62 before); `nc -zv 54.36.173.176 7891` connects. It differs from the proposal in the service name (`sm-demo-livekit`, not `summercms-demo-livekit`), the missing COMMENT and the position (first, not appended); no `rules.conf.bak-*` is in `/etc/vuurmuur/rules/` (the pre-change file was the 15-line one probed on 2026-10-31). DEPLOY.md records it and its removal commands use the applied names.
|
||||
- **WavePath untouched:** `wavepath-livekit` kept pid 1104 throughout (uptime 1 day 23:53 before, 2 days 0:09 after); no other non-demo program was restarted. Nothing was added to `/etc/livekit/livekit.yaml`.
|
||||
|
||||
Supervisor status after the release: summercms-demo, summercms-demo-site, summercms-demo-centrifugo and summercms-demo-livekit RUNNING.
|
||||
|
||||
## Checkpoint answers
|
||||
|
||||
- **Task 3:** deploy.
|
||||
- **Task 5:** firewall done; the user applied the Vuurmuur rule, Claude made no firewall change and verified it read-only.
|
||||
|
||||
## Verification
|
||||
|
||||
- check-deploy: `check-deploy: ok`; negative copies (a /_herald location, LiveKit on another port, a UDP port range, bind 0.0.0.0, a real key, a cap mismatch, a wrong admin URL) each fail with their own line.
|
||||
- Local LiveKit 1.13.1 with the example: signal on 127.0.0.1:7890 only, ICE-TCP on *:7891, UDP 7892 per interface, /rtc/validate 401.
|
||||
- check-pins ok (25 modules); `build.sh release` → `build: ok release c49fabf46c88`; smoke ok; `go vet` and `go test -short ./...` green.
|
||||
- check-live against the live demo after the release and again after the firewall rule: `check-live: ok` (banner, CTA, /backend 404, /smbackend, /chat /forum /friends /call/1 prompts, six chat-family 401s, /livekit/rtc/validate from LiveKit, /_herald 404, robots lines, /ws 101, Back in a browser).
|
||||
- Acceptance greps: 6 chat-family locations, the program once, Vuurmuur 14+ times in DEPLOY.md. The plan's `grep -c 'location ^~ /livekit/'` prints 0 on this machine because `grep` is ugrep, which treats a mid-pattern `^` as an anchor (it also prints 0 for the existing `/_demo/` location); `grep -cF` prints 1.
|
||||
- Robots state: updated, see above. Nothing left for the user from robots.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
**1. [Rule 1 - Bug] check-live's /_herald check** (Task 2, cf08fb5). The first version failed on any JSON answer, but Nuxt answers its 404 as JSON to curl's `Accept: */*`. It now wants status 404 (Go would answer 401 without a JWT).
|
||||
|
||||
**2. [Rule 3 - Blocking] Release build prerequisites** (Tasks 2 and 4). `build.sh release` refused in Task 2: the uncommitted vue-demo-app gitlink (the plan's Task 4 bump), the user's untracked backup file (left untouched; the user removed it) and a stale ROADMAP snapshot (phase 20 progress lines). The snapshot was synced in Task 4 just before the build (6d726b4) so it matched the framework's master at release time.
|
||||
|
||||
**3. [Rule 2 - Missing critical] Runbook safety on a shared host** (Task 1). The LiveKit secret goes into the files through bash builtins and stdin only (the Centrifugo runbook's `sed` put secrets in argv); the substitution is anchored on the newline and indent so a comment holding the placeholder cannot take it; `supervisorctl update` names the program; the new Centrifugo file is created 0640 before `tee` writes it; the vhost is backed up before it is replaced (added to "Release").
|
||||
|
||||
**4. robots.txt through the loopback SEO API** (Task 4). DEPLOY.md's SEO section described a hand edit; the plan allowed an unattended path. The procedure is recorded in DEPLOY.md "Chat family".
|
||||
|
||||
**5. check-live also covers /call/1 and /_chat** (Task 1), because SC-2 and SC-3 name them; the plan's list had /chat, /forum, /friends and five API prefixes.
|
||||
|
||||
**Total deviations:** 5. **Impact:** none on the goal.
|
||||
|
||||
## Boot-log warnings (rome and local alike)
|
||||
|
||||
`golem15.chatchannels: ChannelAccessResolver is deny-all`, `golem15.forum: ForumAccessResolver is deny-all`, `golem15.chatbots: BotAuthResolver is deny-all` and `golem15.herald: PresenceGate is deny-all` appear at every boot, locally too (12 times each in the local go.log). They are logged before golem15.demo installs its resolvers in `lagoon.OnDatabase` (`plugins/demo/chat.go:68,86`); chatbots has no bot users and herald no UI (D-16). Plan 06's signed-in live checks confirm the wiring on rome.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## Left for the user
|
||||
|
||||
Nothing required. Optional: keep a dated copy of the pre-change rules.conf if you want one next to the file (DEPLOY.md lists the 15 earlier rules). NAT'd-browser media is proven only by plan 06's live call; the TURN fallback needs its own decision.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Plan 06 can run its live checks: the stale local demo servers from plan 04 are stopped, the live demo passes check-live, the media ports are reachable, and a signed-in member (Turnstile is closed in production, so a test account comes from the operator or the visitor account in rome's .env) can exercise chat, forum, friends and a two-browser DM call.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- sm-demo-app commits exist and are on origin: b5c639e, cf08fb5, c399bfd, 6d726b4, fcd8d95, f2e35c1 (remote master f2e35c1). vue-demo-app origin master 9357711.
|
||||
- Files exist: deploy/supervisor/summercms-demo-livekit.conf, the modified files above.
|
||||
- rome: summercms-demo-livekit RUNNING, `.env` LiveKit secret count 1, VAPID count 3, wavepath-livekit pid 1104 unchanged, check-live ok.
|
||||
@@ -0,0 +1,447 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 06
|
||||
type: execute
|
||||
wave: 6
|
||||
depends_on: ["20-01", "20-02", "20-03", "20-04", "20-05"]
|
||||
files_modified:
|
||||
- ../sm-moderation-plugin/classes/filter_test.go
|
||||
- ../sm-moderation-plugin/models/settings_test.go
|
||||
- ../sm-moderation-plugin/plugin_test.go
|
||||
- ../sm-chat-plugin/saving_test.go
|
||||
- ../sm-forum-plugin/saving_test.go
|
||||
- ../sm-demo-app/moderation_test.go
|
||||
- ../sm-demo-app/chat_test.go
|
||||
- ../sm-demo-app/video_test.go
|
||||
- ../sm-demo-app/seed_chat_test.go
|
||||
- ../sm-demo-app/reset_test.go
|
||||
- ../sm-demo-app/realtime_test.go
|
||||
- ../sm-demo-app/boot_test.go
|
||||
- ../sm-demo-app/plugins/demo/classes/chat_context_test.go
|
||||
- ../sm-demo-app/plugins/demo/chatbots_test.go
|
||||
- ../sm-demo-app/scripts/check-chat.cjs
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/check-all.sh
|
||||
- ../sm-demo-app/README.md
|
||||
- ../vue-chat-layer/vitest.config.ts
|
||||
- ../vue-chat-layer/app/lib/chatEvents.test.ts
|
||||
- ../vue-chat-layer/app/lib/chatFormat.test.ts
|
||||
- ../vue-chat-layer/app/lib/chatText.test.ts
|
||||
- ../vue-chat-layer/app/lib/chatUnread.test.ts
|
||||
- ../vue-chat-layer/app/lib/realtime.test.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.test.ts
|
||||
- ../vue-chat-layer/tests/client.test.ts
|
||||
- ../vue-chat-layer/tests/store.test.ts
|
||||
- ../vue-chatvideo-layer/tests/callMachine.test.ts
|
||||
- ../vue-chatvideo-layer/tests/videoClient.test.ts
|
||||
- ../vue-chatvideo-layer/tests/useCall.test.ts
|
||||
- ../vue-forum-layer/tests/client.test.ts
|
||||
- ../vue-userfriends-layer/tests/client.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/lib/realtime.test.ts
|
||||
autonomous: false
|
||||
requirements: [SC-1, SC-2, SC-3, SC-4, D-01, D-02, D-04, D-05, D-06, D-07, D-08, D-09, D-11, D-12, D-13, D-14, D-15, D-17, D-18, D-20, D-21, D-22, D-23]
|
||||
estimate:
|
||||
tokens: 360000
|
||||
raw_tokens: 360000
|
||||
tasks: 8
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-4: every behaviour row of 20-VALIDATION.md has a passing automated test under the name it lists, in the repository it lists; the new code of plans 01 to 05 is covered by unit tests in this last plan (project rule)."
|
||||
- "D-18: TestMessageSaving* (sm-chat-plugin) and TestPostSaving* (sm-forum-plugin) pin: no listener gives byte-identical responses and stored rows; a rejecting listener on create, reply, ReplyTo and edit (chat) and thread, reply and edit (forum) gives 422 under the Rejection's field, writes and changes nothing, fires no post-save event and publishes nothing; a non-Rejection listener error keeps the 500 path; the existing php_method_map and golden tests pass unedited."
|
||||
- "D-17: TestMatch*, TestParseList and TestFilterCheck* (sm-moderation-plugin) pin case-insensitive word and phrase matching with Unicode letter boundaries (Polish letters, digits, underscores), host, subdomain, www and scheme-less link matching, URL-prefix entries, the disabled switch, the recompile-on-change cache, the list limits in BeforeValidate and the locale fallback of the message; TestDemoModeration pins the demo wiring end to end through HTTP."
|
||||
- "D-06, D-07, D-08, D-22: TestDemoChatContext*, TestDemoChannelAdapter, TestDemoChannelsSeededOnly, TestDemoChatBootstrap, TestDemoChatMembers, TestDemoDMs and TestDemoModeratorDelete pin membership (banned and deleted users excluded with live membership), the channel alias, refused channel creation, the bootstrap and members JSON shapes, DMs between any members, and moderator deletion limited to channel conversations."
|
||||
- "D-11, D-12, D-23: TestDemoVideoStart pins that a DM call starts with a token and livekit_url against a fake RoomService and that the server does not refuse by conversation type (calls are limited to DMs by the UI); the vue-chat-layer tests pin that the conversation-actions slot renders only for DMs."
|
||||
- "D-05: TestDemoCommands pins the catalog entries demo and tour and their ephemeral dispatch; the layer tests pin the command picker's dispatch path."
|
||||
- "D-09: TestSeedChat pins EN and PL channels, threads, reactions, pins, forum categories and posts, friendships and the group, and idempotency; TestResetKeepsPlans pins that every chat-family table is emptied and reseeded and that moderation settings survive."
|
||||
- "D-01, D-02, D-04: bm's chatEvents, chatFormat, chatText, chatUnread and realtime tests run under vitest in vue-chat-layer with only import paths changed, next to new tests for the multi-channel store, threads, pins, link embeds, the client's refresh-and-retry and the anonymous no-bootstrap path."
|
||||
- "D-13, D-14, D-15, D-21: the chatvideo machine and useCall (mocked livekit-client Room) tests, and the forum and friends client tests pass under their layers' test scripts."
|
||||
- "SC-2: locally, scripts/check-local.sh chatlive callmedia passes: two browsers see each other's channel message live, and a DM call shows each side a playing remote video with fake media through the local LiveKit."
|
||||
- "SC-2, SC-3: scripts/check-all.sh (including check-live against https://demo.summercms.io) prints check-all: ok, and the user confirms a two-browser chat and a DM call on the live demo."
|
||||
artifacts:
|
||||
- path: "../sm-moderation-plugin/classes/filter_test.go"
|
||||
provides: "TestMatch*, TestParseList, TestFilterCheck*"
|
||||
contains: "TestMatch"
|
||||
- path: "../sm-chat-plugin/saving_test.go"
|
||||
provides: "TestMessageSaving*"
|
||||
contains: "TestMessageSaving"
|
||||
- path: "../sm-forum-plugin/saving_test.go"
|
||||
provides: "TestPostSaving*"
|
||||
contains: "TestPostSaving"
|
||||
- path: "../sm-demo-app/chat_test.go"
|
||||
provides: "TestDemoChat*, TestDemoChannelsSeededOnly, TestDemoDMs, TestDemoModeratorDelete, TestDemoCommands"
|
||||
contains: "TestDemoChannelsSeededOnly"
|
||||
- path: "../sm-demo-app/video_test.go"
|
||||
provides: "TestDemoVideoStart with a fake RoomService"
|
||||
contains: "TestDemoVideoStart"
|
||||
- path: "../sm-demo-app/scripts/check-chat.cjs"
|
||||
provides: "two-browser realtime and DM call checks"
|
||||
contains: "use-fake-device-for-media-stream"
|
||||
- path: "../vue-chat-layer/tests/store.test.ts"
|
||||
provides: "multi-channel store, threads, pins, commands"
|
||||
contains: "describe"
|
||||
key_links:
|
||||
- from: "../sm-demo-app/scripts/check-all.sh"
|
||||
to: "../sm-demo-app/scripts/check-live.sh"
|
||||
via: "the gate runs every suite, the layers and the chat-family plugins, then check-live"
|
||||
pattern: "check-live\\.sh"
|
||||
- from: "../sm-demo-app/scripts/check-local.sh"
|
||||
to: "../sm-demo-app/scripts/check-chat.cjs"
|
||||
via: "check_chatlive and check_callmedia run the Playwright script with two contexts"
|
||||
pattern: "check-chat\\.cjs"
|
||||
- from: "../sm-demo-app/moderation_test.go"
|
||||
to: "../sm-demo-app/plugins/demo/moderation.go"
|
||||
via: "HTTP send with a banned word answers 422 through the demo listener and the moderation Filter"
|
||||
pattern: "422"
|
||||
prohibitions:
|
||||
- statement: "Tests use no real secret, no production database and no network service except the Docker Postgres, the local dev stack and in-process fakes."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "No production behaviour changes in this plan except fixes for bugs the tests expose, within Task 7's fix budget (small, no feature, schema or contract change, at most one patch tag per repository and one redeploy), each in its own commit, named in the SUMMARY, and released through the Task 6 checkpoint; the app-wiring extraction in vue-demo-app is behaviour-preserving."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "Test-only commits in plugin and layer repositories get no tag; nothing is pushed before the Task 6 go-ahead."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): SC-4 says the new code has unit tests, delivered in the phase's last plan. The live demo shows the chat family working.
|
||||
|
||||
This plan's slice (plan 6 of 6, wave 6, per D-20 and the project rule that unit tests are the last plan): unit tests for everything plans 01 to 05 built, in Go, the four layers and the site, then a local two-browser chat and call check and the live verification, ending with the user's look at the live demo.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Where tests live:**
|
||||
- plugin seam tests next to the plan 01 smoke tests;
|
||||
- the demo's database tests in the root package (they compile every plugin through PluginIDs and the shared Postgres harness, as 19.4.1 did), with pure demo classes tested in plugins/demo/classes;
|
||||
- bm's chat tests next to the ported sources in vue-chat-layer/app/lib (copied with only import paths changed, the 19.4.1 vue-demo-app pattern), new layer tests in tests/.
|
||||
- **Fake LiveKit:** TestDemoVideoStart points `golem15.chatvideo.livekit_admin_url` at an httptest server answering the Twirp RoomService calls Start makes (CreateRoom, and ListParticipants if used), so chatvideo's real code path runs without a LiveKit.
|
||||
- **useCall test:** livekit-client is replaced with vi.mock of a minimal Room (connect, disconnect, localParticipant setters, event emitter). The real SDK is exercised by check-chat.cjs against the local LiveKit with fake media.
|
||||
- **Site tests:** the hook factories in vue-demo-app's app/plugins/auth.ts (token, refresh and unauthorized for chat; token getters; the friends directory mapping) move unchanged into app/utils/communityAuth.ts, so vitest can test them without Nuxt.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
## Artifacts this phase produces (this plan)
|
||||
|
||||
- Go tests:
|
||||
- sm-moderation-plugin `TestMatchWords`, `TestMatchLinks`, `TestParseList`, `TestFilterCheckCache`, `TestFilterCheckDisabled`, `TestSettingsLimits`, `TestBootPublishesFilter`;
|
||||
- sm-chat-plugin `TestMessageSavingNoListener`, `TestMessageSavingRejects`, `TestMessageSavingOtherError`;
|
||||
- sm-forum-plugin `TestPostSavingNoListener`, `TestPostSavingRejects`;
|
||||
- sm-demo-app `TestDemoModeration`, `TestDemoChatContext*`, `TestDemoChannelAdapter`, `TestDemoChannelsSeededOnly`, `TestDemoChatBootstrap`, `TestDemoChatMembers`, `TestDemoDMs`, `TestDemoModeratorDelete`, `TestDemoCommands`, `TestDemoVideoStart`, `TestSeedChat`, extended `TestResetKeepsPlans`, `TestRealtimeRoutes`, `TestRealtimeMemberToken`, `TestBootAllPlugins`.
|
||||
- Layer tests: vue-chat-layer (ported bm tests plus `store.test.ts`, `client.test.ts`, `linkEmbeds.test.ts`), vue-chatvideo-layer (`callMachine`, `videoClient`, `useCall`), vue-forum-layer and vue-userfriends-layer client tests.
|
||||
- Site: `app/utils/communityAuth.ts` with its test.
|
||||
- Scripts: check-chat.cjs modes `--two` (realtime) and `--call` (fake media); check-local checks `chatlive` and `callmedia`; check-all.sh steps for the chat-family plugins and the four layers.
|
||||
|
||||
<objective>
|
||||
Cover the phase's new code with unit tests, prove two-browser chat and DM calls locally, and verify the live demo with the user.
|
||||
|
||||
Purpose: SC-4 (unit tests in the last plan) and the live proof of SC-2 and SC-3 for every decision the phase implemented.
|
||||
Output: test commits in eight Go and five frontend repositories, script commits in sm-demo-app, pushes after the go-ahead, and the user's sign-off on the live demo.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-VALIDATION.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-RESEARCH.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-01-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-02-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-03-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-04-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-05-SUMMARY.md
|
||||
|
||||
Repos: ../sm-moderation-plugin, ../sm-chat-plugin, ../sm-forum-plugin, ../sm-demo-app (root tests, plugins/demo, scripts), ../sm-demo-app/vue-demo-app, ../vue-chat-layer, ../vue-chatvideo-layer, ../vue-forum-layer, ../vue-userfriends-layer. bm test sources (read-only): ../sm-bm-app/frontend/src/lib/{chatEvents,chatFormat,chatText,chatUnread,realtime}.test.ts and stores/chat.test.ts.
|
||||
|
||||
Rules: no co-author tags; stage by explicit path; Docker tests skip under -short and the TestMain calls flag.Parse and testing.Short (CLAUDE.md); if the Docker socket is denied, run through `sudo -u golem`; production code changes only for bugs the tests expose and only within the fix budget in Task 7 (own commit each, named in the SUMMARY; anything larger becomes a todo and decimal-phase candidate); nothing is pushed before Task 6.
|
||||
|
||||
<interfaces>
|
||||
sm-demo-app test harness: testmain_test.go `bootDemo(t, environ, set) *demotest.Demo`; internal/demotest (App, DB, Options{PluginIDs, Environ, Set}); existing tests TestGoModRequiresTags, TestBootAllPlugins (wantPlugins), TestRealtimeRoutes (realtimeApp, realtimeRoutes, wantNamespaces), TestResetKeepsPlans, TestSeedRoadmapUpsert; smoke tests from plan 02: TestDemoChatTracer, TestDemoModerationSmoke, TestSeedChatSmoke (chat_smoke_test.go).
|
||||
Plugin harnesses: chat bootWeb, frontendToken, call, conversation, count, memory (lighthouse MemoryDriver publications); forum bootWeb, call, count; plan 01 smoke tests TestMessageSavingTracer, TestPostSavingTracer, TestFilterSmoke.
|
||||
Demo classes (plan 02): DemoContext, ChannelContext, ChatAccess, ForumAccess with WithMembership and MemberFunc injection; chat_api.go bootstrap and members; chatbots.go demo and tour; moderation.go listeners; realtime_access.go guard.
|
||||
Layers (plans 03 and 04): vue-chat-layer createChatClient, useChat, linkify, registerEmbedRenderer, onUserEvent, slots; vue-chatvideo-layer callMachine (initialCallState, transition), createVideoClient, videoSessionChannel, useCall; createForumClient; createFriendsClient.
|
||||
Scripts: check-local.sh (visitor_jwt, throwaway registration helper, ALL_CHECKS, NODE_PATH="$(npm root -g)" for Playwright scripts), check-chat.cjs (plan 03 single-browser), check-all.sh (steps, "check-all: ok").
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: one banned word travels from the admin settings through the filter, the demo listener and the chat seam to a 422 in a member's request, under test</name>
|
||||
<precondition>`docker info` exits 0; the plan 05 SUMMARY exists.</precondition>
|
||||
<files>../sm-moderation-plugin/classes/filter_test.go, ../sm-demo-app/moderation_test.go</files>
|
||||
<read_first>../sm-moderation-plugin/classes/filter.go and filter_smoke_test.go, ../sm-demo-app/plugins/demo/moderation.go, ../sm-demo-app/chat_smoke_test.go (TestDemoModerationSmoke), ../sm-demo-app/testmain_test.go, 20-VALIDATION.md (D-17 rows)</read_first>
|
||||
<action>Per D-17, D-18, SC-4.
|
||||
- sm-moderation-plugin classes/filter_test.go, table tests for the pure functions:
|
||||
- TestMatchWords: case-insensitive; a word inside a longer word does not match; phrases; Polish letters on both sides of a boundary (for example "żółw" against "żółwik" and "żółw!"); digits and underscores count as word characters; QuoteMeta'd specials such as "c++".
|
||||
- TestMatchLinks: a host entry matches the bare domain, www., http and https URLs, subdomains, upper case and trailing paths; "notbad.example" does not match "bad.example"; a URL-prefix entry matches only below its path.
|
||||
- TestParseList: trims, lowercases, drops empty lines and duplicates.
|
||||
- sm-demo-app moderation_test.go `TestDemoModeration` (Docker), end to end through HTTP:
|
||||
- after demo:seed, update golem15_moderation_settings with banned_words "blockedword" and banned_links "bad.example";
|
||||
- a member's message, reply and edit containing either answer 422 with errors.content, and the message count does not change;
|
||||
- a forum thread title answers 422 errors.title and a reply body 422 errors.body;
|
||||
- after changing the list to another word without restarting, the old word is accepted (cache refresh);
|
||||
- with enabled false, everything is accepted.
|
||||
|
||||
Commit per repository (`test: ...`).</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-moderation-plugin test -count=1 ./... && go -C ../sm-demo-app test -count=1 -run '^TestDemoModeration$' -v . 2>&1 | grep -q -- '^--- PASS: TestDemoModeration'</automated>
|
||||
<fails_when>Non-zero exit from the moderation suite (a boundary, host or cache case wrong), or no "--- PASS: TestDemoModeration" line (skipped without Docker, banned content stored, or a list change not picked up).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '^func TestMatch' ../sm-moderation-plugin/classes/filter_test.go` prints at least 2.
|
||||
- `grep -c 'żółw' ../sm-moderation-plugin/classes/filter_test.go` prints at least 1.
|
||||
</acceptance_criteria>
|
||||
<done>The D-17/D-18 chain is pinned from the settings row to the HTTP answer.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Seam and moderation plugin unit tests: parity without a listener, refusals on every write path</name>
|
||||
<files>../sm-chat-plugin/saving_test.go, ../sm-forum-plugin/saving_test.go, ../sm-moderation-plugin/models/settings_test.go, ../sm-moderation-plugin/plugin_test.go</files>
|
||||
<read_first>../sm-chat-plugin/saving_smoke_test.go, http_tracer_test.go, harness_test.go (memory driver), classes/attachments.go (ReplyTo), ../sm-forum-plugin/saving_smoke_test.go, http_tracer_test.go, ../sm-moderation-plugin/models/settings.go, plugin.go, updates/*.go, ../sm-sitemap-plugin/models/definition_test.go (settings test style)</read_first>
|
||||
<action>Per D-18, D-17.
|
||||
- sm-chat-plugin saving_test.go:
|
||||
- TestMessageSavingNoListener: the same send, reply, edit and ReplyTo requests answer the same status and body keys as before the seam, and MessageCreated and MessageUpdated still fire;
|
||||
- TestMessageSavingRejects: table over send, reply (POST replies), ReplyTo (service) and edit. Each gives 422 under the Rejection field (and "content" when the field is empty), no row inserted or changed, no MessageCreated or MessageUpdated fired (a counting listener), and no publication on the memory driver;
|
||||
- TestMessageSavingOtherError: a plain error from a listener gives 500 with the generic body and nothing stored;
|
||||
- the event carries Op, ConversationID, ActorID, RootID, MessageID and the trimmed Content.
|
||||
- sm-forum-plugin saving_test.go: TestPostSavingNoListener and TestPostSavingRejects over thread, reply and edit (field title or body, nothing stored, content_html unchanged on a refused edit, Op values).
|
||||
- sm-moderation-plugin:
|
||||
- models/settings_test.go TestSettingsLimits: too many entries, too long entries and a bad link entry refused with their lang keys; valid lists saved;
|
||||
- plugin_test.go TestBootPublishesFilter (Docker, with the sitemap-style harness): migrations create the singleton row, Boot publishes *classes.Filter, and Check on a clean text gives nil.
|
||||
Keep php_method_map_test.go and golden_test.go untouched in both content plugins. Commit per repository.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-chat-plugin test -count=1 ./... && go -C ../sm-forum-plugin test -count=1 ./... && go -C ../sm-moderation-plugin test -count=1 ./... && go -C ../sm-chat-plugin test -count=1 -run '^TestMessageSaving' -v . 2>&1 | grep -c -- '^--- PASS: TestMessageSaving' | grep -qvx '[0-2]'</automated>
|
||||
<fails_when>Non-zero exit from any of the three suites (parity broken, a write path that bypasses the seam, an event fired after a refusal), or fewer than three passing TestMessageSaving* lines (tests skipped without Docker).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../sm-chat-plugin diff HEAD~1 --stat -- php_method_map_test.go golden_test.go` and the same in ../sm-forum-plugin print nothing.
|
||||
- `grep -c 'ReplyTo' ../sm-chat-plugin/saving_test.go` prints at least 1.
|
||||
</acceptance_criteria>
|
||||
<done>The seams' contract (silent without listeners, total refusal with one) and the moderation plugin's settings and boot are pinned.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Demo host unit tests: context, adapter, bootstrap, DMs, moderator delete, commands, video start, realtime, seed and reset</name>
|
||||
<files>../sm-demo-app/plugins/demo/classes/chat_context_test.go, ../sm-demo-app/plugins/demo/chatbots_test.go, ../sm-demo-app/chat_test.go, ../sm-demo-app/video_test.go, ../sm-demo-app/seed_chat_test.go, ../sm-demo-app/reset_test.go, ../sm-demo-app/realtime_test.go, ../sm-demo-app/boot_test.go</files>
|
||||
<read_first>../sm-demo-app/plugins/demo/{chat.go,chat_api.go,chatbots.go,moderation.go,realtime_access.go,routes.go,classes/chat_context.go,classes/forum_access.go,console/seed_chat.go,console/seed_forum.go,console/seed_friends.go,console/reset.go}, ../sm-demo-app/{chat_smoke_test.go,demo_api_test.go,realtime_test.go,reset_test.go,seed_test.go,boot_test.go,testmain_test.go}, ../sm-demo-app/plugins/golem15/chatvideo/classes/livekit.go (RoomAPI, NewProductionRooms, FakeRooms) and boot.go, ../sm-bm-app/realtime_test.go, 20-VALIDATION.md</read_first>
|
||||
<action>Per D-05, D-06, D-07, D-08, D-09, D-11, D-12, D-22, D-23, SC-1.
|
||||
- plugins/demo/classes/chat_context_test.go (pure, with WithMembership and MemberFunc stubs): constants, BroadcastChannel never empty for either alias, CanModerateMessage only for moderator-group members in non-DM conversations, RequireLiveMembership true, ChatAccess CanManageContext always false and CanAccessContext only for demo/1 members, ForumAccess read, post and manage rules.
|
||||
- plugins/demo/chatbots_test.go: TestDemoCommands. Triggers demo and tour, IsAvailable false for actor 0, Handle returns an ephemeral result whose text lists the site paths.
|
||||
- chat_test.go (Docker), with a seeded demo and members created in the test:
|
||||
- TestDemoChatContextMembership: a banned user and a deleted user are not members; a member banned after joining loses access at the next request (live membership);
|
||||
- TestDemoChannelAdapter: the conversation of each seeded channel resolves through the channel alias;
|
||||
- TestDemoChannelsSeededOnly: POST channels is refused, join and leave work;
|
||||
- TestDemoChatBootstrap: the JSON keys and types of /_demo/api/v1/chat for a member, {member: false} for a non-member, 401 without a JWT;
|
||||
- TestDemoChatMembers: excludes the caller and personas count as members;
|
||||
- TestDemoDMs: any two members open a DM, and opening it again returns the same id;
|
||||
- TestDemoModeratorDelete: a moderator-group member deletes another member's channel message (200) but not a DM message of others (404); a plain member gets 404;
|
||||
- TestDemoCommands over HTTP: GET /_chatbots/api/v1/commands lists demo and tour; POST dispatch "/demo" answers mode ephemeral; "/nope" answers 422 errors.input.
|
||||
- video_test.go (Docker) TestDemoVideoStart: an httptest server answers the Twirp RoomService calls chatvideo's RoomAPI makes, with livekit_admin_url pointing at it and test keys in the environment. POST /_chatvideo/api/v1/conversations/{dm}/video/start answers 2xx with token and livekit_url, the token's claims grant the room for that user, and a second start returns the same session. A start in a seeded channel conversation is not refused by type (D-23 UI-only); assert the status the plugin gives with the channel's participant count and max_participants 4, and record it.
|
||||
- realtime_test.go: TestRealtimeRoutes keeps the middleware list from plan 02. New TestRealtimeMemberToken (Docker): a member's JWT gives 200 with a token, a banned user's gives 403 (or the guard's documented status), no JWT gives 401.
|
||||
- seed_chat_test.go TestSeedChat: exact counts per EN and PL channel, threads with replies and summary rows consistent, reactions, pins, three forum categories with content_html, friendships, the group, the visitor's DM and pending request when the visitor is set, the moderator group, and idempotency (every new step reports exists on the second run).
|
||||
- reset_test.go: TestResetKeepsPlans also asserts that every chat-family table named in resetTables is empty after the wipe and repopulated after the reseed, and that golem15_moderation_settings and the userfriends context row are unchanged.
|
||||
- boot_test.go: the chat-family route prefixes, and jwt.auth on GET /_demo/api/v1/chat and /chat/members.
|
||||
Commit `test: demo chat family`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-demo-app vet . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -run '^(TestDemoChannelsSeededOnly|TestDemoVideoStart|TestSeedChat|TestResetKeepsPlans|TestRealtimeMemberToken)$' -v . 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 5</automated>
|
||||
<fails_when>Non-zero exit or a FAIL line from the full app suite, or fewer than five "--- PASS" lines for the named tests (skipped without Docker, a refused channel create that succeeds, a video start error against the fake RoomService, a seed count mismatch, or a reset leaving chat rows).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '^func Test' ../sm-demo-app/chat_test.go` prints at least 7.
|
||||
- `go -C ../sm-demo-app test -count=1 -short . ./plugins/demo/...` passes without Docker.
|
||||
</acceptance_criteria>
|
||||
<done>Every demo host decision of the phase is pinned by a unit or database test.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Layer and site unit tests: bm's chat tests on the layer, new store and client tests, the call machine and the app wiring</name>
|
||||
<files>../vue-chat-layer/vitest.config.ts, ../vue-chat-layer/app/lib/chatEvents.test.ts, ../vue-chat-layer/app/lib/chatFormat.test.ts, ../vue-chat-layer/app/lib/chatText.test.ts, ../vue-chat-layer/app/lib/chatUnread.test.ts, ../vue-chat-layer/app/lib/realtime.test.ts, ../vue-chat-layer/app/lib/linkEmbeds.test.ts, ../vue-chat-layer/tests/client.test.ts, ../vue-chat-layer/tests/store.test.ts, ../vue-chatvideo-layer/tests/callMachine.test.ts, ../vue-chatvideo-layer/tests/videoClient.test.ts, ../vue-chatvideo-layer/tests/useCall.test.ts, ../vue-forum-layer/tests/client.test.ts, ../vue-userfriends-layer/tests/client.test.ts, ../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts, ../sm-demo-app/vue-demo-app/app/utils/communityAuth.test.ts, ../sm-demo-app/vue-demo-app/app/plugins/auth.ts, ../sm-demo-app/vue-demo-app/app/lib/realtime.test.ts</files>
|
||||
<read_first>../sm-bm-app/frontend/src/lib/{chatEvents,chatFormat,chatText,chatUnread,realtime}.test.ts and stores/chat.test.ts, ../sm-bm-app/frontend/vite.config.ts (its test block), ../vue-chat-layer/app/lib/*.ts, app/composables/useChat.ts, tests/smoke.test.ts, ../vue-chatvideo-layer/app/lib/*.ts and app/composables/useCall.ts, ../vue-forum-layer/app/utils/forumClient.ts, ../vue-userfriends-layer/app/utils/friendsClient.ts, ../sm-demo-app/vue-demo-app/app/plugins/auth.ts, vitest.config.ts, app/lib/realtime.test.ts</read_first>
|
||||
<action>Per D-01, D-02, D-04, D-05, D-13, D-14, D-15, D-21, D-23.
|
||||
- vue-chat-layer:
|
||||
- vitest.config.ts includes app/**/*.test.ts and tests/**/*.test.ts in the node environment, with aliases so bm's tests run with only import paths changed;
|
||||
- copy bm's chatEvents, chatFormat, chatText, chatUnread and realtime tests next to the ports;
|
||||
- linkEmbeds.test.ts: linkify escapes, only http(s), rel and target set, the registry order, max_embeds;
|
||||
- client.test.ts: every endpoint's URL and method, 401 refresh-and-retry once, unauthorized after a failed refresh, the 422 mapping, multipart upload;
|
||||
- store.test.ts (bm's chat.test.ts rewritten for the useState composable, with a fake client and a fake realtime):
|
||||
- the bootstrap fills channels and DMs; an empty hostApiBase starts nothing; a non-member bootstrap starts nothing (D-04);
|
||||
- opening a channel lazy-joins; a realtime message increments unread in other conversations and appends in the open one;
|
||||
- thread replies and counts, pins load, reactions toggle;
|
||||
- a "/" input dispatches instead of posting and the ephemeral answer stays local (D-05);
|
||||
- polling starts when realtime is unavailable;
|
||||
- onUserEvent receives a video:* event the store does not handle;
|
||||
- the conversation-actions slot renders only for DMs (mount ChatHeader with @vue/test-utils only if it is already in the workspace lockfiles, else test the computed visibility helper the header uses).
|
||||
- vue-chatvideo-layer:
|
||||
- callMachine.test.ts: every transition, including failure reasons;
|
||||
- videoClient.test.ts: URLs, auth, videoSessionChannel;
|
||||
- useCall.test.ts: vi.mock livekit-client with a fake Room; start, connect, a remote track event adds a tile, mute and camera toggles call the local participant, leave disconnects and posts leave, an ended event on the session channel ends the call, and a 422 start fails with the too-many reason.
|
||||
- vue-forum-layer and vue-userfriends-layer: extend the client tests to every method and error mapping.
|
||||
- vue-demo-app: move the hook factories from app/plugins/auth.ts unchanged into app/utils/communityAuth.ts (`createChatAuth`, `tokenGetter`, `friendsDirectory`). auth.ts imports them. communityAuth.test.ts covers the token read, refresh storing the new token, unauthorized clearing the cookie, and the directory mapping. app/lib/realtime.test.ts still passes through the re-export.
|
||||
Commit per repository (`test: ...`; the vue-demo-app extraction as `refactor: community auth hooks into app/utils` before its test commit).</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chat-layer test && pnpm --dir ../vue-chatvideo-layer test && pnpm --dir ../vue-forum-layer test && pnpm --dir ../vue-userfriends-layer test && pnpm --dir ../sm-demo-app/vue-demo-app test && pnpm --dir ../sm-demo-app/vue-demo-app run build</automated>
|
||||
<fails_when>Non-zero exit from any layer's test script, the vue-demo-app vitest suite, or the app build after the hook extraction.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `ls ../vue-chat-layer/app/lib/*.test.ts | wc -l` prints at least 6.
|
||||
- `diff <(sed -n '/^describe/,$p' ../sm-bm-app/frontend/src/lib/chatText.test.ts) <(sed -n '/^describe/,$p' ../vue-chat-layer/app/lib/chatText.test.ts)` prints nothing (only imports differ).
|
||||
- `grep -c "vi.mock('livekit-client'" ../vue-chatvideo-layer/tests/useCall.test.ts` prints 1.
|
||||
- `grep -c 'from .*communityAuth' ../sm-demo-app/vue-demo-app/app/plugins/auth.ts` prints 1.
|
||||
</acceptance_criteria>
|
||||
<done>The four layers and the site's wiring are covered by unit tests, with bm's chat tests running unchanged on the port.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 5: Two browsers locally: live channel messages and a DM call with fake media, and the phase gate in check-all</name>
|
||||
<precondition>`../sm-demo-app/scripts/dev.sh up` runs with LiveKit on 127.0.0.1:7890; the global Playwright resolves (`NODE_PATH="$(npm root -g)" node -e "require('playwright')"` exits 0).</precondition>
|
||||
<files>../sm-demo-app/scripts/check-chat.cjs, ../sm-demo-app/scripts/check-local.sh, ../sm-demo-app/scripts/check-all.sh, ../sm-demo-app/README.md</files>
|
||||
<read_first>../sm-demo-app/scripts/check-chat.cjs (plan 03), check-remote.cjs, lib/browser.cjs, check-local.sh (visitor_jwt, throwaway registration helper, check_remote), check-all.sh (steps and plugin dirs), README.md (checks section)</read_first>
|
||||
<action>Per SC-2, D-11, D-13, D-23.
|
||||
- check-chat.cjs: add `--two` and `--call` modes. Each launches Chromium with `--use-fake-ui-for-media-stream` and `--use-fake-device-for-media-stream` and opens two contexts with two JWTs (DEMO_JWT and DEMO_JWT2).
|
||||
- `--two`: both open /chat#general; A sends a unique text; B sees it within 10 s without reload; B reacts and A sees the reaction; B types and A sees the typing indicator.
|
||||
- `--call`: A opens a DM with B (POST /_chat/api/v1/contexts/demo/1/dm through page.request with A's token) and opens it on /chat. The DM header shows the call button and no call button shows in #general (D-23). A clicks it; B's page shows the incoming prompt within 10 s and accepts. Both call pages reach the connected state and each shows one remote tile whose video element has videoWidth above 0 within 20 s. A mutes and B sees the muted marker if the tile shows one. Both leave and the session ends (GET status).
|
||||
- Print `check-chat: ok two` or `check-chat: ok call`.
|
||||
- check-local.sh: `check_chatlive` and `check_callmedia` take the visitor JWT and a throwaway user's JWT, run the script in the matching mode, and join ALL_CHECKS and the header list.
|
||||
- check-all.sh, new steps after the existing plugin suites:
|
||||
- `go test ./...` in ../sm-chat-plugin, ../sm-forum-plugin and ../sm-moderation-plugin, and `go test -short ./...` in chatchannels, chatbots, chatvideo, herald and userfriends (directories overridable by env, as USER_PLUGIN_DIR is);
|
||||
- `pnpm test` in the four layer checkouts (overridable);
|
||||
- the local browser step runs `check-local.sh chatlive callmedia` alongside back and remote.
|
||||
Update the header comment and README's checks section.
|
||||
Commit `test: two-browser chat and call checks; phase gate covers the chat family`.</action>
|
||||
<verify>
|
||||
<automated>../sm-demo-app/scripts/check-local.sh chat chatlive callmedia forum friends call herald tour realtime remote</automated>
|
||||
<fails_when>The last line is not "check-local: ok ..." listing the checks; a "check-local: chatlive failed" or "callmedia failed" line (message not delivered live, no incoming prompt, no remote video within 20 s, or a call button in a channel) or any other named check failing.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'use-fake-device-for-media-stream' ../sm-demo-app/scripts/check-chat.cjs` prints at least 1.
|
||||
- `grep -cE 'chatlive|callmedia' ../sm-demo-app/scripts/check-local.sh` prints at least 4.
|
||||
- `grep -c 'sm-moderation-plugin' ../sm-demo-app/scripts/check-all.sh` prints at least 1.
|
||||
</acceptance_criteria>
|
||||
<done>Two-browser realtime chat and a DM video call are proven automatically on the local stack, and the phase gate runs every new suite.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 6: Go-ahead to push the test commits (and to release fixes if the tests found bugs)</name>
|
||||
<read_first>Claude's table: per repository the unpushed commits (`git log origin/<branch>..HEAD --oneline`), which are test-only and which are fixes; for each fix, the proposed patch tag (next free number from the remote) and the pin bumps and redeploy it needs (plan 05 runbook); failures outside Task 7's fix budget are listed as todos, not as fixes</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user chose one option and it is recorded in the SUMMARY.
|
||||
</acceptance_criteria>
|
||||
<decision>Push the test commits, and tag and redeploy fixes if there are any?</decision>
|
||||
<context>Test-only commits get no tag (19.4.1 precedent). A production fix in a shared plugin or layer needs a new patch tag (one-way), a go.mod or package.json pin bump in the demo and a redeploy through DEPLOY.md; the table lists each case. If there are no fixes, this only pushes.</context>
|
||||
<options>
|
||||
<option id="push">
|
||||
<name>Push (and release the listed fixes)</name>
|
||||
<pros>Tests are on origin; any fix reaches the live demo before the final check.</pros>
|
||||
<cons>Fix tags are permanent.</cons>
|
||||
</option>
|
||||
<option id="push-tests-only">
|
||||
<name>Push test commits only</name>
|
||||
<pros>No new tags.</pros>
|
||||
<cons>Listed fixes stay local and the live demo keeps the bug.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>Nothing leaves this machine.</pros>
|
||||
<cons>check-all's suites still run locally, but origin lacks the tests.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "push", "push-tests-only" or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 7: Push, release any fixes, and run the phase gate against the live demo</name>
|
||||
<reversibility rating="one-way">Only when fixes are released: their patch tags are cached by module proxies and lockfiles.</reversibility>
|
||||
<precondition>Task 6 answered "push" or "push-tests-only".</precondition>
|
||||
<files>../sm-demo-app/README.md</files>
|
||||
<read_first>The Task 6 table and answer, ../sm-demo-app/DEPLOY.md (Release, Verify)</read_first>
|
||||
<action>Per SC-2, SC-3, SC-4.
|
||||
- Push the test commits of every repository (plugins and layers first, then vue-demo-app, then sm-demo-app).
|
||||
- For "push" with fixes, in one release batch:
|
||||
- tag each fixed plugin or layer with the next patch (annotated, on the verified HEAD) and push;
|
||||
- bump the demo's go.mod (GOWORK=off go get) or package.json pins in one `chore: bump <name> to <tag>` commit each;
|
||||
- push vue-demo-app before the sm-demo-app pointer bump;
|
||||
- release on rome through DEPLOY.md.
|
||||
- Run `scripts/check-all.sh --local` (every suite, the browser checks, check-live). Fix a failure only within the fix budget below, then run it again. Do not loop past the budget.
|
||||
- Fix budget. It bounds the whole plan: fixes made in Tasks 1 to 5, in this task and for the Task 8 findings.
|
||||
- Source: a fix is allowed only for a failure found by this plan's own tests or checks (Tasks 1 to 5, check-all, check-live, the Task 8 UAT).
|
||||
- Size: each fix is small. It adds no feature, changes no schema or migration, and changes no API route, payload, event, config key, hook, prop or other published contract.
|
||||
- Release: at most one new patch tag per affected repository and at most one redeploy on rome in this plan. Every in-budget fix goes into that one release batch. Under "push-tests-only", fixes are committed but not tagged or deployed, and each one is recorded as a todo.
|
||||
- After the release: a fix that needs no tag or redeploy (a check script or a test in sm-demo-app) is still allowed if it is small. Anything that needs a second tag of the same repository or a second redeploy is outside the budget.
|
||||
- Outside the budget: do not fix it in this plan. Record it as a todo in `.planning/todos/pending/` with its g15office task (`.planning/G15OFFICE.md` rules). List it in the SUMMARY as a decimal-phase candidate (for example `/msd-phase --insert 20.1`). Leave the check-all result as it is, and stop at Task 8's checkpoint with the open failures listed for the user.
|
||||
- Record in README's checks section what the gate now covers.</action>
|
||||
<verify>
|
||||
<automated>../sm-demo-app/scripts/check-all.sh --local 2>&1 | tail -1 | grep -qx 'check-all: ok'</automated>
|
||||
<fails_when>The last line is not "check-all: ok" (a suite, the release build, check-pins, smoke, check-deploy, a browser check or check-live failed; the failing step is named in its own "check-all: <step> failed" line). A failure outside the fix budget keeps this red: it is recorded as a todo and the plan stops at Task 8 instead of fixing further.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- For each repository touched in this plan, `git ls-remote origin` shows the default branch at the local HEAD (or the SUMMARY records the "hold" answer).
|
||||
- Any fix tag equals its pushed HEAD and the demo pins it (`check-pins.sh` prints `check-pins: ok`).
|
||||
- The fix budget held. The SUMMARY lists every production fix with its commit and the failure that found it, every tag created in this plan (no repository twice), and at most one DEPLOY.md release. `git -C <repo> show --stat <fix>` for each listed fix touches no migration (`updates/`) and no parity test file (`php_method_map_test.go`, `golden_test.go`).
|
||||
- Either the last line of check-all is `check-all: ok`, or every remaining failure is recorded as a todo in `.planning/todos/pending/` with a `g15office:` ID and named as a decimal-phase candidate in the SUMMARY, and execution stopped at Task 8 with those failures shown to the user.
|
||||
</acceptance_criteria>
|
||||
<done>Every test is on origin, every in-budget fix is live, and the phase gate is green against the live demo, or each remaining failure is recorded as a todo and decimal-phase candidate for the user at Task 8.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Task 8: The user checks chat and a DM video call on the live demo with two browsers</name>
|
||||
<read_first>The Task 7 check-all output, ../sm-demo-app/DEPLOY.md (Verify), 20-VALIDATION.md (Manual-Only Verifications)</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user replied "approved". Or each issue they listed was fixed within Task 7's fix budget (released in the plan's one release batch only if it is still unused, check-live green again) and the user approved. Or the issues outside the budget are recorded as todos and decimal-phase candidates in the SUMMARY and the user approved closing the plan with them open.
|
||||
</acceptance_criteria>
|
||||
<what-built>https://demo.summercms.io with chat (channels, DMs, threads, pins, reactions, attachments, slash commands, floating panel), forum, friends and DM video calls through the demo's own LiveKit, moderation of banned words and links, EN and PL, and the tour cards. Anonymous visitors get register prompts on /chat and /forum.</what-built>
|
||||
<how-to-verify>
|
||||
1. Browser A: log in as the visitor (DEMO_VISITOR_EMAIL; the password is SUMMER_GOLEM15__DEMO__VISITOR__PASSWORD in /srv/summercms-demo/.env on rome). Browser B (another profile or device on a different network if possible, for example a phone on mobile data): register a new account.
|
||||
2. Both open /chat, then #general. Send a message from A and see it arrive in B without reloading. Reply in a thread, react, and pin if allowed. Type "/demo" and see the answer only in your own window.
|
||||
3. Add a banned word in the admin (log in at /smbackend with the admin credentials in /root/summercms-demo-admin.txt on rome, Settings › Moderation), then send a message containing it: it is refused with a message. Remove the word again.
|
||||
4. From A, open a DM with B's account and press the call button (it must not appear in #general). In B, accept the prompt. Both see and hear each other; mute, toggle the camera, then leave.
|
||||
5. Check /forum and /friends as a member and anonymously (register prompt), the floating chat panel on /blog, and the Polish language switch.
|
||||
</how-to-verify>
|
||||
<resume-signal>Reply "approved", or describe what is wrong.</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| test harnesses to Docker Postgres and local services | test data only, no production systems |
|
||||
| browser checks to the local and live demo | throwaway accounts, the visitor credentials from .env |
|
||||
| build machine to origin and rome (fix releases only) | tags and releases after the go-ahead |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-35 | Information disclosure | credentials in tests and check output | medium | mitigate | tests use generated users and test keys; check scripts read the visitor password from .env and never print it; the live UAT names the .env key, not the value |
|
||||
| T-20-36 | Tampering | regressions hiding behind skipped tests | medium | mitigate | verify commands count "--- PASS" lines so a Docker-less skip fails the gate; check-all runs full (non-short) suites |
|
||||
| T-20-37 | Denial of service | throwaway accounts on the live demo | low | accept | the live check registers no accounts (check-live is read-only); the human UAT creates one, removed by the reset job |
|
||||
| T-20-SC | Tampering | npm/pip/cargo installs | high | mitigate | no new package: tests use vitest 3.2.7 and the existing workspace pins; @vue/test-utils only if already in a lockfile (otherwise the helper is tested directly); Playwright is the existing global install |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: moderation suite and TestDemoModeration.
|
||||
- Task 2: chat, forum and moderation suites with Docker; parity tests unedited.
|
||||
- Task 3: sm-demo-app full suite plus the named database tests.
|
||||
- Task 4: four layer suites, vue-demo-app vitest and build.
|
||||
- Task 5: check-local with the two-browser chat and call checks.
|
||||
- Task 6: push and fix-release decision recorded.
|
||||
- Task 7: check-all --local prints check-all: ok against the live demo.
|
||||
- Task 8: the user approves the live demo.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
SC-4: the phase's new code is unit-tested in its last plan. SC-2 and SC-3 are proven live, automatically through check-all and check-live and by the user through a two-browser chat and a DM video call on https://demo.summercms.io.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-06-SUMMARY.md` when done: the test names per repository, bugs found and fixed (commits and tags), what TestDemoVideoStart recorded for a channel start, the check-all output, both checkpoint answers and the user's UAT notes.
|
||||
</output>
|
||||
@@ -0,0 +1,328 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 06
|
||||
subsystem: tests, sm-demo-app checks, vue-demo-app header
|
||||
tags: [tests, vitest, testcontainers, playwright, livekit, moderation, chat, forum, check-all, uat]
|
||||
|
||||
requires:
|
||||
- phase: 20-01
|
||||
provides: "MessageSaving and PostSaving seams, golem15.moderation Filter"
|
||||
- phase: 20-02
|
||||
provides: "the demo host (contexts, policies, bootstrap, seed, reset, realtime guard)"
|
||||
- phase: 20-03
|
||||
provides: "vue-chat-layer v0.1.0"
|
||||
- phase: 20-04
|
||||
provides: "vue-forum-layer, vue-userfriends-layer and vue-chatvideo-layer v0.1.0"
|
||||
- phase: 20-05
|
||||
provides: "the chat family live on demo.summercms.io with its own LiveKit"
|
||||
provides:
|
||||
- "Unit and database tests for the phase's new code in the plugin, layer and app repos that own it (SC-4)"
|
||||
- "check-chat.cjs --two and --call; check-local chatlive and callmedia (two browsers, a DM call with fake media through the local LiveKit)"
|
||||
- "check-all.sh runs the chat family's plugin suites, the four layer suites and the two-browser checks"
|
||||
- "The live header: every site link on the left (menu entries, Chat, Forum, member links), only the language switcher and Log in/Log out on the right"
|
||||
affects: [phase-20 verification]
|
||||
|
||||
actuals:
|
||||
tokens: 82300 # chars/4 over the realized diffs of the nine repos (329253 chars, go.sum and the roadmap snapshot excluded)
|
||||
tasks: 8
|
||||
commits: 0 # MEASURED in summercms.go: git rev-list --count 8a3ac87..HEAD before this SUMMARY commit (docs only here); code commits: 18 across nine sibling repos (table below)
|
||||
plan_head_before: 8a3ac87abb6caa5d8d668fa9ead52fb0dcc24ee9 # summercms.go
|
||||
plan_head_after: 8a3ac87abb6caa5d8d668fa9ead52fb0dcc24ee9 # summercms.go before this SUMMARY commit
|
||||
|
||||
tech-stack:
|
||||
added:
|
||||
- "sm-moderation-plugin: github.com/testcontainers/testcontainers-go v0.44.0 and github.com/jackc/pgx/v5 v5.10.0 as test-only dependencies (the decided versions the other plugins pin)"
|
||||
patterns:
|
||||
- "Fake LiveKit RoomService for Go tests: an httptest server answering /twirp/livekit.RoomService/* with empty protobuf bodies, so chatvideo's real RoomServiceClient path runs"
|
||||
- "Nuxt composables tested outside Nuxt by stubbing the auto-imported globals (useState, useNuxtApp, useChatApi, ...) over a fresh state per test"
|
||||
- "Two-browser Playwright checks with --use-fake-ui-for-media-stream and --use-fake-device-for-media-stream against the local LiveKit"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../sm-moderation-plugin/classes/filter_test.go
|
||||
- ../sm-moderation-plugin/classes/filter_internal_test.go
|
||||
- ../sm-moderation-plugin/models/settings_test.go
|
||||
- ../sm-moderation-plugin/plugin_test.go
|
||||
- ../sm-chat-plugin/saving_test.go
|
||||
- ../sm-forum-plugin/saving_test.go
|
||||
- ../sm-demo-app/moderation_test.go
|
||||
- ../sm-demo-app/chat_test.go
|
||||
- ../sm-demo-app/video_test.go
|
||||
- ../sm-demo-app/seed_chat_test.go
|
||||
- ../sm-demo-app/plugins/demo/chatbots_test.go
|
||||
- ../sm-demo-app/plugins/demo/classes/chat_context_test.go
|
||||
- ../vue-chat-layer/app/lib/chatEvents.test.ts
|
||||
- ../vue-chat-layer/app/lib/chatFormat.test.ts
|
||||
- ../vue-chat-layer/app/lib/chatText.test.ts
|
||||
- ../vue-chat-layer/app/lib/chatUnread.test.ts
|
||||
- ../vue-chat-layer/app/lib/realtime.test.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.test.ts
|
||||
- ../vue-chat-layer/app/lib/slots.ts
|
||||
- ../vue-chat-layer/tests/client.test.ts
|
||||
- ../vue-chat-layer/tests/store.test.ts
|
||||
- ../vue-chat-layer/tests/support/http.ts
|
||||
- ../vue-chatvideo-layer/tests/videoClient.test.ts
|
||||
- ../vue-chatvideo-layer/tests/useCall.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/components/SiteNav.vue
|
||||
modified:
|
||||
- ../sm-moderation-plugin/go.mod
|
||||
- ../sm-moderation-plugin/README.md
|
||||
- ../sm-demo-app/boot_test.go
|
||||
- ../sm-demo-app/realtime_test.go
|
||||
- ../sm-demo-app/reset_test.go
|
||||
- ../sm-demo-app/scripts/check-chat.cjs
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/check-all.sh
|
||||
- ../sm-demo-app/README.md
|
||||
- ../sm-demo-app/plugins/demo/content/ROADMAP.md
|
||||
- ../vue-chat-layer/vitest.config.ts
|
||||
- ../vue-chat-layer/app/components/Chat/Header.vue
|
||||
- ../vue-chat-layer/README.md
|
||||
- ../vue-chatvideo-layer/tests/callMachine.test.ts
|
||||
- ../vue-chatvideo-layer/README.md
|
||||
- ../vue-forum-layer/tests/client.test.ts
|
||||
- ../vue-userfriends-layer/tests/client.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/assets/css/site.css
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
|
||||
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
|
||||
|
||||
key-decisions:
|
||||
- "Task 6 checkpoint: push. The tests found no bugs, so there were no fixes, no tags and no fix release; only branch pushes."
|
||||
- "Task 8 round 1: the user approved the chat (and the DM video call) on the live demo, and asked for Chat and Forum in the header with every feature link on the left and only the language switcher and Log out on the right"
|
||||
- "Chat and Forum are header links in a local SiteNav, not seeded menu entries: MenuNav has no slot for app items, so the member links could not sit in its mobile panel, and seeded entries would have needed a new binary and demo:seed on rome. The fix shipped as a site-only redeploy."
|
||||
- "Task 8 round 2: approved (the live header and the live check, including the DM video call)"
|
||||
- "The DM-only conversation-actions rule became a tested helper (dmActionsTarget) instead of a component mount: @vue/test-utils is in no lockfile"
|
||||
|
||||
patterns-established:
|
||||
- "check-all.sh covers every repo the demo's chat family depends on, with overridable *_PLUGIN_DIR and *_LAYER_DIR checkouts"
|
||||
|
||||
requirements-completed: [SC-1, SC-2, SC-3, SC-4, D-01, D-02, D-04, D-05, D-06, D-07, D-08, D-09, D-11, D-12, D-13, D-14, D-15, D-17, D-18, D-20, D-21, D-22, D-23]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Banned words and links from the settings row reach the filter, the demo listeners and the chat and forum seams: 422 under content, title or body on every write path, nothing stored, list changes live, disabled passes"
|
||||
requirement: "D-17, D-18"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../sm-moderation-plugin/classes/filter_test.go#TestMatchWords, TestMatchLinks, TestParseList"
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: "../sm-demo-app/moderation_test.go#TestDemoModeration"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "The pre-save seams are silent without listeners and refuse totally with one (no row, no post-save event, no publication); a plain listener error stays 500"
|
||||
requirement: "D-18"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-chat-plugin/saving_test.go#TestMessageSavingNoListener, TestMessageSavingRejects, TestMessageSavingOtherError"
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: "../sm-forum-plugin/saving_test.go#TestPostSavingNoListener, TestPostSavingRejects"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "Moderation settings limits, the filter cache and message locale, and the plugin's boot"
|
||||
requirement: "D-17"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../sm-moderation-plugin/models/settings_test.go#TestSettingsLimits; classes/filter_internal_test.go#TestFilterCheckCache, TestViolationMessage"
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: "../sm-moderation-plugin/plugin_test.go#TestBootPublishesFilter, TestFilterCheckDisabled, TestFilterCheckReload"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "Demo host: live membership, channel adapter, seeded-only channels, bootstrap JSON, members, DMs, moderator delete limited to channels, slash commands, DM video start against a fake RoomService, seed counts and idempotency, reset of every chat-family table, member-only realtime tokens, jwt.auth on every chat-family route"
|
||||
requirement: "D-05, D-06, D-07, D-08, D-09, D-11, D-12, D-22, D-23"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "../sm-demo-app/chat_test.go, video_test.go#TestDemoVideoStart, seed_chat_test.go#TestSeedChat, reset_test.go#TestResetKeepsPlans, realtime_test.go#TestRealtimeMemberToken, boot_test.go#TestBootAllPlugins"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "../sm-demo-app/plugins/demo/classes/chat_context_test.go, plugins/demo/chatbots_test.go#TestDemoCommands"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D5
|
||||
description: "Layers: bm's chat tests unchanged on the port, the client, the multi-channel store, link embeds, the call machine, the video client, useCall on a mocked Room, the forum and friends clients, the site's auth hooks"
|
||||
requirement: "D-01, D-02, D-04, D-05, D-13, D-14, D-15, D-21, D-23"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "pnpm test in vue-chat-layer (146), vue-chatvideo-layer (114), vue-forum-layer (12), vue-userfriends-layer (11), vue-demo-app (218)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D6
|
||||
description: "Two browsers locally: a live #general message with reaction and typing; a DM call with fake media, remote video on both sides, mute seen across, the session ended after both leave; no call button in #general"
|
||||
requirement: "SC-2, D-11, D-13, D-23"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "../sm-demo-app/scripts/check-local.sh chatlive callmedia (check-chat.cjs --two, --call)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D7
|
||||
description: "The phase gate, ending with check-live against the live demo"
|
||||
requirement: "SC-2, SC-3, SC-4"
|
||||
verification:
|
||||
- kind: e2e
|
||||
ref: "../sm-demo-app/scripts/check-all.sh --local (check-all: ok)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D8
|
||||
description: "Two-browser chat and a DM video call on https://demo.summercms.io, and the header with every link on the left"
|
||||
requirement: "SC-2, SC-3"
|
||||
verification:
|
||||
- kind: manual
|
||||
ref: "Task 8 UAT by the user: approved (after the header round)"
|
||||
status: pass
|
||||
human_judgment: true
|
||||
|
||||
duration: about 3 h of work (2026-11-01 17:42Z to the header redeploy), with two checkpoints and one UAT round
|
||||
completed: 2026-11-02
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 20 Plan 06: unit tests for the chat family, two-browser checks and the live sign-off Summary
|
||||
|
||||
**The phase's new code is covered by tests in the repos that own it: the moderation filter and settings, both pre-save seams, the demo host (membership, channels, DMs, moderator delete, slash commands, video start against a fake LiveKit RoomService, seed, reset, realtime), bm's chat tests running unchanged on vue-chat-layer next to new client, store and link-embed tests, the call machine and useCall on a mocked Room, and the forum, friends and site auth clients. Two browsers prove live chat and a DM call with fake media locally, check-all gates every suite and ends green against the live demo, and the user approved the live chat, DM call and a reworked header.**
|
||||
|
||||
## Test counts
|
||||
|
||||
| Suite | Before | After |
|
||||
|---|---|---|
|
||||
| sm-moderation-plugin (Go top-level tests) | 2 | 16 |
|
||||
| sm-chat-plugin (Go) | 44 | 47 |
|
||||
| sm-forum-plugin (Go) | 16 | 18 |
|
||||
| sm-demo-app `./...` (Go) | 27 | 47 |
|
||||
| vue-chat-layer (vitest) | 6 | 146 |
|
||||
| vue-chatvideo-layer (vitest) | 10 | 114 |
|
||||
| vue-forum-layer (node --test) | 7 | 12 |
|
||||
| vue-userfriends-layer (node --test) | 6 | 11 |
|
||||
| vue-demo-app (vitest) | 209 | 218 |
|
||||
|
||||
Go counts are top-level test functions (`go test -list`); the Docker tests ran in every verify (PASS lines counted).
|
||||
|
||||
## Tests per repository
|
||||
|
||||
- **sm-moderation-plugin:**
|
||||
- `classes`: `TestMatchWords`, `TestMatchWordsFirstAndEmpty`, `TestMatchLinks`, `TestMatchLinksInvalidEntries`, `TestParseList`, `TestFilterCheckCache` and `TestViolationMessage`.
|
||||
- `models`: `TestSettingsLimits`, `TestLinkEntry` and `TestSettingsModel`.
|
||||
- root (testcontainers): `TestBootPublishesFilter`, `TestFilterCheckDisabled` and `TestFilterCheckReload`.
|
||||
- **sm-chat-plugin:** `TestMessageSavingNoListener`, `TestMessageSavingRejects` (send, reply, ReplyTo, edit; field empty, content or custom) and `TestMessageSavingOtherError`.
|
||||
- **sm-forum-plugin:** `TestPostSavingNoListener` and `TestPostSavingRejects` (thread, reply, edit; title, body or empty field; plain error 500).
|
||||
- **sm-demo-app:**
|
||||
- `TestDemoModeration`.
|
||||
- In chat_test.go: `TestDemoChatContextMembership`, `TestDemoChannelAdapter`, `TestDemoChannelsSeededOnly`, `TestDemoChatBootstrap`, `TestDemoChatMembers`, `TestDemoDMs`, `TestDemoModeratorDelete` and `TestDemoCommands` (HTTP).
|
||||
- `TestDemoVideoStart`, `TestSeedChat` and `TestSeedChatWithoutVisitor`.
|
||||
- Extended `TestResetKeepsPlans` and `TestBootAllPlugins`, and the new `TestRealtimeMemberToken`.
|
||||
- In `plugins/demo/classes`: `TestDemoChatContextConstants`, `TestDemoChatContextMembershipHooks`, `TestDemoChatContextLoaders`, `TestDemoChatAccess`, `TestDemoForumAccess` and `TestDemoMembershipWithoutDatabase`.
|
||||
- In `plugins/demo`: `TestDemoCommands`.
|
||||
- **vue-chat-layer:**
|
||||
- bm's `chatEvents`, `chatFormat`, `chatText`, `chatUnread` and `realtime` tests next to their ports (only the imports differ).
|
||||
- `linkEmbeds.test.ts`, `tests/client.test.ts` and `tests/store.test.ts`.
|
||||
- **vue-chatvideo-layer:** `callMachine.test.ts` (every event in every state), `videoClient.test.ts` and `useCall.test.ts` (`vi.mock('livekit-client')`).
|
||||
- **vue-forum-layer, vue-userfriends-layer:** every client method's refusal and answer, and the error bodies.
|
||||
- **vue-demo-app:** `app/utils/communityAuth.test.ts`. The existing `app/lib/realtime.test.ts` still passes through the re-export.
|
||||
|
||||
**What TestDemoVideoStart recorded for a channel start.** Seeded #general has 5 participants (4 personas plus the caller) against `max_participants` 4. A start there answers 422 "Conversation has too many participants for a video call". With 2 participants it answers 201, so the server has no conversation-type rule; calls are limited to DMs only by the UI (D-23). The DM start answers 201, then 200 with the same session on a second start and for the other side. The token claims (issuer, user id, room) verify with the test secret, and CreateRoom reached the fake Twirp RoomService exactly once with a bearer token.
|
||||
|
||||
## Task commits
|
||||
|
||||
| Task | Repo | Commit | Message |
|
||||
|---|---|---|---|
|
||||
| 1 | sm-moderation-plugin | 8a93cc8 | test: word, phrase and link matching of the filter |
|
||||
| 1 | sm-demo-app | a660add | test: moderation end to end through the chat and forum seams |
|
||||
| 2 | sm-moderation-plugin | 313d117 | test: settings limits, filter cache and locale, boot publishes the filter |
|
||||
| 2 | sm-chat-plugin | 6539dd2 | test: MessageSaving parity, refusals on every write path and other errors |
|
||||
| 2 | sm-forum-plugin | 13aa642 | test: PostSaving parity and refusals on thread, reply and edit |
|
||||
| 3 | sm-demo-app | 08b7784 | test: demo chat family |
|
||||
| 4 | vue-chat-layer | 764cb42 | refactor: the DM-only conversation-actions rule as a helper |
|
||||
| 4 | vue-chat-layer | b6d3389 | test: the SPA's chat tests on the port, client, store and link embeds |
|
||||
| 4 | vue-chatvideo-layer | 8222255 | test: every call transition, the video client and useCall on a fake Room |
|
||||
| 4 | vue-forum-layer | 4780824 | test: every forum client method's refusal and answer, error bodies |
|
||||
| 4 | vue-userfriends-layer | 6a5f6ce | test: every friends client method's refusal and answer, error bodies |
|
||||
| 4 | vue-demo-app | 0c1a66b | refactor: community auth hooks into app/utils |
|
||||
| 4 | vue-demo-app | ec45480 | test: community auth hooks |
|
||||
| 5 | sm-demo-app | 9b9da38 | test: two-browser chat and call checks; phase gate covers the chat family |
|
||||
| 5 | sm-demo-app | 3d86215 | chore: bump vue-demo-app (community auth hooks and their tests) |
|
||||
| 5 | sm-demo-app | 71ff755 | chore: sync the roadmap snapshot |
|
||||
| 6 | — | — | checkpoint: **push** |
|
||||
| 7 | all nine | — | branch pushes; check-all: ok |
|
||||
| 8 | vue-demo-app | deb809f | feat: every site link on the left of the header, with Chat and Forum |
|
||||
| 8 | sm-demo-app | 2cd4640 | chore: bump vue-demo-app (header: all links left, Chat and Forum) |
|
||||
| 8 | — | — | site-only redeploy on rome; UAT: **approved** |
|
||||
|
||||
Every repo was pushed with plain fast-forwards. `git ls-remote origin` equals local HEAD for each:
|
||||
|
||||
| Repo | Pushed head |
|
||||
|---|---|
|
||||
| sm-moderation-plugin | 313d117 |
|
||||
| sm-chat-plugin | 6539dd2 |
|
||||
| sm-forum-plugin | 13aa642 |
|
||||
| vue-chat-layer | b6d3389 |
|
||||
| vue-chatvideo-layer | 8222255 |
|
||||
| vue-forum-layer | 4780824 |
|
||||
| vue-userfriends-layer | 6a5f6ce |
|
||||
| vue-demo-app | deb809f |
|
||||
| sm-demo-app | 2cd4640 |
|
||||
|
||||
No tags were created in this plan.
|
||||
|
||||
## Checkpoint answers and the UAT
|
||||
|
||||
- **Task 6:** push. No bugs were found, so there were no fixes and no fix release; only branch pushes.
|
||||
- **Task 7:** `check-all.sh --local` printed `check-all: ok`. It covered:
|
||||
- every suite: the app, the MCP-tagged app, sm-user, sm-journal, chat, forum and moderation with Docker, `-short` of chatchannels, chatbots, chatvideo, herald and userfriends, vitest in vue-demo-app and the four layers;
|
||||
- `check-pins: ok (25 modules)`, `build: ok release e50834496975`, `smoke: ok` and `check-deploy: ok`;
|
||||
- `check-local: ok back remote chatlive callmedia`;
|
||||
- `check-live: ok` against https://demo.summercms.io.
|
||||
- **Task 8, round 1:** "chat itself approved, but it's missing in navbar … make all to the left, and on the right just language and logout."
|
||||
- Fix: `SiteNav` renders the main menu's entries (vue-menu-layer's `MenuNavItem`), then Chat and Forum for everyone, then My presentations, Friends and Security for members, in one list. The right side keeps only the language switcher and Log in or Log out.
|
||||
- Below 1180px every link is in the menu panel, so the member links are reachable on phones too. Phone spacing was tightened to fit 390px.
|
||||
- Checked with Playwright at 1280, 1440, 1024 and 390px, as visitor and member, in EN and PL. Also `check-local tour chat back`, `smoke.sh`, vue-demo-app's tests and build.
|
||||
- Released site-only after the user's "yes":
|
||||
- pushed deb809f and 2cd4640;
|
||||
- `build: ok release f9fa556fd20e`, `smoke: ok`;
|
||||
- rsynced only `vue-demo-app/.output/` to `site/.output.new`, swapped it in (`.output.prev` kept) and restarted only `summercms-demo-site` (RUNNING, pid 1773325);
|
||||
- `check-live: ok`;
|
||||
- the anonymous live header shows Home, Journal, FAQ, Subscriptions, Chat, Forum (PL: Start, Blog, FAQ, Subskrypcje, Czat, Forum) on the left and EN/PL and Log in on the right.
|
||||
- The binary, config, migrations, `demo:seed`, nginx, Centrifugo and LiveKit were untouched. Site rollback: `sudo mv site/.output site/.output.bad && sudo mv site/.output.prev site/.output && sudo supervisorctl restart summercms-demo-site`.
|
||||
- **Task 8, round 2:** approved. This covers the live header and the live check, including the two-browser chat and the DM video call.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
1. **Slot helper instead of a component mount.** @vue/test-utils is in no lockfile, so ChatHeader's inline DM-only `v-if` became `dmActionsTarget` (`vue-chat-layer/app/lib/slots.ts`, 764cb42, no behaviour change) and is tested in the store test. It is on vue-chat-layer main, untagged; the demo still pins v0.1.0.
|
||||
2. **Where the filter tests landed.** `TestFilterCheckCache` is an internal test in `classes`. The database tests (`TestFilterCheckDisabled`, `TestFilterCheckReload`) are in the plugin root's `plugin_test.go` with the sitemap-style harness, not in `filter_test.go`. Extra tests were added (listed above).
|
||||
3. **Test-only dependencies.** sm-moderation-plugin's go.mod gained testcontainers-go v0.44.0 and pgx v5.10.0, resolved offline with `GOPROXY=off` from the versions the other plugins already pin. The README Testing section names them.
|
||||
4. **The ported realtime test.** vue-chat-layer's `realtime.test.ts` is vue-demo-app's adapted copy of bm's test (a stubbed token route). The vitest config maps bm's `@/api/http` to `tests/support/http.ts`. The other four bm tests match bm's after `describe` (diff empty).
|
||||
5. **Split chatvideo test file.** The video-client part of `callMachine.test.ts` moved into a new `videoClient.test.ts`.
|
||||
6. **Extra demo tests.** `TestSeedChatWithoutVisitor`; `TestDemoCommands` exists in `plugins/demo` (the command objects) and in the root package (HTTP); `TestBootAllPlugins` checks `jwt.auth` on every chat-family route.
|
||||
7. **Commits needed by the gate.** The vue-demo-app pointer bump (3d86215) and a roadmap snapshot sync (71ff755) were committed in Task 5. `build.sh release` refuses a dirty tree and a stale snapshot, and the framework's ROADMAP had moved since plan 05.
|
||||
8. **The check-back hook.** The header rework kept the `site-header__mine` class on the member links and keeps the text out of template comments. scripts/check-back.cjs (also run by check-live) relies on it, so the live check works on the old and the new site alike.
|
||||
9. **Header breakpoint.** The panel takes over below 1180px rather than only below 768px, because nine links for a member do not fit on one row below that width.
|
||||
|
||||
**Total deviations:** 9. **Impact on plan:** none on the goal. No production behaviour changed except the header, which the user asked for in the UAT.
|
||||
|
||||
## Notes
|
||||
|
||||
- **Banned-link prefix matching.** A banned-link entry with a path matches by string prefix, so `shop.example/promo` also matches `/promotions`. That's what the README and the admin form say ("starts with"); the plan said "only below its path". It is not pinned by a test.
|
||||
- **A stale snapshot reddens the gate.** Any later commit to the framework ROADMAP turns `check-all` red at `sync-roadmap --check` until the demo's snapshot is synced and committed.
|
||||
- **Leftover dev process.** A `nuxt dev` from Oct 22 (pids 212159 and 212194) still runs in vue-demo-app, listening on no port. It was left alone, as instructed.
|
||||
- **Phone header before this plan.** At 390px the visitor's Polish header ("Zaloguj się") probably overflowed already; the header round fixed it along the way.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None. The new surface is test code and check scripts. The scripts read the visitor's credentials only through check-local's existing `.env` helper and never print them; the header change adds links to existing pages.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- Commits exist on their remotes: sm-moderation-plugin 8a93cc8 and 313d117; sm-chat-plugin 6539dd2; sm-forum-plugin 13aa642; vue-chat-layer 764cb42 and b6d3389; vue-chatvideo-layer 8222255; vue-forum-layer 4780824; vue-userfriends-layer 6a5f6ce; vue-demo-app 0c1a66b, ec45480 and deb809f; sm-demo-app a660add, 08b7784, 9b9da38, 3d86215, 71ff755 and 2cd4640 (`ls-remote` heads above).
|
||||
- The key files listed above exist in their repos.
|
||||
- rome: summercms-demo-site RUNNING with `site/.output` (new) and `site/.output.prev`; check-live ok.
|
||||
@@ -0,0 +1,255 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 07
|
||||
type: execute
|
||||
wave: 7
|
||||
depends_on: ["20-06"]
|
||||
gap_closure: true
|
||||
review_findings: [CR-02, CR-03]
|
||||
files_modified:
|
||||
- ../sm-moderation-plugin/classes/filter.go
|
||||
- ../sm-moderation-plugin/classes/normalize.go
|
||||
- ../sm-moderation-plugin/classes/html.go
|
||||
- ../sm-moderation-plugin/classes/bypass_test.go
|
||||
- ../sm-moderation-plugin/classes/html_test.go
|
||||
- ../sm-moderation-plugin/classes/filter_test.go
|
||||
- ../sm-moderation-plugin/models/settings.go
|
||||
- ../sm-moderation-plugin/models/settings_test.go
|
||||
- ../sm-moderation-plugin/plugin_test.go
|
||||
- ../sm-moderation-plugin/go.mod
|
||||
- ../sm-moderation-plugin/go.sum
|
||||
- ../sm-moderation-plugin/README.md
|
||||
- ../sm-forum-plugin/events/events.go
|
||||
- ../sm-forum-plugin/classes/forum_service.go
|
||||
- ../sm-forum-plugin/classes/lifecycle.go
|
||||
- ../sm-forum-plugin/saving_test.go
|
||||
- ../sm-forum-plugin/README.md
|
||||
autonomous: true
|
||||
requirements: [D-17, D-18, SC-2]
|
||||
estimate:
|
||||
tokens: 170000
|
||||
raw_tokens: 170000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "CR-03, D-17: classes.Match and Filter.Check refuse every word bypass the reviewer listed: a zero-width space or soft hyphen inside a banned word (and every other format character), a no-break, thin or ideographic space between the words of a banned phrase, decomposed (NFD) Polish diacritics against an NFC entry, fullwidth letters, HTML entities (viagra) and inline markup inside a word (via**gra**, via`gra`, _viagra_). Matching is diacritic-insensitive (zolw matches the entry żółw) and reports the entry as listed."
|
||||
- "CR-02, D-17: classes.Match and Filter.Check refuse every link bypass the reviewer listed: a percent-encoded host (bit%2Ely, bit.l%79), fullwidth letters and ideographic, fullwidth or halfwidth dots in the host, a port in front of a path rule (example.com:443/promo), a percent-encoded or doubled path (/%70romo, //promo), a trailing dot (example.com./promo), a subdomain of a path rule (sub.example.com/promo), userinfo (user@bit.ly), an entity in a link destination ([x](https://bit.ly/a)), and either spelling of an IDN (punycode against Unicode, both ways). The http(s) scheme with no or mixed slashes and backslashes after the colon (https:bit.ly) counts as the host it opens."
|
||||
- "Clean text stays clean: every existing case of TestMatchWords, TestMatchWordsFirstAndEmpty, TestMatchLinks, TestMatchLinksInvalidEntries and TestParseList keeps its expectation, except `a.shop.example/promo`, which the review's subdomain rule now flags."
|
||||
- "CR-03, D-18: forum's events.PostSaving carries HTML, the content_html breakwater renders from Body, on thread, reply and edit; the value equals what is stored. With no listener the forum's routes, payloads, stored rows and status codes are unchanged, and the existing seam, golden and method-map tests pass unedited."
|
||||
- "CR-03: classes.MatchHTML and Filter.CheckHTML read rendered HTML as a member sees it (text across inline tags joined, entities decoded, href and src values as links), so the forum's Markdown forms the raw check cannot see (bit\\.ly, via<!-- x -->gra, [x](https:bit.ly), a reference link with an entity in its destination) are refused once a host checks PostSaving.HTML."
|
||||
- "No new module enters the build: golang.org/x/text v0.42.0 and golang.org/x/net v0.58.0 become direct requires of sm-moderation-plugin at the versions the framework already requires directly (summercms.go go.mod), resolved offline."
|
||||
artifacts:
|
||||
- path: "../sm-moderation-plugin/classes/normalize.go"
|
||||
provides: "text normaliser (entities, NFKC, format characters, Unicode spaces, diacritics, inline markup) and the link-candidate canonicaliser (percent-decoding, dots, IDNA, port, userinfo, path)"
|
||||
contains: "norm.NFKC"
|
||||
- path: "../sm-moderation-plugin/classes/html.go"
|
||||
provides: "MatchHTML and Filter.CheckHTML over x/net/html tokens"
|
||||
contains: "func MatchHTML"
|
||||
- path: "../sm-moderation-plugin/classes/bypass_test.go"
|
||||
provides: "the reviewer's probes as regression tests"
|
||||
contains: "TestMatchBypassLinks"
|
||||
- path: "../sm-forum-plugin/events/events.go"
|
||||
provides: "PostSaving.HTML"
|
||||
contains: "HTML"
|
||||
key_links:
|
||||
- from: "../sm-forum-plugin/classes/forum_service.go"
|
||||
to: "../sm-forum-plugin/events/events.go"
|
||||
via: "CreateThread and Reply render first and fire PostSaving with HTML set to the rendered body"
|
||||
pattern: "HTML: *html"
|
||||
- from: "../sm-forum-plugin/classes/lifecycle.go"
|
||||
to: "../sm-forum-plugin/events/events.go"
|
||||
via: "EditPost renders first and fires PostSaving with HTML"
|
||||
pattern: "HTML: *html"
|
||||
- from: "../sm-moderation-plugin/classes/filter.go"
|
||||
to: "../sm-moderation-plugin/classes/normalize.go"
|
||||
via: "compile folds every entry and match runs on the normalised text, Check and Match alike"
|
||||
pattern: "normali[sz]e"
|
||||
prohibitions:
|
||||
- statement: "sm-moderation-plugin imports neither sm-chat-plugin nor sm-forum-plugin."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "No push, tag or deploy in this plan; sm-demo-app is not edited here (its listener change needs the new tags and lands in 20-09)."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "Forum's HTTP API, stored columns, migrations and config keys do not change; PostSaving gains a field and nothing else changes shape."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): sm-demo-app runs every shared plugin and its public site shows them working, deployed publicly.
|
||||
|
||||
This plan's slice (gap round after the code review, plan 7 of 9, wave 7): the moderation filter refuses what members actually see, not only the literal text they type. It closes CR-02 (banned-link bypass through URL forms browsers normalise) and CR-03 (banned-word bypass through invisible characters, Unicode spaces, decomposed diacritics and forum Markdown) from 20-REVIEW.md, in the two repositories that own the code: sm-moderation-plugin (the filter) and sm-forum-plugin (the pre-save seam passes the rendered post).
|
||||
|
||||
**Unit tests rule for this gap round:** the project rule "unit tests are the last plan of every phase" is met because every fix in this plan ships with its own regression tests in the repository that owns the code, and plan 20-09 runs every touched repository's full suite before anything is tagged.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Where the rendered text comes from.** Forum renders the body before it fires PostSaving and passes the result in a new field `HTML` (additive; the review's second option, "so every host gets it"). The moderation plugin offers `MatchHTML` and `Filter.CheckHTML` to read it. Moderation stays free of chat and forum imports; HTML is generic, so a later host (journal posts, a rich editor) can use the same call.
|
||||
- **The raw check stays and gets stronger.** `Check` and `Match` normalise the text themselves (entities, NFKC, format characters, Unicode spaces, diacritics, inline markup inside words), so chat messages, which the browser renders with vue-chat-layer's inline renderer, and forum titles are covered without any host change. The three forum forms the reviewer reproduced (via**gra**, viagra, an entity in a link destination) are already refused on the raw body by this normalisation; `CheckHTML` adds the forms only the renderer resolves.
|
||||
- **The demo listener.** `plugins/demo/moderation.go` `checkMessage` needs no change (Check normalises). `checkPost` needs one more check, `CheckHTML` on `ev.HTML`, which compiles only against the new moderation and forum tags. sm-demo-app's go.work points at the submodule checkouts pinned to the current tags, so that edit is made in 20-09 right after the dependency bumps, keeping every sm-demo-app commit buildable. This plan records the finding in its SUMMARY.
|
||||
- **Dependencies (CLAUDE.md rule).** `golang.org/x/text` (unicode/norm) and `golang.org/x/net` (idna for punycode, html for the tokenizer) move from indirect to direct requires of sm-moderation-plugin. Both are already direct requires of the framework at v0.42.0 and v0.58.0 (summercms.go go.mod), already in the plugin's go.sum and in the module cache, and sm-journal-plugin imports `x/net/html` directly (.planning/notes/journal-html-sanitizing-bluemonday.md). The standard library has no NFKC, IDNA or HTML tokenizer. This plan is the phase note that names them; the README's Dependencies section says so too.
|
||||
- **Diacritic-insensitive matching** folds both the entries and the text: NFD, drop nonspacing marks, recompose, plus a small map for the letters that have no decomposition (ł, đ, ø, ħ, ŧ and their capitals). An entry is reported as listed, so `Match` keeps answering "żółw", not its folded form.
|
||||
- **Path rules match subdomains** as host rules do (the review's fix). This flips one existing expectation, `a.shop.example/promo`, from clean to flagged; the plan updates that case and no other.
|
||||
- **Versions.** The next patch tags are v0.1.1 for sm-moderation-plugin (its latest tag is v0.1.0; the brief's v0.1.2 assumed a v0.1.1 that does not exist) and v0.1.2 for sm-forum-plugin (latest v0.1.1). The README changelog entries name those versions; 20-09 re-checks the tags before the release gate.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
<objective>
|
||||
Make the banned-word and banned-link filter match what a member sees: normalise the text and every link candidate before matching, read rendered forum HTML, and give the forum seam the rendered post.
|
||||
|
||||
Purpose: D-17 (banned words and links refused in chat and forum) holds against anyone who tries more than once; D-18's seam carries what the forum stores. Closes CR-02 and CR-03 server-side.
|
||||
Output: commits in ../sm-moderation-plugin and ../sm-forum-plugin (not pushed, not tagged), with regression tests for every bypass the reviewer listed.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-06-SUMMARY.md
|
||||
|
||||
Repos: ../sm-moderation-plugin (main at 313d117, tag v0.1.0) and ../sm-forum-plugin (main at 13aa642, tag v0.1.1). Both have a tracked go.work (`use .`, framework replaced by ../summercms.go). Read-only reference: ../sm-demo-app/plugins/demo/moderation.go (the listener), ../summercms.go/modules/breakwater (Render), ../sm-demo-app/plugins/demo/console/seed_friends.go (the demo's default lists: buy followers, casino bonus, free crypto, viagra; bit.ly).
|
||||
|
||||
Rules: no co-author tags; stage files by explicit path; plugin code and planning docs in separate commits; no push or tag (20-09 does both after a go-ahead); framework code and these plugins name no consuming application (README examples use `acme`); check `git status` in each repo before editing and leave edits that are not this plan's alone. Docker tests skip under `-short`; if the Docker socket is denied, run the Docker tests through `sudo -u golem` (CLAUDE.md). Resolve modules offline: `GOFLAGS=-mod=mod GOPROXY=off` for `go mod tidy`.
|
||||
|
||||
The reviewer's probe: /tmp/claude-1000/-media-nvme-dev-golem15-summercms-io-summercms-summercms-go/0fc9bf8a-bc2a-4cab-8faa-51763a879541/scratchpad/modtest/main_test.go (a module that replaces sm-moderation-plugin with the sibling checkout; run it with `GOWORK=off GOFLAGS=-mod=mod GOPROXY=off go test -v` in that directory). It may be gone after a reboot; its cases are copied into bypass_test.go in Task 1 and Task 2, which are the record.
|
||||
|
||||
<interfaces>
|
||||
sm-moderation-plugin today (classes/filter.go): consts KindWord, KindLink; type Violation {Kind, Match, Message}; `boundary` = non-letter, non-digit, non-underscore; `hostPattern` regexp (labels of letters, digits, inner hyphens, a dot; optional http(s) scheme; optional path); `ParseList(text) []string` (trim, lower-case, collapse whitespace, dedupe); unexported `compile(words, links) (*matcher, error)` and `(*matcher).match(text) *Violation` (words regexp `(?i)(?:^|boundary)(alt|alt)(?:$|boundary)` with `\s+` between phrase words; link rules {entry, host, path}, host rules match the host and its subdomains, path rules the same host and a path prefix); `Match(words, links, text) *Violation` (pure); `Filter` {db, tr, cache} with `NewFilter(db)`, `SetTranslator(tr)`, `Check(ctx, text) (*Violation, error)` (reads row 1, enabled switch, recompiles on change, translated message).
|
||||
models/settings.go: `LinkEntry(entry) (host, path string, ok bool)` (host entry or http(s) URL, lower-cased, www. and trailing dot dropped, path unescaped, port and userinfo refused), `ValidHost(h)`, `Lines`, `Text`, `Settings.BeforeValidate` (uses LinkEntry to refuse bad link entries).
|
||||
sm-forum-plugin: events.PostSaving {ContextType, ContextID, ActorID, ThreadID, PostID, Title, Body, Op}; fire sites CreateThread (classes/forum_service.go, Fire at ~284, Render at ~290), Reply (~341, Render ~347), EditPost (classes/lifecycle.go ~235, Render ~241), each guarded by `s.bus != nil`; tests saving_test.go TestPostSavingNoListener, TestPostSavingRejects (Docker harness).
|
||||
breakwater.Render output for the forum probes (checked during planning): via**gra** → `<p>via<strong>gra</strong></p>`; viagra → `<p>viagra</p>`; [x](https://bit.ly/a) → an anchor with href https://bit.ly/a; bit\.ly → `<p>bit.ly</p>`; via<!-- -->gra → `<p>viagra</p>`; [x](https:bit.ly) → href "https:bit.ly"; _viagra_ → `<em>viagra</em>`; a reference link `[x][1]` with `[1]: https://bit.ly/r` → href https://bit.ly/r.
|
||||
Go facts (checked during planning): net/url refuses a percent-escape in the host ("invalid URL escape %2E"), so the authority is percent-decoded before parsing; `idna.Lookup.ToASCII` maps fullwidth letters and the dots U+3002, U+FF0E and U+FF61 and gives punycode for an IDN (żółw.pl → xn--w-uga1v8h.pl); NFKC maps fullwidth letters and U+FF0E but not U+3002.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: a banned word split by a zero-width space and a banned host written as bit%2Ely are refused by Match and by Filter.Check, through one normaliser and one link canonicaliser, under test</name>
|
||||
<precondition>`git -C ../sm-moderation-plugin status --porcelain` prints nothing and `git -C ../sm-moderation-plugin rev-parse HEAD` equals `git -C ../sm-moderation-plugin ls-remote origin refs/heads/main` (fast-forward base).</precondition>
|
||||
<files>../sm-moderation-plugin/classes/normalize.go, ../sm-moderation-plugin/classes/filter.go, ../sm-moderation-plugin/classes/bypass_test.go, ../sm-moderation-plugin/plugin_test.go, ../sm-moderation-plugin/go.mod, ../sm-moderation-plugin/go.sum</files>
|
||||
<read_first>../sm-moderation-plugin/classes/filter.go (whole file), classes/filter_test.go (runMatch helper and the existing cases), classes/filter_internal_test.go, plugin_test.go (TestMain, the testcontainers harness, TestFilterCheckDisabled), models/settings.go (LinkEntry), go.mod, 20-REVIEW.md CR-02 and CR-03, the scratchpad probe main_test.go</read_first>
|
||||
<action>Per D-17, closing the first case of CR-03 and of CR-02 end to end.
|
||||
1. Red first: create classes/bypass_test.go (package classes_test, reusing the runMatch shape of filter_test.go) with `TestMatchBypassWords` holding one case, the word "viagra" with a U+200B zero-width space after "via", and `TestMatchBypassLinks` holding one case, "https://bit%2Ely/x" against the host entry bit.ly. Lists come from `classes.ParseList` of the demo defaults (words "buy followers", "casino bonus", "free crypto", "viagra"; links "bit.ly" and "example.com/promo"). Run them and see both fail.
|
||||
2. classes/normalize.go (new, unexported helpers, doc comments in the file's style):
|
||||
- a text normaliser used by both Match and Filter.Check: decode HTML entities once with the standard library's `html.UnescapeString`, apply `norm.NFKC` (golang.org/x/text/unicode/norm), drop every rune of category Cf (zero-width space, joiners, word joiner, BOM, soft hyphen, bidi controls), and turn every rune that `unicode.IsSpace` or the Z categories accept into a plain space;
|
||||
- a link-candidate canonicaliser: given one candidate (with or without an http(s) scheme), percent-decode its authority once (the WHATWG parser does; net/url refuses an escape in the host), parse it with net/url, take `Hostname()` (this drops the port and userinfo), lower-case it, drop a trailing dot and a leading "www.", and convert it with `idna.Lookup.ToASCII` (golang.org/x/net/idna), falling back to the lower-cased NFKC form when ToASCII refuses the label.
|
||||
3. classes/filter.go: `compile` folds each word entry with the same normaliser before quoting it, and remembers the entry as listed; `match` normalises the text first; link candidates found in the text go through the canonicaliser, and rule hosts are converted to their ASCII form once in compile. Keep `Violation.Match` the entry as listed (ParseList's form). This task only needs candidate extraction to see "bit%2Ely" as one host: widen candidate extraction so a host may contain percent-escapes (Task 2 replaces it with full tokenising).
|
||||
4. go.mod: `GOFLAGS=-mod=mod GOPROXY=off go -C ../sm-moderation-plugin mod tidy`; golang.org/x/text and golang.org/x/net move to the direct block at v0.42.0 and v0.58.0 (no version change, no new module).
|
||||
5. plugin_test.go: add `TestFilterCheckNormalises` (Docker, the existing harness): with the settings row holding the demo default lists, `Filter.Check` on the zero-width-space word answers KindWord "viagra" and on "https://bit%2Ely/x" KindLink "bit.ly", and clean text answers nil.
|
||||
6. Make both bypass tests and every existing test green. Commit in sm-moderation-plugin: `fix: normalise text and link hosts before matching banned entries`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-moderation-plugin vet ./... && go -C ../sm-moderation-plugin test -count=1 -short ./... && go -C ../sm-moderation-plugin test -count=1 -short -run '^(TestMatchBypassWords|TestMatchBypassLinks)$' -v ./classes 2>&1 | grep -c -- '^--- PASS: TestMatchBypass' | grep -qx 2 && go -C ../sm-moderation-plugin test -count=1 -run '^TestFilterCheckNormalises$' .</automated>
|
||||
<fails_when>Non-zero exit: vet fails, an existing short test breaks, either bypass test is missing or red, or the Docker test TestFilterCheckNormalises fails (the stored lists do not reach the normalised matcher).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -cE '^\s+golang.org/x/(text|net) v0\.(42|58)\.0$' ../sm-moderation-plugin/go.mod` prints 2 (both direct, without the indirect comment).
|
||||
- `go -C ../sm-moderation-plugin list -deps ./... | grep -cE 'sm-(chat|forum)-plugin'` prints 0.
|
||||
</acceptance_criteria>
|
||||
<done>One invisible-character word and one percent-encoded host are refused by the pure matcher and by the stored-list filter, and the tracer's normaliser and canonicaliser are the single path every later case goes through.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Every word and link bypass the reviewer listed is refused, entries are normalised the same way, and clean text stays clean</name>
|
||||
<files>../sm-moderation-plugin/classes/normalize.go, ../sm-moderation-plugin/classes/filter.go, ../sm-moderation-plugin/classes/bypass_test.go, ../sm-moderation-plugin/classes/filter_test.go, ../sm-moderation-plugin/models/settings.go, ../sm-moderation-plugin/models/settings_test.go, ../sm-moderation-plugin/README.md</files>
|
||||
<read_first>The Task 1 code, classes/filter_test.go (all cases), models/settings_test.go (TestLinkEntry), README.md (Features, Usage, API reference, Dependencies, Testing, Changelog), 20-REVIEW.md CR-02 table and CR-03 list, ../vue-chat-layer/app/lib/markdown.ts formatSpans and ../vue-chat-layer/app/lib/chatText.ts CODE_RE (the inline markup chat renders)</read_first>
|
||||
<behavior>
|
||||
- Words (TestMatchBypassWords): viagra split by U+200B, U+00AD, U+200D, U+2060 or U+FEFF; "buy followers" with U+00A0, U+2009, U+202F or U+3000 between the words; fullwidth viagra; viagra and viagra; via**gra**, via`gra`, via~~gra~~ and _viagra_; with the entry żółw, its NFD spelling (z plus U+0307, o plus U+0301, ł, w) and the folded spelling zolw both flag and report "żółw".
|
||||
- Words that must stay clean: spam_bot, _spam, spamming (with spam listed), and every existing TestMatchWords case.
|
||||
- Links (TestMatchBypassLinks), against bit.ly and example.com/promo: https://bit%2Ely/x, https://bit.l%79/x, bit.l%79/x, https://bit.ly/x, https://bit。ly/x, https://bit.ly/x, https://bit。ly/x, https://user@bit.ly/x, https://example.com@bit.ly/, [x](https://bit.ly/a), https:bit.ly, https:/\bit.ly/x, https://bit.ly./x, https://example.com:443/promo, https://example.com/%70romo, https://example.com//promo, https://example.com/./promo, https://example.com./promo, https://sub.example.com/promo; with the entry żółw.example, https://xn--w-uga1v8h.example/ flags, and with the entry xn--w-uga1v8h.example, https://żółw.example/ flags.
|
||||
- Links that must stay clean: https://notbit.ly/x, https://example.com/about, https://example.com/x/promo, https://bit.lyx/, and every existing TestMatchLinks case except a.shop.example/promo, which now flags (path rules cover subdomains).
|
||||
</behavior>
|
||||
<action>Per D-17, closing CR-02 and the text half of CR-03.
|
||||
- Extend bypass_test.go with every case of the behavior block (one table per test, each case commented with the bypass it pins), then make it green:
|
||||
- normaliser: after the Task 1 steps, fold diacritics (NFD, drop category Mn, recompose with NFC, then map ł Ł đ Đ ø Ø ħ Ħ ŧ Ŧ to their base letters); the same function folds the entries in compile, and a map from folded entry to listed entry keeps `Violation.Match` as listed. Join the words of a phrase with `[\p{Z}\s]+`.
|
||||
- markup: `match` runs the words and links on two forms of the text, first the normalised text, then the same text with inline markup removed: every asterisk, backtick and tilde dropped, and an underscore pair around a word (`_word_` between boundaries, the rule of vue-chat-layer's formatSpans) unwrapped. A lone underscore stays a word character, so spam_bot and _spam stay clean.
|
||||
- links: replace the regexp candidate extraction with tokenising: split the normalised text on whitespace and on the delimiters `<>"'()[]{}`, trim trailing sentence punctuation (.,;:!?), and treat a token as a candidate when it has an http(s) scheme or contains a dot after the dot mapping. For http and https, any run of slashes and backslashes after the colon (none included) counts as `//`, as the WHATWG parser reads special schemes. The candidate's path is percent-decoded and cleaned with path.Clean after a leading slash (collapses //, /./ and dot segments) and compared lower-cased. A path rule matches its host and every subdomain, like a host rule.
|
||||
- models/settings.go `LinkEntry`: apply NFKC and the dot mapping to the entry, and return the host in its IDNA ASCII form (`idna.Lookup.ToASCII`); an entry whose host ToASCII refuses is not ok, so the admin form refuses it. Existing ASCII cases of TestLinkEntry keep their results; change the żółw.example case to expect its punycode host and add cases for a fullwidth entry and an entry with U+3002.
|
||||
- filter_test.go: change only the a.shop.example/promo case to expect a KindLink violation for https://shop.example/promo, with a comment that path rules cover subdomains (CR-02).
|
||||
- README.md: Features (normalisation and link canonicalisation, in plain words, with the list of forms), Usage unchanged, API reference (LinkEntry's ASCII host), Dependencies (golang.org/x/text and golang.org/x/net, why, at the framework's versions), Testing (the new test names), Changelog `### v0.1.1` (banned entries match what members see: invisible characters, Unicode spaces, diacritics, entities, inline markup, URL forms browsers normalise; path rules cover subdomains; no schema, config or API change other than LinkEntry's ASCII host). Name no application.
|
||||
- Commit in sm-moderation-plugin: `fix: match banned words and links in the forms browsers show`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-moderation-plugin vet ./... && go -C ../sm-moderation-plugin test -count=1 -short ./... && go -C ../sm-moderation-plugin test -count=1 ./... && P=/tmp/claude-1000/-media-nvme-dev-golem15-summercms-io-summercms-summercms-go/0fc9bf8a-bc2a-4cab-8faa-51763a879541/scratchpad/modtest; if [ -f "$P/main_test.go" ]; then (cd "$P" && GOWORK=off GOFLAGS=-mod=mod GOPROXY=off go test -count=1 -v . 2>&1 | grep -c 'flagged=false' | grep -qx 0); fi</automated>
|
||||
<fails_when>Non-zero exit: vet fails; a short or Docker test fails (a bypass case still passes, a clean case is now flagged, an existing expectation other than a.shop.example/promo changed, LinkEntry refuses a valid entry); or the reviewer's probe, when it still exists, prints any flagged=false line.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `go -C ../sm-moderation-plugin test -count=1 -short -run '^TestMatchBypass(Words|Links)$' -v ./classes 2>&1 | grep -c -- '^--- PASS'` prints 2.
|
||||
- `grep -F 'a.shop.example/promo' ../sm-moderation-plugin/classes/filter_test.go | grep -c 'KindLink'` prints 1 (the one existing case that changed), and `git -C ../sm-moderation-plugin diff --stat 313d117 -- classes/filter_test.go` reports 1 deletion (the old case line; the insertions are the new case and its comment).
|
||||
- `grep -c '### v0.1.1' ../sm-moderation-plugin/README.md` prints 1.
|
||||
</acceptance_criteria>
|
||||
<done>No word or link form from the review gets past the filter, an admin's entry matches in every spelling a browser accepts, and every clean sentence the earlier tests pinned still passes.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: The forum seam carries the rendered post, and the filter reads rendered HTML the way a member sees it</name>
|
||||
<files>../sm-moderation-plugin/classes/html.go, ../sm-moderation-plugin/classes/html_test.go, ../sm-moderation-plugin/README.md, ../sm-forum-plugin/events/events.go, ../sm-forum-plugin/classes/forum_service.go, ../sm-forum-plugin/classes/lifecycle.go, ../sm-forum-plugin/saving_test.go, ../sm-forum-plugin/README.md</files>
|
||||
<read_first>../sm-forum-plugin/events/events.go, classes/forum_service.go (CreateThread, Reply), classes/lifecycle.go (EditPost, Preview), saving_test.go (harness, TestPostSavingNoListener, TestPostSavingRejects), README.md (Features "Pre-save seam", API reference, Testing, Changelog), ../summercms.go/modules/breakwater/breakwater.go (Render, the sanitiser policy: which tags and attributes survive), ../sm-demo-app/plugins/demo/moderation.go (checkPost, read only), the Task 2 normaliser</read_first>
|
||||
<behavior>
|
||||
- TestMatchHTML (moderation, -short): for each forum probe, MatchHTML(defaults, breakwater.Render(probe)) is a violation: via**gra**, viagra, _viagra_, via`gra`, via<!-- x -->gra (word "viagra"); [x](https://bit.ly/a), [x](https:bit.ly), bit\.ly, a reference link [x][1] with [1]: https://bit.ly/r, and an autolink <https://bit.ly/x> (link "bit.ly"). Clean Markdown (a heading, a list, a link to https://example.org/about, code with "via" in one span and "gra" in another paragraph) is not.
|
||||
- Text across inline tags joins without a boundary (via<strong>gra</strong> is "viagra"); block tags and <br> separate (<p>via</p><p>gra</p> is clean); href and src values are link candidates; alt and title text is checked as words.
|
||||
- TestPostSavingHTML (forum, Docker): a recording listener sees, for a thread, a reply and an edit, HTML equal to the content_html stored for that post; a body of viagra gives HTML that contains "viagra"; TestPostSavingNoListener and TestPostSavingRejects pass unchanged.
|
||||
</behavior>
|
||||
<action>Per D-17 and D-18, closing the forum half of CR-03.
|
||||
sm-forum-plugin:
|
||||
- events/events.go: add the field `HTML` to PostSaving, documented as the content_html that would be stored, rendered by breakwater from Body (sanitised), set on every Op. Update the package and type comments: the event fires after the Markdown is rendered and before anything is persisted.
|
||||
- classes/forum_service.go (CreateThread, Reply) and classes/lifecycle.go (EditPost): call `breakwater.Render(body)` before the Fire and pass the result as `HTML`; the transaction stores the same value. Behaviour without a listener is byte-identical (the render only moves up). Update the doc comments of the three methods.
|
||||
- saving_test.go: add TestPostSavingHTML per the behavior block.
|
||||
- README.md: Features "Pre-save seam" (fires after render, carries HTML), API reference row for PostSaving with HTML, the acme listener example also checking `ev.HTML`, Testing (TestPostSavingHTML), Changelog `### v0.1.2` (PostSaving carries the rendered HTML; additive, no route, payload, table, migration or config change). Commit in sm-forum-plugin: `feat: PostSaving carries the rendered post HTML`.
|
||||
sm-moderation-plugin:
|
||||
- classes/html.go: `MatchHTML(words, links []string, html string) *Violation` (pure) and `(*Filter).CheckHTML(ctx, html string) (*Violation, error)` (the same settings row, enabled switch, cache and translated message as Check). Walk the HTML with the golang.org/x/net/html tokenizer: text tokens (the tokenizer decodes entities) appended as they come, with no separator for inline elements and a newline for block elements and br; the values of href and src checked as link candidates on their own; alt and title appended as text. Then run the Task 2 matcher (both forms) on the joined text, words before links, and on each attribute URL.
|
||||
- classes/html_test.go: TestMatchHTML per the behavior block, rendering with breakwater (a framework module the plugin already requires).
|
||||
- README.md: Usage gets the host pattern for rendered content (check the source text with Check and the rendered HTML with CheckHTML, as in the acme example); API reference rows for MatchHTML and Filter.CheckHTML; Testing; the v0.1.1 changelog entry gains "MatchHTML and Filter.CheckHTML read rendered HTML". Commit in sm-moderation-plugin: `feat: MatchHTML and Filter.CheckHTML for rendered content`.
|
||||
- Read ../sm-demo-app/plugins/demo/moderation.go and write into the SUMMARY: checkMessage needs no change; checkPost needs `CheckHTML(ctx, ev.HTML)` after title and body (field body), which 20-09 adds after bumping the demo to these tags. Do not edit sm-demo-app here.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-forum-plugin vet ./... && go -C ../sm-forum-plugin test -count=1 -short ./... && go -C ../sm-forum-plugin test -count=1 -run '^(TestPostSavingNoListener|TestPostSavingRejects|TestPostSavingHTML|TestPostSavingTracer)$' . && go -C ../sm-moderation-plugin vet ./... && go -C ../sm-moderation-plugin test -count=1 -short -run '^TestMatchHTML$' -v ./classes 2>&1 | grep -q -- '^--- PASS: TestMatchHTML' && go -C ../sm-moderation-plugin test -count=1 ./...</automated>
|
||||
<fails_when>Non-zero exit: forum vet or tests fail (the HTML field differs from the stored content_html, the no-listener path changed, a refusal stopped working), TestMatchHTML is missing or red (a rendered probe passes, clean Markdown is flagged), or any moderation test fails.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -cE 'HTML: *html' ../sm-forum-plugin/classes/forum_service.go` prints 2 and `grep -cE 'HTML: *html' ../sm-forum-plugin/classes/lifecycle.go` prints 1.
|
||||
- `grep -c '### v0.1.2' ../sm-forum-plugin/README.md` prints 1.
|
||||
- `grep -cE 'MatchHTML|CheckHTML' ../sm-moderation-plugin/README.md` prints at least 3.
|
||||
</acceptance_criteria>
|
||||
<done>A host can refuse a forum post by what its readers will see, and the two plugins are ready for their patch tags with every bypass pinned by a test.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| member text to the filter | untrusted chat messages, forum titles and Markdown bodies, any Unicode |
|
||||
| filter to the member's browser | what passes is rendered as text, links and link cards by the chat renderer, goldmark and the WHATWG URL parser |
|
||||
| admin settings to the filter | banned entries typed by an administrator, any Unicode |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-38 | Spoofing | banned-link matching (classes/normalize.go, filter.go) | high | mitigate | candidates are canonicalised the way browsers resolve them (percent-decoded authority, IDNA ASCII, dots mapped, port and userinfo dropped, special-scheme slashes, cleaned path) and compared with entries in the same form; TestMatchBypassLinks pins every form from CR-02 |
|
||||
| T-20-39 | Tampering | banned-word matching | high | mitigate | NFKC, format characters dropped, Unicode spaces folded, diacritics folded on both sides, entities decoded, inline markup removed in a second pass; TestMatchBypassWords pins every form from CR-03 |
|
||||
| T-20-40 | Tampering | forum Markdown rendered after the check | high | mitigate | PostSaving carries the rendered HTML and CheckHTML reads it as a member sees it; TestPostSavingHTML and TestMatchHTML pin the rendered forms (wired in the demo in 20-09) |
|
||||
| T-20-41 | Denial of service | normalising and matching large texts | low | accept | RE2 is linear, lists are bounded by max_entries and max_entry_length, the work is two passes over a message the plugins already cap in size |
|
||||
| T-20-SC | Tampering | Go module installs | high | mitigate | no new module: golang.org/x/text v0.42.0 and golang.org/x/net v0.58.0 are already direct requires of the framework and in go.sum; tidy runs with GOPROXY=off, so nothing is fetched |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: vet, short tests, the two tracer bypass tests and the Docker TestFilterCheckNormalises.
|
||||
- Task 2: the full moderation suite with Docker; every reviewer probe flagged; one existing expectation flipped on purpose.
|
||||
- Task 3: forum suite with the HTML seam test and the unchanged seam tests; TestMatchHTML on breakwater output; the demo listener finding recorded for 20-09.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Every bypass in CR-02 and CR-03 is refused by the filter and pinned by a regression test, the forum seam passes the rendered post (D-18, additive), clean text is still accepted, and both plugins are committed, untagged, ready for 20-09's release gate.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-07-SUMMARY.md` when done: the commits per repo, the probe table (form, before, after), the one changed expectation, the dependency note, and the listener finding for 20-09 (checkMessage unchanged, checkPost adds CheckHTML on ev.HTML).
|
||||
</output>
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 07
|
||||
subsystem: moderation filter (sm-moderation-plugin) and forum pre-save seam (sm-forum-plugin)
|
||||
status: complete
|
||||
gap_closure: true
|
||||
review_findings: [CR-02, CR-03]
|
||||
tags: [moderation, normalisation, idna, nfkc, forum, seam, security]
|
||||
requires: [20-06]
|
||||
provides:
|
||||
- "classes.Match / Filter.Check normalise text and links before matching (CR-02, CR-03)"
|
||||
- "classes.MatchHTML / Filter.CheckHTML read rendered HTML as members see it"
|
||||
- "models.CanonicalHost; models.LinkEntry returns the IDNA ASCII host"
|
||||
- "forum events.PostSaving.HTML (the content_html that is stored)"
|
||||
affects: [20-09 (dependency bumps, demo listener, tags)]
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "normalise both sides: entries and text through the same fold, entry reported as listed"
|
||||
- "two passes per text (as typed, without inline markup), words before links"
|
||||
- "link candidates canonicalised like the WHATWG URL parser (percent-decoded authority, last @, port dropped, IDNA ASCII, special-scheme slashes, cleaned path)"
|
||||
key-files:
|
||||
created:
|
||||
- ../sm-moderation-plugin/classes/normalize.go
|
||||
- ../sm-moderation-plugin/classes/html.go
|
||||
- ../sm-moderation-plugin/classes/bypass_test.go
|
||||
- ../sm-moderation-plugin/classes/html_test.go
|
||||
modified:
|
||||
- ../sm-moderation-plugin/classes/filter.go
|
||||
- ../sm-moderation-plugin/classes/filter_test.go
|
||||
- ../sm-moderation-plugin/models/settings.go
|
||||
- ../sm-moderation-plugin/models/settings_test.go
|
||||
- ../sm-moderation-plugin/plugin_test.go
|
||||
- ../sm-moderation-plugin/go.mod
|
||||
- ../sm-moderation-plugin/README.md
|
||||
- ../sm-forum-plugin/events/events.go
|
||||
- ../sm-forum-plugin/classes/forum_service.go
|
||||
- ../sm-forum-plugin/classes/lifecycle.go
|
||||
- ../sm-forum-plugin/saving_test.go
|
||||
- ../sm-forum-plugin/README.md
|
||||
decisions:
|
||||
- "Hosts go through a WHATWG-like UTS #46 profile (lookup mapping, bidi and joiner rules, CheckHyphens and STD3 off) rather than idna.Lookup, which refuses names browsers open (ab--c.example)"
|
||||
- "The authority is split by hand (last @, last :) instead of net/url, which errors on escapes and odd ports and would drop the candidate"
|
||||
- "The old host regexp stays as a second candidate source next to tokenising, so every host the old matcher found (url=bad.example) is still found"
|
||||
- "The markup pass also drops a backslash before ASCII punctuation, so the raw check refuses bit\\.ly too"
|
||||
- "Combining marks Mn and Me are dropped when folding; Cc controls that are not spaces are dropped with Cf"
|
||||
metrics:
|
||||
duration: 20min
|
||||
started: 2026-11-02T17:29:01Z
|
||||
completed: 2026-11-02T17:49:03Z
|
||||
tasks: 3
|
||||
files: 16
|
||||
actuals:
|
||||
tokens: 17100
|
||||
tasks: 3
|
||||
commits: 4
|
||||
plan_head_before: "sm-moderation-plugin 313d117, sm-forum-plugin 13aa642 (summercms.go: no code commits)"
|
||||
plan_head_after: "sm-moderation-plugin 334697b, sm-forum-plugin ec1a82c"
|
||||
---
|
||||
|
||||
# Phase 20 Plan 07: Filter hardening for CR-02 and CR-03 Summary
|
||||
|
||||
The moderation filter now matches text and links the way a member reads and a browser opens them: NFKC, dropped format characters, Unicode spaces, folded diacritics, entities and inline markup for words; percent-decoding, IDNA ASCII, mapped dots, port and userinfo, special-scheme slashes and cleaned paths for links. Rendered forum HTML can be checked with `CheckHTML`, and forum's `PostSaving` now carries that HTML.
|
||||
|
||||
## Commits
|
||||
|
||||
The plan's code lives in the two sibling repos. Nothing was pushed or tagged. The `commits: 4` above was counted with `git rev-list --count` from each repo's base. The summercms.go repo has no code commits; this SUMMARY is left uncommitted for the orchestrator.
|
||||
|
||||
| Repo | Hash | Subject |
|
||||
|------|------|---------|
|
||||
| sm-moderation-plugin | 266fc60 | fix: normalise text and link hosts before matching banned entries |
|
||||
| sm-moderation-plugin | 9715ce7 | fix: match banned words and links in the forms browsers show |
|
||||
| sm-moderation-plugin | 334697b | feat: MatchHTML and Filter.CheckHTML for rendered content |
|
||||
| sm-forum-plugin | ec1a82c | feat: PostSaving carries the rendered post HTML |
|
||||
|
||||
## Probe table
|
||||
|
||||
Lists: words `buy followers`, `casino bonus`, `free crypto`, `viagra`; links `bit.ly`, `example.com/promo`. "Before" is v0.1.0 (313d117); every row was also checked with the reviewer's scratchpad probe, which now prints no `flagged=false` line.
|
||||
|
||||
| Form | Before | After | Where pinned |
|
||||
|------|--------|-------|--------------|
|
||||
| `via<U+200B>gra`, soft hyphen, ZWJ, word joiner, BOM | clean | word viagra | TestMatchBypassWords |
|
||||
| `buy<NBSP/U+2009/U+202F/U+3000>followers` | clean | word buy followers | TestMatchBypassWords |
|
||||
| fullwidth `viagra` | clean | word viagra | TestMatchBypassWords |
|
||||
| `viagra`, `viagra` | clean | word viagra | TestMatchBypassWords, TestMatchHTML |
|
||||
| `via**gra**`, ``via`gra` ``, `via~~gra~~`, `_viagra_` | clean | word viagra | TestMatchBypassWords, TestMatchHTML |
|
||||
| NFD `żółw`, folded `zolw` (entry żółw) | clean | word żółw (as listed) | TestMatchBypassWords |
|
||||
| `https://bit%2Ely/x`, `https://bit.l%79/x`, `bit.l%79/x` | clean | link bit.ly | TestMatchBypassLinks, TestFilterCheckNormalises |
|
||||
| `https://bit.ly/x`, `bit。ly`, `bit.ly`, `bit。ly` | clean | link bit.ly | TestMatchBypassLinks |
|
||||
| `https://user@bit.ly/x`, `https://example.com@bit.ly/` | flagged (the regexp found bit.ly after the @) | link bit.ly | TestMatchBypassLinks |
|
||||
| `[x](https://bit.ly/a)` | clean | link bit.ly | TestMatchBypassLinks, TestMatchHTML |
|
||||
| `https:bit.ly`, `https:/\bit.ly/x`, `https:\\bit.ly` | flagged (regexp found the bare host) | link bit.ly | TestMatchBypassLinks |
|
||||
| `https://bit.ly./x` | flagged | link bit.ly | TestMatchBypassLinks |
|
||||
| `example.com:443/promo`, `/%70romo`, `//promo`, `/./promo`, `/x/../promo`, `example.com./promo` | clean | link example.com/promo | TestMatchBypassLinks |
|
||||
| `https://sub.example.com/promo` | clean | link example.com/promo | TestMatchBypassLinks |
|
||||
| punycode against a Unicode entry, and the reverse | clean | link (entry as listed) | TestMatchBypassLinks |
|
||||
| rendered `via<!-- x -->gra`, `bit\.ly`, reference link with an entity, `<https://bit.ly/x>` | clean (raw) | flagged by MatchHTML | TestMatchHTML |
|
||||
| clean: `spam_bot`, `_spam`, `spamming`, `notbit.ly`, `/about`, `/x/promo`, `bit.lyx`, `<p>via</p><p>gra</p>` | clean | clean | bypass and HTML tests |
|
||||
|
||||
## The one changed expectation
|
||||
|
||||
`TestMatchLinks`: `a.shop.example/promo` against the entry `https://shop.example/promo` was clean and now flags (KindLink, entry as listed). Path rules cover subdomains, as host rules do (CR-02). `git diff --stat 313d117 -- classes/filter_test.go` shows 2 insertions (the comment and the case) and 1 deletion. No other existing case changed.
|
||||
|
||||
`TestLinkEntry`: the `żółw.example` case now expects `xn--w-uga1v8h.example`. New cases cover fullwidth letters, U+3002 and U+FF61 dots, an ASCII punycode entry, `ab--c.example` (accepted) and the invalid punycode `xn--zz.example` (refused).
|
||||
|
||||
## Dependency note
|
||||
|
||||
`golang.org/x/text v0.42.0` (unicode/norm) and `golang.org/x/net v0.58.0` (idna, html) moved from indirect to direct requires of sm-moderation-plugin. The framework already requires both directly at these versions. `go mod tidy` ran with `GOPROXY=off`, go.sum did not change, and no new module entered the build. The README's Dependencies section names both. `go list -deps ./...` shows no sm-chat-plugin or sm-forum-plugin import.
|
||||
|
||||
## Listener finding for 20-09
|
||||
|
||||
`../sm-demo-app/plugins/demo/moderation.go` (read only, not edited):
|
||||
|
||||
- `checkMessage` needs no change: `Check` now normalises the chat text itself.
|
||||
- `checkPost` should call `f.CheckHTML(ctx, ev.HTML)` after the title and body checks, and reject under field `body` when it flags. This only compiles against the new tags (sm-forum-plugin v0.1.2 for `PostSaving.HTML`, sm-moderation-plugin v0.1.1 for `CheckHTML`). The demo's go.work uses the submodule checkouts at `plugins/golem15/{forum,moderation}`, currently at v0.1.1 and v0.1.0. So the edit belongs right after 20-09 bumps those submodules.
|
||||
- Even without that edit, the raw `Check` on the body now refuses `via**gra**`, `viagra`, `_viagra_`, `[x](https://bit.ly/a)`, `[x](https:bit.ly)` and `bit\.ly`. Only the forms the renderer alone resolves, such as a comment inside a word or a reference-link destination with an entity, need `CheckHTML`.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] TestPostSavingNoListener had to gain the HTML field**
|
||||
- **Found during:** Task 3
|
||||
- **Issue:** The plan said the existing seam tests pass unedited. But `TestPostSavingNoListener` compares whole `PostSaving` values with `slices.Equal`, so the new field made it fail.
|
||||
- **Fix:** The three expected events now carry `HTML: breakwater.Render(body)`. Nothing else in the test changed. `TestPostSavingRejects`, `TestPostSavingTracer`, the golden and method-map tests are unedited and pass.
|
||||
- **Files modified:** ../sm-forum-plugin/saving_test.go
|
||||
- **Commit:** ec1a82c
|
||||
|
||||
**2. [Rule 1 - Bug] WHATWG-like IDNA profile instead of `idna.Lookup`**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** `idna.Lookup` checks hyphens. It refuses `ab--c.example`, a name browsers open. Used in `LinkEntry`, that would make the admin form reject a valid entry.
|
||||
- **Fix:** `models.CanonicalHost` uses `idna.New(MapForLookup, BidiRule, Transitional(false), CheckHyphens(false), StrictDomainName(false), CheckJoiners(true))`, which is UTS #46 as the URL standard applies it. Punycode results are the same (`żółw.example` → `xn--w-uga1v8h.example`). It is one exported function used by both `LinkEntry` and the matcher, so entries and candidates are always read alike.
|
||||
- **Files modified:** ../sm-moderation-plugin/models/settings.go
|
||||
- **Commit:** 9715ce7
|
||||
|
||||
**3. [Rule 1 - Bug] Authority split by hand, not with net/url**
|
||||
- **Issue:** `url.Parse` errors on some decoded hosts and on non-numeric ports. Each such error would silently drop a candidate.
|
||||
- **Fix:** `canonicalLink` takes the text after the last `@`, drops a `:port` and passes the host to CanonicalHost. This gives the same result as `Hostname()` for valid URLs and never drops a candidate.
|
||||
- **Commit:** 266fc60
|
||||
|
||||
**4. [Rule 2 - Missing functionality] The host regexp stays next to tokenising**
|
||||
- **Issue:** The plan said to replace the regexp with tokenising. Tokens alone miss a host glued to other text (`url=bad.example`, `a,bad.example`), which the old matcher found.
|
||||
- **Fix:** `matchLinks` checks the tokens first, then every `hostPattern` match (widened for percent-escapes). The union can only add matches, and every must-stay-clean case still passes.
|
||||
- **Commit:** 9715ce7
|
||||
|
||||
**5. [Rule 2 - Missing functionality] Small additions to the normaliser**
|
||||
- The markup pass also drops a backslash before ASCII punctuation (a Markdown escape), so the raw check refuses `bit\.ly`.
|
||||
- Controls (Cc) that are not spaces are dropped along with Cf.
|
||||
- Diacritic folding drops enclosing marks (Me) along with Mn.
|
||||
- **Commit:** 266fc60, 9715ce7
|
||||
|
||||
**6. [Rule 2 - Test coverage] Extra tests**
|
||||
- `TestFilterCheckNormalises` also covers `CheckHTML` through the stored lists: word, link with the pl message, clean, disabled.
|
||||
- `TestMatchHTMLWalk` pins the tokenizer walk: inline joins, block/br/td separation, href, src, alt and title, comments and scripts.
|
||||
- **Commit:** 334697b
|
||||
|
||||
**7. [Rule 1 - Bug] Invisible characters escaped in test sources**
|
||||
- The first bypass test was committed with a literal U+200B in its source (266fc60). In 9715ce7 every invisible or combining character in the test sources became a `\uXXXX` escape, so the cases can be read and reviewed.
|
||||
|
||||
### TDD notes
|
||||
|
||||
- Task 1: RED was seen before any code changed. Both tracer tests failed with "got no violation".
|
||||
- Task 2: RED was seen before the code changed: 19 "got no violation" failures across TestMatchBypassWords, TestMatchBypassLinks and the flipped TestMatchLinks case.
|
||||
- Task 3: the HTML tests were written after `html.go`, and both passed on their first run. RED was not observed separately.
|
||||
|
||||
## Test results
|
||||
|
||||
- sm-moderation-plugin: `go vet ./...` is clean. `go test -short ./...` and `go test ./...` (Docker Postgres) pass. That covers TestMatchBypassWords, TestMatchBypassLinks, TestMatchHTML, TestMatchHTMLWalk, TestLinkEntry and TestFilterCheckNormalises.
|
||||
- sm-forum-plugin: `go vet ./...` is clean. `go test -short ./...` and `go test ./...` (Docker) pass, including TestPostSavingTracer, TestPostSavingNoListener, TestPostSavingRejects and TestPostSavingHTML.
|
||||
- Reviewer probe (scratchpad modtest): all 20 cases print `flagged=true`.
|
||||
- Acceptance greps: go.mod has 2 direct x/text and x/net lines. There are 0 chat/forum deps. `HTML: html` appears 2 times in forum_service.go and once in lifecycle.go. Each README has one changelog heading (`### v0.1.1` moderation, `### v0.1.2` forum). MatchHTML/CheckHTML appear 11 times in the moderation README.
|
||||
|
||||
## Known limitations (not stubs)
|
||||
|
||||
- Path rules are prefixes, as before: `example.com/promo` also matches `/promotional`. This behaviour is older than this plan and was not changed.
|
||||
- IPv4 forms a browser normalises (`0x7f.1`, dotless decimals) and IPv6 literals are not canonicalised. No listed entry in the review relies on them.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None. No new endpoint, auth path, file access or schema change. PostSaving gains a read-only field.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: classes/normalize.go, classes/html.go, classes/bypass_test.go, classes/html_test.go (sm-moderation-plugin)
|
||||
- FOUND commits: 266fc60, 9715ce7, 334697b (sm-moderation-plugin), ec1a82c (sm-forum-plugin)
|
||||
@@ -0,0 +1,324 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 08
|
||||
type: execute
|
||||
wave: 7
|
||||
depends_on: ["20-06"]
|
||||
gap_closure: true
|
||||
review_findings: [CR-01, WR-01, WR-04, WR-05, CR-02]
|
||||
files_modified:
|
||||
- ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- ../vue-chatvideo-layer/app/lib/videoClient.ts
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/Call.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue
|
||||
- ../vue-chatvideo-layer/app/assets/css/chatvideo-base.css
|
||||
- ../vue-chatvideo-layer/i18n/locales/en.json
|
||||
- ../vue-chatvideo-layer/i18n/locales/pl.json
|
||||
- ../vue-chatvideo-layer/tests/useCall.test.ts
|
||||
- ../vue-chatvideo-layer/tests/videoClient.test.ts
|
||||
- ../vue-chatvideo-layer/README.md
|
||||
- ../vue-chat-layer/app/lib/urlGuard.ts
|
||||
- ../vue-chat-layer/app/lib/urlGuard.test.ts
|
||||
- ../vue-chat-layer/app/lib/markdown.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.test.ts
|
||||
- ../vue-chat-layer/README.md
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/composables/useDemoAuth.ts
|
||||
autonomous: true
|
||||
requirements: [SC-2, D-02, D-04, D-11, D-13, D-17, D-23]
|
||||
estimate:
|
||||
tokens: 230000
|
||||
raw_tokens: 230000
|
||||
tasks: 5
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "CR-01, D-13: a call the user leaves, or whose page unmounts, while start or join is pending, while livekit-client loads, while LiveKit connects or between enabling the camera and the microphone never publishes media after the leave: no Room connects after it, setCameraEnabled and setMicrophoneEnabled are not called after it, a Room already created is disconnected, and once the server session exists the starter posts end and the callee posts leave. Leave works in the starting and connecting states. A second begin while one is pending creates no second Room."
|
||||
- "WR-05: a failed LiveKit connect posts end when the session has nobody joined besides this user (GET status), and leave otherwise; when status cannot be read, the starter posts end and the callee leave."
|
||||
- "WR-04, D-11, D-13, D-23: ChatvideoCall starts media on mount only when an in-memory handoff younger than a minute shows the user just clicked: the DM call button's start answer (start) or the incoming prompt's Accept (join). A direct load or a chat link to /call/{id}, with or without ?start=1, shows a confirmation with a Start call or Join call button and calls neither video/start nor video/join and opens no LiveKit connection until it is clicked."
|
||||
- "CR-02 (client side), D-02, D-17: the chat renders as text, with no link and no link card, any http(s) URL whose host as written is not the host the browser opens: a percent-escape, userinfo or a backslash in the authority, ideographic, fullwidth or halfwidth dots, fullwidth letters, a trailing dot, or a scheme not followed by exactly two slashes. Honest URLs, IDN hosts written in Unicode, ports, queries and fragments still link and embed. bm's copied chat tests pass unchanged."
|
||||
- "WR-01, D-04: logging out (header or login page) and the chat's unauthorized() reset the chat store, close the shared realtime socket and dismiss a ringing call prompt in the same tab; one failing part does not stop the others; the next login starts from empty chat state with a fresh connection token."
|
||||
- "Every fix has vitest regression tests in the repository that owns it; vue-demo-app builds and passes its tests on its current layer pins (v0.1.0 already exports useChat().reset, the realtime disconnect and useIncomingCalls().dismiss); nothing is pushed or tagged here."
|
||||
artifacts:
|
||||
- path: "../vue-chatvideo-layer/app/composables/useCall.ts"
|
||||
provides: "per-attempt token, stale checks after every await, leave from the pre-room states, failed-connect end rule"
|
||||
contains: "attempt"
|
||||
- path: "../vue-chatvideo-layer/app/lib/videoClient.ts"
|
||||
provides: "hasStart, rememberAccept, takeAccept and callAutostart (the click handoffs)"
|
||||
contains: "callAutostart"
|
||||
- path: "../vue-chatvideo-layer/app/components/Chatvideo/Call.vue"
|
||||
provides: "the join confirmation"
|
||||
contains: "chatvideo-confirm"
|
||||
- path: "../vue-chat-layer/app/lib/urlGuard.ts"
|
||||
provides: "honestHttpUrl"
|
||||
contains: "honestHttpUrl"
|
||||
- path: "../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts"
|
||||
provides: "createCommunitySignOut and endSession"
|
||||
contains: "createCommunitySignOut"
|
||||
key_links:
|
||||
- from: "../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue"
|
||||
to: "../vue-chatvideo-layer/app/lib/videoClient.ts"
|
||||
via: "Accept leaves the join handoff before it navigates"
|
||||
pattern: "rememberAccept"
|
||||
- from: "../vue-chatvideo-layer/app/components/Chatvideo/Call.vue"
|
||||
to: "../vue-chatvideo-layer/app/lib/videoClient.ts"
|
||||
via: "mount begins only when callAutostart answers true"
|
||||
pattern: "callAutostart"
|
||||
- from: "../vue-chat-layer/app/lib/markdown.ts"
|
||||
to: "../vue-chat-layer/app/lib/urlGuard.ts"
|
||||
via: "safeUrl allows an http(s) target only through honestHttpUrl"
|
||||
pattern: "honestHttpUrl"
|
||||
- from: "../vue-chat-layer/app/lib/linkEmbeds.ts"
|
||||
to: "../vue-chat-layer/app/lib/urlGuard.ts"
|
||||
via: "linkify and messageUrls parse through honestHttpUrl"
|
||||
pattern: "honestHttpUrl"
|
||||
- from: "../sm-demo-app/vue-demo-app/app/plugins/auth.ts"
|
||||
to: "../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts"
|
||||
via: "the plugin builds the sign-out and hands it to createChatAuth and to logout"
|
||||
pattern: "createCommunitySignOut"
|
||||
prohibitions:
|
||||
- statement: "No push, tag or pin change in this plan; vue-demo-app keeps its v0.1.0 layer pins and the sm-demo-app gitlink is not bumped (20-09)."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "No new package in any package.json or lockfile; tests use vitest, vi.mock and pure helpers (no @vue/test-utils, which no lockfile has)."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "Neither layer names a consuming application or a host path."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): sm-demo-app runs every shared plugin and its public site shows them working, video calls included.
|
||||
|
||||
This plan's slice (gap round after the code review, plan 8 of 9, wave 7, parallel with 20-07: no shared file): the call and session fixes from 20-REVIEW.md in the repositories that own the code.
|
||||
- CR-01: leaving or unmounting during start or join still connected and published the camera and microphone.
|
||||
- WR-05: a failed connect posted leave and left an empty ringing session.
|
||||
- WR-04: a link opened a call and turned media on with no confirmation.
|
||||
- WR-01: logout left the previous user's chat store, realtime socket and call prompt running.
|
||||
- The client half of CR-02: the chat's link-embed rendering gets the guard the brief asked for; the server half is 20-07.
|
||||
|
||||
**Unit tests rule for this gap round:** the project rule "unit tests are the last plan of every phase" is met because every fix here ships with vitest regression tests in the repository that owns it, and 20-09 runs every touched repository's full suite before anything is tagged.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **One attempt token** (the review's fix shape). `begin` increments an attempt counter and dispatches `start` before its first await, for the callee too, so the state leaves idle at once and Leave and unmount always see a live attempt. After every await (the start or join answer, the livekit-client import, connect, each media toggle) it bails out when the attempt is stale. `leave()` invalidates the attempt. The call machine already moves starting → connecting on `joined`, so it needs no change.
|
||||
- **Who posts what after a stale answer.** When the start or join answer arrives after a leave, the server session exists only from that moment, so `begin`'s stale branch posts `end` (starter) or `leave` (callee) itself. `leave()` posts only when an answer has already arrived for the attempt. This avoids the 404 that the current code's premature `end` produced.
|
||||
- **"Alone" after a failed connect (WR-05).** The review's formula (`start || remoteParticipants.size === 0`) would end the call for a waiting caller whenever a callee's connect fails, because a room that never connected has no remote participants. The plan uses the server's view instead: GET status, alone when at most one participant has status `joined` (chatvideo marks the starter joined at start and the callee at join). Fallback on a status error: the starter ends, the callee leaves.
|
||||
- **Confirmation (WR-04).** The autostart decision is a pure helper, `callAutostart(conversationId, start)`, over in-memory handoffs that a link cannot create: the call button's start answer (existing `rememberStart`, now readable with `hasStart` without taking it) and a new Accept marker (`rememberAccept`, `takeAccept`), each valid for a minute. `?start=1` stays in the demo's call path but only chooses Start over Join on the confirmation. The rule is tested as a helper because @vue/test-utils is in no lockfile (20-06 deviation 1). The demo's call page needs no code change. Its doc comment is updated together with the pin bump in 20-09, so it never describes behaviour that the pinned layer lacks.
|
||||
- **Link guard (CR-02 client side).** It lives in a new `app/lib/urlGuard.ts` with `honestHttpUrl(raw)`, used by `safeUrl` (markdown.ts) and by `parseHttp` (linkEmbeds.ts). A deceptive URL stays text: no anchor and no card. The server now refuses banned ones (20-07). The client guard covers any host, so a card never shows a different host than the text. bm's copied tests (chatText.test.ts and the other four) stay byte-identical, so the new cases go into urlGuard.test.ts and linkEmbeds.test.ts.
|
||||
- **Sign-out (WR-01).** The review's explicit-call option, not a `watch(loggedIn)`: the token store is document.cookie, which a useCookie watcher would not see when `unauthorized()` clears it. `createCommunitySignOut` and `endSession` are Nuxt-free factories in `app/utils/communityAuth.ts`, tested with vitest. The plugin builds the sign-out with `nuxtApp.runWithContext` and hands it to `createChatAuth` (unauthorized) and, through `$communitySignOut`, to `useDemoAuth().logout()`. SiteHeader.vue and login.vue already go through `logout()` and need no change. Clearing `chatvideo:incoming` uses `useIncomingCalls().dismiss()`, which also stops the ring timer and closes the session handle. The handle leak between two pending subscribes is IN-07 and stays deferred.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
<objective>
|
||||
Make leaving a call final at any moment, end empty sessions after a failed connect, ask before a call page starts the camera and microphone, keep deceptive link hosts out of chat links and cards, and reset the previous user's chat, socket and call prompt on logout.
|
||||
|
||||
Purpose: D-13 (the minimal call page) and D-11/D-23 (DM calls from the call button) behave as the user expects. D-02 and D-17 hold in the chat renderer. D-04 holds after logout (no chat for a signed-out visitor).
|
||||
Output: commits in ../vue-chatvideo-layer, ../vue-chat-layer and ../sm-demo-app/vue-demo-app (not pushed, not tagged, pins unchanged), each with vitest regression tests.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-06-SUMMARY.md
|
||||
|
||||
Repos: ../vue-chatvideo-layer (main at 8222255, tag v0.1.0), ../vue-chat-layer (main at b6d3389, tag v0.1.0; 764cb42 and b6d3389 are already on main after the tag), ../sm-demo-app/vue-demo-app (the submodule, master at deb809f; pins vue-chat-layer and vue-chatvideo-layer v0.1.0 by git+https tag). Test runners: `pnpm --dir <repo> test` (vitest 3.2.7); the layers' SFCs compile with `pnpm --dir <layer> run build:playground`; vue-demo-app builds with `pnpm --dir ../sm-demo-app/vue-demo-app run build`.
|
||||
|
||||
Rules: no co-author tags; stage files by explicit path; no push, tag or pin change (20-09); a layer's README changes in the same commit as its API; the layers name no application; check `git status` in each repo before editing and leave edits that are not this plan's alone (vue-demo-app often has a stale `nuxt dev` from 2026-10-22 running, pids 212159 and 212194, leave it alone). Do not edit sm-demo-app itself; its browser checks for these fixes are written in 20-09 Task 1, where they run against the unreleased layers.
|
||||
|
||||
<interfaces>
|
||||
vue-chatvideo-layer today:
|
||||
- app/composables/useCall.ts: `useCall(conversationId)` returns {state, tiles, declined, audioBlocked, reconnecting, mediaError, begin(start), leave(), toggleMute(), toggleCamera(), startAudio()}; module-level `room`, `lk`, `channel`, `leaving`; begin: guard on `status !== 'idle' && isLive`, `dispatch start` only for the starter, `await client.start/join` (or takeStart), `joined`, pagehide listener, `openChannel(session_id)`, `await import('livekit-client')`, `room = new Room(...)`, `await r.connect`, a check that room is still r, `connected`, `await setCameraEnabled(true)`, `await setMicrophoneEnabled(true)`; on connect failure it posts leave. `leave()` returns early on idle; it posts end when alone (no room or no remote participants) else leave, then disconnects. onBeforeUnmount calls leave.
|
||||
- app/lib/callMachine.ts: states idle, starting, connecting, connected, ended, failed; `joined` accepted from idle or starting; `isLive`; unchanged by this plan.
|
||||
- app/lib/videoClient.ts: `createVideoClient` {start, join, leave, end, status → VideoStatus {session_id, conversation_id, status, started_by, participants [{user_id, status}]} or null}; `rememberStart`/`takeStart` (in-memory, a minute, taken once); `videoSessionChannel`; `parseIncomingCall`.
|
||||
- Call.vue: props conversationId, start, backPath; `onMounted(() => call.begin(props.start))`; Leave enabled while starting, connecting or connected; retry calls begin. IncomingCall.vue: `accept()` takes the pending call and navigates to callPath; decline posts leave. Locale keys chatvideo.state.*, chatvideo.action.*, chatvideo.reason.*.
|
||||
- tests/useCall.test.ts: vi.mock of livekit-client (fake Room with connect, disconnect, localParticipant setters as vi.fn, `Room.instances`, `failConnect`, `onCreate`), vi.mock of vue-chat-layer realtime (`realtime.subs`), unmount hooks captured, a stub client (start, join, leave, end, status as vi.fn), `connected(start)` helper. The test "a failed LiveKit connect fails the call and leaves the session" expects leave; WR-05 changes it.
|
||||
- chatvideo server facts: Start creates the session with the starter's participant row `joined` and the others `invited`; Join marks the actor `joined`; Leave marks `left`.
|
||||
vue-chat-layer today: app/lib/markdown.ts `safeUrl(raw)` (http(s) with `//` and a non-slash, mailto, site paths, anchors), `escapeHtml`, `formatSpans`; app/lib/chatText.ts `renderChatText` (LINK_RE, URL_RE through safeUrl); app/lib/linkEmbeds.ts `parseHttp(raw)` (new URL, http(s) only), `linkify`, `messageUrls`, `registerEmbedRenderer`, `embedRendererFor`; Chat/LinkEmbed.vue shows url.host and links url.href; useChat `reset()` (exported in v0.1.0); app/lib/realtime.ts `disconnect()` (exported in v0.1.0).
|
||||
vue-demo-app today: app/utils/communityAuth.ts {CommunityTokens, CommunityFetch, tokenGetter, createChatAuth(store, fetchJson) → {token, refresh, unauthorized}, friendsDirectory}; app/plugins/auth.ts provides paymentGatewayAuth, chatAuth, forumAuth, userfriendsAuth, userfriendsDirectory and calls setRealtimeAuth; app/composables/useDemoAuth.ts `logout()` posts /_user/api/v1/logout with the token, then `token.value = null`; app/lib/realtime.ts re-exports vue-chat-layer's realtime (disconnect included); app/layouts/default.vue renders ChatFloatingPanel and ChatvideoIncomingCall for members.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: the caller clicks Leave while the call is still starting, and nothing connects or turns on afterwards, under test</name>
|
||||
<precondition>`git -C ../vue-chatvideo-layer status --porcelain` prints nothing; `pnpm --dir ../vue-chatvideo-layer test` passes before the change.</precondition>
|
||||
<files>../vue-chatvideo-layer/app/composables/useCall.ts, ../vue-chatvideo-layer/tests/useCall.test.ts</files>
|
||||
<read_first>../vue-chatvideo-layer/app/composables/useCall.ts (whole file), app/lib/callMachine.ts, tests/useCall.test.ts (whole file: the fakes, beforeEach, the connected helper, every existing test), 20-REVIEW.md CR-01</read_first>
|
||||
<action>Per D-13, closing the caller path of CR-01 end to end.
|
||||
1. Red first: in tests/useCall.test.ts add a small deferred-promise helper and the test "leave while start is pending: no room, no media, end once the session exists". `client.start` answers a deferred promise; call `begin(true)` without awaiting it, `await leave()`, then resolve the start answer and await the begin promise. Expect: no fake Room was connected (`Room.instances` empty, or none of them had connect called), setCameraEnabled and setMicrophoneEnabled never called, `client.end` called once with the conversation id after the answer arrived, the state ended with reason left, no open session channel, no pagehide listener. Run it and see it fail.
|
||||
2. useCall.ts: add the per-attempt counter. begin increments it and keeps its own number, resets `leaving`, dispatches `start` before the first await (for both roles), and after the start or join answer checks whether the attempt is stale (another attempt started or leave ran); if so it posts `end` for a start or `leave` for a join (errors swallowed) and returns before subscribing, adding the pagehide listener or loading livekit-client. leave() no longer returns early while an attempt is in flight in the starting state: it marks leaving, invalidates the attempt, dispatches leave, posts end or leave only when this attempt already has its answer, and disconnects.
|
||||
3. Keep every existing test green; update the module header comment (begin, leave and unmount semantics).
|
||||
4. Commit in vue-chatvideo-layer: `fix: leaving while a call starts never connects it`.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chatvideo-layer test</automated>
|
||||
<fails_when>Non-zero exit: the new test fails (a Room connects, a media setter runs, end is posted before or never, the state is not ended) or an existing useCall, callMachine or videoClient test breaks.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'leave while start is pending' ../vue-chatvideo-layer/tests/useCall.test.ts` prints 1.
|
||||
- `git -C ../vue-chatvideo-layer diff --stat 8222255 -- package.json pnpm-lock.yaml` prints nothing.
|
||||
</acceptance_criteria>
|
||||
<done>A caller who hangs up during "Connecting…" is out of the call for good: the late start answer ends the session and no camera or microphone turns on.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Every other moment of leaving is final too (callee join, unmount, livekit-client load, connect, between camera and microphone, a second begin), and a failed connect ends an empty session</name>
|
||||
<files>../vue-chatvideo-layer/app/composables/useCall.ts, ../vue-chatvideo-layer/tests/useCall.test.ts, ../vue-chatvideo-layer/README.md</files>
|
||||
<read_first>The Task 1 code and test, tests/useCall.test.ts (the fake Room's connect and setters, failConnect, onCreate, the unmount hooks), app/lib/videoClient.ts (status, VideoStatus), README.md (Usage, "The call flow", API reference, Testing)</read_first>
|
||||
<behavior>
|
||||
- "unmount while join is pending": begin(false) with a deferred join, run the captured unmount hook, resolve the join; no Room connects, no media setter runs, client.leave is posted once after the answer, state ended.
|
||||
- "leave while connect is pending": connect answers a deferred promise; leave; resolve connect; setCameraEnabled and setMicrophoneEnabled never called, the Room disconnected, end posted once (alone).
|
||||
- "leave between camera and microphone": setCameraEnabled answers a deferred promise; leave; resolve it; setMicrophoneEnabled never called, the Room disconnected.
|
||||
- "leave while livekit-client loads": the import is awaited after the answer; stall it with a hoisted deferred gate in the mocked module if vitest allows it reliably, otherwise call leave in the same tick the answer resolves (the stale check right after the answer) and say which in the SUMMARY; no Room created after the leave, end posted once.
|
||||
- "a second begin while the first join is pending": two begin(false) calls before the answer; join called once, at most one Room ever created and connected.
|
||||
- WR-05 "a failed connect ends a session nobody else joined": failConnect set, client.status answers participants [{user_id: 7, status: 'joined'}, {user_id: 9, status: 'invited'}]; client.end posted, client.leave not. "a failed connect leaves when the other side joined": status answers two joined participants; client.leave posted, client.end not. "status unreadable": status rejects; the starter posts end, the callee posts leave.
|
||||
- The existing test "a failed LiveKit connect fails the call and leaves the session" is renamed and changed to the WR-05 rule: the stub's status answers undefined, which counts as unreadable (as do null and a rejection), so the starter ends; every other existing expectation stays.
|
||||
</behavior>
|
||||
<action>Per D-13 and D-12 (the reconcile job and ringing behave as designed), closing the rest of CR-01 and WR-05.
|
||||
- useCall.ts: after the livekit-client import, return when stale (no Room is created); after `connect` resolves, when stale disconnect that Room (disconnect(true), errors swallowed) and return; check staleness before each of setCameraEnabled and setMicrophoneEnabled, and after the camera, so a leave between them disconnects and skips the microphone; the Disconnected handler and finish() keep working for the current attempt only. On a connect failure: dispatch error, disconnect, then ask `client.status(conversationId)`; post end when at most one participant has status joined, else leave; on a status error post end for a start and leave for a join. Remove nothing else (tiles, declined, audio, reconnecting stay as they are).
|
||||
- tests/useCall.test.ts: the behavior block's tests; keep the fakes, extend them only where a deferred is needed.
|
||||
- README.md: "The call flow" says Leave works at any moment and what is posted when, the WR-05 rule, and Testing lists the new tests.
|
||||
- Commit in vue-chatvideo-layer: `fix: a call left at any moment stays left, and a failed connect ends an empty session`.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chatvideo-layer test</automated>
|
||||
<fails_when>Non-zero exit: any behavior-block test fails (media published after a leave, a second Room, a stale branch posting the wrong call, WR-05 posting leave for an empty session) or an existing test breaks.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -cE "test\('(unmount while join is pending|leave while connect is pending|leave between camera and microphone|a second begin while the first join is pending)" ../vue-chatvideo-layer/tests/useCall.test.ts` prints 4.
|
||||
- `grep -c 'a failed connect ends a session nobody else joined' ../vue-chatvideo-layer/tests/useCall.test.ts` prints 1.
|
||||
</acceptance_criteria>
|
||||
<done>Whatever the moment a user leaves or navigates away, the camera and microphone stay off and the session is closed the right way, and a call that could not connect does not keep ringing.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: The call page asks before it starts media, unless the user just clicked the call button or Accept</name>
|
||||
<files>../vue-chatvideo-layer/app/lib/videoClient.ts, ../vue-chatvideo-layer/app/components/Chatvideo/Call.vue, ../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue, ../vue-chatvideo-layer/app/assets/css/chatvideo-base.css, ../vue-chatvideo-layer/i18n/locales/en.json, ../vue-chatvideo-layer/i18n/locales/pl.json, ../vue-chatvideo-layer/tests/videoClient.test.ts, ../vue-chatvideo-layer/README.md</files>
|
||||
<read_first>app/lib/videoClient.ts (the handoff block: HANDOFF_MS, rememberStart, takeStart), app/components/Chatvideo/Call.vue, CallButton.vue, IncomingCall.vue, app/assets/css/chatvideo-base.css (button and note styles), i18n/locales/en.json and pl.json, tests/videoClient.test.ts (the handoff tests), README.md (Usage, Components, "The call flow"), ../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue and app/pages/chat.vue (how the demo passes start and callPath; read only), 20-REVIEW.md WR-04</read_first>
|
||||
<behavior>
|
||||
- callAutostart(id, true) is false on a direct load; true right after rememberStart(id, …) within a minute, and begin's takeStart still receives that answer (hasStart does not take it); false after a minute; false for another conversation.
|
||||
- callAutostart(id, false) is false on a direct load; true once right after rememberAccept(id) within a minute, then false (taken); false after a minute; false for another conversation; a start handoff does not make a join autostart.
|
||||
- takeStart behaves as before (the existing handoff tests stay).
|
||||
</behavior>
|
||||
<action>Per D-11, D-13 and D-23, closing WR-04.
|
||||
- app/lib/videoClient.ts: add `hasStart(conversationId, now?)` (a start answer younger than HANDOFF_MS is waiting; not taken), `rememberAccept(conversationId, now?)` and `takeAccept(conversationId, now?)` (an Accept marker, a minute, taken once; in memory, never in a URL or storage), and `callAutostart(conversationId, start, now?)` (start: hasStart; join: takeAccept). Doc comments say why: a link can open the call route but cannot create a handoff.
|
||||
- IncomingCall.vue: accept() calls rememberAccept for the conversation before it navigates.
|
||||
- Call.vue: on mount, begin only when callAutostart answers true; otherwise the idle state renders a confirmation block (class `chatvideo-confirm`) with the text chatvideo.confirm.start or chatvideo.confirm.join and one button (classes `chatvideo-button chatvideo-confirm__go`, label chatvideo.action.startCall or chatvideo.action.joinCall) that calls begin(start), plus the back link when backPath is set. Live, ended and failed states render as today; Retry stays an explicit click. Update the component's header comment (media starts only after a click on this page, the call button or Accept).
|
||||
- Locales en and pl: confirm.start, confirm.join (each says the camera and microphone turn on after the click), action.startCall, action.joinCall. chatvideo-base.css: the confirm block in the existing card and button style.
|
||||
- tests/videoClient.test.ts: the behavior block.
|
||||
- README.md: Components (ChatvideoCall's confirmation; `start` picks Start or Join), "The call flow" (autostart only after the call button or Accept; a direct load or a link asks), API reference (hasStart, rememberAccept, takeAccept, callAutostart), Usage (the ?start=1 example now only selects Start), Testing.
|
||||
- Commit in vue-chatvideo-layer: `feat: the call page asks before it starts the camera and microphone`.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chatvideo-layer test && pnpm --dir ../vue-chatvideo-layer run build:playground</automated>
|
||||
<fails_when>Non-zero exit: a handoff test fails (a direct load autostarts, Accept does not, hasStart takes the answer, a marker outlives a minute or crosses conversations), an earlier test breaks, or the playground build fails to compile Call.vue or IncomingCall.vue.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'callAutostart' ../vue-chatvideo-layer/app/components/Chatvideo/Call.vue` prints at least 1 and `grep -c 'rememberAccept' ../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue` prints at least 1.
|
||||
- `node -e "for (const l of ['en','pl']) { const c = require('../vue-chatvideo-layer/i18n/locales/' + l + '.json').chatvideo; if (!c.confirm?.start || !c.confirm?.join || !c.action?.startCall || !c.action?.joinCall) process.exit(1) }"` exits 0.
|
||||
- `grep -rniE 'golem15\.demo|sm-demo|demo\.summercms' ../vue-chatvideo-layer/app ../vue-chatvideo-layer/README.md | wc -l` prints 0.
|
||||
</acceptance_criteria>
|
||||
<done>Opening a call link shows a clear Start call or Join call button and nothing turns on until it is clicked, while the call button and Accept still go straight into the call.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 4: The chat renders deceptive link hosts as text, never as a link or a link card</name>
|
||||
<files>../vue-chat-layer/app/lib/urlGuard.ts, ../vue-chat-layer/app/lib/urlGuard.test.ts, ../vue-chat-layer/app/lib/markdown.ts, ../vue-chat-layer/app/lib/linkEmbeds.ts, ../vue-chat-layer/app/lib/linkEmbeds.test.ts, ../vue-chat-layer/README.md</files>
|
||||
<read_first>../vue-chat-layer/app/lib/markdown.ts, app/lib/chatText.ts (LINK_RE, URL_RE, how safeUrl is used), app/lib/linkEmbeds.ts, app/lib/linkEmbeds.test.ts, app/components/Chat/LinkEmbed.vue, README.md (link embeds section, Testing), 20-REVIEW.md CR-02 (the table and the rendering paragraph)</read_first>
|
||||
<behavior>
|
||||
- honestHttpUrl refuses (returns null): https://bit%2Ely/x, https://bit.l%79/x, https://bit.ly/x, https://bit。ly/x, https://bit.ly/x, https://bit。ly/x, https://user@bit.ly/x, https://example.com@bit.ly/, https:/\bit.ly/x, https://\bit.ly/x, https://bit.ly./x, javascript: and data: URLs, and anything new URL cannot parse.
|
||||
- honestHttpUrl accepts: https://bit.ly/x, http://example.com:8080/a?b=c#d, https://żółw.example/ (an IDN written in Unicode), https://xn--w-uga1v8h.example/, https://sub.example.org/path.
|
||||
- renderChatText of each refused URL, bare and as [label](url), contains no anchor (the text shows as written, escaped); messageUrls of a text holding them returns none; linkify leaves them as text. The accepted URLs still render as links and still yield cards.
|
||||
- bm's copied tests (chatEvents, chatFormat, chatText, chatUnread, realtime) pass byte-identical.
|
||||
</behavior>
|
||||
<action>Per D-02 (generic link embeds) and D-17, the client half of CR-02.
|
||||
- app/lib/urlGuard.ts (new): `honestHttpUrl(raw: string): URL | null`. The URL must parse with new URL as http or https, and the scheme must be followed by exactly two slashes. The authority as written, up to the first slash, question mark or hash, must hold no percent sign, no at sign and no backslash. The host as written must hold none of U+3002, U+FF0E and U+FF61, must be unchanged by NFKC (no fullwidth or compatibility characters), and must not end with a dot. Its lower-cased form must equal url.hostname, or, for a host with non-ASCII letters, it must be in NFC with only U+002E as the separator. Doc comment: the chat links and embeds only URLs whose written host is the host the browser opens, so a card never shows a host the text does not.
|
||||
- markdown.ts: safeUrl allows an http(s) target only when honestHttpUrl accepts it (mailto, site paths and anchors unchanged). linkEmbeds.ts: parseHttp delegates to honestHttpUrl, so linkify and messageUrls skip deceptive URLs.
|
||||
- app/lib/urlGuard.test.ts (new): the behavior block, including renderChatText cases (import it from ./chatText). linkEmbeds.test.ts: messageUrls and linkify cases for two refused and two accepted URLs.
|
||||
- README.md: the link embeds section describes the guard; Testing lists urlGuard.test.ts.
|
||||
- Commit in vue-chat-layer: `fix: deceptive link hosts render as text, not links or cards`.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chat-layer test && git -C ../vue-chat-layer diff --quiet b6d3389 -- app/lib/chatEvents.test.ts app/lib/chatFormat.test.ts app/lib/chatText.test.ts app/lib/chatUnread.test.ts app/lib/realtime.test.ts</automated>
|
||||
<fails_when>Non-zero exit: a guard test fails (a deceptive URL becomes an anchor or a card, an honest or IDN URL stops linking), a store, client or embed test breaks, or one of bm's copied test files was edited.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'honestHttpUrl' ../vue-chat-layer/app/lib/markdown.ts` and `grep -c 'honestHttpUrl' ../vue-chat-layer/app/lib/linkEmbeds.ts` each print at least 1.
|
||||
- `grep -rniE 'golem15\.demo|sm-demo|demo\.summercms' ../vue-chat-layer/app ../vue-chat-layer/README.md | wc -l` prints 0.
|
||||
</acceptance_criteria>
|
||||
<done>A message can no longer show a working link or a link card to a host it hides behind escapes, dots or userinfo; honest links work as before.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 5: Logging out resets the chat, closes the realtime socket and clears a ringing call in the same tab</name>
|
||||
<files>../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts, ../sm-demo-app/vue-demo-app/app/utils/communityAuth.test.ts, ../sm-demo-app/vue-demo-app/app/plugins/auth.ts, ../sm-demo-app/vue-demo-app/app/composables/useDemoAuth.ts</files>
|
||||
<read_first>../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts and communityAuth.test.ts (whole files), app/plugins/auth.ts, app/composables/useDemoAuth.ts (whole file), app/components/SiteHeader.vue and app/pages/login.vue (their logout calls), app/lib/realtime.ts (the re-export), app/layouts/default.vue, vitest.config.ts, ../vue-chat-layer/app/composables/useChat.ts (reset, lines around 1514) and app/lib/realtime.ts (disconnect), ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts (dismiss), 20-REVIEW.md WR-01</read_first>
|
||||
<behavior>
|
||||
- createCommunitySignOut({resetChat, disconnectRealtime, dismissCall}) runs the three in that order; a part that throws does not stop the next ones; calling it twice is safe.
|
||||
- createChatAuth(store, fetch, onSignedOut): unauthorized() clears the token, then calls onSignedOut once; without onSignedOut it behaves as before (the existing tests pass unchanged).
|
||||
- endSession(token, postLogout, clearToken, signOut): with a token it posts logout with that token, clears the token even when the post rejects, then signs out once; without a token it posts nothing and still clears and signs out.
|
||||
</behavior>
|
||||
<action>Per D-04 (no chat for a signed-out visitor), closing WR-01.
|
||||
- app/utils/communityAuth.ts: add `createCommunitySignOut(parts)` and `endSession(token, postLogout, clearToken, signOut)` (Nuxt-free, doc comments), and an optional third parameter `onSignedOut` on `createChatAuth`, called by unauthorized() after the token is cleared. Update the file header.
|
||||
- app/plugins/auth.ts: take the nuxtApp argument; build the sign-out with createCommunitySignOut whose parts run only in the browser: resetChat runs useChat().reset() inside nuxtApp.runWithContext, disconnectRealtime calls disconnect from ~/lib/realtime, dismissCall runs useIncomingCalls().dismiss() inside nuxtApp.runWithContext. Pass it to createChatAuth and provide it as `communitySignOut`. Update the header comment.
|
||||
- app/composables/useDemoAuth.ts: read `$communitySignOut` from useNuxtApp() when the composable is created (before any await, so the Nuxt context is still there), and make logout() delegate to endSession with the current token, the existing logout POST, a clear that sets the token to null, and that sign-out. SiteHeader.vue and login.vue keep calling logout() unchanged.
|
||||
- app/utils/communityAuth.test.ts: the behavior block, next to the existing tests.
|
||||
- Commit in vue-demo-app only (not pushed; the sm-demo-app gitlink is bumped in 20-09): `fix: logging out resets the chat, closes the realtime socket and clears a ringing call`.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../sm-demo-app/vue-demo-app test && pnpm --dir ../sm-demo-app/vue-demo-app run build</automated>
|
||||
<fails_when>Non-zero exit: a sign-out or endSession test fails, an existing auth hook test breaks, or the site build fails (a missing auto-import or a layer API that v0.1.0 does not export).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'createCommunitySignOut' ../sm-demo-app/vue-demo-app/app/plugins/auth.ts` prints at least 1 and `grep -c 'endSession' ../sm-demo-app/vue-demo-app/app/composables/useDemoAuth.ts` prints at least 1.
|
||||
- `git -C ../sm-demo-app/vue-demo-app diff --stat deb809f -- package.json pnpm-lock.yaml app/components/SiteHeader.vue` prints nothing.
|
||||
- `git -C ../sm-demo-app status --porcelain -- vue-demo-app` prints ` M vue-demo-app` (the gitlink moved, not staged; 20-09 commits the bump).
|
||||
</acceptance_criteria>
|
||||
<done>After logout nothing of the previous member stays in the tab: no chat state, no open socket, no ringing prompt, and the next member starts clean.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| browser camera and microphone to LiveKit | media leaves the device once a Room is connected and tracks are published |
|
||||
| chat links to the call route | any member can post a same-site link to /call/{id} |
|
||||
| chat text to rendered links and cards | member-written URLs become anchors and cards |
|
||||
| one browser tab, two accounts | the previous member's state must not reach the next one |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-42 | Information disclosure | useCall (camera and microphone after leave) | critical | mitigate | per-attempt token checked after every await; leave invalidates it; a stale branch disconnects any Room and never calls the media setters; useCall tests pin each moment (start, join, import, connect, between camera and microphone, unmount, second begin) |
|
||||
| T-20-43 | Elevation of privilege | /call/{id} opened from a link | high | mitigate | media starts on mount only with an in-memory handoff a link cannot create (call button start answer, Accept marker, a minute, taken once); otherwise the confirmation waits for a click; callAutostart tests |
|
||||
| T-20-44 | Information disclosure | chat store, realtime socket and call prompt after logout | high | mitigate | logout and unauthorized run the community sign-out (reset, disconnect, dismiss), each part isolated; communityAuth tests; 20-09 adds a browser check that the socket closes |
|
||||
| T-20-45 | Denial of service | empty ringing session after a failed connect | medium | mitigate | the failed-connect branch ends the session when GET status shows nobody else joined; tests for both outcomes and for an unreadable status |
|
||||
| T-20-46 | Spoofing | deceptive hosts in chat anchors and link cards | high | mitigate | honestHttpUrl refuses escapes, userinfo, backslashes, compatibility dots and letters, trailing dots and malformed scheme separators before safeUrl, linkify or messageUrls produce a link or card; urlGuard tests |
|
||||
| T-20-SC | Tampering | npm installs | high | mitigate | no package or lockfile change in this plan; acceptance checks the layer manifests are untouched |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: vue-chatvideo-layer tests with the caller leave-during-start test.
|
||||
- Task 2: the remaining CR-01 moments and WR-05 under test.
|
||||
- Task 3: handoff tests and the playground build compiling the changed components.
|
||||
- Task 4: vue-chat-layer tests with the guard, bm's copied tests untouched.
|
||||
- Task 5: vue-demo-app tests and build on the v0.1.0 pins.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
CR-01, WR-01, WR-04, WR-05 and the client half of CR-02 are fixed in the repositories that own the code, each with regression tests; nothing is pushed, tagged or re-pinned, so 20-09 can run the full suites, integrate the unreleased layers locally and release them.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-08-SUMMARY.md` when done: the commits per repo, the new tests per finding, the changed expectation of the failed-connect test, the new layer exports (hasStart, rememberAccept, takeAccept, callAutostart, honestHttpUrl) and class names (chatvideo-confirm, chatvideo-confirm__go) that 20-09's browser checks use.
|
||||
</output>
|
||||
@@ -0,0 +1,253 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 08
|
||||
subsystem: chat-video-frontend
|
||||
tags: [vue, nuxt, livekit, vitest, chat, video, auth, gap-closure]
|
||||
status: complete
|
||||
gap_closure: true
|
||||
review_findings: [CR-01, WR-01, WR-04, WR-05, CR-02]
|
||||
|
||||
requires:
|
||||
- phase: 20-06
|
||||
provides: "useCall on a fake Room, the chat layer's tests, the community auth hooks and their tests"
|
||||
provides:
|
||||
- "useCall: a per-attempt token with stale checks after every await; leave works and is final at any moment"
|
||||
- "useCall: a failed connect (or livekit-client import) ends a session nobody else joined (GET status)"
|
||||
- "videoClient: hasStart, rememberAccept, takeAccept, callAutostart (click handoffs)"
|
||||
- "ChatvideoCall: confirmation (chatvideo-confirm, chatvideo-confirm__go) unless the call button or Accept just handed over"
|
||||
- "vue-chat-layer: honestHttpUrl (app/lib/urlGuard.ts), used by safeUrl, linkify and messageUrls"
|
||||
- "vue-demo-app: createCommunitySignOut and endSession; logout and unauthorized() reset the chat, close the socket and dismiss the ring"
|
||||
affects: [20-09]
|
||||
|
||||
actuals:
|
||||
tokens: 16745 # chars/4 over the three repos' diffs (8222255..HEAD, b6d3389..HEAD, deb809f..HEAD)
|
||||
tasks: 5
|
||||
commits: 5 # measured per repo: vue-chatvideo-layer 3, vue-chat-layer 1, vue-demo-app 1; none in summercms.go
|
||||
plan_head_before: "vue-chatvideo-layer 8222255, vue-chat-layer b6d3389, vue-demo-app deb809f"
|
||||
plan_head_after: "vue-chatvideo-layer 5386903, vue-chat-layer a798bb1, vue-demo-app 188ae25"
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Per-attempt object ({start, answered, left}) plus a stale() closure checked after every await of an async lifecycle"
|
||||
- "In-memory click handoffs (a minute, taken once) as proof of user intent before media starts"
|
||||
- "A written-host-equals-opened-host guard before any anchor or link card is produced"
|
||||
- "A Nuxt-free sign-out factory whose parts run isolated, wired by the plugin with runWithContext"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../vue-chat-layer/app/lib/urlGuard.ts
|
||||
- ../vue-chat-layer/app/lib/urlGuard.test.ts
|
||||
modified:
|
||||
- ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- ../vue-chatvideo-layer/app/lib/videoClient.ts
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/Call.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue
|
||||
- ../vue-chatvideo-layer/app/assets/css/chatvideo-base.css
|
||||
- ../vue-chatvideo-layer/i18n/locales/en.json
|
||||
- ../vue-chatvideo-layer/i18n/locales/pl.json
|
||||
- ../vue-chatvideo-layer/tests/useCall.test.ts
|
||||
- ../vue-chatvideo-layer/tests/videoClient.test.ts
|
||||
- ../vue-chatvideo-layer/README.md
|
||||
- ../vue-chat-layer/app/lib/markdown.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.test.ts
|
||||
- ../vue-chat-layer/README.md
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.test.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/composables/useDemoAuth.ts
|
||||
|
||||
key-decisions:
|
||||
- "A stale start or join answer closes its session (end for the caller, leave for the callee) only when no newer attempt replaced it; a newer attempt owns the session"
|
||||
- "leave() before the call connects posts end for the caller and leave for the callee (not the room-based alone rule), and only once the attempt has its answer"
|
||||
- "WR-05 uses the server's view: GET status, end when at most one participant is joined; unreadable status (null, undefined, rejection) falls back to end for the caller and leave for the callee. The same rule applies to a failed livekit-client import"
|
||||
- "callAutostart: start needs a waiting start answer (hasStart, left for begin to take); join takes an Accept marker. ?start=1 only chooses Start call over Join call"
|
||||
- "honestHttpUrl also refuses invisible characters (Default_Ignorable_Code_Point, Cf) in a host, which the Unicode-host branch would otherwise accept"
|
||||
|
||||
patterns-established:
|
||||
- "Leaving at every await of begin() is a test: deferred promises for start, join, connect and the camera setter, and a gated vi.doMock of livekit-client for the import"
|
||||
|
||||
requirements-completed: [SC-2, D-02, D-04, D-11, D-13, D-17, D-23]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "CR-01: leaving or unmounting at any moment of a call attempt never connects a Room or turns on media afterwards"
|
||||
requirement: D-13
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../vue-chatvideo-layer/tests/useCall.test.ts (leave while start is pending; unmount while join is pending; leave while livekit-client loads; leave while connect is pending; a connect that fails after a leave posts nothing more; leave between camera and microphone; a second begin while the first join is pending)"
|
||||
status: pass
|
||||
- id: D2
|
||||
description: "WR-05: a failed connect ends a session nobody else joined, else leaves"
|
||||
requirement: D-13
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../vue-chatvideo-layer/tests/useCall.test.ts (a failed LiveKit connect fails the call; an unreadable status ends the starter's session; a failed connect ends a session nobody else joined; a failed connect leaves when the other side joined; a failed connect with an unreadable status: the starter ends, the callee leaves)"
|
||||
status: pass
|
||||
- id: D3
|
||||
description: "WR-04: the call page asks before media unless the call button or Accept just handed over"
|
||||
requirement: D-11
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../vue-chatvideo-layer/tests/videoClient.test.ts (describe call autostart)"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "pnpm --dir ../vue-chatvideo-layer run build:playground (Call.vue and IncomingCall.vue compile)"
|
||||
status: pass
|
||||
- id: D4
|
||||
description: "CR-02 client side: deceptive link hosts render as text, never as a link or a card"
|
||||
requirement: D-17
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../vue-chat-layer/app/lib/urlGuard.test.ts; ../vue-chat-layer/app/lib/linkEmbeds.test.ts"
|
||||
status: pass
|
||||
- id: D5
|
||||
description: "WR-01: logout and unauthorized() reset the chat, close the socket and dismiss the ring"
|
||||
requirement: D-04
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "../sm-demo-app/vue-demo-app/app/utils/communityAuth.test.ts (createChatAuth with a sign-out, createCommunitySignOut, endSession)"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "pnpm --dir ../sm-demo-app/vue-demo-app run build on the v0.1.0 pins"
|
||||
status: pass
|
||||
|
||||
duration: 14min
|
||||
completed: 2026-11-02
|
||||
---
|
||||
|
||||
# Phase 20 Plan 08: Call and session fixes Summary
|
||||
|
||||
**Leaving a call is now final at any await of the attempt (per-attempt token with stale checks), a failed connect ends an empty session from GET status, the call page asks before media unless the call button or Accept handed over in memory, the chat renders deceptive link hosts as text through `honestHttpUrl`, and logout resets the chat, the realtime socket and the ring in the same tab.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** about 14 min
|
||||
- **Started:** 2026-11-02T17:25:39Z
|
||||
- **Completed:** 2026-11-02T17:39:00Z
|
||||
- **Tasks:** 5 of 5
|
||||
- **Files modified:** 20 (2 created) across three repositories
|
||||
|
||||
## Commits per repository
|
||||
|
||||
Nothing was pushed or tagged. vue-demo-app keeps its v0.1.0 layer pins. The sm-demo-app gitlink moved but is not staged (` M vue-demo-app`); 20-09 bumps it.
|
||||
|
||||
| Repo | Hash | Subject |
|
||||
|------|------|---------|
|
||||
| ../vue-chatvideo-layer | 69e8b83 | fix: leaving while a call starts never connects it |
|
||||
| ../vue-chatvideo-layer | 27ad81c | fix: a call left at any moment stays left, and a failed connect ends an empty session |
|
||||
| ../vue-chatvideo-layer | 5386903 | feat: the call page asks before it starts the camera and microphone |
|
||||
| ../vue-chat-layer | a798bb1 | fix: deceptive link hosts render as text, not links or cards |
|
||||
| ../sm-demo-app/vue-demo-app | 188ae25 | fix: logging out resets the chat, closes the realtime socket and clears a ringing call |
|
||||
|
||||
## Test results
|
||||
|
||||
| Suite | Before | After |
|
||||
|-------|--------|-------|
|
||||
| vue-chatvideo-layer `pnpm test` | 114 | 127 passed (3 files) |
|
||||
| vue-chat-layer `pnpm test` | 146 | 215 passed (10 files) |
|
||||
| vue-demo-app `pnpm test` | 218 | 225 passed (18 files) |
|
||||
|
||||
- `pnpm --dir ../vue-chatvideo-layer run build:playground` passed. So did `pnpm --dir ../vue-chat-layer run build:playground` and `pnpm --dir ../sm-demo-app/vue-demo-app run build` (v0.1.0 pins). In the built bundle, the plugin calls the resolved `useChat().reset()`, `disconnect()` and `useIncomingCalls().dismiss()`.
|
||||
- The SPA's copied chat tests (chatEvents, chatFormat, chatText, chatUnread, realtime) are byte-identical to b6d3389 (`git diff --quiet` exit 0).
|
||||
- No package.json or lockfile changed in any repo. Neither layer names an application (grep count 0).
|
||||
|
||||
## New tests per finding
|
||||
|
||||
- **CR-01** (useCall.test.ts):
|
||||
- leave while start is pending: no room, no media, end once the session exists (Task 1, red first)
|
||||
- unmount while join is pending: no room, no media, leave once the session exists
|
||||
- leave while connect is pending: no media, the Room disconnected, end once
|
||||
- a connect that fails after a leave posts nothing more
|
||||
- leave between camera and microphone: the microphone stays off, the Room disconnected
|
||||
- a second begin while the first join is pending creates no second Room
|
||||
- leave while livekit-client loads: no Room after the leave, end once. This one stalls the import itself. `vi.resetModules()` plus `vi.doMock('livekit-client')` with an async factory gated on a deferred, then a fresh import of useCall; the `finally` restores the plain fake. The test is last in the file, and five consecutive runs were stable.
|
||||
- **WR-05** (useCall.test.ts): a failed connect ends a session nobody else joined; a failed connect leaves when the other side joined; a failed connect with an unreadable status: the starter ends, the callee leaves.
|
||||
- **Changed expectation:** the old test "a failed LiveKit connect fails the call and leaves the session" is now "a failed LiveKit connect fails the call; an unreadable status ends the starter's session". The stub's `status` answers undefined, which counts as unreadable, so the starter posts `end`, not `leave`. Every other expectation stays.
|
||||
- **WR-04** (videoClient.test.ts, `describe('call autostart')`):
|
||||
- a start begins on mount only with the call button's answer, which begin still takes
|
||||
- a join begins on mount only once, right after Accept
|
||||
- a start answer does not make a join begin, nor an Accept a start
|
||||
- **CR-02 client** (urlGuard.test.ts, new):
|
||||
- `honestHttpUrl` refuses 16 deceptive forms. These are the review's table plus `https:///`, `https:bit.ly`, soft hyphen, ZWSP and `0x7f.1`, along with other schemes and unparseable input.
|
||||
- It accepts 8 honest forms: a port with query and fragment, an IDN in Unicode and in punycode, a subdomain, upper case, `@` in the path, and `%` in the query.
|
||||
- `renderChatText` (bare and `[label](url)`), `safeUrl`, `messageUrls` and `linkify` behave on both sets.
|
||||
- linkEmbeds.test.ts has two new cases.
|
||||
- **WR-01** (communityAuth.test.ts): unauthorized clears the token, then signs out once. createCommunitySignOut runs its parts in order, keeps going when a part throws, and is safe to call twice. endSession posts then clears then signs out, clears and signs out when the post rejects, and posts nothing without a token.
|
||||
|
||||
## For 20-09 (browser checks and release)
|
||||
|
||||
- **Layer exports added:** vue-chatvideo-layer `app/lib/videoClient.ts`: `hasStart`, `rememberAccept`, `takeAccept`, `callAutostart`. vue-chat-layer `app/lib/urlGuard.ts`: `honestHttpUrl`. vue-demo-app `app/utils/communityAuth.ts`: `createCommunitySignOut`, `endSession`, and an optional third parameter `onSignedOut` on `createChatAuth`. The plugin provides `$communitySignOut`.
|
||||
- **Class names:** `.chatvideo-confirm` (the confirmation block), `.chatvideo-confirm__go` (Start call / Join call button), `.chatvideo-confirm__text`, `.chatvideo-confirm__back` (the back link when `backPath` is set).
|
||||
- **Locale keys:** `chatvideo.confirm.start`, `chatvideo.confirm.join`, `chatvideo.action.startCall` (en "Start call", pl "Rozpocznij rozmowę"), `chatvideo.action.joinCall` (en "Join call", pl "Dołącz do rozmowy").
|
||||
- **Browser-visible behaviour changes once the pins move:**
|
||||
- A direct load of `/call/{id}` or `/call/{id}?start=1` shows the confirmation and posts nothing until the click.
|
||||
- The DM call button (start handoff) and the incoming prompt's Accept still go straight in.
|
||||
- The callee's status now passes through `starting` before `connecting`; both render "Connecting…".
|
||||
- Existing browser checks that load `/call/{id}?start=1` directly and expect media must click `.chatvideo-confirm__go` first.
|
||||
- **Demo call page doc comment** (`vue-demo-app/app/pages/call/[conversation].vue`) still says "With ?start=1 … it starts the call". Per the plan it is updated with the pin bump in 20-09.
|
||||
- **New layer tags:** each layer needs one (main is ahead of v0.1.0: chatvideo 3 commits, chat 1 commit on top of the 2 already after the tag) before vue-demo-app can pin them.
|
||||
|
||||
## Decisions Made
|
||||
|
||||
See key-decisions in the frontmatter. In short:
|
||||
- **Stale answer:** it closes its session only when it is still the current attempt.
|
||||
- **Leave before connect:** the caller posts end and the callee posts leave, and only once the answer has arrived.
|
||||
- **WR-05:** the rule follows GET status, with a fallback by role when the status cannot be read.
|
||||
- **Autostart:** a start needs the waiting start answer; a join takes the Accept marker.
|
||||
- **Invisible characters:** hosts containing them are refused.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - Missing critical] Session-channel handle closed when the attempt goes stale while subscribing**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** `openChannel` set `channel` after `await subscribe`. A leave during the subscribe left the handle open (the review's "the channel handle leaks"). A stale attempt's publications could still call `finish`.
|
||||
- **Fix:** `openChannel(sessionId, stale)` closes the handle when the attempt is stale on arrival, and ignores publications for a stale attempt.
|
||||
- **Files modified:** ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- **Commit:** 27ad81c
|
||||
|
||||
**2. [Rule 1 - Bug] A failed livekit-client import left the session ringing, like a failed connect**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** WR-05's cause also applied to the import-failure branch, which only disconnected.
|
||||
- **Fix:** That branch now uses the same `closeFailed` (GET status) rule.
|
||||
- **Files modified:** ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- **Commit:** 27ad81c
|
||||
|
||||
**3. [Rule 2 - Missing critical] Invisible characters in a Unicode host**
|
||||
- **Found during:** Task 4
|
||||
- **Issue:** The plan's Unicode-host branch (NFC, only U+002E separators) accepted `https://bit.l\u00ady/x`, which displays as and opens `bit.ly`. A soft hyphen or ZWSP is dropped by the URL parser.
|
||||
- **Fix:** `honestHttpUrl` refuses hosts containing `\p{Default_Ignorable_Code_Point}` or `\p{Cf}`. Both forms are under test.
|
||||
- **Files modified:** ../vue-chat-layer/app/lib/urlGuard.ts, ../vue-chat-layer/app/lib/urlGuard.test.ts
|
||||
- **Commit:** a798bb1
|
||||
|
||||
**4. [Rule 1 - Bug] leave() before connect no longer ends the caller's call from the callee side**
|
||||
- **Found during:** Task 1
|
||||
- **Issue:** The old rule `alone = !room || room.remoteParticipants.size === 0` made a callee who left while connecting post `end`, which ended the waiting caller's call.
|
||||
- **Fix:** Before `connected`, the caller posts end and the callee leave, as the plan's truth states. Once connected, the room-based last-one-out rule still applies.
|
||||
- **Files modified:** ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- **Commit:** 69e8b83
|
||||
|
||||
### Other notes
|
||||
|
||||
- The `leave while livekit-client loads` test stalls the dynamic import itself (the preferred variant in the plan), not the same-tick fallback.
|
||||
- **Not done here, per the plan:** IN-07 (the handle race between two pending incoming subscribes) stays deferred. The demo's call page comment waits for 20-09.
|
||||
|
||||
## Deferred Issues
|
||||
|
||||
- `tsc --noEmit -p .nuxt/tsconfig.app.json` in vue-demo-app reports a type error at `app/plugins/auth.ts` on the `fetchJson` line (`$fetch(url, opts)` with `method?: string`). The line was there before this plan (it is line 20 at deb809f) and does not affect the build. Out of scope.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None. The changes close T-20-42 to T-20-46 and add no new endpoint, auth path or storage.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: ../vue-chat-layer/app/lib/urlGuard.ts, ../vue-chat-layer/app/lib/urlGuard.test.ts
|
||||
- FOUND commits: 69e8b83, 27ad81c, 5386903 (vue-chatvideo-layer), a798bb1 (vue-chat-layer), 188ae25 (vue-demo-app)
|
||||
@@ -0,0 +1,552 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
plan: 09
|
||||
type: execute
|
||||
wave: 8
|
||||
depends_on: ["20-07", "20-08"]
|
||||
gap_closure: true
|
||||
review_findings: [CR-01, CR-02, CR-03, WR-01, WR-04, WR-05]
|
||||
files_modified:
|
||||
- ../vue-chat-layer/package.json
|
||||
- ../vue-chatvideo-layer/package.json
|
||||
- ../sm-demo-app/scripts/check-moderation.sh
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/check-chat.cjs
|
||||
- ../sm-demo-app/scripts/check-all.sh
|
||||
- ../sm-demo-app/README.md
|
||||
- ../sm-demo-app/DEPLOY.md
|
||||
- ../sm-demo-app/go.mod
|
||||
- ../sm-demo-app/go.sum
|
||||
- ../sm-demo-app/plugins/golem15/moderation
|
||||
- ../sm-demo-app/plugins/golem15/forum
|
||||
- ../sm-demo-app/plugins/demo/moderation.go
|
||||
- ../sm-demo-app/moderation_test.go
|
||||
- ../sm-demo-app/plugins/demo/content/ROADMAP.md
|
||||
- ../sm-demo-app/vue-demo-app
|
||||
- ../sm-demo-app/vue-demo-app/package.json
|
||||
- ../sm-demo-app/vue-demo-app/pnpm-lock.yaml
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue
|
||||
- .planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW-DISPOSITION.md
|
||||
- .planning/todos/pending/chatchannels-pin-policy.md
|
||||
- .planning/todos/pending/moderation-profile-group-and-filenames.md
|
||||
- .planning/todos/pending/forum-friends-client-401-refresh.md
|
||||
- .planning/todos/pending/chatvideo-dm-only-host-hook.md
|
||||
- .planning/todos/pending/chatvideo-live-membership.md
|
||||
- .planning/todos/pending/check-local-jwt-out-of-argv.md
|
||||
- .planning/todos/pending/chat-slash-text-escape.md
|
||||
- .planning/todos/pending/demo-seed-moderation-lists-once.md
|
||||
- .planning/todos/pending/demo-nginx-livekit-rtc-only.md
|
||||
- .planning/todos/pending/chatvideo-incoming-handle-leak.md
|
||||
- .planning/todos/pending/demo-vapid-runbook-pipefail.md
|
||||
- .planning/todos/pending/demo-chat-members-read-only.md
|
||||
autonomous: false
|
||||
requirements: [SC-2, SC-3, SC-4, D-10, D-13, D-17, D-18]
|
||||
estimate:
|
||||
tokens: 340000
|
||||
raw_tokens: 340000
|
||||
tasks: 12
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-4: before anything is pushed, the full suites pass in every repository the gap round touched: sm-moderation-plugin and sm-forum-plugin (go vet, go test ./... with Docker), vue-chat-layer and vue-chatvideo-layer (vitest and the playground build), vue-demo-app (vitest and the Nuxt build) and sm-demo-app (go vet, go test ./... with Docker)."
|
||||
- "Before any tag, the unreleased fixes run together in the local demo (the sibling plugin checkouts through a scratch go.work, the local layers as packed tarballs, both temporary and reverted): check-local moderation, chat, chatlive and callmedia pass, so a one-way tag never ships an untested combination."
|
||||
- "After the Task 3 go-ahead: annotated tags exist on origin at the default branch's head, each containing the earlier tags. sm-moderation-plugin gets the next patch after v0.1.0 (v0.1.1), sm-forum-plugin after v0.1.1 (v0.1.2), and vue-chat-layer and vue-chatvideo-layer after v0.1.0 (v0.1.1 each). For each, `git ls-remote origin refs/tags/<tag>^{}` equals the pushed HEAD."
|
||||
- "sm-demo-app requires the new moderation and forum tags (go.mod and go.sum, submodules checked out at the tags, check-pins ok, one `chore: bump` commit per plugin), its forum listener also checks the rendered post (PostSaving.HTML through CheckHTML), and TestDemoModeration refuses every reviewer probe through HTTP on chat send, reply and edit and on forum thread, reply and edit, with nothing stored. vue-demo-app pins both layers at their new tags."
|
||||
- "check-moderation.sh refuses every reviewer probe in chat and forum with 422 under the right field, after a plain control word is refused (so changed lists cannot pass silently), and leaves nothing behind. check-chat.cjs --call shows the confirmation on a direct /call load with no LiveKit connection before the click, then completes the DM call. check-chat.cjs's default mode shows that logout closes the realtime socket."
|
||||
- "SC-3, after the Task 7 go-ahead: rome runs the new binary and site through DEPLOY.md's Upload and Release. Only summercms-demo and summercms-demo-site restart, check-live prints `check-live: ok`, and bin/demo.prev and site/.output.prev are kept for a rollback."
|
||||
- "SC-2, D-17 on the live site: with the user's live tokens, the bypass probe passes against https://demo.summercms.io and the call probe completes a DM call there with the confirmation step. Without tokens the user's own UAT of the same steps is recorded. smoke.sh passes on the deployed artifact."
|
||||
- "After the Task 11 go-ahead, one post per plugin tag (sm-moderation-plugin, sm-forum-plugin) is on https://summercms.io/changelog/plugins, written per CLAUDE.md (user-facing, no planning IDs, no H1). The journal token is never printed or copied."
|
||||
- "20-REVIEW-DISPOSITION.md: CR-01, CR-02, CR-03, WR-01, WR-04 and WR-05 are fixed, with commit refs. WR-02, WR-03, WR-06 and IN-01 to IN-09 are deferred, each pointing at its todo in .planning/todos/pending/ (g15office task id in the frontmatter when the g15office tools answer)."
|
||||
artifacts:
|
||||
- path: "../sm-demo-app/scripts/check-moderation.sh"
|
||||
provides: "the bypass probe for a local or the live demo"
|
||||
contains: "check-moderation: ok"
|
||||
- path: "../sm-demo-app/plugins/demo/moderation.go"
|
||||
provides: "forum listener checking the rendered post"
|
||||
contains: "CheckHTML"
|
||||
- path: ".planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW-DISPOSITION.md"
|
||||
provides: "the closed ledger"
|
||||
contains: "fixed"
|
||||
key_links:
|
||||
- from: "../sm-demo-app/plugins/demo/moderation.go"
|
||||
to: "../sm-forum-plugin/events/events.go"
|
||||
via: "checkPost runs Filter.CheckHTML on ev.HTML after title and body"
|
||||
pattern: "ev\\.HTML"
|
||||
- from: "../sm-demo-app/go.mod"
|
||||
to: "../sm-moderation-plugin"
|
||||
via: "require at the new patch tag"
|
||||
pattern: "sm-moderation-plugin v0\\.1\\.[1-9]"
|
||||
- from: "../sm-demo-app/vue-demo-app/package.json"
|
||||
to: "../vue-chatvideo-layer"
|
||||
via: "git+https pin at the new tag"
|
||||
pattern: "vue-chatvideo-layer.git#v0\\.1\\.[1-9]"
|
||||
prohibitions:
|
||||
- statement: "No push, tag, rome change or changelog post happens before its checkpoint is answered; a tag is never moved or re-pushed; tags go on the default branch only."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "No secret value (JWTs, the journal token, .env values) appears in a command line, a log, a committed file or the SUMMARY; .env files are never read; JWTs reach the scripts through 0600 files or the environment and curl gets the header through a config on stdin."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
- statement: "The temporary integration (scratch go.work, packed layer tarballs) is never committed: vue-demo-app's package.json and pnpm-lock.yaml match their committed state when Task 2 ends."
|
||||
status: unresolved
|
||||
verification: automated
|
||||
- statement: "On rome only summercms-demo and summercms-demo-site restart; nginx, Centrifugo, LiveKit, the firewall and WavePath's programs are untouched."
|
||||
status: unresolved
|
||||
verification: judgment
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
ROADMAP Goal (not in user-story format; no story is invented here): sm-demo-app runs every shared plugin and its public Nuxt site shows them working, deployed publicly with the backend call to action.
|
||||
|
||||
This plan's slice (gap round after the code review, plan 9 of 9, wave 8): it releases 20-07's and 20-08's fixes, redeploys the demo and re-checks it live.
|
||||
- Prove the unreleased fixes together locally.
|
||||
- Tag the four repositories after a go-ahead.
|
||||
- Consume the tags in the demo, including the one listener change that needs them.
|
||||
- Rebuild, redeploy on rome after a go-ahead, and probe the live site for the bypasses and the call flow.
|
||||
- Publish the two plugin changelog posts after a go-ahead.
|
||||
- Close 20-REVIEW-DISPOSITION.md.
|
||||
|
||||
**Unit tests rule for this gap round:** the project rule "unit tests are the last plan of every phase" is met because every fix in 20-07 and 20-08 carries its own regression tests and this plan runs every touched repository's full suite (Task 2) and the demo's whole gate (Task 6) before anything goes live.
|
||||
|
||||
## Decisions taken in this plan (Claude's discretion, recorded)
|
||||
|
||||
- **Versions.** Each tag is the next patch after the latest tag, checked on 2026-11-02 with `git tag --sort=-v:refname` and `git ls-remote --tags origin`:
|
||||
|
||||
| Repo | Latest tag | New tag |
|
||||
|---|---|---|
|
||||
| sm-moderation-plugin | v0.1.0 | v0.1.1 |
|
||||
| sm-forum-plugin | v0.1.1 | v0.1.2 |
|
||||
| vue-chat-layer | v0.1.0 | v0.1.1 |
|
||||
| vue-chatvideo-layer | v0.1.0 | v0.1.1 |
|
||||
|
||||
The brief asked for moderation v0.1.2. No v0.1.1 exists, and skipping one would leave a hole in the series, so the plan proposes v0.1.1 and the Task 3 checkpoint shows the table for the user to confirm or override. Task 2 re-reads the tags, because another session could tag in between.
|
||||
- **Integration before tagging.** Tags are one-way, so Task 1 and Task 2 run the unreleased code together in the local demo. The Go side uses a scratch go.work that maps moderation and forum to the sibling checkouts (GOWORK is respected by dev.sh and build.sh dev). The site side installs the two layers from `pnpm pack` tarballs; unlike link pins, a tarball resolves vue-chat-layer once, as the git tag install will. Both are reverted before the release gate.
|
||||
- **The demo listener change comes after the bumps** (20-07's finding). `checkPost` gains `CheckHTML(ctx, ev.HTML)` in the commit right after the two `chore: bump` commits, so every sm-demo-app commit builds with its own pointers. Until then, the reviewer's three forum forms are already refused on the raw body by the new Check. The tarball and scratch integration therefore proves those three; the rendered-only forms (bit\.ly, an HTML comment) are pinned by TestDemoModeration in Task 5.
|
||||
- **Probes written as checks.** The bypass probe is `scripts/check-moderation.sh BASE`, reusable locally (`check-local.sh moderation`) and live. The call probe is check-chat.cjs --call, extended with the direct-load confirmation step, plus a logout step in its default mode. Both read JWTs from a 0600 file or the environment, never argv, and curl gets the bearer header through a config on stdin (the pattern IN-03 asks for). Live, the probe posts only in the visitor's own DM with a persona and as replies on a seeded thread. It starts with a control word that must be refused, and it deletes anything a probe managed to store.
|
||||
- **Live tokens are an authentication gate.** Live login needs a real Turnstile solve, so Task 9 asks the user to sign in in a browser and save the token cookie values into two files. The alternative is "manual": the user runs the same steps by hand.
|
||||
- **Changelog posts** go to sm-moderation-plugin and sm-forum-plugin only. The layers have no plugin.yaml and no changelog stream, and changelog-post.py refuses a repository without a manifest.
|
||||
- **Deferred findings** (WR-02, WR-03, WR-06, IN-01 to IN-09) each become one todo in the existing format. IN-07's logout half was fixed by 20-08 (dismiss on sign-out); its todo keeps the handle leak.
|
||||
- spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
<objective>
|
||||
Release the gap-round fixes, put them on the live demo, and prove there that the bypasses are closed and the call flow asks before media; close the review ledger.
|
||||
|
||||
Purpose: SC-2, SC-3 and SC-4 hold again after the code review; D-17 (moderation), D-18 (the seams) and D-13 (the call page) hold on the live site.
|
||||
Output: four tags, commits in sm-demo-app and vue-demo-app, a new release on rome, two changelog posts, the closed disposition ledger and twelve follow-up todos, each step after its go-ahead.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW-DISPOSITION.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-05-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-06-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-07-SUMMARY.md
|
||||
@.planning/phases/20-demo-instance-with-every-shared-plugin/20-08-SUMMARY.md
|
||||
|
||||
Repos: ../sm-moderation-plugin, ../sm-forum-plugin, ../vue-chat-layer, ../vue-chatvideo-layer (each on main, 20-07 and 20-08 commits unpushed); ../sm-demo-app (master; submodules plugins/golem15/* at their required tags; vue-demo-app submodule with 20-08's commit, gitlink moved but not committed); ../sm-summercmsio-app (scripts/changelog-post.py). Host: rome over `ssh -p 2222 debian@10.8.3.118` (passwordless sudo; the `rome` alias does not resolve here), with `RSH="ssh -p 2222"` and `ROME=debian@10.8.3.118` as DEPLOY.md uses them.
|
||||
|
||||
Rules (CLAUDE.md and the brief): no co-author tags; stage files by explicit path; one logical change per commit; planning docs and code in separate commits; the plugin or layer is pushed and tagged first, then the pointer or pin bump in the app as its own commit (one `chore: bump <name> to <tag>` per plugin); push vue-demo-app before the sm-demo-app commit that moves its gitlink; tags only on the default branch, annotated, never moved; never read `.env*` files; never print, copy or mint the journal token; leave other sessions' uncommitted edits (STATE.md, state.json, G15OFFICE.md) alone; Docker tests through `sudo -u golem` if the socket is denied. After Task 4, write a progress note into a draft 20-09-SUMMARY.md (tasks done, tags and commits, open points), so a context reset resumes cleanly. `SCRATCH` in the commands below is this session's scratchpad directory; set it once (`SCRATCH=<the scratchpad path>`) before Task 1 and again after a context reset.
|
||||
|
||||
<interfaces>
|
||||
sm-demo-app scripts: dev.sh up (Postgres, Centrifugo, LiveKit 127.0.0.1:7890, Go on :8097, Nuxt on :3020; builds through go.work, so GOWORK overrides it); check-local.sh CHECK... (helpers request, json_has, bad, visitor_jwt, throwaway_user, psql_value; ALL_CHECKS; check_call, two_member_chat, check_chatlive, check_callmedia); check-chat.cjs --base URL [--two|--call] (DEMO_JWT, DEMO_JWT2 from the environment; TOKEN_COOKIE summercms_demo_token; the call mode clicks .chatvideo-callbutton__btn, accepts on .chatvideo-incoming, waits for remote video, mutes, both click .chatvideo-button--leave, polls video/status); check-all.sh [--local] (step 5 runs check-local.sh back remote chatlive callmedia); check-pins.sh; build.sh [release|dev] (release refuses dirty trees, a stale ROADMAP snapshot and pins off go.mod); sync-roadmap.sh; smoke.sh [binary]; check-deploy.sh; check-live.sh URL.
|
||||
Demo APIs used by the probe: GET /_demo/api/v1/chat/members (persona Ada Hart); POST /_chat/api/v1/contexts/demo/1/dm {user_id}; POST /_chat/api/v1/conversations/{id}/messages {content}; DELETE /_chat/api/v1/messages/{id}; GET /_forum/api/v1/contexts/demo/1/categories and /threads; POST /_forum/api/v1/contexts/demo/1/categories/{categoryId}/threads {title, body}; POST /_forum/api/v1/contexts/demo/1/threads/{threadId}/posts {body}; DELETE /_forum/api/v1/contexts/demo/1/posts/{postId} and /threads/{threadId}. Refusal: 422 {"error":"Validation failed","errors":{field:[message]}} with field content (chat), title or body (forum).
|
||||
Live default lists (demo:seed, unless an admin changed them): words "buy followers", "casino bonus", "free crypto", "viagra"; links "bit.ly".
|
||||
20-08 names used by the checks: the confirmation block `.chatvideo-confirm`, its button `.chatvideo-confirm__go`; the call button `.chatvideo-callbutton__btn`.
|
||||
DEPLOY.md: "Build" (build.sh, smoke.sh, check-deploy.sh), "Upload" (three rsync lines with --chown=root:root and sudo rsync), "Release" (migrate and demo:seed with bin/demo.new, keep bin/demo.prev and site/.output.prev, restart summercms-demo and summercms-demo-site, websockets:health), "Verify" (check-live.sh, supervisorctl status, the reset schedule off), "Rollback".
|
||||
changelog (../sm-summercmsio-app/DEPLOY.md "Posting to the changelog"): `scripts/changelog-post.py source vX.Y.Z --repo ../sm-<name>-plugin`, then `scripts/changelog-post.py publish vX.Y.Z notes.md --excerpt "…" --repo ../sm-<name>-plugin` (`--draft` saves unpublished); the plugin checkout must be exactly at the tag with a clean worktree and a plugin.yaml that passes `summer plugin:manifest --check`; the token is read from ~/.config/summercms/journal-token by the script.
|
||||
Todo format (.planning/todos/pending/*.md): frontmatter title, date, priority, area, g15office (task id); a short body. .planning/G15OFFICE.md: each todo gets a g15office task in project summercms (type Bug, Feature, Improvement or Task; the description ends with `Local: .planning/todos/pending/<file>`).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: the bypass, call-confirmation and logout checks exist, and they pass against the unreleased fixes running together in the local demo</name>
|
||||
<precondition>The 20-07 and 20-08 SUMMARYs exist and record their commits; `git -C <repo> status --porcelain` is empty in sm-moderation-plugin, sm-forum-plugin, vue-chat-layer and vue-chatvideo-layer; in sm-demo-app it lists at most ` M vue-demo-app`; Docker runs.</precondition>
|
||||
<files>../sm-demo-app/scripts/check-moderation.sh, ../sm-demo-app/scripts/check-local.sh, ../sm-demo-app/scripts/check-chat.cjs, ../sm-demo-app/scripts/check-all.sh, ../sm-demo-app/README.md, ../sm-demo-app/DEPLOY.md</files>
|
||||
<read_first>../sm-demo-app/scripts/check-local.sh (header, helpers, visitor_jwt, check_call, two_member_chat, ALL_CHECKS), scripts/check-chat.cjs (whole file), scripts/check-all.sh (step 5), scripts/dev.sh (up, how it builds), go.work, README.md "Checks", DEPLOY.md "Verify", 20-REVIEW.md (the probe forms), 20-07-SUMMARY.md (probe table), 20-08-SUMMARY.md (class names and handoffs)</read_first>
|
||||
<action>Per D-17, D-13 and D-04.
|
||||
1. scripts/check-moderation.sh BASE (new, `set -euo pipefail`, header in the style of check-live.sh):
|
||||
- It reads the member JWT from the file named by DEMO_JWT_FILE (it must be mode 600; a looser mode stops the script) or from DEMO_JWT. It never prints the JWT and never puts it in argv: every request passes the Authorization header to curl as a config on stdin, written with bash builtins.
|
||||
- It finds the visitor's DM with the persona Ada Hart (members, then dm) and the first seeded forum category and thread.
|
||||
- Control first: the plain word "viagra" must answer 422 as a chat message (errors.content) and as a forum reply (errors.body). If either control is accepted, it deletes what was stored, prints "check-moderation: the filter is off or the lists differ from the defaults" and exits 1.
|
||||
- Then every probe from the review, in one array whose comment says it mirrors 20-07's TestMatchBypassWords and TestMatchBypassLinks. Words: viagra with U+200B, with U+00AD; "buy followers" with U+00A0, with U+2009, with U+3000; fullwidth viagra; viagra; via**gra**. Links: https://bit%2Ely/x, https://bit.l%79/x, https://bit.ly/x, https://bit。ly/x, https://user@bit.ly/x, [x](https://bit.ly/a). Write each with bash $'\u…' escapes and build the JSON bodies with python3 json.dumps, as check-local does.
|
||||
- Each probe must answer 422 as a chat message, as a forum reply and once as a forum thread title (errors.title). A probe that answers 2xx is deleted at once (the message, post or thread) and reported.
|
||||
- It ends with "check-moderation: ok", or one line per failure and exit 1.
|
||||
2. check-local.sh: `check_moderation` runs check-moderation.sh against $GO with the visitor's JWT through the environment; add `moderation` to ALL_CHECKS and the header list. check-all.sh step 5 runs `moderation` with the other browser and API checks (header comment too).
|
||||
3. check-chat.cjs:
|
||||
- Read DEMO_JWT_FILE and DEMO_JWT2_FILE when set (trimmed, never printed), else DEMO_JWT and DEMO_JWT2.
|
||||
- --call: before the call-button step, A loads /call/{dm}?start=1 directly. `.chatvideo-confirm` must be visible within 5 s. Watch the page's WebSockets for 3 s: none may open to a URL containing /livekit/rtc, and no .chatvideo-tile may render. GET .../video/status must show no session. Then the existing flow runs (the call button and Accept autostart through the handoffs), and the summary line stays "check-chat: ok call".
|
||||
- Default mode: after the message check, the member clicks Log out in the header. Within 5 s every WebSocket the page opened to /ws must be closed, and /chat must show the register link.
|
||||
- Update the header comment.
|
||||
4. README.md "Checks" and DEPLOY.md "Verify": the moderation check, the live bypass probe and the live call probe with token files (the commands, the file mode, that they post only in the visitor's DM and as thread replies and clean up), in the files' style.
|
||||
5. Commit in sm-demo-app (scripts and docs only): `test: moderation bypass probe, call confirmation and logout checks`.
|
||||
6. Temporary integration (never committed):
|
||||
- Write a scratch go.work, $SCRATCH/demo-gap.go.work under this session's scratchpad. It is ../sm-demo-app/go.work with every path made absolute, plugins/golem15/moderation replaced by the absolute path of ../sm-moderation-plugin and plugins/golem15/forum by ../sm-forum-plugin.
|
||||
- Pack both layers with `pnpm --dir ../vue-chat-layer pack --pack-destination $SCRATCH` (and the same for vue-chatvideo-layer), then `pnpm --dir ../sm-demo-app/vue-demo-app add <the two tarball paths>`.
|
||||
- Run `GOWORK=$SCRATCH/demo-gap.go.work ../sm-demo-app/scripts/dev.sh up`.
|
||||
- Run `../sm-demo-app/scripts/check-local.sh moderation chat callmedia` and see them pass. Leave the setup in place for Task 2, which reverts it; say so in the draft SUMMARY if the run stops here.</action>
|
||||
<verify>
|
||||
<automated>bash -n ../sm-demo-app/scripts/check-moderation.sh && node --check ../sm-demo-app/scripts/check-chat.cjs && ../sm-demo-app/scripts/check-local.sh moderation chat callmedia</automated>
|
||||
<fails_when>Non-zero exit: a script has a syntax error, or check-local reports moderation failed (a probe stored, a control accepted, a wrong field), chat failed (the message or the logout socket check) or callmedia failed (the direct load opened LiveKit or showed no confirmation, or the DM call did not complete).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../sm-demo-app show --stat HEAD | grep -cE 'scripts/check-moderation.sh|scripts/check-chat.cjs|scripts/check-local.sh'` prints 3.
|
||||
- `grep -v '^\s*#' ../sm-demo-app/scripts/check-moderation.sh | grep -cE -- '-H +.?Authorization'` prints 0 (the bearer header never goes on curl's command line).
|
||||
</acceptance_criteria>
|
||||
<done>The bypass probe, the call confirmation step and the logout check exist and pass against all four unreleased fixes together, before anything is tagged.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Full suites of every touched repository, the rest of the local checks on the unreleased code, revert of the temporary integration, and release prep</name>
|
||||
<files>../vue-chat-layer/package.json, ../vue-chatvideo-layer/package.json</files>
|
||||
<read_first>The Task 1 setup ($SCRATCH/demo-gap.go.work, the tarball pins), each repo's README Testing and Changelog sections, ../sm-moderation-plugin/plugin.yaml and ../sm-forum-plugin/plugin.yaml, .planning/notes/core-plugins-own-repos.md, ../sm-demo-app/scripts/check-pins.sh</read_first>
|
||||
<action>Per SC-4.
|
||||
1. Full suites (record pass counts in the draft SUMMARY):
|
||||
- sm-moderation-plugin and sm-forum-plugin: `go -C <repo> vet ./...` and `go -C <repo> test -count=1 ./...` with Docker.
|
||||
- vue-chat-layer and vue-chatvideo-layer: `pnpm --dir <repo> test` and `pnpm --dir <repo> run build:playground`.
|
||||
- vue-demo-app: `pnpm test` and `pnpm run build`, first under the tarball pins, then again after the revert below.
|
||||
- sm-demo-app: `go vet ./...` and `go test -count=1 ./...` under its own go.work (the committed pointers). Also `GOWORK=$SCRATCH/demo-gap.go.work go -C ../sm-demo-app test -count=1 -run '^(TestDemoModeration|TestBootAllPlugins|TestGoModRequiresTags)$' .`, which shows the new plugin code works with the demo before it is tagged. TestGoModRequiresTags only reads go.mod, so it must still pass.
|
||||
2. Remaining local checks on the unreleased code: `../sm-demo-app/scripts/check-local.sh chatlive call forum friends herald tour`.
|
||||
3. Revert the temporary integration: `git -C ../sm-demo-app/vue-demo-app checkout -- package.json pnpm-lock.yaml`, then `pnpm --dir ../sm-demo-app/vue-demo-app install --frozen-lockfile`. Restart the stack without the GOWORK override (`../sm-demo-app/scripts/dev.sh up` restarts or rebuilds per its own rules; stop the old Go process if dev.sh does not). Delete the scratch tarballs and go.work.
|
||||
4. Release prep, recorded as a table in the draft SUMMARY:
|
||||
- For each of the four repos: the latest tag (`git tag --sort=-v:refname | head -1` and `git ls-remote --tags origin`) and the next patch tag (expected v0.1.1, v0.1.2, v0.1.1, v0.1.1).
|
||||
- The default branch (`git remote show origin`, HEAD branch main), a fast-forward of origin main (`git merge-base --is-ancestor origin/main HEAD` after `git fetch`), and every earlier tag an ancestor of HEAD.
|
||||
- The README changelog entries for the new versions (moderation, forum), and `summer plugin:manifest --check` passing in both plugins (summer from PATH, else `go -C ../summercms.go run ./cmd/summer`).
|
||||
- Set "version" in the two layers' package.json to the new version, and commit each: `chore: release 0.1.1`.
|
||||
- The commits each tag will contain (`git log --oneline <latest tag>..HEAD`).</action>
|
||||
<verify>
|
||||
<automated>for r in sm-moderation-plugin sm-forum-plugin; do go -C ../$r vet ./... && go -C ../$r test -count=1 ./... || exit 1; done && for l in vue-chat-layer vue-chatvideo-layer; do pnpm --dir ../$l test || exit 1; done && pnpm --dir ../sm-demo-app/vue-demo-app test && pnpm --dir ../sm-demo-app/vue-demo-app run build && go -C ../sm-demo-app vet ./... && go -C ../sm-demo-app test -count=1 ./... && git -C ../sm-demo-app/vue-demo-app diff --quiet -- package.json pnpm-lock.yaml && for l in vue-chat-layer vue-chatvideo-layer; do node -e "process.exit(require('../$l/package.json').version === '0.1.1' ? 0 : 1)" || exit 1; done</automated>
|
||||
<fails_when>Non-zero exit: a suite fails in any touched repository, the temporary pins were not reverted, or a layer's package.json version was not set.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- The draft SUMMARY holds the release table (repo, latest tag, new tag, HEAD, commits since the tag) and the suite results.
|
||||
- `git -C ../sm-demo-app status --porcelain` lists at most ` M vue-demo-app`.
|
||||
</acceptance_criteria>
|
||||
<done>Every touched repository is green on its own and together with the others, the integration left no trace, and the release table is ready for the go-ahead.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 3: Go-ahead to push main and tag the four repositories</name>
|
||||
<read_first>The Task 2 release table (repo, latest tag, proposed tag, HEAD, commits since the latest tag), the suite results and the local checks, the note on moderation's version (v0.1.1, not the brief's v0.1.2)</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user's answer is recorded in the SUMMARY with the confirmed versions.
|
||||
</acceptance_criteria>
|
||||
<decision>Push main and create the annotated tags sm-moderation-plugin v0.1.1, sm-forum-plugin v0.1.2, vue-chat-layer v0.1.1 and vue-chatvideo-layer v0.1.1?</decision>
|
||||
<context>Tags are one-way: consumers' go.sum and lockfiles pin them, so they are never moved, only superseded. Each tag carries only the gap-round fixes listed in the table (plus vue-chat-layer's two test and refactor commits already on main since v0.1.0). The demo can consume them only after this. Other applications pin older tags and are unaffected, because the changes are additive (PostSaving gains a field, the filter matches more forms, the layers add a guard, handoffs and a confirmation).</context>
|
||||
<options>
|
||||
<option id="release">
|
||||
<name>Push and tag all four</name>
|
||||
<pros>The demo can pin the fixes and be redeployed.</pros>
|
||||
<cons>The versions are public and final.</cons>
|
||||
</option>
|
||||
<option id="push-only">
|
||||
<name>Push main, no tags yet</name>
|
||||
<pros>The commits are backed up and visible for review.</pros>
|
||||
<cons>The demo cannot pin them; the plan stops after Task 4 until tags are approved.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>Nothing leaves this machine.</pros>
|
||||
<cons>The live demo keeps the bypasses and the call race.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "release" (optionally with other versions), "push-only" or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Push the four repositories and tag them</name>
|
||||
<reversibility rating="one-way">Pushed tags are pinned by consumers' go.sum and lockfiles; they can be superseded but never moved.</reversibility>
|
||||
<precondition>Task 3 answered "release" or "push-only".</precondition>
|
||||
<files>(no files; git refs on origin)</files>
|
||||
<read_first>The Task 3 answer, the Task 2 release table, .planning/notes/core-plugins-own-repos.md</read_first>
|
||||
<action>For each of sm-moderation-plugin, sm-forum-plugin, vue-chat-layer and vue-chatvideo-layer, in that order:
|
||||
- `git fetch origin` and confirm origin/main is still an ancestor of HEAD (stop and report if another session pushed);
|
||||
- `git push origin main` and check `git ls-remote origin refs/heads/main` equals HEAD;
|
||||
- with "release": create the annotated tag at HEAD (`git tag -a <tag> -m "<one line: what the release fixes>"`), push only that tag (`git push origin <tag>`), check `git ls-remote origin "refs/tags/<tag>^{}"` equals HEAD and that the previous tag is an ancestor (`git merge-base --is-ancestor <previous> <tag>`).
|
||||
With "push-only", stop after the pushes, record it, and end the plan run here (resume at Task 3 when the user approves tags).
|
||||
Write the progress note into the draft 20-09-SUMMARY.md: the four pushed heads and tags.</action>
|
||||
<verify>
|
||||
<automated>for r in "sm-moderation-plugin v0.1.1" "sm-forum-plugin v0.1.2" "vue-chat-layer v0.1.1" "vue-chatvideo-layer v0.1.1"; do set -- $r; [ "$(git -C ../$1 ls-remote origin refs/heads/main | cut -f1)" = "$(git -C ../$1 rev-parse HEAD)" ] || exit 1; [ "$(git -C ../$1 ls-remote origin "refs/tags/$2^{}" | cut -f1)" = "$(git -C ../$1 rev-parse HEAD)" ] || exit 1; done</automated>
|
||||
<fails_when>Non-zero exit: a remote main differs from the local HEAD, or a tag is missing on origin or points elsewhere. Use the versions confirmed in Task 3 if they differ from the table; with "push-only" only the main check applies.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../sm-moderation-plugin describe --exact-match HEAD` and the same in the other three repos print the new tag.
|
||||
</acceptance_criteria>
|
||||
<done>The four fixes are public at their patch tags on the default branch.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 5: The demo consumes the tags: layer pins, plugin bumps, the forum listener reads the rendered post, and the gitlink</name>
|
||||
<precondition>Task 4 created all four tags on origin.</precondition>
|
||||
<files>../sm-demo-app/vue-demo-app/package.json, ../sm-demo-app/vue-demo-app/pnpm-lock.yaml, ../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue, ../sm-demo-app/go.mod, ../sm-demo-app/go.sum, ../sm-demo-app/plugins/golem15/moderation, ../sm-demo-app/plugins/golem15/forum, ../sm-demo-app/plugins/demo/moderation.go, ../sm-demo-app/moderation_test.go, ../sm-demo-app/vue-demo-app, ../sm-demo-app/plugins/demo/content/ROADMAP.md</files>
|
||||
<read_first>../sm-demo-app/plugins/demo/moderation.go, moderation_test.go (TestDemoModeration: setLists, post, put, refused, the stored-count check), go.mod, .gitmodules, scripts/check-pins.sh, scripts/build.sh (the release refusals), scripts/sync-roadmap.sh, vue-demo-app/package.json, vue-demo-app/app/pages/call/[conversation].vue, 20-07-SUMMARY.md (the listener finding), ../sm-moderation-plugin/README.md (CheckHTML), ../sm-forum-plugin/README.md (PostSaving.HTML)</read_first>
|
||||
<behavior>
|
||||
- TestDemoModeration, with the lists set to the demo defaults plus the path rule example.com/promo: every probe of check-moderation.sh, the path-rule forms (https://example.com:443/promo, https://example.com//promo, https://sub.example.com/promo) and the decomposed żółw case (with żółw added to the words), is refused with 422 on chat send, reply and edit (errors.content) and on forum thread title, thread body, reply and edit (errors.title or errors.body); nothing is stored.
|
||||
- The rendered-only forum forms bit\.ly and via<!-- x -->gra are refused on reply and edit with errors.body (only CheckHTML on ev.HTML catches them).
|
||||
- The existing TestDemoModeration cases keep passing.
|
||||
</behavior>
|
||||
<action>Per D-17, D-18 and D-13, in this commit order:
|
||||
1. vue-demo-app: `pnpm --dir ../sm-demo-app/vue-demo-app add` the two git+https specs at the new tags (vue-chat-layer and vue-chatvideo-layer). Update the doc comment of app/pages/call/[conversation].vue: ?start=1 picks Start over Join on the confirmation; media starts only after a click there, the call button or Accept. Run `pnpm test` and `pnpm run build`, then commit in vue-demo-app: `chore: pin vue-chat-layer and vue-chatvideo-layer v0.1.1`.
|
||||
2. sm-demo-app, for moderation and then forum: fetch tags in the submodule and check it out at the new tag; `GOWORK=off GOPRIVATE=git.golem15.com/* go -C ../sm-demo-app get git.golem15.com/golem15/sm-<name>-plugin@<tag>` and `GOWORK=off GOPRIVATE=git.golem15.com/* go -C ../sm-demo-app mod tidy` (GOPRIVATE as build.sh sets it); commit go.mod, go.sum and the gitlink: `chore: bump sm-moderation-plugin to v0.1.1`, then `chore: bump sm-forum-plugin to v0.1.2`.
|
||||
3. plugins/demo/moderation.go: checkPost also runs `Filter.CheckHTML` on `ev.HTML` (when not empty), after title and body, and answers a violation as `Rejection{Field: "body"}`; update the function and file comments (chat messages are checked by Check, which normalises; forum posts also by what they render to). Extend TestDemoModeration per the behavior block (red first for the rendered-only forms). Commit: `fix: refuse forum posts whose rendered text carries a banned word or link`.
|
||||
4. Commit the vue-demo-app gitlink in sm-demo-app: `chore: bump vue-demo-app (layers v0.1.1, sign-out reset)`.
|
||||
5. If `scripts/sync-roadmap.sh --check` reports a stale snapshot, run `scripts/sync-roadmap.sh` and commit `chore: sync the roadmap snapshot`.
|
||||
Nothing is pushed in this task.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-demo-app vet ./... && go -C ../sm-demo-app test -count=1 ./... && go -C ../sm-demo-app test -count=1 -run '^(TestDemoModeration|TestGoModRequiresTags)$' -v . 2>&1 | grep -cE -- '^--- PASS: Test(DemoModeration|GoModRequiresTags) ' | grep -qx 2 && ../sm-demo-app/scripts/check-pins.sh && pnpm --dir ../sm-demo-app/vue-demo-app test</automated>
|
||||
<fails_when>Non-zero exit: vet or a Go test fails (a probe stored, a rendered-only form accepted, a go.mod require not a tag), check-pins reports a checkout off its required tag, or the site tests fail on the new pins.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -cE 'sm-moderation-plugin v0\.1\.1$|sm-forum-plugin v0\.1\.2$' ../sm-demo-app/go.mod` prints 2.
|
||||
- `grep -cE 'vue-chat(video)?-layer\.git#v0\.1\.1' ../sm-demo-app/vue-demo-app/package.json` prints 2.
|
||||
- `git -C ../sm-demo-app status --porcelain` prints nothing.
|
||||
</acceptance_criteria>
|
||||
<done>The demo builds from the released fixes only, and its own listener refuses forum posts by what they render to.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 6: The demo's whole gate passes locally on the released versions, including a release build and the smoke run</name>
|
||||
<files>(no files; build outputs bin/demo and vue-demo-app/.output, untracked)</files>
|
||||
<read_first>../sm-demo-app/scripts/check-all.sh (steps and --local), DEPLOY.md "Build", 20-06-SUMMARY.md (the last check-all run)</read_first>
|
||||
<action>Run `../sm-demo-app/scripts/dev.sh up` (the stack now builds from the bumped submodules through go.work), then `../sm-demo-app/scripts/check-all.sh --local`. It runs the app and plugin suites, vitest in vue-demo-app and the four layers, sync-roadmap --check, check-pins, `build.sh release`, smoke.sh, check-deploy, then check-local back remote chatlive callmedia moderation and check-live against the current live site. Record the release id from the `build: ok release <id>` line and each step's result in the draft SUMMARY. If a step fails, fix the cause in the repository that owns it. A fix to a tagged repository means a new patch tag through Task 3's gate again, never a moved tag.</action>
|
||||
<verify>
|
||||
<automated>../sm-demo-app/scripts/check-all.sh --local 2>&1 | tail -1 | grep -qx 'check-all: ok'</automated>
|
||||
<fails_when>Non-zero exit: any check-all step fails (a suite, the snapshot, pins, the release build, smoke, check-deploy, a browser check or check-live).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- The draft SUMMARY records `build: ok release <id>` and `smoke: ok` from this run.
|
||||
</acceptance_criteria>
|
||||
<done>The exact release that would go to rome passed the whole gate on this machine.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 7: Go-ahead to push the demo repositories and deploy the release to rome</name>
|
||||
<read_first>The release id from Task 6 and the check-all result; `git -C ../sm-demo-app log --oneline origin/master..HEAD` and the same for vue-demo-app; the list of what changes on rome: binary, site, config rsync; `migrate` (no new migrations in the bumped plugins: check `git -C <plugin> diff --stat <previous tag> <new tag> -- updates/`) and `demo:seed`; restart of summercms-demo and summercms-demo-site only; no nginx, Centrifugo, LiveKit, firewall or WavePath change; the rollback commands from DEPLOY.md "Rollback"</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user's answer is recorded in the SUMMARY.
|
||||
</acceptance_criteria>
|
||||
<decision>Push vue-demo-app and sm-demo-app and deploy release <id> to demo.summercms.io?</decision>
|
||||
<context>The live demo still has CR-01 (calls connect after Leave), CR-02 and CR-03 (filter bypasses), WR-01, WR-04 and WR-05. The release restarts only the demo's own two programs; bin/demo.prev and site/.output.prev stay for a rollback.</context>
|
||||
<options>
|
||||
<option id="deploy">
|
||||
<name>Push and deploy</name>
|
||||
<pros>The fixes are live today.</pros>
|
||||
<cons>A short restart of the demo's API and site.</cons>
|
||||
</option>
|
||||
<option id="push-only">
|
||||
<name>Push, deploy later</name>
|
||||
<pros>The pins are backed up.</pros>
|
||||
<cons>The live demo keeps the bugs; Tasks 8 to 10 wait.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold</name>
|
||||
<pros>No change anywhere.</pros>
|
||||
<cons>As above, and the pins exist only here.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "deploy", "push-only" or "hold".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 8: Push the demo, upload and release on rome by the runbook, and check the live site</name>
|
||||
<reversibility rating="costly">A release can be rolled back with bin/demo.prev and site/.output.prev (DEPLOY.md "Rollback"); migrations, if any ran, are not reversed.</reversibility>
|
||||
<precondition>Task 7 answered "deploy" (with "push-only" do steps 1 and 2 only and stop).</precondition>
|
||||
<files>(no repository files; rome: /srv/summercms-demo/bin, /srv/summercms-demo/site, /srv/summercms-demo/config)</files>
|
||||
<read_first>../sm-demo-app/DEPLOY.md "Upload", "Release", "Verify", "Rollback"; 20-05-SUMMARY.md (how the last release went, shared-host rules)</read_first>
|
||||
<action>Per SC-3 and D-10.
|
||||
1. Push vue-demo-app master, check `git ls-remote` equals HEAD; then push sm-demo-app master, check the same.
|
||||
2. With "push-only", record and stop here.
|
||||
3. Build machine: DEPLOY.md "Upload", the three rsync lines exactly (config without overrides.yaml, bin/demo to bin/demo.new, vue-demo-app/.output/ to site/.output.new/, `--chown=root:root`, sudo rsync, `$RSH`), from the release built in Task 6 (re-run `scripts/build.sh` if anything changed since, then smoke.sh again).
|
||||
4. rome: DEPLOY.md "Release", exactly as written, in this order:
|
||||
- migrate and demo:seed with bin/demo.new as summercms-demo with SUMMER_ENV=production;
|
||||
- keep bin/demo.prev and site/.output.prev, then swap in the new binary and site;
|
||||
- `sudo supervisorctl restart summercms-demo summercms-demo-site`;
|
||||
- websockets:health answers Configuration OK.
|
||||
Restart nothing else. Every command that could carry a secret runs on rome without echoing it.
|
||||
5. DEPLOY.md "Verify":
|
||||
- `scripts/check-live.sh https://demo.summercms.io` prints `check-live: ok`;
|
||||
- supervisorctl status shows the four demo programs RUNNING;
|
||||
- the reset schedule stays off;
|
||||
- `wavepath-livekit` keeps its pid (read-only check).
|
||||
6. Record in the draft SUMMARY: the release id, the commands' results, the pids before and after, and the rollback state.</action>
|
||||
<verify>
|
||||
<automated>[ "$(git -C ../sm-demo-app ls-remote origin refs/heads/master | cut -f1)" = "$(git -C ../sm-demo-app rev-parse HEAD)" ] && [ "$(git -C ../sm-demo-app/vue-demo-app ls-remote origin refs/heads/master | cut -f1)" = "$(git -C ../sm-demo-app/vue-demo-app rev-parse HEAD)" ] && ../sm-demo-app/scripts/check-live.sh https://demo.summercms.io</automated>
|
||||
<fails_when>Non-zero exit: a remote master differs from the local HEAD, or check-live reports any failure after the release (roll back per DEPLOY.md and report if the site or API is broken).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `ssh -p 2222 debian@10.8.3.118 sudo supervisorctl status summercms-demo summercms-demo-site summercms-demo-centrifugo summercms-demo-livekit` shows four RUNNING lines.
|
||||
</acceptance_criteria>
|
||||
<done>demo.summercms.io runs the release with all six fixes, and its anonymous checks pass.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-action" gate="blocking">
|
||||
<name>Task 9: The user signs in on the live demo so the probes can act as members (an authentication gate: live login needs a real Turnstile solve)</name>
|
||||
<action>Sign in on https://demo.summercms.io in a browser and save the session token for the probes. Claude cannot do this because live login is behind Turnstile.</action>
|
||||
<instructions>
|
||||
Claude already deployed the release and ran the anonymous live checks. The member probes need a signed-in session:
|
||||
1. In a browser, log in at https://demo.summercms.io/login as the demo's visitor account (or any member account you use for checks).
|
||||
2. In the browser's developer tools (Application, then Cookies), copy the value of the cookie `summercms_demo_token`.
|
||||
3. Save it in a file only you can read, without pasting it into this chat: `install -m 600 /dev/null ~/.config/summercms/demo-live-jwt`, then paste the value into that file with an editor.
|
||||
4. For the two-browser call probe, do the same with a second member account (register one in a private window if needed) into `~/.config/summercms/demo-live-jwt2`.
|
||||
Alternatively run the checks yourself ("manual"):
|
||||
- Send each probe from DEPLOY.md "Verify" as a DM to Ada and as a forum reply. Each must be refused, and the plain word viagra too.
|
||||
- Open /call/{your DM with Ada}?start=1 directly. A Start call button must show, and the camera must stay off until you click it.
|
||||
- From a second browser, call yourself from the DM button and accept. Both sides must connect.
|
||||
- Leave while the page still says "Connecting…". The camera light must go off and the other side must stop ringing.
|
||||
- Log out while a call rings. The prompt and the chat panel must go away.
|
||||
</instructions>
|
||||
<verification>Claude checks that each file exists with mode 600 and is not empty (`stat -c %a`, `test -s`), without reading its content into the conversation.</verification>
|
||||
<resume-signal>Reply "tokens ready" (both files), "one token" (only demo-live-jwt; the call probe is then your manual check) or "manual approved" / "manual failed: what you saw".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 10: Live recheck: the bypass probe, the call probe, check-live and smoke, then the changelog drafts</name>
|
||||
<precondition>Task 9 answered; for the automated probes the token files exist with mode 600.</precondition>
|
||||
<files>(no repository files; drafts in this session's scratchpad)</files>
|
||||
<read_first>The Task 9 answer, ../sm-demo-app/DEPLOY.md "Verify" (the probe commands from Task 1), ../sm-summercmsio-app/DEPLOY.md "Posting to the changelog", the CLAUDE.md changelog rules</read_first>
|
||||
<action>Per SC-2, D-17 and D-13.
|
||||
1. With a token: `DEMO_JWT_FILE=~/.config/summercms/demo-live-jwt ../sm-demo-app/scripts/check-moderation.sh https://demo.summercms.io` prints `check-moderation: ok`.
|
||||
2. With two tokens: `DEMO_JWT_FILE=~/.config/summercms/demo-live-jwt DEMO_JWT2_FILE=~/.config/summercms/demo-live-jwt2 NODE_PATH="$(npm root -g)" node ../sm-demo-app/scripts/check-chat.cjs --base https://demo.summercms.io --call` prints `check-chat: ok call`. Fake media goes through rome's LiveKit; the direct-load step shows the confirmation. Do not run the default mode live: it would post in public #general and log the token out.
|
||||
3. With "manual approved", record the user's answer instead of the automated probe it replaces; with "manual failed", stop and report what the user saw against the fix it points to.
|
||||
4. `../sm-demo-app/scripts/check-live.sh https://demo.summercms.io` and `../sm-demo-app/scripts/smoke.sh` (the deployed artifact bin/demo) again; both ok.
|
||||
5. Remove the two token files (`rm -f`) and tell the user their browser sessions stay signed in.
|
||||
6. Changelog drafts. From ../sm-summercmsio-app run `scripts/changelog-post.py source <tag> --repo ../sm-moderation-plugin`, and the same for sm-forum-plugin. Write the user-facing notes to $SCRATCH/changelog-moderation.md and $SCRATCH/changelog-forum.md, using sections `## Highlights`, `## Added`, `## Changed` and `## Fixed` as needed. Include no H1, no planning IDs and no `quick-*` codes, and no consuming application's name. Add a one-line plain-text excerpt for each.
|
||||
- Moderation: banned words and links now match what readers see (invisible characters, Unicode spaces, diacritics, entities, inline markup, URL forms browsers normalise); path entries cover subdomains; MatchHTML and Filter.CheckHTML for rendered content.
|
||||
- Forum: PostSaving carries the rendered post HTML.
|
||||
7. Record every result in the draft SUMMARY.</action>
|
||||
<verify>
|
||||
<automated>../sm-demo-app/scripts/check-live.sh https://demo.summercms.io && test -s "$SCRATCH/changelog-moderation.md" && test -s "$SCRATCH/changelog-forum.md" && ! grep -qE '^# |CR-0|WR-0|IN-0|20-0[0-9]|quick-' "$SCRATCH/changelog-moderation.md" "$SCRATCH/changelog-forum.md"</automated>
|
||||
<fails_when>Non-zero exit: check-live fails, a draft is missing, or a draft has an H1, a review or plan ID or a quick code. The probe runs of steps 1 and 2 are recorded with their output line; a probe failure stops the plan with a report, which is not a verify failure.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- The draft SUMMARY records `check-moderation: ok` and `check-chat: ok call` against https://demo.summercms.io, or the user's manual answer for each.
|
||||
- `test -e ~/.config/summercms/demo-live-jwt || echo gone` prints gone.
|
||||
</acceptance_criteria>
|
||||
<done>The live demo refuses every bypass from the review, asks before a call page turns media on, completes a DM call, and passes its anonymous checks and smoke run.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 11: Go-ahead for the two plugin changelog posts</name>
|
||||
<read_first>$SCRATCH/changelog-moderation.md and $SCRATCH/changelog-forum.md with their excerpts, the tags (sm-moderation-plugin v0.1.1, sm-forum-plugin v0.1.2), and whether ~/.config/summercms/journal-token exists (`test -s`, never read)</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user's answer is recorded in the SUMMARY, with any wording changes applied to the drafts.
|
||||
</acceptance_criteria>
|
||||
<decision>Publish the two plugin posts on https://summercms.io/changelog/plugins?</decision>
|
||||
<context>CLAUDE.md: plugin release tags get a post on /changelog/plugins the same day. The posts are public and can be updated later with --update. The layers get no post (no plugin.yaml, no changelog stream).</context>
|
||||
<options>
|
||||
<option id="publish">
|
||||
<name>Publish both</name>
|
||||
<pros>The releases are announced the day they are tagged.</pros>
|
||||
<cons>Public at once.</cons>
|
||||
</option>
|
||||
<option id="draft">
|
||||
<name>Save as drafts (--draft)</name>
|
||||
<pros>The text can be reviewed in the admin first.</pros>
|
||||
<cons>Not announced until published.</cons>
|
||||
</option>
|
||||
<option id="skip">
|
||||
<name>Skip</name>
|
||||
<pros>No post.</pros>
|
||||
<cons>Breaks the same-day rule.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "publish", "draft" or "skip", with any changes to the text.</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 12: Publish the posts as answered, and close the review ledger with commit refs and follow-up todos</name>
|
||||
<precondition>Task 11 answered.</precondition>
|
||||
<files>.planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW-DISPOSITION.md, .planning/todos/pending/chatchannels-pin-policy.md, .planning/todos/pending/moderation-profile-group-and-filenames.md, .planning/todos/pending/forum-friends-client-401-refresh.md, .planning/todos/pending/chatvideo-dm-only-host-hook.md, .planning/todos/pending/chatvideo-live-membership.md, .planning/todos/pending/check-local-jwt-out-of-argv.md, .planning/todos/pending/chat-slash-text-escape.md, .planning/todos/pending/demo-seed-moderation-lists-once.md, .planning/todos/pending/demo-nginx-livekit-rtc-only.md, .planning/todos/pending/chatvideo-incoming-handle-leak.md, .planning/todos/pending/demo-vapid-runbook-pipefail.md, .planning/todos/pending/demo-chat-members-read-only.md</files>
|
||||
<read_first>20-REVIEW-DISPOSITION.md, 20-REVIEW.md (WR-02, WR-03, WR-06, IN-01 to IN-09: files, issue, fix), two existing files in .planning/todos/pending/ (format), .planning/G15OFFICE.md (todo mirroring), the commit refs from the 20-07, 20-08 and draft 20-09 SUMMARYs</read_first>
|
||||
<action>Per SC-4 and the brief.
|
||||
1. Posts (with "publish" or "draft"):
|
||||
- From ../sm-summercmsio-app, for each plugin, check the checkout is exactly at its tag with a clean worktree (`git -C ../sm-<name>-plugin describe --exact-match HEAD`; check out the tag if main moved on).
|
||||
- Run `scripts/changelog-post.py publish <tag> <draft file> --excerpt "<line>" --repo ../sm-<name>-plugin`, adding --draft for "draft". The script reads the journal token itself.
|
||||
- If the token file is missing or the token is refused, stop and ask the user. Never print, copy or mint a token.
|
||||
- Check https://summercms.io/changelog/plugins lists the published posts.
|
||||
- Return the checkouts to main.
|
||||
2. 20-REVIEW-DISPOSITION.md: CR-01, CR-02, CR-03, WR-01, WR-04 and WR-05 become `fixed`. Each note names the repo, the commit short sha and the tag, for example `sm-moderation-plugin <sha> (v0.1.1)`, plus the live check that confirmed it. WR-02, WR-03, WR-06 and IN-01 to IN-09 become `deferred`, each note pointing at its todo file. Add a `closed: 2026-11-02` line (or the actual date) to the frontmatter.
|
||||
3. Todos, one per deferred finding, in the existing format: title, date, priority (high for WR-02 and WR-03, medium for WR-06, IN-01, IN-02 and IN-07, low for the rest), area (the repo and file), an empty g15office field until the task exists. The body gives the finding's issue and fix in two or three sentences, with "Source: phase 20 code review (20-REVIEW.md <ID>)". IN-07's todo notes that the logout half was fixed by 20-08. The files are:
|
||||
- chatchannels-pin-policy.md (WR-02)
|
||||
- moderation-profile-group-and-filenames.md (WR-03)
|
||||
- forum-friends-client-401-refresh.md (WR-06)
|
||||
- chatvideo-dm-only-host-hook.md (IN-01)
|
||||
- chatvideo-live-membership.md (IN-02)
|
||||
- check-local-jwt-out-of-argv.md (IN-03)
|
||||
- chat-slash-text-escape.md (IN-04)
|
||||
- demo-seed-moderation-lists-once.md (IN-05)
|
||||
- demo-nginx-livekit-rtc-only.md (IN-06)
|
||||
- chatvideo-incoming-handle-leak.md (IN-07)
|
||||
- demo-vapid-runbook-pipefail.md (IN-08)
|
||||
- demo-chat-members-read-only.md (IN-09)
|
||||
4. g15office (.planning/G15OFFICE.md):
|
||||
- Create one task per todo in project summercms (type Bug for WR-02, WR-03, WR-06, IN-02, IN-04, IN-05, IN-07 and IN-09, Improvement for the rest). Each description ends with `Local: .planning/todos/pending/<file>`. Write each task id into its todo's frontmatter.
|
||||
- Post a short comment on the Phase 20 milestone task: the gap round released and deployed, with the four tags.
|
||||
- If the g15office tools do not answer, leave the ids empty and list the todos as left for the user in the SUMMARY. Do not edit G15OFFICE.md itself.
|
||||
5. Commit in summercms.go by explicit path (planning docs only; STATE.md, state.json and G15OFFICE.md untouched): `docs(20): review disposition after the gap closure`.</action>
|
||||
<verify>
|
||||
<automated>D=.planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW-DISPOSITION.md; for f in CR-01 CR-02 CR-03 WR-01 WR-04 WR-05; do grep -E "^\| $f \|" $D | grep -q '| fixed |' || exit 1; done; for f in WR-02 WR-03 WR-06 IN-01 IN-02 IN-03 IN-04 IN-05 IN-06 IN-07 IN-08 IN-09; do grep -E "^\| $f \|" $D | grep -q '| deferred |' || exit 1; done; ls .planning/todos/pending/{chatchannels-pin-policy,moderation-profile-group-and-filenames,forum-friends-client-401-refresh,chatvideo-dm-only-host-hook,chatvideo-live-membership,check-local-jwt-out-of-argv,chat-slash-text-escape,demo-seed-moderation-lists-once,demo-nginx-livekit-rtc-only,chatvideo-incoming-handle-leak,demo-vapid-runbook-pipefail,demo-chat-members-read-only}.md >/dev/null && git diff --quiet HEAD -- $D</automated>
|
||||
<fails_when>Non-zero exit: a finding has the wrong disposition, a todo file is missing, or the ledger change is not committed.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '| open |' .planning/phases/20-demo-instance-with-every-shared-plugin/20-REVIEW-DISPOSITION.md` prints 0.
|
||||
- Every fixed row names at least one commit sha and tag.
|
||||
- The SUMMARY records the post URLs (or the draft ids, or "skipped") and the g15office ids or the note that they are left for the user.
|
||||
</acceptance_criteria>
|
||||
<done>The gap round is announced as the user chose, every review finding has its final disposition, and every deferred one is a tracked todo.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| build machine to origin | pushes and one-way tags that other applications pin |
|
||||
| build machine to rome | rsync and sudo on a shared production host |
|
||||
| probes to the live demo | member sessions posting test content on a public site |
|
||||
| build machine to summercms.io | the journal token publishing posts |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-20-47 | Tampering | release tags | high | mitigate | annotated tags on the default branch only after Task 3's go-ahead; fast-forward check before push; ls-remote equals HEAD; earlier tags are ancestors; never moved, a fix gets a new patch tag |
|
||||
| T-20-48 | Information disclosure | live member JWTs | high | mitigate | the user writes them into 0600 files (never pasted); scripts read the files, never print them, and pass the bearer header to curl as a config on stdin; the files are removed after the probes; the live default mode of check-chat (which would log out and post publicly) is not run |
|
||||
| T-20-49 | Tampering | probe content on the live demo | medium | mitigate | probes post only in the visitor's own DM and as replies or one thread on seeded content; a control word must be refused first; anything a probe stored is deleted at once and reported |
|
||||
| T-20-50 | Information disclosure | journal token | high | mitigate | changelog-post.py reads ~/.config/summercms/journal-token itself; it is never printed, copied or minted; a missing or refused token stops the step and asks the user |
|
||||
| T-20-51 | Denial of service | the shared host during the release | medium | mitigate | DEPLOY.md's release restarts only summercms-demo and summercms-demo-site; WavePath's pid is checked before and after; rollback with bin/demo.prev and site/.output.prev |
|
||||
| T-20-52 | Tampering | temporary integration leaking into a release | medium | mitigate | the scratch go.work and the tarball pins live outside the repos or are reverted in Task 2 (verify checks package.json and pnpm-lock.yaml are unchanged); build.sh release refuses dirty trees and pins off go.mod |
|
||||
| T-20-SC | Tampering | npm and Go installs | high | mitigate | only the project's own layers and plugins change version, by git tag; no third-party package is added or bumped; Go tidy runs against tags already on origin |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Task 1: the three checks pass against the unreleased fixes running together locally.
|
||||
- Task 2: every touched repository's full suite; the integration reverted; the release table.
|
||||
- Task 3: go-ahead for push and tags.
|
||||
- Task 4: remote heads and tags equal local HEAD.
|
||||
- Task 5: the demo on the tags, the listener on the rendered post, TestDemoModeration and check-pins green.
|
||||
- Task 6: check-all.sh --local ends with check-all: ok (release build and smoke included).
|
||||
- Task 7: go-ahead for push and deploy.
|
||||
- Task 8: pushed heads, the runbook release, check-live ok.
|
||||
- Task 9: live tokens or the user's manual answer.
|
||||
- Task 10: bypass probe and call probe against the live site, check-live and smoke again, changelog drafts clean.
|
||||
- Task 11: go-ahead for the posts.
|
||||
- Task 12: posts as answered; the ledger closed; twelve todos.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
The six fixed findings are released at patch tags, consumed by the demo, deployed on demo.summercms.io and proven there (bypass probe, call probe, check-live, smoke); the two plugin posts are handled as the user decided; 20-REVIEW-DISPOSITION.md has no open row and every deferred finding is a todo.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-09-SUMMARY.md` when done (it grows from the draft started in Task 2): the release table and tags, every checkpoint answer, the demo commits, the release id and rome results, the live probe results, the post URLs, the ledger changes and the todo list with g15office ids.
|
||||
</output>
|
||||
@@ -0,0 +1,147 @@
|
||||
# Phase 20: Demo instance with every shared plugin - Context
|
||||
|
||||
**Gathered:** 2026-10-28
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Phase 19.4.1 put `sm-demo-app` live on demo.summercms.io with the plugins of that time. This phase adds the chat family to that live instance and shows it working on the public Nuxt site: `chat`, `chatchannels`, `chatvideo`, `chatbots`, `forum`, `herald` and `userfriends` are mounted at tagged versions, seeded by `demo:seed`, deployed on rome, and given site UI through new shared Nuxt layers. Everything decided in 19.4.1 still holds (hosting on rome, own Centrifugo, `/backend` refused by nginx with the contact call to action, open registration behind Turnstile, the reset job, the demo banner, EN/PL, the summercms.io look). This phase does not repeat it.
|
||||
|
||||
New shared repos created by this phase: `vue-chat-layer`, `vue-chatvideo-layer`, `vue-forum-layer`, `vue-userfriends-layer`, `sm-moderation-plugin`.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Chat frontend
|
||||
- **D-01:** The chat UI is ported from `sm-bm-app`'s Vite SPA (`frontend/src/components/chat/`, `stores/chat.ts`, `api/chat.ts`, `lib/chat*.ts`, about 4.6k lines) into a new shared Nuxt layer, **`vue-chat-layer`**, consumed by `vue-demo-app` like the journal, menu, FAQ and paymentgateway layers. The layer is Golem15 code with no bm (JZ) specifics: BM link embeds, Terminarz deadline pins and other bm-only pieces are stripped or turned into slots or extension points. The layer names no application. — **Reversibility:** costly. A public layer with tagged releases; later sites pin it by tag.
|
||||
- **D-02:** The full bm feature set: channels, DMs, threads, mentions, reactions, typing, unread counts, attachments, member picker, delete dialog, embeds (generic link embeds only).
|
||||
- **D-03:** Chat appears as a full `/chat` page (channel sidebar, message pane) **and** a floating panel (DM list and unread badge) on every page for logged-in users. The homepage tour (19.4.1 D-11) gets a "Chat" card.
|
||||
- **D-04:** Anonymous visitors on `/chat` see a description and a "register to chat" prompt, the same pattern as quizzes (19.4.1 D-18). There is no read-only preview, and the floating panel is hidden for them.
|
||||
- **D-05:** Chatbots has no UI of its own. Its slash commands appear as a command picker in the `vue-chat-layer` composer. There is no `vue-chatbots-layer`.
|
||||
|
||||
### Chat context and access
|
||||
- **D-06:** One demo community: a single chat context (in the spirit of bm's `bm/1`, `plugins/jz/bm/classes/chat_context.go`, e.g. `demo/1`) implemented in `golem15.demo` as the host `contracts.Context` and the chatchannels `ChannelAccessResolver`. Every registered user is a member automatically.
|
||||
- **D-07:** Channels are **seeded only** (for example #general, #announcements, a Polish channel). Users join seeded channels and cannot create channels of any kind.
|
||||
- **D-08:** Any community member can DM any other member, as in bm. userfriends does not gate DMs.
|
||||
- **D-09:** `demo:seed` creates a handful of persona users with message history, threads, reactions and pins in EN and PL channels. The reset job (19.4.1 D-09) wipes and reseeds them along with everything else. There is no live bot persona.
|
||||
|
||||
### Video calls
|
||||
- **D-10:** LiveKit is self-hosted on rome under supervisor, next to the demo's Centrifugo (19.4.1 D-17), with its own keys in `.env`. The media ports (UDP range, TCP fallback, TURN/TLS through nginx stream or LiveKit's embedded TURN) are opened on rome and documented in `sm-demo-app/DEPLOY.md`. — **Reversibility:** reversible. Moving to LiveKit Cloud later only changes `golem15.chatvideo.livekit_*` config.
|
||||
- **D-11:** Calls start from DMs only. chat has DMs plus one context-wide group conversation (`GetGroupChat`) and no ad-hoc group DMs, and with D-07 there are no private channels, so in practice that means 1:1 calls. The researcher confirms this against the plugin. Calls are never started in seeded public channels.
|
||||
- **D-12:** Caps for a public demo: `max_duration` about 15 minutes, about 4 participants per room, the plugin's existing rate limits, and the `chatvideo:reconcile-sessions` job ending idle rooms.
|
||||
- **D-13:** The video UI is a **minimal call page** (own camera, remote tiles, mute, camera toggle, leave) built on `livekit-client` and released as the first version of a new shared **`vue-chatvideo-layer`**. bm has no video UI to port.
|
||||
|
||||
### Forum, friends, push
|
||||
- **D-14:** **`vue-forum-layer`** is a new shared layer with a `/forum` page: categories, threads and Markdown posts, seeded in EN and PL by `demo:seed`.
|
||||
- **D-15:** **`vue-userfriends-layer`** is a new shared layer: friends list, requests and friend groups. It is linked from the chat sidebar and the profile.
|
||||
- **D-16:** herald (Web Push) is mounted and configured (VAPID keys in `.env`) but has **no subscribe UI** in this phase.
|
||||
|
||||
### Moderation
|
||||
- **D-17:** A new shared plugin, **`sm-moderation-plugin`**, filters banned words and links in chat messages and forum posts. The banned-word and link lists are editable in its admin settings. On top of it: the plugins' rate limits, Turnstile on register (19.4.1 D-07), admins deleting messages and banning users from the backend, and the reset job.
|
||||
- **D-18:** chat and forum fire their festival events after the save (`events.MessageCreated` etc.), so the filter needs a **new, generic, additive pre-save seam** in `sm-chat-plugin` and `sm-forum-plugin`: a host- or plugin-registered validator that can reject a message or post before it is persisted. The change is additive and ships as patch tags. It must not change the existing PHP-parity API or payloads (these plugins are WavePath's port target, Phase 31), and the seam names no application. — **Reversibility:** costly. A public plugin contract other consumers can start using.
|
||||
|
||||
### Plan shape (suggestion; confirmed at plan time per the lean-planning rule)
|
||||
- **D-19:** Backend first, then layers. The suggested split from the discussion, before the forum and userfriends layers and the moderation plugin were added: 01 mount and tag the chat family, demo context, seed, LiveKit and the rome deploy (with the folded todo); 02 the `vue-chat-layer` port; 03 `vue-chatvideo-layer` plus herald config; 04 forum and friends layers, slash-command picker, tour cards; 05 unit tests and live verification. The planner fits in `sm-moderation-plugin`, the pre-save seams and the two extra layers, and presents the final count for confirmation.
|
||||
|
||||
### Plan-time decisions (2026-10-28, after research)
|
||||
- **D-20:** Six plans, as in `20-RESEARCH.md` § Suggested Plan Split: 01 shared plugin release (sibling fast-forward, go.mod fixes, chat and forum pre-save seams, `sm-moderation-plugin`, tags); 02 demo backend; 03 `vue-chat-layer` and its use in vue-demo-app; 04 the chatvideo, forum and userfriends layers, pages, tour cards, herald VAPID; 05 rome deploy (LiveKit, Vuurmuur rule as a checkpoint, nginx, `.env`, DEPLOY.md, check-deploy/check-live); 06 unit tests and live verification. 03 and 04 may run in parallel after 02.
|
||||
- **D-21:** Anonymous visitors on `/forum` see a description and a "register to join" prompt, as on `/chat` (D-04). No public forum read endpoint.
|
||||
- **D-22:** People-moderation uses a demo moderator user group (bm pattern) whose members can delete messages from the site UI; banning goes through the existing user admin. Chat-family admin screens are deferred.
|
||||
- **D-23:** chatvideo keeps about 4 participants per room (D-12). Calls are limited to DMs by the UI only: the call button appears only in DM conversations. The server does not refuse channel calls.
|
||||
|
||||
### Claude's Discretion
|
||||
- Seeded channel names and persona users, and how much EN/PL history to seed.
|
||||
- How LiveKit's media and TURN ports are exposed on rome (embedded TURN vs nginx stream), as long as calls work from typical NAT'd browsers.
|
||||
- The exact shape of the pre-save validator seam in chat and forum (interface name, registration through `pact` or the service registry), within D-18's constraints.
|
||||
- Which chatbots commands are registered for the demo (`/help`, `/demo`, …) and what they answer.
|
||||
- How `vue-chat-layer` exposes extension points for app-specific embeds.
|
||||
|
||||
### Folded Todos
|
||||
- **Commit sm-demo-app's leftover journal and oauthserver submodule moves** (`.planning/todos/pending/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md`, g15office `ssuyq2os`): sm-demo-app still shows `M plugins/golem15/oauthserver`. This phase bumps submodule pointers and go.mod requires anyway, so the first plan moves each checkout to the tag go.mod requires and makes one `chore: bump <plugin> to <tag>` commit per plugin before mounting the chat family. `TestGoModRequiresTags` and `scripts/check-pins.sh` must pass.
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Prior demo decisions
|
||||
- `.planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/19.4.1-CONTEXT.md` — hosting, accounts, reset job, banner, tour, EN/PL, look, Centrifugo, tagged-module go.mod (D-01..D-23)
|
||||
- `../sm-demo-app/DEPLOY.md` — rome layout, ports in use, supervisor programs, Centrifugo, release and rollback
|
||||
- `../sm-demo-app/README.md` — local run, `demo:seed`, credentials handling
|
||||
- `../sm-demo-app/summer.yaml`, `../sm-demo-app/go.mod` — the current plugin set and tagged requires
|
||||
|
||||
### Chat UI source (port)
|
||||
- `../sm-bm-app/frontend/src/components/chat/` — ChatPanel, MessageList, ChatMessage, ChatComposer, ChatHeader, DmList, MemberPicker, MentionPopup, ReactionBar, EmbedCard, EmbedPicker, StagingChips, DeleteDialog, Avatar
|
||||
- `../sm-bm-app/frontend/src/stores/chat.ts`, `../sm-bm-app/frontend/src/api/chat.ts`, `../sm-bm-app/frontend/src/lib/chat{Events,Format,Text,Unread}.ts` (with their tests)
|
||||
- `../sm-bm-app/plugins/jz/bm/classes/chat_context.go`, `../sm-bm-app/plugins/jz/bm/chat.go` — host context and access wiring to mirror in `golem15.demo`
|
||||
- `.planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/` plans for the presentations port (precedent for porting a bm Vite view into Nuxt)
|
||||
|
||||
### Plugins
|
||||
- `../sm-chat-plugin/README.md` — Context contract, Service, events, generic API, channel authorizer
|
||||
- `../sm-chatchannels-plugin/README.md` — channels, access resolver
|
||||
- `../sm-chatvideo-plugin/README.md` — LiveKit config keys, API, reconcile job, limits
|
||||
- `../sm-chatbots-plugin/README.md` — command catalog, dispatch, bot-auth seam
|
||||
- `../sm-forum-plugin/README.md`, `../sm-herald-plugin/README.md`, `../sm-userfriends-plugin/README.md`
|
||||
- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — chat port contract (PHP parity, D-07 generic API mirrors WavePath, which must not drift)
|
||||
- `.planning/phases/19.1-chat-satellites/19.1-CONTEXT.md` — satellites decisions
|
||||
- `.planning/notes/core-plugins-own-repos.md` — new shared plugin and layer repos, submodule mounting, commit order
|
||||
|
||||
### Existing layers (pattern)
|
||||
- `../vue-journal-layer`, `../vue-faq-layer`, `../vue-menu-layer`, `../vue-paymentgateway-layer`, `../vue-oauth-layer` — layer structure, tags, how `vue-demo-app` consumes them
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- bm chat SPA (about 4.6k lines with tests): the store, the API client and the event handling port almost directly; components need Nuxt/SSR guards (client-only realtime).
|
||||
- The demo's Centrifugo and `lighthouse` wiring from 19.4.1 plan 04 (speaker/remote sync) carries chat realtime too; chat authorizes `chat:conversation:{id}` and chatvideo `video:session:{id}`.
|
||||
- `golem15.demo` plugin and `demo:seed`, with the EN/PL seeding through translate (19.4.1 D-13).
|
||||
- The `realtime_test.go`, `seed_test.go`, `reset_test.go` and `go_mod_test.go` patterns in sm-demo-app for the new plugins.
|
||||
|
||||
### Established Patterns
|
||||
- Shared plugin and layer repos are their own git.golem15.com repos, mounted as submodules. Plugins are pushed and tagged first, then the pointer bump in the app goes in a separate commit.
|
||||
- `go.mod` requires tagged versions (19.4.1 D-03); `scripts/check-pins.sh` and `TestGoModRequiresTags` enforce checkouts at the tag.
|
||||
- chat/chatchannels APIs and events are PHP-parity contracts for WavePath (Phase 19 D-07, Phase 31). Changes are additive only.
|
||||
|
||||
### Integration Points
|
||||
- `golem15.demo`: chat `contracts.Context`, chatchannels `ChannelAccessResolver`, seed, moderation word lists, chatbots command registrations.
|
||||
- `vue-demo-app/nuxt.config.ts` `extends`: four new layers.
|
||||
- rome: new supervisor program for LiveKit, firewall and nginx changes, `.env` keys (LiveKit, VAPID).
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- "There is a simple chat view in sm-bm-app": port it rather than build chat UI from scratch.
|
||||
- The video UI starts small but as a reusable layer ("make it as initial vue-chatvideo-layer"), so later sites and the WavePath work can grow it.
|
||||
- The user prefers reusable shared pieces over demo-only code: a layer for each satellite with UI, and a shared moderation plugin rather than a filter inside `golem15.demo`.
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- Web Push subscribe UI (opt-in notifications for DMs and mentions, sharing the PWA service worker): herald is mounted without UI here.
|
||||
- User-created channels (public or private) and ad-hoc group DMs with group calls.
|
||||
- A live bot persona answering in channels.
|
||||
- A read-only `/chat` preview for anonymous visitors.
|
||||
- Admin screens for chat-family plugins (deleting messages from the backend); D-22 uses a site-side moderator group for now.
|
||||
|
||||
### Reviewed Todos (not folded)
|
||||
- "Prompt open admin and site tabs to reload when a new version is deployed": its site half was folded into 19.4.1 (D-22); the admin half is framework work, not this phase.
|
||||
- "Translate Messages as a Nuxt i18n JSON editor", "Port the menu plugin as sm-menu-plugin…", and the user/mfa/cabana/build todos that matched on keywords only: they are unrelated to the chat family on the demo.
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 20-demo-instance-with-every-shared-plugin*
|
||||
*Context gathered: 2026-10-28*
|
||||
@@ -0,0 +1,137 @@
|
||||
# Phase 20: Demo instance with every shared plugin - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-10-28
|
||||
**Phase:** 20-demo-instance-with-every-shared-plugin
|
||||
**Areas discussed:** Chat frontend source, Chat context & access, Video calls hosting, Abuse & satellites scope
|
||||
|
||||
The user corrected the opening premise: "There is simple chat view in sm-bm-app". bm's Vite SPA chat (about 4.6k lines) became the port source.
|
||||
|
||||
Folded todo: "Commit sm-demo-app's leftover journal and oauthserver submodule moves" (Fold it in).
|
||||
|
||||
---
|
||||
|
||||
## Chat frontend source
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| New vue-chat-layer | Shared Nuxt layer; bm-specific bits stripped or slots | ✓ |
|
||||
| Demo-only pages | Port into vue-demo-app as 19.4.1 did for presentations | |
|
||||
| Layer, but later | Demo-only now, extraction as backlog todo | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Full bm feature set | Channels, DMs, threads, mentions, reactions, typing, unread, attachments | ✓ |
|
||||
| Core only | Channels and DMs with realtime, unread, typing | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Dedicated /chat page | Full-page chat plus tour card | |
|
||||
| Page + floating panel | /chat plus floating DM/unread widget | ✓ |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Read-only #general preview | Live read-only seeded channel | |
|
||||
| Login prompt only | As quizzes D-18 | ✓ |
|
||||
|
||||
---
|
||||
|
||||
## Chat context & access
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| One demo community | Single context like bm/1 | ✓ |
|
||||
| Per-user workspaces | Users create contexts | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Seeded public + user private | Users create private channels | |
|
||||
| Anyone, any channel | | |
|
||||
| Seeded only | Join seeded channels, DM each other | ✓ |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Seeded users + history, EN/PL | Persona users with history | ✓ |
|
||||
| Plus a live bot | Bot answers slash commands | |
|
||||
| Empty channels | | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Any member of the community | userfriends does not gate DMs | ✓ |
|
||||
| Friends only | | |
|
||||
|
||||
---
|
||||
|
||||
## Video calls hosting
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Self-host on rome | LiveKit under supervisor, own keys | ✓ |
|
||||
| LiveKit Cloud free tier | | |
|
||||
| Decide in research | | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| DMs and private groups | No calls in public channels | ✓ |
|
||||
| Any conversation | | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| LiveKit components in the chat layer | Call view on livekit-client | |
|
||||
| Minimal call page | Bare-bones join page | ✓ (as the initial vue-chatvideo-layer) |
|
||||
|
||||
**Notes:** "make it as initial vue-chatvideo-layer". Since channels are seeded only and chat has no ad-hoc group DMs, calls are effectively 1:1 DMs.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Short calls, few people | ~15 min, ~4 participants | ✓ |
|
||||
| Plugin defaults | | |
|
||||
|
||||
---
|
||||
|
||||
## Abuse & satellites scope
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Rate limits + report + reset | No content filter | |
|
||||
| Plus a word filter | Banned words/link filter | ✓ |
|
||||
| Posting needs approval | | |
|
||||
|
||||
Follow-up, filter home: Hook in plugins + list in demo / Demo plugin only / **New shared plugin** ✓
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Forum page + friends in chat + /commands | Built in demo or chat layer | |
|
||||
| A layer for each | vue-forum-layer, vue-userfriends-layer | ✓ |
|
||||
| Forum only | | |
|
||||
|
||||
Follow-up, which layers: **forum + userfriends; commands in chat layer** ✓ / Also a vue-chatbots-layer
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Push for DMs and mentions | Opt-in notifications | |
|
||||
| Mounted, no UI | | ✓ |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Backend first, then layers | 5-plan split | ✓ |
|
||||
| You decide at plan time | | |
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Seeded channel names, personas, history volume
|
||||
- LiveKit port/TURN exposure on rome
|
||||
- Shape of the pre-save validator seam in chat and forum
|
||||
- Demo chatbots commands
|
||||
- vue-chat-layer extension points for embeds
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Web Push subscribe UI
|
||||
- User-created channels and ad-hoc group DMs/group calls
|
||||
- Live bot persona
|
||||
- Anonymous read-only chat preview
|
||||
@@ -0,0 +1,288 @@
|
||||
# Phase 20: Demo instance with every shared plugin - Pattern Map
|
||||
|
||||
**Mapped:** 2026-10-28
|
||||
**Files analyzed:** 34 (grouped by repo)
|
||||
**Analogs found:** 31 / 34
|
||||
|
||||
Paths are relative to the summercms.go repo root. The analogs are tracked source in their own repos. bm's `plugins/golem15/*` trees are nested submodules of sm-bm-app, and `plugins/jz/bm` is its own repo. Edit the shared plugins only in their `../sm-*-plugin` checkouts, after fast-forwarding them (RESEARCH Pitfall 1). Read the bm copies for reference only.
|
||||
|
||||
## File Classification
|
||||
|
||||
| New/Modified File | Role | Data Flow | Closest Analog | Match |
|
||||
|---|---|---|---|---|
|
||||
| `../sm-chat-plugin/events/events.go` (+`MessageSaving`) | event type | event-driven (pre-save) | `sm-user-plugin/classes/events.go` (DeactivatingEvent, lines 60-90) | role-match |
|
||||
| `../sm-chat-plugin/contracts/rejection.go` (new) | contract/error | request-response | none (new type); errors pattern in `chat/api/errors.go:35-45` | partial |
|
||||
| `../sm-chat-plugin/classes/service.go` (fire seam in `SendMessageWith`, `EditMessage`) | service | CRUD | itself, lines 287-345 | exact |
|
||||
| `../sm-chat-plugin/api/errors.go` (map Rejection to 422) | api helper | request-response | itself, `writeValidation` lines 39-44 | exact |
|
||||
| `../sm-forum-plugin/events/events.go` (new pkg, `PostSaving`) | event type | event-driven | chat `events/events.go` | role-match |
|
||||
| `../sm-forum-plugin/classes/forum_service.go` (fire in CreateThread/Reply/EditPost) | service | CRUD | itself, lines 263-300 (`Bus` field line 57-58, unused) | exact |
|
||||
| `../sm-forum-plugin/api/errors.go` | api helper | request-response | itself, `writeValidation` line 28, `writeForumError` line 44 | exact |
|
||||
| `../sm-chatvideo-plugin/go.mod`, `../sm-herald-plugin/go.mod`, `../sm-userfriends-plugin/go.mod` | config | n/a | `sm-bm-app/plugins/golem15/chatbots/go.mod` (commit d0b9fb1 "drop sibling replaces") | exact |
|
||||
| `../sm-moderation-plugin/plugin.go` | plugin entry | boot | `../sm-sitemap-plugin/plugin.go` lines 1-80 | role-match |
|
||||
| `../sm-moderation-plugin/admin.go` (HasSettings) | admin | CRUD (settings singleton) | `../sm-sitemap-plugin/admin.go` lines 40-72 | exact |
|
||||
| `../sm-moderation-plugin/models/settings.go` + `models/settings/fields.yaml` | model | CRUD | `../sm-sitemap-plugin/models/settings.go`, `models/settings/fields.yaml` | exact |
|
||||
| `../sm-moderation-plugin/classes/filter.go` | service | transform | none | no analog |
|
||||
| `../sm-moderation-plugin/updates/`, `lang/`, `config/`, `README.md` | migration/lang/config | n/a | `../sm-sitemap-plugin/{updates,lang,config,README.md}` | exact |
|
||||
| `../sm-demo-app/plugins/demo/chat.go` | host wiring | boot/event-driven | `../sm-bm-app/plugins/jz/bm/chat.go` lines 1-95 | exact |
|
||||
| `../sm-demo-app/plugins/demo/classes/chat_context.go` (DemoContext, ChannelContext adapter, access resolvers) | model/contract impl | request-response | `../sm-bm-app/plugins/jz/bm/classes/chat_context.go` | exact |
|
||||
| `../sm-demo-app/plugins/demo/realtime_access.go` | middleware | request-response | `../sm-bm-app/plugins/jz/bm/realtime_access.go` | exact |
|
||||
| `../sm-demo-app/plugins/demo/routes.go` (mountRealtime guard, chat bootstrap routes) | route | request-response | itself, lines 60-87 | exact |
|
||||
| `../sm-demo-app/plugins/demo/chat_api.go` (`GET /_demo/api/v1/chat`, `/chat/members`) | controller | request-response | `../sm-bm-app/plugins/jz/bm/controllers/api/chat.go`; style `plugins/demo/quizzes_api.go` | exact |
|
||||
| `../sm-demo-app/plugins/demo/chatbots.go` (demo commands) | service | request-response | RESEARCH Code Examples "Chatbots command"; contracts `chatbots/contracts/slash_command.go` | partial |
|
||||
| `../sm-demo-app/plugins/demo/plugin.go` (Requires, Middlewares, Boot calls registerChat) | plugin entry | boot | itself, lines 33-100 | exact |
|
||||
| `../sm-demo-app/plugins/demo/console/seed_chat.go`, `seed_forum.go`, `seed_friends.go` | console/seed | batch | `plugins/demo/console/seed.go` (`seedQuiz` 309-340, `insertID`/`exists` 177-189) | exact |
|
||||
| `../sm-demo-app/plugins/demo/console/reset.go` (`resetTables`) | console | batch | itself, lines 21-75 | exact |
|
||||
| `../sm-demo-app/{summer.yaml,go.mod,go.work,.gitmodules}` | config | n/a | existing entries (summer.yaml plugins list) | exact |
|
||||
| `../sm-demo-app/go_mod_test.go`, `boot_test.go`, `realtime_test.go`, `reset_test.go`, `seed_test.go` (extend) + new `chat_test.go`, `seed_chat_test.go` | test | n/a | the same files (`TestGoModRequiresTags` :22, `TestBootAllPlugins` :31, `TestRealtimeRoutes` :124) | exact |
|
||||
| `../sm-demo-app/deploy/centrifugo.json.example` (chat/user/video namespaces) | config | pub-sub | itself lines 41-46 + `../sm-bm-app/deploy/centrifugo/bm-config.json` lines 39+ | exact |
|
||||
| `../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf`, `deploy/livekit.yaml.example` | config | n/a | `deploy/supervisor/summercms-demo-centrifugo.conf`; RESEARCH supervisor block | exact |
|
||||
| `../sm-demo-app/deploy/nginx/demo.summercms.io.conf`, `scripts/{dev.sh,check-deploy.sh,check-live.sh,check-local.sh}`, `DEPLOY.md` | config/script | n/a | the same files (Centrifugo `/ws` sections) | exact |
|
||||
| `../vue-chat-layer/nuxt.config.ts`, `package.json` | config | n/a | `../vue-faq-layer/nuxt.config.ts`, `package.json` | exact |
|
||||
| `../vue-chat-layer/app/composables/useChatApi.ts` (auth hook `chatAuth`) | composable | request-response | `../vue-paymentgateway-layer/app/composables/usePaymentGatewayApi.ts` | exact |
|
||||
| `../vue-chat-layer/app/composables/useChat.ts` (store) | store | event-driven | `../sm-bm-app/frontend/src/stores/chat.ts` (Pinia setup store, convert) | role-match |
|
||||
| `../vue-chat-layer/app/lib/realtime.ts` (+`onUserEvent`) | utility | pub-sub | `../sm-demo-app/vue-demo-app/app/lib/realtime.ts` (`openChannel` :58, dynamic import :59) | exact |
|
||||
| `../vue-chat-layer/app/lib/chat{Events,Format,Text,Unread}.ts` + tests, `app/components/chat/*` | utility/component | transform | `../sm-bm-app/frontend/src/lib/chat*.ts`, `frontend/src/components/chat/*` | exact (port) |
|
||||
| `../vue-chat-layer/app/components/chat/{ChannelList,ThreadPane,PinsPanel,CommandPicker}.vue` | component | request-response | none in bm (bm has one channel, no threads/pins) | no analog |
|
||||
| `../vue-chatvideo-layer/*` (call page on livekit-client) | component/composable | streaming | none (bm has no video UI) | no analog |
|
||||
| `../vue-forum-layer/*`, `../vue-userfriends-layer/*` | layer | request-response | `../vue-faq-layer` (structure) + `../vue-paymentgateway-layer` (authenticated client) | role-match |
|
||||
| `../sm-demo-app/vue-demo-app/{nuxt.config.ts,package.json,app/plugins/auth.ts}` | config/provider | n/a | itself: `extends` line 51, layer deps lines 19-22, auth.ts | exact |
|
||||
| `../sm-demo-app/vue-demo-app/app/pages/{chat.vue,forum.vue,friends.vue,call/[id].vue}` | page | request-response | `app/pages/quizzes/index.vue` (anonymous register prompt, lines 46, 68) | exact |
|
||||
| `../sm-demo-app/vue-demo-app/app/pages/index.vue` (tour cards) | page | n/a | itself, `<TourCard` line 40 | exact |
|
||||
|
||||
Edit `sm-demo-app/vue-demo-app` (the submodule), not the stale `../vue-demo-app` (RESEARCH Anti-Patterns).
|
||||
|
||||
## Pattern Assignments
|
||||
|
||||
### Chat / forum pre-save seam (D-18)
|
||||
|
||||
**Event type analog:** `sm-user-plugin/classes/events.go` (read here at `../sm-demo-app/plugins/golem15/user/classes/events.go`), lines 13-17 and 74-86:
|
||||
```go
|
||||
const DeactivatingEventName = "user.Deactivating"
|
||||
// ... A listener error rolls the deactivation back.
|
||||
type DeactivatingEvent struct {
|
||||
User *models.User
|
||||
Tx *gorm.DB
|
||||
}
|
||||
```
|
||||
`MessageSaving` and `PostSaving` follow the same doc-comment style and add a `<Name>EventName` const. They fire **before** the transaction, so they carry no `Tx`.
|
||||
|
||||
**Fire site, chat:** `../sm-chat-plugin/classes/service.go` `SendMessageWith` (lines 287-345 at v0.1.3). Insert the call after the `ErrEmptyMessage` check (line ~311) and before `lagoon.Transaction`. Copy the existing nil-bus guard:
|
||||
```go
|
||||
if s.bus != nil {
|
||||
if err := s.bus.Fire(ctx, &events.MessageCreated{MessageEvent: events.MessageEvent{
|
||||
MessageID: msg.ID, ConversationID: conversationID, ActorID: senderID, RootID: rootID, Tx: tx,
|
||||
}}); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
```
|
||||
Do the same in `EditMessage` after `CanEditMessage`. `Fire` returns `errors.Join`, so callers use `errors.As`.
|
||||
|
||||
**Fire site, forum:** `../sm-forum-plugin/classes/forum_service.go` `CreateThread` lines 263-281. Fire between the `CanPost` check and `html := breakwater.Render(body)` (line 281). Do the same in `Reply` (line 316, before the Render at 330) and in `EditPost`. Use `s.Bus` (field at line 57-58), guarded for nil.
|
||||
|
||||
**422 mapping:** `../sm-chat-plugin/api/errors.go` lines 39-44 (forum: `api/errors.go:28`):
|
||||
```go
|
||||
func writeValidation(w http.ResponseWriter, errs map[string][]string) {
|
||||
wire.WriteJSON(w, http.StatusUnprocessableEntity, map[string]any{
|
||||
"error": errValidation,
|
||||
"errors": errs,
|
||||
})
|
||||
}
|
||||
```
|
||||
In the service-error mapper (`writeChatError` / `writeForumError` line 44), add `var rej contracts.Rejection; if errors.As(err, &rej) { writeValidation(w, map[string][]string{rej.Field: {rej.Message}}); return }` before the 500 default. With no listener registered, no existing branch changes.
|
||||
|
||||
**Tests:** keep `php_method_map_test.go` and `golden_test.go` green. Add the seam tests next to `tombstone_test.go` / `upload_limit_test.go`, using the `harness_test.go` fixture.
|
||||
|
||||
---
|
||||
|
||||
### `../sm-moderation-plugin` (new shared plugin)
|
||||
|
||||
**Plugin entry analog:** `../sm-sitemap-plugin/plugin.go` lines 1-60. Copy the package doc comment, the interface assertions and the embedded config:
|
||||
```go
|
||||
var (
|
||||
_ party.Plugin = (*Plugin)(nil)
|
||||
_ pact.HasConfig = (*Plugin)(nil)
|
||||
_ pact.HasMigrations = (*Plugin)(nil)
|
||||
_ pact.HasModels = (*Plugin)(nil)
|
||||
)
|
||||
//go:embed config
|
||||
var configFS embed.FS
|
||||
type Plugin struct { app *backpack.App }
|
||||
func (p *Plugin) ID() string { return "golem15.sitemap" }
|
||||
func (p *Plugin) Requires() []string { return nil }
|
||||
func (p *Plugin) Register(app *backpack.App) error { p.app = app; return nil }
|
||||
```
|
||||
Publish `*classes.Filter` from an `lagoon.OnDatabase` hook in Boot, the way chat publishes its Service (`app.Lookup[*chatclasses.Service]()` in bm chat.go:58). The plugin must not import chat or forum.
|
||||
|
||||
**Settings analog:** `../sm-sitemap-plugin/admin.go` lines 54-72:
|
||||
```go
|
||||
{
|
||||
Code: "sitemap_settings",
|
||||
Label: "golem15.sitemap::lang.settings.label",
|
||||
Description: "golem15.sitemap::lang.settings.description",
|
||||
Category: "golem15.sitemap::lang.settings.category",
|
||||
Icon: "settings",
|
||||
Permissions: []string{controllers.PermissionAccessDefinitions},
|
||||
Form: "models/settings/fields.yaml",
|
||||
NewModel: func() any { return &models.Settings{} },
|
||||
},
|
||||
// ...
|
||||
_ pact.HasSettings = (*Plugin)(nil)
|
||||
_ pact.HasLang = (*Plugin)(nil)
|
||||
```
|
||||
**Model:** `../sm-sitemap-plugin/models/settings.go` uses a singleton row id 1 on `golem15_<plugin>_settings`, `*string` columns, and validation in `BeforeValidate` with a lang-key error const (`errFrontendURL`). The moderation model gets `banned_words` and `banned_links` (textarea, one per line). **fields.yaml:** copy the header block and the `label/comment/type/span` shape from `../sm-sitemap-plugin/models/settings/fields.yaml`.
|
||||
|
||||
**Filter (no analog):** a stdlib-only `Check(ctx, text) *Violation`: case-insensitive word-boundary match for words; links matched by scheme, host or bare domain. Use table tests.
|
||||
|
||||
---
|
||||
|
||||
### `../sm-demo-app/plugins/demo/chat.go` (host wiring)
|
||||
|
||||
**Analog:** `../sm-bm-app/plugins/jz/bm/chat.go` lines 1-95.
|
||||
|
||||
Imports (lines 3-15). Swap the bm classes for `sm-demo-app/plugins/demo/classes` and add the forum, chatbots, moderation and chat events imports:
|
||||
```go
|
||||
chatclasses "git.golem15.com/golem15/sm-chat-plugin/classes"
|
||||
chatcontracts "git.golem15.com/golem15/sm-chat-plugin/contracts"
|
||||
chanclasses "git.golem15.com/golem15/sm-chatchannels-plugin/classes"
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
"git.golem15.com/golem15/summercms/modules/lagoon"
|
||||
```
|
||||
Core (lines 35-50, 72-87). Add a second `reg.Add` for `chanmodels.ChannelAlias` (RESEARCH Pattern 1):
|
||||
```go
|
||||
if app == nil || !app.HasPlugin("golem15.chat") { return nil }
|
||||
reg, ok := app.Lookup[*chatcontracts.Registry]()
|
||||
if !ok || reg == nil { return errors.New("jz.bm: golem15.chat must be listed before jz.bm in summer.yaml") }
|
||||
if err := reg.Add(p.ID(), chatcontracts.Registration{Alias: classes.ChatContextType, Loader: p.loadChatContext}); err != nil { return err }
|
||||
...
|
||||
return lagoon.OnDatabase(app, func(_ *sql.DB, _ *gorm.DB) error {
|
||||
svc, ok := app.Lookup[*chanclasses.ChannelService]()
|
||||
if !ok || svc == nil { return errors.New("... must be listed before ...") }
|
||||
svc.SetAccessResolver(classes.NewChatAccess(p.database, p.chatGroup(), nil))
|
||||
return nil
|
||||
})
|
||||
```
|
||||
Copy the config-key const block (lines 17-28) for `golem15.demo.chat.moderator_group` and the limits. The moderation listeners follow RESEARCH Pattern 2 (`app.Events.Listen[*chatevents.MessageSaving](p.ID(), ...)`).
|
||||
|
||||
### `../sm-demo-app/plugins/demo/classes/chat_context.go`
|
||||
|
||||
**Analog:** `../sm-bm-app/plugins/jz/bm/classes/chat_context.go`. Copy:
|
||||
- The interface assertions (lines 12-17).
|
||||
- The const block (lines 21-35): `ChatContextType = "demo"`, `ChatContextID = 1`, `ChatBroadcastChannel = "chat:context:1"`. The broadcast channel must never be empty.
|
||||
- `MemberFunc` injection and `WithMembership` for tests.
|
||||
- The five one-line methods (`ID/Type/ChatEnabled/GroupName/BroadcastChannel`).
|
||||
- `CanActFor` → `chatcontracts.DefaultCanActFor`; `CanOverseeChats` false.
|
||||
- `CanModerateMessage` limited to `conversationType == "group"` plus the moderator group (D-22).
|
||||
- `RequireLiveMembership` true.
|
||||
|
||||
Difference from bm: `HasMember` means "registered, not deleted, not banned". There is no group check (D-06), so drop `ChatMemberIDs`'s group join and query `users` directly. Add a `ChannelContext` with the same methods, loaded by channel id, and `BroadcastChannel() = "chat:channel:{id}"`.
|
||||
|
||||
### `../sm-demo-app/plugins/demo/realtime_access.go`
|
||||
|
||||
**Analog:** `../sm-bm-app/plugins/jz/bm/realtime_access.go` lines 1-70. Copy `MiddlewareRealtimeAccess` (name it `demo.realtime-access`), the `presentationsOwnerGuard` name const, the `sync.Once` owner-guard lookup, and the 401/503/member-pass flow (`bouncer.User(r.Context())`, `writeRealtimeGuard`). Then change `../sm-demo-app/plugins/demo/routes.go:78-86`. Mount when presentations **or** chat is active, and replace `"presentations.realtime-owner"` with the new guard:
|
||||
```go
|
||||
return lighthouse.Mount(r, p.realtime.Driver(), lighthouse.Surfaces{
|
||||
UserAuth: surf.Use("jwt.auth", "presentations.realtime-owner", bucketRealtime),
|
||||
ServerToServer: surf.Use(),
|
||||
Middleware: surf.Use(),
|
||||
})
|
||||
```
|
||||
`plugin.go` gains `pact.HasMiddleware` (`Middlewares() map[string]pact.Middleware`, bm realtime_access.go:24-29).
|
||||
|
||||
### `../sm-demo-app/plugins/demo/chat_api.go`
|
||||
|
||||
**Analog:** `../sm-bm-app/plugins/jz/bm/controllers/api/chat.go` (bootstrap JSON shape: channels with unread and mentions, DMs, members, limits). Mount it the way `routes.go:60-62` does: `r.Group(APIPrefix, surf.Use("jwt.auth", "throttle:120,1"), func(g pact.Router) { g.Get("/chat", ...) })`. Write errors with `wire.WriteJSON(w, status, map[string]string{"error": ...})` (routes.go:98).
|
||||
|
||||
### Seed and reset
|
||||
|
||||
**Seed analog:** `../sm-demo-app/plugins/demo/console/seed.go`:
|
||||
- Helpers at lines 177-189 (`exists`, `insertID` with `RETURNING id`).
|
||||
- `seedQuiz` (309-340) is the idempotent `(bool, error)` step shape, registered through `created(...)` in `runSeed` (40-80).
|
||||
- Use raw SQL only. Do not go through `chat.Service` or a `CreateChannel` gated by the resolver (RESEARCH Anti-Patterns).
|
||||
- Locale variants follow `seed_locales.go`.
|
||||
|
||||
**Reset analog:** `../sm-demo-app/plugins/demo/console/reset.go:21-40`, `resetTables []struct{ table, where string }`, children first. Insert the chat-family tables before `users` in the order from RESEARCH Pitfall 10. Keep `golem15_moderation_settings`.
|
||||
|
||||
### Tests (sm-demo-app)
|
||||
|
||||
Extend `go_mod_test.go:22 TestGoModRequiresTags` (its `wantPlugins` list), `boot_test.go:31 TestBootAllPlugins` (route prefixes), `realtime_test.go:124 TestRealtimeRoutes` (any member gets 200) and `reset_test.go`. New `chat_test.go` follows `demo_api_test.go`, and `seed_chat_test.go` follows `seed_test.go`, Docker-gated through `testmain_test.go`.
|
||||
|
||||
### Deploy config
|
||||
|
||||
- **Centrifugo:** `../sm-demo-app/deploy/centrifugo.json.example:41-46` uses the `{"name": ..., "subscribe_proxy_enabled": true}` format. Add `chat` (presence and join_leave options from `../sm-bm-app/deploy/centrifugo/bm-config.json` namespaces, line 39+), `user` and `video`. Keep the demo's option names, not bm's named proxies (RESEARCH A6).
|
||||
- **Supervisor:** copy `deploy/supervisor/summercms-demo-centrifugo.conf` to `summercms-demo-livekit.conf` using the RESEARCH "Supervisor program" block. **LiveKit yaml:** use the RESEARCH block (ports 7890/7891/7892).
|
||||
- **nginx:** add the `location ^~ /livekit/` block next to the existing `/ws` block in `deploy/nginx/demo.summercms.io.conf`, and extend the Go path allow-list with `/_chat/ /_chatchannels/ /_chatvideo/ /_chatbots/ /_forum/ /_userfriends/`.
|
||||
|
||||
---
|
||||
|
||||
### `../vue-chat-layer` (and the structure of the other three layers)
|
||||
|
||||
**Config analog:** `../vue-faq-layer/nuxt.config.ts`. Copy:
|
||||
- The header comment ("An app consumes it with `extends: [...]`").
|
||||
- `const currentDir = fileURLToPath(new URL('.', import.meta.url))` with absolute css paths.
|
||||
- `runtimeConfig.<x>.apiBase` (server, `NUXT_<X>_API_BASE`) and `runtimeConfig.public.<x>.apiBase` (same-origin).
|
||||
|
||||
Leave out the faq-specific `cachePurge`/`siteCache` keys. Add `public.chat.hostApiBase` (default `/_demo/api/v1` must NOT be hard-coded with an app name; default `''` and let the app set it) and `routeRules: { '/chat/**': { ssr: false } }`.
|
||||
|
||||
**package.json analog:** `../vue-faq-layer/package.json`: `"private": true, "type": "module", "main": "./nuxt.config.ts"`, `engines.node >=22.18`, `peerDependencies.nuxt 4.4.8`, devDeps nuxt 4.4.8 / typescript 5.9.3 / vue 3.5.35. For vue-chat-layer, replace the `node --test` script with vitest 3.2.7 and add `centrifuge@5.7.3`.
|
||||
|
||||
**Auth-hook client analog:** `../vue-paymentgateway-layer/app/composables/usePaymentGatewayApi.ts` lines 1-55. Copy the doc comment with the `defineNuxtPlugin` provide example, the hook lookup through `useNuxtApp()`, `Authorization: Bearer`, and the server-vs-browser base split:
|
||||
```ts
|
||||
type AuthHook = () => string | null | undefined
|
||||
const auth = (useNuxtApp() as unknown as { $paymentGatewayAuth?: AuthHook }).$paymentGatewayAuth
|
||||
const authHeaders = (): Record<string, string> => {
|
||||
const token = typeof auth === 'function' ? auth() : null
|
||||
return token ? { authorization: `Bearer ${token}` } : {}
|
||||
}
|
||||
```
|
||||
For chat, the hook becomes `$chatAuth: { token(), refresh(), unauthorized() }` (RESEARCH Pattern 4). The pure client goes in `app/utils/client.ts` (as in faq/paymentgateway `utils/client.ts`) so `tests/*.test.ts` can test it without Nuxt.
|
||||
|
||||
**App wiring:** `../sm-demo-app/vue-demo-app/app/plugins/auth.ts`:
|
||||
```ts
|
||||
export default defineNuxtPlugin(() => ({
|
||||
provide: { paymentGatewayAuth: () => useCookie<string | null>(DEMO_TOKEN_COOKIE).value ?? null },
|
||||
}))
|
||||
```
|
||||
Add `chatAuth` (and forum/friends/video hooks) to the same `provide`. Append the layers to `nuxt.config.ts:51` `extends`, and add `package.json` deps in the `git+https://git.golem15.com/golem15/vue-x-layer.git#vX.Y.Z` form (lines 19-22).
|
||||
|
||||
**Store port:** `../sm-bm-app/frontend/src/stores/chat.ts`. It imports `defineStore` from 'pinia' plus `@/api/chat`, `@/lib/chatEvents`, `@/stores/toast`. Convert it to a module-level composable that uses `useState` (no Pinia, 19.4.1). Replace `general`/`generalId` with `channels[]`. Strip the bm `embeds` lib (`deadline|class|reading`) and add a slot or renderer registry for it.
|
||||
|
||||
**Realtime analog:** `../sm-demo-app/vue-demo-app/app/lib/realtime.ts`: `REALTIME_WS_PATH = '/ws'` (:7), `UNAVAILABLE = new Set([401,403,404])` (:19), `tokenFailureIsFinal` (:22), `wsURL` (:42), `openChannel` with `await import('centrifuge')` (:58-59). Move it into the layer as one shared client and add `onUserEvent(handler)` (Pattern 3). vue-chatvideo-layer reuses it and must not open a second client.
|
||||
|
||||
**Pages, anonymous prompt analog:** `../sm-demo-app/vue-demo-app/app/pages/quizzes/index.vue`. The doc comment (line 4) covers the anonymous prompt; `registerLink` (line 46) is `{ path: '/register', query: { next } }`; line 68 renders `<NuxtLink class="button button--small" :to="registerLink(...)">{{ t('quiz.registerToTake') }}</NuxtLink>`. Apply it to `/chat` (D-04) and `/forum` (D-21). Tour cards follow `<TourCard` in `app/pages/index.vue:40`. Wrap the floating panel in `<ClientOnly>` in the app layout.
|
||||
|
||||
## Shared Patterns
|
||||
|
||||
### Host wiring through the service registry plus OnDatabase
|
||||
**Source:** `../sm-bm-app/plugins/jz/bm/chat.go:55-87`
|
||||
**Apply to:** demo chat.go (chat limits, chatchannels resolver, forum resolver, chatbots registry, moderation filter lookup). Use the guard `if !app.HasPlugin(id) { return nil }`, then `app.Lookup[*T]()` inside `lagoon.OnDatabase`. A missing service returns the error "must be listed before … in summer.yaml".
|
||||
|
||||
### Festival events with listener-error rollback
|
||||
**Source:** `sm-user-plugin/classes/events.go:60-110`, fire sites `classes/access_revoked.go:50`, `backend_links.go:358` (`app.Events.Fire(ctx, &X{...})`)
|
||||
**Apply to:** the chat and forum seams and the demo listeners.
|
||||
|
||||
### Error envelope
|
||||
**Source:** `../sm-chat-plugin/api/errors.go:35-45`, `../sm-forum-plugin/api/errors.go:24-44`: `{"error": msg}` and the 422 `{"error":"Validation failed","errors":{field:[msg]}}` through `wire.WriteJSON`.
|
||||
**Apply to:** the seam rejection and the demo chat bootstrap API.
|
||||
|
||||
### Layer conventions
|
||||
**Source:** `../vue-faq-layer` (config, package, `tests/*.test.ts`, `app/utils/client.ts` + `app/composables/use*Api.ts`), `../vue-paymentgateway-layer` (auth hook).
|
||||
**Apply to:** all four new layers. They name no app and have no Pinia.
|
||||
|
||||
### Release hygiene
|
||||
**Source:** `sm-bm-app/plugins/golem15/chatbots/go.mod` (commit d0b9fb1, no sibling replaces). Requires are tags only. `../sm-demo-app/scripts/check-pins.sh` and `go_mod_test.go:22`.
|
||||
**Apply to:** every plugin go.mod and the demo pointer bumps. Make one `chore: bump <plugin> to <tag>` commit per plugin.
|
||||
|
||||
## No Analog Found
|
||||
|
||||
| File | Role | Data Flow | Reason |
|
||||
|---|---|---|---|
|
||||
| `../sm-moderation-plugin/classes/filter.go` | service | transform | No text filter exists. Use RESEARCH D-17 test map (word boundary, links). |
|
||||
| `../vue-chat-layer` ChannelList / ThreadPane / PinsPanel / CommandPicker | component | request-response | bm UI has one channel, no threads or pins. Build on chatchannels pins and chat replies APIs (RESEARCH OQ 4). |
|
||||
| `../vue-chatvideo-layer` call page | component | streaming | No video UI anywhere. Use livekit-client (human-verify checkpoint first), loaded with dynamic `import()` like centrifuge. |
|
||||
|
||||
## Metadata
|
||||
|
||||
**Analog search scope:** sm-demo-app (plugins/demo, deploy, scripts, vue-demo-app), sm-bm-app (plugins/jz/bm, plugins/golem15/{chat,chatchannels,chatbots}, frontend/src), sm-forum-plugin, sm-sitemap-plugin, sm-user-plugin (via demo submodule), vue-faq-layer, vue-paymentgateway-layer
|
||||
**Files scanned:** ~40
|
||||
**Pattern extraction date:** 2026-10-28
|
||||
@@ -0,0 +1,694 @@
|
||||
# Phase 20: Demo instance with every shared plugin - Research
|
||||
|
||||
**Researched:** 2026-10-28
|
||||
**Domain:** Mounting the chat family (chat, chatchannels, chatvideo, chatbots, forum, herald, userfriends) into `sm-demo-app`, new shared Nuxt layers, a self-hosted LiveKit on rome, a new shared moderation plugin
|
||||
**Confidence:** HIGH for the backend and repo state (read and compiled this session), MEDIUM for LiveKit deployment, MEDIUM for the layer port effort
|
||||
|
||||
<user_constraints>
|
||||
## User Constraints (from CONTEXT.md)
|
||||
|
||||
### Locked Decisions
|
||||
|
||||
#### Chat frontend
|
||||
- **D-01:** The chat UI is ported from `sm-bm-app`'s Vite SPA (`frontend/src/components/chat/`, `stores/chat.ts`, `api/chat.ts`, `lib/chat*.ts`, about 4.6k lines) into a new shared Nuxt layer, **`vue-chat-layer`**, consumed by `vue-demo-app` like the journal, menu, FAQ and paymentgateway layers. The layer is Golem15 code with no bm (JZ) specifics: BM link embeds, Terminarz deadline pins and other bm-only pieces are stripped or turned into slots or extension points. The layer names no application. — **Reversibility:** costly. A public layer with tagged releases; later sites pin it by tag.
|
||||
- **D-02:** The full bm feature set: channels, DMs, threads, mentions, reactions, typing, unread counts, attachments, member picker, delete dialog, embeds (generic link embeds only).
|
||||
- **D-03:** Chat appears as a full `/chat` page (channel sidebar, message pane) **and** a floating panel (DM list and unread badge) on every page for logged-in users. The homepage tour (19.4.1 D-11) gets a "Chat" card.
|
||||
- **D-04:** Anonymous visitors on `/chat` see a description and a "register to chat" prompt, the same pattern as quizzes (19.4.1 D-18). There is no read-only preview, and the floating panel is hidden for them.
|
||||
- **D-05:** Chatbots has no UI of its own. Its slash commands appear as a command picker in the `vue-chat-layer` composer. There is no `vue-chatbots-layer`.
|
||||
|
||||
#### Chat context and access
|
||||
- **D-06:** One demo community: a single chat context (in the spirit of bm's `bm/1`, `plugins/jz/bm/classes/chat_context.go`, e.g. `demo/1`) implemented in `golem15.demo` as the host `contracts.Context` and the chatchannels `ChannelAccessResolver`. Every registered user is a member automatically.
|
||||
- **D-07:** Channels are **seeded only** (for example #general, #announcements, a Polish channel). Users join seeded channels and cannot create channels of any kind.
|
||||
- **D-08:** Any community member can DM any other member, as in bm. userfriends does not gate DMs.
|
||||
- **D-09:** `demo:seed` creates a handful of persona users with message history, threads, reactions and pins in EN and PL channels. The reset job (19.4.1 D-09) wipes and reseeds them along with everything else. There is no live bot persona.
|
||||
|
||||
#### Video calls
|
||||
- **D-10:** LiveKit is self-hosted on rome under supervisor, next to the demo's Centrifugo (19.4.1 D-17), with its own keys in `.env`. The media ports (UDP range, TCP fallback, TURN/TLS through nginx stream or LiveKit's embedded TURN) are opened on rome and documented in `sm-demo-app/DEPLOY.md`. — **Reversibility:** reversible. Moving to LiveKit Cloud later only changes `golem15.chatvideo.livekit_*` config.
|
||||
- **D-11:** Calls start from DMs only. chat has DMs plus one context-wide group conversation (`GetGroupChat`) and no ad-hoc group DMs, and with D-07 there are no private channels, so in practice that means 1:1 calls. The researcher confirms this against the plugin. Calls are never started in seeded public channels.
|
||||
- **D-12:** Caps for a public demo: `max_duration` about 15 minutes, about 4 participants per room, the plugin's existing rate limits, and the `chatvideo:reconcile-sessions` job ending idle rooms.
|
||||
- **D-13:** The video UI is a **minimal call page** (own camera, remote tiles, mute, camera toggle, leave) built on `livekit-client` and released as the first version of a new shared **`vue-chatvideo-layer`**. bm has no video UI to port.
|
||||
|
||||
#### Forum, friends, push
|
||||
- **D-14:** **`vue-forum-layer`** is a new shared layer with a `/forum` page: categories, threads and Markdown posts, seeded in EN and PL by `demo:seed`.
|
||||
- **D-15:** **`vue-userfriends-layer`** is a new shared layer: friends list, requests and friend groups. It is linked from the chat sidebar and the profile.
|
||||
- **D-16:** herald (Web Push) is mounted and configured (VAPID keys in `.env`) but has **no subscribe UI** in this phase.
|
||||
|
||||
#### Moderation
|
||||
- **D-17:** A new shared plugin, **`sm-moderation-plugin`**, filters banned words and links in chat messages and forum posts. The banned-word and link lists are editable in its admin settings. On top of it: the plugins' rate limits, Turnstile on register (19.4.1 D-07), admins deleting messages and banning users from the backend, and the reset job.
|
||||
- **D-18:** chat and forum fire their festival events after the save (`events.MessageCreated` etc.), so the filter needs a **new, generic, additive pre-save seam** in `sm-chat-plugin` and `sm-forum-plugin`: a host- or plugin-registered validator that can reject a message or post before it is persisted. The change is additive and ships as patch tags. It must not change the existing PHP-parity API or payloads (these plugins are WavePath's port target, Phase 31), and the seam names no application. — **Reversibility:** costly. A public plugin contract other consumers can start using.
|
||||
|
||||
#### Plan shape (suggestion; confirmed at plan time per the lean-planning rule)
|
||||
- **D-19:** Backend first, then layers. The suggested split from the discussion, before the forum and userfriends layers and the moderation plugin were added: 01 mount and tag the chat family, demo context, seed, LiveKit and the rome deploy (with the folded todo); 02 the `vue-chat-layer` port; 03 `vue-chatvideo-layer` plus herald config; 04 forum and friends layers, slash-command picker, tour cards; 05 unit tests and live verification. The planner fits in `sm-moderation-plugin`, the pre-save seams and the two extra layers, and presents the final count for confirmation.
|
||||
|
||||
#### Folded Todos
|
||||
- **Commit sm-demo-app's leftover journal and oauthserver submodule moves** (`.planning/todos/pending/2026-10-26-sm-demo-app-journal-oauthserver-pointers.md`, g15office `ssuyq2os`): sm-demo-app still shows `M plugins/golem15/oauthserver`. This phase bumps submodule pointers and go.mod requires anyway, so the first plan moves each checkout to the tag go.mod requires and makes one `chore: bump <plugin> to <tag>` commit per plugin before mounting the chat family. `TestGoModRequiresTags` and `scripts/check-pins.sh` must pass.
|
||||
|
||||
### Claude's Discretion
|
||||
- Seeded channel names and persona users, and how much EN/PL history to seed.
|
||||
- How LiveKit's media and TURN ports are exposed on rome (embedded TURN vs nginx stream), as long as calls work from typical NAT'd browsers.
|
||||
- The exact shape of the pre-save validator seam in chat and forum (interface name, registration through `pact` or the service registry), within D-18's constraints.
|
||||
- Which chatbots commands are registered for the demo (`/help`, `/demo`, …) and what they answer.
|
||||
- How `vue-chat-layer` exposes extension points for app-specific embeds.
|
||||
|
||||
### Deferred Ideas (OUT OF SCOPE)
|
||||
- Web Push subscribe UI (opt-in notifications for DMs and mentions, sharing the PWA service worker): herald is mounted without UI here.
|
||||
- User-created channels (public or private) and ad-hoc group DMs with group calls.
|
||||
- A live bot persona answering in channels.
|
||||
- A read-only `/chat` preview for anonymous visitors.
|
||||
|
||||
#### Reviewed Todos (not folded)
|
||||
- "Prompt open admin and site tabs to reload when a new version is deployed": its site half was folded into 19.4.1 (D-22); the admin half is framework work, not this phase.
|
||||
- "Translate Messages as a Nuxt i18n JSON editor", "Port the menu plugin as sm-menu-plugin…", and the user/mfa/cabana/build todos that matched on keywords only: they are unrelated to the chat family on the demo.
|
||||
</user_constraints>
|
||||
|
||||
<phase_requirements>
|
||||
## Phase Requirements
|
||||
|
||||
No requirement IDs are mapped (ROADMAP: "Requirements: TBD"). The success criteria and D-01..D-19 are the source of truth.
|
||||
|
||||
| ID | Description | Research Support |
|
||||
|----|-------------|------------------|
|
||||
| SC-1 | `sm-demo-app` builds with every shared plugin incl. chat, chatchannels, chatvideo, chatbots, forum, herald, userfriends; `demo:seed` fills each | §Repo state and tagging, §Demo host wiring, §Seeding |
|
||||
| SC-2 | Public Nuxt pages show chat/channels with realtime, video calls, presentations, journal, others through shared layers | §Layers, §Realtime, §LiveKit |
|
||||
| SC-3 | Deployed publicly; frontend open; `/backend` unreachable; "contact Golem15" CTA | §rome deployment, Open Question 1 |
|
||||
| SC-4 | New code unit-tested in the last plan | §Validation Architecture |
|
||||
</phase_requirements>
|
||||
|
||||
## Summary
|
||||
|
||||
The backend half is in better shape than the repo layout suggests, but every chat-family plugin needs release work before `sm-demo-app` can require it. Only `sm-chat-plugin` has tags (v0.1.0-v0.1.3 on origin). `chatchannels`, `chatbots`, `chatvideo`, `forum`, `herald` and `userfriends` have none. Three sibling checkouts (`../sm-chat-plugin`, `../sm-chatchannels-plugin`, `../sm-chatbots-plugin`) are **behind origin**; the current code lives in `sm-bm-app/plugins/golem15/*`. `chatvideo` still requires `sm-chat-plugin v0.0.0`, and `chatvideo` and `herald` keep sibling `replace` lines. I copied all seven trees to a scratch workspace, set their requires to tags (chat v0.1.3, user v0.1.13, summercms v0.5.1) and dropped the sibling replaces. With that, all seven `go build`, `go vet` and `go test -short` pass against framework **v0.5.1**, the version `sm-demo-app` pins. Without the go.mod fix, module resolution fails with `unknown revision v0.0.0`. So the gap is release hygiene, not framework drift.
|
||||
|
||||
The frontend half is larger than D-01's "port about 4.6k lines" implies. bm's chat SPA is built around **one** channel (`# ogólny`) plus DMs. Its store has `general`/`generalId` throughout. It has **no thread UI, no pins, no channel list**, and its embeds are bm entity types (`'deadline' | 'class' | 'reading'`), not link embeds. It also depends on a bm host bootstrap endpoint (`/_bm/api/v1/chat` and `/chat/members`). D-02 and D-07 (several seeded channels, threads, pins) therefore need new UI: a multi-channel store, a thread pane and a pins view. The demo also needs its own bootstrap endpoints in `golem15.demo`.
|
||||
|
||||
The backend gaps are small but each one blocks something:
|
||||
- `chatchannels` does not register the `channel` chat alias. Messages in channels made with `CreateChannel` resolve through a host "channel-as-context adapter", which `golem15.demo` must register.
|
||||
- The demo's realtime token route is limited to presentation owners. Chat needs every member to get a token.
|
||||
- Centrifugo needs the `chat`, `user` and `video` namespaces.
|
||||
- No chat-family plugin has admin screens. "Admins deleting messages from the backend" (D-17) has no UI today.
|
||||
|
||||
On rome, a WavePath LiveKit 1.13.1 already runs on 127.0.0.1:7880, 7881/tcp and 50000-60000/udp. Its media ports are defined in Vuurmuur but **not applied in the firewall rules**. The demo needs its own instance on free ports and a Vuurmuur rule.
|
||||
|
||||
**Primary recommendation:** Plan in three stages:
|
||||
1. Release work in the shared plugin repos: fast-forward the siblings, fix the go.mod files, add the pre-save seams, create `sm-moderation-plugin`, tag v0.1.x.
|
||||
2. Demo host wiring and seed: the context, the channel adapter, bootstrap endpoints, the realtime guard, Centrifugo namespaces, local LiveKit.
|
||||
3. Layers, with the realtime client living in `vue-chat-layer` and reused by `vue-chatvideo-layer`, then the rome deploy and the tests plan.
|
||||
|
||||
Set `golem15.chatvideo.max_participants: 2` so the server itself enforces D-11 (DM-only calls).
|
||||
|
||||
## Architectural Responsibility Map
|
||||
|
||||
| Capability | Primary Tier | Secondary Tier | Rationale |
|
||||
|------------|-------------|----------------|-----------|
|
||||
| Chat persistence, permissions, realtime publish | API / Backend (`golem15.chat`) | Database | Shared plugin; host only supplies context |
|
||||
| Demo community membership, channel adapter, channel/forum access policy | API / Backend (`golem15.demo`) | — | Host-specific policy (D-06); plugins stay neutral |
|
||||
| Chat bootstrap (channels with unread/mentions, DMs, members, limits) | API / Backend (`golem15.demo` `/_demo/api/v1/chat*`) | — | bm keeps this host-side (`/_bm/api/v1/chat`); generic APIs lack a "my conversations across contexts" call |
|
||||
| Pre-save content filter | API / Backend (`sm-moderation-plugin` service, wired by `golem15.demo` into chat/forum seams) | — | Must run before persistence; must not couple moderation to chat/forum modules |
|
||||
| Slash commands | API / Backend (`golem15.chatbots` registry, demo registers commands) | Browser (composer picker) | Dispatch runs as JWT actor server-side |
|
||||
| Video room lifecycle, tokens | API / Backend (`golem15.chatvideo`) | LiveKit SFU (rome) | Plugin mints tokens; media never touches Go |
|
||||
| Media transport | LiveKit SFU on rome (UDP mux / ICE-TCP) | Browser (`livekit-client`) | WebRTC needs direct ports, not nginx/Cloudflare |
|
||||
| Realtime fan-out | Centrifugo (demo instance) | API (subscribe proxy authorizers) | Already deployed in 19.4.1 |
|
||||
| Chat/forum/friends/video UI | Browser / Client (layers, client-only) | Frontend Server (SSR shell, `/forum` may SSR) | Chat and video touch window/WebSocket; SSR only the shell |
|
||||
| Anonymous prompts, tour cards | Frontend Server (vue-demo-app) | — | App-specific copy, EN/PL |
|
||||
|
||||
## Project Constraints (from CLAUDE.md)
|
||||
|
||||
- **Stdlib first.** A new Go dependency needs a research doc or decision note naming it. No new Go deps are needed beyond what the chat family already carries (`livekit/server-sdk-go/v2` and `SherClockHolmes/webpush-go` come in with `chatvideo` and `herald`). `sm-moderation-plugin` should be stdlib-only (+ `gorm`, framework modules).
|
||||
- **YAML** is parsed with `goccy/go-yaml`, never `gopkg.in/yaml.v3`.
|
||||
- **Framework code and shared plugins/layers never name a consuming application.** READMEs use neutral names (`blog`, `acme`). The pre-save seam, `sm-moderation-plugin` and every `vue-*-layer` follow this. `golem15.demo` may name itself.
|
||||
- **Core plugins: no breaking changes** (user, blog, pages, payment… and here chat/forum: WavePath parity, Phase 31). Seams are additive and ship as patch tags (D-18).
|
||||
- **Submodule commit order:** commit and push the plugin first, then the pointer bump in the app as a separate commit. Never stage files inside a submodule from the app repo. One `chore: bump <plugin> to <tag>` per plugin.
|
||||
- **go.mod requires tags only** (`TestGoModRequiresTags`, `scripts/check-pins.sh`); `go.work` handles local checkouts.
|
||||
- **Module/plugin READMEs** follow the standard structure (H1, summary, import, `**Name:**` mnemonic, Overview, Features, Usage, API reference, Configuration, CLI, Dependencies, Testing); every identifier must exist (docs checker for framework; plugin READMEs by hand).
|
||||
- **Lean planning:** few, large plans; present the plan count with one-line scopes and wait for confirmation. **Unit tests are the last plan.** STATE.md via `msd_run query state.*` handlers. g15office sync on phase advance.
|
||||
- **Commits:** no co-author tags (user's global CLAUDE.md overrides the harness attribution); stage files by explicit path; planning docs and code in separate commits. Don't push, tag or deploy without the user's go-ahead.
|
||||
- **Pushed release tags `vX.Y.Z`** of the framework get a changelog post on summercms.io the same day (only if this phase cuts a framework tag — not expected).
|
||||
- **Memory:** tag only at phase completion for the framework (interim plugin tags are fine). Add new shared plugins to the demo (this phase's whole point).
|
||||
- **Docker tests:** if the Docker socket is denied, run through `sudo -u golem`.
|
||||
|
||||
## Repo State and Tagging (verified this session)
|
||||
|
||||
| Plugin | Where current code lives | Origin `main` | Tags on origin | go.mod problems for module mode |
|
||||
|--------|-------------------------|---------------|----------------|----------------------------------|
|
||||
| `sm-chat-plugin` | `sm-bm-app/plugins/golem15/chat` (51c9e17 = v0.1.3) | 51c9e17 | v0.1.0, v0.1.1, v0.1.2, v0.1.3 | none (requires user v0.1.2, summercms v0.4.0) |
|
||||
| `sm-chatchannels-plugin` | `sm-bm-app/plugins/golem15/chatchannels` (a30f04a) | a30f04a | **none** | none (requires chat v0.1.0) |
|
||||
| `sm-chatbots-plugin` | `sm-bm-app/plugins/golem15/chatbots` (d0b9fb1 "drop sibling replaces") | d0b9fb1 | **none** | none (requires chat v0.1.0) |
|
||||
| `sm-chatvideo-plugin` | `../sm-chatvideo-plugin` (be688fe) | be688fe | **none** | `require sm-chat-plugin v0.0.0`; `replace sm-chat-plugin => ../sm-chat-plugin`; `replace sm-user-plugin => ../fonoteka.go/plugins/golem15/user` |
|
||||
| `sm-forum-plugin` | `../sm-forum-plugin` (2779341) | 2779341 | **none** | none |
|
||||
| `sm-herald-plugin` | `../sm-herald-plugin` (74c889c) | 74c889c | **none** | `replace sm-user-plugin => ../fonoteka.go/plugins/golem15/user` |
|
||||
| `sm-userfriends-plugin` | `../sm-userfriends-plugin` (57db2ba) | 57db2ba | **none** | requires chat pseudo-version `v0.0.0-20261017200243-4d0e764ca443` |
|
||||
|
||||
[VERIFIED: `git ls-remote origin` per repo; `git -C … log`; go.mod files read]
|
||||
|
||||
- **Sibling checkouts are stale:** `../sm-chat-plugin` is at 5fea654 (origin 51c9e17). `../sm-chatchannels-plugin` is at f3ac5d1 (origin a30f04a). `../sm-chatbots-plugin` is at 9dfe8b7 (origin d0b9fb1). Fast-forward (`git pull --ff-only`) before any edit.
|
||||
- **Compatibility proof:** in a scratch `go.work` I used framework v0.5.1 (from `git archive v0.5.1`) and user v0.1.13 (the demo's submodule), set every chat-family go.mod to `sm-chat-plugin v0.1.3`, `sm-user-plugin v0.1.13` and `summercms v0.5.1`, and removed the sibling replaces. All seven pass `go build ./...`, `go vet ./...` and `go test -short ./...`. Before the go.mod fix, every build failed with `git.golem15.com/golem15/sm-chat-plugin@v0.0.0: reading … go.mod at revision v0.0.0: unknown revision v0.0.0`. [VERIFIED: scratch build output]
|
||||
- **Suggested tags** (one-way, D-03 of 19.4.1):
|
||||
|
||||
| Plugin | Tag |
|
||||
|--------|-----|
|
||||
| chat | v0.1.4: pre-save seam, additive (patch) |
|
||||
| chatchannels | v0.1.0 |
|
||||
| chatbots | v0.1.0 |
|
||||
| chatvideo | v0.1.0, after the go.mod fix |
|
||||
| forum | v0.1.0, with the seam (its first tag) |
|
||||
| herald | v0.1.0, after dropping the replace |
|
||||
| userfriends | v0.1.0, chat requirement → v0.1.3 or v0.1.4 |
|
||||
| sm-moderation-plugin | v0.1.0 |
|
||||
|
||||
Raising the minimal `summercms` / `sm-user-plugin` requires in plugin go.mod files is optional (MVS picks the demo's v0.5.1 / v0.1.13). Keep the `replace git.golem15.com/golem15/summercms => ../summercms.go` line, the standard plugin pattern.
|
||||
- **bm is unaffected:** `sm-bm-app` pins chatchannels and chatbots as `v0.0.0` with local `replace` lines. It keeps building whatever the new tags are.
|
||||
- **Folded todo (oauthserver):** the `sm-demo-app` submodule is at b6a9586 (`v0.1.2-7-gb6a9586`, uncommitted move). The index has 8bbec72 = v0.1.2, and go.mod requires v0.1.2. Tag v0.1.3 = df2eddd ("require SummerCMS v0.5.0 and sm-user-plugin v0.1.11") contains b6a9586. Move the checkout to v0.1.3, run `GOWORK=off go get git.golem15.com/golem15/sm-oauthserver-plugin@v0.1.3` then `go mod tidy`, and commit `chore: bump sm-oauthserver-plugin to v0.1.3`. The journal half of the todo is already done (`11d485f chore: bump journal to v0.2.5`). [VERIFIED: `git submodule status`, `git log`]
|
||||
|
||||
## Standard Stack
|
||||
|
||||
### Core (backend, all already chosen in Phases 19/19.1)
|
||||
| Library / module | Version | Purpose | Why Standard |
|
||||
|------------------|---------|---------|--------------|
|
||||
| `git.golem15.com/golem15/summercms` | v0.5.1 (demo pin; v0.5.2 exists) | Framework | Demo already on it; chat family proven on it this session |
|
||||
| `sm-chat-plugin` | v0.1.3 → v0.1.4 (seam) | Conversations, messages, reactions, attachments | Phase 19 port |
|
||||
| `sm-chatchannels-plugin` | first tag v0.1.0 | Channels, pins, mentions | Phase 19 port |
|
||||
| `sm-chatvideo-plugin` | first tag v0.1.0 | LiveKit sessions, tokens, reconcile | Phase 19.1 |
|
||||
| `sm-chatbots-plugin` | first tag v0.1.0 | Slash command registry/dispatch | Phase 19.1 |
|
||||
| `sm-forum-plugin` | first tag v0.1.0 (seam) | Forum | Phase 19.1 |
|
||||
| `sm-herald-plugin` | first tag v0.1.0 | Web Push (mounted, no UI) | Phase 19.1 |
|
||||
| `sm-userfriends-plugin` | first tag v0.1.0 | Friends, groups | Phase 19.1 |
|
||||
| `github.com/livekit/server-sdk-go/v2` | v2.19.0 (transitive via chatvideo) | RoomService client | Already in chatvideo go.mod |
|
||||
| LiveKit server | 1.13.1 (installed on rome `/usr/local/bin/livekit-server` and locally) | SFU | Same binary WavePath runs; no install needed |
|
||||
| Centrifugo | v6.5.1 (rome and local) | Realtime | Already the demo's (D-17) |
|
||||
|
||||
### Frontend
|
||||
| Library | Version | Purpose | When to Use |
|
||||
|---------|---------|---------|-------------|
|
||||
| `nuxt` | 4.4.8 (pinned across layers) | Layers and app | All layers `peerDependencies: { nuxt: 4.4.8 }` |
|
||||
| `vue` | 3.5.35 | — | — |
|
||||
| `centrifuge` | 5.7.3 (already pinned in vue-demo-app; audited in 19.4.1) | Centrifugo client | Move/duplicate into `vue-chat-layer` deps at the same pin |
|
||||
| `livekit-client` | 2.23.0 latest (published 2026-10-16) `[WARNING: flagged as suspicious — verify before using.]` | WebRTC client for `vue-chatvideo-layer` | Pin an exact version after the human-verify checkpoint |
|
||||
| `vitest` | 3.2.7 (vue-demo-app's pin) | Layer unit tests for the ported bm tests | bm's chat tests are vitest |
|
||||
|
||||
**No Pinia.** 19.4.1 established "Pinia stores become `useState` composables" (19.4.1-PATTERNS.md:259; 19.4.1-04-PLAN.md:134). `@pinia/nuxt` 1.0.3 peers `pinia ^4.1.0` and depends on `@nuxt/kit ^4.6.0`, against the repo's `nuxt` 4.4.8. bm's store is a setup store (`defineStore('chat', () => {…})`), so converting it to a module-level factory or composable is mechanical. [VERIFIED: npm view @pinia/nuxt peerDependencies dependencies]
|
||||
|
||||
### Alternatives Considered
|
||||
| Instead of | Could Use | Tradeoff |
|
||||
|------------|-----------|----------|
|
||||
| Own LiveKit instance on rome | Add a key pair to WavePath's LiveKit (`/etc/livekit/livekit.yaml`) | Any API key can list/delete every room on that server; cross-tenant blast radius; D-10 says own keys → use own instance |
|
||||
| UDP mux (`rtc.udp_port`) | Port range (`port_range_start/end`) | Range needs a wide firewall hole and overlaps WavePath's 50000-60000; mux needs one port |
|
||||
| Embedded TURN/TLS on 443 via nginx `stream` `ssl_preread` | No TURN, ICE-TCP fallback (`rtc.tcp_port`) | `ssl_preread` would restructure every 443 vhost on a shared host; ICE-TCP covers most NAT'd browsers |
|
||||
| Festival "-ing" event as pre-save seam | Validator registry on the services (`Service.AddValidator`) | Both additive; festival mirrors `user.Deleting`/`user.Deactivating` and needs no new type on the service |
|
||||
|
||||
**Installation (layers):**
|
||||
```bash
|
||||
# vue-chat-layer
|
||||
pnpm add centrifuge@5.7.3
|
||||
pnpm add -D vitest@3.2.7 nuxt@4.4.8 vue@3.5.35 typescript@5.9.3
|
||||
# vue-chatvideo-layer (after checkpoint:human-verify on livekit-client)
|
||||
pnpm add livekit-client@<pinned>
|
||||
```
|
||||
|
||||
**Version verification:** `npm view livekit-client version` → 2.23.0 (2026-10-16). `npm view centrifuge version` → 5.8.0 (2026-10-20); the demo stays on the audited 5.7.3. [VERIFIED: npm registry]
|
||||
|
||||
## Package Legitimacy Audit
|
||||
|
||||
| Package | Registry | Age (latest) | Downloads | Source Repo | Verdict | Disposition |
|
||||
|---------|----------|-----|-----------|-------------|---------|-------------|
|
||||
| `livekit-client` | npm | latest 12 days | 5.67M/wk | github.com/livekit/client-sdk-js | [SUS] reason `too-new` | Flagged — planner must add checkpoint:human-verify; pin an exact version |
|
||||
| `centrifuge` | npm | latest 8 days | 1.61M/wk | github.com/centrifugal/centrifuge-js | [SUS] reason `too-new` (latest only) | Keep the already-audited 5.7.3 pin from 19.4.1; no new install decision |
|
||||
| `pinia`, `@pinia/nuxt` | npm | — | — | github.com/vuejs/pinia | [SUS] `too-new` | Not recommended (see above) |
|
||||
|
||||
No postinstall scripts on `livekit-client` or `centrifuge` (`npm view … scripts.postinstall` empty). `centrifuge` pulls `protobufjs`, whose postinstall is already disabled in `pnpm-workspace.yaml` (`protobufjs: false`).
|
||||
|
||||
**Packages removed due to [SLOP] verdict:** none
|
||||
**Packages flagged as suspicious [SUS]:** `livekit-client`: the planner inserts checkpoint:human-verify before the install. The "too-new" verdict is about the latest release, not the package. It is LiveKit's official JS SDK, but its name came to me from training and the chatvideo README, not from Context7, so treat it as `[ASSUMED]` until verified.
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### System Architecture Diagram
|
||||
|
||||
```
|
||||
Browser (vue-demo-app + layers, client-only chat/video)
|
||||
│ JWT (DEMO cookie) as Bearer
|
||||
├─ GET /_demo/api/v1/chat ─────────────► golem15.demo bootstrap ──► chat.Service.GetConversationsForUser
|
||||
│ chatchannels.ChannelService (channels, mention counts)
|
||||
├─ /_chat/api/v1/... (send/edit/react/replies/upload) ──► chat.Service
|
||||
│ └─ [NEW] Fire MessageSaving (pre-save) ──► demo listener ──► moderation.Filter.Check ──► 422 or continue
|
||||
│ └─ tx: insert ─► Fire MessageCreated ─► chatchannels mentions; lighthouse Bind ─► broadcasts queue ─► Centrifugo publish
|
||||
├─ /_chatchannels/api/v1/contexts/demo/1/channels/... (join, pins, mentions)
|
||||
├─ /_chatbots/api/v1/commands | /dispatch ─► chatbots Registry (demo-registered commands, ephemeral answers)
|
||||
├─ /_forum/api/v1/contexts/demo/1/... ─► forum.Service ─► [NEW] Fire PostSaving ─► moderation ─► persist (breakwater render)
|
||||
├─ /_userfriends/api/v1/...
|
||||
├─ /_chatvideo/api/v1/conversations/{dm}/video/start ─► chatvideo (participants ≤ max_participants=2 ⇒ DMs only)
|
||||
│ └─ RoomAPI ─► http://127.0.0.1:<lk-signal> (loopback, TrustedMode) ; returns {token, livekit_url}
|
||||
├─ GET /api/realtime/token ─► demo guard (any member) ─► lighthouse token
|
||||
├─ wss /ws ─► nginx ─► Centrifugo (demo) ──subscribe proxy──► Go authorizers: chat / user / video / presentations
|
||||
└─ wss /livekit/rtc ─► Cloudflare ─► nginx ─► LiveKit (demo instance) signal
|
||||
media: UDP <mux port> / TCP <ice-tcp port> direct to rome public IP (bypasses Cloudflare)
|
||||
```
|
||||
|
||||
### Recommended Project Structure
|
||||
|
||||
```
|
||||
sm-moderation-plugin/ # new shared plugin (golem15.moderation)
|
||||
├── plugin.go admin.go # pact.HasSettings, HasMigrations, HasConfig, HasLang
|
||||
├── classes/filter.go # Filter.Check(ctx, text) -> *Violation (words, links)
|
||||
├── models/settings.go + models/settings/fields.yaml
|
||||
├── updates/ lang/ config/
|
||||
sm-demo-app/plugins/demo/
|
||||
├── chat.go # registry aliases "demo" + "channel", resolvers, limits, seam listeners, chatbots commands
|
||||
├── classes/ (or chat_context.go) # DemoContext, ChannelContext adapter, access resolvers (chatchannels, forum)
|
||||
├── chat_api.go # GET /_demo/api/v1/chat, /chat/members (bootstrap)
|
||||
├── console/seed_chat.go seed_forum.go seed_friends.go
|
||||
vue-chat-layer/ # new
|
||||
├── app/components/chat/… # ported + ChannelList, ThreadPane, PinsPanel, CommandPicker
|
||||
├── app/composables/useChat.ts # ported store (no Pinia)
|
||||
├── app/lib/realtime.ts # shared Centrifuge client + onUserEvent hook (used by chatvideo layer)
|
||||
├── app/lib/chat{Events,Format,Text,Unread}.ts (+ tests)
|
||||
├── app/pages/chat.vue # optional; or app provides page and renders <ChatPage>
|
||||
vue-chatvideo-layer/ # extends vue-chat-layer
|
||||
vue-forum-layer/ vue-userfriends-layer/
|
||||
```
|
||||
|
||||
### Pattern 1: Host context and channel-as-context adapter (golem15.demo)
|
||||
**What:** Register two aliases on `*chatcontracts.Registry`:
|
||||
- `demo`: one context, id 1. Every registered, non-deleted, non-banned user is a member.
|
||||
- `channel`: loads a `chatchannels` channel by id. Its members are the demo community's members, since every channel is public (D-07).
|
||||
|
||||
Install `chatchannels` `SetAccessResolver` (any member may access `demo/1`, nobody manages it) and `forum.SetAccessResolver`.
|
||||
**Why the `channel` alias is required:** `CreateChannel` writes the backing conversation with `ContextType: &alias` where `alias := models.ChannelAlias` (`"channel"`) [VERIFIED: sm-bm-app/plugins/golem15/chatchannels/classes/channel_service.go:168-174]. No production code registers that alias. The only `Alias: models.ChannelAlias` registration is the test fixture [VERIFIED: chatchannels/fixture_plugin_test.go:172]. Without it, chat resolves the conversation's context to `ErrUnknownContextType` (404).
|
||||
**Lazy join:** `JoinChannel` only upserts a pref row (`row.HasLeft = false`) and adds no chat participant [VERIFIED: channel_service.go:959-969]. Sending needs `isParticipant` [VERIFIED: chat/classes/service.go:463-468], while reading falls back to `host.HasMember` [VERIFIED: service.go:630-640]. The client gets participant rows by calling `GET /_chat/api/v1/contexts/channel/{channelId}/conversation`, where `GetGroupChat` "still lazy-joins a context member" (chat README). Alternatively, the demo bootstrap adds the participant. Choose one and test it.
|
||||
**Example (mirror bm):**
|
||||
```go
|
||||
// Source: sm-bm-app/plugins/jz/bm/chat.go:35-90 (pattern), adapted
|
||||
func (p *Plugin) registerChat(app *backpack.App) error {
|
||||
reg, ok := app.Lookup[*chatcontracts.Registry]()
|
||||
if !ok || reg == nil { return errors.New("golem15.demo: golem15.chat must boot first") }
|
||||
if err := reg.Add(p.ID(), chatcontracts.Registration{Alias: "demo", Loader: p.loadDemoContext}); err != nil { return err }
|
||||
if err := reg.Add(p.ID(), chatcontracts.Registration{Alias: chanmodels.ChannelAlias, Loader: p.loadChannelContext, LegacyPHPClass: chanmodels.ChannelMorphName}); err != nil { return err }
|
||||
return lagoon.OnDatabase(app, func(_ *sql.DB, _ *gorm.DB) error {
|
||||
ch, _ := app.Lookup[*chanclasses.ChannelService]()
|
||||
ch.SetAccessResolver(p.channelAccess) // CanAccessContext: member && demo/1; CanManageContext: false
|
||||
f, _ := app.Lookup[*forum.Plugin]()
|
||||
f.SetAccessResolver(p.forumAccess) // CanRead/CanPost: member; CanManage: moderator group
|
||||
// chatbots registry is published inside its own OnDatabase hook (chatbots/boot.go bootService)
|
||||
bots, _ := app.Lookup[*botclasses.Registry]()
|
||||
return registerDemoCommands(bots)
|
||||
})
|
||||
}
|
||||
```
|
||||
`BroadcastChannel()` must be non-empty for both contexts ("an empty host channel silences the conversation channels too", bm chat_context.go:31-35). Use names no client can subscribe to, for example `chat:context:1` and `chat:channel:{id}`. `AuthorizeChat` admits only `chat:conversation:{id}`.
|
||||
Implement `contracts.LiveMembership` (`RequireLiveMembership() true`) and `contracts.MessageModerator`, as bm does, so that banned users lose access at the next check and a moderator group can delete messages in group conversations.
|
||||
|
||||
### Pattern 2: Additive pre-save seam (D-18), recommended shape
|
||||
**What:** Use a festival "-ing" event, fired **before** the write transaction, mirroring `user.Deleting` / `user.Deactivating` (sm-user-plugin/classes/events.go: "A listener error rolls the deactivation back").
|
||||
- chat: `events.MessageSaving{ConversationID, ActorID, RootID, Content, Metadata, Op}`, where `Op` is `"create"` or `"update"`. Fire it in `SendMessageWith` after the participant and empty checks, and in `EditMessage` after `CanEditMessage`.
|
||||
- forum: `events.PostSaving{ContextType, ContextID, ActorID, ThreadID, PostID, Title, Body, Op}`. Fire it in `CreateThread`, `Reply` and `EditPost` before `breakwater.Render`.
|
||||
- A listener rejects with a typed error, for example `contracts.Rejection{Field, Message}`, implementing `error`. The services return it wrapped. The API maps `errors.As(err, &contracts.Rejection{})` to the **existing** 422 envelope `{"error":"Validation failed","errors":{field:[message]}}` (chat api/errors.go:39-44, forum api/errors.go). Every existing route, payload and status stays the same. Only a request a listener rejects gets the new 422.
|
||||
- With no listener, behaviour is byte-identical (WavePath parity; the PHP method map tests stay green).
|
||||
|
||||
**Why not the existing events:** `MessageCreated` fires inside the transaction after `tx.Create(msg)` (service.go SendMessageWith). A listener error there rolls back, but it maps to 500 (the `writeChatError` default) and burns an id. **Forum fires no festival events at all.** `grep "Fire("` over sm-forum-plugin finds none, and `ForumService` has a `Bus` field (classes/forum_service.go:57-58) that is never used. CONTEXT's "chat and forum fire their festival events after the save" is accurate only for chat.
|
||||
|
||||
**Coupling:** `sm-moderation-plugin` must not import chat or forum. It publishes a `*classes.Filter`, and `golem15.demo` (which already imports both) wires it:
|
||||
```go
|
||||
// Source: pattern from festival bus.go:43 (Listen[T]) and user events
|
||||
app.Events.Listen[*chatevents.MessageSaving](p.ID(), func(ctx context.Context, ev *chatevents.MessageSaving) error {
|
||||
if v := filter.Check(ctx, ev.Content); v != nil {
|
||||
return chatcontracts.Rejection{Field: "content", Message: v.Message}
|
||||
}
|
||||
return nil
|
||||
})
|
||||
```
|
||||
Note: `festival.Bus.Fire` returns `errors.Join` of the listener errors (bus.go:74-75), so callers must use `errors.As`, not `==`.
|
||||
|
||||
### Pattern 3: One shared realtime connection across layers
|
||||
bm's `lib/realtime.ts` keeps a single Centrifuge client (`connect`, `subscribe`, `presence`). The chat store subscribes to `user:{me}` for the whole session. chatvideo publishes `video:call:incoming` to `user:{id}` (chatvideo README). One client cannot hold two subscriptions to the same channel, so `vue-chatvideo-layer` must **not** open its own `user:{me}` subscription. Put the realtime client in `vue-chat-layer` and add `onUserEvent(handler)` so unknown `user:` events (`video:*`) reach other layers. `vue-chatvideo-layer` `extends` `vue-chat-layer` and subscribes to `video:session:{id}` through the same client.
|
||||
|
||||
### Pattern 4: Layer conventions (from vue-faq-layer, vue-paymentgateway-layer, vue-oauth-layer)
|
||||
- `nuxt.config.ts` builds absolute paths from `fileURLToPath(new URL('.', import.meta.url))`.
|
||||
- runtimeConfig has a server `apiBase` (`NUXT_<X>_API_BASE`) and a public same-origin `apiBase`.
|
||||
- `peerDependencies: { nuxt: 4.4.8 }` and `engines.node >=22.18`.
|
||||
- Tests run with `node --test --test-reporter=tap tests/*.test.ts`.
|
||||
- Each layer is consumed as `"vue-x-layer": "git+https://git.golem15.com/golem15/vue-x-layer.git#vX.Y.Z"`.
|
||||
- **Auth hook:** the app provides a token getter through a Nuxt plugin (`provide: { paymentGatewayAuth: () => useCookie(DEMO_TOKEN_COOKIE).value ?? null }`, vue-demo-app/app/plugins/auth.ts). The chat layer needs more than a getter: a 401 refresh (bm's client calls `/_user/api/v1/fetch` to renew) and an `onUnauthorized`. Define a `chatAuth` hook with `token()`, `refresh()` and `unauthorized()`, or let the app inject the whole HTTP client.
|
||||
- **Host bootstrap contract:** the layer reads `public.chat.hostApiBase` (for example `/_demo/api/v1`) and documents the `GET {hostApiBase}/chat` and `/chat/members` JSON shapes as the layer's contract. Any host implements them, so the layer names no app.
|
||||
- **SSR:** `routeRules` `ssr: false` for `/chat/**` and the call page. The floating panel goes in `<ClientOnly>` in the app's layout, because a layer cannot inject into the app's layout.
|
||||
|
||||
### Pattern 5: DM-only calls enforced server-side (D-11)
|
||||
`VideoService.Start` checks only that the actor is a participant and that the conversation's participant count is at most `golem15.chatvideo.max_participants` (`max := s.intKey("golem15.chatvideo.max_participants", 8); if max > 0 && len(memberIDs) > max { return nil, ErrTooMany }`) [VERIFIED: sm-chatvideo-plugin/classes/video_service.go:109-112]. Conversation type is not checked, so **the plugin does not restrict calls to DMs.** `GetOrCreateDm` creates two-person DMs only. With `max_participants: 2` and every seeded channel holding three or more participants, `Start` on any channel or group conversation answers 422 `errTooMany` [VERIFIED: chatvideo/api/errors.go:42-43]. That is server-side enforcement of D-11 with no plugin change. The UI shows the call button only in DMs. LiveKit's `room.max_participants: 4` is a second cap. `Join` does not check counts (video_service.go:171-195), but only conversation participants can get a session (`sessionForActor`).
|
||||
|
||||
### Anti-Patterns to Avoid
|
||||
- **Seeding channels through `CreateChannel` with the demo's resolver.** It is gated by `CanManageContext` [VERIFIED: channel_service.go:136], which the demo answers false (D-07). Seed with a separate trusted instance instead, `chanclasses.New(chanclasses.Options{DB: tx, Resolver: seedResolver})`, or with raw SQL in the existing seed style.
|
||||
- **Seeding chat messages through `chat.Service`.** Its `SendMessageWith` emits realtime and enqueues jobs inside the tx. The seed already uses raw SQL (`insertID`, `exists`) and stays idempotent.
|
||||
- **Announce-mode chatbots commands.** HTTP dispatch passes `classes.CommandContext{}` [VERIFIED: chatbots/api/commands.go:57], so `announce` never persists (`cmdCtx.ConversationID == 0` returns early, dispatcher.go:52-56). Demo commands must be `Ephemeral`.
|
||||
- **Opening a second Centrifuge client** in the video layer (see Pattern 3).
|
||||
- **Editing `../vue-demo-app`.** That sibling checkout is stale (32049f7, no remote). The real app is the submodule `sm-demo-app/vue-demo-app` (44a5229, origin `golem15/vue-demo-app`).
|
||||
- **Putting the moderation filter in `golem15.demo`.** The user asked for a shared plugin (CONTEXT specifics).
|
||||
|
||||
## Don't Hand-Roll
|
||||
|
||||
| Problem | Don't Build | Use Instead | Why |
|
||||
|---------|-------------|-------------|-----|
|
||||
| Chat persistence, permissions, unread, reactions, tombstones | Demo-side message tables or endpoints | `sm-chat-plugin` generic API `/_chat/api/v1` | PHP-parity contracts; WavePath target |
|
||||
| Channel pins, mentions, joins | Custom pin/mention tables | `/_chatchannels/api/v1/contexts/demo/1/channels/{id}/pins`, `/mentions` | Already ported, with mention accrual listeners |
|
||||
| Video tokens / room cleanup | Own JWT minting or room GC | `chatvideo` `Start/Join/Leave/End` + `chatvideo:reconcile-sessions` (every 5 min) + LiveKit `room.empty_timeout` | HS256 golden tested |
|
||||
| WebRTC | Raw `RTCPeerConnection` | `livekit-client` | SFU signalling, reconnection, simulcast |
|
||||
| Realtime | Own WebSocket server | Centrifugo + lighthouse authorizers | Already deployed |
|
||||
| Markdown → safe HTML for forum | Client-side markdown rendering of user input | Server `content_html` from `breakwater.Render` (stored on write) | Sanitized server-side; render with `v-html` only from that field |
|
||||
| Web Push | Custom VAPID | `herald` + `herald:vapid-generate` | — |
|
||||
| Settings screen for word lists | Custom admin page | `pact.HasSettings` + `fields.yaml` singleton (pattern: sm-feedback-plugin admin.go) | cabana renders it |
|
||||
| Firewall changes on rome | Raw `iptables` | Vuurmuur (`vuurmuur_conf`/`vuurmuur_script`): rome's INPUT chain is Vuurmuur-managed (`vrmr:` NFLOG prefixes) | Raw rules get overwritten on Vuurmuur reload |
|
||||
|
||||
**Key insight:** The chat family is complete server-side. The work is host glue (context, adapter, resolvers, bootstrap), release hygiene and UI. Adding parallel endpoints or tables would fork the WavePath contract.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Pitfall 1: Stale sibling checkouts
|
||||
**What goes wrong:** Editing `../sm-chat-plugin` (13+ commits behind) and tagging an old tree, or a seam patch that conflicts with v0.1.3.
|
||||
**How to avoid:** `git -C ../sm-chat-plugin pull --ff-only` (same for chatchannels and chatbots) as task 1, then assert `git rev-parse HEAD == $(git ls-remote origin refs/heads/main)`.
|
||||
|
||||
### Pitfall 2: `v0.0.0` and pseudo-version requires break module mode
|
||||
**What goes wrong:** `GOWORK=off go build` in sm-demo-app fails with `unknown revision v0.0.0` (verified).
|
||||
**How to avoid:** Fix chatvideo and userfriends go.mod before tagging. `TestGoModRequiresTags` checks only the app's own go.mod, not transitive ones, so also build `GOWORK=off` in a clean temp dir.
|
||||
|
||||
### Pitfall 3: Missing `channel` alias, so messages in seeded channels 404
|
||||
**How to avoid:** Pattern 1. Test sending to a seeded channel conversation through the HTTP API.
|
||||
|
||||
### Pitfall 4: Realtime token route limited to presentation owners
|
||||
**What goes wrong:** Chat users get 403 from `/api/realtime/token`. The demo mounts `UserAuth: surf.Use("jwt.auth", "presentations.realtime-owner", bucketRealtime)` and mounts nothing unless presentations is active [VERIFIED: sm-demo-app/plugins/demo/routes.go:78-87]. The vue-demo-app realtime client treats 401/403/404 as final (`UNAVAILABLE = new Set([401, 403, 404])`, app/lib/realtime.ts) and stops for good.
|
||||
**How to avoid:** Port bm's `jz.bm.realtime-access` guard (sm-bm-app/plugins/jz/bm/realtime_access.go): a demo member passes, otherwise the presentations owner guard decides.
|
||||
|
||||
### Pitfall 5: Centrifugo namespaces missing
|
||||
**What goes wrong:** Subscribes to `chat:…`, `user:…` and `video:…` fail. The demo config has only `presentations` (deploy/centrifugo.json.example).
|
||||
**How to avoid:** Add `chat` (`presence`, `join_leave`, `force_push_join_leave`, `allow_presence_for_subscriber`, subscribe proxy), `user` and `video` (subscribe proxy), copying bm's namespace block (sm-bm-app/deploy/centrifugo/bm-config.json). "`centrifugo checkconfig` does not catch misspelt option names" (sm-bm-app DEPLOY.md:395). Compare against `centrifugo defaultconfig`. The `user` authorizer comes from sm-user-plugin v0.1.13 (`RegisterUserAuthorizer`, classes/authorizer.go:35-47). Restart `summercms-demo-centrifugo` after changing `centrifugo.json`.
|
||||
|
||||
### Pitfall 6: LiveKit media ports not open on rome
|
||||
**What goes wrong:** Signalling works but the call shows no remote video (ICE fails). rome's INPUT policy is DROP under Vuurmuur. A Vuurmuur service `Livekit` exists (`RANGE="6;7881*1024:65535"`, `RANGE="17;50000:60000*1024:65535"`) but no rule in `/etc/vuurmuur/rules/rules.conf` uses it, and `iptables -S` shows no rule for 7881 or 50000-60000 [VERIFIED: read-only ssh probe 2026-10-28].
|
||||
**How to avoid:** Define a demo service in Vuurmuur (TCP ICE port plus UDP mux port) and a rule allowing it from the internet to the firewall, then apply it through Vuurmuur. This needs the user's go-ahead (shared production host). Verify with `ss -lunp` and an external `nc -u` / a real two-browser call.
|
||||
|
||||
### Pitfall 7: Port collisions with WavePath's LiveKit
|
||||
**What goes wrong:** LiveKit defaults (7880, 7881, 50000-60000) collide with the running `wavepath-livekit` program.
|
||||
**How to avoid:** Use distinct ports: for example signal `127.0.0.1:7890`, `rtc.tcp_port: 7891`, `rtc.udp_port: 7892` (mux, no `port_range_*`). Check them free with `ss -ltnup` at deploy time. The ss probe today showed 7890-7892 unused. Extend `scripts/check-deploy.sh` port agreement checks to LiveKit.
|
||||
|
||||
### Pitfall 8: LiveKit behind Cloudflare and nginx
|
||||
**What goes wrong:** The signal WebSocket drops or the URL path is wrong.
|
||||
**How to avoid:**
|
||||
- Keep the signal on the same origin under a prefix, for example `livekit_url: wss://demo.summercms.io/livekit`. livekit-client appends paths to the existing pathname ("`wss://host/livekit` becomes `wss://host/livekit/rtc`", client-sdk-js src/api/utils.ts `appendUrlPath`) [CITED: github.com/livekit/client-sdk-js/blob/main/src/api/utils.ts].
|
||||
- nginx: `location ^~ /livekit/ { proxy_pass http://127.0.0.1:7890/; proxy_http_version 1.1; Upgrade/Connection headers; proxy_read_timeout 7d; proxy_buffering off; }`, as lk.wavepath.org does.
|
||||
- Set `livekit_admin_url: http://127.0.0.1:7890` so the Go RoomService calls stay on loopback. fetchguard TrustedMode allows loopback.
|
||||
- Media goes direct to the public IP, so ICE candidates reveal rome's IP (54.36.173.176) despite Cloudflare. It is accepted risk, since rome already exposes game servers on that IP.
|
||||
- Newer livekit-client tries `/rtc/v1` and falls back to `/rtc`. Server 1.13.1 support is `[ASSUMED]`. Test locally against the same 1.13.1 binary.
|
||||
|
||||
### Pitfall 9: Floating panel and SSR
|
||||
**What goes wrong:** Hydration mismatches or `window` errors.
|
||||
**How to avoid:** Render the floating panel in `<ClientOnly>`. Set `ssr: false` for `/chat/**` and the call route. Load `livekit-client` with a dynamic `import()`, as `centrifuge` is in realtime.ts.
|
||||
|
||||
### Pitfall 10: Reset leaves LiveKit rooms and chat rows behind
|
||||
**What goes wrong:** `demo:reset` deletes `users`. Chat tables cascade from users in parts only, `golem15_chatchannels_*` rows have no FK to messages, and active LiveKit rooms survive.
|
||||
**How to avoid:** Add every chat-family table to `resetTables` in FK order, children first, before `users`:
|
||||
- chatvideo participants and sessions
|
||||
- chat reactions, thread mutes, thread summaries, messages, participants and conversations
|
||||
- chatchannels mentions, pins, members, prefs, user context prefs, personal categories, channels and categories
|
||||
- forum reads, posts, threads and categories
|
||||
- userfriends bans, invites, group members, groups and friendships (keep the singleton context id=1)
|
||||
- herald subscriptions
|
||||
- chatbots bot flags
|
||||
|
||||
Keep `golem15_moderation_settings`. Set LiveKit `room.empty_timeout` and `departure_timeout` so orphaned rooms close. `TestResetKeepsPlans` must grow to cover the new tables.
|
||||
|
||||
### Pitfall 11: robots.txt and allow-lists drift
|
||||
**What goes wrong:** New API prefixes are not routed by nginx, or they show up in robots.txt.
|
||||
**How to avoid:** Add the new paths in three places:
|
||||
- nginx Go allow-list: `/_chat/`, `/_chatchannels/`, `/_chatvideo/`, `/_chatbots/`, `/_forum/`, `/_userfriends/`, and `/livekit/` to LiveKit.
|
||||
- `vue-demo-app` `goPaths`: dev proxy and robots.
|
||||
- The SEO plugin's robots.txt in the admin (DEPLOY.md "SEO": the Disallow lines are copied by hand).
|
||||
|
||||
`/_herald/` stays unrouted: there is no UI (D-16).
|
||||
|
||||
### Pitfall 12: Forum and friends APIs are JWT-only
|
||||
Every forum route is behind `jwt.auth` (forum README). An anonymous `/forum` cannot list threads without a new public endpoint. See Open Question 3.
|
||||
|
||||
### Pitfall 13: No admin screens for chat/forum content
|
||||
None of the seven plugins implements `HasAdminControllers` or `HasSettings` (grep). D-17's "admins deleting messages … from the backend" has no backend UI. See Open Question 2.
|
||||
|
||||
## Code Examples
|
||||
|
||||
### Demo context (verbatim interface members bm implements)
|
||||
```go
|
||||
// Source: sm-bm-app/plugins/jz/bm/classes/chat_context.go:12-17,101-110
|
||||
var (
|
||||
_ chatcontracts.Context = (*ChatContext)(nil)
|
||||
_ chatcontracts.MessageModerator = (*ChatContext)(nil)
|
||||
_ chatcontracts.LiveMembership = (*ChatContext)(nil)
|
||||
_ chancontracts.AccessResolver = (*ChatAccess)(nil)
|
||||
)
|
||||
func (c *ChatContext) ID() uint { return ChatContextID }
|
||||
func (c *ChatContext) Type() string { return ChatContextType }
|
||||
func (c *ChatContext) ChatEnabled() bool { return true }
|
||||
func (c *ChatContext) GroupName() string { return ChatGeneralName }
|
||||
func (c *ChatContext) BroadcastChannel() string { return ChatBroadcastChannel }
|
||||
// + CanActFor, CanOverseeChats, CanModerateMessage, RequireLiveMembership, HasMember, Members
|
||||
```
|
||||
|
||||
### Chatbots command (ephemeral)
|
||||
```go
|
||||
// Source: contracts in sm-bm-app/plugins/golem15/chatbots/contracts/slash_command.go
|
||||
type demoCommand struct{}
|
||||
func (demoCommand) Trigger() string { return "demo" }
|
||||
func (demoCommand) Description() string { return "What this demo shows" }
|
||||
func (demoCommand) IsAvailable(actor uint, _ contracts.CommandContext) bool { return actor != 0 }
|
||||
func (demoCommand) Handle(args string, actor uint, _ contracts.CommandContext) contracts.CommandResult {
|
||||
return classes.Ephemeral("This is the SummerCMS demo: chat, channels, calls, forum …")
|
||||
}
|
||||
```
|
||||
Catalog JSON: `GET /_chatbots/api/v1/commands` → `{"commands":[{"trigger","description"}]}`. Dispatch: `POST /dispatch {"input":"/demo"}` → `{"mode","payload"}`; unknown → 422 `errors.input` [VERIFIED: chatbots/api/commands.go:21-66; classes/dispatcher.go:89-99].
|
||||
|
||||
### Chatvideo config for the demo
|
||||
```yaml
|
||||
# config/golem15.chatvideo.yaml (keys verbatim from sm-chatvideo-plugin/config/config.yaml:4-11)
|
||||
livekit_url: "wss://demo.summercms.io/livekit"
|
||||
livekit_admin_url: "http://127.0.0.1:7890"
|
||||
max_duration: 900 # D-12 ≈15 min (reconcile runs every 5 min, so up to ~20)
|
||||
max_participants: 2 # DM-only calls server-side (Pattern 5)
|
||||
token_ttl: 900
|
||||
screen_share: false # minimal call page (D-13)
|
||||
# secrets: SUMMER_GOLEM15__CHATVIDEO__LIVEKIT_API_KEY / __LIVEKIT_API_SECRET in .env (or PHP names LIVEKIT_API_KEY/SECRET)
|
||||
```
|
||||
|
||||
### LiveKit config for the demo instance (keys from LiveKit config-sample)
|
||||
```yaml
|
||||
# /srv/summercms-demo/livekit.yaml (root:summercms-demo 0640)
|
||||
port: 7890
|
||||
bind_addresses: [127.0.0.1]
|
||||
rtc:
|
||||
tcp_port: 7891
|
||||
udp_port: 7892 # UDP mux; port_range_start/end must NOT be set
|
||||
use_external_ip: true
|
||||
room:
|
||||
max_participants: 4
|
||||
empty_timeout: 120
|
||||
departure_timeout: 20
|
||||
keys:
|
||||
CHANGE_ME_KEY: CHANGE_ME_SECRET
|
||||
```
|
||||
[CITED: raw.githubusercontent.com/livekit/livekit/master/config-sample.yaml]. The `udp_port` comment there says "port_range_start & end must not be set for this config to take effect". `bind_addresses` is used by rome's working WavePath config [VERIFIED: /etc/livekit/livekit.yaml on rome].
|
||||
|
||||
### Supervisor program (pattern from rome's wavepath-livekit.conf)
|
||||
```ini
|
||||
[program:summercms-demo-livekit]
|
||||
command=/usr/local/bin/livekit-server --config /srv/summercms-demo/livekit.yaml
|
||||
directory=/srv/summercms-demo
|
||||
user=summercms-demo
|
||||
autostart=true
|
||||
autorestart=true
|
||||
startsecs=5
|
||||
stopsignal=INT
|
||||
stopwaitsecs=10
|
||||
redirect_stderr=true
|
||||
stdout_logfile=/var/log/supervisor/summercms-demo-livekit.log
|
||||
```
|
||||
|
||||
## State of the Art
|
||||
|
||||
| Old Approach | Current Approach | When Changed | Impact |
|
||||
|--------------|------------------|--------------|--------|
|
||||
| bm SPA: one channel + DMs, host bootstrap | Multi-channel sidebar over chatchannels + host bootstrap | This phase | New store shape (`channels[]` replaces `general`) |
|
||||
| Pinia stores | `useState`/module composables | 19.4.1 | No Pinia in layers |
|
||||
| LiveKit port range | UDP mux single port | LiveKit ≥1.x | One firewall hole |
|
||||
| livekit-client `/rtc` | `/rtc/v1` with v0 fallback | client 2.17+ (per community reports) | Test against server 1.13.1 |
|
||||
|
||||
**Deprecated/outdated:**
|
||||
- The sibling `../sm-chat-plugin`, `../sm-chatchannels-plugin` and `../sm-chatbots-plugin` trees are behind origin. Treat origin `main` as the truth.
|
||||
|
||||
## Assumptions Log
|
||||
|
||||
| # | Claim | Section | Risk if Wrong |
|
||||
|---|-------|---------|---------------|
|
||||
| A1 | `livekit-client` (latest 2.x) connects to LiveKit server 1.13.1 through `/livekit` prefix behind Cloudflare | Pitfall 8 | Calls fail; fallback: dedicated `lk.demo.summercms.io` host (DNS + cert) |
|
||||
| A2 | UDP mux + ICE-TCP without TURN is enough for "typical NAT'd browsers" | Alternatives | Some corporate networks fail; fallback: embedded TURN on UDP 3478 / TLS 5349 with a DNS-only hostname |
|
||||
| A3 | Chat `GetGroupChat` on alias `channel` lazy-joins a channel member as participant (README statement; not traced through the HTTP handler this session) | Pattern 1 | Users cannot post in channels; fallback: bootstrap adds participants |
|
||||
| A4 | Forum `PostSaving` and chat `MessageSaving` names/shape | Pattern 2 | Discretion area; any additive shape is fine |
|
||||
| A5 | Persona users without passwords are acceptable (no login) | Seeding | None material |
|
||||
| A6 | Centrifugo v6 namespace option names copied from bm's running config are correct for the demo's config format (`channel.proxy.subscribe` + `subscribe_proxy_enabled`, unlike bm's named `proxies`) | Pitfall 5 | Subscribes denied; `centrifugo checkconfig` + `defaultconfig` comparison catches most |
|
||||
| A7 | `livekit-client` is the official LiveKit package (name from chatvideo README/training, registry repo github.com/livekit/client-sdk-js) | Legitimacy | Human-verify checkpoint covers it |
|
||||
|
||||
## Open Questions (RESOLVED)
|
||||
|
||||
Resolved 2026-10-28: Q1 by the 19.4.1 decision (admin at `/smbackend`, `/backend` 404; restated in plan 05's deploy checkpoint); Q2 by D-22 (moderator group, admin screens deferred); Q3 by D-21 (register prompt); Q4 by plans 03/04 (threads, pins, linkified URLs and an embed slot).
|
||||
|
||||
1. **Is the admin public or not?**
|
||||
- What we know: ROADMAP's goal says "The admin backend is not public". 19.4.1-02's DECISION CHANGE (user, 2026-10-20) made the admin public at `/smbackend` with a login required, throttled to 5/min, while `/backend` returns 404. SC-3 says "`/backend` is not reachable". That holds literally.
|
||||
- Recommendation: keep `/smbackend` as the user decided, and confirm in the plan's checkpoint.
|
||||
2. **How do admins delete chat messages and forum posts (D-17)?**
|
||||
- What we know: no chat-family plugin has admin screens.
|
||||
- Options:
|
||||
- (a) A demo moderator user group. `DemoContext.CanModerateMessage` (delete in group conversations) and the forum resolver's `CanManage` grant deletion. bm's `DeleteDialog` already supports moderators, and admins add users to the group in the user admin.
|
||||
- (b) cabana list screens in `golem15.demo` or `sm-moderation-plugin` over chat messages and forum posts, with delete actions. That puts chat/forum coupling into moderation, or app code into demo.
|
||||
- Recommendation: (a) now, and (b) as a backlog item.
|
||||
3. **Anonymous `/forum`.** D-14 does not say whether anonymous visitors see the forum, and the forum API is JWT-only. Recommendation: use the D-04/D-18 pattern (description plus "register to read and post") unless the user wants a public read endpoint in `golem15.demo`.
|
||||
4. **D-02 scope vs. bm reality.** bm has no threads, pins, multi-channel list or link embeds. Recommendation:
|
||||
- Threads: replies through `/messages/{id}/replies`, plus `PUT /threads/{rootId}/mute`.
|
||||
- Pins: chatchannels pins API.
|
||||
- Link embeds: linkified URLs. No unfurl backend exists, so no preview card. Add a slot or extension point for host embed renderers (bm's entity embeds become a host extension).
|
||||
|
||||
Confirm with the user that link embeds without previews is enough.
|
||||
5. **New git.golem15.com repos.** `vue-chat-layer`, `vue-chatvideo-layer`, `vue-forum-layer`, `vue-userfriends-layer` and `sm-moderation-plugin` must be created on git.golem15.com (as for vue-oauth-layer in 32.1). The layers must be public or pnpm-installable from the build machine (existing layers install via `git+https`). The plan should start with a user-run or token-backed repo creation step.
|
||||
6. **Firewall change on a shared production host.** Opening the LiveKit ports through Vuurmuur needs the user's go-ahead. Plan it as a `checkpoint:human-action`.
|
||||
|
||||
## Environment Availability
|
||||
|
||||
| Dependency | Required By | Available | Version | Fallback |
|
||||
|------------|------------|-----------|---------|----------|
|
||||
| Go | all Go repos | ✓ | go1.27.2 | — |
|
||||
| Docker | testcontainers tests | ✓ | 29.9.1 | `-short` tests |
|
||||
| Node | layers, vue-demo-app | ✓ | v24.22.0 local (rome site runs Node 22.22.0) | — |
|
||||
| pnpm | layers | ✓ | 12.14.0 | — |
|
||||
| livekit-server (local) | dev.sh video, tests | ✓ | 1.13.1 | `classes.FakeRooms` in Go tests |
|
||||
| livekit-server (rome) | D-10 | ✓ binary present | 1.13.1 | — |
|
||||
| centrifugo (local + rome) | realtime | ✓ | v6.5.1 | null driver |
|
||||
| rome free ports 7890-7892 | demo LiveKit | ✓ (not listening today) | — | other free ports |
|
||||
| rome firewall opening | media | ✗ (Vuurmuur rule needed) | — | none for media; blocks calls |
|
||||
| ssh rome | deploy | ✓ (`debian@10.8.3.118 -p 2222`, passwordless sudo) | — | — |
|
||||
|
||||
**Missing dependencies with no fallback:** the Vuurmuur rule for the demo LiveKit media ports (user-approved action).
|
||||
**Missing with fallback:** none.
|
||||
|
||||
## Validation Architecture
|
||||
|
||||
### Test Framework
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Framework (Go) | `go test` (testcontainers Postgres for full runs; `-short` skips Docker) |
|
||||
| Framework (layers) | `node --test` (existing layers); **vitest 3.2.7** recommended for `vue-chat-layer` (bm's chat tests are vitest, `vi.mock`) |
|
||||
| Framework (app site) | vitest 3.2.7 (`sm-demo-app/vue-demo-app/vitest.config.ts`) |
|
||||
| Quick run (plugin) | `go vet ./... && go test -short ./...` in the plugin checkout |
|
||||
| Quick run (demo) | `cd ../sm-demo-app && go vet ./... && go test -short ./...` |
|
||||
| Full suite (demo) | `scripts/check-all.sh` (Go app + summercms_mcp tag, user/journal plugin tests, vitest, sync-roadmap, check-pins, build release, smoke, check-deploy, browser checks, check-live) |
|
||||
|
||||
### Phase Requirements → Test Map
|
||||
| Req | Behavior | Test Type | Automated Command | File Exists? |
|
||||
|-----|----------|-----------|-------------------|-------------|
|
||||
| SC-1 | go.mod requires tags for all chat-family modules and summer.yaml lists them | unit | `go test -run TestGoModRequiresTags .` (sm-demo-app) | ✅ (extend wantPlugins) |
|
||||
| SC-1 | checkouts on required tags | script | `scripts/check-pins.sh` | ✅ |
|
||||
| SC-1 | every plugin activates, routes mounted (`/_chat/api/v1`, `/_chatchannels/api/v1`, `/_chatvideo/api/v1`, `/_chatbots/api/v1`, `/_forum/api/v1`, `/_userfriends/api/v1`, `/_herald/api/v1`, `/_demo/api/v1/chat`) | unit | `go test -short -run TestBootAllPlugins .` | ✅ extend |
|
||||
| SC-1 | release builds without go.work | script | `scripts/build.sh release` | ✅ |
|
||||
| SC-1 | demo:seed fills chat/channels/threads/reactions/pins/forum/friends EN+PL, idempotent | integration (Docker) | `go test -run 'TestSeed' .` | ❌ Wave 0: `seed_chat_test.go` |
|
||||
| SC-1 | reset wipes chat family and reseeds | integration | `go test -run TestResetKeepsPlans .` | ✅ extend |
|
||||
| D-06 | demo context membership, live membership, banned user excluded; channel adapter resolves | unit/integration | `go test -run 'TestDemoChat' ./plugins/demo/...` | ❌ Wave 0 |
|
||||
| D-07 | members cannot create channels (403/404 on POST channels) | integration | `go test -run TestDemoChannelsSeededOnly .` | ❌ |
|
||||
| D-11 | `video/start` on a channel conversation → 422; on DM → 201 with FakeRooms | integration | `go test -run TestDemoCallsDMOnly .` | ❌ |
|
||||
| Pitfall 4 | `/api/realtime/token` 200 for any member, 401 without JWT | unit | `go test -run TestRealtimeRoutes .` | ✅ extend |
|
||||
| D-18 | seam: no listener → identical behaviour; rejecting listener → 422 errors.content / errors.body, nothing persisted, no event | unit + Docker | `go test -short ./...` + `go test -run 'TestMessageSaving|TestPostSaving' .` in sm-chat-plugin / sm-forum-plugin | ❌ |
|
||||
| D-18 | PHP parity untouched | unit | existing `php_method_map_test.go`, `golden_test.go` | ✅ |
|
||||
| D-17 | filter: words (case-insensitive, word boundary), links (scheme/host/bare domain), settings round-trip | unit | `go test ./...` in sm-moderation-plugin | ❌ new repo |
|
||||
| D-05 | demo commands listed and dispatched ephemeral | unit | `go test -run TestDemoCommands ./plugins/demo/...` | ❌ |
|
||||
| Centrifugo | namespaces chat/user/video/presentations valid | script | `scripts/check-deploy.sh` (`centrifugo checkconfig`) | ✅ extend |
|
||||
| LiveKit | config valid, ports agree across supervisor/nginx/config | script | `scripts/check-deploy.sh` | ❌ extend |
|
||||
| D-01/02 | store: channels, DMs, threads, unread, mentions, reactions, typing, events parsing | unit | `pnpm test` in vue-chat-layer (ported `chat.test.ts`, `chatEvents/Format/Text/Unread.test.ts`) | ❌ port |
|
||||
| D-13 | call page state machine (join/leave/mute/camera, token errors) with a mocked Room | unit | `pnpm test` in vue-chatvideo-layer | ❌ |
|
||||
| D-14/15 | forum and friends API clients (URL building, error envelopes) | unit | `pnpm test` in each layer | ❌ |
|
||||
| SC-2/3 | live: /chat prompt anonymous, /forum, CTA, /backend 404, /_chat 401 without JWT, `/livekit/rtc/validate` reachable, /ws 101 | live | `scripts/check-live.sh https://demo.summercms.io` | ✅ extend |
|
||||
| SC-2 | two-browser chat realtime + DM call | manual (browser) | `scripts/check-local.sh chat` (Playwright, as check-remote.cjs) + human UAT on live | ❌ |
|
||||
|
||||
### Sampling Rate
|
||||
- **Per task commit:** the quick run of the repo touched (`go test -short ./...` or `pnpm test`)
|
||||
- **Per wave merge:** sm-demo-app `go test ./...` (Docker) + `pnpm --dir vue-demo-app test` + `scripts/check-pins.sh`
|
||||
- **Phase gate:** `scripts/check-all.sh` green, then `/msd-verify-work`
|
||||
|
||||
### Wave 0 Gaps
|
||||
- [ ] `sm-demo-app/seed_chat_test.go`, `chat_test.go` (context, adapter, resolvers, DM-only calls, bootstrap JSON)
|
||||
- [ ] `sm-chat-plugin` seam tests; `sm-forum-plugin` seam tests
|
||||
- [ ] `sm-moderation-plugin` package + tests (new repo)
|
||||
- [ ] `vue-chat-layer` vitest config + ported bm tests (rewrite `setActivePinia(createPinia())` setup for the composable store)
|
||||
- [ ] `vue-chatvideo-layer`, `vue-forum-layer`, `vue-userfriends-layer` `tests/*.test.ts`
|
||||
- [ ] `scripts/dev.sh`: start a local `livekit-server` (dev keys, ports 7890-7892 or `--dev`) like Centrifugo; `scripts/check-local.sh chat`
|
||||
|
||||
## Security Domain
|
||||
|
||||
### Applicable ASVS Categories
|
||||
| ASVS Category | Applies | Standard Control |
|
||||
|---------------|---------|-----------------|
|
||||
| V2 Authentication | yes | `jwt.auth` on every chat-family route; Turnstile on register (existing) |
|
||||
| V3 Session Management | yes | user JWT + refresh; realtime tokens (lighthouse, TTL 3600); LiveKit join tokens (HS256, `token_ttl` 900) |
|
||||
| V4 Access Control | yes | Host resolvers (demo context membership, live membership), chat participant checks, IDOR→404 in plugins, DM-only calls via `max_participants: 2` |
|
||||
| V5 Input Validation | yes | Plugin validators + new pre-save moderation seam; forum Markdown sanitized on write (`breakwater.Render`); chat content rendered as text (bm `chatText`), never `v-html` of raw content |
|
||||
| V6 Cryptography | yes | No hand-rolled crypto: LiveKit keys and VAPID keys generated (`openssl rand`, `herald:vapid-generate`), stored in `.env` 0640 |
|
||||
| V12 Files | yes | Chat attachments private, served only to participants; upload body limit 1 MiB default (keep, nginx `client_max_body_size 2m`) |
|
||||
|
||||
### Known Threat Patterns
|
||||
| Pattern | STRIDE | Standard Mitigation |
|
||||
|---------|--------|---------------------|
|
||||
| Spam/abuse in public chat and forum | Tampering / DoS | Moderation filter (pre-save), plugin buckets (`chat-api` 120/min, `chat-dm` 10/min, `chat-upload` 20/min, `forum-api`, `video-initiate` 5/min), Turnstile, reset job, user ban |
|
||||
| Stored XSS via messages/posts/names | Tampering | Text rendering for chat; server-sanitized `content_html` only for forum; no `v-html` on user fields |
|
||||
| Subscribing to others' conversations | Information disclosure | Centrifugo subscribe proxy → `AuthorizeChat` (participants only), `AuthorizeVideo`, user authorizer (`user:{self}`) |
|
||||
| LiveKit key co-tenancy with WavePath | Elevation | Separate LiveKit instance and keys (not a second key on WavePath's server) |
|
||||
| Origin IP disclosure via ICE | Information disclosure | Accepted (rome already exposes services on its IP); document in DEPLOY.md |
|
||||
| Call abuse (long or large rooms) | DoS | `max_duration` 900 + reconcile, `room.max_participants` 4, `empty_timeout`, `video-initiate` bucket |
|
||||
| Upload abuse | DoS | chat pending quota (10 files), prune job hourly, 1 MiB body limit |
|
||||
| Secrets in logs/payloads | Information disclosure | Same discipline as 19.4.1: keys only by name; never in `NUXT_PUBLIC_*` except public ones (VAPID public key) |
|
||||
|
||||
## Sources
|
||||
|
||||
### Primary (HIGH confidence)
|
||||
- Repo reads this session:
|
||||
- `sm-bm-app/plugins/golem15/{chat,chatchannels,chatbots}` (README, classes, api, boot, events, fixture tests)
|
||||
- `sm-{chatvideo,forum,herald,userfriends}-plugin` (README, config, classes, api)
|
||||
- `sm-bm-app/plugins/jz/bm/{chat.go,classes/chat_context.go,classes/chat_sync.go,controllers/api/chat.go,realtime_access.go}`
|
||||
- `sm-bm-app/frontend/src/{api/chat.ts,api/types.ts,stores/chat.ts,lib/chatEvents.ts,components/chat/*}`
|
||||
- `sm-demo-app/{summer.yaml,go.mod,go.work,.gitmodules,DEPLOY.md,README.md,scripts/check-pins.sh,go_mod_test.go,boot_test.go,plugins/demo/*,deploy/*,config/*}`
|
||||
- `vue-{faq,paymentgateway,oauth}-layer`
|
||||
- `sm-demo-app/vue-demo-app`
|
||||
- `summercms.go/modules/{festival,lighthouse,fetchguard,party,conga}` README and source
|
||||
- Scratch compile and tests of all seven plugins against framework v0.5.1 (go build/vet/test -short)
|
||||
- `git ls-remote` per plugin repo; npm registry (`npm view`); msd package-legitimacy seam
|
||||
- Read-only ssh probe of rome (ports, supervisor programs, LiveKit config with keys redacted, Vuurmuur service, iptables)
|
||||
|
||||
### Secondary (MEDIUM confidence)
|
||||
- LiveKit config sample: https://raw.githubusercontent.com/livekit/livekit/master/config-sample.yaml
|
||||
- livekit-client URL handling: https://raw.githubusercontent.com/livekit/client-sdk-js/main/src/api/utils.ts
|
||||
|
||||
### Tertiary (LOW confidence)
|
||||
- [upd.dev patch notes on /rtc/v1 fallback](https://upd.dev/slopus/happy/compare/4533ef5666..c97ea347f1.patch)
|
||||
- [LiveKit community: v1.13.1 signalling drops behind nginx ssl_preread](https://community.livekit.io/t/livekit-v1-13-1-signaling-ws-drops-mid-call-with-client-request-leave-full-reconnect-media-udp-unaffected-behind-nginx-ssl-preread/1481)
|
||||
- [client-sdk-js PR #1785 (new rtc path)](https://app.semanticdiff.com/gh/livekit/client-sdk-js/pull/1785/overview)
|
||||
- [livekit-client 2.18.4 release notes](https://newreleases.io/project/npm/livekit-client/release/2.18.4)
|
||||
- [LiveKit firewall tips](https://kb.livekit.io/articles/1724892785-establishing-media-connection-firewall-troubleshooting)
|
||||
|
||||
## Suggested Plan Split (for the lean-planning confirmation)
|
||||
|
||||
| # | Scope (one line) | Repos |
|
||||
|---|------------------|-------|
|
||||
| 01 | Shared plugin release: fast-forward siblings; fix chatvideo/herald/userfriends go.mod; chat v0.1.4 and forum pre-save seams; new `sm-moderation-plugin`; tag all eight (with go-ahead) | 8 plugin repos |
|
||||
| 02 | Demo backend: oauthserver bump (folded todo); mount 8 plugins (submodules, go.work, go.mod, summer.yaml); demo context + channel adapter + resolvers; bootstrap endpoints; realtime guard; chatbots commands; moderation wiring; seed + reset; Centrifugo namespaces; local LiveKit in dev.sh | sm-demo-app |
|
||||
| 03 | `vue-chat-layer` v0.1.0 (port, multi-channel, threads, pins, command picker, shared realtime) and its use in vue-demo-app (`/chat`, floating panel, Chat tour card, EN/PL) | vue-chat-layer, vue-demo-app |
|
||||
| 04 | `vue-chatvideo-layer`, `vue-forum-layer`, `vue-userfriends-layer` v0.1.0 and their pages and tour cards in vue-demo-app; herald VAPID config | 3 layers, vue-demo-app, sm-demo-app |
|
||||
| 05 | rome deploy: LiveKit program, Vuurmuur rule (checkpoint), nginx locations, `.env` keys (LiveKit, VAPID), Centrifugo restart, release, DEPLOY.md, check-deploy and check-live extensions | sm-demo-app, rome |
|
||||
| 06 | Unit tests (Go, layers, site) and live verification incl. a two-browser chat and DM call | all |
|
||||
|
||||
Plans 03 and 04 can run in parallel after 02. 05 can merge into 04 if the user prefers fewer plans.
|
||||
|
||||
## Metadata
|
||||
|
||||
**Confidence breakdown:**
|
||||
- Standard stack: HIGH. Versions come from go.mod files and the registry, and compatibility was compiled this session.
|
||||
- Architecture: HIGH for the backend glue (code read), MEDIUM for the layer design (new multi-channel work).
|
||||
- LiveKit deployment: MEDIUM. rome was probed, but the client path behaviour on server 1.13.1 behind Cloudflare is assumed.
|
||||
- Pitfalls: HIGH for repo, realtime and seed issues, MEDIUM for the network ones.
|
||||
|
||||
**Research date:** 2026-10-28
|
||||
**Valid until:** 2026-11-27 for the repo state (re-check `git ls-remote` before tagging); 7 days for the livekit-client version pick
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
review: 20-REVIEW.md
|
||||
recorded: 2026-11-02
|
||||
closed: 2026-11-03
|
||||
---
|
||||
|
||||
# Phase 20 review disposition
|
||||
|
||||
One row per finding in 20-REVIEW.md. `fixed` names the commits and the release tag and the check that confirmed it on the live demo (release 195aa213c546, deployed 2026-11-02 by plan 20-09); `deferred` points at the todo that tracks it. No row is open.
|
||||
|
||||
| Finding | Severity | Disposition | Note |
|
||||
|---|---|---|---|
|
||||
| CR-01 | critical | fixed | Leaving or unmounting during start/join still connects and publishes camera and microphone. vue-chatvideo-layer 69e8b83, 27ad81c (v0.1.1): a per-attempt token with stale checks after every await; leave is final at any moment. Live: `check-chat.cjs --call` ok against demo.summercms.io. |
|
||||
| CR-02 | critical | fixed | Banned-link filter bypass through URL forms the browser normalises, rendered as working links. sm-moderation-plugin 266fc60, 9715ce7 (v0.1.1): link hosts and paths canonicalised like the URL parser; vue-chat-layer a798bb1 (v0.1.1): deceptive hosts render as text; sm-demo-app 262da37 (CheckHTML on the rendered forum post). Live: `check-moderation.sh` ok (fixed probe, sm-demo-app da481c9), every link form refused in chat, forum reply and thread title. |
|
||||
| CR-03 | critical | fixed | Banned-word filter bypass through invisible characters, Unicode spaces and forum Markdown. sm-moderation-plugin 266fc60, 9715ce7, 334697b (v0.1.1): words matched after NFKC, format characters, Unicode spaces, diacritics, entities and inline markup; MatchHTML/CheckHTML; sm-forum-plugin ec1a82c (v0.1.2): PostSaving.HTML; sm-demo-app 262da37 (listener checks the rendered post). Live: `check-moderation.sh` ok, every word form refused. |
|
||||
| WR-01 | warning | fixed | Logout leaves the chat store and the realtime socket of the previous user running. vue-demo-app 188ae25 (pinned in sm-demo-app 27c48cf with layers v0.1.1): logout and unauthorized reset the chat, close the realtime socket and dismiss the ring. Local: check-chat.cjs default mode, every /ws socket closed within 5 s of Log out (not run live: it posts in #general). |
|
||||
| WR-02 | warning | deferred | Any member can pin or unpin any message in every public channel; the message is not checked against the channel. Todo: .planning/todos/pending/chatchannels-pin-policy.md |
|
||||
| WR-03 | warning | deferred | Member-visible text outside the chat and forum seams is never moderated. Todo: .planning/todos/pending/moderation-profile-group-and-filenames.md |
|
||||
| WR-04 | warning | fixed | A link opens a call and turns the camera and microphone on with no confirmation. vue-chatvideo-layer 5386903 (v0.1.1): the call page asks before media unless the call button or Accept handed over; vue-demo-app 9a12701 (pins). Live: `check-chat.cjs --call`, a direct /call load showed the confirmation with no LiveKit socket, tile or session before the click. |
|
||||
| WR-05 | warning | fixed | A failed LiveKit connect posts `leave`, not `end`, leaving an empty ringing session behind. vue-chatvideo-layer 27ad81c (v0.1.1): a failed connect (or livekit-client import) ends a session nobody else joined, from GET status. Unit tests in useCall.test.ts; deployed with release 195aa213c546. |
|
||||
| WR-06 | warning | deferred | The forum and friends clients have no 401 refresh; an expired token shows "not found". Todo: .planning/todos/pending/forum-friends-client-401-refresh.md |
|
||||
| IN-01 | info | deferred | Group calls in public channels are blocked only by the seeded participant count. Todo: .planning/todos/pending/chatvideo-dm-only-host-hook.md |
|
||||
| IN-02 | info | deferred | chatvideo checks participant rows, not live membership. Todo: .planning/todos/pending/chatvideo-live-membership.md |
|
||||
| IN-03 | info | deferred | check-local passes member JWTs to curl in argv. Todo: .planning/todos/pending/check-local-jwt-out-of-argv.md |
|
||||
| IN-04 | info | deferred | A chat message that starts with "/" can never be posted. Todo: .planning/todos/pending/chat-slash-text-escape.md |
|
||||
| IN-05 | info | deferred | `demo:seed` brings back the default moderation lists after an admin empties them. Todo: .planning/todos/pending/demo-seed-moderation-lists-once.md |
|
||||
| IN-06 | info | deferred | nginx `/livekit/` exposes LiveKit's whole HTTP surface. Todo: .planning/todos/pending/demo-nginx-livekit-rtc-only.md |
|
||||
| IN-07 | info | deferred | The incoming-call runtime can leak a session handle and survives logout. The logout half was fixed by 20-08 (vue-demo-app 188ae25); the handle leak remains. Todo: .planning/todos/pending/chatvideo-incoming-handle-leak.md |
|
||||
| IN-08 | info | deferred | The VAPID runbook pipeline runs without `pipefail`. Todo: .planning/todos/pending/demo-vapid-runbook-pipefail.md |
|
||||
| IN-09 | info | deferred | `GET /chat/members` writes, and builds an unbounded `IN` list. Todo: .planning/todos/pending/demo-chat-members-read-only.md |
|
||||
@@ -0,0 +1,387 @@
|
||||
---
|
||||
phase: 20-demo-instance-with-every-shared-plugin
|
||||
reviewed: 2026-11-01T23:50:42Z
|
||||
depth: standard
|
||||
files_reviewed: 105
|
||||
files_reviewed_list:
|
||||
- ../sm-chat-plugin/api/errors.go
|
||||
- ../sm-chat-plugin/classes/service.go
|
||||
- ../sm-chat-plugin/classes/writes.go
|
||||
- ../sm-chat-plugin/contracts/rejection.go
|
||||
- ../sm-chat-plugin/events/events.go
|
||||
- ../sm-chatvideo-plugin/go.mod
|
||||
- ../sm-demo-app/config/env/production/golem15.chatvideo.yaml
|
||||
- ../sm-demo-app/config/golem15.chatvideo.yaml
|
||||
- ../sm-demo-app/config/golem15.chat.yaml
|
||||
- ../sm-demo-app/deploy/nginx/demo.summercms.io.conf
|
||||
- ../sm-demo-app/deploy/supervisor/summercms-demo-livekit.conf
|
||||
- ../sm-demo-app/deploy/centrifugo.json.example
|
||||
- ../sm-demo-app/deploy/livekit.yaml.example
|
||||
- ../sm-demo-app/deploy/env.example
|
||||
- ../sm-demo-app/DEPLOY.md
|
||||
- ../sm-demo-app/.gitmodules
|
||||
- ../sm-demo-app/go.mod
|
||||
- ../sm-demo-app/go.work
|
||||
- ../sm-demo-app/plugins/demo/chat_api.go
|
||||
- ../sm-demo-app/plugins/demo/chatbots.go
|
||||
- ../sm-demo-app/plugins/demo/chat.go
|
||||
- ../sm-demo-app/plugins/demo/classes/chat_context.go
|
||||
- ../sm-demo-app/plugins/demo/classes/forum_access.go
|
||||
- ../sm-demo-app/plugins/demo/config/config.yaml
|
||||
- ../sm-demo-app/plugins/demo/console/reset.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_chat.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_forum.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed_friends.go
|
||||
- ../sm-demo-app/plugins/demo/console/seed.go
|
||||
- ../sm-demo-app/plugins/demo/moderation.go
|
||||
- ../sm-demo-app/plugins/demo/plugin.go
|
||||
- ../sm-demo-app/plugins/demo/realtime_access.go
|
||||
- ../sm-demo-app/plugins/demo/routes.go
|
||||
- ../sm-demo-app/plugins.gen.go
|
||||
- ../sm-demo-app/scripts/check-all.sh
|
||||
- ../sm-demo-app/scripts/check-chat.cjs
|
||||
- ../sm-demo-app/scripts/check-deploy.sh
|
||||
- ../sm-demo-app/scripts/check-live.sh
|
||||
- ../sm-demo-app/scripts/check-local.sh
|
||||
- ../sm-demo-app/scripts/dev.sh
|
||||
- ../sm-demo-app/scripts/smoke.sh
|
||||
- ../sm-demo-app/summer.yaml
|
||||
- ../sm-demo-app/vue-demo-app/app/assets/css/site.css
|
||||
- ../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/SiteNav.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/components/TourCard.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/layouts/default.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/lib/realtime.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/account/security.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/chat.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/forum/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/forum/t/[id].vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/friends.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/pages/index.vue
|
||||
- ../sm-demo-app/vue-demo-app/app/plugins/auth.ts
|
||||
- ../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts
|
||||
- ../sm-demo-app/vue-demo-app/nuxt.config.ts
|
||||
- ../sm-demo-app/vue-demo-app/pnpm-lock.yaml
|
||||
- ../sm-demo-app/vue-demo-app/vitest.config.ts
|
||||
- ../sm-forum-plugin/api/errors.go
|
||||
- ../sm-forum-plugin/classes/forum_service.go
|
||||
- ../sm-forum-plugin/classes/lifecycle.go
|
||||
- ../sm-forum-plugin/contracts/rejection.go
|
||||
- ../sm-forum-plugin/events/events.go
|
||||
- ../sm-herald-plugin/go.mod
|
||||
- ../sm-moderation-plugin/admin.go
|
||||
- ../sm-moderation-plugin/classes/filter.go
|
||||
- ../sm-moderation-plugin/go.mod
|
||||
- ../sm-moderation-plugin/models/settings.go
|
||||
- ../sm-moderation-plugin/plugin.go
|
||||
- ../sm-moderation-plugin/config/config.yaml
|
||||
- ../sm-moderation-plugin/models/settings/fields.yaml
|
||||
- ../sm-moderation-plugin/updates/202610280001_create_golem15_moderation_settings.go
|
||||
- ../sm-userfriends-plugin/go.mod
|
||||
- ../vue-chat-layer/app/assets/css/chat-tokens.css
|
||||
- ../vue-chat-layer/app/components/Chat/CommandPicker.vue
|
||||
- ../vue-chat-layer/app/components/Chat/FloatingPanel.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Header.vue
|
||||
- ../vue-chat-layer/app/components/Chat/ThreadPane.vue
|
||||
- ../vue-chat-layer/app/components/Chat/Message.vue
|
||||
- ../vue-chat-layer/app/components/Chat/MessageList.vue
|
||||
- ../vue-chat-layer/app/components/Chat/LinkEmbed.vue
|
||||
- ../vue-chat-layer/app/composables/useChat.ts
|
||||
- ../vue-chat-layer/app/lib/client.ts
|
||||
- ../vue-chat-layer/app/lib/chatText.ts
|
||||
- ../vue-chat-layer/app/lib/markdown.ts
|
||||
- ../vue-chat-layer/app/lib/linkEmbeds.ts
|
||||
- ../vue-chat-layer/app/lib/realtime.ts
|
||||
- ../vue-chat-layer/app/lib/slots.ts
|
||||
- ../vue-chat-layer/nuxt.config.ts
|
||||
- ../vue-chat-layer/vitest.config.ts
|
||||
- ../vue-chatvideo-layer/app/composables/useCall.ts
|
||||
- ../vue-chatvideo-layer/app/composables/useIncomingCalls.ts
|
||||
- ../vue-chatvideo-layer/app/lib/callMachine.ts
|
||||
- ../vue-chatvideo-layer/app/lib/videoClient.ts
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/Call.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/CallButton.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/IncomingCall.vue
|
||||
- ../vue-chatvideo-layer/app/components/Chatvideo/Tile.vue
|
||||
- ../vue-chatvideo-layer/nuxt.config.ts
|
||||
- ../vue-forum-layer/app/components/Forum/Thread.vue
|
||||
- ../vue-forum-layer/app/utils/forumClient.ts
|
||||
- ../vue-userfriends-layer/app/components/Friends/Groups.vue
|
||||
- ../vue-userfriends-layer/app/utils/friendsClient.ts
|
||||
findings:
|
||||
critical: 3
|
||||
warning: 6
|
||||
info: 9
|
||||
total: 18
|
||||
status: issues_found
|
||||
---
|
||||
|
||||
# Phase 20: Code Review Report
|
||||
|
||||
**Reviewed:** 2026-11-01T23:50:42Z
|
||||
**Depth:** standard
|
||||
**Files Reviewed:** 105 (the 86 listed files, plus the layer components, libs and deploy files the SUMMARYs under-listed)
|
||||
**Status:** issues_found
|
||||
|
||||
## Summary
|
||||
|
||||
The review covered the phase's code in its sibling repositories. That is the chat and forum pre-save seams (`git diff v0.1.4..main` and `v0.1.0..main`; both tags exist), the new sm-moderation-plugin, the sm-demo-app host plugin, deploy files and scripts (commits since 2026-10-28), vue-demo-app since 44a5229, and the four new layers.
|
||||
|
||||
Areas that held up when traced:
|
||||
- **Pre-save seams.** Both are additive and silent without a listener, and they map `contracts.Rejection` to 422 on every chat and forum write path (send, reply, ReplyTo, edit; thread, reply, edit).
|
||||
- **Core plugins.** The phase changed no core plugin (user, journal/blog, pages, payment). sm-user-plugin is consumed by tag and unchanged.
|
||||
- **XSS.** `renderChatText` escapes everything before it adds tags, placeholders cannot be forged (`\u0000` is stripped), and `safeUrl` refuses `javascript:`, `data:` and `//` / `/\` paths. Forum `content_html` comes from goldmark plus bluemonday. Attachments download as octet-stream with the `download` attribute. No XSS was found.
|
||||
- **Realtime authorization.** Every Centrifugo namespace goes through the subscribe proxy. The `user`, `chat`, `video` and `presentations` authorizers each check their own rule, so giving every member a connection token does not widen channel access. LiveKit tokens are scoped to one room, with no `roomAdmin`.
|
||||
- **Runbook secrets.** The runbooks keep secrets out of argv and logs.
|
||||
|
||||
Three defects need fixing before more traffic reaches the demo:
|
||||
1. **Call race (CR-01).** The call composable connects to LiveKit and publishes the camera and microphone after the user has already left or navigated away.
|
||||
2. **Link filter bypass (CR-02).** The banned-link filter misses URL forms that browsers normalise to the banned host. The chat then renders them as working links and link cards.
|
||||
3. **Word filter bypass (CR-03).** The banned-word filter misses invisible characters, non-breaking spaces and forum Markdown that renders to the banned word.
|
||||
|
||||
Each bypass was confirmed by running `classes.Match` against the probes; all of them returned `flagged=false`.
|
||||
|
||||
## Critical Issues
|
||||
|
||||
### CR-01: Leaving or unmounting during start/join still connects and publishes camera and microphone
|
||||
|
||||
**File:** `../vue-chatvideo-layer/app/composables/useCall.ts:177-231` (also `258-266`, `274-276`; Leave is enabled while `starting`/`connecting` in `../vue-chatvideo-layer/app/components/Chatvideo/Call.vue:72,91`)
|
||||
|
||||
**Issue:** `begin()` never re-checks the state or `leaving` after its awaits (`client.start`/`client.join` at line 184, `import('livekit-client')` at line 193). It also assigns `room` only after the import. `leave()` sees `room === null`, so it cannot disconnect anything.
|
||||
|
||||
- **Caller:** Leave is clicked while the status shows "Connecting…" (the state is `starting`). `leave()` dispatches `ended`, posts `end` (404, because the session does not exist yet) and navigates away. Then `start` resolves. `begin` subscribes `video:session:{id}`, loads livekit-client, creates a `Room`, connects, and runs `setCameraEnabled(true)` and `setMicrophoneEnabled(true)`. The server session was created and the callee is ringing. If they accept, they see and hear a caller who believes they hung up. Nothing on the page can stop it, and the channel handle leaks.
|
||||
- **Callee:** this path is worse. `begin(false)` dispatches nothing before `await client.join()`, so the state stays `idle`. Navigating away during the join runs `onBeforeUnmount → leave()`, which returns early on `status === 'idle'` (line 259). Then the join resolves: `transition` lets `joined` move `idle → connecting`, and the callee is live in the room with camera and microphone, with no UI and no leave posted.
|
||||
- **Second join:** the same missing guard lets a second `begin(false)` start while the first is pending. That creates two Rooms, and the first is never disconnected.
|
||||
|
||||
**Fix:** Add a per-attempt token and bail out after every await. Mark the attempt live before the first await. Make `leave()` work from the pre-room states.
|
||||
|
||||
```ts
|
||||
let attempt = 0
|
||||
async function begin(start: boolean) {
|
||||
if (state.value.status !== 'idle' && isLive(state.value)) return
|
||||
const mine = ++attempt
|
||||
leaving = false
|
||||
dispatch({ type: 'start' }) // also for the callee: leaves 'idle' before any await
|
||||
const stale = () => mine !== attempt || leaving || !isLive(state.value)
|
||||
let join: VideoJoin
|
||||
try { join = start ? (takeStart(conversationId) ?? (await client.start(conversationId))) : await client.join(conversationId) }
|
||||
catch (e) { if (!stale()) dispatch({ type: 'error', code: e instanceof VideoApiError ? e.status : 0, message: e instanceof Error ? e.message : '' }); return }
|
||||
if (stale()) { void (start ? client.end(conversationId) : client.leave(conversationId)).catch(() => {}); return }
|
||||
// ...same checks after import('livekit-client'), after r.connect(), and before each setXEnabled:
|
||||
// if (stale()) { await r.disconnect(true); return }
|
||||
}
|
||||
async function leave() {
|
||||
if (leaving || !isLive(state.value)) return // no early return on 'idle' while an attempt is pending
|
||||
leaving = true; attempt++ // invalidates the in-flight begin
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Add `useCall.test.ts` cases: "leave while start is pending" and "unmount while join is pending". Both must assert that `Room.connect` and `setCameraEnabled` are never called.
|
||||
|
||||
### CR-02: Banned-link filter bypass through URL forms the browser normalises, rendered as working links
|
||||
|
||||
**File:** `../sm-moderation-plugin/classes/filter.go:50,122-135`; `../sm-moderation-plugin/models/settings.go:137-168`; rendering in `../vue-chat-layer/app/lib/chatText.ts:87-93`, `../vue-chat-layer/app/lib/linkEmbeds.ts:40-47,69-83` and `../vue-chat-layer/app/components/Chat/LinkEmbed.vue:13`
|
||||
|
||||
**Issue:** `hostPattern` matches the literal text and compares hosts and paths byte for byte. The WHATWG URL parser (browsers, and `new URL` in `linkEmbeds.ts`) percent-decodes and IDNA-maps the host, so each form below reaches the banned host. Every probe returned `flagged=false` against `Match(["viagra",...], ["bit.ly","example.com/promo"], …)`. With `node`, `new URL()` resolves each one to `bit.ly`:
|
||||
|
||||
| Text sent | What the browser opens |
|
||||
|---|---|
|
||||
| `https://bit%2Ely/x` | `https://bit.ly/x` |
|
||||
| `https://bit.l%79/x` | `https://bit.ly/x` |
|
||||
| `https://bit.ly/x` (fullwidth) | `https://bit.ly/x` |
|
||||
| `https://bit。ly/x` (U+3002) | `https://bit.ly/x` |
|
||||
| `https://example.com:443/promo` | path rule skipped: the port stops the path group |
|
||||
| `https://example.com/%70romo`, `//promo`, `https://example.com./promo` | path-prefix rules skipped |
|
||||
| `https://sub.example.com/promo` | path rules never cover subdomains |
|
||||
| punycode `xn--…` vs. Unicode host | either spelling of an IDN bypasses the other |
|
||||
|
||||
The chat then renders the bypass as a clickable `<a href="https://bit%2Ely/x">`. `ChatLinkEmbed` makes it worse: its card shows the normalised host `bit.ly` and links to `https://bit.ly/x`. The forum renders the same through goldmark autolinks. Spammers can post any banned link, which defeats D-17 for links.
|
||||
|
||||
**Fix:** Normalise both sides the way the browser does before comparing. In the filter, find every candidate URL or host, then:
|
||||
|
||||
```go
|
||||
// for each candidate: s := found[0]; if no scheme, s = "http://" + s
|
||||
u, err := url.Parse(s) // then:
|
||||
host, _ := url.PathUnescape(u.Hostname()) // %2E -> .
|
||||
host = strings.Map(func(r rune) rune { // ideographic/fullwidth dots
|
||||
switch r { case '。', '.', '。': return '.' }; return r }, host)
|
||||
host, err = idna.Lookup.ToASCII(norm.NFKC.String(host)) // fullwidth -> ASCII, Unicode -> punycode (x/net/idna)
|
||||
host = strings.TrimSuffix(strings.TrimPrefix(strings.ToLower(host), "www."), ".")
|
||||
path := path.Clean("/" + mustUnescape(u.EscapedPath())) // //promo, /./promo, %70romo
|
||||
```
|
||||
|
||||
Apply the same `idna.Lookup.ToASCII` and NFKC to entries in `LinkEntry`. Let path rules also match subdomains, as host rules do. Widen `hostPattern` so its host class takes `%`, `.` and `。`, or tokenise on whitespace and parse each token. Add these probes to `filter_test.go`. `golang.org/x/net/idna` and `x/text` are already transitive dependencies of the framework; note them per the dependency rule.
|
||||
|
||||
### CR-03: Banned-word filter bypass through invisible characters, Unicode spaces and forum Markdown
|
||||
|
||||
**File:** `../sm-moderation-plugin/classes/filter.go:45,91,94,115`; seams `../sm-forum-plugin/classes/forum_service.go:284,341` and `../sm-forum-plugin/classes/lifecycle.go:235`; listener `../sm-demo-app/plugins/demo/moderation.go:65,86`
|
||||
|
||||
**Issue:** The word regexp uses `[^\p{L}\p{N}_]` as its boundary and RE2's ASCII-only `\s+` between the words of a phrase. Confirmed with `classes.Match`:
|
||||
|
||||
- **Invisible characters.** `viagra` (zero-width space) and `viagra` (soft hyphen) display as "viagra" and are not flagged. Format characters (`\p{Cf}`) count as boundaries.
|
||||
- **Unicode spaces.** `buy followers` (NBSP; likewise U+2009, U+3000) is not flagged.
|
||||
- **NFD text.** Polish diacritics typed in decomposed (NFD) form do not match an NFC entry, and the combining mark counts as a boundary.
|
||||
- **Forum Markdown.** The forum seam passes the raw Markdown body and title, but members see `breakwater.Render` output. `via**gra**` renders "via**gra**" as one word, `viagra` renders "viagra", and `[x](https://bit.ly/a)` renders a link to `bit.ly` because CommonMark decodes entities in link destinations. None of them are flagged.
|
||||
|
||||
Moderation is therefore cosmetic against anyone who tries once.
|
||||
|
||||
**Fix:** Normalise the text before matching, in `Filter.Check` (and `Match`):
|
||||
|
||||
```go
|
||||
t := norm.NFKC.String(text)
|
||||
t = strings.Map(func(r rune) rune {
|
||||
if unicode.Is(unicode.Cf, r) { return -1 } // ZWSP, ZWJ, soft hyphen, BOM...
|
||||
if unicode.IsSpace(r) { return ' ' } // NBSP, thin, ideographic spaces
|
||||
return r
|
||||
}, t)
|
||||
```
|
||||
|
||||
Use `[\p{Z}\s]+` in place of `\s+` between phrase words. Normalise entries with the same function in `ParseList`.
|
||||
|
||||
For the forum, check the rendered text too. In the demo's `checkPost`, run the filter on `html.UnescapeString` of `breakwater.Render(body)` with tags stripped, and on the hrefs it contains. Alternatively, have forum's `PostSaving` carry the rendered HTML (an additive field) so every host gets it.
|
||||
|
||||
## Warnings
|
||||
|
||||
### WR-01: Logout leaves the chat store and the realtime socket of the previous user running
|
||||
|
||||
**File:** `../sm-demo-app/vue-demo-app/app/composables/useDemoAuth.ts:83-92`, `../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue:12-15`, `../sm-demo-app/vue-demo-app/app/utils/communityAuth.ts:57`; `reset()` in `../vue-chat-layer/app/composables/useChat.ts:1514-1516`
|
||||
|
||||
**Issue:** `logout()` blacklists the JWT and clears the cookie. Nothing calls `useChat().reset()` or the realtime `disconnect()`, and the floating panel just unmounts. `start()` is the only caller of `reset()`, and it runs only when a chat view mounts again. After logout the tab therefore keeps:
|
||||
- the Centrifugo connection and the `user:{me}` subscription, which deliver the old user's DM and call events until the connection token expires;
|
||||
- the old user's messages and DMs in `useState`;
|
||||
- a pending incoming-call prompt in `chatvideo:incoming`.
|
||||
|
||||
`$chatAuth.unauthorized()` has the same gap: it only clears the cookie. The layer's own comment says reset exists so that a second account never sees the first one's chat, but the host never wires it.
|
||||
|
||||
**Fix:** In `logout()` (and in `unauthorized`), after clearing the token, call `useChat().reset()` (it disconnects the shared client) and clear `useState('chatvideo:incoming')`. Alternatively, `watch(loggedIn)` in `plugins/auth.ts` and reset when it turns false. Add a vitest case for the logout path.
|
||||
|
||||
### WR-02: Any member can pin or unpin any message in every public channel; the message is not checked against the channel
|
||||
|
||||
**File:** `../sm-demo-app/plugins/demo/classes/chat_context.go:259-269` (the policy) reaching `../sm-chatchannels-plugin/classes/channel_service.go:1332-1353` and `../sm-chatchannels-plugin/api/pins.go:31-52`
|
||||
|
||||
**Issue:** chatchannels gates `PinMessage` and `UnpinMessage` only with `requireChannelAccess`. The demo's `ChatAccess.CanAccessContext` answers true for every member, so any registered visitor can unpin the seeded welcome pins in #general, #announcements and #ogólny, or flood the pins panel. `PinMessage` also never checks that `messageID` belongs to the channel's conversation, so pins can point at another conversation's (DM) message ids. Contents do not leak, because the client's `GET /messages/{id}` needs participation, but the rows are bogus. Plan 03 noted "the visitor was allowed to pin … the pin succeeded" without treating it as a gap.
|
||||
|
||||
**Fix:** Make pinning a manage action, for example additively in chatchannels: `PinMessage`/`UnpinMessage` require `CanManageContext`, or an optional `contracts.PinPolicy` the host implements. The demo then answers it from the moderator group. Also verify `message.conversation_id == *ch.ConversationID` before creating the pin. Until then, the demo layer can hide pin actions for non-moderators (`pinAllowed`), but the server must enforce the rule.
|
||||
|
||||
### WR-03: Member-visible text outside the chat and forum seams is never moderated
|
||||
|
||||
**File:** `../sm-demo-app/plugins/demo/moderation.go:28-44`
|
||||
|
||||
**Issue:** The filter runs only on `MessageSaving.Content` and the `PostSaving` title and body. Members write other text that other members see:
|
||||
- **Profile name and surname.** They appear in `/chat/members` for every member, in mention chips, in DM headers, as forum `author_name`, and as `caller_name` in the incoming-call prompt.
|
||||
- **userfriends group names and descriptions.** They are shown to invitees in the code preview.
|
||||
- **Chat attachment filenames.**
|
||||
|
||||
A member registering as "free crypto bit.ly/x" puts that text in front of everyone, including in a ringing prompt. D-17 states that banned words and links are refused on every write path.
|
||||
|
||||
**Fix:** Run `Filter.Check` on the profile name and surname at registration and profile update. Use a user-plugin saving event if one exists, otherwise the demo's own registration route, without changing the core user plugin. Do the same for userfriends group create and update if a seam exists, or add an additive `GroupSaving` seam, and for attachment filenames (chat `MessageSaving` could carry them additively). Record any path left out as an explicit, documented exception.
|
||||
|
||||
### WR-04: A link opens a call and turns the camera and microphone on with no confirmation
|
||||
|
||||
**File:** `../vue-chatvideo-layer/app/components/Chatvideo/Call.vue:34-36`, `../sm-demo-app/vue-demo-app/app/pages/call/[conversation].vue:17,30`; same-tab site links in `../vue-chat-layer/app/lib/markdown.ts:22`
|
||||
|
||||
**Issue:** `ChatvideoCall` calls `begin()` on mount. `/call/{id}?start=1` starts a call (and rings the other side), and `/call/{id}` joins a live one. The chat renders site paths such as `/call/45?start=1` as same-tab links. One member can DM another `[see this](/call/45?start=1)`, where 45 is their shared DM. A click puts the victim in a call that publishes camera and microphone at once; once the origin has the media permission there is no prompt. A forged `?start=1` also bypasses the call button's intent.
|
||||
|
||||
**Fix:** Require an explicit action on the call page. Render a "Start call" or "Join" button and call `begin()` from its click. Keep auto-start only for a `takeStart()` handoff, which proves the click came from `ChatvideoCallButton`, and drop the `?start=1` trigger for direct loads.
|
||||
|
||||
### WR-05: A failed LiveKit connect posts `leave`, not `end`, leaving an empty ringing session behind
|
||||
|
||||
**File:** `../vue-chatvideo-layer/app/composables/useCall.ts:204-208`
|
||||
|
||||
**Issue:** When `r.connect()` fails, the caller posts `client.leave()`. As the starter and only connected participant, the session stays `pending` or `active` with nobody in it:
|
||||
- the callee keeps ringing for up to 45 s, and Accept joins an empty room;
|
||||
- Retry (`begin(true)`) gets the existing session back (`Created: false`), so it never rings again until the reconcile job runs.
|
||||
|
||||
This is the "left-open session never rings again" bug that `leave()` itself fixed with "last one out ends".
|
||||
|
||||
**Fix:** Use the same rule as `leave()`: `void (start || r.remoteParticipants.size === 0 ? client.end(conversationId) : client.leave(conversationId)).catch(() => {})`.
|
||||
|
||||
### WR-06: The forum and friends clients have no 401 refresh; an expired token shows "not found"
|
||||
|
||||
**File:** `../vue-forum-layer/app/utils/forumClient.ts:139-159`, `../vue-forum-layer/app/components/Forum/Thread.vue:41`, `../vue-userfriends-layer/app/utils/friendsClient.ts:135`
|
||||
|
||||
**Issue:** The chat and video clients refresh once on 401 through `$chatAuth.refresh()`. `$forumAuth` and `$userfriendsAuth` are bare token getters, and neither client retries. After the JWT expires, a member on `/forum/t/{id}` sees "thread not found", because `Thread.vue` maps 401 to `forum.error.notFound`. Posting fails the same way. `/chat` keeps working in the same tab.
|
||||
|
||||
**Fix:** Give both hooks the `{token, refresh, unauthorized}` shape (the demo can pass `chatAuth`), and add the chat client's single-flight refresh-and-retry to `request()`. Map 401 to its own "signed out" message rather than not-found.
|
||||
|
||||
## Info
|
||||
|
||||
### IN-01: Group calls in public channels are blocked only by the seeded participant count
|
||||
|
||||
**File:** `../sm-demo-app/config/golem15.chatvideo.yaml:13-18`, `../sm-chatvideo-plugin/classes/video_service.go:91,109-112`
|
||||
|
||||
**Issue:** The server has no DM-only rule (D-23 is UI only, as documented). Channel calls are refused today only because the four personas plus any visitor exceed `max_participants: 4`. If the cap is raised, or a channel is created with fewer seeded participants, any member can start a call that rings everyone who opened that channel.
|
||||
|
||||
**Fix:** Add a host hook in chatvideo (for example an optional `CanStartCall(conversationType)`), or check `conversation.type == dm` in the demo, so the rule does not depend on seed data.
|
||||
|
||||
### IN-02: chatvideo checks participant rows, not live membership
|
||||
|
||||
**File:** `../sm-chatvideo-plugin/classes/video_service.go:425-443`, `../sm-chatvideo-plugin/classes/authorizer.go:54-79`
|
||||
|
||||
**Issue:** A ban revokes the user's JWTs, so new calls are blocked. A LiveKit join token already minted (900 s) and an open `video:session` subscription still survive the ban, because chatvideo never consults `contracts.LiveMembership` as chat does.
|
||||
|
||||
**Fix:** Optional: have chatvideo honour `LiveMembership` (via chat's `Service.IsParticipant`) in `requireParticipant` and the authorizer, and remove the participant from the LiveKit room on a ban.
|
||||
|
||||
### IN-03: check-local passes member JWTs to curl in argv
|
||||
|
||||
**File:** `../sm-demo-app/scripts/check-local.sh:452,514,601` (and the friends checks)
|
||||
|
||||
**Issue:** The LiveKit join token is passed carefully through a curl config on stdin, but the member JWTs go into `-H "Authorization: Bearer $jwt"` arguments, which other local users can read in `/proc/*/cmdline`. This is local and uses throwaway users, but it is inconsistent with the stated pattern.
|
||||
|
||||
**Fix:** Reuse the `curl -K -` approach with `header = "Authorization: Bearer …"`.
|
||||
|
||||
### IN-04: A chat message that starts with "/" can never be posted
|
||||
|
||||
**File:** `../vue-chat-layer/app/composables/useChat.ts:825-829`
|
||||
|
||||
**Issue:** Every text starting with `/` (for example "/r/golang is great", or a path) is dispatched as a slash command and refused as unknown.
|
||||
|
||||
**Fix:** Dispatch only when the first token matches a known trigger from `commands`, or support a `//` escape.
|
||||
|
||||
### IN-05: `demo:seed` brings back the default moderation lists after an admin empties them
|
||||
|
||||
**File:** `../sm-demo-app/plugins/demo/console/seed_friends.go:117-122`
|
||||
|
||||
**Issue:** `seedModerationLists` refills both lists whenever both are empty, and every release runs `demo:seed`. An admin who deliberately clears both lists gets the defaults back at the next deploy.
|
||||
|
||||
**Fix:** Seed only on the first run, for example by inserting the lists in a row-creation step or recording a seeded flag.
|
||||
|
||||
### IN-06: nginx `/livekit/` exposes LiveKit's whole HTTP surface
|
||||
|
||||
**File:** `../sm-demo-app/deploy/nginx/demo.summercms.io.conf:363-375`
|
||||
|
||||
**Issue:** Browsers need only `/rtc` (and `/rtc/validate`). The location also exposes LiveKit's Twirp `RoomService` on the public origin. That service is protected by admin JWTs signed with the API secret, so exposing it publicly is unnecessary.
|
||||
|
||||
**Fix:** `location ^~ /livekit/rtc { proxy_pass http://127.0.0.1:7890/rtc; … }`, and answer 404 for the rest of `/livekit/`. Adjust check-deploy.
|
||||
|
||||
### IN-07: The incoming-call runtime can leak a session handle and survives logout
|
||||
|
||||
**File:** `../vue-chatvideo-layer/app/composables/useIncomingCalls.ts:41-56,58-70`
|
||||
|
||||
**Issue:** Two `video:call:incoming` events for the same session, both pending in `subscribe`, both pass the `pending.value?.sessionId === call.sessionId` check. The second overwrites `rt.channel` and the first handle is never closed. `pending` is also never cleared on logout (see WR-01).
|
||||
|
||||
**Fix:** Keep a sequence number per `watchSession` and close the handle unless it is the latest. Clear `pending` from the logout path.
|
||||
|
||||
### IN-08: The VAPID runbook pipeline runs without `pipefail`
|
||||
|
||||
**File:** `../sm-demo-app/DEPLOY.md:533-540`
|
||||
|
||||
**Issue:** The remote script uses `set -e` without `pipefail`. If `herald:vapid-generate` fails, `jq` emits nothing and `tee -a` appends nothing, but the `SUBJECT` line is still appended. The re-run guard (`grep -c "^…VAPID__" = 0`) then refuses ("already in .env") although no key pair exists, and recovery needs a hand edit of `.env`. The keys were already applied on rome; this matters for a rebuild.
|
||||
|
||||
**Fix:** Use `set -eo pipefail`, generate into a variable first, check both keys are non-empty, then append all three lines in one `tee`.
|
||||
|
||||
### IN-09: `GET /chat/members` writes, and builds an unbounded `IN` list
|
||||
|
||||
**File:** `../sm-demo-app/plugins/demo/chat_api.go:338-358`
|
||||
|
||||
**Issue:** A GET assigns handles (`AssignHandle`) to members without one. Two concurrent first loads race on the same rows. It also expands every member id into `id IN ?`, which fails with 500 past Postgres' 65535 bind-parameter limit. The production reset schedule is off, so users accumulate.
|
||||
|
||||
**Fix:** Select with the `memberWhere` subquery (`WHERE id <> ? AND <memberWhere>`) instead of an id list. Assign missing handles at registration or in `demo:seed`, not in a GET.
|
||||
|
||||
---
|
||||
|
||||
_Reviewed: 2026-11-01T23:50:42Z_
|
||||
_Reviewer: Claude (msd-code-reviewer)_
|
||||
_Depth: standard_
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
phase: "20"
|
||||
slug: "demo-instance-with-every-shared-plugin"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-11-05"
|
||||
---
|
||||
|
||||
# Phase 20 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail. Static audit of repository contents (no SSH, no ls-remote, no host contact). Audited: sm-demo-app da03c06 with plugin submodules on their tags (chat v0.1.5, forum v0.1.2, moderation v0.1.1, chatvideo/herald/userfriends v0.1.1, chatchannels/chatbots v0.1.0); vue-demo-app pins vue-chat-layer v0.1.1, vue-chatvideo-layer v0.1.1, vue-forum-layer v0.1.0, vue-userfriends-layer v0.1.0. Paths are relative to `../` (the meta repo). One medium threat (T-20-32) is open and non-blocking.
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| chat/forum HTTP clients → plugin APIs | message and post bodies untrusted; the saving seam runs before storage | message content, thread title, Markdown, JWT (high) |
|
||||
| host listeners → plugin services | the host decides refusals; listener errors must not leak internals | saving events, Rejection, errors (medium) |
|
||||
| admin settings → moderation filter | admins edit lists every message is matched against | banned word/link entries (medium) |
|
||||
| build machine → git.golem15.com / proxies / origin | tags become immutable inputs of every consumer | tags, pushes, go.sum, pnpm lock (medium) |
|
||||
| browser → /_demo, /_chat, /_chatchannels, /_chatbots, /_chatvideo, /_forum, /_userfriends | every request untrusted; actor only from the JWT | JWT, JSON, uploads ≤5 MiB (high) |
|
||||
| Centrifugo subscribe proxy → Go / browser → Centrifugo | client channel names, authorized server-side | channel names, connection tokens, X-Centrifugo-Secret (high) |
|
||||
| seed/reset commands → DB | trusted operator commands; persona accounts must stay unusable | persona rows, random bcrypt hashes (medium) |
|
||||
| Go → LiveKit RoomService (loopback) / browser → LiveKit | admin calls signed with the API secret; WebRTC with short-lived join token | admin JWT, join token (TTL 900), media, ICE (high) |
|
||||
| members' content → other members' browsers | untrusted text, links, cards, content_html, names | rendered content (high) |
|
||||
| realtime events → incoming-call prompt | server payloads about other users | session_id, conversation_id, caller_name (low) |
|
||||
| npm / git → layers | third-party (livekit-client) and own layers | packages, lockfile integrity (medium) |
|
||||
| internet → nginx (Cloudflare) / rome public 7891/tcp, 7892/udp | six API prefixes plus /livekit/; WebRTC media straight to LiveKit | HTTP, WS, SRTP, ICE (high) |
|
||||
| build machine → rome (SSH) | secrets generated on rome; releases and rsync | binaries, configs (high) |
|
||||
| demo services ↔ WavePath on the same host | must stay isolated | ports, supervisor programs, LiveKit config (high) |
|
||||
| test harnesses / browser checks → local and live demo | throwaway accounts, visitor creds, live JWT files | JWTs (0600 files), probe content (medium) |
|
||||
| build machine → summercms.io | journal token publishing changelog posts | g15_ token (high) |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-20-01 | Tampering | chat write paths that skip the seam | high | mitigate | MessageSaving fired on the only message insert and content update (sm-chat-plugin classes/service.go:314-337, writes.go:267-276); forum equivalents; TestMessageSavingTracer/Rejects. Chatbots announce path inserts without the seam but is unreachable on the demo (Ephemeral commands) | closed |
|
||||
| T-20-02 | Information disclosure | listener errors in API bodies | medium | mitigate | only Rejection → 422, everything else opaque 500 (chat/forum api/errors.go) on every write handler | closed |
|
||||
| T-20-03 | Denial of service | filter matching cost | medium | mitigate | QuoteMeta + RE2, recompile only on list change; 500 entries / 200 chars enforced in BeforeValidate | closed |
|
||||
| T-20-04 | Elevation of privilege | moderation settings screen | medium | mitigate | `PermissionManageSettings`, role `developer`, enforced by cabana | closed |
|
||||
| T-20-05 | Tampering | one-way module tags | medium | mitigate | all family tags annotated, on origin/main, monotonic | closed |
|
||||
| T-20-06 | Elevation of privilege | channel creation by members | high | mitigate | `CanManageContext` always false (plugins/demo/classes/chat_context.go:272-274); tests refuse member and moderator | closed |
|
||||
| T-20-07 | Information disclosure | subscribing to other conversations | high | mitigate | chat/user/video authorizers admit only own or participant channels; all namespaces via subscribe proxy. Residual IN-02 | closed |
|
||||
| T-20-08 | Spoofing | persona accounts | medium | mitigate | `personas.demo.invalid` emails, random bcrypt hashes never printed; reset reseeds | closed |
|
||||
| T-20-09 | Elevation of privilege | moderator rights | medium | mitigate | group conversations only, member + moderator group, banned users excluded, live membership required; group seeded empty | closed |
|
||||
| T-20-10 | Tampering | spam/abuse in chat and forum | high | mitigate | moderation listeners on both seams; rate buckets (chat 120/min, DM 10/min, forum, video-initiate 5/min); Turnstile `closed`; manual demo:reset (schedule off in production). Residual WR-03 | closed |
|
||||
| T-20-11 | Denial of service | realtime token minting | low | mitigate | JWT + membership guard, 120/min per user | closed |
|
||||
| T-20-12 | Information disclosure | LiveKit and VAPID secrets (local) | high | mitigate | dev.sh umask 077, names only echoed; empty examples; CHANGE_ME placeholders enforced by check-deploy.sh:391-399 | closed |
|
||||
| T-20-13 | Denial of service | stale chat-family rows after reset | low | mitigate | reset lists chat-family tables before users; reset tests | closed |
|
||||
| T-20-14 | Tampering | stored XSS (text, names, URLs) | high | mitigate | vue-chat-layer v-html only through the escaping renderer; safeUrl, rel noopener noreferrer nofollow; linkify on escaped text with honestHttpUrl | closed |
|
||||
| T-20-15 | Information disclosure | JWT handling in the layer | medium | mitigate | token from auth.token() as Bearer to same-origin bases; no web storage or cookie use | closed |
|
||||
| T-20-16 | Information disclosure | attachment downloads | medium | mitigate | bearer download, object URL; server checks CanView | closed |
|
||||
| T-20-17 | Spoofing | slash command answers | low | mitigate | `/` text dispatched, never posted; local ephemeral row marked "only you" | closed |
|
||||
| T-20-18 | Tampering | layer supply chain | medium | mitigate | exact pins; layers pinned by tag and locked to commits | closed |
|
||||
| T-20-19 | Denial of service | realtime connections | low | mitigate | single Centrifuge client; bounded polling | closed |
|
||||
| T-20-20 | Tampering | forum stored XSS | high | mitigate | v-html only on server-rendered content_html; `breakwater.Render` (bluemonday) on write; server-side preview | closed |
|
||||
| T-20-21 | Spoofing | call joins | high | mitigate | requireParticipant on start/join, token TTL 900, max 4 participants; layer never builds tokens | closed |
|
||||
| T-20-22 | Information disclosure | camera and microphone | medium | mitigate | media only after handoff/click; disconnect stops tracks; leave on pagehide/unmount | closed |
|
||||
| T-20-23 | Tampering | incoming-call payloads | low | mitigate | text binding for caller name; positive integer ids only | closed |
|
||||
| T-20-24 | Denial of service | call spam | medium | mitigate | video-initiate 5/min, max_duration 900, reconcile job; DM-only slot in the UI. Residual IN-01 | closed |
|
||||
| T-20-25 | Information disclosure | friend enumeration | low | mitigate | generic 422 shown as is; directory = chat picker set | closed |
|
||||
| T-20-26 | Information disclosure | VAPID private key | high | mitigate | never printed; empty example; no `/_herald` route in Nuxt or nginx, enforced by check-deploy.sh:405-409 | closed |
|
||||
| T-20-27 | Elevation of privilege | LiveKit co-tenancy with WavePath | high | mitigate | own supervisor program, config, user, ports, key pair; WavePath config untouched (DEPLOY.md:355-410). Host state live-only | closed |
|
||||
| T-20-28 | Information disclosure | LiveKit, VAPID, Centrifugo secrets (rome) | high | mitigate | generated on rome, `install -m 0640 root:summercms-demo`, written via stdin, unset; placeholders enforced. File modes live-only | closed |
|
||||
| T-20-29 | Denial of service | open media ports | medium | mitigate | only 7891/tcp and 7892/udp via Vuurmuur; participant and timeout limits. Firewall live-only | closed |
|
||||
| T-20-30 | Information disclosure | origin IP in ICE candidates | low | accept | AR-20-01 | closed |
|
||||
| T-20-31 | Elevation of privilege | unintended Go routes | medium | mitigate | six chat-family locations + `/livekit/`, no /_herald, `/backend` 404; check-deploy.sh. Residual IN-06 | closed |
|
||||
| T-20-32 | Tampering | firewall drift | medium | mitigate | Vuurmuur change and removal documented (DEPLOY.md:467-490), but **no dated rules.conf backup**; DEPLOY.md:475-476 points to a "Probed on rome on 2026-10-31" section (:94-102) that lists no rules | open — below high threshold (non-blocking) |
|
||||
| T-20-33 | Denial of service | a release breaking the live demo | medium | mitigate | `.prev` binary and site kept, rollback documented, check-live after release; clean-tree builds | closed |
|
||||
| T-20-34 | Spoofing | signalling WebSocket | low | mitigate | tokens only after requireParticipant (TTL 900); `/rtc/validate` 401 without token | closed |
|
||||
| T-20-35 | Information disclosure | credentials in tests and check output | medium | mitigate | visitor password read from `.env`, never printed; failures name keys only. Residual IN-03 (argv) | closed |
|
||||
| T-20-36 | Tampering | regressions behind skipped tests | medium | mitigate | check-all.sh runs suites without `-short`; container start failure fails tests; PLAN verifies count `--- PASS` lines | closed |
|
||||
| T-20-37 | Denial of service | throwaway accounts on the live demo | low | accept | AR-20-02 (rationale corrected) | closed |
|
||||
| T-20-38 | Spoofing | banned-link matching | high | mitigate | sm-moderation-plugin normalize.go canonical links (dots, percent-decode, last `@`, port, IDNA, path); TestMatchBypassLinks | closed |
|
||||
| T-20-39 | Tampering | banned-word matching | high | mitigate | entity decode, NFKC, Cf/Cc drop, space folding, diacritics, markup strip; two passes; TestMatchBypassWords | closed |
|
||||
| T-20-40 | Tampering | forum Markdown rendered after the check | high | mitigate | PostSaving.HTML carries rendered HTML; demo runs CheckHTML on it; forum, moderation and demo tests | closed |
|
||||
| T-20-41 | Denial of service | normalising and matching large texts | low | accept | AR-20-03 | closed |
|
||||
| T-20-42 | Information disclosure | useCall: media after leave | critical | mitigate | per-attempt `stale()` checks at every await; stale branch drops the Room; tests cover seven moments | closed |
|
||||
| T-20-43 | Elevation of privilege | /call/{id} opened from a link | high | mitigate | confirmation unless an in-memory 60 s single-use handoff exists | closed |
|
||||
| T-20-44 | Information disclosure | chat store, socket, call prompt after logout | high | mitigate | isolated sign-out steps; reset, disconnect, dismiss wired; communityAuth tests; check-chat.cjs requires `/ws` closed in 5 s | closed |
|
||||
| T-20-45 | Denial of service | empty ringing session after a failed connect | medium | mitigate | closeFailed ends sessions with ≤1 participant; tests | closed |
|
||||
| T-20-46 | Spoofing | deceptive hosts in anchors and cards | high | mitigate | `honestHttpUrl` (vue-chat-layer urlGuard.ts:28-48) on every link path; tests | closed |
|
||||
| T-20-47 | Tampering | release tags | high | mitigate | annotated, on origin/main, monotonic; ls-remote and fast-forward recorded in 20-09-SUMMARY | closed |
|
||||
| T-20-48 | Information disclosure | live member JWTs | high | mitigate | mode 600/400 required, header via `curl -K -` stdin; delete afterwards documented and recorded. Deletion live-only | closed |
|
||||
| T-20-49 | Tampering | probe content on the live demo | medium | mitigate | scope limited to own DM and seeded thread; stored probes deleted and reported; controls refused first | closed |
|
||||
| T-20-50 | Information disclosure | journal token | high | mitigate | changelog-post.py own token file, refuses readable-by-others, never printed | closed |
|
||||
| T-20-51 | Denial of service | the shared host during a release | medium | mitigate | restarts only the demo programs; rollback; pids recorded. Pid check live-only | closed |
|
||||
| T-20-52 | Tampering | temporary integration leaking into a release | medium | mitigate | clean-tree builds, GOWORK=off, frozen lockfile; tag-only pins; no go.mod replace | closed |
|
||||
| T-20-SC | Tampering | npm / Go installs (plans 01-09) | high | mitigate | every new module matches an already-vetted version (sitemap or framework); livekit-client 2.23.0 exact with lock integrity and human checkpoint; `protobufjs: false`; later plans change only golem15 modules and layer tags | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-20-01 | T-20-30 | rome already exposes services on its public address; the ICE candidates show it (DEPLOY.md:367-369). | 20-05 PLAN | 2026-11-05 |
|
||||
| AR-20-02 | T-20-37 | check-live registers no accounts (its token-less register expects 422). **Corrected:** the plan said the reset job removes the human UAT account, but the reset schedule is off in production (DEPLOY.md:945-946, 1006-1009), so UAT accounts stay until someone runs `demo:reset --force` by hand. | 20-09 PLAN (corrected by audit) | 2026-11-05 |
|
||||
| AR-20-03 | T-20-41 | RE2 is linear, lists are bounded by max_entries and max_entry_length, and the work is two passes over a message the plugins already cap in size. | 20-07 PLAN | 2026-11-05 |
|
||||
|
||||
*Accepted risks do not resurface in future audit runs.*
|
||||
|
||||
---
|
||||
|
||||
## Open Below Threshold
|
||||
|
||||
| Threat | Severity | Gap | To close (any one) |
|
||||
|--------|----------|-----|--------------------|
|
||||
| T-20-32 | medium | no dated `rules.conf` backup before the Vuurmuur change; DEPLOY.md's substitute reference points at a section without the rules | take a dated `rules.conf.bak-<date>` on rome, record the 15 pre-change RULE lines in DEPLOY.md's "Probed on rome" section, or record an accepted risk |
|
||||
|
||||
---
|
||||
|
||||
## Unregistered Flags and Residual Risk (non-blocking)
|
||||
|
||||
- **Unregistered (20-02):** `GET /_demo/api/v1/chat/members` (sm-demo-app/plugins/demo/chat_api.go) lists every member's name, surname and handle to any member; IN-09 adds that the GET writes handles and builds an unbounded `IN` list (500 above 65535 members). Todo `demo-chat-members-read-only.md`.
|
||||
- Deferred review items, each with a pending todo: WR-02 (any member can pin/unpin in public channels), WR-03 (profile names, friend-group names and attachment filenames are not moderated), WR-06 (forum/friends clients lack 401 refresh), IN-01 (no server-side DM-only call rule), IN-02 (video join token survives a ban up to 900 s), IN-03 (member JWTs and — found by this audit — the visitor password at check-local.sh:333 in curl argv), IN-04, IN-05, IN-06 (nginx `/livekit/` exposes LiveKit's whole HTTP surface incl. admin-JWT-protected RoomService), IN-07, IN-08 (VAPID runbook without `pipefail`).
|
||||
- Untracked: the 19.4.1 Centrifugo secrets runbook (DEPLOY.md:327-328) passes secrets as `sed` arguments on rome (not echoed; noted in 20-05 deviation 3, not fixed).
|
||||
|
||||
### Host-only checks (not verifiable from the repos)
|
||||
|
||||
WavePath LiveKit untouched and pid unchanged (T-20-27, T-20-51); file modes of `livekit.yaml`, `.env`, `centrifugo.json` (T-20-28); the applied Vuurmuur rule (T-20-29, T-20-32); live JWT files deleted (T-20-48); `RESET__ENABLED` count 0.
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-11-05 | 53 | 52 | 1 (medium, non-blocking) | msd-security-auditor (ASVS L1, block_on high; static, repo contents only) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
- [ ] T-20-32 closed (backup or recorded rules) or accepted
|
||||
- [ ] Host-only checks confirmed on rome
|
||||
|
||||
**Approval:** verified 2026-11-05 (ASVS L1; T-20-32 open below threshold)
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
phase: "20"
|
||||
slug: "demo-instance-with-every-shared-plugin"
|
||||
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
|
||||
# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
|
||||
status: draft
|
||||
nyquist_compliant: false
|
||||
wave_0_complete: false
|
||||
created: "2026-10-28"
|
||||
---
|
||||
|
||||
# Phase 20 — Validation Strategy
|
||||
|
||||
> Per-phase validation contract for feedback sampling during execution.
|
||||
|
||||
---
|
||||
|
||||
## Test Infrastructure
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Framework** | go test (plugins, sm-demo-app; testcontainers Postgres on full runs); vitest 3.2.7 (vue-demo-app, vue-chat-layer); node --test or vitest (other layers) |
|
||||
| **Config file** | `../sm-demo-app/vue-demo-app/vitest.config.ts`; new layers: none — Wave 0 installs |
|
||||
| **Quick run command** | `go vet ./... && go test -short ./...` in the touched Go repo; `pnpm test` in the touched layer |
|
||||
| **Full suite command** | `cd ../sm-demo-app && scripts/check-all.sh` |
|
||||
| **Estimated runtime** | ~30 seconds quick, ~300 seconds full |
|
||||
|
||||
---
|
||||
|
||||
## Sampling Rate
|
||||
|
||||
- **After every task commit:** Run the quick run command of the repo touched
|
||||
- **After every plan wave:** Run sm-demo-app `go test ./...` (Docker) + `pnpm --dir vue-demo-app test` + `scripts/check-pins.sh`
|
||||
- **Before `/msd-verify-work`:** Full suite must be green
|
||||
- **Max feedback latency:** 60 seconds
|
||||
|
||||
---
|
||||
|
||||
## Per-Task Verification Map
|
||||
|
||||
Filled by the planner from the plans; source map in `20-RESEARCH.md` § Validation Architecture.
|
||||
|
||||
| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|
||||
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
|
||||
| 20-01-01 | 01 | 1 | D-18, SC-1 | T-20-01, T-20-02 | a rejecting MessageSaving listener gives 422 and stores nothing; no listener changes nothing | integration (Docker) | `go -C ../sm-chat-plugin test -count=1 -run '^TestMessageSavingTracer$' -v .` | ❌ created in task (saving_smoke_test.go) | ⬜ pending |
|
||||
| 20-01-02 | 01 | 1 | D-18 | T-20-01 | forum thread, reply and edit refused before render | integration (Docker) | `go -C ../sm-forum-plugin test -count=1 -run '^TestPostSavingTracer$' -v .` | ❌ created in task | ⬜ pending |
|
||||
| 20-01-03 | 01 | 1 | D-17 | T-20-03, T-20-04 | word and link matching; list caps; settings behind a permission | unit | `go -C ../sm-moderation-plugin test -count=1 -run '^TestFilterSmoke$' -v ./classes` | ❌ new repo | ⬜ pending |
|
||||
| 20-01-04 | 01 | 1 | SC-1 | T-20-05 | modules resolve by tag only | build | `for r in …8 repos; do go -C ../$r vet ./... && go -C ../$r test -short ./...; done` + `GOWORK=off go build` of 5 dependants | ✅ | ⬜ pending |
|
||||
| 20-01-05 | 01 | 1 | — | T-20-05 | go-ahead before one-way tags | checkpoint | — | — | ⬜ pending |
|
||||
| 20-01-06 | 01 | 1 | SC-1 | T-20-05 | remote tags equal verified HEADs | script | `git ls-remote origin refs/tags/<tag>^{}` loop | ✅ | ⬜ pending |
|
||||
| 20-02-01 | 02 | 2 | SC-1, D-06, D-07 | T-20-06, T-20-07 | member posts in #general; channel creation refused | integration (Docker) | `go -C ../sm-demo-app test -count=1 -run '^(TestDemoChatTracer\|TestGoModRequiresTags\|TestBootAllPlugins)$' -v .` + `scripts/check-pins.sh` | ❌ created in task (chat_smoke_test.go) | ⬜ pending |
|
||||
| 20-02-02 | 02 | 2 | D-05, D-08, D-12, D-14, D-17, D-22, D-23 | T-20-09, T-20-10 | banned words and links refused in chat and forum | integration (Docker) | `go -C ../sm-demo-app test -count=1 -run '^TestDemoModerationSmoke$' -v .` + `scripts/build.sh dev` | ❌ created in task | ⬜ pending |
|
||||
| 20-02-03 | 02 | 2 | D-09 | T-20-08, T-20-13 | personas cannot log in; reset empties every chat-family table | integration (Docker) | `go -C ../sm-demo-app test -count=1 -run '^(TestSeedChatSmoke\|TestResetKeepsPlans\|TestSeedRoadmapUpsert)$' -v .` | ❌ / ✅ | ⬜ pending |
|
||||
| 20-02-04 | 02 | 2 | D-06, D-10 | T-20-11, T-20-12 | realtime token only for live members; no secret committed | unit + script | `go -C ../sm-demo-app test -short .` + `centrifugo checkconfig` + `scripts/dev.sh up` + `scripts/check-local.sh realtime` | ✅ | ⬜ pending |
|
||||
| 20-03-01 | 03 | 3 | D-01, D-04, D-07, SC-2 | T-20-15 | anonymous prompt; Bearer only to same-origin APIs | unit + browser | `pnpm --dir ../vue-chat-layer test` + vue-demo-app build + `scripts/check-local.sh chat` | ❌ created in task | ⬜ pending |
|
||||
| 20-03-02 | 03 | 3 | D-02, SC-2 | T-20-14, T-20-19 | text escaped; one realtime connection | unit + browser | layer and vue-demo-app tests + `scripts/check-local.sh chat realtime remote` | ✅ (app) | ⬜ pending |
|
||||
| 20-03-03 | 03 | 3 | D-02, D-05, D-22, D-23 | T-20-14, T-20-16, T-20-17 | linkify on escaped HTML; authorised downloads; ephemeral answers stay local | unit + build | `pnpm --dir ../vue-chat-layer test` + `build:playground` + `scripts/check-local.sh chat` | ✅ | ⬜ pending |
|
||||
| 20-03-04 | 03 | 3 | D-03, D-04 | — | floating panel hidden for anonymous visitors | browser | `scripts/check-local.sh tour chat` | ✅ extend | ⬜ pending |
|
||||
| 20-03-05 | 03 | 3 | D-01 | — | go-ahead before the public tag | checkpoint | — | — | ⬜ pending |
|
||||
| 20-03-06 | 03 | 3 | D-01 | T-20-18 | layer pinned by tag with a committed lockfile | script | remote tag equals HEAD + pin grep + vue-demo-app test and build | ✅ | ⬜ pending |
|
||||
| 20-04-01 | 04 | 4 | D-14, D-21, D-22 | T-20-20 | posts render only server content_html | unit + script | `pnpm --dir ../vue-forum-layer test` + build + `scripts/check-local.sh forum` | ❌ created in task | ⬜ pending |
|
||||
| 20-04-02 | 04 | 4 | D-15 | T-20-25 | friend refusals stay generic | unit + script | `pnpm --dir ../vue-userfriends-layer test` + `scripts/check-local.sh friends forum chat` | ❌ created in task | ⬜ pending |
|
||||
| 20-04-03 | 04 | 4 | D-13 | T-20-SC | livekit-client legitimacy confirmed before install | checkpoint (blocking-human) | — | — | ⬜ pending |
|
||||
| 20-04-04 | 04 | 4 | D-11, D-12, D-13, D-23 | T-20-21, T-20-22, T-20-23, T-20-24 | server-minted tokens; call button only in DMs; media only after start or accept | unit + script | `pnpm --dir ../vue-chatvideo-layer test` + build + `scripts/check-local.sh call chat` | ❌ created in task | ⬜ pending |
|
||||
| 20-04-05 | 04 | 4 | D-16 | T-20-26 | VAPID keys only in .env | script | `scripts/dev.sh up` + `scripts/check-local.sh herald tour` | ❌ check added in task | ⬜ pending |
|
||||
| 20-04-06 | 04 | 4 | D-14, D-15, D-13 | — | go-ahead before public tags | checkpoint | — | — | ⬜ pending |
|
||||
| 20-04-07 | 04 | 4 | SC-2 | T-20-SC | layers pinned by tag | script | remote tags equal HEAD + vue-demo-app test, build + `scripts/check-local.sh forum friends call chat tour` | ✅ | ⬜ pending |
|
||||
| 20-05-01 | 05 | 5 | D-10, D-12, SC-3 | T-20-31 | exact Go allow-list; /_herald unrouted; ports and caps agree | script | `scripts/check-deploy.sh` (last line `check-deploy: ok`) | ✅ extend | ⬜ pending |
|
||||
| 20-05-02 | 05 | 5 | SC-1 | T-20-33 | release build from tags, smoke clean | script | `scripts/check-pins.sh` + `scripts/build.sh release` + `scripts/smoke.sh` | ✅ | ⬜ pending |
|
||||
| 20-05-03 | 05 | 5 | SC-3 | T-20-27 | go-ahead before rome changes | checkpoint | — | — | ⬜ pending |
|
||||
| 20-05-04 | 05 | 5 | SC-2, SC-3, D-10, D-16 | T-20-27, T-20-28, T-20-34 | WavePath untouched; secrets generated on rome | live | `scripts/check-live.sh https://demo.summercms.io` | ✅ extend | ⬜ pending |
|
||||
| 20-05-05 | 05 | 5 | D-10 | T-20-29, T-20-32 | go-ahead before the firewall change | checkpoint | — | — | ⬜ pending |
|
||||
| 20-05-06 | 05 | 5 | D-10 | T-20-29, T-20-32 | only 7891/tcp and 7892/udp opened, through Vuurmuur | live | `ssh … iptables -S` count + `nc -zv … 7891` | ✅ | ⬜ pending |
|
||||
| 20-06-01 | 06 | 6 | D-17, D-18, SC-4 | T-20-10 | settings to filter to listener to 422 | unit + integration | `go -C ../sm-moderation-plugin test ./...` + `-run '^TestDemoModeration$'` | ❌ created in task | ⬜ pending |
|
||||
| 20-06-02 | 06 | 6 | D-18, D-17 | T-20-01, T-20-02 | parity without listeners; refusal on every write path | unit + integration | chat, forum and moderation full suites | ❌ created in task | ⬜ pending |
|
||||
| 20-06-03 | 06 | 6 | D-05 to D-09, D-11, D-12, D-22, D-23, SC-1 | T-20-06, T-20-07, T-20-09, T-20-11 | membership, refused channel create, moderator scope, member-only tokens | integration | `go -C ../sm-demo-app test -count=1 . ./plugins/demo/...` + named tests | ❌ created in task | ⬜ pending |
|
||||
| 20-06-04 | 06 | 6 | D-01, D-02, D-04, D-05, D-13, D-14, D-15, D-21, D-23 | T-20-14 | escaping and DM-only slot pinned | unit | `pnpm test` in four layers + vue-demo-app test and build | ❌ created in task | ⬜ pending |
|
||||
| 20-06-05 | 06 | 6 | SC-2, D-11, D-13, D-23 | — | two-browser realtime; DM call with fake media | browser E2E | `scripts/check-local.sh chat chatlive callmedia forum friends call herald tour realtime remote` | ❌ created in task | ⬜ pending |
|
||||
| 20-06-06 | 06 | 6 | — | — | go-ahead before pushes and fix tags | checkpoint | — | — | ⬜ pending |
|
||||
| 20-06-07 | 06 | 6 | SC-2, SC-3, SC-4 | T-20-36 | full gate including check-live | gate | `scripts/check-all.sh --local` (last line `check-all: ok`) | ✅ extend | ⬜ pending |
|
||||
| 20-06-08 | 06 | 6 | SC-2, SC-3 | — | two-browser chat and DM call on the live demo | manual (UAT) | — | — | ⬜ pending |
|
||||
|
||||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||||
|
||||
---
|
||||
|
||||
## Wave 0 Requirements
|
||||
|
||||
Each gap is closed inside the plan that creates the code (a smoke test or check in the same task), and the full tests come in plan 06 (project rule: unit tests are the last plan).
|
||||
|
||||
- [ ] `sm-demo-app/seed_chat_test.go`, `chat_test.go` (context, channel adapter, resolvers, DM calls, bootstrap JSON): smoke in 20-02 (`chat_smoke_test.go`), full in 20-06 Task 3
|
||||
- [ ] `sm-chat-plugin` and `sm-forum-plugin` pre-save seam tests: smoke in 20-01 Tasks 1-2, full in 20-06 Task 2
|
||||
- [ ] `sm-moderation-plugin` package and tests (new repo): smoke in 20-01 Task 3, full in 20-06 Tasks 1-2
|
||||
- [ ] `vue-chat-layer` vitest config and ported bm chat tests (composable store setup): config and smoke in 20-03 Task 1, ported tests in 20-06 Task 4
|
||||
- [ ] `vue-chatvideo-layer`, `vue-forum-layer`, `vue-userfriends-layer` `tests/*.test.ts`: smoke in 20-04 Tasks 1, 2 and 4, full in 20-06 Task 4
|
||||
- [ ] `scripts/dev.sh` local livekit-server (20-02 Task 4); `scripts/check-local.sh chat` (20-03 Task 1), `forum`, `friends`, `call`, `herald` (20-04), `chatlive` and `callmedia` (20-06 Task 5)
|
||||
|
||||
---
|
||||
|
||||
## Manual-Only Verifications
|
||||
|
||||
| Behavior | Requirement | Why Manual | Test Instructions |
|
||||
|----------|-------------|------------|-------------------|
|
||||
| Two-browser chat realtime and a DM video call on the live demo | SC-2, D-13 | Real media over NAT'd browsers and the rome firewall | Two accounts on https://demo.summercms.io: send a message, see it arrive live; start a DM call, see and hear both tiles, mute, leave |
|
||||
| Vuurmuur firewall rule on rome | D-10 | Shared production host change | Apply with the user's go-ahead; confirm with `/livekit/rtc/validate` and a call |
|
||||
|
||||
---
|
||||
|
||||
## Validation Sign-Off
|
||||
|
||||
- [x] All tasks have `<automated>` verify or Wave 0 dependencies (checkpoints excepted)
|
||||
- [x] Sampling continuity: no 3 consecutive tasks without automated verify
|
||||
- [ ] Wave 0 covers all MISSING references
|
||||
- [x] No watch-mode flags (vitest run, node --test)
|
||||
- [ ] Feedback latency < 60s
|
||||
- [ ] `nyquist_compliant: true` set in frontmatter
|
||||
|
||||
**Approval:** pending
|
||||
@@ -0,0 +1,72 @@
|
||||
# API Coverage — Phase 20 (livekit-client, LiveKit server, Centrifugo, Web Push)
|
||||
|
||||
> Full coverage by default. Opt-outs are explicit, reasoned decisions. The phase builds no new server-side client: LiveKit's server API is called by `sm-chatvideo-plugin` (server-sdk-go), Centrifugo by `lighthouse`, Web Push by `sm-herald-plugin`. This phase adds the browser side of the video calls (`vue-chatvideo-layer` on `livekit-client` 2.23.0, plan 04), the chat's use of Centrifugo (`vue-chat-layer`, plan 03) and herald's VAPID configuration (plan 04).
|
||||
|
||||
## livekit-client 2.23.0 (plan 04, vue-chatvideo-layer)
|
||||
|
||||
| capability | decision | reason |
|
||||
|---|---|---|
|
||||
| Room connect (livekit_url and the server-minted join token) | INTEGRATE | |
|
||||
| Room disconnect (stops the local tracks) | INTEGRATE | |
|
||||
| publish camera (localParticipant.setCameraEnabled) | INTEGRATE | |
|
||||
| publish microphone (localParticipant.setMicrophoneEnabled) | INTEGRATE | |
|
||||
| subscribe and attach remote tracks (TrackSubscribed, track.attach and detach) | INTEGRATE | |
|
||||
| mute and unmute | INTEGRATE | |
|
||||
| camera toggle | INTEGRATE | |
|
||||
| participant events (ParticipantConnected, ParticipantDisconnected, TrackMuted, TrackUnmuted, LocalTrackPublished) | INTEGRATE | |
|
||||
| connection state and reconnection (Reconnecting, Reconnected, Disconnected) | INTEGRATE | |
|
||||
| adaptiveStream and dynacast | INTEGRATE | |
|
||||
| audio playback unlock (AudioPlaybackStatusChanged, startAudio) | INTEGRATE | |
|
||||
| dynamic import of the package | INTEGRATE | |
|
||||
| screen share | OPT-OUT | explicitly out of scope: D-13 keeps the call page minimal and the server config has screen_share false |
|
||||
| data channel (publishData, data streams, RPC) | OPT-OUT | not needed: chat messages go through the chat plugins, not the call |
|
||||
| device selection (switchActiveDevice, getLocalDevices) | OPT-OUT | not needed for a minimal demo call: the browser's default camera and microphone are used |
|
||||
| end-to-end encryption (E2EE worker) | OPT-OUT | explicitly out of scope: a public demo call with a short-lived room; media is DTLS-SRTP encrypted in transit |
|
||||
| recording and egress | OPT-OUT | explicitly out of scope: the demo records nothing |
|
||||
| simulcast tuning (videoEncoding, layers) | OPT-OUT | not needed: the defaults with adaptiveStream and dynacast fit 1:1 calls |
|
||||
| audio-only mode | OPT-OUT | not needed: turning the camera off gives the same call without video |
|
||||
| background effects and track processors | OPT-OUT | not needed: not part of a minimal call page |
|
||||
| active speaker highlighting | OPT-OUT | not needed: calls are 1:1 DMs (D-11), so there is no speaker to pick out |
|
||||
|
||||
## LiveKit server 1.13.1 through golem15.chatvideo (plans 02 and 05)
|
||||
|
||||
| capability | decision | reason |
|
||||
|---|---|---|
|
||||
| room create (on video/start) | INTEGRATE | |
|
||||
| room delete (on video/end and at max_duration) | INTEGRATE | |
|
||||
| join token mint (per participant, token_ttl 900) | INTEGRATE | |
|
||||
| participant count and active rooms (reconcile) | INTEGRATE | |
|
||||
| remove participant (on video/leave) | INTEGRATE | |
|
||||
| reconcile job (chatvideo:reconcile-sessions ends idle and overdue rooms) | INTEGRATE | |
|
||||
| room max_participants (4 in livekit.yaml, next to chatvideo max_participants, D-12) | INTEGRATE | |
|
||||
| /rtc/validate (check-local call) | INTEGRATE | |
|
||||
| egress (recording, streaming) | OPT-OUT | explicitly out of scope: the demo records nothing |
|
||||
| ingress (RTMP, WHIP) | OPT-OUT | explicitly out of scope: calls start from the site only |
|
||||
| SIP | OPT-OUT | explicitly out of scope: no phone dial-in on a public demo |
|
||||
| webhooks | OPT-OUT | not needed: the reconcile job polls room state, and the call events go through Centrifugo |
|
||||
| TURN server | OPT-OUT | deferred: plan 05 decides it with the rome network setup (ICE TCP 7891 and UDP 7892 first) |
|
||||
|
||||
## Centrifugo v6 (plans 02 to 04)
|
||||
|
||||
| capability | decision | reason |
|
||||
|---|---|---|
|
||||
| chat namespace with presence and join/leave | INTEGRATE | |
|
||||
| user namespace (user:{id}, the chat's events and video:call:incoming) | INTEGRATE | |
|
||||
| video namespace (video:session:{id}: accepted, ended, participant joined and left) | INTEGRATE | |
|
||||
| subscribe proxy on chat, user and video | INTEGRATE | |
|
||||
| one shared client per page (vue-chat-layer realtime, onUserEvent for other layers) | INTEGRATE | |
|
||||
| server HTTP API publish (lighthouse broadcast jobs) | INTEGRATE | |
|
||||
| history and recovery | OPT-OUT | not needed: the chat refetches the open conversation over HTTP on every (re)subscribe |
|
||||
| client-side publish | OPT-OUT | explicitly out of scope: browsers never publish; Go publishes after authorizing the write |
|
||||
| client RPC | OPT-OUT | not needed: every action is an HTTP call |
|
||||
| presence on the video namespace | OPT-OUT | not needed: LiveKit's participant events show who is in the call |
|
||||
|
||||
## Web Push through golem15.herald (plan 04)
|
||||
|
||||
| capability | decision | reason |
|
||||
|---|---|---|
|
||||
| VAPID key pair in .env (herald:vapid-generate, D-16) | INTEGRATE | |
|
||||
| VAPID public key route (/_herald/api/v1/push/vapid-public-key, check-local herald) | INTEGRATE | |
|
||||
| subscribe UI and service worker | OPT-OUT | deferred per D-16: herald is mounted without UI in this phase |
|
||||
| push on chat events (DMs, mentions, incoming calls) | OPT-OUT | deferred per D-16: needs the subscribe UI first |
|
||||
| push to /_herald from the site (goPaths) | OPT-OUT | deferred per D-16: the site does not call herald, so /_herald is not routed by vue-demo-app |
|
||||
@@ -0,0 +1,161 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- modules/tide/normalize.go
|
||||
- modules/tide/variables.go
|
||||
- modules/tide/record.go
|
||||
- modules/tide/replay.go
|
||||
- modules/tide/diff.go
|
||||
- modules/tide/rules.go
|
||||
- modules/tide/flow.go
|
||||
- modules/tide/fixture.go
|
||||
- modules/tide/manifest.go
|
||||
- modules/tide/rules_test.go
|
||||
- modules/tide/relative_smoke_test.go
|
||||
- modules/tide/additions_smoke_test.go
|
||||
- modules/tide/README.md
|
||||
- docs/services/parity-testing.md
|
||||
autonomous: true
|
||||
requirements: [SC-4, D-06, D-11, D-12]
|
||||
estimate:
|
||||
tokens: 150000
|
||||
raw_tokens: 150000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "modules/tide/normalize.go"
|
||||
provides: "Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference"
|
||||
key_links:
|
||||
- from: "modules/tide/normalize.go"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: a relative-time string recorded from a reference server replays against a port on another day (tide gap T-1), documented</name>
|
||||
<precondition>`go test -count=1 -short ./modules/tide/` passes and `go run ./cmd/summer docs:build --check` prints `docs:build: no problems found` before the change.</precondition>
|
||||
<files>modules/tide/normalize.go, modules/tide/relative_smoke_test.go, modules/tide/README.md, docs/services/parity-testing.md</files>
|
||||
<read_first>modules/tide/normalize.go (whole file: maskLeaf, maskDate, isDateKey, disabledPath, the mask constants), modules/tide/normalize_phase13_test.go (the table style and neutral names), modules/tide/roundtrip_test.go (how a test records with RecordFlow against httptest and replays with ReplayFlow), modules/tide/README.md (Features "Replay and diff", API reference), docs/services/parity-testing.md (the masking sentences in "Flows" and "The parity commands"), 31-PATTERNS.md "tide T-1"</read_first>
|
||||
<action>Per D-11 (every message row of the corpus carries a relative-time string) and SC-4.
|
||||
1. Red first: write `modules/tide/relative_smoke_test.go` (package `tide`) with `TestRelativeTimeMaskSmoke`. A "reference" `httptest` server answers a JSON body holding an id, a title and a key `updated_at_human` with the value `3 weeks ago`. Record a one-step flow with `RecordFlow`, save it with `SaveFlow`, load it with `LoadFlow`, and replay it with `ReplayFlow` against three "port" servers: one answering `5 weeks ago` (expect no diff), one answering the number 7 at that key (expect exactly one `Diff` whose path ends in that key), and one answering `5 weeks ago` while the step carries a normalize rule disabling that key (expect one `Diff`). Run it and see it fail.
|
||||
2. `normalize.go`: add a predicate for keys ending in `_human` next to `isDateKey`, and a mask function in the style of `maskDate`: `nil` stays `nil`; a non-empty string becomes a fixed mask token (add a constant next to the date mask token, value `{{relative}}`); anything else (a non-string, an empty string) appends a `Diff` naming the expected shape and returns the value unchanged. Call it from `maskLeaf` after the `disabledPath` check and before the id branch. A mask never hides a wrong shape.
|
||||
3. `modules/tide/README.md`: in Features "Replay and diff", add one sentence: keys ending in `_human` are relative-time strings compared by shape, and a step can switch the mask off with a `normalize` rule. `docs/services/parity-testing.md`: the same fact where masking of IDs and timestamps is described, with a neutral example.
|
||||
4. Commit: `feat(tide): compare relative-time strings by shape`.</action>
|
||||
<verify>
|
||||
<automated>go vet ./modules/tide/ && go test -count=1 -short ./modules/tide/ && go test -count=1 -run '^TestRelativeTimeMaskSmoke$' -v ./modules/tide/ 2>&1 | grep -q -- '^--- PASS: TestRelativeTimeMaskSmoke'</automated>
|
||||
<fails_when>Non-zero exit: vet or an existing tide test fails, or the `--- PASS: TestRelativeTimeMaskSmoke` line is absent (the test failed, or the filter matched nothing and go printed "no tests to run").</fails_when>
|
||||
<automated>go run ./cmd/summer docs:build --check 2>&1 | grep -q 'no problems found'</automated>
|
||||
<fails_when>Non-zero exit: the docs checker printed a problem list instead of `docs:build: no problems found`.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '_human' modules/tide/normalize.go` prints at least 1 and `grep -c '_human' modules/tide/README.md` prints at least 1.
|
||||
- `go test -count=1 -run '^TestRelativeTimeMaskSmoke$' -v ./modules/tide/` prints `--- PASS: TestRelativeTimeMaskSmoke`.
|
||||
- `D="$(git diff 2acf8e4 -- modules/tide docs cmd/summer/parity.go)" && printf '%s\n' "$D" | grep '^+' | grep -ciE 'wavepath|_wave/|wave_guest|hubot|fonoteka'` prints 0 (the diff is captured first, so a failing git is not read as a clean result).
|
||||
- `git diff --stat 2acf8e4 -- go.mod go.sum` prints nothing.
|
||||
</acceptance_criteria>
|
||||
<done>A fixture whose rows say "3 weeks ago" replays against a backend that says "5 weeks ago", a wrong shape still fails, and the README and the docs page say so.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 4: Cookie captures, extra response headers, any client label, repeated requests and the manifest's reference revisions (tide gaps T-6, T-7, T-8, T-10; D-12)</name>
|
||||
<files>modules/tide/variables.go, modules/tide/record.go, modules/tide/replay.go, modules/tide/diff.go, modules/tide/rules.go, modules/tide/rules_test.go, modules/tide/flow.go, modules/tide/fixture.go, modules/tide/manifest.go, modules/tide/additions_smoke_test.go, modules/tide/README.md, docs/services/parity-testing.md, docs/console/utilities.md</files>
|
||||
<read_first>modules/tide/variables.go (lines 20-40 the scrub patterns, 265-350 extractCapture, 685-750 the two uses of cookieRe), modules/tide/rules.go (lines 14-16, 50-65, 137-141 filterHeaders joining Set-Cookie with a newline), modules/tide/rules_test.go (lines 54-56), modules/tide/record.go (lines 17-60 the RecordFlow loop, 118-140), modules/tide/replay.go (the step loop and line 109), modules/tide/diff.go (lines 35-80), modules/tide/flow.go (Step, Request, CaptureRule), modules/tide/fixture.go (lines 48, 135-166: the strict loader and writeStep, writeRequest), modules/tide/manifest.go (Manifest, RouteCase, recordRoute's Step literal, mergeHeaders, caseRequest), modules/tide/headers_test.go, modules/tide/capture_test.go (the capture test style), modules/tide/proxy.go (where the client label becomes a directory name), modules/tide/README.md (Features "Capture rules", the Manifest rows), docs/services/parity-testing.md (the capture-source sentence in "The parity commands"), 31-PATTERNS.md "tide T-6" to "tide T-10" and finding F-9</read_first>
|
||||
<behavior>
|
||||
- `TestCookieCaptureSmoke` (T-6): a response with two Set-Cookie headers; a rule `from: response.cookie`, `name: session_ref` captures that cookie's value into the store; a missing cookie is the error "missing response cookie session_ref"; the saved fixture holds the placeholder and not the value, in the Set-Cookie header and in a later request's Cookie header; a JWT-shaped value in a cookie of any name that no rule captured refuses the write.
|
||||
- `TestExtraHeadersSmoke` (T-7): a case with `headers: {Retry-After: present, X-RateLimit-Limit: exact}` records both headers; replay passes when Retry-After differs but is non-empty and X-RateLimit-Limit is equal; it reports `header.X-Ratelimit-Limit` when that value differs and `header.Retry-After` when it is missing; a header that is in no list is not recorded.
|
||||
- `TestClientLabelSmoke` (T-8): rules with client `bot` and `web-app` load; `nuxt` and `mcp` still load; an empty label, a label with a slash, a dot or an upper-case letter is refused.
|
||||
- `TestRepeatSmoke` (T-10): a case with `repeat: 3` against a server that answers 200 twice and then 429 records one response with status 429 and the server saw three requests; replay sends three and compares the last; `repeat: 0` and an absent field mean one request; `repeat: 1001` is a validation error; a flow with `repeat` saved and loaded keeps the value.
|
||||
- `TestManifestReferenceSmoke` (D-12): a manifest with a `reference` map of two entries parses and `Manifest.Reference` holds them; a manifest without it parses; an unknown top-level key is still refused.
|
||||
</behavior>
|
||||
<action>Per D-11 (the guest cookie credential, the ten rate-bucket cases, Range and rate-limit headers), D-07 and D-17 (a recording client that is neither of the two existing labels) and D-12.
|
||||
1. T-6, `variables.go`: add the capture source `response.cookie` to `extractCapture`: parse the recorded `Set-Cookie` value (several cookies are joined with a newline by `filterHeaders`) and return the value of the cookie named `rule.Name`; error text in the style of the other sources. Replace the single-name cookie pattern in the scrubber: detect `name=value` pairs in `Cookie` and `Set-Cookie` headers for any cookie name, mask a value that equals a vars entry with that variable's placeholder, redact in logs as before, and refuse a token-shaped value that is not masked, whatever the cookie is called.
|
||||
2. T-7, `record.go`, `diff.go`, `replay.go`: `keepResponseHeaders` takes the step and also keeps every header named in `Step.Headers`. `compareHeaders` reads the map values as a mode: empty or `exact` compares the value, `present` requires a non-empty value on both sides; any other mode is a validation error when the flow or manifest is loaded.
|
||||
3. T-8, `rules.go`: accept any client label matching lower-case letters, digits, hyphen and underscore, 1 to 32 characters, starting with a letter or digit. Keep `ClientNuxt` and `ClientMCP`. Update `rules_test.go:54-56` in the same commit (F-8): the label that used to fail now loads, and the refused shapes are tested instead.
|
||||
4. T-10, `flow.go`, `fixture.go`, `manifest.go`, `record.go`, `replay.go`: add `Repeat int` (yaml `repeat,omitempty`) to `Step` and to `RouteCase`; `recordRoute` copies it into the step. `RecordFlow` and the replay loop send the request that many times in a row (0 and 1 mean once; above 1000 is refused at validation) and keep, capture from and compare only the last response. Add the field to `writeStep` so a saved flow loads again (F-9).
|
||||
5. D-12, `manifest.go`: add `Reference map[string]string` (yaml `reference,omitempty`) to `Manifest`, documented as the source revisions of the reference backend the corpus was recorded from (repository name to commit). `ValidateManifest` refuses an empty name or an empty revision.
|
||||
6. `additions_smoke_test.go`: the behavior block.
|
||||
7. `modules/tide/README.md`: Features "Capture rules" (the cookie source), "Replay and diff" (header modes), "Manifests" (repeat, reference), the client label rule; API reference rows where a described type gained a field. `docs/services/parity-testing.md`: the capture-source list gains `response.cookie`; one paragraph each for extra headers and for repeat. `docs/console/utilities.md` only if a described flag or behaviour changed.
|
||||
8. Before the commit run `go vet ./... && go test -count=1 -short ./...` once for the whole repo and record the result (a failure outside tide, cmd/summer and docs is reported, not fixed). Commit: `feat(tide): cookie captures, extra headers, client labels, repeat and manifest reference`. Then post the g15office comment on task `hgol7otp`.</action>
|
||||
<verify>
|
||||
<automated>go vet ./modules/tide/ ./cmd/summer/ && go test -count=1 -short ./modules/tide/ ./cmd/summer/ && go test -count=1 -run '^(TestCookieCaptureSmoke|TestExtraHeadersSmoke|TestClientLabelSmoke|TestRepeatSmoke|TestManifestReferenceSmoke)$' -v ./modules/tide/ 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 5</automated>
|
||||
<fails_when>Non-zero exit: vet fails, an existing tide or cmd/summer test fails (a fixture or manifest written before this plan no longer loads, the round-trip test breaks), or fewer than five `--- PASS: Test` lines are printed.</fails_when>
|
||||
<automated>go run ./cmd/summer docs:build --check 2>&1 | grep -q 'no problems found' && go test -count=1 -run '^TestDocsTree$' -v ./cmd/summer 2>&1 | grep -q -- '^--- PASS: TestDocsTree'</automated>
|
||||
<fails_when>Non-zero exit: the docs checker reports a problem, or the `--- PASS: TestDocsTree` line is absent.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '"response.cookie"' modules/tide/variables.go` prints at least 1, and `TestCookieCaptureSmoke` passes with a cookie name that tide's source does not mention.
|
||||
- `grep -c 'yaml:"repeat,omitempty"' modules/tide/flow.go modules/tide/manifest.go | awk -F: '{s+=$2} END {print s}'` prints 2 and `grep -c 'yaml:"reference,omitempty"' modules/tide/manifest.go` prints 1.
|
||||
- `go test -count=1 -run '^TestRoundTrip' -v ./modules/tide/ 2>&1 | grep -c '^--- FAIL'` prints 0.
|
||||
- `D="$(git diff 2acf8e4 -- modules/tide docs cmd/summer/parity.go)" && printf '%s\n' "$D" | grep '^+' | grep -ciE 'wavepath|_wave/|wave_guest|hubot|fonoteka'` prints 0 (the diff is captured first, so a failing git is not read as a clean result).
|
||||
- `git diff --stat 2acf8e4 -- go.mod go.sum` prints nothing.
|
||||
- `git status --porcelain -- modules/tide cmd/summer/parity.go cmd/summer/parity_test.go docs/services/parity-testing.md docs/console/utilities.md` prints nothing (everything committed).
|
||||
</acceptance_criteria>
|
||||
<done>A corpus can log in with a cookie that exists only in Set-Cookie, assert rate-limit and range headers, be recorded by a client with any label, hit a rate bucket in one case, and name the commits it was recorded from.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-01 | Information disclosure | upstream sidecars with minted credentials (T-4) | high | mitigate | a credential is rewritten only for a declared host, header and scheme; the token itself is never written, only the listed claims; `WriteUpstream` keeps refusing every other unmasked credential; `TestMintedCredentialSmoke` asserts the sidecar holds no JWT-shaped string and that an undeclared host is still refused |
|
||||
| T-31-02 | Information disclosure | cookie values in fixtures (T-6) | high | mitigate | captured cookie values go to the mode-0600 vars store; the scrubber masks any cookie value equal to a vars entry and refuses a token-shaped cookie value under any name; `TestCookieCaptureSmoke` |
|
||||
| T-31-06 | Denial of service | `repeat` and `--wait` | low | mitigate | `repeat` is bounded at 1000 and validated on load; `--wait` is a bounded duration and listeners are loopback only |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Tide core data contracts: relative masks, cookies, headers, labels, repeat and manifest reference is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-01-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: [31-01]
|
||||
files_modified:
|
||||
- modules/tide/centrifugo.go
|
||||
- modules/tide/centrifugo_golden.go
|
||||
- modules/tide/manifest.go
|
||||
- modules/tide/upstream.go
|
||||
- modules/tide/upstream_proxy.go
|
||||
- modules/tide/centrifugo_test.go
|
||||
- modules/tide/sidecar_smoke_test.go
|
||||
- modules/tide/upstream_smoke_test.go
|
||||
- cmd/summer/parity.go
|
||||
- cmd/summer/parity_test.go
|
||||
- modules/tide/README.md
|
||||
- docs/services/parity-testing.md
|
||||
- docs/console/utilities.md
|
||||
autonomous: true
|
||||
requirements: [SC-2, SC-4, D-06, D-10, D-11]
|
||||
estimate:
|
||||
tokens: 180000
|
||||
raw_tokens: 180000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "modules/tide/centrifugo.go"
|
||||
provides: "Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring"
|
||||
key_links:
|
||||
- from: "modules/tide/centrifugo.go"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: One manifest run records a broadcast sidecar and an upstream sidecar for every case, with a reset hook before each (tide gaps T-2, T-3, T-9)</name>
|
||||
<files>modules/tide/manifest.go, modules/tide/centrifugo.go, modules/tide/centrifugo_golden.go, modules/tide/upstream_proxy.go, modules/tide/centrifugo_test.go, modules/tide/sidecar_smoke_test.go, cmd/summer/parity.go, cmd/summer/parity_test.go, modules/tide/README.md, docs/services/parity-testing.md, docs/console/utilities.md</files>
|
||||
<read_first>modules/tide/manifest.go (ManifestConfig, RecordManifest, recordRoute, caseFixturePath, ReplayManifest and its per-case loop), modules/tide/centrifugo.go (whole file), modules/tide/centrifugo_golden.go (whole file, and the doc comment of NormalizePublications that lists every rule), modules/tide/upstream_proxy.go (UpstreamProxy, NewUpstreamProxy, scripted, Flush, ListenAndServe), modules/tide/upstream.go (UpstreamPath, WriteUpstream), modules/tide/centrifugo_test.go (lines 17-68: postJSON, the assertions F-8 names), modules/tide/normalize_phase13_test.go (lines 53-60), cmd/summer/parity.go (parityRecordCommand, parityReplayCommand, runParityUpstream, the flag lists), cmd/summer/parity_test.go, modules/tide/README.md (API reference rows for the recorder, goldens and the proxy; "CLI commands"), docs/services/parity-testing.md ("Broadcast goldens", "Upstream exchanges"), docs/console/utilities.md (the parity flag table), 31-PATTERNS.md "tide T-2", "tide T-3", "tide T-9", ../fonoteka.go/parity/broadcast_goldens_test.go (lines 210-241, the unordered comparison this plan generalises; read only)</read_first>
|
||||
<behavior>
|
||||
- `TestManifestCaseSidecarsSmoke`: a reference `httptest` server whose POST route publishes one message to the in-process recorder and calls one HTTPS vendor URL through the in-process upstream proxy, and whose GET route does neither. `RecordManifest` over a two-route manifest with `Recorder`, `Upstream` and `BeforeCase` set writes: both fixtures; `BroadcastPath(postFixture)` holding one publication; `UpstreamPath(postFixture)` holding one exchange; no sidecar of either kind for the GET case. The hook was called once per case, in order, with that route and case. `ReplayManifest` in self-check mode with the recorder attached passes, and fails with a publication diff after the sidecar on disk is edited.
|
||||
- `TestBroadcastPayloadMaskSmoke` (T-3): two publications whose payload holds `edited_at` and `read_at` at depth 2 and 3 with different Carbon dates, and a `created_at_human` with different strings, normalise equal; a date written with a `Z` suffix where the golden has a Carbon offset stays visible as a diff.
|
||||
- `TestRecorderPresenceAndUnsubscribeSmoke` (T-9): with `RecordUnsubscribe` set, an unsubscribe call is recorded as a `Publication`; with a presence table for one channel, a presence call for that channel answers one client entry per listed user id and another channel answers the empty result; with neither option the behaviour of the existing tests is unchanged.
|
||||
- `DiffPublicationsUnordered` returns no diff for the same publications in another order and a diff when one body differs.
|
||||
</behavior>
|
||||
<action>Per D-10 (a golden for every writing case), D-11 (vendor calls as sidecars) and D-06 (unattended).
|
||||
1. `centrifugo_golden.go`: add `BroadcastPath(fixturePath string) string` (maps `x.yaml` or `x.yml` to `x.broadcasts.yaml`, mirroring `UpstreamPath`). Add `DiffPublicationsUnordered(expected, actual []Publication) []Diff` (both sides sorted by normalised body, then `DiffPublications`). Add `DiffCaseBroadcasts(fixturePath string, pubs []Publication, store *Store, unordered bool) ([]Diff, error)`: loads the golden at `BroadcastPath(fixturePath)` (a missing file means a golden with zero publications), normalises `pubs` with `NormalizePublications` and diffs. T-3: in `normalizer.walk`, mask every string value under `$.data.payload.` whose key ends in `_at` and that matches the Carbon offset form or an ISO-8601 form, at any depth, and mask keys ending in `_human` under the payload with the Task 1 rule. Keep the id rule as it is (an id becomes a placeholder only when it equals a captured `id:*` variable). Update the doc comment of `NormalizePublications`.
|
||||
2. `centrifugo.go` (T-9): add two fields to `CentrifugoRecorderOptions`: `RecordUnsubscribe bool` (an `/unsubscribe` call is stored as a `Publication` like a publish) and `Presence map[string][]string` (channel name to user ids; a `/presence` call for a listed channel answers a `result.presence` object with one synthetic client entry per user id, each carrying `client` and `user`; other channels answer the empty result as today). Defaults keep today's behaviour.
|
||||
3. `upstream_proxy.go`: add `(*UpstreamProxy).Begin(out string) error` (sets the sidecar path of the next `Flush`, clears the recorded exchanges and errors, and makes every script entry available again; for a non-empty `out` the CA directory and the vars file must be outside its directory, as `NewUpstreamProxy` checks for `Out`; an empty `out` resets the proxy and sets no path) and `(*UpstreamProxy).Recorded() int`. `NewUpstreamProxy` accepts an empty `Out` when the proxy is driven through `Begin`; `Flush` with no path set is an error.
|
||||
4. `manifest.go`: add `type CaseHook func(ctx context.Context, route Route, c RouteCase) error` and four `ManifestConfig` fields: `BeforeCase CaseHook`, `Recorder *CentrifugoRecorder`, `BroadcastSettle time.Duration`, `Upstream *UpstreamProxy`. In `recordRoute`, per case: call `BeforeCase` (an error aborts the run and names the case); `Recorder.Reset()`; `Upstream.Begin(UpstreamPath(dest))`; `RecordFlow`; wait `BroadcastSettle` (default `DefaultBroadcastSettle`); when the recorder holds publications, normalise them, refuse a body containing the API key (as `RecordBroadcasts` does) and write a `BroadcastGolden` named after the case to `BroadcastPath(dest)`; when it holds none, write no sidecar and, under `Update`, remove a stale one; `Upstream.Flush()` only when `Recorded()` is above zero, else remove a stale sidecar under `Update`. In `ReplayManifest`, per case: `BeforeCase`, `Recorder.Reset()`, `Upstream.Begin("")` (on replay the proxy answers from its script and nothing is flushed), replay, settle, and when `Recorder` is set compare with `DiffCaseBroadcasts` (unordered); a publication diff makes the case failing.
|
||||
5. `cmd/summer/parity.go`: on `parity:record` and `parity:replay`, manifest mode only (each is an error without `--manifest`): `--broadcasts` (true/false: attach a recorder), `--centrifugo-listen` (default `tide.DefaultCentrifugoListen`), `--api-key` (default `$PARITY_CENTRIFUGO_API_KEY`), `--settle` (default `tide.DefaultBroadcastSettle`), `--presence` (a YAML file with one key `channels`, mapping a channel name to a list of user ids; names and ids are expanded with the vars store when the file is loaded), `--record-unsubscribe` (true/false), `--upstream-script` (attach an upstream proxy in script mode), `--upstream-listen` (default `tide.DefaultUpstreamProxyListen`), `--ca-dir`, `--case-hook` (path to an executable file, run directly with no shell before each case, with the environment variables `PARITY_ROUTE_ID`, `PARITY_CASE_ID` and `PARITY_SEED_HOOK`; a missing or non-executable file is refused at start, a non-zero exit aborts the run), `--wait` (a Go duration: after the listeners are bound, wait up to this long for `--target` to accept TCP connections before the first request; default 0). Every listen address must be loopback. The command prints the CA certificate path when a proxy is attached. Update the help text and the examples of both commands.
|
||||
6. `centrifugo_test.go`: keep the existing assertions for the default options and add the option cases (F-8). `sidecar_smoke_test.go`: the behavior block. `cmd/summer/parity_test.go`: a help-output check that `parity:record` lists `--case-hook`, `--broadcasts` and `--upstream-script`, and that `--broadcasts true` without `--manifest` is an error.
|
||||
7. `modules/tide/README.md`: Features (per-case sidecars; presence and unsubscribe options; payload-wide masks), API reference rows for `tide.BroadcastPath`, `tide.DiffCaseBroadcasts`, `tide.DiffPublicationsUnordered`, `tide.CaseHook`, `tide.ManifestConfig` and the two new proxy methods, and the changed description of `tide.NormalizePublications`; "CLI commands": a manifest-mode example with the new flags (neutral paths). `docs/services/parity-testing.md`: "Broadcast goldens" gains the per-case sidecar workflow and "Upstream exchanges" the per-case recording. `docs/console/utilities.md`: the flag lists of `parity:record` and `parity:replay`.
|
||||
8. Commit: `feat(tide): per-case broadcast and upstream sidecars in manifest recording`.</action>
|
||||
<verify>
|
||||
<automated>go vet ./modules/tide/ ./cmd/summer/ && go test -count=1 -short ./modules/tide/ ./cmd/summer/ && go test -count=1 -run '^(TestManifestCaseSidecarsSmoke|TestBroadcastPayloadMaskSmoke|TestRecorderPresenceAndUnsubscribeSmoke)$' -v ./modules/tide/ 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 3</automated>
|
||||
<fails_when>Non-zero exit: vet fails, an existing tide or cmd/summer test fails (including the F-8 assertions and TestDocsTree), or fewer than three `--- PASS: Test` lines are printed for the three named smoke tests.</fails_when>
|
||||
<automated>go run ./cmd/summer docs:build --check 2>&1 | grep -q 'no problems found'</automated>
|
||||
<fails_when>Non-zero exit: the docs checker reports an identifier, link, anchor or command name that does not exist.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'func BroadcastPath' modules/tide/centrifugo_golden.go` prints 1 and `grep -c 'BeforeCase' modules/tide/manifest.go` prints at least 2.
|
||||
- `go run ./cmd/summer help parity:record 2>&1 | grep -c -- 'case-hook'` prints at least 1.
|
||||
- `grep -c 'case-hook' docs/console/utilities.md` prints at least 1 and `grep -c 'tide.BroadcastPath' modules/tide/README.md` prints at least 1.
|
||||
- `go test -count=1 -run '^TestCentrifugoRecorder' -v ./modules/tide/ 2>&1 | grep -c '^--- FAIL'` prints 0.
|
||||
- `D="$(git diff 2acf8e4 -- modules/tide docs cmd/summer/parity.go)" && printf '%s\n' "$D" | grep '^+' | grep -ciE 'wavepath|_wave/|wave_guest|hubot|fonoteka'` prints 0 (the diff is captured first, so a failing git is not read as a clean result).
|
||||
</acceptance_criteria>
|
||||
<done>A porter can record a whole manifest with one command and get, next to every fixture, the publications and vendor calls that case caused, each case starting from a reset state; replaying against the reference backend proves the goldens are reproducible.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Upstream sidecars hold signed and encrypted vendor calls (tide gaps T-4, T-5)</name>
|
||||
<files>modules/tide/upstream.go, modules/tide/upstream_proxy.go, modules/tide/upstream_smoke_test.go, modules/tide/README.md, docs/services/parity-testing.md</files>
|
||||
<read_first>modules/tide/upstream.go (whole file: UpstreamCompareHeaders at 118-128, binaryScalar at 84-116, NewUpstreamFake at 195, RoundTrip at 200-229, compare at 252, WriteUpstream at 573, the credential refusal at 635-638 and fullyMasked and credentialResidueRe at 655-666), modules/tide/upstream_proxy.go (loadUpstreamScript, UpstreamScript, how a recorded request is built around lines 420-450), modules/tide/upstream_test.go (lines 16-60: upstreamTestSidecar, upstreamCall and its send helper, the neutral host), modules/tide/testdata/upstream/post_json.upstream.yaml, modules/tide/README.md (the Upstream rows and the security rules under "CLI commands"), docs/services/parity-testing.md ("Upstream exchanges", "Recording through the proxy", "Replaying offline"), 31-PATTERNS.md "tide T-4, T-5", ../fonoteka.go/parity/upstream_replay_test.go (lines 50-55: the existing callers of NewUpstreamFake whose signature must not change; read only)</read_first>
|
||||
<behavior>
|
||||
- `TestMintedCredentialSmoke`: an upstream script declares a minted credential for host `api.example.test`, header `Authorization`, scheme `Bearer`, claims `iss` and `video`. The proxy records a request carrying a bearer JWT. The written sidecar holds no JWT-shaped string; the header value is the scheme followed by a placeholder; the two claims are recorded. The fake accepts a replayed request with a different token whose `iss` and `video` claims match, and reports a problem when `iss` differs or the scheme differs. A request with a bearer token to a host that is not declared still refuses the write with the existing error.
|
||||
- The same for a header value in the form scheme word, a `t=` parameter holding a JWT and a `k=` parameter holding a key that is in the vars store: the token becomes the placeholder and the key is masked by its variable.
|
||||
- `TestUpstreamBodyComparerSmoke`: a fake with a comparer registered for a content type receives the expected and the actual body bytes and its returned problems fail `Verify`; with `OpaqueBody` registered, two different non-empty bodies pass and an empty body fails; with no comparer the existing JSON and byte comparison is unchanged.
|
||||
</behavior>
|
||||
<action>Per D-11 (LiveKit and web-push calls are recorded and asserted) and threat T-31-01.
|
||||
1. T-4 in `upstream.go` and `upstream_proxy.go`: add `type MintedCredential struct` with fields `Host` (exact, or with a leading `*.` wildcard), `Header`, `Scheme` (the auth scheme word) and `Claims []string` (JWT claim names compared by value on replay; `exp`, `iat`, `nbf` and `jti` are never compared and are refused in the list). `UpstreamScript` gains a top-level `minted` list, and `UpstreamProxyConfig` gains `Minted []MintedCredential` for callers that build the config in code. When the proxy records a request whose host and header match a declaration and whose value starts with the declared scheme, the first JWT-shaped token in the value is replaced by a fixed placeholder (`{{minted}}`), and the exchange's request records the declaration that matched and the values of the listed claims (decoded from the token's payload without verifying the signature). Add the fields to the sidecar structs, the YAML writer and the strict loader. `WriteUpstream` keeps refusing any credential header that is neither masked by a vars entry nor rewritten by a declaration; do not relax `fullyMasked` for anything else. The fake's `compare`: for a request recorded with a minted declaration, the actual header must have the same scheme and, when claims were recorded, the same claim values; the placeholder is never compared as text.
|
||||
2. T-5 in `upstream.go`: add `type UpstreamBodyComparer func(expected, actual []byte, contentType string) []string`, `type UpstreamBodyMatch struct` with `Host` (exact or `*.` wildcard, optional) and `ContentType` (prefix, optional; at least one of the two is required), `(*UpstreamFake).SetBodyComparer(match UpstreamBodyMatch, cmp UpstreamBodyComparer)`, and `OpaqueBody` (an `UpstreamBodyComparer` that reports a problem only when exactly one side is empty). `compare` consults the first matching comparer for the body only; headers, method and URL are compared as before. Keep the signature of `NewUpstreamFake`.
|
||||
3. `upstream_smoke_test.go`: the behavior block, with the builder style and neutral host of `upstream_test.go`.
|
||||
4. `modules/tide/README.md`: Features and API reference rows for `tide.MintedCredential`, `tide.UpstreamBodyComparer`, `tide.UpstreamBodyMatch`, `tide.OpaqueBody` and the new method on `tide.UpstreamFake`; the security rules gain one sentence: a credential is written only as a variable placeholder or, when declared as minted, as a scheme and a placeholder. `docs/services/parity-testing.md`: "Upstream exchanges" explains minted credentials and body comparers with a neutral vendor.
|
||||
5. Commit: `feat(tide): minted credentials and body comparers for upstream sidecars`.</action>
|
||||
<verify>
|
||||
<automated>go vet ./modules/tide/ && go test -count=1 -short ./modules/tide/ ./cmd/summer/ && go test -count=1 -run '^(TestMintedCredentialSmoke|TestUpstreamBodyComparerSmoke)$' -v ./modules/tide/ 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 2</automated>
|
||||
<fails_when>Non-zero exit: vet fails, an existing upstream test fails (the default credential refusal changed, or an old sidecar no longer loads), or fewer than two `--- PASS: Test` lines are printed.</fails_when>
|
||||
<automated>go run ./cmd/summer docs:build --check 2>&1 | grep -q 'no problems found'</automated>
|
||||
<fails_when>Non-zero exit: the docs checker reports a problem.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c 'type MintedCredential struct' modules/tide/upstream.go modules/tide/upstream_proxy.go | awk -F: '{s+=$2} END {print s}'` prints 1.
|
||||
- `grep -c 'func (f \*UpstreamFake) SetBodyComparer' modules/tide/upstream.go` prints 1 and `grep -c 'func NewUpstreamFake(s UpstreamSidecar, store \*Store) \*UpstreamFake' modules/tide/upstream.go` prints 1.
|
||||
- `go test -count=1 -run '^TestUpstream' -v ./modules/tide/ 2>&1 | grep -c '^--- FAIL'` prints 0.
|
||||
- `grep -c 'tide.MintedCredential' modules/tide/README.md` prints at least 1.
|
||||
</acceptance_criteria>
|
||||
<done>A vendor call signed with a fresh token, or carrying an encrypted body, can be recorded without a secret in the sidecar and asserted on replay by scheme, claims and an application-supplied body comparer.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-03 | Elevation of privilege | `--case-hook` executes a program | medium | mitigate | the flag takes a path to an executable file and runs it directly with no shell; route and case ids are passed as environment variables, never interpolated into a command line; a missing or non-executable file is refused at start |
|
||||
| T-31-04 | Spoofing | masks and opaque comparers hiding real differences | medium | mitigate | every mask is shape-checked and emits a `Diff` on a wrong shape; the opaque comparer and every body comparer are opt-in per host or content type; a step can disable the relative-time mask; defaults are unchanged and pinned by the existing tests |
|
||||
| T-31-05 | Information disclosure | broadcast sidecars | medium | mitigate | the per-case writer reuses the API-key body check of `RecordBroadcasts`; the authorization header is stored as a boolean only; `WriteBroadcastGolden` keeps refusing token-shaped bodies |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Tide per-case broadcast/upstream sidecars, minted credentials, body comparers and CLI wiring is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-02-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,224 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 03
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- ../sm-wavepath-app/.gitmodules
|
||||
- ../sm-wavepath-app/summer.yaml
|
||||
- ../sm-wavepath-app/go.mod
|
||||
- ../sm-wavepath-app/go.work
|
||||
- ../sm-wavepath-app/app/app.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/
|
||||
- ../sm-wavepath-app/config/app.yaml
|
||||
- ../sm-wavepath-app/parity/pins.env
|
||||
- ../sm-wavepath-app/parity/parity.env
|
||||
- ../sm-wavepath-app/parity/php_parity.sh
|
||||
- ../sm-wavepath-app/parity/case_hook.sh
|
||||
- ../sm-wavepath-app/scripts/parity-stack.sh
|
||||
- ../sm-wavepath-app/parity/README.md
|
||||
- ../sm-wavepath-app/README.md
|
||||
autonomous: false
|
||||
requirements: [SC-1, D-01, D-02, D-05, D-08, D-20, D-21]
|
||||
estimate:
|
||||
tokens: 200000
|
||||
raw_tokens: 200000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "sm-wavepath-app skeleton and fail-closed isolated PHP parity stack is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../sm-wavepath-app/.gitmodules"
|
||||
provides: "sm-wavepath-app skeleton and fail-closed isolated PHP parity stack"
|
||||
key_links:
|
||||
- from: "../sm-wavepath-app/.gitmodules"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
sm-wavepath-app skeleton and fail-closed isolated PHP parity stack.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: one route goes from PHP at the pinned commits to a recorded fixture, a green PHP self-replay, a pending manifest entry the Go harness loads and a gate that prints the pending count</name>
|
||||
<reversibility rating="costly">D-02: the repository name, module path and parity/ layout are what WavePath's agent and every later WavePath phase build on; a rename later touches every import. Task 5 asks before the first push.</reversibility>
|
||||
<precondition>`../sm-wavepath-app` does not exist; `docker info` answers; `GIT_OPTIONAL_LOCKS=0 git -C /media/nvme/dev/jz/wavepath.org cat-file -t 7c517191879cada7bb50ac05f474f3ac02ad4b98` prints `commit` and `GIT_OPTIONAL_LOCKS=0 git -C /media/nvme/dev/jz/wavepath.org/plugins/golem15/chat cat-file -t fbfbcf98e3392269c6e98801270669dc5d845b3b` prints `commit`.</precondition>
|
||||
<files>../sm-wavepath-app/.gitignore, ../sm-wavepath-app/.gitmodules, ../sm-wavepath-app/summer.yaml, ../sm-wavepath-app/go.mod, ../sm-wavepath-app/go.sum, ../sm-wavepath-app/go.work, ../sm-wavepath-app/main.go, ../sm-wavepath-app/plugins.gen.go, ../sm-wavepath-app/boot_test.go, ../sm-wavepath-app/config/app.yaml, ../sm-wavepath-app/app/app.go, ../sm-wavepath-app/plugins/golem15/wavepath/go.mod, ../sm-wavepath-app/plugins/golem15/wavepath/plugin.go, ../sm-wavepath-app/plugins/golem15/wavepath/README.md, ../sm-wavepath-app/parity/pins.env, ../sm-wavepath-app/parity/parity.env, ../sm-wavepath-app/parity/php_parity.sh, ../sm-wavepath-app/parity/wavepath_reset.php, ../sm-wavepath-app/parity/fixtureplugin/plugin.go, ../sm-wavepath-app/parity/fixtureplugin/seed.go, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/seed/bootstrap.yaml, ../sm-wavepath-app/parity/fixtures/routes/GET___wave_api_v1_community_friends_jwt.yaml, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/testmain_test.go, ../sm-wavepath-app/scripts/parity-stack.sh, ../sm-wavepath-app/scripts/check-parity.sh</files>
|
||||
<read_first>../sm-demo-app/summer.yaml, ../sm-demo-app/go.mod, ../sm-demo-app/go.work, ../sm-demo-app/.gitmodules, ../sm-demo-app/boot_test.go, ../sm-demo-app/testmain_test.go, ../sm-demo-app/plugins/demo/plugin.go (lines 35-126), ../fonoteka.go/go.mod, ../fonoteka.go/go.work, ../fonoteka.go/app/app.go, ../fonoteka.go/parity/php_parity.sh (whole file), ../fonoteka.go/parity/fonoteka_reset.php (lines 1-100 and 640-676), ../fonoteka.go/parity/fixtureplugin/plugin.go, ../fonoteka.go/parity/fonoteka_seed_test.go (lines 1-80 and 600-660), ../fonoteka.go/parity/manifest.yaml (lines 1-40), ../fonoteka.go/parity/parity_test.go (lines 40-210), ../fonoteka.go/parity/synthetic_test.go (lines 36-104), ../fonoteka.go/parity/fixtures/seed/bootstrap.yaml, modules/tide/README.md ("Usage", "CLI commands"), 31-RESEARCH.md ("Recording commit and pins", "PHP stack from outside the checkout", "The sm-wavepath-app skeleton"), 31-PATTERNS.md (the sections for summer.yaml, app/app.go, manifest.yaml, php_parity.sh, wavepath_reset.php, fixtureplugin and parity_test.go). From the PHP contract, read-only with `git show`: the route at `routes.php` line 616 (`GET community/friends`), `controllers/api/CommunityFriendsController.php` (index), `classes/responses/ApiResponse.php`, and the code that issues the session JWT at login</read_first>
|
||||
<action>Per D-02, D-01, D-08, D-20, D-04, D-21 and D-15.
|
||||
1. Repository: `git init -b master ../sm-wavepath-app`. `.gitignore` covers the built binary `wavepath`, `tmp/`, `*.vars`, `*.vars.yaml` and editor files. `summer.yaml`: module `git.golem15.com/golem15/sm-wavepath-app`, binary `wavepath`, the eight shared plugin entries in the order of the interfaces block, then `golem15.wavepath` with module `git.golem15.com/golem15/sm-wavepath-app/plugins/golem15/wavepath`. Add the eight shared plugins as submodules at `plugins/golem15/NAME` with `ssu` (or `git submodule add -b BRANCH`), each checked out at the released tag listed in the interfaces block. `go.mod` requires the framework and the plugins at those tags and replaces the framework with `../summercms.go`; `go.work` uses `.`, the eight submodule directories and `./plugins/golem15/wavepath`, and carries the framework replace. Check each plugin's go.mod for other `replace` lines and override any in go.work.
|
||||
2. App plugin shell `plugins/golem15/wavepath` (own go.mod, package `wavepath`): `const ID = "golem15.wavepath"`, a `Plugin` type holding `*backpack.App`, `Requires()` returning the eight shared plugin ids, `Register` and `Boot` that only store the app, `init()` calling `party.Register`, compile-time assertion for `party.Plugin`. README in the module README structure (H1, one sentence, import line, Overview, Usage, Testing), marked as the start of WavePath's Go app.
|
||||
3. `app/app.go`: `PluginIDs` (the nine ids) and `Handler` in the shape of fonoteka's, with the nine plugins blank-imported. `config/app.yaml`: the application config the binary and tests load, with test-only values only. Generate `plugins.gen.go` and `main.go` with the `summer build` command (install the CLI with `go install ./cmd/summer` from `summercms.go`, then run `summer build` in the app directory); do not hand-write them. `boot_test.go`: `TestBootAllPlugins` in the shape of the demo's.
|
||||
4. `parity/pins.env`: `KEY=value` lines for `SUPERPROJECT`, and one `PIN_NAME` per pinned repository (wavepath, chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, user, websockets, oauthserver, journal, and the three clients), with full 40-character ids read from `git ls-tree 7c517191879cada7bb50ac05f474f3ac02ad4b98` in the checkout. They must agree with the research table; a difference is reported, not resolved silently. `parity/parity.env`: the test-only overlay values as `KEY=value` data: `APP_KEY`, `JWT_SECRET`, `CENTRIFUGO_API_KEY`, `CENTRIFUGO_SECRET` (at least 32 bytes), `CENTRIFUGO_PROXY_SECRET`, a VAPID pair generated once for tests, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`, `TURNSTILE_SECRET`, `TURNSTILE_SITE_KEY`, and a JWT lifetime long enough for a whole recording run.
|
||||
5. `parity/php_parity.sh` (bash, `set -euo pipefail`, structure of fonoteka's): variables `WAVEPATH_SRC` (default `/media/nvme/dev/jz/wavepath.org`), `PARITY_ROOT` (default `${XDG_CACHE_HOME:-$HOME/.cache}/summercms/wavepath-parity`), `PARITY_INSTANCE` (default `corpus`), `PHP_ROOT="$PARITY_ROOT/$PARITY_INSTANCE/php"`, vars file `$PARITY_ROOT/$PARITY_INSTANCE/vars.yaml` (mode 0600). Subcommands for the tracer:
|
||||
- `export`: with `GIT_OPTIONAL_LOCKS=0`, archive the superproject at `SUPERPROJECT` into `PHP_ROOT`, then every gitlink that `git ls-tree -r` lists at that commit (recursively) from its own repository directory at the recorded commit; a missing commit object is a refusal naming the repository (never fetch there). Copy `vendor/` with `rsync -a` (source read-only), and any other untracked directory Composer installed that the application needs to boot. Write `PHP_ROOT/.parity-export` listing each path and commit. Never copy `.env`.
|
||||
- `db`: start (or reuse) the container `wavepath-parity-mariadb` from the local image `mariadb:11`, published on `127.0.0.1:33306` only, and create the database `wavepath_parity_$PARITY_INSTANCE`.
|
||||
- `export_env` (a function): refuse a database name without `parity` or a non-loopback host; export `DB_*`, `CACHE_DRIVER=file`, `SESSION_DRIVER=array`, `MAIL_MAILER=array`, `APP_URL`, `APP_DEBUG=false`, `SCOUT_DRIVER=null` and the values of `parity/parity.env` (parsed as data).
|
||||
- `artisan ARGS`, `reset` (runs `artisan winter:up`, then `artisan tinker --execute` requiring the absolute path of `parity/wavepath_reset.php` with `PARITY_VARS_OUT` set), `serve` (PHP's built-in server on `127.0.0.1:8423` with `-d error_reporting=8191`, cwd `PHP_ROOT`), `rows SELECT` (one SELECT without a semicolon).
|
||||
- After `export`, assert through `artisan tinker` that the file of `Golem15\Chat\Classes\AttachmentStreamer` lies under `PHP_ROOT`; otherwise print `refuse: PHP loaded chat from outside the parity root` and exit 1.
|
||||
6. `scripts/parity-stack.sh` in its thinnest form: `up` (mode `readonly`: `BROADCAST_ENABLED=false`, `QUEUE_CONNECTION=database` with no worker, `HTTPS_PROXY` and `https_proxy` set to `http://127.0.0.1:9`, then export, db, reset and serve, recording the process group), `down` (stops this instance's PHP server; the container stays), `self-replay` (runs `summer parity:replay --manifest parity/manifest.yaml --fixtures parity/fixtures --target http://127.0.0.1:8423 --vars VARSFILE --self-check true` and prints its summary line).
|
||||
7. `parity/wavepath_reset.php`, tracer scope: users `alice@parity.test` and `dave@parity.test` with explicit ids, an accepted friendship between them, id floors with `ALTER TABLE … AUTO_INCREMENT`, the session JWT of alice minted with the application's own token code, and only the vars file as output (`jwt:alice`, `id:alice`, `id:dave`; never echo a value).
|
||||
8. `parity/fixtureplugin`: the plugin shell (`ID()` `parity.fixtureplugin`, `Requires()` `golem15.wavepath`, constructed in process, never registered) and `Seed(ctx, db, store)` writing the same two users, the friendship and the same variable names, with alice's JWT minted through the user plugin's token service.
|
||||
9. `parity/manifest.yaml`: version 1, auth groups `jwt`, `guest`, `bot`, `webhook`, `realtime`, the seed spec, and one route: id `GET /_wave/api/v1/community/friends jwt`, status `pending`, seed hook `community`, two cases: `alice` (request header `Cookie: token={{jwt:alice}}`, `Accept: application/json`) and `unauthenticated` (no cookie). Record both from PHP with `summer parity:record --manifest`, then run the self-replay. If the recorded body holds a relative-time string that only plan 31-01's mask can compare and that plan has not committed it yet, record `GET /_wave/api/v1/push/vapid-public-key jwt` as the tracer route instead and say so in the SUMMARY (the friends route is then recorded in plan 31-05).
|
||||
10. `parity/testmain_test.go` and `parity/parity_test.go`: a testcontainers Postgres (`postgres:16-alpine`) started in `TestMain` after `flag.Parse()` unless `testing.Short()`; `seedHooks` with `community` calling `fixtureplugin.Seed`; `TestParityCorpus` loads and validates the manifest, serves `app.Handler` through `httptest`, loads every fixture of a pending route without sending it, replays every ported route strictly, and logs one line `parity: ported P pending N`. A pending route is never counted as passing.
|
||||
11. `scripts/check-parity.sh` in its first form: the corpus stage (fixtures of the manifest load), the replay stage (`go test -count=1 -json ./parity`, failing on a failed test, on zero tests and on a missing `TestParityCorpus`), an optional `--self-replay` stage calling `scripts/parity-stack.sh up`, `self-replay` and `down`, and one summary line `check-parity: recorded R/T ported P pending N`. The flags `--allow-unrecorded` and `--allow-pending-foundation` are accepted.
|
||||
12. Commit in `../sm-wavepath-app` in logical steps (skeleton; PHP stack; scenario seed; manifest and fixture; harness and gate), staging by path.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app vet . ./app/... ./parity/... ./plugins/golem15/wavepath/... && go -C ../sm-wavepath-app test -count=1 -short . ./app/... ./plugins/golem15/wavepath/... && go -C ../sm-wavepath-app test -count=1 -run '^TestBootAllPlugins$' -v . 2>&1 | grep -q -- '^--- PASS: TestBootAllPlugins' && go -C ../sm-wavepath-app test -count=1 -run '^TestParityCorpus$' -v ./parity 2>&1 | grep -q -- '^--- PASS: TestParityCorpus'</automated>
|
||||
<fails_when>Non-zero exit: vet or a short test fails, the nine plugins do not boot, or the `--- PASS: TestParityCorpus` line is absent (the manifest or the fixture did not load, Docker was not reachable, or the filter matched nothing).</fails_when>
|
||||
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh --self-replay --allow-unrecorded --allow-pending-foundation 2>&1)" && printf '%s\n' "$OUT" | grep -qE 'failing 0 unrecorded 0' && printf '%s\n' "$OUT" | grep -qE '^check-parity: recorded 1/1 ported 0 pending 1'</automated>
|
||||
<fails_when>Non-zero exit from the gate (the PHP stack refused or did not boot, the self-replay found a difference), or the output lacks the self-replay line `failing 0 unrecorded 0`, or lacks the summary line `check-parity: recorded 1/1 ported 0 pending 1`.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '^\[submodule ' ../sm-wavepath-app/.gitmodules` prints 8, and `git -C ../sm-wavepath-app submodule status` prints eight lines, none starting with `+` or `-`.
|
||||
- `grep -c 'golem15.wavepath' ../sm-wavepath-app/summer.yaml` prints 1; `grep -c 'parity.fixtureplugin' ../sm-wavepath-app/summer.yaml ../sm-wavepath-app/plugins.gen.go ../sm-wavepath-app/app/app.go | awk -F: '{s+=$2} END {print s}'` prints 0.
|
||||
- The recorded fixture has the `alice` case with status 200 and the `unauthenticated` case with the status PHP answered, and holds no JWT: `grep -cE 'eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.' ../sm-wavepath-app/parity/fixtures/routes/*.yaml | awk -F: '{s+=$2} END {print s}'` prints 0.
|
||||
- `stat -c %a "${XDG_CACHE_HOME:-$HOME/.cache}/summercms/wavepath-parity/corpus/vars.yaml"` prints 600.
|
||||
- `grep -vE '^\s*#' ../sm-wavepath-app/parity/php_parity.sh ../sm-wavepath-app/scripts/parity-stack.sh | grep -cE 'worktree add|git (-C [^ ]+ )?(checkout|stash|commit|fetch|pull)|composer (install|update)|(npm|pnpm) (install|ci|add)'` prints 0.
|
||||
- `git -C ../sm-wavepath-app remote` prints nothing.
|
||||
</acceptance_criteria>
|
||||
<done>The application repository exists and boots, the PHP reference backend runs from the pinned commits without touching the other agent's checkout, and one real route is recorded, self-replays green on PHP and is counted as pending by the Go harness and by the gate.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: The stack fails closed: record mode, instances, snapshot and per-case restore, status and check, and a self-test of every refusal</name>
|
||||
<precondition>Task 1's verify passed: `../sm-wavepath-app/scripts/parity-stack.sh up` and `down` work in read-only mode.</precondition>
|
||||
<files>../sm-wavepath-app/scripts/parity-stack.sh, ../sm-wavepath-app/parity/php_parity.sh, ../sm-wavepath-app/parity/case_hook.sh, ../sm-wavepath-app/parity/README.md</files>
|
||||
<read_first>../sm-wavepath-app/scripts/parity-stack.sh and ../sm-wavepath-app/parity/php_parity.sh (as Task 1 left them), ../fonoteka.go/scripts/dev-stack.sh (lines 1-130 the header contract and helpers; the functions is_loopback, parse_env_file, check_keys, check_services, port_busy, launch, stop_groups, cleanup, up, down, status, check and the dispatch at the end), ../fonoteka.go/parity/php_parity.sh (lines 10-73 and 120-220), 31-RESEARCH.md ("Recommended shape" items 1 to 6, pitfalls 3, 4, 5 and 8), 31-PATTERNS.md ("parity-stack.sh", "Fail-closed scripts", "No Analog Found"). From the PHP contract with `git show`: the config files that name the environment variables for Centrifugo, LiveKit, VAPID, Turnstile, the queue and the cache</read_first>
|
||||
<action>Per D-08 and D-20, closing threats T-31-08 and T-31-10.
|
||||
1. `scripts/parity-stack.sh`: a header comment listing every subcommand and environment variable and the rule that lines starting with `refuse:` or `missing:` mean the script stopped and `warn:` lines never stop it. Helpers `say`, `warn`, `refuse`, `fail` in the style of fonoteka's; `set -euo pipefail`; `unset FORCE_COLOR`; a `curl --noproxy '*'` wrapper; env files parsed as `KEY=value` data, never executed. Subcommands:
|
||||
- `up [--mode readonly|record]`. Mode `record` exports `BROADCAST_DRIVER=centrifugo`, `BROADCAST_ENABLED=true`, `CENTRIFUGO_API_URL=http://127.0.0.1:RECORDER_PORT/api`, `QUEUE_CONNECTION=sync`, `HTTPS_PROXY` and `https_proxy` at `http://127.0.0.1:PROXY_PORT`, `NO_PROXY=127.0.0.1,localhost`, the parity CA through `-d curl.cainfo` and `-d openssl.cafile` on the PHP server, `LIVEKIT_URL=https://livekit.example.test` (a name that never resolves, so a call that bypasses the proxy fails), and the LiveKit, VAPID and Turnstile values of `parity/parity.env`. Before starting PHP it waits up to `PARITY_LISTENER_WAIT` seconds (default 60) for the recorder and the proxy to accept connections and then prints `refuse: recorder not listening on …` or `refuse: upstream proxy not listening on …` and exits 1. Mode `readonly` is Task 1's.
|
||||
- `down` stops this instance's process groups (TERM, then KILL after 10 seconds); `down --all` also stops the container when no other instance has a pid file.
|
||||
- `status` lists the instance, mode, ports, database and whether each process answers.
|
||||
- `check` verifies: the export's `.parity-export` equals `parity/pins.env`; the chat class-path assertion; the database name contains `parity` and the host is loopback; the vars file is mode 0600; the keys of the vars file equal `parity/scenario.vars.keys` once that file exists; in record mode both listeners answer. It prints every failed check and exits 1 if any failed.
|
||||
- `selftest` runs each refusal against planted input in a scratch directory with no real service: a database name without `parity`, a non-loopback `DB_HOST`, a non-loopback target, record mode with nothing listening, a `pins.env` that differs from the export record, a vars file with mode 0644. Each must print its `refuse:` line and exit non-zero; `selftest` prints `selftest: ok` only when all did.
|
||||
- Ports per instance: `corpus` uses 8423 (PHP), 8424 (recorder), 8425 (upstream proxy), 8422 (session proxy); any other instance name adds 100 to each. The MariaDB container is shared, one database per instance.
|
||||
2. `parity/php_parity.sh`: add `snapshot` (dump the instance database after `reset` into `$PARITY_ROOT/$PARITY_INSTANCE/snapshot.sql`, AUTO_INCREMENT floors included) and `restore` (load the snapshot, clear the export's file cache so rate-limit counters start at zero); add `script FILE [ARGS]` (run a PHP file through `artisan tinker` with the overlay, for plan 31-08). Keep the `rows` guard.
|
||||
3. `parity/case_hook.sh` (executable): reads `PARITY_ROUTE_ID`, `PARITY_CASE_ID` and `PARITY_SEED_HOOK`, calls `php_parity.sh restore`, and applies the case's scenario variant when the reset script defines one for that case id. Exit non-zero on any failure. Measure one restore and write the time into the README.
|
||||
4. `parity/README.md`: the runbook so far: what the parity root holds, the pins, the two modes, the instance rule, every refusal and what it means, how to bring the stack up and down, and the rule that nothing is written in the PHP checkout.
|
||||
5. Commit: `feat(parity): fail-closed stack with record mode, instances and per-case restore`.</action>
|
||||
<verify>
|
||||
<automated>OUT="$(../sm-wavepath-app/scripts/parity-stack.sh selftest 2>&1)" && printf '%s\n' "$OUT" | grep -qx 'selftest: ok'</automated>
|
||||
<fails_when>Non-zero exit, or the line `selftest: ok` is absent: a planted bad input (database name without parity, non-loopback host or target, missing listeners, pin mismatch, vars mode) was accepted.</fails_when>
|
||||
<automated>( ../sm-wavepath-app/scripts/parity-stack.sh up --mode readonly && ../sm-wavepath-app/scripts/parity-stack.sh check && ../sm-wavepath-app/parity/php_parity.sh snapshot && PARITY_ROUTE_ID=x PARITY_CASE_ID=y PARITY_SEED_HOOK=community ../sm-wavepath-app/parity/case_hook.sh && OUT="$(../sm-wavepath-app/scripts/parity-stack.sh self-replay 2>&1)" && printf '%s\n' "$OUT" | grep -q 'failing 0 unrecorded 0'; RC=$?; ../sm-wavepath-app/scripts/parity-stack.sh down; exit $RC )</automated>
|
||||
<fails_when>Non-zero exit: `up` or `check` printed a `refuse:` line, the snapshot or the case hook failed, or the self-replay after a restore no longer prints `failing 0 unrecorded 0` (the restore does not bring back the recorded state).</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `PARITY_LISTENER_WAIT=2 ../sm-wavepath-app/scripts/parity-stack.sh up --mode record` with nothing on 8424 exits non-zero and prints a line starting with `refuse: recorder not listening`.
|
||||
- `grep -c 'refuse:' ../sm-wavepath-app/scripts/parity-stack.sh` prints at least 6.
|
||||
- `grep -vE '^\s*#' ../sm-wavepath-app/parity/php_parity.sh ../sm-wavepath-app/scripts/parity-stack.sh ../sm-wavepath-app/parity/case_hook.sh | grep -cE 'worktree add|git (-C [^ ]+ )?(checkout|stash|commit|fetch|pull)|composer (install|update)|(npm|pnpm) (install|ci|add)'` prints 0.
|
||||
- `test -x ../sm-wavepath-app/parity/case_hook.sh` exits 0.
|
||||
- `docker ps --format '{{.Names}} {{.Ports}}' | grep wavepath-parity-mariadb` shows the port published on `127.0.0.1` only.
|
||||
</acceptance_criteria>
|
||||
<done>The stack cannot serve PHP in record mode without the recorder and the proxy, cannot use a database that is not a parity database, and can return to the recorded state before every case.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 5: Go-ahead for the remote of sm-wavepath-app and its module path</name>
|
||||
<read_first>`git -C ../sm-wavepath-app log --oneline`, the module path in ../sm-wavepath-app/go.mod and summer.yaml, the gate's summary line from Task 4, memory note "sm- repo naming"</read_first>
|
||||
<acceptance_criteria>
|
||||
- The user's answer is recorded in the SUMMARY with the confirmed module path and remote URL, or "local".
|
||||
</acceptance_criteria>
|
||||
<decision>Create the remote for sm-wavepath-app and push master, and is `git.golem15.com/golem15/sm-wavepath-app` the right module path?</decision>
|
||||
<context>D-02 rates the repository name, module path and parity/ layout as costly: WavePath's agent and every later WavePath phase build on them, and a rename later touches every import. Right now the repository is a skeleton, so a rename is one `go mod edit` and a small import rewrite. The other applications live under `golem15/` except `sm-bm-app` (`jakub/`). Plans 31-03 to 31-06 work on the local repository either way; a push is not needed to continue. Claude cannot create the repository on git.golem15.com; if you choose to push, the remote must exist first.</context>
|
||||
<options>
|
||||
<option id="push">
|
||||
<name>Keep the path, push to git@git.golem15.com:golem15/sm-wavepath-app.git</name>
|
||||
<pros>The work is backed up and WavePath's agent can clone it.</pros>
|
||||
<cons>The name and path are public from now on.</cons>
|
||||
</option>
|
||||
<option id="rename">
|
||||
<name>Another namespace or name (say which), then push</name>
|
||||
<pros>Fixed while it costs almost nothing.</pros>
|
||||
<cons>A second remote to create.</cons>
|
||||
</option>
|
||||
<option id="local">
|
||||
<name>Keep it local for now</name>
|
||||
<pros>Nothing leaves this machine; the decision can wait.</pros>
|
||||
<cons>No backup; a later rename costs more with every plan.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "push" (after creating the empty remote), "rename NAMESPACE/NAME" or "local".</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 6: Act on the answer: rename if asked, push if allowed, and leave the repository clean</name>
|
||||
<reversibility rating="costly">A pushed module path is what other checkouts and go.sum files will name; after this point a rename is a coordinated change.</reversibility>
|
||||
<precondition>Task 5 has an answer.</precondition>
|
||||
<files>../sm-wavepath-app/go.mod, ../sm-wavepath-app/go.work, ../sm-wavepath-app/summer.yaml, ../sm-wavepath-app/plugins.gen.go, ../sm-wavepath-app/main.go, ../sm-wavepath-app/app/app.go, ../sm-wavepath-app/plugins/golem15/wavepath/go.mod, ../sm-wavepath-app/README.md</files>
|
||||
<read_first>The Task 5 answer, ../sm-wavepath-app/go.mod, summer.yaml and every Go file that imports the module path (`grep -rl 'sm-wavepath-app' ../sm-wavepath-app --include=*.go --include=*.yaml --include=go.mod --include=go.work`)</read_first>
|
||||
<action>Per D-02.
|
||||
- "rename NAMESPACE/NAME": change the module path in `go.mod`, the app plugin's `go.mod`, `summer.yaml` and every import; regenerate `plugins.gen.go` and `main.go` with `summer build`; if the directory name changes too, stop and ask (the plans of this phase name `../sm-wavepath-app`). Run Task 4's first verify command again, commit `chore: module path NAMESPACE/NAME`, then continue as "push" with the new URL.
|
||||
- "push": `git -C ../sm-wavepath-app remote add origin URL`, `git push -u origin master`, and check that `git ls-remote origin refs/heads/master` equals `git rev-parse HEAD`. A refused push (the remote does not exist, no permission) is reported with the exact message; nothing else is tried.
|
||||
- "local": add no remote. Record it.
|
||||
In every case: no tag. Post the g15office comment on task `hgol7otp` (plan 31-03 executed; repository local or pushed).</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app vet . ./app/... ./parity/... ./plugins/golem15/wavepath/... && go -C ../sm-wavepath-app test -count=1 -short . ./app/... ./plugins/golem15/wavepath/... && test -z "$(git -C ../sm-wavepath-app status --porcelain)" && test -z "$(git -C ../sm-wavepath-app tag)"</automated>
|
||||
<fails_when>Non-zero exit: the repository no longer vets or passes its short tests after a rename, has uncommitted changes, or has a tag.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- With "push" or "rename": the commit id printed by `git -C ../sm-wavepath-app ls-remote origin refs/heads/master` equals `git -C ../sm-wavepath-app rev-parse HEAD`. With "local": `git -C ../sm-wavepath-app remote` prints nothing.
|
||||
- The SUMMARY records the answer, the module path and the remote URL or "local".
|
||||
</acceptance_criteria>
|
||||
<done>The repository has the name and path the user confirmed, is pushed only if the user said so, and the next plans can work on it.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-07 | Tampering | scripts touching the other agent's checkout | high | mitigate | export by `git archive` at commit ids and rsync with the checkout as source only; `GIT_OPTIONAL_LOCKS=0`; acceptance greps the scripts for checkout, stash, commit, fetch, pull, worktree and install commands; the PHP server's cwd and storage are the export |
|
||||
| T-31-08 | Information disclosure | a recording run reaching real vendors | high | mitigate | record mode refuses to start PHP unless the recorder and the upstream proxy listen; read-only mode sets the HTTPS proxy to a closed loopback port and a queue with no worker; LiveKit uses a host name that never resolves; the overlay holds test-only values from `parity/parity.env`; `selftest` proves the refusals |
|
||||
| T-31-10 | Tampering | recording against a real database | high | mitigate | the database is a container published on loopback only; the name must contain `parity`; the checkout's `.env` is never read or copied; `selftest` plants a bad name and a non-loopback host |
|
||||
| T-31-13 | Tampering | recording a version other than the freeze | medium | mitigate | export by the commit ids of `parity/pins.env`; `.parity-export` compared by `check`; the class-path assertion on a class that exists only at the chat pin |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
sm-wavepath-app skeleton and fail-closed isolated PHP parity stack is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-03-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on: [31-01, 31-02, 31-03]
|
||||
files_modified:
|
||||
- ../sm-wavepath-app/parity/scenario.md
|
||||
- ../sm-wavepath-app/parity/scenario.vars.keys
|
||||
- ../sm-wavepath-app/parity/scenario-deferred.txt
|
||||
- ../sm-wavepath-app/parity/wavepath_reset.php
|
||||
- ../sm-wavepath-app/parity/fixtureplugin/
|
||||
- ../sm-wavepath-app/parity/fixtures/seed/bootstrap.yaml
|
||||
- ../sm-wavepath-app/parity/manifest.yaml
|
||||
- ../sm-wavepath-app/parity/routes.snapshot
|
||||
- ../sm-wavepath-app/parity/foundation-routes.txt
|
||||
- ../sm-wavepath-app/parity/check_corpus.go
|
||||
- ../sm-wavepath-app/parity/parity_test.go
|
||||
- ../sm-wavepath-app/parity/harness_test.go
|
||||
- ../sm-wavepath-app/parity/upstream_replay_test.go
|
||||
- ../sm-wavepath-app/scripts/check-parity.sh
|
||||
autonomous: true
|
||||
requirements: [SC-1, SC-3, D-04, D-09, D-15, D-16, D-18, D-19]
|
||||
estimate:
|
||||
tokens: 180000
|
||||
raw_tokens: 180000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../sm-wavepath-app/parity/scenario.md"
|
||||
provides: "Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate"
|
||||
key_links:
|
||||
- from: "../sm-wavepath-app/parity/scenario.md"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: The whole scenario is seeded on both sides with the same ids and variable names</name>
|
||||
<files>../sm-wavepath-app/parity/scenario.md, ../sm-wavepath-app/parity/scenario.vars.keys, ../sm-wavepath-app/parity/scenario-deferred.txt, ../sm-wavepath-app/parity/wavepath_reset.php, ../sm-wavepath-app/parity/fixtureplugin/plugin.go, ../sm-wavepath-app/parity/fixtureplugin/seed.go, ../sm-wavepath-app/parity/seed_test.go, ../sm-wavepath-app/parity/fixtures/seed/bootstrap.yaml</files>
|
||||
<read_first>../sm-wavepath-app/parity/wavepath_reset.php and ../sm-wavepath-app/parity/fixtureplugin/seed.go (as Task 1 left them), ../fonoteka.go/parity/fonoteka_reset.php (whole file), ../fonoteka.go/parity/fonoteka_seed_test.go (lines 1-120 and 600-700), 31-CONTEXT.md (D-04, D-11, D-18, D-19, D-21), 31-RESEARCH.md ("Rate buckets in the corpus", "Route table", "Gap map", "Upstream vendors the corpus reaches", "Pattern 2", pitfalls 2, 4, 6 and 10), the models of the eight shared Go plugins (`../sm-wavepath-app/plugins/golem15/*/models/`) and their test fixture plugins (`fixture_plugin_test.go`) for how rows are created. From the PHP contract with `git show`: the models of the wavepath plugin and of the shared plugins, `Plugin.php` lines 160-558 (what a created group, a new member and a message trigger), and the migrations under `updates/` that add host columns to shared tables</read_first>
|
||||
<behavior>
|
||||
- `TestScenarioSeeds` (Docker): `fixtureplugin.Seed` on a migrated database succeeds twice in a row (idempotent) and every seeded row has the id the scenario names.
|
||||
- `TestScenarioVarsMatch`: the variable names the Go seeder wrote, together with the names in `parity/scenario-deferred.txt`, equal the names in `parity/scenario.vars.keys`; a name missing on one side fails with that name.
|
||||
- `TestFixtureAbsentFromProduction`: `parity.fixtureplugin` is not in `app.PluginIDs`, `summer.yaml` or `plugins.gen.go`.
|
||||
- `TestSeededJWTAuthenticates` (Docker): a request to a route of the user plugin behind `jwt.auth` with `Cookie: token=` and the seeded JWT of alice is authenticated as alice.
|
||||
</behavior>
|
||||
<action>Per D-04, D-21, D-11 (a user on each side of every access rule), D-18 and D-19.
|
||||
1. `parity/scenario.md` is the single definition. It names every identity, row and explicit id, and for each the variable it produces (`id:NAME`, `jwt:IDENTITY`, `token:NAME`, `code:NAME`). Minimum content:
|
||||
- Identities: `alice` (owner of the group `harbor`), `bob` (admin of `harbor`, two push subscriptions, offline), `carol` (member, with a user status), `dave` (no group; accepted friend of alice), `erin` (banned from `harbor`), `frank` (stranger: no friendship, no group), `olive` (member, the one user the presence script reports online), an unclaimed imported member, one user per rate bucket for the ten 429 cases (`rl-wave-api`, `rl-community-join` and so on), and a bot user with a `wave_` token of scope `chat:bot`.
|
||||
- Groups: `harbor` (closed, with an invite code and a custom code free for the invite cases), `plaza` (open, for the open-join cases), `cellar` (closed, alice is not a member, for denials), each with its chat and channels as the PHP lifecycle creates them.
|
||||
- Channels of `harbor`: the system default `general`, a private channel, an archived channel, a category, a personal category, pins, a favourite, a muted channel.
|
||||
- Messages: plain messages, one thread with replies, a message per delete, edit, pin and reaction case, a webhook message, an attachment; no http(s) URL in any message except in the unfurl cases.
|
||||
- Direct messages: a conversation between alice and dave with a thread.
|
||||
- Friendships: alice and dave accepted, bob to alice pending, alice to carol sent, each case that changes one having its own row.
|
||||
- Video: a call link, a channel guest link, a guest session in each state the guest routes need.
|
||||
- Forum: categories, threads and posts in `harbor`. Notes (D-18): diary entries of alice, one shared publicly and one shared with `harbor`.
|
||||
- Push: the VAPID test pair and subscriptions whose endpoints are on real public push host names (the PHP endpoint rule resolves them); the subscription key pairs are test-only and listed in the scenario.
|
||||
- A webhook on `general` with its token, a custom emoji, and the rows the 17 uncalled routes need for a success case each (D-19).
|
||||
Each access rule of D-11 has an identity on each side of it; the document says which.
|
||||
2. `parity/wavepath_reset.php`: the whole scenario, idempotent, wiping the scenario's state by id before recreating it, with explicit ids and AUTO_INCREMENT floors per table (steps of 10000000, so ids of different tables never collide when values become variables). Per-case variants are selected by an environment variable naming the case. It mints the session JWT of every identity and writes only the vars file. It never prints a secret.
|
||||
3. `parity/fixtureplugin/seed.go`: the same rows through the Go plugins' models for every table that exists (the shared plugins' tables, and the user rows), with the same explicit ids, Postgres sequences set to the same floors, and the same variable names written into the `*tide.Store`. The JWTs are minted through the user plugin with the secret from `parity/parity.env`. A scenario row whose host table does not exist yet is not seeded and its variable names go into `parity/scenario-deferred.txt`, one per line with the phase that ports the table (31.1 or 31.2); this plan adds no host table.
|
||||
4. `parity/scenario.vars.keys`: the sorted variable names, written from a PHP reset run (names only, no values). `parity/fixtures/seed/bootstrap.yaml`: the seed flow without a login step (D-21).
|
||||
5. `parity/seed_test.go`: the behavior block.
|
||||
6. Run `scripts/parity-stack.sh up`, `check` (it now compares the vars keys), `php_parity.sh snapshot`, `down`. Commit: `feat(parity): the community scenario on PHP and Go`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app vet ./parity/... && go -C ../sm-wavepath-app test -count=1 -run '^(TestScenarioSeeds|TestScenarioVarsMatch|TestFixtureAbsentFromProduction|TestSeededJWTAuthenticates)$' -v ./parity 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 4</automated>
|
||||
<fails_when>Non-zero exit: fewer than four `--- PASS: Test` lines (a seeding error, a variable name on one side only, the fixture plugin listed for production, or the seeded cookie JWT not accepted by the Go guard; a skipped Docker test also yields fewer than four).</fails_when>
|
||||
<automated>( ../sm-wavepath-app/scripts/parity-stack.sh up --mode readonly && ../sm-wavepath-app/scripts/parity-stack.sh check; RC=$?; ../sm-wavepath-app/scripts/parity-stack.sh down; exit $RC )</automated>
|
||||
<fails_when>Non-zero exit: the PHP reset failed on the fresh MariaDB database, or `check` printed a `refuse:` line because the vars file's key set differs from `parity/scenario.vars.keys`.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -cE '^(jwt|id):(alice|bob|carol|dave|erin|frank|olive)$' ../sm-wavepath-app/parity/scenario.vars.keys` prints 14.
|
||||
- `grep -c '^jwt:rl-' ../sm-wavepath-app/parity/scenario.vars.keys` prints at least 8 (the buckets keyed by user; the guest, bot and webhook buckets use their own credentials).
|
||||
- Every line of `../sm-wavepath-app/parity/scenario-deferred.txt` names a variable and one of `31.1` or `31.2`: `grep -vcE ' (31\.1|31\.2)$' ../sm-wavepath-app/parity/scenario-deferred.txt` prints 0.
|
||||
- `grep -cE 'eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.' ../sm-wavepath-app/parity/scenario.md ../sm-wavepath-app/parity/scenario.vars.keys ../sm-wavepath-app/parity/wavepath_reset.php | awk -F: '{s+=$2} END {print s}'` prints 0.
|
||||
</acceptance_criteria>
|
||||
<done>Both backends start every case from the same named state, and a request can log in on either side with a seeded cookie.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 4: The 196-route manifest with every route pending, the corpus checker and snapshot, a harness that can fail, and the complete gate</name>
|
||||
<files>../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/routes.snapshot, ../sm-wavepath-app/parity/foundation-routes.txt, ../sm-wavepath-app/parity/check_corpus.go, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/harness_test.go, ../sm-wavepath-app/parity/upstream_replay_test.go, ../sm-wavepath-app/scripts/check-parity.sh, ../sm-wavepath-app/parity/README.md, ../sm-wavepath-app/README.md, ../sm-wavepath-app/plugins/golem15/wavepath/plugin_test.go</files>
|
||||
<read_first>../sm-wavepath-app/parity/manifest.yaml, parity_test.go and scripts/check-parity.sh (as Task 1 left them), ../fonoteka.go/parity/check_corpus.go (whole file: flags at 120-129, run at 138-206, scanSecrets at 437-515, the PHP route parser at 549-648, sanitizeFile at 717, the ported-versus-fixture check at 766-779), ../fonoteka.go/parity/check_corpus_test.go (how the checker is built and tested beside a test package), ../fonoteka.go/parity/routes.snapshot, ../fonoteka.go/parity/parity_test.go (lines 106-310), ../fonoteka.go/parity/synthetic_test.go, ../fonoteka.go/parity/upstream_replay_test.go (whole file), scripts/check-phase19.1.sh (lines 1-80: stages, the go test -json detectors, the self-test stage, the Docker message), ../sm-demo-app/scripts/check-all.sh (lines 42-82), 31-RESEARCH.md ("Count", "Route table", "Consumer gate"), 31-PATTERNS.md ("check_corpus.go", "check-parity.sh", "parity_test.go"). The route file, read-only: `GIT_OPTIONAL_LOCKS=0 git -C /media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath show a08ed0a34d1af72314a3453bb25593c6a1660056:routes.php`</read_first>
|
||||
<behavior>
|
||||
- `go run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --allow-incomplete` (run in the app directory) exits 0 and prints `routes 196` and the recorded and pending counts; with `--routes FILE` it also checks the SHA-256 of the route file against the snapshot and that the parsed ids equal the snapshot.
|
||||
- It exits non-zero when: the manifest has a route the snapshot lacks or the reverse; a route's auth group differs from the classifier's; `--require-recorded` is set and a case has no fixture; a ported case's manifest status differs from its fixture; `--check-secrets` finds a JWT shape, a `wave_` token, an invite code, a webhook token, a call-link code or a cookie value in a fixture or sidecar that is not an allow-listed test constant.
|
||||
- `TestParityHarnessCanFail`: over a synthetic manifest and handler, the suite fails for a ported route whose response differs, for a ported route without a fixture, for a ported route with an unknown seed hook and for a mutated recorded response; a pending route is reported as pending and is not in the passing count.
|
||||
- `TestUpstreamSidecarsAreReplayed`: fails on an upstream sidecar of a ported route that no case replayed (it passes while no route is ported).
|
||||
- `TestNoWaveRoutesYet` in the app plugin: the shell registers no route (the foundation slice adds them in plans 31-06 and 31-07).
|
||||
- The gate: `scripts/check-parity.sh --self-test` feeds planted go test -json output (a failed test, zero tests, a skipped required test, a missing required test name) and planted checker output to its detectors and passes only when each is refused.
|
||||
</behavior>
|
||||
<action>Per D-09, D-15 as amended by D-16, D-10 (the realtime routes are ordinary routes) and D-05.
|
||||
1. `parity/check_corpus.go` (`package main`, run with `go run`, built beside the test package the way fonoteka does it): constants for the 194 routes of the route file and the 196 expected ids; the PHP route parser over `Route::group` frames and `Route::` verbs, filtered to the D-09 prefixes (`/_wave/api/v1/community`, `/_wave/api/v1/guest`, `/_wave/api/v1/push`, the four bot and token routes under `/api/v1`, `/hooks/{token}`); the classifier mapping prefix and middleware to `jwt`, `guest`, `bot`, `webhook`; the two realtime ids as extras in group `realtime`. Flags `--manifest`, `--snapshot`, `--routes`, `--fixtures`, `--allow-incomplete`, `--require-recorded`, `--require-clients`, `--check-secrets`, `--foundation FILE` (prints `foundation F pending G`), `--write-snapshot` (writes the snapshot from `--routes`). Route id is `METHOD path auth_group`; a fixture name is the id with slashes and spaces replaced, as `sanitizeFile` does. Secret patterns beyond fonoteka's: `wave_` bearer tokens, 40-character webhook tokens, invite and call-link codes that equal a vars entry, any cookie value; the test-only constants of `parity/parity.env` are allow-listed by exact value.
|
||||
2. `parity/routes.snapshot`: written once with `--write-snapshot` from the route file at `a08ed0a` (digest and the 196 ids). `parity/manifest.yaml`: all 196 routes, status `pending`, seed hook `community`, the auth group of each, the tracer route keeping its two cases; no other cases yet (plan 31-05 writes them). `parity/foundation-routes.txt`: the 36 foundation-slice route ids, one per line.
|
||||
3. `parity/parity_test.go`: assert the manifest has 196 routes; one subtest per route; the pending and ported branches as in the tracer; a `coverage` subtest. `parity/harness_test.go`: `TestParityHarnessCanFail` over a synthetic manifest and handler. `parity/upstream_replay_test.go`: the upstream switch (the fake put on each request's context with `fetchguard.WithTransport`; a case without a sidecar gets an empty fake, so any vendor call fails it) and `TestUpstreamSidecarsAreReplayed`, copied from fonoteka's with this suite's names.
|
||||
4. `scripts/check-parity.sh`, complete: stages `self-test`, `corpus` (the checker with `--check-secrets`, and `--require-recorded` unless `--allow-unrecorded`), `replay` (`go test -count=1 -json ./parity`, parsed: a failed test, a skipped required test, zero tests, a missing required test name or an unreachable Docker daemon fails the stage; required names `TestParityCorpus`, `TestParityHarnessCanFail`, `TestUpstreamSidecarsAreReplayed`, `TestScenarioVarsMatch`, `TestFixtureAbsentFromProduction`), `foundation` (every id in `parity/foundation-routes.txt` is `ported` unless `--allow-pending-foundation`), `consumers` (`sm-bm-app`: `go build ./...` and its tests `TestChatMounted`, `TestRealtimeDefaultDriver`, `TestRealtimeRoutes`, `TestRealtimeConfigDefaults`, `TestRemoteKeyOverride`; `sm-demo-app`: `go vet` and `go test -short` of the root package and `./plugins/demo/...`; directories from `BM_DIR` and `DEMO_DIR` with `../` defaults), optional `--self-replay`. One summary line: `check-parity: recorded R/196 ported P pending N foundation-pending F`. Each allow flag prints `NOT COMPLETE: …` with the count it let through. Exit 0 only when no stage failed.
|
||||
5. `parity/README.md`: the corpus boundary (D-09), the manifest conventions, the checker's flags, the harness rules (pending never passes), the gate's stages and flags. `README.md` at the root: what the repository is, the plugin list, quick start (`summer build`, `go test -short ./...`), a pointer to `parity/README.md`.
|
||||
6. Commit in steps: checker and snapshot; manifest; harness; gate and READMEs.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app vet . ./app/... ./parity/... ./plugins/golem15/wavepath/... && go -C ../sm-wavepath-app run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --allow-incomplete --check-secrets --foundation parity/foundation-routes.txt 2>&1 | grep -qx 'routes 196' && go -C ../sm-wavepath-app test -count=1 -run '^(TestParityCorpus|TestParityHarnessCanFail|TestUpstreamSidecarsAreReplayed)$' -v ./parity 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 3</automated>
|
||||
<fails_when>Non-zero exit: vet fails, the checker does not print the line `routes 196` (a route missing, extra or in the wrong group, or a secret found), or fewer than three `--- PASS: Test` lines are printed.</fails_when>
|
||||
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh --allow-unrecorded --allow-pending-foundation 2>&1)" && printf '%s\n' "$OUT" | grep -qE '^check-parity: recorded [0-9]+/196 ported 0 pending 196 foundation-pending 36$' && ! ../sm-wavepath-app/scripts/check-parity.sh >/dev/null 2>&1</automated>
|
||||
<fails_when>Non-zero exit: the gate with both allow flags failed a stage (self-test, corpus, replay or a consumer build), the summary line is absent or has other counts, or the gate without flags exited 0 although routes are unrecorded and the foundation slice is pending.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c '^ - id: ' ../sm-wavepath-app/parity/manifest.yaml` prints 196 and `grep -c 'status: ported' ../sm-wavepath-app/parity/manifest.yaml` prints 0.
|
||||
- `wc -l < ../sm-wavepath-app/parity/foundation-routes.txt` prints 36.
|
||||
- `go -C ../sm-wavepath-app run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --require-recorded` exits non-zero (195 routes have no fixture yet).
|
||||
- `../sm-wavepath-app/scripts/check-parity.sh --self-test` exits 0 and prints a line for each planted case it refused.
|
||||
- `git -C ../sm-wavepath-app status --porcelain` prints nothing.
|
||||
</acceptance_criteria>
|
||||
<done>The corpus has its full route list, a checker that ties it to the PHP route file, a replay suite proven able to fail, and a gate that says how many routes are recorded, ported and pending and refuses to pass early.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-09 | Information disclosure | secrets in committed fixtures | high | mitigate | captured values live in the mode-0600 vars file under the parity root; the reset script writes only that file; `check_corpus --check-secrets` scans fixtures and sidecars for JWT shapes, `wave_` tokens, webhook tokens, codes and cookie values; `.gitignore` covers vars files |
|
||||
| T-31-11 | Spoofing | a gate that passes on nothing | high | mitigate | the gate parses `go test -json`, requires named tests, fails on zero tests, skips and a missing Docker daemon; its self-test feeds planted output to each detector; `TestParityHarnessCanFail` proves a pending route is never a pass |
|
||||
| T-31-12 | Elevation of privilege | the fixture plugin in a production binary | high | mitigate | constructed in process by tests only; never registered with `party.Register`, never in `summer.yaml`, `plugins.gen.go` or `app.PluginIDs`; `TestFixtureAbsentFromProduction` |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Scenario on both sides, 196 pending-route manifest, corpus checker, harness and fail-closed gate is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-04-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 05
|
||||
type: execute
|
||||
wave: 4
|
||||
depends_on: [31-02, 31-04]
|
||||
files_modified:
|
||||
- ../sm-wavepath-app/parity/manifest.yaml
|
||||
- ../sm-wavepath-app/parity/capture-rules.yaml
|
||||
- ../sm-wavepath-app/parity/capture_clients.mjs
|
||||
- ../sm-wavepath-app/parity/record_corpus.sh
|
||||
- ../sm-wavepath-app/parity/presence.yaml
|
||||
- ../sm-wavepath-app/parity/accepted-differences.yaml
|
||||
- ../sm-wavepath-app/parity/README.md
|
||||
- ../sm-wavepath-app/parity/fixtures/routes/
|
||||
- ../sm-wavepath-app/parity/upstream/
|
||||
- ../sm-wavepath-app/parity/parity_test.go
|
||||
- ../sm-wavepath-app/parity/broadcast_test.go
|
||||
- ../sm-wavepath-app/parity/upstream_replay_test.go
|
||||
- ../sm-wavepath-app/scripts/parity-stack.sh
|
||||
- ../sm-wavepath-app/scripts/check-parity.sh
|
||||
autonomous: true
|
||||
requirements: [SC-1, SC-2, D-06, D-07, D-09, D-10, D-11, D-12, D-13, D-17, D-19]
|
||||
estimate:
|
||||
tokens: 260000
|
||||
raw_tokens: 260000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../sm-wavepath-app/parity/manifest.yaml"
|
||||
provides: "Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay"
|
||||
key_links:
|
||||
- from: "../sm-wavepath-app/parity/manifest.yaml"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: one client writing route records its response, every publication and every vendor call, then self-replays green</name>
|
||||
<precondition>31-01 and 31-02 summaries exist; `scripts/parity-stack.sh selftest` passes; the manifest has 196 routes and the tracer route is still pending.</precondition>
|
||||
<files>../sm-wavepath-app/parity/capture-rules.yaml, ../sm-wavepath-app/parity/capture_clients.mjs, ../sm-wavepath-app/parity/record_corpus.sh, ../sm-wavepath-app/parity/presence.yaml, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/clients/, ../sm-wavepath-app/parity/fixtures/routes/, ../sm-wavepath-app/parity/upstream/scripts/, ../sm-wavepath-app/parity/README.md, ../sm-wavepath-app/scripts/parity-stack.sh</files>
|
||||
<read_first>../sm-wavepath-app/parity/README.md, manifest.yaml, scenario.md, scenario.vars.keys, capture-rules.yaml if present, scripts/parity-stack.sh, parity/php_parity.sh, parity/case_hook.sh, 31-01-SUMMARY.md, 31-02-SUMMARY.md, 31-03-SUMMARY.md, 31-04-SUMMARY.md, modules/tide/README.md sections for proxy, manifest recording, broadcasts and upstream scripts, ../fonoteka.go/parity/capture_clients.mjs, ../fonoteka.go/parity/capture-rules.yaml, /media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/stores/channelChatStore.ts and the API module for the selected writing route, /media/nvme/dev/jz/wavepath.org/hubot-wavepath/src/rest.mjs</read_first>
|
||||
<action>Per D-07, D-10, D-11, D-17, D-20 and D-21.
|
||||
1. Choose one writing route called by the SPA whose seeded path is short and deterministic; prefer a friendship request or a group update rather than a messaging route reserved for 31.1. Run the SPA through `summer parity:proxy` against the `corpus` PHP instance and capture the exact method, path, headers and body. The script resolves Playwright from the existing client tree and writes nothing there. It starts client processes with environment variables only and tracks and terminates every child.
|
||||
2. `capture-rules.yaml`: client labels `nuxt` and `hubot`; keep only contract headers; capture server-minted ids/codes/cookies into the mode-0600 vars store; scrub every credential. Add route-specific captures only where the request-only spec cannot carry them. Keep Cookie but never its value.
|
||||
3. Convert the observed tracer session into a committed request-only spec and merge its success plus D-11 denial/422 cases into the manifest. Use a fresh scenario identity for a rate-bucket case if the selected route has a named secondary bucket.
|
||||
4. Add the smallest upstream script needed by the route. When no vendor call is expected, the attached proxy remains empty and fails on any unexpected call. Add `presence.yaml` with `olive` online so the online branch is deterministic.
|
||||
5. `record_corpus.sh`: fail-closed wrapper around stack check, pin/reference check, `summer parity:record` with the manifest, vars, `--broadcasts true`, recorder and proxy loopback addresses, upstream script, presence table, case hook and wait; then `summer parity:replay --self-check true --require-recorded false`. It accepts a route/case selector for the tracer and no selector for the full run. It never evaluates env files as shell.
|
||||
6. Record the tracer. Require its fixture and, because it writes, its broadcast sidecar. Require an upstream sidecar exactly when the reference made a vendor call. Re-run against PHP and require zero diffs. Document the command and generated files in `parity/README.md`.
|
||||
7. Commit request/spec/script changes separately from generated fixtures: `feat(parity): capture one community writing route`; `test(parity): record the community tracer from PHP`.</action>
|
||||
<verify>
|
||||
<automated>OUT="$(cd ../sm-wavepath-app && parity/record_corpus.sh --tracer --self-replay 2>&1)" && printf '%s\n' "$OUT" | grep -qE 'failing 0 unrecorded 0' && printf '%s\n' "$OUT" | grep -q 'broadcast'</automated>
|
||||
<fails_when>Non-zero exit, no `failing 0 unrecorded 0` line, or no broadcast evidence: the stack or pin check refused, the observed request did not record, a publication differed, an unexpected vendor call escaped the script, or self-replay was not executed.</fails_when>
|
||||
<automated>cd ../sm-wavepath-app && go run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --allow-incomplete --check-secrets --foundation parity/foundation-routes.txt</automated>
|
||||
<fails_when>Non-zero exit: the tracer changed the route inventory, wrote a live secret, used an invalid fixture name, or marked a pending route as passed.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- The tracer's request method, path, request headers and body are byte-for-byte derived from a proxy session, not reconstructed from controller code.
|
||||
- Its success fixture exists and contains no JWT, session cookie, bot token, webhook token or vendor credential.
|
||||
- Its `.broadcasts.yaml` exists and contains all publications emitted before the settle interval ended; deleting one publication makes self-replay fail.
|
||||
- `git -C /media/nvme/dev/jz/wavepath.org status --porcelain` is not run or changed by the scripts; script source contains no checkout, stash, fetch, pull, install or commit command.
|
||||
</acceptance_criteria>
|
||||
<done>One real writing path is observed from a real client, recorded with all side effects and self-replays green from committed files.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Expand proxy-derived specs and case depth across every route the SPA and bot call</name>
|
||||
<precondition>The tracer self-replay is green and both clients resolve their existing dependencies without an install.</precondition>
|
||||
<files>../sm-wavepath-app/parity/capture_clients.mjs, ../sm-wavepath-app/parity/capture-rules.yaml, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/clients/, ../sm-wavepath-app/parity/upstream/scripts/, ../sm-wavepath-app/parity/upstream/helpers/, ../sm-wavepath-app/parity/presence.yaml, ../sm-wavepath-app/parity/README.md</files>
|
||||
<read_first>Task 1 outputs, 31-RESEARCH.md "Route table", "Rate buckets in the corpus", "Routes that none of the three clients calls", "Upstream vendors", /media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/ request call sites including src/sw.js, /media/nvme/dev/jz/wavepath.org/hubot-wavepath/src/rest.mjs, the pinned PHP route file and controller validation rules through read-only `git show`, modules/tide/README.md minted credentials and body comparers</read_first>
|
||||
<action>Per D-07, D-09, D-10, D-11 and D-17.
|
||||
1. Drive named, deterministic SPA journeys over the seeded scenario: group administration, membership and invite paths; chat/channel/DM/thread/commands; reactions, emoji, prefs, pins and attachments; presence/status; forum; notes; push; video and guest. Drive the bot's four REST paths with its seeded token. Capture request sessions only; do not use `wavepath-mcp`.
|
||||
2. Build a coverage map from every proxy request to one of the 196 manifest ids. Deduplicate the same route shape while preserving materially different client bodies and headers. A request outside D-09 is reported and excluded; a D-09 client-called route with no captured request stops the task.
|
||||
3. For each captured route add the observed client cases and D-11 depth: unauthenticated, non-member/forbidden or not-found per access rule, UI-triggerable 422, and exactly one repeated 429 case per named rate bucket across the corpus. Do not invent statuses or envelopes; record them.
|
||||
4. Add script answers for LiveKit Twirp, web-push, unfurl HTML/images, webhook icons and Turnstile. Helpers may decode protobuf or decrypt push payloads using scenario test keys and register a tide body comparer. If push decryption proves impossible (research A6), compare endpoint, headers, non-empty body and request count and record the limitation in README; do not accept arbitrary empty bodies.
|
||||
5. Prove pinned requests stay inside the upstream proxy before running the broad recording: a planted public hostname resolves to a test address, the proxy sees the original host, and a closed proxy makes the PHP request fail. Keep scenario text free of URLs except explicit unfurl cases.
|
||||
6. Write client flow provenance into README: client commit, session name, manifest routes covered, and excluded out-of-corpus requests. Commit specs and scripts; generated fixtures remain for Task 3.</action>
|
||||
<verify>
|
||||
<automated>cd ../sm-wavepath-app && node parity/capture_clients.mjs --check-deps && node parity/capture_clients.mjs --check-coverage --manifest parity/manifest.yaml</automated>
|
||||
<fails_when>Non-zero exit: existing client dependencies cannot be resolved, a client-called D-09 route lacks a captured request, a session maps to an unknown route, or wavepath-mcp appears as a corpus client.</fails_when>
|
||||
<automated>cd ../sm-wavepath-app && parity/record_corpus.sh --check-upstream-confinement</automated>
|
||||
<fails_when>Non-zero exit: a pinned PHP request bypasses the loopback proxy, loses its host name, accepts a closed proxy, or a script answer does not match the vendor request.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- Coverage output reports 177 client-called route ids and 17 no-client route ids.
|
||||
- The manifest contains exactly ten 429 cases, one for each named bucket, with the required repeat count.
|
||||
- Client source trees have no modified or untracked file caused by capture.
|
||||
- Every upstream script host is a test/public vendor hostname from the pinned PHP code; no private, production credential or developer endpoint is present.
|
||||
</acceptance_criteria>
|
||||
<done>Every client-called corpus route has a proxy-derived request contract and complete denial, validation and rate-limit depth ready for unattended recording.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Add the 17 hand-written success specs, record all 196 routes and freeze a green PHP self-replay</name>
|
||||
<precondition>Task 2 reports exactly 177 client-called and 17 no-client routes, and the stack's pin check matches the reference revisions.</precondition>
|
||||
<files>../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/fixtures/routes/, ../sm-wavepath-app/parity/upstream/scripts/, ../sm-wavepath-app/parity/accepted-differences.yaml, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/broadcast_test.go, ../sm-wavepath-app/parity/upstream_replay_test.go, ../sm-wavepath-app/parity/README.md, ../sm-wavepath-app/scripts/check-parity.sh</files>
|
||||
<read_first>Task 2 coverage output, 31-CONTEXT.md D-12/D-13/D-19, 31-RESEARCH.md table of 17 uncalled routes, pinned controllers and validation rules through read-only `git show`, ../fonoteka.go/parity/broadcast_goldens_test.go, ../fonoteka.go/parity/upstream_replay_test.go, ../sm-oauthserver-plugin/testdata/parity/deviations.yaml</read_first>
|
||||
<action>Per D-06, D-09, D-10, D-11, D-12, D-13 and D-19.
|
||||
1. Add one request-only success spec for each of the 17 no-client routes: three forum category operations; nine channel category/show/restore/mute operations; five note compatibility routes; webhook ingest; webhook icon (use the exact final list from the coverage map—if the research table's grouping count differs, the route ids, not prose arithmetic, win). Derive bodies from the pinned controller validation rules and scenario rows, then record PHP's actual result. Add denial and validation cases where applicable.
|
||||
2. Fill `manifest.reference` from the `.parity-export`/pins produced by 31-02: superproject plus wavepath, user, chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, websockets, oauthserver and journal commits. The recording wrapper refuses any mismatch.
|
||||
3. Create `accepted-differences.yaml` version 1 with an empty `differences` list and schema comments requiring id, route, case, path, reason, security rationale and sign-off. The replay loader rejects an entry without all fields; no entry is needed for PHP self-replay.
|
||||
4. Run the full unattended recording from a fresh snapshot. For every writing case require a broadcast sidecar, including an explicit empty golden when the PHP reference emits none. For every case require either the expected upstream sidecar or proof that no upstream call occurred. Capture all generated ids/codes/cookies in the vars store and scan again before commit.
|
||||
5. Extend parity checks: `TestBroadcastSidecarsAreComplete` rejects an orphan sidecar, a writing case without a golden and an unexpected publication; `TestUpstreamSidecarsAreReplayed` rejects orphans and unexpected calls; `TestPHPFixturesComplete` requires all 196 routes and all cases recorded. Keep all routes pending—the corpus is recorded, not ported.
|
||||
6. Run PHP self-replay across all fixtures and sidecars. Re-record a nondeterministic case only after fixing its capture/normalization/spec; never edit the expected response. Update README with duration, counts, revisions and the one-command rerun. Commit generated corpus in reviewable groups without mixing code changes.
|
||||
7. Tighten `scripts/check-parity.sh`: without `--allow-unrecorded`, corpus completeness is mandatory; with `--allow-pending-foundation`, the still-pending foundation is the only allowed incompleteness. It prints `recorded 196/196 ported 0 pending 196 foundation-pending 36` at this point.</action>
|
||||
<verify>
|
||||
<automated>cd ../sm-wavepath-app && parity/record_corpus.sh --self-replay 2>&1 | tee "${TMPDIR:-/tmp}/wavepath-self-replay.log" && grep -qE 'recorded 196/196.*failing 0.*unrecorded 0' "${TMPDIR:-/tmp}/wavepath-self-replay.log"</automated>
|
||||
<fails_when>Non-zero exit or missing summary: any route/case is unrecorded, a response/header/publication/vendor call differs, a reference pin differs, a sidecar is absent or orphaned, or a secret scan fails.</fails_when>
|
||||
<automated>cd ../sm-wavepath-app && go run ./parity/check_corpus.go --manifest parity/manifest.yaml --snapshot parity/routes.snapshot --require-recorded --require-clients --check-secrets --foundation parity/foundation-routes.txt && go test -count=1 -run '^(TestPHPFixturesComplete|TestBroadcastSidecarsAreComplete|TestUpstreamSidecarsAreReplayed)$' -v ./parity 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 3</automated>
|
||||
<fails_when>Non-zero exit, corpus checker refusal, or fewer than three PASS lines: route/client coverage is incomplete, a secret exists, or fixture/broadcast/upstream completeness is not proven.</fails_when>
|
||||
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh --allow-pending-foundation 2>&1)" && printf '%s\n' "$OUT" | grep -qx 'check-parity: recorded 196/196 ported 0 pending 196 foundation-pending 36'</automated>
|
||||
<fails_when>Non-zero exit or exact summary absent: the fail-closed gate did not run all corpus, replay and consumer stages or accepted an unrecorded case.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `manifest.reference` equals the export pins and has no abbreviated commit.
|
||||
- Exactly 196 manifest route entries have recorded fixtures; exactly 17 are marked with hand-written provenance, and none of those 17 lacks a success case.
|
||||
- Every writing case has a broadcast sidecar, including an explicit zero-publication golden; every sidecar belongs to one manifest case.
|
||||
- `accepted-differences.yaml` has zero entries.
|
||||
- Every route remains `pending`; neither Phase 31.1 nor 31.2 implementation is pulled into this plan.
|
||||
</acceptance_criteria>
|
||||
<done>The committed corpus is a complete, secret-free observation of all 196 PHP routes at frozen commits, with publications and vendor calls, and it self-replays green unattended.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-14 | Information disclosure | proxy sessions and generated fixtures | high | mitigate | mode-0600 vars store, tide capture and scrub rules, second `check_corpus --check-secrets` scan, exact secret-shape tests, and client source trees remain read-only |
|
||||
| T-31-15 | Information disclosure | sync PHP jobs reaching real vendors | high | mitigate | stack refuses record mode unless the loopback upstream proxy listens; confinement test proves pinned requests traverse it and a closed proxy fails |
|
||||
| T-31-16 | Tampering | recording wrong PHP revisions | high | mitigate | manifest.reference is populated from the export pins; stack check compares full commits and refuses before recording |
|
||||
| T-31-17 | Repudiation | hand-written cases presented as client traffic | medium | mitigate | per-route provenance marks `proxy:nuxt`, `proxy:hubot` or `hand-written:D-19`; coverage check requires exactly the decided 17 hand-written routes |
|
||||
| T-31-18 | Tampering | missing publications or vendor calls treated as success | high | mitigate | explicit broadcast golden for every writing case, empty fake for cases without upstream sidecars, orphan/completeness tests and PHP self-replay |
|
||||
| T-31-19 | Denial of service | repeated 429 cases and broad client journeys | medium | mitigate | bounded tide repeat, dedicated identities, snapshot restore per case, loopback-only services and child-process cleanup |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Full 196-route PHP recording with client provenance, publications, upstreams and green self-replay is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-05-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 06
|
||||
type: execute
|
||||
wave: 5
|
||||
depends_on: [31-05]
|
||||
files_modified:
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/plugin.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/routes.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/buckets.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/chat.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/realtime.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/api/response.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/api/actor.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/context.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/channel_access.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/forum_access.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/classes/authorizer.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/updates/
|
||||
- ../sm-wavepath-app/parity/manifest.yaml
|
||||
- ../sm-wavepath-app/parity/foundation_smoke_test.go
|
||||
autonomous: true
|
||||
requirements: [SC-1, SC-2, D-01, D-03, D-10, D-11, D-16, D-21]
|
||||
estimate:
|
||||
tokens: 150000
|
||||
raw_tokens: 150000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
|
||||
provides: "Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime"
|
||||
key_links:
|
||||
- from: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer: recorded foundation write through envelope, cookie actor, buckets, shared service and broadcast</name>
|
||||
<files>../sm-wavepath-app/plugins/golem15/wavepath/plugin.go, ../sm-wavepath-app/plugins/golem15/wavepath/routes.go, ../sm-wavepath-app/plugins/golem15/wavepath/buckets.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/response.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/actor.go, ../sm-wavepath-app/plugins/golem15/wavepath/updates/, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/foundation_smoke_test.go</files>
|
||||
<action>Per D-01, D-03, D-10, D-11 and D-21, select one recorded foundation write with a deterministic publication. Start with a failing TestFoundationTracer that sends the fixture's token cookie through app.Handler and compares response and broadcast sidecar. Implement typed PHP-compatible success/error envelopes, actor/path/body helpers, app-owned wave-api and presence-state buckets, reuse userfriends.JoinBucket, mount only the selected unchanged /_wave path, and call the shared service through a host serializer. Add only migration-backed companion data needed by the route. Mark only the tracer route ported; fix implementation rather than fixtures.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app vet ./plugins/golem15/wavepath/... ./parity/... && go -C ../sm-wavepath-app test -count=1 -run '^TestFoundationTracer$' -v ./parity 2>&1 | grep -q -- '^--- PASS: TestFoundationTracer'</automated>
|
||||
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
|
||||
</verify>
|
||||
<done>One real foundation write is green end to end with exact PHP envelope, persistence and publications.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Contexts, access resolvers, wave/presence authorizers and realtime routes</name>
|
||||
<files>../sm-wavepath-app/plugins/golem15/wavepath/chat.go, ../sm-wavepath-app/plugins/golem15/wavepath/realtime.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/context.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/channel_access.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/forum_access.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/authorizer.go, ../sm-wavepath-app/plugins/golem15/wavepath/README.md, ../sm-wavepath-app/parity/manifest.yaml</files>
|
||||
<action>Per D-03 and D-10, implement the host group context over userfriends membership and roles, use the existing friendgroup alias, and add only the channel alias. Install channel/forum resolvers inside lagoon.OnDatabase and deny on missing database or errors. Read lighthouse channel parsing before implementing strict wave:group:{id} and presence:wave:group:{id} authorizers; register wave once and match recorded info/capabilities. Mount token and subscribe routes with their recorded auth and cache behavior. Mark only the two realtime routes ported after all success and denial fixtures pass.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app test -count=1 -run 'TestParityCorpus/.+realtime' -v ./parity 2>&1 | grep -q -- '^--- PASS:'</automated>
|
||||
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
|
||||
</verify>
|
||||
<done>Foundation infrastructure and both realtime routes match the corpus and deny malformed or cross-group access.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-20 | Elevation of privilege | auth-group crossover on /_wave and realtime routes | high | mitigate | route groups use only jwt.auth for member routes; fixtures test guest/bot/invalid credentials; actor rejects backend/zero principals |
|
||||
| T-31-22 | Elevation of privilege | wave/presence channel authorization | high | mitigate | strict channel parser, runtime membership check, deny on DB/error/malformed input, exact success/denial subscribe fixtures |
|
||||
| T-31-23 | Denial of service | route and join/presence buckets | medium | mitigate | global bucket ownership checked, named buckets reused instead of duplicated, stacked limits and recorded 429 repeat cases |
|
||||
| T-31-25 | Spoofing | app host serializer diverges from shared service state | medium | mitigate | handlers derive state from services/models and strict fixture replay; typed structs prevent accidental generic API envelopes |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Foundation infrastructure: envelope, actor, buckets, contexts, resolvers, authorizers and realtime is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-06-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 07
|
||||
type: execute
|
||||
wave: 6
|
||||
depends_on: [31-06]
|
||||
files_modified:
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/plugin.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/routes.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/lifecycle.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/api/groups.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/api/members.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/api/invites.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/api/join.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/api/friends.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/updates/
|
||||
- ../sm-wavepath-app/parity/manifest.yaml
|
||||
- ../sm-wavepath-app/parity/parity_test.go
|
||||
- ../sm-wavepath-app/parity/broadcast_test.go
|
||||
- ../sm-wavepath-app/parity/foundation_smoke_test.go
|
||||
- ../sm-wavepath-app/scripts/check-parity.sh
|
||||
autonomous: true
|
||||
requirements: [SC-1, SC-2, SC-3, D-03, D-10, D-11, D-13, D-16]
|
||||
estimate:
|
||||
tokens: 190000
|
||||
raw_tokens: 190000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
|
||||
provides: "Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate"
|
||||
key_links:
|
||||
- from: "../sm-wavepath-app/plugins/golem15/wavepath/plugin.go"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Port groups, members, invites, join and friends against recorded cases</name>
|
||||
<files>../sm-wavepath-app/plugins/golem15/wavepath/routes.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/groups.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/members.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/invites.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/join.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/friends.go, ../sm-wavepath-app/plugins/golem15/wavepath/updates/, ../sm-wavepath-app/parity/manifest.yaml, ../sm-wavepath-app/parity/foundation_smoke_test.go</files>
|
||||
<action>Per D-03, D-11, D-13 and D-16, expand from the tracer one vertical family at a time: groups, members, invites/join, then friends. Use GroupService and FriendshipService for generic operations and app-side transactions for host-only fields without changing shared serializers. Define typed requests/responses from fixtures, preserve nil/empty/conditional keys, scope parent before nested ids, and reproduce recorded 401/403/404/422/429 behavior. Stack wave-api with community-join only where recorded. Mark each family ported only after all of its cases and broadcasts pass; finish with 34 non-realtime foundation routes ported.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app test -count=1 -run 'TestParityCorpus/.+(groups|members|invites|join|friends)' -v ./parity 2>&1 | tee /tmp/phase31-foundation.log && ! grep -q -- '^--- FAIL:' /tmp/phase31-foundation.log && grep -q -- '^--- PASS:' /tmp/phase31-foundation.log</automated>
|
||||
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
|
||||
</verify>
|
||||
<done>All group/member/invite/join/friend routes and their denial, validation, rate and publication cases pass.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Transactional group lifecycle and foundation-pending zero gate</name>
|
||||
<files>../sm-wavepath-app/plugins/golem15/wavepath/plugin.go, ../sm-wavepath-app/plugins/golem15/wavepath/lifecycle.go, ../sm-wavepath-app/plugins/golem15/wavepath/README.md, ../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/broadcast_test.go, ../sm-wavepath-app/parity/foundation_smoke_test.go, ../sm-wavepath-app/scripts/check-parity.sh</files>
|
||||
<action>Per D-03, listen for GroupCreated, MemberJoined/Left and GroupDeleted. Work on ev.Tx so failures roll back; create group chat/default channel once, avoid duplicate owner work, update memberships idempotently, and on delete end video and remove forum/host context in PHP order. Add lifecycle smoke coverage for rows, rollback and publications. Prove exactly foundation-routes.txt is ported and run the gate without allow flags; it must report recorded 196/196, ported 36, pending 160, foundation-pending 0.</action>
|
||||
<verify>
|
||||
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh 2>&1)" && printf '%s\n' "$OUT" | grep -qx 'check-parity: recorded 196/196 ported 36 pending 160 foundation-pending 0'</automated>
|
||||
<fails_when>Non-zero exit, a named test does not run, or the expected corpus count is absent.</fails_when>
|
||||
</verify>
|
||||
<done>Lifecycle is rollback-safe and the Phase 31 foundation gate closes at zero foundation pending while 160 later-phase routes remain pending.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-21 | Information disclosure | group/member/invite/friend IDOR | high | mitigate | parent-first scope checks, membership/role gate before nested lookup, recorded 403/404 collapse and cross-group denial cases |
|
||||
| T-31-24 | Tampering | partial group lifecycle | high | mitigate | listeners use ev.Tx and return errors; create/delete side effects and rollback behavior tested with broadcasts |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Foundation handlers and lifecycle green: groups, members, invites, join, friends and phase gate is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-07-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 08
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: [31-03]
|
||||
files_modified:
|
||||
- ../sm-oauthserver-plugin/testdata/parity/flows/
|
||||
- ../sm-oauthserver-plugin/testdata/parity/seed.json
|
||||
- ../sm-oauthserver-plugin/testdata/parity/winter-export.jsonl
|
||||
- ../sm-oauthserver-plugin/testdata/parity/id_token_shape.json
|
||||
- ../sm-oauthserver-plugin/testdata/parity/README.md
|
||||
autonomous: true
|
||||
requirements: [SC-3, D-08, D-20, TODO-OIDC]
|
||||
estimate:
|
||||
tokens: 80000
|
||||
raw_tokens: 80000
|
||||
tasks: 1
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Folded OIDC PHP parity recording in sm-oauthserver-plugin is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../sm-oauthserver-plugin/testdata/parity/flows/"
|
||||
provides: "Folded OIDC PHP parity recording in sm-oauthserver-plugin"
|
||||
key_links:
|
||||
- from: "../sm-oauthserver-plugin/testdata/parity/flows/"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Folded OIDC PHP parity recording in sm-oauthserver-plugin.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Record the ten PHP OIDC flows on the isolated oidc instance and make the existing parity harness mandatory-green</name>
|
||||
<precondition>31-02's stack supports `PARITY_INSTANCE=oidc`; the pinned oauthserver commit is present; `../sm-oauthserver-plugin/testdata/parity/README.md` lists the ten flows and the plugin's unrelated go.work change is left unstaged.</precondition>
|
||||
<files>../sm-oauthserver-plugin/testdata/parity/flows/, ../sm-oauthserver-plugin/testdata/parity/seed.json, ../sm-oauthserver-plugin/testdata/parity/winter-export.jsonl, ../sm-oauthserver-plugin/testdata/parity/id_token_shape.json, ../sm-oauthserver-plugin/testdata/parity/README.md</files>
|
||||
<read_first>../sm-oauthserver-plugin/testdata/parity/README.md (whole file), parity_test.go tests TestPHPParityReplay and TestIDTokenShapeParity, scripts/winter-export.sql, all ten existing request-only flows, 31-03-SUMMARY.md instance/port contract, ../sm-wavepath-app/parity/php_parity.sh and scripts/parity-stack.sh, pinned PHP oauthserver models and migrations through the parity export</read_first>
|
||||
<action>Per the folded OIDC todo, D-08 and D-20.
|
||||
1. Start `PARITY_INSTANCE=oidc` with its isolated database/export/ports. Seed one activated parity user and the `Parity RP` client (`https://rp.example.test/callback`, openid/profile/email, active, non-development, no prior consent), and mint the user's session token into `~/.config/summercms/parity-oauthserver.vars` with mode 0600. Add no committed secret.
|
||||
2. Record, in this exact order and stopping on first failure: discovery, jwks, authorize_errors, login_handoff, consent_allow, consent_silent, token_errors, userinfo_errors, consent_deny, authorizations. Invoke `summer parity:record --spec FLOW --output FLOW --target BASE --vars PRIVATE --update true`; do not pass `--rules`.
|
||||
3. Remove every Set-Cookie entry from recorded responses. Generate `seed.json`, `winter-export.jsonl` through the runbook's MariaDB export (hashes, not plaintext secrets), and `id_token_shape.json`. Reject a real hostname, token, client secret, authorization code or cookie in any committed file.
|
||||
4. Run the two mandatory parity tests. Resolve only observed documented differences through the existing deviation mechanism; do not broaden masks. Update the runbook with the automated `oidc` instance steps and exact green output.
|
||||
5. Commit only testdata paths: `test(oauthserver): record PHP OIDC parity against WavePath`.</action>
|
||||
<verify>
|
||||
<automated>PHASE194_REQUIRE_PARITY=1 go -C ../sm-oauthserver-plugin test -count=1 -run '^(TestPHPParityReplay|TestIDTokenShapeParity)$' -v ./... 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 2</automated>
|
||||
<fails_when>Non-zero exit or fewer than two PASS lines: a flow is absent/drifted, id-token shape differs, parity is still optional/skipped, or the filter matched nothing.</fails_when>
|
||||
<automated>test "$(stat -c %a ~/.config/summercms/parity-oauthserver.vars)" = 600 && ! rg -n 'Set-Cookie|eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.|client_secret"?\\s*:' ../sm-oauthserver-plugin/testdata/parity/flows ../sm-oauthserver-plugin/testdata/parity/seed.json ../sm-oauthserver-plugin/testdata/parity/winter-export.jsonl</automated>
|
||||
<fails_when>Non-zero exit: private vars permissions are wrong or a cookie/JWT/client secret appears in committed parity artifacts.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- All ten named flow files contain recorded responses and retain their request specs.
|
||||
- No flow contains Set-Cookie; export values are hashes only.
|
||||
- `git -C ../sm-oauthserver-plugin diff -- go.work` is exactly the pre-existing other-session diff and is not staged.
|
||||
- Both mandatory parity tests pass without a skip.
|
||||
</acceptance_criteria>
|
||||
<done>PHP OIDC behavior is a committed, secret-free reference corpus and the existing Go provider passes it under the mandatory parity flag.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-26 | Information disclosure | OIDC recorded flows/export | high | mitigate | private mode-0600 vars, Set-Cookie removal, hashes-only export, token/secret scan and mandatory parity tests |
|
||||
| T-31-27 | Tampering | OIDC masks hiding a real difference | medium | mitigate | fixed ordered runbook, no `--rules`, existing narrow deviations only and strict `PHASE194_REQUIRE_PARITY=1` |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Folded OIDC PHP parity recording in sm-oauthserver-plugin is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-08-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 09
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- ../vue-chat-layer/app/composables/useChat.ts
|
||||
- ../vue-chat-layer/tests/store.test.ts
|
||||
- ../vue-chat-layer/README.md
|
||||
autonomous: true
|
||||
requirements: [SC-4, D-22, TODO-SLASH]
|
||||
estimate:
|
||||
tokens: 60000
|
||||
raw_tokens: 60000
|
||||
tasks: 1
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Folded vue-chat-layer slash-command parity fix is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../vue-chat-layer/app/composables/useChat.ts"
|
||||
provides: "Folded vue-chat-layer slash-command parity fix"
|
||||
key_links:
|
||||
- from: "../vue-chat-layer/app/composables/useChat.ts"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Folded vue-chat-layer slash-command parity fix.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Match WavePath slash behavior: known dispatch, local unknown refusal with draft retained, and // text escape</name>
|
||||
<files>../vue-chat-layer/app/composables/useChat.ts, ../vue-chat-layer/tests/store.test.ts, ../vue-chat-layer/README.md</files>
|
||||
<read_first>31-CONTEXT.md D-22, 31-RESEARCH.md "Slash text that names no command", ../vue-chat-layer/app/composables/useChat.ts send/runCommand/loadCommands and command state, ../vue-chat-layer/tests/store.test.ts existing slash cases and fake API, /media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/stores/channelChatStore.ts slash branch and MessageComposer handling (read-only)</read_first>
|
||||
<behavior>
|
||||
- Known `/demo arg` with catalog trigger `demo` calls dispatch once, does not call message send and clears the draft on success.
|
||||
- Unknown `/nope arg` with a loaded non-empty catalog calls neither dispatch nor message send, adds the local unknown-command hint and keeps the exact draft.
|
||||
- `//r/golang is great` calls ordinary message send with `/r/golang is great`, never dispatches, and clears the draft only on send success.
|
||||
- Bare `/` follows ordinary send; when the loaded catalog is empty, slash text follows WavePath's ordinary-send branch; while catalog is null, load it before deciding and do not race a send against the lookup.
|
||||
</behavior>
|
||||
<action>Per D-22.
|
||||
1. Red first: replace the old server-422 unknown-command expectation with the behavior block. Assert exact draft, dispatch/send call counts, arguments and ephemeral hint. Add the `//`, bare slash, empty catalog and null/loading cases.
|
||||
2. In `send`, handle `//` before command dispatch: remove exactly one leading slash and pass the remainder through the normal text-send path. Do not mutate the draft until that send succeeds.
|
||||
3. For one-leading-slash content with a non-empty trigger token, ensure the catalog is loaded. Compare the first token after `/` case-normalized in the same manner as existing command triggers. A known trigger calls `runCommand`; an unknown trigger pushes the existing local error row/hint, returns false and leaves `d.text` untouched. A bare `/` is not a trigger.
|
||||
4. Preserve the WavePath empty-catalog behavior documented in D-22/research: on a surface whose loaded catalog is empty, slash text uses ordinary message send. Do not silently post unknown slash text when a catalog exists.
|
||||
5. Update the layer README's command behavior and `//` escape. Commit: `fix(chat-layer): match WavePath slash command handling`.</action>
|
||||
<verify>
|
||||
<automated>pnpm --dir ../vue-chat-layer test -- --run 2>&1 | tee "${TMPDIR:-/tmp}/vue-chat-layer-test.log" && ! grep -qE '(^|[^0-9])([1-9][0-9]*) failed' "${TMPDIR:-/tmp}/vue-chat-layer-test.log"</automated>
|
||||
<fails_when>Non-zero exit or failed-test count: known/unknown/escape behavior differs, draft handling regressed, or another layer test failed.</fails_when>
|
||||
<automated>pnpm --dir ../vue-chat-layer run build:playground</automated>
|
||||
<fails_when>Non-zero exit: the composable's changed types or runtime imports do not build in the layer playground.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- Unknown `/nope` with a loaded catalog invokes neither API dispatch nor message send and preserves the draft.
|
||||
- `//text` sends `/text` through the ordinary path.
|
||||
- No backend or shared Go plugin changes for slash handling.
|
||||
- README describes all four branches: known, unknown, escape, bare/empty catalog.
|
||||
</acceptance_criteria>
|
||||
<done>A user can deliberately post slash-prefixed text with //, while accidental unknown commands are refused locally exactly as WavePath specifies.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-28 | Elevation of privilege | slash text dispatched as an unintended command | medium | mitigate | loaded-catalog first-token match; unknown triggers never call dispatch; explicit tests for dispatch/send call counts |
|
||||
| T-31-29 | Tampering | `//` escape altering more than one slash | low | accept | deterministic one-character removal is directly covered; remaining risk is cosmetic user input, not authorization |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Folded vue-chat-layer slash-command parity fix is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-09-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 10
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- ../sm-chat-plugin/events/events.go
|
||||
- ../sm-chat-plugin/classes/service.go
|
||||
- ../sm-chat-plugin/README.md
|
||||
- ../sm-userfriends-plugin/events/events.go
|
||||
- ../sm-userfriends-plugin/contracts/rejection.go
|
||||
- ../sm-userfriends-plugin/classes/group_service.go
|
||||
- ../sm-userfriends-plugin/api/errors.go
|
||||
- ../sm-userfriends-plugin/README.md
|
||||
- ../sm-user-plugin/classes/events.go
|
||||
- ../sm-user-plugin/contracts/rejection.go
|
||||
- ../sm-user-plugin/controllers/
|
||||
- ../sm-user-plugin/README.md
|
||||
- ../sm-demo-app/plugins/demo/moderation.go
|
||||
- ../sm-demo-app/plugins/demo/plugin.go
|
||||
autonomous: true
|
||||
requirements: [SC-3, D-14, TODO-MODERATION]
|
||||
estimate:
|
||||
tokens: 150000
|
||||
raw_tokens: 150000
|
||||
tasks: 1
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "Folded additive moderation seams for users, friend groups and attachment filenames is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
artifacts:
|
||||
- path: "../sm-chat-plugin/events/events.go"
|
||||
provides: "Folded additive moderation seams for users, friend groups and attachment filenames"
|
||||
key_links:
|
||||
- from: "../sm-chat-plugin/events/events.go"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Folded additive moderation seams for users, friend groups and attachment filenames.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Add additive user/group/filename saving seams and moderate them in the demo without changing listener-free behavior</name>
|
||||
<files>../sm-chat-plugin/events/events.go, ../sm-chat-plugin/classes/service.go, ../sm-chat-plugin/saving_test.go, ../sm-chat-plugin/README.md, ../sm-userfriends-plugin/events/events.go, ../sm-userfriends-plugin/contracts/rejection.go, ../sm-userfriends-plugin/classes/group_service.go, ../sm-userfriends-plugin/api/errors.go, ../sm-userfriends-plugin/saving_test.go, ../sm-userfriends-plugin/README.md, ../sm-user-plugin/classes/events.go, ../sm-user-plugin/contracts/rejection.go, ../sm-user-plugin/controllers/registration.go, ../sm-user-plugin/controllers/api_controller.go, ../sm-user-plugin/controllers/users_admin_controller.go, ../sm-user-plugin/saving_test.go, ../sm-user-plugin/README.md, ../sm-demo-app/plugins/demo/moderation.go, ../sm-demo-app/plugins/demo/plugin.go, ../sm-demo-app/moderation_test.go, ../sm-demo-app/go.mod, ../sm-demo-app/go.sum, ../sm-demo-app/plugins/golem15/chat, ../sm-demo-app/plugins/golem15/user, ../sm-demo-app/plugins/golem15/userfriends, ../sm-bm-app/plugins/golem15/chat</files>
|
||||
<read_first>31-PATTERNS.md "Folded todo: saving seams", ../sm-chat-plugin/events/events.go, classes/service.go attachment claim flow, classes/writes.go edit fire, contracts/rejection.go, api/errors.go, saving_test.go; ../sm-forum-plugin/events/events.go and classes/forum_service.go saving event; ../sm-userfriends-plugin/events/events.go, classes/group_service.go create/update/fire, api/errors.go; ../sm-user-plugin/classes/events.go, controllers registration/api/admin write paths and validation writers; ../sm-demo-app/plugins/demo/moderation.go, plugin.go and moderation_test.go; module READMEs</read_first>
|
||||
<behavior>
|
||||
- Chat: MessageSaving on create carries the filenames of attachment ids being claimed; no attachments yields an empty slice; rejection field `attachments` returns 422 and stores neither message nor claims; no listener preserves current response and storage.
|
||||
- Userfriends: GroupSaving fires for create and update after access/required checks but before transaction/write, with op, actor, group id, name and description; Rejection maps to a 422 field; no listener preserves current behavior.
|
||||
- User: Saving fires before frontend registration/profile update and backend-admin create/update with operation, actor where known, user id, name and surname; Rejection maps to each path's existing 422 field; no listener preserves current behavior.
|
||||
- Demo: banned content in profile name/surname, group name/description or any claimed attachment filename produces the owning API's 422 and leaves storage unchanged.
|
||||
</behavior>
|
||||
<action>Per the moderation folded todo and D-14.
|
||||
1. Red first in each plugin: table-driven smoke cases from the behavior block, including no-listener compatibility, owning Rejection, plain listener error (500/rollback), event ordering and no post-save event after refusal.
|
||||
2. Chat: add `AttachmentFilenames []string` (or the final neutral plural name) to `MessageSaving`. In `SendMessageWith`, resolve pending attachment rows owned by the actor and collect basename/original names after validation but before firing; do not claim them yet. Existing listeners see the zero value. Edit events carry no attachment names.
|
||||
3. Userfriends: add operation constants and `GroupSaving` in `events`, plus value `contracts.Rejection`. Extend the service fire type switch; fire create/update after permission and required checks and before transaction/write. Map Rejection in `api/errors.go`, defaulting an empty field to `name`.
|
||||
4. User: add `SavingEvent`, operation constants, `FireSavingEvent`, and value Rejection. Fire from frontend registration, profile update and backend-admin create/update after request validation and authorization but before persistence. Include proposed name/surname values, not mutable model pointers. Map a rejection through each handler's existing validation writer.
|
||||
5. Update all three READMEs in their API-reference/event sections. These are additive exported APIs; no behavior changes without a listener.
|
||||
6. Demo: register listeners only when each plugin is active. Filter profile fields and group fields with `Filter.Check`; filter each filename and reject field `attachments` on the first refusal. Update plugin/package comments and extend `moderation_test.go` over real HTTP paths with unchanged row counts.
|
||||
7. Commit plugin changes independently. Point bm/demo submodules locally at candidate commits. Run bm and demo gates before any requested tag. If the user has separately authorized release, push/tag each plugin, post its changelog, then commit consumer pointers separately; otherwise stop at clean local commits and record release-ready hashes.</action>
|
||||
<verify>
|
||||
<automated>for r in sm-chat-plugin sm-userfriends-plugin sm-user-plugin; do go -C ../$r vet ./... && go -C ../$r test -count=1 -short ./... || exit 1; done && go -C ../sm-chat-plugin test -count=1 -run '^TestMessageSaving' -v . 2>&1 | grep -q -- '^--- PASS:' && go -C ../sm-userfriends-plugin test -count=1 -run '^TestGroupSaving' -v . 2>&1 | grep -q -- '^--- PASS:' && go -C ../sm-user-plugin test -count=1 -run '^TestSaving' -v . 2>&1 | grep -q -- '^--- PASS:'</automated>
|
||||
<fails_when>Non-zero exit or a PASS line absent: a plugin does not vet/test, listener-free behavior changed, a rejection writes data, or a named saving test did not run.</fails_when>
|
||||
<automated>go -C ../sm-demo-app vet . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -run '^TestDemoModeration' -v . 2>&1 | grep -q -- '^--- PASS: TestDemoModeration' && go -C ../sm-bm-app build ./... && go -C ../sm-bm-app test -count=1 -run '^(TestChatMounted|TestRealtimeDefaultDriver|TestRealtimeRoutes|TestRealtimeConfigDefaults|TestRemoteKeyOverride)$' -v . 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 5</automated>
|
||||
<fails_when>Non-zero exit, demo moderation PASS absent, or bm prints fewer than five PASS lines: the listeners do not reject through HTTP, a consumer fails at candidate commits, or required bm tests did not run.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- Each plugin has a no-listener compatibility assertion and a refusal-no-write assertion.
|
||||
- Existing MessageSaving listeners compile unchanged.
|
||||
- User saving covers frontend and backend-admin writes; group saving covers create/update; filename saving covers claims on message create.
|
||||
- READMEs name only exported identifiers that exist.
|
||||
- No tag/push/changelog occurs without explicit authorization.
|
||||
</acceptance_criteria>
|
||||
<done>Hosts can moderate all requested names and filenames through additive pre-save events, and the demo proves refusals while unlistened plugins remain compatible.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-30 | Tampering | moderation event fires after persistence | high | mitigate | fire after checks and before transaction/write; refusal and plain-error tests assert unchanged row/claim counts |
|
||||
| T-31-31 | Denial of service | listener recursion or mutable event payload | medium | mitigate | immutable proposed scalar fields/slices, one pre-save fire per operation, no model save from the framework seam |
|
||||
| T-31-32 | Spoofing | consumer gate tests wrong plugin revision | high | mitigate | local submodule pointers are set to exact candidate commits before bm/demo build/tests; release hashes recorded |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Folded additive moderation seams for users, friend groups and attachment filenames is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-10-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
phase: 31-chat-polish-against-wavepath-clients
|
||||
plan: 11
|
||||
type: execute
|
||||
wave: 7
|
||||
depends_on: [31-01, 31-02, 31-04, 31-05, 31-07, 31-08, 31-09, 31-10]
|
||||
files_modified:
|
||||
- modules/tide/
|
||||
- cmd/summer/parity_test.go
|
||||
- ../sm-wavepath-app/plugins/golem15/wavepath/
|
||||
- ../sm-wavepath-app/parity/
|
||||
- ../sm-wavepath-app/scripts/check-parity.sh
|
||||
- ../sm-chat-plugin/saving_test.go
|
||||
- ../sm-userfriends-plugin/saving_test.go
|
||||
- ../sm-user-plugin/saving_test.go
|
||||
- ../sm-demo-app/moderation_test.go
|
||||
- ../vue-chat-layer/tests/store.test.ts
|
||||
autonomous: true
|
||||
requirements: [SC-1, SC-2, SC-3, SC-4, D-01, D-03, D-06, D-09, D-10, D-11, D-13, D-14, D-16, D-22]
|
||||
estimate:
|
||||
tokens: 260000
|
||||
raw_tokens: 260000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
scope_exception: "This closing unit-and-gate plan intentionally groups test matrices across the phase; splitting it would violate the project rule that the last plan owns unit coverage and the closing gate."
|
||||
must_haves:
|
||||
truths:
|
||||
- "Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices is delivered against the frozen PHP corpus and locked decisions."
|
||||
- "Verification fails closed: missing, skipped, pending or mismatching evidence is not counted as a pass."
|
||||
- "D-16 remains intact: messaging, satellites, Range support, guest/bot/webhook host services, zero total pending and final security review stay in Phases 31.1/31.2."
|
||||
- "The final gate reports recorded 196/196, ported 36, pending 160 and foundation-pending 0."
|
||||
artifacts:
|
||||
- path: "modules/tide/"
|
||||
provides: "Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices"
|
||||
key_links:
|
||||
- from: "modules/tide/"
|
||||
to: "the plan's automated verification"
|
||||
via: "the named tracer and fail-closed checks"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
WavePath's complete 196-route PHP community corpus is recorded and self-replays green; Phase 31 ports and proves only the 36-route foundation slice, leaving exactly 160 routes pending for Phases 31.1 and 31.2 per D-16.
|
||||
|
||||
<objective>
|
||||
Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices.
|
||||
|
||||
Purpose: preserve the frozen client/PHP contract while keeping this executor slice cohesive and within the authorized hybrid re-slice.
|
||||
Output: the artifacts and machine evidence named below.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md
|
||||
@.planning/phases/31-chat-polish-against-wavepath-clients/31-VALIDATION.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer test: mutate one foundation case at each side-effect boundary and prove replay and the gate fail closed</name>
|
||||
<precondition>31-04's gate summary is `recorded 196/196 ported 36 pending 160 foundation-pending 0` and 31-05's repo suites are green.</precondition>
|
||||
<files>../sm-wavepath-app/parity/parity_test.go, ../sm-wavepath-app/parity/broadcast_test.go, ../sm-wavepath-app/parity/upstream_replay_test.go, ../sm-wavepath-app/parity/gate_test.go, ../sm-wavepath-app/scripts/check-parity.sh</files>
|
||||
<read_first>31-05-SUMMARY.md fixture/sidecar counts, 31-07-SUMMARY.md tracer route and gate output, parity_test.go, broadcast_test.go, upstream_replay_test.go, scripts/check-parity.sh, ../fonoteka.go/parity/parity_test.go negative subtests, scripts/check-phase19.1.sh self-test detector pattern</read_first>
|
||||
<action>Per D-10, D-11, D-13 and D-16.
|
||||
1. Add `TestFoundationParityFailClosed` using a temp copy of the tracer fixture and sidecars. Table cases: response status/body mutation, removed broadcast, extra broadcast, changed broadcast body, removed expected upstream call, extra upstream sidecar/call, route set back to pending, missing seed hook and a planted accepted-difference without sign-off. Each mutation must produce a non-empty error naming route and case; the untouched control passes.
|
||||
2. Add `TestGateFailClosed` around extracted/testable detector functions or `scripts/check-parity.sh --self-test`: planted go-test JSON for fail, skip, zero tests and missing required name; checker output with unrecorded case, foundation pending, wrong counts/reference, secret residue; consumer command failure. Each is refused.
|
||||
3. Keep the real gate script's behavior unchanged except for factoring detector helpers and adding checks that mutation tests expose. No allow flag in its normal path.
|
||||
4. Commit: `test(parity): prove foundation replay and gate fail closed`.</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-wavepath-app test -count=1 -run '^(TestFoundationParityFailClosed|TestGateFailClosed)$' -v ./parity 2>&1 | grep -c -- '^--- PASS: Test' | grep -qx 2</automated>
|
||||
<fails_when>Non-zero exit or fewer than two PASS lines: an altered response/sidecar/manifest/gate signal was accepted, the untouched control failed, or a named test did not run.</fails_when>
|
||||
<automated>../sm-wavepath-app/scripts/check-parity.sh --self-test 2>&1 | grep -q 'self-test: ok'</automated>
|
||||
<fails_when>Non-zero exit or marker absent: at least one planted false-green condition is not rejected by the executable gate.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- Every table mutation fails for the intended reason and names the route/case or gate stage.
|
||||
- Committed fixtures and sidecars remain byte-identical; all mutation happens in a temp directory.
|
||||
- The untouched control traverses response, broadcast and upstream checks and passes.
|
||||
</acceptance_criteria>
|
||||
<done>A single end-to-end foundation case proves that no missing or altered observable can produce a green parity or gate verdict.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Complete table-driven tide, foundation handler, resolver, authorizer, lifecycle and corpus-checker coverage</name>
|
||||
<files>modules/tide/normalize_test.go, modules/tide/centrifugo_test.go, modules/tide/centrifugo_golden_test.go, modules/tide/manifest_test.go, modules/tide/upstream_test.go, modules/tide/variables_test.go, modules/tide/headers_test.go, modules/tide/rules_test.go, modules/tide/fixture_test.go, cmd/summer/parity_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/response_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/groups_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/members_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/invites_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/api/friends_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/context_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/classes/authorizer_test.go, ../sm-wavepath-app/plugins/golem15/wavepath/lifecycle_test.go, ../sm-wavepath-app/parity/check_corpus_test.go</files>
|
||||
<read_first>31-01-SUMMARY.md and 31-02-SUMMARY.md final tide APIs, every tide smoke test and adjacent existing unit tests, cmd/summer/parity_test.go, 31-06-SUMMARY.md and 31-07-SUMMARY.md final handler/type/route names, app-plugin production files, all foundation recorded denial/validation fixtures, parity/check_corpus.go and fonoteka's checker tests</read_first>
|
||||
<behavior>
|
||||
- Tide T-1..T-10 and Reference: valid, malformed, disabled/absent/default, strict YAML round-trip and old-format compatibility cases.
|
||||
- Tide security: undeclared credentials/cookies refused; wrong JWT scheme/claims rejected; body comparer scoped by host/content type; case hook has no shell interpolation; listeners require loopback; repeat bound enforced.
|
||||
- Foundation handlers: each family has success, malformed JSON, missing actor, role denial, missing/cross-group nested id, validation rejection, nil service/database and unexpected error; exact status, envelope and row-count effects.
|
||||
- Authorizers/resolvers: malformed channel/context, zero user, absent/error DB, non-member/member/role cases and exact allowed info/capabilities.
|
||||
- Lifecycle: create is idempotent, owner MemberJoined does not duplicate default channel, member leave/join behavior, delete cleanup, child failure rolls back all changes.
|
||||
- Corpus checker: route/snapshot/auth mismatch, missing fixture, wrong ported status, missing/orphan broadcast/upstream, every secret pattern, wrong reference commit, missing D-19 provenance and wrong foundation set.
|
||||
</behavior>
|
||||
<action>Per SC-4.
|
||||
1. Replace or extend the 31-01 smoke coverage with table-driven tests in the canonical tide test files. Cover all final exported options and strict loaders/writers; load representative pre-Phase-31 fixtures/manifests/sidecars to prove backward compatibility.
|
||||
2. Add CLI tests that parse the final record/replay flags, reject their use outside manifest mode, reject non-loopback listeners and non-executable case hooks, and prove hook ids are environment data rather than shell input.
|
||||
3. Add app-plugin unit matrices with injected services/checks and `httptest`. Use real fixture snippets for exact envelope/key/null behavior, but keep database integration in the existing parity tests.
|
||||
4. Add resolver/authorizer pure tables and lifecycle transaction tests over testcontainers or the app's test DB. Assert rows and event/publication calls before and after rollback.
|
||||
5. Extend `check_corpus_test.go` with temp manifests/sidecars for every behavior row. Include all secret forms: JWT, wave token, cookie, invite/webhook/call-link code and minted vendor credential.
|
||||
6. Commit framework tests separately from app tests: `test(tide): cover Phase 31 recording additions`; `test(wavepath): cover foundation handlers and access`; `test(parity): cover corpus checker failures`.</action>
|
||||
<verify>
|
||||
<automated>go vet ./modules/tide/ ./cmd/summer/ && go test -count=1 -short ./modules/tide/ ./cmd/summer/ && go test -count=1 -run '^(TestRelative|TestManifest|TestUpstream|TestCookie|TestExtraHeaders|TestClient|TestRepeat|TestCentrifugo)' -v ./modules/tide/ 2>&1 | tee "${TMPDIR:-/tmp}/tide-unit.log" && grep -q -- '^--- PASS:' "${TMPDIR:-/tmp}/tide-unit.log" && ! grep -q -- '^--- FAIL:' "${TMPDIR:-/tmp}/tide-unit.log"</automated>
|
||||
<fails_when>Non-zero exit, no PASS line or any FAIL line: tide/cmd tests do not compile, a compatibility/security/edge table fails, or the filter matched nothing.</fails_when>
|
||||
<automated>go -C ../sm-wavepath-app vet ./plugins/golem15/wavepath/... ./parity/... && go -C ../sm-wavepath-app test -count=1 -run '^(Test(Response|Groups|Members|Invites|Friends|Context|Authorize|Lifecycle|CheckCorpus))' -v ./plugins/golem15/wavepath/... ./parity 2>&1 | tee "${TMPDIR:-/tmp}/wavepath-unit.log" && grep -q -- '^--- PASS:' "${TMPDIR:-/tmp}/wavepath-unit.log" && ! grep -q -- '^--- FAIL:' "${TMPDIR:-/tmp}/wavepath-unit.log"</automated>
|
||||
<fails_when>Non-zero exit, no PASS line or any FAIL line: handler/access/lifecycle/checker unit matrices fail, Docker-backed lifecycle setup fails, or named tests did not run.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- Every behavior bullet has at least one named table row and failure output names the row.
|
||||
- Old tide fixture/manifest/upstream files from before Phase 31 load unchanged.
|
||||
- Every high threat T-31-01..T-31-32 that belongs to tide/foundation/checkers has a direct regression test or gate mutation.
|
||||
- Production changes, if any bug is found, are minimal and listed in the summary.
|
||||
</acceptance_criteria>
|
||||
<done>The generic recording toolkit, foundation app plugin and parity checkers have deterministic positive, edge, compatibility and fail-closed unit coverage.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Run folded-todo regressions, full foundation gate, consumer suites and framework docs checks</name>
|
||||
<files>../sm-chat-plugin/saving_test.go, ../sm-userfriends-plugin/saving_test.go, ../sm-user-plugin/saving_test.go, ../sm-demo-app/moderation_test.go, ../vue-chat-layer/tests/store.test.ts, ../sm-wavepath-app/scripts/check-parity.sh</files>
|
||||
<read_first>31-08-SUMMARY.md, 31-09-SUMMARY.md and 31-10-SUMMARY.md final flow/event/field names and commits, saving tests in all three plugins, demo moderation tests, layer slash tests, 31-VALIDATION.md, project CLAUDE.md commands, scripts/check-parity.sh required test list</read_first>
|
||||
<action>Per SC-3, SC-4, D-14 and D-22.
|
||||
1. Expand the three saving test files into tables for every fire path, operation, field default, listener-free control, owning Rejection, plain error and no-write/no-post-event behavior. Expand demo moderation to each requested field and filename position.
|
||||
2. Keep the slash test matrix explicit for known, unknown, `//`, bare `/`, empty loaded catalog and null/loading catalog; run the full layer suite and playground build.
|
||||
3. Run each touched plugin's full short suite, demo's root/plugin suite and bm's build/required tests at the exact candidate commits recorded in 31-05.
|
||||
4. Run `scripts/check-parity.sh` with no allow flags. It must execute corpus completeness, strict ported replay, broadcasts, upstream, foundation, consumers and self-tests and print exactly `recorded 196/196 ported 36 pending 160 foundation-pending 0`.
|
||||
5. Run framework vet/short tests and both docs checks. Confirm the framework diff contains no consuming-application name and module docs match final tide identifiers/flags.
|
||||
6. Update `31-VALIDATION.md` status through the validation workflow when execution reaches its sign-off; do not raw-edit STATE.md. Post the Phase 31 g15office progress comment through the configured integration.
|
||||
7. Commit test-only expansions per repository. Planning/code commits remain separate.</action>
|
||||
<verify>
|
||||
<automated>for r in sm-chat-plugin sm-userfriends-plugin sm-user-plugin; do go -C ../$r vet ./... && go -C ../$r test -count=1 -short ./... || exit 1; done && go -C ../sm-demo-app vet . ./plugins/demo/... && go -C ../sm-demo-app test -count=1 -short . ./plugins/demo/... && go -C ../sm-bm-app build ./... && go -C ../sm-bm-app test -count=1 -run '^(TestChatMounted|TestRealtimeDefaultDriver|TestRealtimeRoutes|TestRealtimeConfigDefaults|TestRemoteKeyOverride)$' .</automated>
|
||||
<fails_when>Non-zero exit: a saving seam, demo listener or existing consumer behavior fails at the candidate commits, or a required bm test fails.</fails_when>
|
||||
<automated>pnpm --dir ../vue-chat-layer test -- --run && pnpm --dir ../vue-chat-layer run build:playground</automated>
|
||||
<fails_when>Non-zero exit: any slash regression or existing layer test fails, or the playground does not build.</fails_when>
|
||||
<automated>OUT="$(../sm-wavepath-app/scripts/check-parity.sh 2>&1)" && printf '%s\n' "$OUT" | grep -qx 'check-parity: recorded 196/196 ported 36 pending 160 foundation-pending 0'</automated>
|
||||
<fails_when>Non-zero exit or exact summary absent: a corpus/golden/upstream/foundation/consumer/self-test stage failed, a required test skipped, Docker was unavailable, or an allow flag was needed.</fails_when>
|
||||
<automated>go vet ./... && go test -count=1 -short ./... && go run ./cmd/summer docs:build --check 2>&1 | grep -q 'no problems found' && go test -count=1 -run '^TestDocsTree$' -v ./cmd/summer 2>&1 | grep -q -- '^--- PASS: TestDocsTree'</automated>
|
||||
<fails_when>Non-zero exit: framework vet/short tests fail, docs drift or name an absent identifier/command, or TestDocsTree did not run and pass.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- All folded-todo regression tables pass, including no-listener controls.
|
||||
- Full gate uses no allow flag and prints the exact 196/36/160/0 counts.
|
||||
- Framework docs build/check and TestDocsTree pass; no consuming app name was added to framework source/docs/tests.
|
||||
- Each touched repository is clean for files owned by this phase; unrelated changes remain unstaged.
|
||||
</acceptance_criteria>
|
||||
<done>Phase 31's unit suites, consumers, foundation gate and documentation checks are green, with remaining 160 routes explicitly pending for Phases 31.1 and 31.2.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| recorded PHP/client contract to committed artifacts | live identities, responses and side effects become replay expectations |
|
||||
| untrusted request to Go/plugin behavior | authentication, authorization, validation and rate limits must match safely |
|
||||
| automated evidence to completion verdict | missing or skipped work must not look green |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-31-33 | Spoofing | gate passes on zero, skipped or missing tests | high | mitigate | planted go-test JSON detector matrix, exact required test names and PASS/count checks |
|
||||
| T-31-34 | Tampering | negative tests modify committed corpus | high | mitigate | copy fixture/manifest/sidecar trees to t.TempDir; clean-tree and hash checks after mutation suite |
|
||||
| T-31-35 | Repudiation | untested threat mitigations | medium | mitigate | map high threats to named unit/gate cases and record command evidence in summary |
|
||||
| T-31-36 | Spoofing | consumer tests resolve wrong plugin commit | high | mitigate | assert submodule HEAD equals 31-05 candidate hash before bm/demo tests |
|
||||
| T-31-37 | Denial of service | Docker failure represented as skip | medium | mitigate | TestMain skips only under testing.Short; full gate treats unavailable Docker and skipped required names as failure |
|
||||
| T-31-SC | Tampering | npm/pip/cargo installs | high | mitigate | no package install; use existing dependencies and explicit lockfiles |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run every task's automated command and preserve its fails_when semantics. Do not use Phase 31.1/31.2 work to make this plan green.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
Unit tests last: tide, app foundation, parity/gate and folded-todo regression matrices is complete, its named tests ran, and no locked decision or D-16 phase boundary drifted.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/31-chat-polish-against-wavepath-clients/31-11-SUMMARY.md` with commits, final identifiers, verification evidence, deviations, and remaining D-16 pending work.
|
||||
</output>
|
||||
@@ -0,0 +1,188 @@
|
||||
# Phase 31: Chat polish against WavePath clients - Context
|
||||
|
||||
**Gathered:** 2026-11-13
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
WavePath's community traffic is recorded from the PHP backend with `tide`, replayed against Go, and Go is fixed until the replay is green. "Community traffic" is wider than the roadmap entry's wording (D-09): every route under `/_wave/api/v1/community`, the guest routes, the push routes and the bot and token routes, about 190 routes, plus every realtime publication those routes cause.
|
||||
|
||||
The replay target is a new application repo, `sm-wavepath-app`, which mounts the seven shared chat plugins and serves the recorded `/_wave` paths from an in-repo `wavepath` app plugin. That plugin ports only what the recorded routes exercise. It is the start of WavePath's Go app, not the whole app port.
|
||||
|
||||
Out of scope:
|
||||
- The rest of WavePath's backend (diary, practices, trainings, stats, auth, journal, payments, admin screens). They come with the later WavePath phases.
|
||||
- The MariaDB to Postgres import, the production cutover and the pre-freeze re-record (D-06).
|
||||
- `electron-wavepath` and `tauri-wavepath-desktop` as separate recording clients. The roadmap names three clients: `vue-wavepath-app`, `wavepath-mcp` and `hubot-wavepath`.
|
||||
- Any commit in the `wavepath.org` repo (D-08).
|
||||
|
||||
**Repos touched:**
|
||||
- `sm-wavepath-app` (new): app skeleton, `wavepath` app plugin, `parity/` corpus, seeders, recording scripts, the gate script.
|
||||
- The seven shared plugin repos, for parity fixes and re-freeze deltas: `sm-chat-plugin`, `sm-chatchannels-plugin`, `sm-chatbots-plugin`, `sm-chatvideo-plugin`, `sm-forum-plugin`, `sm-herald-plugin`, `sm-userfriends-plugin`.
|
||||
- `sm-user-plugin`, only additively and only if a recorded route needs it.
|
||||
- `summercms.go`, only for `tide` or `lighthouse` gaps.
|
||||
- `sm-demo-app`, `sm-bm-app` and the vue layers (`vue-chat-layer`, `vue-chatvideo-layer`, `vue-forum-layer`, `vue-userfriends-layer`), to follow shared-plugin changes (D-15) and for the folded todos.
|
||||
- `sm-oauthserver-plugin`, for the folded OIDC parity recording.
|
||||
|
||||
**Roadmap corrections** (make them in the first planning commit):
|
||||
- "Depends on": remove Phase 30. Keep Phase 19 and Phase 19.1 (D-05).
|
||||
- "Repos": replace with the list above.
|
||||
- Success criterion 1: the corpus is the community surface defined in D-09, not only "chat, channel, thread, video-room and push routes".
|
||||
- Success criterion 2: every publication of every writing step, on any namespace (D-10).
|
||||
- Success criterion 3: name the gate from D-15. `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Replay target and paths
|
||||
- **D-01:** **Recorded `/_wave` requests replay unchanged against `/_wave` routes served by Go.** A Go app mounts the seven plugins and an in-repo `wavepath` app plugin registers the recorded paths as aliases over the plugin services. `tide` gets no path-rewrite feature, and the plugin test hosts get no `/_wave` aliases. This is the "thin aliases" route that P19 D-07 and P19.1 D-05 left open for the WavePath port.
|
||||
- **D-02:** **The app is a new sibling repo, `sm-wavepath-app`,** laid out like `fonoteka.go`: `summer.yaml`, shared plugins as git submodules at `plugins/golem15/<name>`, the app plugin in-repo, `parity/` with the manifest, fixtures, capture rules and broadcast goldens, a `replace` of the framework to `../summercms.go` during development. WavePath's own agent later grows the same repo for the rest of the app port. — **Reversibility:** costly — the repo name, module path and `parity/` layout are what WavePath's agent and every later WavePath phase build on.
|
||||
- **D-03:** **The app plugin ports whatever the recorded routes need, not only aliases.** That includes the controller logic of WavePath's community controllers and the host seams: the channel and forum access resolvers, the bot auth resolver, the herald profile and presence gate, the notification dispatch, the group context adapter and the group lifecycle wiring (a created group spawns its chat and channels, a deleted group ends video and removes the forum context). Routes outside the corpus stay unported.
|
||||
- **D-04:** **One named scenario, seeded on both sides.** The scenario (users in each role, groups, channels, conversations, an existing thread, pins, a call link, forum content, friendships, a bot, a guest) is defined once. A PHP reset script seeds it into the local WavePath database, and a Go fixture plugin in `sm-wavepath-app` seeds the same rows into Postgres, as `fonoteka.go/parity` does with `fonoteka_reset.php` and `fixtureplugin`. `summer import:winter` is not used here.
|
||||
|
||||
### Recording source and timing
|
||||
- **D-05:** **Phase 31 does not depend on Phase 30.** The user: "phase 30 was meant for plytarium cutover, wavepath is totally separate project". The roadmap dependency was sequencing only.
|
||||
- **D-06:** **Record now, re-record before the WavePath freeze.** The corpus is recorded from today's PHP and Go is fixed against it. Shortly before the WavePath cutover the whole corpus is re-recorded with a drift report and each drift is resolved (the Phase 30 D-12 pattern). That re-record belongs to the WavePath cutover phase. Phase 31 must leave it runnable unattended.
|
||||
- **D-07:** **Proxy once, then scripted specs.** The three real clients run through `summer parity:proxy` once to learn the exact requests, headers and bodies they send. Those sessions become committed spec flows that `summer parity:record` re-runs without a person.
|
||||
- **D-08:** **The PHP backend is the local checkout at `/media/nvme/dev/jz/wavepath.org`,** brought up by a script this phase delivers: the PHP server, its database with the D-04 scenario, Centrifugo pointed at the `tide` recorder, and LiveKit and the push service answered by the `tide` upstream proxy. Nothing is committed in `wavepath.org`. The reset script and the env overlay live in `sm-wavepath-app/parity` and are applied from outside. The phase may check the PHP submodules out at the commits the repo pins and may write to the local dev database.
|
||||
|
||||
### Corpus boundary
|
||||
- **D-09:** **The corpus is WavePath's community surface, about 190 routes:**
|
||||
- everything under `/_wave/api/v1/community`: `groups` (108 routes, group administration included), `dm`, `threads`, `prefs`, `forums`, `friends`, `notes`, `status`, `join`, `presence`, `call-links`, `call-guest`;
|
||||
- `/_wave/api/v1/guest/*` (call-link knock, guest session, guest thread and reactions);
|
||||
- `/_wave/api/v1/push/*`;
|
||||
- the bot and token routes under `/api/v1` (`conversations`, `conversations/{id}/messages`, `realtime/token`) and the `/hooks/{token}` webhook.
|
||||
|
||||
The researcher re-counts from `routes.php` at the recording commit and lists any route under these prefixes that no client calls.
|
||||
- **D-10:** **Every publication of every writing step is asserted.** Each corpus step that writes gets a broadcast golden with all publications PHP sent for it, on any namespace (`chat`, `video`, `presence:`, `user`, `wave`). Channel authorization (the Centrifugo subscribe proxy and `realtime/token`) is replayed as ordinary routes.
|
||||
- **D-11:** **Case depth is client paths plus denials.** Per route:
|
||||
- the cases the clients produced in the proxy sessions;
|
||||
- one denial per access rule (unauthenticated 401, non-member 403 or 404);
|
||||
- the validation errors the UI can trigger (422);
|
||||
- one 429 case per named rate bucket.
|
||||
|
||||
Outbound LiveKit and web-push calls are recorded as `tide` upstream sidecars and asserted on replay.
|
||||
|
||||
### Drift and fix policy
|
||||
- **D-12:** **The port contract is re-frozen at the recording commit.** It replaces the commits in P19 D-01 and P19.1 D-01. The WavePath commit and its pinned submodule commits are written into the manifest. Every delta since the old freeze that the corpus exercises is ported in this phase: into the shared Go plugin when the PHP change is in a shared plugin (chat `943b712..fbfbcf9`, attachment streaming with Range support), into the app plugin when it is in `wavepath` (guest threads and guest identity). — **Reversibility:** costly — names and shapes from the new freeze are copied into every app that mounts the shared plugins.
|
||||
- **D-13:** **Go reproduces PHP's observable behaviour, quirks included.** The one exception is a security defect (data reaching a non-member, a missing access check): Go keeps the safe behaviour, and the case goes into an accepted-differences file with its reason. The user signs off each entry. Precedent: the Phase 19.5 email-proof divergence.
|
||||
- **D-14:** **The PHP shape wins in the shared plugins; consumers follow.** A parity fix corrects the shared serializer or behaviour itself, so the generic `/_x/api/v1` APIs and the `/_wave` aliases keep one serializer set. Each changed plugin gets a patch tag and a changelog post on `/changelog/plugins`, and `sm-demo-app` and the vue layers are updated in this phase. A renamed or removed field is called out in the release notes. The user's condition: "1 is fine as long as sm-bm-app keeps working". Before any plugin tag, `sm-bm-app` (mounts chat, chatchannels and chatbots, with its own frontend) must build with the new plugin commits, pass its tests (`chat_test.go`, `realtime_test.go`), and have its frontend checked against any renamed or removed field. — **Reversibility:** costly — a changed field in a published plugin API reaches every mounting app and vue layer.
|
||||
- **D-15:** **The phase closes at zero pending.** Every corpus route is `ported` with passing cases, every broadcast golden is asserted, and the only non-matching cases are signed entries in the accepted-differences file. A fail-closed gate script checks this, and checks that `sm-bm-app` and `sm-demo-app` build and pass. The gate lives in `sm-wavepath-app`, because a script in `summercms.go` would name an application.
|
||||
|
||||
### Phase split and research answers (decided at planning, 2026-11-13)
|
||||
- **D-16:** **The work is split into three phases.** Research sized it at 12 to 15 large plans. Phase 31 is the corpus and harness: the `tide` additions (T-1 to T-10 in `31-RESEARCH.md`), the `sm-wavepath-app` skeleton, the PHP stack and the scenario, the full PHP recording of all 196 routes with broadcast and upstream sidecars, PHP self-replay green, the foundation slice ported (envelope, cookie actor, rate buckets, contexts, resolvers, the `wave` and presence authorizers, the realtime routes, groups, members, invites, join, friends, group lifecycle), the three folded todos and a unit-test plan. Phase 31.1 ports messaging and releases the chat Range delta. Phase 31.2 ports the satellites and closes out. This amends three earlier decisions for Phase 31:
|
||||
- D-15: the zero-pending gate closes Phase 31.2. In Phase 31 the gate script exists, fails closed on any failing or unrecorded case, and reports the pending count; it requires zero pending only for the foundation slice.
|
||||
- D-12: the manifest is frozen at the recording commit in Phase 31. The chat attachment Range delta is ported in Phase 31.1 and the guest thread and guest identity delta in Phase 31.2.
|
||||
- D-13: the accepted-differences file is created in Phase 31 and gets entries as routes are ported; the final sign-off is in Phase 31.2. The security review named under Claude's Discretion runs in Phase 31.2, when the guest, bot, token and webhook code exists.
|
||||
- **D-17:** **Two recording clients, not three.** `wavepath-mcp` calls no corpus route (it calls only diary, practices, trainings, stats, me and state). The corpus is recorded through `vue-wavepath-app` and `hubot-wavepath`. `wavepath-mcp` is recorded with the rest of the WavePath backend in a later phase. D-09's boundary is unchanged.
|
||||
- **D-18:** **Shared notes stay in the corpus, on a minimal diary read model.** The app plugin gets a small `DiaryEntry` read model and fixture rows, marked provisional for WavePath's agent to replace when the diary is ported. The notes routes are recorded in Phase 31 and ported in Phase 31.2.
|
||||
- **D-19:** **All 17 routes that no client calls stay in the corpus.** Each gets one hand-written success case recorded from PHP, plus its denial and validation cases.
|
||||
- **D-20:** **The PHP stack is isolated from the other agent's work.** [informational] The database is an isolated MariaDB container, not the dev database. The pinned submodule commits (`chat` at `fbfbcf9`, `journal`) are read through a git worktree or export under the parity root, so the `wavepath.org` working tree is not changed at all. This is stricter than D-08 allows.
|
||||
- **D-21:** **Replay logs in without the auth routes.** [informational] Both seeders mint the session JWTs into the `tide` vars store and requests carry them as the `token` cookie; `/_wave/api/v1/auth/login` stays outside the corpus.
|
||||
- **D-22:** **The slash fix matches WavePath.** WavePath refuses unknown slash text (the SPA blocks it from the command catalog and keeps the draft; PHP answers 422 `unknown_command`). The layer fix is therefore: check the first token against the command catalog client-side, keep the draft on an unknown command, and support a `//` escape that posts the rest as text. Unknown slash text is not posted as text.
|
||||
|
||||
Left for the later phases' own discussion: the search backend for the search cases (Typesense or the null driver) and the attachment `url` rewrite (research recommends app-side).
|
||||
|
||||
### Claude's Discretion
|
||||
- Go package, type and route-handler names in the app plugin, and the layout inside `parity/`.
|
||||
- The scenario's exact rows, as long as every access rule in D-11 has a user on each side of it.
|
||||
- How the PHP reset script is run against the checkout without committing there (artisan tinker, a script path, a mounted file).
|
||||
- The name of the gate script and of the accepted-differences file.
|
||||
- Whether `tide` needs additions (for example more broadcast normalisation rules for chat payloads). Any such change is generic, documented in `modules/tide/README.md` and names no application.
|
||||
- The module path and git remote of `sm-wavepath-app`. Creating a remote and pushing need the user's go-ahead.
|
||||
- Plan count and split, subject to the plan-count checkpoint and "unit tests are the last plan". This is a large phase; say so at the checkpoint and propose a split into decimal phases if the count gets unwieldy.
|
||||
- Run the security-review agent: the app plugin adds guest access, bot and token authentication, a webhook and access resolvers.
|
||||
|
||||
### Folded Todos
|
||||
- **Record PHP OIDC parity against WavePath before the OIDC cutover** (`2026-10-19-record-php-oidc-parity-against-wavepath.md`, `sm-oauthserver-plugin`). Phase 19.4 shipped the harness but never recorded PHP. The local WavePath stack from D-08 is exactly what the todo's runbook needs, so the recording is done here: follow `../sm-oauthserver-plugin/testdata/parity/README.md` until `PHASE194_REQUIRE_PARITY=1 go test -run '^(TestPHPParityReplay|TestIDTokenShapeParity)$' ./...` passes. It is separate from the community corpus and lives in the plugin repo.
|
||||
- **Chat messages that start with "/" but name no command are posted as text** (`chat-slash-text-escape.md`, `../vue-chat-layer/app/composables/useChat.ts`). Every text starting with "/" is dispatched as a command and refused. Fix in the layer: dispatch only when the first token is a known trigger from the command catalog, or support a "//" escape. The researcher first checks what `vue-wavepath-app` and the PHP command controller do with such text and matches that.
|
||||
- **Moderate profile names, friend-group names and chat attachment filenames** (`moderation-profile-group-and-filenames.md`, `../sm-demo-app/plugins/demo/moderation.go`). The demo's filter covers only message content and forum text. Add the checks through additive seams (a user-plugin saving event, a group saving seam in userfriends, filenames on chat's message-saving event). The seams are additive and must leave PHP parity untouched: with no listener, behaviour is unchanged.
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### The contract (PHP, read-only)
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — the route table. Groups at lines 195 (auth), 222 (guest), 252 (JWT API, community routes inside), 948 and 1022 (`/api/v1` token and bot), 1073 (`/hooks`).
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/` — the community controllers whose logic D-03 ports (`CommunityForumController`, `CommunityFriendsController`, `CommunityGroupController`, `CommunityVideoController`, `CommunityCommandController`, `CommunitySharedNoteController`, `BotRestController`, `PushSubscriptionController`).
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/Plugin.php` — seam bindings and group lifecycle wiring (lines 160-460 at the old freeze; re-check at the recording commit).
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/{chatbots,notifications,forum,video}/` — the host implementations of the seams.
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/{chat,chatchannels,chatbots,chatvideo,forum,herald,userfriends}` — the shared plugins. The repo pins chat at `fbfbcf9`; the working tree had it at `943b712` on 2026-11-13.
|
||||
- `/media/nvme/dev/jz/wavepath.org/vue-wavepath-app/src/`, `/media/nvme/dev/jz/wavepath.org/wavepath-mcp/src/`, `/media/nvme/dev/jz/wavepath.org/hubot-wavepath/src/` — the three clients that are recorded.
|
||||
- `/media/nvme/dev/jz/wavepath.org/.planning/notes/summercms-framework-asks-for-wavepath.md` — WavePath's hand-off list; section B is what its own agent ports later.
|
||||
|
||||
### Prior decisions that still bind
|
||||
- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — D-02 (no QuestStream trace), D-06 to D-10 (generic API, one serializer set), D-11 to D-14 (context registry, alias rewrite, festival hooks, deny-all resolvers), D-16 and D-17 (lighthouse namespaces). D-01's commits are superseded by D-12 here.
|
||||
- `.planning/phases/19.1-chat-satellites/19.1-CONTEXT.md` — D-05 (satellite generic APIs and rate buckets), D-08 (group lifecycle is app wiring), D-10 (push through fetchguard), D-13 to D-15 (LiveKit, reconciler, video events).
|
||||
- `.planning/phases/30-cutover/30-CONTEXT.md` — D-11 and D-12, the manifest acceptance set and the re-record with a drift report that D-06 and D-15 copy.
|
||||
- `.planning/notes/2026-10-18-roadmap-reorder-demo-release-wavepath.md` and `.planning/notes/wavepath-framework-asks-division.md` — why this phase opens the WavePath work.
|
||||
- `.planning/seeds/SEED-261007-0tb-wavepath-port.md` — size of the whole WavePath port.
|
||||
- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow.
|
||||
|
||||
### Tooling and patterns to copy
|
||||
- `modules/tide/README.md` — flows, recording proxy, capture rules, manifests, the Centrifugo recorder and broadcast goldens, upstream sidecars and the upstream recording proxy.
|
||||
- `../fonoteka.go/parity/` — the model for D-02 and D-04: `manifest.yaml`, `fixtures/`, `capture-rules.yaml`, `capture_clients.mjs`, `fonoteka_reset.php`, `fixtureplugin/`, `broadcast_goldens_test.go`, `upstream/`.
|
||||
- `../fonoteka.go/scripts/dev-stack.sh` — the fail-closed local stack script, a model for D-08.
|
||||
- `../sm-demo-app/summer.yaml`, `../sm-demo-app/chat_test.go`, `../sm-demo-app/realtime_test.go` — an app that already mounts all seven plugins.
|
||||
- `../sm-bm-app/summer.yaml`, `../sm-bm-app/chat_test.go`, `../sm-bm-app/realtime_test.go` — the consumer D-14 protects.
|
||||
|
||||
### Folded todos
|
||||
- `.planning/todos/pending/2026-10-19-record-php-oidc-parity-against-wavepath.md` and `../sm-oauthserver-plugin/testdata/parity/README.md`
|
||||
- `.planning/todos/pending/chat-slash-text-escape.md`
|
||||
- `.planning/todos/pending/moderation-profile-group-and-filenames.md`
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `tide`: everything the recording needs exists (loopback proxy with sessions, spec recording, manifest record and replay, Centrifugo recorder, broadcast goldens, upstream sidecars). It has no request-path rewriting, which D-01 makes unnecessary. Its broadcast normalisation has rules written for album and notification payloads; chat payloads may need generic additions.
|
||||
- The seven shared plugins, each with a typed service API, a generic `/_x/api/v1` API, a test-only host and `testdata/goldens/` built from PHP fixtures (never from a live PHP backend).
|
||||
- `sm-demo-app`: mounts all seven plugins and has chat, realtime and video tests; a working reference for wiring contexts and resolvers.
|
||||
- `lighthouse`: namespaces `chat`, `video` and `user` are registered by the plugins. `presence:` and `wave` belong to the app plugin.
|
||||
|
||||
### Established Patterns
|
||||
- App parity suite in the app repo, `go test ./parity` on testcontainers Postgres, pending never counts as a pass.
|
||||
- One scenario seeded by a PHP reset script and a Go fixture plugin.
|
||||
- Fail-closed per-phase gate script.
|
||||
- Plugin first (commit, push, tag), then the submodule pointer bump in each app as a separate commit.
|
||||
|
||||
### Integration Points
|
||||
- `sm-wavepath-app` registers the group context alias, installs the access resolvers, bot auth, herald profile and presence gate, and wires group lifecycle events to chat, channels, video and forum.
|
||||
- Consumers of the shared plugins today: `sm-demo-app` (all seven) and `sm-bm-app` (chat, chatchannels, chatbots).
|
||||
- The local PHP checkout has uncommitted work and belongs to another agent; the recording script must not leave changes in its working tree beyond the submodule checkouts and the dev database.
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- "phase 30 was meant for plytarium cutover, wavepath is totally separate project": no ordering against the Płytarium work.
|
||||
- "local wavepath is there in /media/nvme/dev/jz/wavepath.org we can work with it": use that checkout for the recording.
|
||||
- "1 is fine as long as sm-bm-app keeps working": `sm-bm-app` is a hard gate on every shared-plugin release.
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- The pre-freeze re-record with a drift report: a task of the WavePath cutover phase (D-06).
|
||||
- The rest of WavePath's backend and the MariaDB to Postgres import: later WavePath phases, owned with WavePath's agent.
|
||||
- `electron-wavepath` and `tauri-wavepath-desktop` as recording clients: with the full-surface corpus at the cutover.
|
||||
- A manual session of the real clients against the Go app: not required to close this phase (D-15); belongs to the cutover.
|
||||
|
||||
### Reviewed Todos (not folded)
|
||||
- The other ten matches were keyword noise and concern other work: the WinterCMS vs SummerCMS benchmark, gate scripts that name applications, changelog previous/next links, the forum and friends 401 refresh, MailBlocker, the menu plugin port, the first password for social accounts, README `src=` fences, the fonoteka README and the translate messages editor.
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 31-chat-polish-against-wavepath-clients*
|
||||
*Context gathered: 2026-11-13*
|
||||
@@ -0,0 +1,193 @@
|
||||
# Phase 31: Chat polish against WavePath clients - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-11-13
|
||||
**Phase:** 31-chat-polish-against-wavepath-clients
|
||||
**Areas discussed:** Replay target and paths, Recording source and timing, Corpus boundary, Drift and fix policy
|
||||
|
||||
---
|
||||
|
||||
## Todo cross-reference
|
||||
|
||||
13 pending todos matched; ten were keyword noise. Three were offered.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| None | Fold nothing | |
|
||||
| PHP OIDC parity | Record PHP OIDC parity against WavePath (sm-oauthserver-plugin) | ✓ |
|
||||
| Slash text escape | "/" text that names no command is refused (vue-chat-layer) | ✓ |
|
||||
| Moderate filenames | Moderate profile names, group names and attachment filenames (sm-demo-app) | ✓ |
|
||||
|
||||
**User's choice:** all three folded.
|
||||
|
||||
---
|
||||
|
||||
## Replay target and paths
|
||||
|
||||
### How recorded /_wave traffic reaches the Go plugins
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| /_wave aliases in a Go app | App skeleton mounts the plugins and serves the recorded paths, host seams wired | ✓ |
|
||||
| Path map in tide | Generic rewrite rules in tide, replay against the generic API on a test host | |
|
||||
| Aliases in plugin test hosts | Each plugin's test host registers /_wave-shaped aliases | |
|
||||
|
||||
### Where the app skeleton and corpus live
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| New sm-wavepath-app | Sibling repo laid out like fonoteka.go | ✓ |
|
||||
| Inside the wavepath.org repo | Go directory next to the PHP code | |
|
||||
| Throwaway parity host | Parity-only module, aliases rewritten later | |
|
||||
|
||||
### Diffs caused by Wave controller logic
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Port what chat routes need | App plugin ports controller logic and host seams for the recorded routes | ✓ |
|
||||
| Thin aliases only | Controller-caused diffs stay pending for the app port | |
|
||||
| You decide per route | Researcher classifies, planner picks | |
|
||||
|
||||
### Starting state
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| One scenario, seeded twice | PHP reset script plus Go fixture plugin | ✓ |
|
||||
| Import the PHP database | summer import:winter into Postgres | |
|
||||
| Flows build their own state | No shared seed beyond users | |
|
||||
|
||||
**User's choice:** the recommended option each time.
|
||||
|
||||
---
|
||||
|
||||
## Recording source and timing
|
||||
|
||||
### When the corpus is recorded
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Now, re-record before cutover | Record from today's PHP, re-record with a drift report before the freeze | ✓ |
|
||||
| Build now, record later | Binding corpus waits until the migration is near | |
|
||||
| Wait for Phase 30 | Keep the roadmap order | |
|
||||
|
||||
**User's choice:** free text first: "Why would it depend on phase 30, phase 30 was meant for plytarium cutover, wavepath is totally separate project". After the clarification that the dependency was sequencing only, the user chose option 1.
|
||||
**Notes:** the Phase 30 dependency is removed from the roadmap entry.
|
||||
|
||||
### How traffic is captured
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Proxy once, then scripted specs | Learn the real requests through the proxy, commit spec flows | ✓ |
|
||||
| Real clients through the proxy only | Every recording is a live session | |
|
||||
| Scripted specs from source | Specs written from the clients' API code | |
|
||||
|
||||
### Which PHP backend
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Local stack, scripted | Phase delivers a script that brings up the local checkout | ✓ (as interpreted) |
|
||||
| Local stack, you start it | User starts the stack | |
|
||||
| Staging through a tunnel | Deployed staging over SSH | |
|
||||
|
||||
**User's choice:** free text: "local wavepath is there in /media/nvme/dev/jz/wavepath.org we can work with it".
|
||||
**Notes:** recorded as the local checkout, brought up by a script from this phase.
|
||||
|
||||
### What may be written in wavepath.org
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Nothing committed there | Reset script and env overlay live in sm-wavepath-app/parity | ✓ |
|
||||
| A parity/ directory in wavepath.org | Committed on a branch there | |
|
||||
| Hand it to WavePath's agent | Spec only, implemented by the other agent | |
|
||||
|
||||
---
|
||||
|
||||
## Corpus boundary
|
||||
|
||||
### Neighbouring route groups (multi-select)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Forum and friends | community/forums (16), community/friends (8) | ✓ |
|
||||
| Bot and token REST | /api/v1 conversations, realtime/token, /hooks/{token} | ✓ |
|
||||
| Guest calls and guest thread | /_wave/api/v1/guest/* and community/call-guest | ✓ |
|
||||
| Shared notes and status | community/notes, status, join | ✓ |
|
||||
|
||||
### How much of community/groups
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| All of community/* | About 190 routes with guest, push and bot/token | ✓ |
|
||||
| Chat-facing group routes only | Group administration left to the app port | |
|
||||
| All, split in two phases | Chat core in 31, the rest in 31.1 | |
|
||||
|
||||
### Realtime assertions
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Every publication of every write step | All namespaces, authorization routes replayed | ✓ |
|
||||
| Only chat, video and presence: | user and wave publications pending | |
|
||||
| Goldens for a chosen event list | Only events the clients listen to | |
|
||||
|
||||
### Case depth
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Client paths plus denials | Client cases, one denial per rule, UI validation errors, upstream sidecars | ✓ |
|
||||
| Client paths only | Only what the proxy sessions produced | |
|
||||
| Full matrix | Every role and every rule | |
|
||||
|
||||
---
|
||||
|
||||
## Drift and fix policy
|
||||
|
||||
### Port contract after PHP drift
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Re-freeze at the recording commit | Deltas the corpus exercises are ported in this phase | ✓ |
|
||||
| Keep the old freeze, park the drift | Drift diffs pending | |
|
||||
| Record from the old commits | PHP submodules checked out at the frozen commits | |
|
||||
|
||||
### PHP quirks and bugs
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Reproduce, except security | Signed accepted-differences file for security defects | ✓ |
|
||||
| Reproduce everything | Unsafe behaviour fixed on PHP first | |
|
||||
| Fix obvious bugs in Go | Each listed as an accepted difference | |
|
||||
|
||||
### Releasing shared-plugin fixes
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| PHP shape wins, layers follow | Patch tags, changelog posts, demo app and vue layers updated | ✓ |
|
||||
| Additive only in shared plugins | /_wave alias adapts output in the app plugin | |
|
||||
| Ask per breaking change | Stop on removed, renamed or retyped fields | |
|
||||
|
||||
**User's choice:** free text: "1 is fine as long as sm-bm-app keeps working".
|
||||
**Notes:** sm-bm-app mounts chat, chatchannels and chatbots; it is a hard gate before every plugin tag.
|
||||
|
||||
### Closing bar
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Zero pending, signed exceptions | Fail-closed gate, sm-bm-app and sm-demo-app pass | ✓ |
|
||||
| Chat core green, rest may pend | Named pending list for the next phase | |
|
||||
| Green plus a manual client session | Adds a manual session of the three clients | |
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Names and layout in the app plugin and `parity/`, the scenario's rows, how the PHP reset script runs from outside the checkout, gate and accepted-differences file names, generic `tide` additions, the module path and remote of `sm-wavepath-app`, plan count and split.
|
||||
- The gate script lives in `sm-wavepath-app` rather than `summercms.go/scripts`, so that no framework script names an application.
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Pre-freeze re-record with a drift report (WavePath cutover phase).
|
||||
- The rest of WavePath's backend and the database import.
|
||||
- electron and tauri clients as recording clients.
|
||||
- A manual session of the real clients against the Go app.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,96 @@
|
||||
---
|
||||
phase: "31"
|
||||
slug: "chat-polish-against-wavepath-clients"
|
||||
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
|
||||
# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
|
||||
status: draft
|
||||
nyquist_compliant: false
|
||||
wave_0_complete: false
|
||||
created: "2026-11-13"
|
||||
---
|
||||
|
||||
# Phase 31 — Validation Strategy
|
||||
|
||||
> Per-phase validation contract for feedback sampling during execution.
|
||||
> Source: `31-RESEARCH.md`, section "Validation Architecture".
|
||||
|
||||
---
|
||||
|
||||
## Test Infrastructure
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Framework** | Go `testing` (testcontainers Postgres for the parity suite); Vitest in the vue layers |
|
||||
| **Config file** | none in `sm-wavepath-app` yet — Wave 0 creates the repo |
|
||||
| **Quick run command** | `go vet ./... && go test -short ./...` in each touched repo |
|
||||
| **Full suite command** | `go vet ./... && go test ./...` in `summercms.go`, `sm-wavepath-app` and each changed plugin; `scripts/check-parity.sh` in `sm-wavepath-app` |
|
||||
| **Estimated runtime** | quick: under 60 seconds per repo; full with Docker: several minutes |
|
||||
|
||||
---
|
||||
|
||||
## Sampling Rate
|
||||
|
||||
- **After every task commit:** Run `go vet ./... && go test -short ./...` in the touched repo
|
||||
- **After every plan wave:** Run `go test ./...` (Docker) in the touched repos and `go test ./parity` in `sm-wavepath-app`
|
||||
- **Before `/msd-verify-work`:** `scripts/check-parity.sh` in `sm-wavepath-app` must be green
|
||||
- **Max feedback latency:** 60 seconds for the quick run
|
||||
|
||||
---
|
||||
|
||||
## Per-Task Verification Map
|
||||
|
||||
Task IDs are filled in by the planner. The rows below are the behaviours every plan set must cover.
|
||||
|
||||
| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|
||||
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
|
||||
| TBD | TBD | TBD | SC-1 every corpus route recorded from PHP | — | fixtures carry no secrets (`--check-secrets`) | corpus check | `go run ./parity/check_corpus.go --manifest parity/manifest.yaml --routes <routes.php> --require-recorded --check-secrets` | ❌ W0 | ⬜ pending |
|
||||
| TBD | TBD | TBD | SC-1 Go replays every ported route; pending never passes | — | denial cases (401, 403, 404) replay | integration | `go test ./parity -run TestParityCorpus` | ❌ W0 | ⬜ pending |
|
||||
| 31-07-T2 | 31-07 | 6 | SC-1 foundation-pending 0 with 160 routes explicitly pending for Phases 31.1/31.2 (D-16) | T-31-24 | fail-closed foundation gate | gate | `scripts/check-parity.sh` | ❌ W0 | ⬜ pending |
|
||||
| TBD | TBD | TBD | SC-2 publications of each writing case match the golden (D-10) | — | no publication reaches a non-member channel | integration | `go test ./parity -run TestBroadcasts` | ❌ W0 | ⬜ pending |
|
||||
| TBD | TBD | TBD | SC-2 channel authorization routes replay | — | subscribe proxy and `realtime/token` deny non-members | integration | `go test ./parity -run 'TestParityCorpus/.*realtime'` | ❌ W0 | ⬜ pending |
|
||||
| TBD | TBD | TBD | D-11 vendor calls match the sidecars | — | N/A | integration | `go test ./parity -run TestUpstreamSidecarsAreReplayed` | ❌ W0 | ⬜ pending |
|
||||
| TBD | TBD | TBD | SC-3 `sm-bm-app` builds and passes with the new plugin commits (D-14) | — | N/A | integration | `cd ../sm-bm-app && go build ./... && go test ./...` | ✅ | ⬜ pending |
|
||||
| TBD | TBD | TBD | SC-3 `sm-demo-app` builds and passes | — | N/A | integration | `cd ../sm-demo-app && go test ./...` | ✅ | ⬜ pending |
|
||||
| TBD | TBD | TBD | SC-3 framework docs name no application | — | N/A | docs check | `summer docs:build --check` and `go test ./cmd/summer -run TestDocsTree` | ✅ | ⬜ pending |
|
||||
| TBD | TBD | TBD | SC-4 tide additions | — | N/A | unit | `go test ./modules/tide/...` | ✅ (extend) | ⬜ pending |
|
||||
| 31-11-T2 | 31-11 | 7 | SC-4 foundation app-plugin services | T-31-20, T-31-21, T-31-22, T-31-24 | envelope, cookie actor, buckets, contexts, resolvers, authorizers, realtime, groups/members/invites/join/friends/lifecycle | unit | `go test -short ./plugins/golem15/wavepath/...` | ❌ W0 | ⬜ pending |
|
||||
| TBD | TBD | TBD | Todo: OIDC parity | — | N/A | integration | `PHASE194_REQUIRE_PARITY=1 go test -count=1 -run '^(TestPHPParityReplay\|TestIDTokenShapeParity)$' ./...` in `sm-oauthserver-plugin` | ✅ (skips today) | ⬜ pending |
|
||||
| TBD | TBD | TBD | Todo: moderation seams fire and reject | — | with no listener, behaviour is unchanged | unit | `go test -short ./...` in user, userfriends, chat; `go test ./... -run TestModeration` in `sm-demo-app` | partly | ⬜ pending |
|
||||
| TBD | TBD | TBD | Todo: slash handling in the layer | — | N/A | unit | the layer's Vitest suite (`pnpm --dir ../vue-chat-layer test`) | ✅ (extend) | ⬜ pending |
|
||||
|
||||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||||
|
||||
---
|
||||
|
||||
## Wave 0 Requirements
|
||||
|
||||
- [ ] `sm-wavepath-app` repo: `go.mod`, `go.work`, submodules, `summer.yaml`
|
||||
- [ ] `parity/parity_test.go` with a `TestMain` that calls `flag.Parse()` and checks `testing.Short()`
|
||||
- [ ] `parity/check_corpus.go` and `routes.snapshot`
|
||||
- [ ] `parity/fixtureplugin` and `wavepath_reset.php` for the scenario
|
||||
- [ ] `scripts/parity-stack.sh` and `parity/php_parity.sh`
|
||||
- [ ] `scripts/check-parity.sh`
|
||||
- [ ] tide tests for each addition (T-1 to T-10 in `31-RESEARCH.md`)
|
||||
|
||||
---
|
||||
|
||||
## Manual-Only Verifications
|
||||
|
||||
| Behavior | Requirement | Why Manual | Test Instructions |
|
||||
|----------|-------------|------------|-------------------|
|
||||
| PHP self-replay is green | SC-1 | needs the local PHP stack running; not part of `go test` | bring the stack up with `scripts/parity-stack.sh`, then `summer parity:replay --manifest parity/manifest.yaml --self-check true` |
|
||||
| Proxy sessions of the real clients | D-07 | done once by a person driving the clients through `summer parity:proxy` | follow the recording runbook in `sm-wavepath-app/parity/README.md` |
|
||||
| Accepted-differences review for foundation entries | D-13, D-16 | each Phase 31 entry needs the user's signature; final corpus sign-off is Phase 31.2 | review foundation entries before the Phase 31 gate; do not require 31.1/31.2 entries yet |
|
||||
|
||||
---
|
||||
|
||||
## Validation Sign-Off
|
||||
|
||||
- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
|
||||
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
|
||||
- [ ] Wave 0 covers all MISSING references
|
||||
- [ ] No watch-mode flags
|
||||
- [ ] Feedback latency < 60s
|
||||
- [ ] `nyquist_compliant: true` set in frontmatter
|
||||
|
||||
**Approval:** pending
|
||||
1
.planning/phases/31.1-wavepath-messaging-parity/.gitkeep
Normal file
1
.planning/phases/31.1-wavepath-messaging-parity/.gitkeep
Normal file
@@ -0,0 +1 @@
|
||||
|
||||
119
.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md
Normal file
119
.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Phase 31.1: WavePath messaging parity - Context
|
||||
|
||||
**Gathered:** 2026-11-13
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
The messaging routes of the WavePath corpus recorded in Phase 31 replay green against Go: group chat, channels, direct messages, threads, commands, reactions, emoji, preferences, pins and attachments, including the attachment streaming delta with Range support (31 D-12) released in `sm-chat-plugin`. Broadcast goldens for writing cases are asserted. `sm-bm-app` and `sm-demo-app` build and pass with each released plugin version (31 D-14). Unit tests are the last plan.
|
||||
|
||||
Out of scope (Phase 31.2): presence and status, notifications and push, full link-unfurl resolve/jobs, webhook CRUD/ingest, bot REST and token guard, search, video and guests, forums and shared notes, zero-pending close-out and the security review.
|
||||
|
||||
**Repos touched:** `sm-wavepath-app` (messaging handlers, row decorator, image proxies); `sm-chat-plugin` (Range streamer release); other shared chat plugins only for parity fixes found by replay; `sm-demo-app`, `sm-bm-app` and vue layers to follow shared-plugin changes.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Carry-forward from Phase 31 (binding)
|
||||
- **D-01:** Phase 31 D-01, D-03, D-10, D-11, D-12, D-13, D-14 and D-16 still bind. Thin `/_wave` aliases; app plugin ports controller logic; every writing case has broadcast goldens; case depth is client paths plus denials; Range delta and messaging close this phase; quirks reproduced except security defects; shared-plugin shape wins with the bm/demo consumer gate; whole-corpus zero-pending closes in 31.2.
|
||||
- **D-02:** Messaging slice scope matches research area E and the roadmap: group chat, channels, DM, threads, commands, host-facing reactions/emoji/prefs/pins/attachments, plus the chat Range release and unit tests.
|
||||
|
||||
### Attachment URL in JSON
|
||||
- **D-03:** **App-side rewrite only.** The WavePath row decorator rewrites attachment `url` to the PHP legacy path; the shared `/_chat` serializer keeps today's Go path. No D-14 field change for bm/demo/layers. — **Reversibility:** reversible — local to the app decorator.
|
||||
- **D-04:** **Absolute URLs.** Rewritten values match PHP `url(...)`: `{app_base}/api/chat/attachments/{messageId}/{fileId}`.
|
||||
- **D-05:** **HTTP and broadcasts.** Every `/_wave` JSON body and every chat/`wave` publication that embeds attachments carries the rewritten absolute `url`.
|
||||
- **D-06:** **Host from app config base URL.** Use the Summer app URL (PHP `APP_URL` equivalent), not the request `Host` header.
|
||||
|
||||
### Reactions and thread mute (locked without deep dive)
|
||||
- **D-07:** **Map reactions onto the existing chat reactions API.** Do not port host `golem15_wavepath_reactions`. Observable `/_wave` shape is adapted in the app decorator as needed. — **Reversibility:** costly — MariaDB import and any later host-table migration must map onto chat reactions instead of a parallel host table.
|
||||
- **D-08:** **Map thread mute onto chat `ThreadMute`.** Do not keep a separate host `ThreadSubscription` table for mute. — **Reversibility:** costly — same import concern as D-07.
|
||||
|
||||
### Image helper routes vs 31.2
|
||||
- **D-09:** **Port `unfurl-image` and `webhook-icon` GETs in 31.1.** Full link-unfurl resolve/jobs and webhook CRUD/ingest stay in 31.2. Success cases use a seeded cache so chat UI image fetches replay green without the fetch pipeline.
|
||||
- **D-10:** **Port the full proxy classes now** (`WebhookIconProxy`-equivalent and unfurl image serving) using `fetchguard`, still without CRUD or resolve jobs.
|
||||
- **D-11:** **No live egress in `go test ./parity`.** Proxy fetches are answered from fixtures and upstream sidecars only.
|
||||
|
||||
### Claude's Discretion
|
||||
- Exact decorator merge order for shared row vs host extras (beyond D-03…D-06).
|
||||
- Package and type names for the Range streamer and image proxies.
|
||||
- How seeded unfurl/icon rows are laid out in the Phase 31 scenario without expanding corpus scope.
|
||||
- Plan count and wave split inside 31.1, subject to lean planning and "unit tests last".
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Prior phase contract
|
||||
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md` — D-01…D-22; messaging split (D-16); Range in 31.1; consumer gate (D-14).
|
||||
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md` — area E sizing, attachment URL analysis, Range delta notes, controller inventory, image helper routes.
|
||||
- `.planning/ROADMAP.md` — Phase 31.1 goal and success criteria.
|
||||
- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — shared serializer, context registry, alias rewrite.
|
||||
- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow.
|
||||
|
||||
### PHP contract (read-only)
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — messaging, attachment, unfurl-image and webhook-icon routes.
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/CommunityChatController.php` — `unfurlImage`, `webhookIcon`, `serveUnfurlFile`, AttachmentStreamer usage.
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/services/WebhookIconProxy.php` — remote icon proxy behaviour.
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/chat` at pin `fbfbcf9` — `AttachmentStreamer` / Range commits.
|
||||
|
||||
### Go assets
|
||||
- `../sm-chat-plugin/api/download.go` — current download handler (no Range yet).
|
||||
- `../sm-chat-plugin/classes/serialize.go` — shared message/attachment `url` shape.
|
||||
- `modules/tide/README.md` — replay, broadcast goldens, upstream sidecars, recorded headers for Range.
|
||||
- `../sm-bm-app/summer.yaml`, `../sm-bm-app/chat_test.go`, `../sm-bm-app/realtime_test.go` — D-14 consumer gate.
|
||||
- `../sm-demo-app/summer.yaml`, `../sm-demo-app/chat_test.go` — D-14 consumer gate.
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `sm-chat-plugin` download path streams via `bucket.NewReader` today; research recommends an exported Range-aware streamer in `classes` shared by plugin and app handlers (`blob.NewRangeReader` available in pinned gocloud).
|
||||
- WavePath PHP already streams unfurl/webhook-icon through `AttachmentStreamer::forFile` (Range-aware, private inline) — Go should reuse the same streamer for those GETs.
|
||||
- App row decoration pattern from Phase 19/31: shared serializer base + host merge in the wavepath app plugin.
|
||||
- `tide` upstream sidecars and broadcast goldens from Phase 31 harness.
|
||||
|
||||
### Established Patterns
|
||||
- Fail-closed parity: pending never counts as pass; phase gate reports messaging pending zero for 31.1 close.
|
||||
- Plugin first (commit, push, tag), then submodule pointer bumps; changelog post on `/changelog/plugins`.
|
||||
- PHP quirks win except security defects → accepted-differences (created in Phase 31).
|
||||
|
||||
### Integration Points
|
||||
- Messaging handlers and aliases in `sm-wavepath-app` `wavepath` plugin.
|
||||
- Range release changes generic `/_chat/api/v1/attachments/...` headers (additive; D-14 still runs).
|
||||
- Image proxy GETs attach to group/channel/DM message routes already in the messaging controllers.
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- User: "2,3 - map into existing api" for reactions and thread mute — prefer chat plugin APIs over host parallel tables even where research favoured host tables for import fidelity.
|
||||
- Attachment URL: research recommendation (app-side rewrite) accepted as-is.
|
||||
- Image helpers: prefer full proxy classes early over minimal read models, but keep parity tests offline (fixtures/sidecars).
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- Full link-unfurl resolve pipeline, OG fetch jobs, and webhook CRUD/ingest — Phase 31.2.
|
||||
- Search backend choice (Typesense vs null driver) — Phase 31.2 discussion (31 D-16 note).
|
||||
- Presence, status, push, video, guests, forums, notes, bot REST, zero-pending close-out, security review — Phase 31.2.
|
||||
|
||||
### Reviewed Todos (not folded)
|
||||
- Thirteen keyword matches; slash-command escape, moderation seams and OIDC PHP recording already folded into Phase 31. Remaining matches were noise for messaging (changelog prev/next, forum/friends 401 refresh, menu plugin, README fences, fonoteka README, translate messages editor, MailBlocker, social first-password, gate scripts naming apps).
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 31.1-wavepath-messaging-parity*
|
||||
*Context gathered: 2026-11-13*
|
||||
@@ -0,0 +1,131 @@
|
||||
# Phase 31.1: WavePath messaging parity - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-11-13
|
||||
**Phase:** 31.1-wavepath-messaging-parity
|
||||
**Areas discussed:** Attachment URL in JSON, Image helper routes vs 31.2 (Reactions storage and Thread mute mapping locked without deep dive)
|
||||
|
||||
---
|
||||
|
||||
## Area selection
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Attachment URL in JSON | PHP legacy path vs Go path | ✓ |
|
||||
| Reactions storage | Host table vs chat API | locked as map-to-existing |
|
||||
| Thread mute mapping | Host subscription vs chat ThreadMute | locked as map-to-existing |
|
||||
| Image helper routes vs 31.2 | Port GETs now vs leave pending | ✓ |
|
||||
|
||||
**User's choice:** Discuss 1 and 4; for 2 and 3 map into existing API.
|
||||
**Notes:** No todos folded into 31.1.
|
||||
|
||||
---
|
||||
|
||||
## Reactions storage (no deep dive)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Host model | Port `golem15_wavepath_reactions` | |
|
||||
| Map into existing API | Use chat plugin reactions | ✓ |
|
||||
|
||||
**User's choice:** Map into existing API.
|
||||
**Notes:** Overrides research preference for host tables (import fidelity).
|
||||
|
||||
---
|
||||
|
||||
## Thread mute mapping (no deep dive)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Host table | Keep `ThreadSubscription` | |
|
||||
| Map into existing API | Use chat `ThreadMute` | ✓ |
|
||||
|
||||
**User's choice:** Map into existing API.
|
||||
|
||||
---
|
||||
|
||||
## Attachment URL in JSON
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| App-side rewrite only | WavePath decorator; shared `/_chat` unchanged | ✓ |
|
||||
| Shared serializer change | D-14 release for all consumers | |
|
||||
| Accepted difference | Leave Go paths in `/_wave` | |
|
||||
|
||||
**User's choice:** App-side rewrite only.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Absolute | Match PHP `url(...)` with host | ✓ |
|
||||
| Path-only | `/api/chat/attachments/...` | |
|
||||
| Fixture-driven | Match whatever one golden shows | |
|
||||
|
||||
**User's choice:** Absolute.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| HTTP and broadcasts | REST + publications with attachments | ✓ |
|
||||
| HTTP only | Leave broadcast payloads as shared serializer | |
|
||||
| You decide | Green replay is enough | |
|
||||
|
||||
**User's choice:** HTTP and broadcasts.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| App config base URL | Summer app URL / PHP APP_URL | ✓ |
|
||||
| Request Host | Build from incoming request | |
|
||||
| You decide | Fixtures agree | |
|
||||
|
||||
**User's choice:** App config base URL.
|
||||
|
||||
---
|
||||
|
||||
## Image helper routes vs 31.2
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Port the GETs in 31.1 | unfurl-image + webhook-icon; CRUD/jobs later | ✓ |
|
||||
| Leave pending until 31.2 | Messaging gate ignores them | |
|
||||
| Port unfurl-image only | webhook-icon with webhooks | |
|
||||
|
||||
**User's choice:** Port the GETs in 31.1.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Seeded cache | Success from fixtures; miss matches PHP | ✓ |
|
||||
| Always 404 until 31.2 | Only denials in 31.1 | |
|
||||
| You decide | Green cases | |
|
||||
|
||||
**User's choice:** Match PHP with seeded cache.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Minimal read models only | Fixture rows, no proxy classes | |
|
||||
| Full proxy classes now | fetchguard proxies; no CRUD/jobs | ✓ |
|
||||
| You decide | Green GETs | |
|
||||
|
||||
**User's choice:** Port the full proxy classes now.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Fixture / sidecar only | No live egress in parity tests | ✓ |
|
||||
| Allow live fetchguard | Real HTTP when allow-listed | |
|
||||
| You decide | No flaky deps | |
|
||||
|
||||
**User's choice:** Fixture / sidecar only.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Decorator merge details beyond the locked URL rewrite rules
|
||||
- Streamer and proxy type names
|
||||
- Scenario seed layout for unfurl/icon rows
|
||||
- Plan count inside the phase
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Full unfurl resolve/jobs and webhook CRUD → Phase 31.2
|
||||
- Search backend → Phase 31.2 discussion
|
||||
@@ -0,0 +1 @@
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
# Phase 31.2: WavePath satellites parity and close-out - Context
|
||||
|
||||
**Gathered:** 2026-11-13
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
The rest of the WavePath corpus replays green against Go and the corpus closes at zero pending (31 D-15): presence and status, notifications and push, full link-unfurl resolve/jobs, webhook CRUD/ingest, bot REST with the token guard, search, video and guests (including the guest thread and guest identity freeze delta), forums and shared notes (on the minimal provisional diary read model from 31 D-18). Broadcast goldens and upstream sidecars are asserted. The fail-closed gate in `sm-wavepath-app` requires zero pending and that `sm-bm-app` and `sm-demo-app` build and pass. Accepted-differences are signed off in a batch at close-out. The security review of guest, bot/token, webhook and access resolvers runs as part of that close-out and its findings are resolved before the phase ends. Unit tests are the last plan. The unattended re-record-with-drift path remains runnable (31 D-06); the pre-freeze re-record itself stays a WavePath cutover task.
|
||||
|
||||
Out of scope: MariaDB→Postgres import and production cutover; diary/practices/trainings/stats beyond the provisional notes read model; `wavepath-mcp` diary surface; desktop clients as recording clients.
|
||||
|
||||
**Repos touched:** `sm-wavepath-app` (satellite handlers, host seams, provisional diary, gate at zero pending); shared plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and vue layers to follow; folded vue-forum / vue-userfriends 401 refresh.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Carry-forward from Phases 31 and 31.1 (binding)
|
||||
- **D-01:** Phase 31 D-01, D-03, D-06, D-10, D-11, D-12, D-13, D-14, D-15, D-16 and D-18 still bind. Thin `/_wave` aliases; app plugin ports host controller logic; broadcast goldens and upstream sidecars; case depth; freeze at recording commit with guest delta here; quirks except security defects → accepted-differences; shared-plugin shape wins with bm/demo consumer gate; zero pending closes this phase; notes on a minimal provisional `DiaryEntry` read model; re-record path left runnable unattended.
|
||||
- **D-02:** Phase 31.1 D-03…D-06 (attachment URL rewrite), D-09…D-11 (image helper GETs already ported; no live egress in `go test ./parity`) still bind. Full unfurl resolve/jobs and webhook CRUD/ingest are in this phase and stay parity-offline for tests (see D-04).
|
||||
|
||||
### Search backend
|
||||
- **D-03:** **Typesense on both sides for the search cases.** Run Typesense containers for PHP recording and Go replay so `GET …/search` exercises a real indexed result set, not the null-driver empty response. — **Reversibility:** costly — recording and goldens assume Typesense-backed hits; switching to null later invalidates search fixtures.
|
||||
|
||||
### Unfurl resolve and webhook ingest
|
||||
- **D-04:** **Keep parity offline.** Recording may capture real upstream responses into tidecars once; `go test ./parity` never performs live egress for unfurl resolve/jobs or webhook outbound fetches. Replay answers from fixtures and upstream sidecars only (same rule as 31.1 D-11 for image helpers). — **Reversibility:** reversible — local to the parity harness.
|
||||
|
||||
### Satellite port order
|
||||
- **D-05:** **Port by the suggested bundles, in this order:** (1) presence, status, notifications and push; (2) webhooks, bot REST with token guard, and search; (3) video and guests (including guest thread/identity delta); (4) forums and shared notes; (5) close-out (accepted-differences batch sign-off, security review and findings, zero-pending gate, consumer builds, unit tests last). — **Reversibility:** reversible — plan-wave ordering only.
|
||||
|
||||
### Close-out
|
||||
- **D-06:** **Batch accepted-differences sign-off at the end.** Entries may be drafted while routes are ported, but the user signs the file once at close-out, not route-by-route. — **Reversibility:** reversible — process only.
|
||||
- **D-07:** **Security review is part of close-out, before the phase is done.** Run it over guest access, bot and token authentication, webhook and access resolvers; resolve findings before the zero-pending gate is accepted as green. Prefer review after the satellite code exists (after bundles 1–4), not before zero pending is reachable. — **Reversibility:** reversible — sequencing only.
|
||||
|
||||
### Claude's Discretion
|
||||
- Exact package/type/handler names inside the app plugin and how provisional diary rows are laid out beyond 31 D-18.
|
||||
- Typesense image tag and how PHP Scout / Go search wire into the parity stack, as long as D-03 holds.
|
||||
- Plan count and wave split inside D-05, subject to lean planning and "unit tests last".
|
||||
- Gate script and accepted-differences file names (already Claude's discretion in Phase 31).
|
||||
|
||||
### Folded Todos
|
||||
- **Single-flight 401 refresh in the forum and friends clients** (`forum-friends-client-401-refresh.md`, `vue-forum-layer` / `vue-userfriends-layer`). Forum and friends hooks never retry on 401; after JWT expiry forum shows "thread not found" while chat still works. Give both clients the chat-shaped `{token, refresh, unauthorized}` auth hook, single-flight refresh-and-retry, and a signed-out message instead of not-found. Fits because forums land in this phase's corpus and the layers must follow shared/forum consumer behaviour.
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Prior phase contract
|
||||
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md` — D-01…D-22; corpus boundary; D-15/D-16 zero-pending in 31.2; D-18 notes; security review deferred here.
|
||||
- `.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md` — area F sizing, Pitfall 7 (Typesense vs null), controller inventory, rate buckets.
|
||||
- `.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md` — messaging closed; image helpers offline; attachment URL rewrite; unfurl/webhook full pipeline deferred here.
|
||||
- `.planning/phases/19.1-chat-satellites/19.1-CONTEXT.md` — herald push, LiveKit, forum, chatbots, userfriends generic APIs and seams.
|
||||
- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — serializer, context registry, alias rewrite, lighthouse namespaces.
|
||||
- `.planning/ROADMAP.md` — Phase 31.2 goal and success criteria.
|
||||
- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow.
|
||||
- `.planning/notes/2026-10-18-webpush-go.md` — herald webpush-go pin.
|
||||
- `.planning/notes/2026-10-18-livekit-server-sdk-go.md` — chatvideo LiveKit pin.
|
||||
|
||||
### PHP contract (read-only)
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — presence, status, push, unfurl, webhooks, bot/token, search, video, guest, forums, notes.
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/` — community satellite controllers (`CommunityPresenceController`, `CommunityStatusController`, `PushSubscriptionController`, unfurl/webhook controllers, `BotRestController`, search, video/guest, forum, shared notes).
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/Plugin.php` — host seam bindings and group lifecycle.
|
||||
- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/{notifications,forum,video,chatbots}/` — host seam implementations.
|
||||
|
||||
### Go / harness assets
|
||||
- `modules/tide/README.md` — replay, broadcast goldens, upstream sidecars.
|
||||
- `../sm-herald-plugin/`, `../sm-chatvideo-plugin/`, `../sm-forum-plugin/`, `../sm-chatbots-plugin/`, `../sm-chatchannels-plugin/` — satellite plugins (search indexer / Typesense seam lives with channels research notes).
|
||||
- `../sm-bm-app/summer.yaml`, `../sm-bm-app/chat_test.go`, `../sm-bm-app/realtime_test.go` — D-14 consumer gate.
|
||||
- `../sm-demo-app/summer.yaml` and its chat/realtime/video tests — D-14 consumer gate.
|
||||
- `.planning/todos/pending/forum-friends-client-401-refresh.md` — folded todo.
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- Shared satellite plugins already expose typed services and `/_x/api/v1` APIs; WavePath `/_wave` handlers are thin aliases plus host merge (31 D-01/D-03).
|
||||
- Herald push through `webpush-go` + fetchguard; chatvideo LiveKit + upstream sidecars; forum Markdown + deny-all resolver — all from Phase 19.1.
|
||||
- 31.1 image proxies and attachment URL decorator patterns for extending unfurl/webhook host routes.
|
||||
- `tide` upstream sidecars and broadcast goldens for push and LiveKit assertions.
|
||||
|
||||
### Established Patterns
|
||||
- Fail-closed parity: pending never counts as pass; Phase 31.2 gate requires total zero pending.
|
||||
- Plugin first (commit, push, tag), then submodule pointer bumps; changelog on `/changelog/plugins`.
|
||||
- PHP quirks win except security defects → accepted-differences (final batch sign-off this phase).
|
||||
- No live egress in `go test ./parity` (31.1 D-11 extended by D-04).
|
||||
|
||||
### Integration Points
|
||||
- App plugin: presence/`wave` authorizers, herald profile and presence gate, notification dispatch, bot auth resolver, forum access resolver, video/guest host logic, provisional diary for notes, webhook ingest.
|
||||
- Typesense containers on the Phase 31 isolated PHP stack and on Go parity for search cases (D-03).
|
||||
- Folded 401 refresh in `vue-forum-layer` and `vue-userfriends-layer` alongside forum route parity.
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- User skipped point-by-point discussion and locked all four gray areas in one reply: Typesense; keep parity offline; suggested satellite order; batch accepted-differences at the end.
|
||||
- Security review placed in close-out after satellite code exists, findings resolved before phase done.
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- Pre-freeze corpus re-record with drift report — WavePath cutover phase (31 D-06).
|
||||
- Full diary/practices/trainings/stats and MariaDB import — later WavePath phases.
|
||||
- `wavepath-mcp` as a recording client — later WavePath backend corpus.
|
||||
|
||||
### Reviewed Todos (not folded)
|
||||
- OIDC PHP parity recording, chat slash-command escape, and moderation seams — already folded into Phase 31.
|
||||
- Remaining keyword matches were noise for this phase (changelog prev/next, menu plugin, README fences, fonoteka README, translate messages editor, MailBlocker, social first-password, gate scripts naming apps, Winter vs Summer benchmark).
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 31.2-wavepath-satellites-parity-and-close-out*
|
||||
*Context gathered: 2026-11-13*
|
||||
@@ -0,0 +1,82 @@
|
||||
# Phase 31.2: WavePath satellites parity and close-out - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-11-13
|
||||
**Phase:** 31.2-wavepath-satellites-parity-and-close-out
|
||||
**Areas discussed:** Search backend, Unfurl resolve & webhook ingest, Satellite port order, Close-out gates (batch answers; no point-by-point deep dive)
|
||||
|
||||
---
|
||||
|
||||
## Todos fold-in
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Forum/friends 401 refresh | Single-flight 401 refresh in forum and friends vue layers | ✓ |
|
||||
| OIDC PHP parity | Already in Phase 31 | |
|
||||
| Chat slash escape | Already in Phase 31 | |
|
||||
| Moderation seams | Already in Phase 31 | |
|
||||
| None | Leave all out | |
|
||||
|
||||
**User's choice:** Forum/friends 401 refresh
|
||||
**Notes:** Folded into 31.2 because forums are in this corpus.
|
||||
|
||||
---
|
||||
|
||||
## Search backend
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Typesense containers both sides | Real indexed search cases | ✓ |
|
||||
| SCOUT_DRIVER=null | Empty results; weaker fixture | |
|
||||
|
||||
**User's choice:** Typesense
|
||||
**Notes:** Locked without deep dive ("1 typesense").
|
||||
|
||||
---
|
||||
|
||||
## Unfurl resolve & webhook ingest
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Keep parity offline | Fixtures + upstream sidecars only in `go test ./parity` | ✓ |
|
||||
| Controlled live during recording | Live fetch allowed in some harness paths | |
|
||||
|
||||
**User's choice:** Keep parity offline
|
||||
**Notes:** Aligns with 31.1 D-11 for image helpers.
|
||||
|
||||
---
|
||||
|
||||
## Satellite port order
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Suggested bundles | presence/push → webhooks/bot/search → video/guests → forums/notes → close-out | ✓ |
|
||||
| Different cut | User-defined reordering | |
|
||||
|
||||
**User's choice:** As suggested
|
||||
**Notes:** No alternative order proposed.
|
||||
|
||||
---
|
||||
|
||||
## Close-out gates
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Sign accepted-differences as routes land | Continuous sign-off | |
|
||||
| Batch at the end | One sign-off at close-out | ✓ |
|
||||
| Security review before vs after zero pending | (clarified in CONTEXT as close-out after code exists, findings before done) | ✓ (batch/close-out) |
|
||||
|
||||
**User's choice:** Batch at the end
|
||||
**Notes:** User answered area 4 as "batch at the end"; security review interpreted as part of that close-out sequence.
|
||||
|
||||
---
|
||||
|
||||
## the agent's Discretion
|
||||
|
||||
- Package/type names, Typesense wiring details under D-03, plan/wave split inside D-05, gate and accepted-differences file names.
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Pre-freeze re-record (WavePath cutover); full diary backend; wavepath-mcp recording client.
|
||||
375
.planning/phases/32-seo-foundation/32-06-SUMMARY.md
Normal file
375
.planning/phases/32-seo-foundation/32-06-SUMMARY.md
Normal file
@@ -0,0 +1,375 @@
|
||||
---
|
||||
phase: 32-seo-foundation
|
||||
plan: 06
|
||||
subsystem: release
|
||||
tags: [release, apisurface, additive-gate, compat-gate, unit-tests, vitest, sm-seo-plugin, sm-journal-plugin, sm-demo-app, changelog]
|
||||
|
||||
requires:
|
||||
- phase: 32-01
|
||||
provides: cross-plugin admin form extensions (pact.AdminFormExtension, cabana compile and save)
|
||||
- phase: 32-02
|
||||
provides: record events (pact.RecordSaved/RecordDeleted, cabana.EmitRecord*), content descriptors (pact.ContentDescriptor, signpost lookups), Journal adoption
|
||||
- phase: 32-03
|
||||
provides: sm-seo-plugin core (entries, rules, settings, resolver, history)
|
||||
- phase: 32-04
|
||||
provides: redirects, 404 log, robots.txt
|
||||
- phase: 32-05
|
||||
provides: management API, MCP tools, batches, undo, CSV, check-phase32.sh, 32-05-demo-mount.patch
|
||||
provides:
|
||||
- "scripts/check-phase32.sh stages additive (scripts/apisurface API-surface comparison with the previous release) and compat (three consumers tested, every other sibling built), with self-tests"
|
||||
- "Framework unit matrices for form extensions, record events and content descriptors"
|
||||
- "sm-seo-plugin unit tests (classes) and 52 vitest element tests; sm-journal-plugin descriptor, journal-tag and translated-slug tests"
|
||||
- "SummerCMS v0.5.1 (patch, strictly additive), sm-journal-plugin v0.2.5, sm-seo-plugin v0.1.0 (first release), all pushed"
|
||||
- "sm-demo-app mounts golem15.seo v0.1.0 (pushed, not deployed)"
|
||||
- "Changelog post https://summercms.io/changelog/summercms-0-5-1"
|
||||
affects: [33, sm-demo-app, sm-grzybyfunkcjonalne-app, sm-summercmsio-app, vue-seo-layer]
|
||||
|
||||
actuals:
|
||||
tokens: 51000
|
||||
tasks: 5
|
||||
commits: 4
|
||||
plan_head_before: 49502e8ccb98e29a067961641dd08e2d39e42f27
|
||||
plan_head_after: a9a7f58eedaf70edd3472b6aebe01b2db4cbb498
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Release gate: the API surface of every changed framework package is compared with the previous release tag (tags containing HEAD skipped); removed or changed elements and methods added to existing interfaces are refused"
|
||||
- "Compat gate reads sibling repositories through temporary-index snapshots or detached worktrees and builds them in a symlinked scratch sibling layout"
|
||||
- "Release steps are logged as they complete (32-06-release-log.md) so a resumed run never re-tags, force-pushes or re-posts"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- scripts/apisurface/main.go
|
||||
- modules/cabana/form_extensions_test.go
|
||||
- modules/cabana/record_events_test.go
|
||||
- modules/signpost/content_test.go
|
||||
- .planning/phases/32-seo-foundation/32-06-release-log.md
|
||||
- .planning/phases/32-seo-foundation/deferred-items.md
|
||||
- ../sm-seo-plugin/classes/*_test.go (resolver, redirect_graph, normalize, robots_value, robots, templates, csv, owner, issues, helpers)
|
||||
- ../sm-seo-plugin/tests/elements/{text,robots,serp,robotstxt,transfer}.test.ts, tests/elements/css.ts
|
||||
- ../sm-journal-plugin/content_descriptors_test.go
|
||||
- ../sm-demo-app/config/golem15.seo.yaml, seo_mount_test.go, seo_mcp_test.go
|
||||
modified:
|
||||
- scripts/check-phase32.sh
|
||||
- .planning/phases/32-seo-foundation/32-VALIDATION.md
|
||||
- ../sm-seo-plugin/go.mod, README.md, classes/redirect_graph.go, classes/issues.go, classes/robots.go, assets/src/elements/measure.ts, assets/dist/seo.js
|
||||
- ../sm-journal-plugin/go.mod, README.md, menu_item_types_test.go
|
||||
- ../sm-demo-app/go.mod, go.sum, go.work, .gitmodules, summer.yaml, plugins.gen.go, boot_test.go, DEPLOY.md, deploy/nginx/demo.summercms.io.conf, plugins/golem15/journal, plugins/golem15/seo
|
||||
|
||||
key-decisions:
|
||||
- "Release per Jakub's go-ahead: SummerCMS v0.5.1, sm-journal-plugin v0.2.5, sm-seo-plugin v0.1.0, all pushed with their branches; sm-demo-app's three commits pushed; nothing deployed"
|
||||
- "The additive gate compares with the newest tag that does not contain HEAD, so a run on the tagged release commit compares it with the previous release, not with itself"
|
||||
- "The demo Journal bump replaces the other session's uncommitted journal pointer drift on the same path (b129902, an ancestor of v0.2.5) with the v0.2.5 pointer; the oauthserver drift is left untouched"
|
||||
- "check-pins is proven on the committed demo tree (clean detached worktree), because the live tree carries another session's oauthserver drift"
|
||||
- "The optional app Journal bumps and per-plugin changelog posts were not named and are deferred"
|
||||
|
||||
patterns-established:
|
||||
- "Post-release gate runs pick the previous release as the additive baseline (git tag --no-contains HEAD)"
|
||||
|
||||
requirements-completed: [SC-5, SC-1, SC-2, SC-3, SC-4, Q-01, D-106, D-90, D-91, D-92, D-93, D-98, D-22, D-25, D-09]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Additive and compat gate stages: the v0.5.1 API surface keeps every v0.5.0 element (cabana +2, pact +87, signpost +8 lines, nothing removed or changed, no interface method added); consumers build and test unchanged"
|
||||
requirement: "D-106"
|
||||
verification:
|
||||
- kind: other
|
||||
ref: "bash scripts/check-phase32.sh --additive (release commit 15b0d0d vs v0.5.0); bash scripts/check-phase32.sh --self-test"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "bash scripts/check-phase32.sh --all (compat stage: 3 consumers tested, 20 siblings built)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "Framework unit matrices for form extensions, record events and content descriptors"
|
||||
requirement: "SC-5"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "go test ./modules/cabana ./modules/signpost (form_extensions_test.go, record_events_test.go, content_test.go)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "sm-seo-plugin class unit tests and element tests; Journal descriptor, journal-tag and translated-slug tests"
|
||||
requirement: "SC-5"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "go -C ../sm-seo-plugin test ./... (TestResolverPrecedence, TestRedirectGraph, TestNormalizeMatrix, TestRobotsValueRoundTrip, TestRobotsMatcherGoogleExamples, TestTemplates, TestCSV, TestOwnerResolution, TestIssues)"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "npm --prefix ../sm-seo-plugin run test (52 element tests)"
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: "go -C ../sm-journal-plugin test ./... (content_descriptors_test.go, menu_item_types_test.go)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "Releases tagged and pushed: SummerCMS v0.5.1, sm-journal-plugin v0.2.5, sm-seo-plugin v0.1.0"
|
||||
requirement: "Q-01"
|
||||
verification:
|
||||
- kind: other
|
||||
ref: "git ls-remote --tags origin v0.5.1 / v0.2.5 / v0.1.0 (aa6e0a5, 16d9326, 9cf0447)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D5
|
||||
description: "sm-demo-app mounts golem15.seo v0.1.0 with tagged requires; SEO tab and MCP catalog proven"
|
||||
requirement: "SC-4"
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "go -C ../sm-demo-app test -count=1 -tags summercms_mcp -run 'TestSEOToolsCatalog|TestGoModRequiresTags|TestSEOTabMounted|TestBootAllPlugins' . (Docker)"
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: "scripts/check-pins.sh in a clean worktree of 9451b31: check-pins: ok (17 modules)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D6
|
||||
description: "Full phase gate green with the demo mounted and no skips"
|
||||
requirement: "D-90"
|
||||
verification:
|
||||
- kind: other
|
||||
ref: "bash scripts/check-phase32.sh --all (exit 0, Phase 32 gate passed)"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D7
|
||||
description: "Changelog post for v0.5.1 on summercms.io reads well and says the right things to users"
|
||||
verification:
|
||||
- kind: other
|
||||
ref: "https://summercms.io/changelog/summercms-0-5-1 answers 200; API shows published at the tag date"
|
||||
status: pass
|
||||
human_judgment: true
|
||||
rationale: "Wording and emphasis of public release notes are an editorial call"
|
||||
|
||||
duration: 1h 25m
|
||||
completed: 2026-10-27
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 32 Plan 06: Unit tests, additive release gate and the v0.5.1 release Summary
|
||||
|
||||
**The phase is proven and released. An API-surface gate shows the framework change is strictly additive against v0.5.0, and a compat gate builds every sibling consumer unchanged. Unit tests cover the framework seams, the SEO plugin (Go and elements) and Journal. SummerCMS v0.5.1, sm-journal-plugin v0.2.5 and sm-seo-plugin v0.1.0 are tagged and pushed. sm-demo-app mounts golem15.seo v0.1.0 and is pushed, not deployed. The changelog post is at https://summercms.io/changelog/summercms-0-5-1.**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** about 1h 25m in two executor contexts (Tasks 1 to 3, then Task 5 after the Task 4 checkpoint)
|
||||
- **Started:** 2026-10-27T11:51Z (plan base 49502e8)
|
||||
- **Completed:** 2026-10-27T13:20Z
|
||||
- **Tasks:** 5 (4 executed, 1 decision checkpoint)
|
||||
- **Files modified:** 6 in this repository, 23 in sm-seo-plugin, 4 in sm-journal-plugin, 14 in sm-demo-app
|
||||
|
||||
## Task 4 answer (Jakub)
|
||||
|
||||
- **Decision:** release. Versions confirmed: v0.5.1, v0.2.5 and v0.1.0.
|
||||
- **Approved pushes:**
|
||||
- framework master and v0.5.1 (master carried 64 commits, including other sessions' work; accepted)
|
||||
- sm-journal-plugin main and v0.2.5
|
||||
- sm-seo-plugin main (first push) and v0.1.0
|
||||
- sm-demo-app master with three commits
|
||||
- **Changelog:** a post for v0.5.1.
|
||||
- **Not named:** the optional app Journal bumps. **Nothing deployed.**
|
||||
- **Gate:** the full run with the demo mounted and no test skips. The fixture is readable after the chown.
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- `check-phase32.sh` has two new stages:
|
||||
- **additive:** `scripts/apisurface` compares the exported API with the previous release and refuses removed or changed elements and methods added to existing interfaces. The self-test plants each case.
|
||||
- **compat:** sm-sitemap-plugin, sm-journal-plugin and sm-demo-app are tested; every other sibling that requires the framework is built.
|
||||
- **Unit tests:**
|
||||
- framework matrices for form extensions, record events and content descriptors
|
||||
- sm-seo-plugin classes (resolver, redirect graph, normalisation, robots value and matcher, templates, CSV, owner, issues) and 52 vitest element tests
|
||||
- Journal: descriptors, the journal-tag type and translated slugs
|
||||
- **Releases:** v0.5.1, v0.2.5 and v0.1.0 are tagged and pushed. Both plugins require v0.5.1.
|
||||
- **Demo:** sm-demo-app requires v0.5.1, bumps Journal to v0.2.5 and mounts golem15.seo v0.1.0 (the 32-05 patch, the submodule and go.work).
|
||||
- **Changelog:** v0.5.1 is announced.
|
||||
|
||||
## Task Commits
|
||||
|
||||
**summercms.go**
|
||||
1. **Task 1: additive and compat stages** - `2b300ec` (test)
|
||||
2. **Task 2: framework unit matrices** - `8c961f5` (test)
|
||||
3. **Task 3D: validation map** - `15b0d0d` (docs). This is the release commit, tagged v0.5.1.
|
||||
4. **Task 5 fix: additive baseline after tagging** - `a9a7f58` (fix). Local only, after the tag.
|
||||
|
||||
**sm-seo-plugin**
|
||||
- Task 3 fixes and refactors:
|
||||
- `e957c00` refactor: run the redirect simulation over a rule list
|
||||
- `79567b3` fix: a loop through the site's absolute URL lists each address once
|
||||
- `6d54fc7` refactor: build the issue report from loaded data
|
||||
- `9461c74` fix: the result preview truncates at the last word boundary
|
||||
- Task 3A: `9e45ddc` test: unit tests for the SEO classes
|
||||
- Task 3B: `dcfbdc0` test: element backstops
|
||||
- Task 5: `b19cd06` chore: require SummerCMS v0.5.1. Tagged v0.1.0.
|
||||
|
||||
**sm-journal-plugin**
|
||||
- Task 3C: `fea88f8` test: content descriptors, journal-tag type and translated slugs
|
||||
- Task 5: `f5a0394` chore: require SummerCMS v0.5.1. Tagged v0.2.5.
|
||||
|
||||
**sm-demo-app** (Task 5)
|
||||
- `11f64bf` chore: require SummerCMS v0.5.1 (go.mod, go.sum)
|
||||
- `11d485f` chore: bump journal to v0.2.5 (go.mod, go.sum, plugins/golem15/journal)
|
||||
- `9451b31` feat: mount golem15.seo v0.1.0 (13 paths, all from this plan)
|
||||
|
||||
**Plan metadata:** the commit that adds this SUMMARY (docs).
|
||||
|
||||
`commits: 4` is measured in this repository with `git rev-list --count 49502e8..HEAD` before this SUMMARY's commit. Sibling commits are listed above.
|
||||
|
||||
## Release steps (from 32-06-release-log.md)
|
||||
|
||||
- **Pre-checks:**
|
||||
- framework: newest tag v0.5.0; master was 64 ahead of origin/master and 0 behind.
|
||||
- admin/: only `admin/tests/form/FormView.test.ts` changed, so no dist rebuild was needed.
|
||||
- **Step 1, framework:**
|
||||
- `go vet` and `go test -short` green.
|
||||
- Annotated tag v0.5.1: tag object aa6e0a5 on commit 15b0d0d.
|
||||
- `git push origin master`: 223f87e..15b0d0d, fast-forward checked after `git fetch`.
|
||||
- `git push origin v0.5.1`; `ls-remote` confirms it.
|
||||
- **Step 2, sm-journal-plugin:**
|
||||
- `go get summercms@v0.5.1` with `GOWORK=off` and `GOPRIVATE`.
|
||||
- README dependency line updated to v0.5.1 (signpost is now a runtime dependency).
|
||||
- Build, vet and `test -short` green.
|
||||
- Commit f5a0394; tag v0.2.5 (tag object 16d9326).
|
||||
- Pushed main 7fc07d8..f5a0394 and the tag.
|
||||
- **Step 3, sm-seo-plugin:**
|
||||
- The same require, plus the README dependency line "SummerCMS v0.5.1 modules".
|
||||
- Build, vet and `test -short` green.
|
||||
- Commit b19cd06; tag v0.1.0 (tag object 9cf0447).
|
||||
- `git push -u origin main` (a new branch on the empty remote) and the tag.
|
||||
- **Step 4, sm-demo-app:**
|
||||
- Found at the start: ` M plugins/golem15/journal` and ` M plugins/golem15/oauthserver`.
|
||||
- Commit 11f64bf: require v0.5.1.
|
||||
- The journal submodule HEAD (b129902) is an ancestor of v0.2.5, so it was moved to v0.2.5. Commit 11d485f: only the v0.2.5 pointer was staged, and it replaces the foreign journal drift on that path.
|
||||
- Mount:
|
||||
- `git apply` the 32-05 patch
|
||||
- `git submodule add -b main` sm-seo-plugin, checked out at v0.1.0
|
||||
- go.work `use ./plugins/golem15/seo`
|
||||
- `go get sm-seo-plugin@v0.1.0` and `go mod tidy` (GOWORK=off)
|
||||
- `summer build` printed ✓ Built bin/demo
|
||||
- Build (plain and summercms_mcp), vet and `test -short` green. With Docker, TestBootAllPlugins, TestGoModRequiresTags, TestSEOToolsCatalog and TestSEOTabMounted pass.
|
||||
- Commit 9451b31.
|
||||
- check-pins: the live tree fails only on the foreign oauthserver drift. A clean worktree of 9451b31 prints `check-pins: ok (17 modules)`, and `GOWORK=off go build ./...` builds from the published tags (plain and mcp).
|
||||
- Pushed master 8fcdbdd..9451b31. Not deployed.
|
||||
- **Step 5, gate:** `check-phase32.sh --all` passes (details under Gate output).
|
||||
- **Step 6, changelog:**
|
||||
- `changelog-post.py source v0.5.1`, then the notes (## Highlights, ## Added).
|
||||
- `publish` returned post id 45: https://summercms.io/changelog/summercms-0-5-1. It is published at the tag date and the page answers 200.
|
||||
- The script read the token itself; it was never printed.
|
||||
- **Step 7, deferred items:** deferred-items.md is written.
|
||||
|
||||
## Gate output (step 5)
|
||||
|
||||
`bash scripts/check-phase32.sh --all` ran with Docker, the demo mounted, no `PHASE32_*` overrides and no test skips. It exited 0 with "Phase 32 gate passed".
|
||||
|
||||
- **Stages:** PASS for self-test, go, plugins (TestNoTideJournalFixtures included), consumers, admin, docs, marker, additive, compat and docker.
|
||||
- **compat:** sm-sitemap-plugin, sm-journal-plugin and sm-demo-app are tested. fonoteka.go, sm-bm-app, sm-grzybyfunkcjonalne-app and every sibling plugin are built.
|
||||
- **docker:** TestSEOTabMounted and TestSEOToolsCatalog pass in the demo.
|
||||
- **No failure lines:** no FAIL, `refuse:`, NOT MOUNTED or additive refusal.
|
||||
- **Additive baseline:** the additive line of that run compared v0.5.1 with itself, which led to fix a9a7f58. Re-run on the release commit, it compared against v0.5.0: cabana +2, pact +87, signpost +8 lines.
|
||||
|
||||
## Decisions Made
|
||||
|
||||
See `key-decisions` in the frontmatter.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Behaviour-neutral refactors so TestRedirectGraph and TestIssues run under -short**
|
||||
- **Found during:** Task 3A
|
||||
- **Fix:** the redirect simulation runs over a rule list, and the issue report is built from loaded data.
|
||||
- **Commits:** sm-seo-plugin e957c00, 6d54fc7
|
||||
|
||||
**2. [Rule 1 - Bug] A loop notice listed an address twice**
|
||||
- **Found during:** Task 3A
|
||||
- **Fix:** a loop through the site's absolute URL lists each address once.
|
||||
- **Commit:** sm-seo-plugin 79567b3
|
||||
|
||||
**3. [Rule 1 - Bug] The result preview did not truncate per UI-SPEC E-1**
|
||||
- **Found during:** Task 3B
|
||||
- **Fix:** the preview truncates at the last word boundary plus " …", and the dist bundle was rebuilt.
|
||||
- **Commit:** sm-seo-plugin 9461c74
|
||||
|
||||
**4. [Rule 3 - Blocking] Extra test support files**
|
||||
- **Found during:** Task 3
|
||||
- **Fix:** classes/helpers_test.go and tests/elements/css.ts were added, and gorm.io/driver/postgres became a direct require in sm-seo-plugin's go.mod.
|
||||
- **Commits:** 9e45ddc, dcfbdc0
|
||||
|
||||
**5. [Rule 3 - Blocking] No layout in happy-dom**
|
||||
- **Found during:** Task 3B
|
||||
- **Fix:** the 320 and 360 px element rows check the stylesheet's layout contract.
|
||||
- **Commit:** dcfbdc0
|
||||
|
||||
**6. [Rule 3 - Blocking] The compat stage has to read other repositories without touching their trees**
|
||||
- **Found during:** Task 1
|
||||
- **Fix:** it reads them through temporary-index snapshots or detached worktrees and builds in a symlinked scratch sibling layout. There is a new PHASE32_SKIP_TESTS knob.
|
||||
- **Commit:** 2b300ec
|
||||
|
||||
**7. No separate RED commits**
|
||||
- **Found during:** Tasks 2 and 3
|
||||
- **Reason:** the green-at-every-commit rule in CLAUDE.md.
|
||||
|
||||
**8. Element tests: 52, against the plan's minimum of 20.**
|
||||
|
||||
**9. [Rule 1 - Bug] The additive stage compared the release with itself once HEAD was tagged**
|
||||
- **Found during:** Task 5, step 5
|
||||
- **Issue:** `last_tag` picked the newest tag, which was v0.5.1 on HEAD.
|
||||
- **Fix:** `git tag --sort=-v:refname --no-contains HEAD`. The re-run against v0.5.0 passes, and so does `--self-test`.
|
||||
- **Commit:** a9a7f58 (local; it is after the pushed tag and was not pushed)
|
||||
|
||||
**10. [Rule 3 - Blocking] The live demo tree fails check-pins**
|
||||
- **Found during:** Task 5, step 4
|
||||
- **Issue:** another session's uncommitted oauthserver drift (b6a9586 against v0.1.2, 8bbec72).
|
||||
- **Fix:** none in the live tree; the drift was left alone. check-pins is proven on a clean detached worktree of the pushed commit.
|
||||
|
||||
**11. [Rule 2 - Docs] Journal README dependency line**
|
||||
- **Found during:** Task 5, step 2
|
||||
- **Issue:** the plan named only the sm-seo-plugin README.
|
||||
- **Fix:** the Journal README now names SummerCMS v0.5.1, and signpost moved from "in tests" to a runtime dependency (CLAUDE.md documentation rule).
|
||||
- **Commit:** f5a0394
|
||||
|
||||
**12. [Rule 3 - Blocking] The demo's TestSEO* tests skip under -short (they need Docker)**
|
||||
- **Fix:** they were run without -short with Docker. Both pass, tagged and untagged.
|
||||
|
||||
**13. `go mod tidy` in the demo**
|
||||
- **Why:** to make sm-seo-plugin a direct require.
|
||||
- **Effect:** go.sum gained grobotstxt's test-dependency checksums and dropped the obsolete v0.5.0 and v0.2.3 lines.
|
||||
- **Commit:** 9451b31
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 13 (5 Rule 1, 1 Rule 2, 5 Rule 3, 2 notes). **Impact:** the fixes are bugs in plugin code or in the gate, plus test scaffolding. No scope creep and no API change.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- **g15office comment not posted.** This executor has no g15office tool. The orchestrator posts the release comment on Phase 32's milestone task `8gldeain` (`.planning/G15OFFICE.md`).
|
||||
- **Retracted dependency in the demo.** sm-demo-app pins `github.com/gabriel-vasile/mimetype v1.4.15`, which upstream has retracted. This was there before the plan; it is recorded in deferred-items.md.
|
||||
|
||||
## Deferred (deferred-items.md)
|
||||
|
||||
- Journal bumps in sm-grzybyfunkcjonalne-app (with `golem15.journal.tag_pages: false`) and sm-summercmsio-app. Not named in the go-ahead.
|
||||
- Changelog posts of their own for sm-journal-plugin v0.2.5 and sm-seo-plugin v0.1.0.
|
||||
- Deploying the demo.
|
||||
- The demo's oauthserver drift (another session's) and the retracted mimetype pin.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Phase 33 can build on the tagged v0.5.1 seams and on sm-seo-plugin v0.1.0.
|
||||
- The demo is pushed but not deployed. Deploy per `../sm-demo-app/DEPLOY.md` when Jakub says so.
|
||||
- Local commits after the release: a9a7f58 and this SUMMARY's commit. They go out with the next framework push.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- Files: scripts/apisurface/main.go, modules/cabana/form_extensions_test.go, modules/cabana/record_events_test.go, modules/signpost/content_test.go, 32-06-release-log.md and deferred-items.md exist.
|
||||
- Commits: 2b300ec, 8c961f5, 15b0d0d and a9a7f58 are in this repository. e957c00, 79567b3, 6d54fc7, 9e45ddc, 9461c74, dcfbdc0 and b19cd06 are in sm-seo-plugin; fea88f8 and f5a0394 in sm-journal-plugin; 11f64bf, 11d485f and 9451b31 in sm-demo-app.
|
||||
- Remote tags: v0.5.1 (aa6e0a5), v0.2.5 (16d9326) and v0.1.0 (9cf0447).
|
||||
- Changelog URL answers 200.
|
||||
|
||||
---
|
||||
*Phase: 32-seo-foundation*
|
||||
*Completed: 2026-10-27*
|
||||
29
.planning/phases/32-seo-foundation/32-06-release-log.md
Normal file
29
.planning/phases/32-seo-foundation/32-06-release-log.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Plan 32-06 release log
|
||||
|
||||
Resume record of Task 5 (one-way). A resumed run confirms each `step <n> done` line and skips it: no tag is created twice, no push is forced, the changelog is posted once.
|
||||
|
||||
## Task 4 answer (Jakub, 2026-10-27)
|
||||
|
||||
- **Decision:** release (full Task 5).
|
||||
- **Versions:** framework `v0.5.1`, sm-journal-plugin `v0.2.5`, sm-seo-plugin `v0.1.0`.
|
||||
- **Pushes approved:** framework master + v0.5.1 (master carries 64 commits incl. other sessions' work, accepted); sm-journal-plugin main + v0.2.5; sm-seo-plugin main (first push, `-u`) + v0.1.0; sm-demo-app master (three commits: framework pin, Journal bump, golem15.seo mount).
|
||||
- **Changelog:** post v0.5.1 on summercms.io.
|
||||
- **Not named:** optional Journal bumps in sm-grzybyfunkcjonalne-app and sm-summercmsio-app (deferred).
|
||||
- **Nothing is deployed.**
|
||||
- **Gate:** full `check-phase32.sh --all` with the demo mounted, no PHASE32_ALLOW_UNMOUNTED, no TestNoTideJournalFixtures skip (fixture readable after the chown).
|
||||
|
||||
## Pre-checks
|
||||
|
||||
- framework: `git fetch --tags origin`; newest tag v0.5.0; master is 64 ahead, 0 behind origin/master (fast-forward).
|
||||
- admin/: only `admin/tests/form/FormView.test.ts` changed since v0.5.0; the embedded dist is unaffected, no rebuild.
|
||||
|
||||
## Steps
|
||||
|
||||
- step 1 done: framework `go vet ./...` + `go test -short ./...` green; annotated tag v0.5.1 (tag object aa6e0a5, commit 15b0d0d) created; `git push origin master` 223f87e..15b0d0d (fast-forward checked after `git fetch origin`); `git push origin v0.5.1` new tag; `git ls-remote --tags origin v0.5.1` prints aa6e0a5.
|
||||
- step 2 done: sm-journal-plugin `GOWORK=off GOPRIVATE=git.golem15.com/* go get git.golem15.com/golem15/summercms@v0.5.1` (v0.5.0 => v0.5.1; go.sum unchanged, the module's replace points at ../summercms.go), README dependency line v0.5.1 (signpost now a runtime dependency); `GOWORK=off go build ./... && go vet ./... && go test -short ./...` green; commit f5a0394 `chore: require SummerCMS v0.5.1` (go.mod, README.md); annotated tag v0.2.5 (tag object 16d9326, commit f5a0394); `git push origin main` 7fc07d8..f5a0394 (fast-forward checked); `git push origin v0.2.5` new tag; ls-remote prints 16d9326.
|
||||
- step 3 done: sm-seo-plugin `GOWORK=off GOPRIVATE=git.golem15.com/* go get git.golem15.com/golem15/summercms@v0.5.1` (v0.5.0 => v0.5.1; go.sum unchanged, replace to ../summercms.go), README dependency line "SummerCMS v0.5.1 modules"; `GOWORK=off go build ./... && go vet ./... && go test -short ./...` green; commit b19cd06 `chore: require SummerCMS v0.5.1` (go.mod, README.md); annotated tag v0.1.0 (tag object 9cf0447, commit b19cd06); `git push -u origin main` new branch (first push, origin was empty); `git push origin v0.1.0` new tag; ls-remote prints main b19cd06 and v0.1.0 9cf0447.
|
||||
- step 4 done: sm-demo-app (pre-existing drift ` M plugins/golem15/journal` (4ab94da recorded, b1299021 checked out) and ` M plugins/golem15/oauthserver` (8bbec72 recorded, b6a9586 checked out) found at start). Commit 11f64bf `chore: require SummerCMS v0.5.1` (go.mod, go.sum; build, mcp build, vet, test -short green). Journal submodule HEAD b129902 confirmed an ancestor of v0.2.5, checked out at v0.2.5 (f5a0394); commit 11d485f `chore: bump journal to v0.2.5` (go.mod, go.sum, plugins/golem15/journal: 4ab94da -> f5a0394; this pointer replaces the other session's journal drift on the same path, only the intended v0.2.5 pointer staged). Mount: `git apply 32-05-demo-mount.patch`, `git submodule add -b main git@git.golem15.com:golem15/sm-seo-plugin.git plugins/golem15/seo` checked out at v0.1.0 (b19cd06), `./plugins/golem15/seo` in go.work, `GOWORK=off go get sm-seo-plugin@v0.1.0` + `GOWORK=off go mod tidy` (seo a direct require), `go run ../summercms.go/cmd/summer build` (✓ Built bin/demo; plugins.gen.go as in the patch, main.go unchanged); `go build ./...`, `go build -tags summercms_mcp ./...`, `go vet ./...`, `go test -short ./...` green; Docker runs: TestBootAllPlugins, TestGoModRequiresTags, TestSEOToolsCatalog, TestSEOTabMounted PASS (tagged), TestBootAllPlugins, TestSEOTabMounted PASS (untagged); commit 9451b31 `feat: mount golem15.seo v0.1.0` (13 paths, this plan's only). `scripts/check-pins.sh` in the live tree fails only on the other session's oauthserver drift; in a detached worktree of 9451b31 with `git submodule update --init plugins/` it prints `check-pins: ok (17 modules)`, and `GOWORK=off go build ./...` (plain and summercms_mcp) builds from the published tags; scratch worktree removed. `git push origin master` 8fcdbdd..9451b31 (fast-forward checked). Not deployed. ` M plugins/golem15/oauthserver` left as found.
|
||||
- step 6a: `scripts/changelog-post.py source v0.5.1` (from ../sm-summercmsio-app) printed the tag message and 64 commit subjects since v0.5.0; user-facing notes written to a scratch file (## Highlights, ## Added; no Changed/Fixed entries in this release).
|
||||
- step 5 done: `bash scripts/check-phase32.sh --all` (no PHASE32_* overrides, Docker, demo mounted at 9451b31, no test skips) exit 0, "Phase 32 gate passed": PASS self-test, go, plugins (TestNoTideJournalFixtures included), consumers, admin, docs, marker, additive, compat (sm-sitemap-plugin, sm-journal-plugin, sm-demo-app tested; every other sibling built), docker (TestSEOTabMounted, TestSEOToolsCatalog in sm-demo-app). No FAIL, refuse:, NOT MOUNTED or additive refusal lines. The additive stage of that run compared v0.5.1 with itself (last_tag picked the tag on HEAD); fixed in a9a7f58 `fix(32-06): the additive stage compares with the previous release once HEAD is tagged` (last_tag uses `--no-contains HEAD`); `check-phase32.sh --additive` on the release commit then compared with v0.5.0: cabana +2, pact +87, signpost +8 lines, nothing removed or changed, no interface method added; `--self-test` passes. a9a7f58 is local (after the tag, not pushed).
|
||||
- step 6 done: `scripts/changelog-post.py publish v0.5.1 <notes> --excerpt "Plugins can extend each other's admin forms, react to record writes and map URLs to records. Strictly additive."` posted id=45, https://summercms.io/changelog/summercms-0-5-1 (title "SummerCMS 0.5.1", published_at 2026-10-27T13:00:42Z, the tag's date). Token read by the script from ~/.config/summercms/journal-token; never printed or copied.
|
||||
- step 7 done: deferred-items.md lists the unnamed app Journal bumps (sm-grzybyfunkcjonalne-app, sm-summercmsio-app), plugin release posts, the deploy, the demo's oauthserver drift and the retracted mimetype pin. Nothing deployed.
|
||||
278
.planning/phases/32-seo-foundation/32-REVIEW-DISPOSITION.md
Normal file
278
.planning/phases/32-seo-foundation/32-REVIEW-DISPOSITION.md
Normal file
@@ -0,0 +1,278 @@
|
||||
---
|
||||
phase: 32
|
||||
review: 32-REVIEW.md
|
||||
titles: json
|
||||
findings:
|
||||
- id: CR-01
|
||||
severity: critical
|
||||
disposition: fixed
|
||||
title: "[CR-A01] `required: true` on a form extension field makes every save of the host form fail (also for administrators who cannot see the extension)"
|
||||
- id: CR-02
|
||||
severity: critical
|
||||
disposition: fixed
|
||||
title: "[CR-A02] Plugin field-type upload route ignores the extension's Permissions/Visible, so administrators without them can run its `Upload`"
|
||||
- id: WR-01
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-A01] Admin writes that change or delete records fire no record event (hasMany link/unlink, deferred child unlink, deferred child commit)"
|
||||
- id: WR-02
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-A02] `RecordSaved.Locale` is the admin's UI language or the raw `Accept-Language` header, not a content locale, and reorder reports something different"
|
||||
- id: WR-03
|
||||
severity: warning
|
||||
disposition: skipped
|
||||
title: "[WR-A03] A failing extension `Load` (or plugin-type `Load`) after a successful save rolls back the whole save"
|
||||
- id: WR-04
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-A04] Journal API writes can commit changes (including a slug) and fire no RecordSaved"
|
||||
- id: WR-05
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-A05] Journal `postSavedEvent` reports `Old: nil` for a translated `content_html` that existed, because the body is mutated between the snapshot and the event"
|
||||
- id: WR-06
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-A06] Tags auto-created by the Journal post API fire no RecordSaved although `journal-tag` is now a content type"
|
||||
- id: WR-07
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-A07] `Hide` leaves the owner's relation-manager and partial endpoints of a hidden field reachable"
|
||||
- id: IN-01
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-A01] Dead check in `BindWritableFields`"
|
||||
- id: IN-02
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-A02] Scoped API tokens never see an extension that declares no Permissions, and their posted values are dropped silently"
|
||||
- id: IN-03
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-A03] `resolveExtensionLocales` wraps a nil error"
|
||||
- id: IN-04
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-A04] `tab: default` on an extension field is refused although `default` names the default tab elsewhere"
|
||||
- id: IN-05
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-A05] Journal `requestLocale` drops the region, so translated slugs in region-coded locales never match"
|
||||
- id: IN-06
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-A06] The extension's client assets are served to every administrator of the host form"
|
||||
- id: CR-03
|
||||
severity: critical
|
||||
disposition: fixed
|
||||
title: "[CR-B01] Exact redirects with a trailing slash or upper-case query characters never match at runtime"
|
||||
- id: WR-08
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B01] A query-specific exact redirect is silently shadowed by the path-only rule"
|
||||
- id: WR-09
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B02] `AddressChanged` writes redirects without validation or the loop simulation"
|
||||
- id: WR-10
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B03] The save-time loop check races with concurrent writes"
|
||||
- id: WR-11
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B04] Undo is not idempotent under concurrent requests"
|
||||
- id: WR-12
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B05] Public resolve and 404 report answer 500 for NUL or invalid UTF-8 paths"
|
||||
- id: WR-13
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B06] The runtime cycle log grows without bound and is keyed by attacker-controlled URLs"
|
||||
- id: WR-14
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B07] Export with a large `page` panics the handler"
|
||||
- id: WR-15
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B08] Public throttle buckets key on the SSR server's IP, capping the whole site"
|
||||
- id: WR-16
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B09] Social image values bypass validation on every non-admin write path"
|
||||
- id: WR-17
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B10] Invalid redirect status, match or query values are silently coerced on API, MCP and import"
|
||||
- id: WR-18
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B11] `set_url_seo`, batch `set_seo` and the records import accept any locale"
|
||||
- id: WR-19
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-B12] Entry generation overwrites `entry.URL`, which can swallow an address change and its 301"
|
||||
- id: IN-07
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B01] The `regexCache` / `globCache` maps are never evicted"
|
||||
- id: IN-08
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B02] CSV `unescapeCell` changes legitimate values that start with an apostrophe"
|
||||
- id: IN-09
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B03] The transfer token has no expiry or user binding, and the fallback key is per process"
|
||||
- id: IN-10
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B04] Uniqueness checks swallow query errors inside the save transaction"
|
||||
- id: IN-11
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B05] `RenderTemplate` trims separators that belong to the content"
|
||||
- id: IN-12
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B06] Body caps do not account for JSON escaping"
|
||||
- id: IN-13
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B07] `/robots.txt` serves allow-all without the noindex header when the service is nil, even outside production"
|
||||
- id: IN-14
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-B08] Self canonical and `url` are built from the decoded path"
|
||||
- id: CR-04
|
||||
severity: critical
|
||||
disposition: fixed
|
||||
title: "[CR-C01] The SERP preview and the robots.txt tester deadlock: their first action is dropped by the host and `inflight` is never cleared"
|
||||
- id: WR-20
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-C01] The social image preview accepts `/\\host/...`, so the admin can load an image from an attacker's host"
|
||||
- id: WR-21
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-C02] The CSV export/import round trip changes cells that already start with an apostrophe followed by a formula character"
|
||||
- id: WR-22
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-C03] The 404 \"Open/Resolved\" filter and the redirect \"Chains\" filter disagree with the runtime matcher"
|
||||
- id: WR-23
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-C04] The URL rule address is uncapped but sits in a btree UNIQUE index, so long values return 500 instead of 422"
|
||||
- id: WR-24
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-C05] The robots element's grammar drifts from the Go grammar, and an unparseable value is silently wiped on the next edit"
|
||||
- id: WR-25
|
||||
severity: warning
|
||||
disposition: fixed
|
||||
title: "[WR-C06] The element tests never exercise the host protocol; the tester and the image element have no tests"
|
||||
- id: IN-15
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C01] The regex length refusal puts an untranslated English phrase into the Polish UI"
|
||||
- id: IN-16
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C02] A migration comment is stale"
|
||||
- id: IN-17
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C03] The SERP preview's template rendering is not single-pass like the Go renderer"
|
||||
- id: IN-18
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C04] `plural()` can throw on an unusual `ui-locale`"
|
||||
- id: IN-19
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C05] Two test names do not describe what they assert"
|
||||
- id: IN-20
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C06] The inner controls' accessible name is the machine field name"
|
||||
- id: IN-21
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C07] The README test instructions skip the vitest suite, and the test script hides an empty run"
|
||||
- id: IN-22
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C08] Three partials are maintained twice"
|
||||
- id: IN-23
|
||||
severity: info
|
||||
disposition: open
|
||||
title: "[IN-C09] The `disabled` branches in the widget elements are dead, and would be broken if reached"
|
||||
open: 23
|
||||
total: 52
|
||||
recorded: 2026-10-27T14:47:23.755Z
|
||||
---
|
||||
|
||||
# Phase 32: Code Review Disposition
|
||||
|
||||
| Finding | Severity | Disposition | Source |
|
||||
|---------|----------|-------------|--------|
|
||||
| CR-01 | critical | fixed | 32-REVIEW-FIX.md |
|
||||
| CR-02 | critical | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-01 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-02 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-03 | warning | skipped | 32-REVIEW-FIX.md |
|
||||
| WR-04 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-05 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-06 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-07 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| IN-01 | info | open | - |
|
||||
| IN-02 | info | open | - |
|
||||
| IN-03 | info | open | - |
|
||||
| IN-04 | info | open | - |
|
||||
| IN-05 | info | open | - |
|
||||
| IN-06 | info | open | - |
|
||||
| CR-03 | critical | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-08 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-09 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-10 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-11 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-12 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-13 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-14 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-15 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-16 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-17 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-18 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-19 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| IN-07 | info | open | - |
|
||||
| IN-08 | info | open | - |
|
||||
| IN-09 | info | open | - |
|
||||
| IN-10 | info | open | - |
|
||||
| IN-11 | info | open | - |
|
||||
| IN-12 | info | open | - |
|
||||
| IN-13 | info | open | - |
|
||||
| IN-14 | info | open | - |
|
||||
| CR-04 | critical | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-20 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-21 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-22 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-23 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-24 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| WR-25 | warning | fixed | 32-REVIEW-FIX.md |
|
||||
| IN-15 | info | open | - |
|
||||
| IN-16 | info | open | - |
|
||||
| IN-17 | info | open | - |
|
||||
| IN-18 | info | open | - |
|
||||
| IN-19 | info | open | - |
|
||||
| IN-20 | info | open | - |
|
||||
| IN-21 | info | open | - |
|
||||
| IN-22 | info | open | - |
|
||||
| IN-23 | info | open | - |
|
||||
|
||||
Dispositions: `open` (recorded, not yet triaged), `fixed`, `skipped`, `deferred`.
|
||||
Set `deferred` by hand and put the reason in the Source cell; both are preserved. A `|` in the reason is kept as prose and escaped on the next run.
|
||||
Re-running the gate keeps every row it can. A row the current review no longer reports is kept and its Source cell flagged, so a finding does not leave this record silently. ONE exception: when a finding id is REUSED by a different finding, the earlier decision cannot keep a row — the id is taken — and it is dropped. A RECORDED decision (anything but `open`) is named on the console when that happens; a row still at `open` is replaced silently, because `open` records no decision to lose.
|
||||
496
.planning/phases/32-seo-foundation/32-REVIEW-FIX.md
Normal file
496
.planning/phases/32-seo-foundation/32-REVIEW-FIX.md
Normal file
@@ -0,0 +1,496 @@
|
||||
---
|
||||
phase: 32-seo-foundation
|
||||
fixed_at: 2026-10-27T14:47:00Z
|
||||
review_path: /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32-seo-foundation/32-REVIEW.md
|
||||
iteration: 1
|
||||
findings_in_scope: 29
|
||||
fixed: 28
|
||||
skipped: 1
|
||||
status: partial
|
||||
---
|
||||
|
||||
# Phase 32: Code Review Fix Report
|
||||
|
||||
Two fixer lanes ran in parallel on disjoint repositories. CR-04 was split into a framework half (WidgetField.vue element ordering) and a plugin half (element action queue with dropped-action retry); both are fixed.
|
||||
|
||||
## Fixed Issues
|
||||
|
||||
### CR-01: [CR-A01] `required: true` on a form extension field makes every save of the host form fail (also for administrators who cannot see the extension)
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Repo:** summercms.go
|
||||
**Commit:** 676ca53
|
||||
**Files modified:** `modules/cabana/crud.go`, `modules/cabana/form_extensions.go`, `modules/cabana/form_extensions_postgres_test.go`, `docs/backend/admin-controllers.md`
|
||||
**Applied fix:**
|
||||
- `mergedRules` skips extension fields, so the owner's model never gets a rule for them.
|
||||
- `liftExtensionValues` checks `required` on the lifted value, and only for visible extensions:
|
||||
- On create, the value must be sent and not blank. Blank means null or whitespace; for a translatable field it means the default locale's text.
|
||||
- On update, the value is checked only when it is sent.
|
||||
- New Postgres test `TestFormExtensionRequired` covers both cases:
|
||||
- An administrator who sees the extension gets a 422 when the value is missing, blank or null, a 201 when it is filled, and a 200 on a partial update.
|
||||
- An administrator who does not see the extension can create and update freely.
|
||||
- Docs bullet added.
|
||||
|
||||
### CR-02: [CR-A02] Plugin field-type upload route ignores the extension's Permissions/Visible, so administrators without them can run its `Upload`
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Repo:** summercms.go
|
||||
**Commit:** 5471b66
|
||||
**Files modified:** `modules/cabana/field_type_upload.go`, `modules/cabana/form_extensions_postgres_test.go`, `docs/backend/admin-controllers.md`
|
||||
**Applied fix:** `fieldUpload` answers 404 when the field belongs to an extension that `extensionVisible` refuses. New Postgres test `TestFormExtensionUpload`:
|
||||
- A visible upload gets a 201 on both create (id 0) and update.
|
||||
- An administrator without the extension's permission gets a 404 on both, and `Upload` never runs.
|
||||
|
||||
The docs now say the extension's "field type uploads" answer 404 too. I found no other route that resolves an extension field by name without a visibility check.
|
||||
|
||||
### CR-04: [CR-C01] The SERP preview and the robots.txt tester deadlock: their first action is dropped by the host and `inflight` is never cleared
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed (framework half only; the sm-seo-plugin element changes belong to the other fixer)
|
||||
**Repo:** summercms.go
|
||||
**Commit:** d660cd0
|
||||
**Files modified:**
|
||||
- `admin/src/components/form/fields/WidgetField.vue`
|
||||
- `admin/tests/form/WidgetField.test.ts`
|
||||
- `docs/backend/partials-and-widgets.md`
|
||||
- `modules/boardwalk/dist/index.html`
|
||||
- `modules/boardwalk/dist/assets/index-*.js` and `editor-*.js` (renamed by the rebuild)
|
||||
|
||||
**Applied fix:**
|
||||
- `element = created` now runs before `mountPoint.value.append(created)`.
|
||||
- New vitest case (`an action from connectedCallback (CR-04)`) mounts attached to the document. It uses an element that dispatches `summer-action` with a payload from `connectedCallback`, then checks that the POST is sent with that payload, that `busy` is set and then cleared, and that `summer-result` is dispatched. I confirmed the case fails on the old ordering.
|
||||
- Dist rebuilt and committed; `check-admin-dist.sh` passes.
|
||||
- Docs note that an action dispatched from `connectedCallback` is taken, and that one dispatched while `busy` is set is dropped.
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed (plugin half; `WidgetField.vue` was not touched, as instructed)
|
||||
**Commit:** 3ecbd1f
|
||||
**Files:** `assets/src/elements/actions.ts` (new), `serp.ts`, `robotstester.ts`, `labels.ts`, `assets/dist/seo.js`, `tests/elements/host.ts` (new), `tests/elements/serp.test.ts`, `tests/elements/robotstester.test.ts` (new)
|
||||
**Applied fix:** Both elements now share a new `ActionQueue`:
|
||||
- **Drop detection:** after `summer-action` is dispatched, a missing `busy` attribute means the host dropped the action. `inflight` is cleared and the payload is retried once on the next task.
|
||||
- **Second drop:** reported as a failure. The SERP preview shows `contextFailed`; the tester shows a new `testFailed` label (en/pl).
|
||||
- **First request:** `{op:'context'}` is sent on a microtask after `connectedCallback`.
|
||||
- **Disconnect:** clears the request in flight and any pending retry. On reconnect the context is requested again, or the duplicate check is re-armed.
|
||||
|
||||
**Tests:**
|
||||
- `tests/elements/host.ts` is a fake of `WidgetField.onAction`. It sets `busy` synchronously, settles asynchronously, sets `state=error` on failure and removes `busy`. It supports both wiring orders (`append-first` is the v0.5.1 host), dropping N actions, and an unwired host.
|
||||
- The SERP and tester suites cover:
|
||||
- the append-first host;
|
||||
- a dropped retry;
|
||||
- a host that never takes the action;
|
||||
- a queue behind `busy`;
|
||||
- `state=error` unblocking the next request;
|
||||
- a disconnect while a request is in flight.
|
||||
- Against the old `serp.ts`, 6 of the 7 new SERP host tests fail.
|
||||
|
||||
### WR-01: [WR-A01] Admin writes that change or delete records fire no record event (hasMany link/unlink, deferred child unlink, deferred child commit)
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Repo:** summercms.go
|
||||
**Commit:** 468af06
|
||||
**Files modified:**
|
||||
- `modules/cabana/relation.go`
|
||||
- `modules/cabana/deferred.go`
|
||||
- `modules/cabana/crud.go`
|
||||
- `modules/cabana/http.go`
|
||||
- `modules/cabana/relation_child.go`
|
||||
- `modules/cabana/record_events_postgres_test.go`
|
||||
- `modules/cabana/README.md`
|
||||
- `docs/backend/admin-controllers.md`
|
||||
|
||||
**Applied fix:**
|
||||
- New `RelationService.saveLinkedChild`: snapshot, mutate, `Save`, then `recordChanges` and `emitChildSaved`. It is used by:
|
||||
- hasMany `linkRelated` and `unlinkRelated`;
|
||||
- the deferred commit's attach of children created in the session (`applyRelationBinding`).
|
||||
- `unlinkDeferred` fires `RecordDeleted` after it deletes a child the session created.
|
||||
- `CRUDService` gains an unexported `reg *Registry` field, set in `crud()`, so the deferred commit's `RelationService` can name the child's controller. It also now carries `app`. The change is additive and unexported.
|
||||
- New subtests `hasMany link and unlink` and `deferred children` in `TestRecordEvents`.
|
||||
- README and docs list the new event sources.
|
||||
|
||||
### WR-02: [WR-A02] `RecordSaved.Locale` is the admin's UI language or the raw `Accept-Language` header, not a content locale, and reorder reports something different
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed (requires human verification of the chosen meaning)
|
||||
**Repo:** summercms.go
|
||||
**Commit:** 1583651
|
||||
**Files modified:**
|
||||
- `modules/cabana/record_events.go`
|
||||
- `modules/cabana/record_events_test.go`
|
||||
- `modules/cabana/relation_child.go`
|
||||
- `modules/cabana/reorder.go`
|
||||
- `modules/pact/record_events.go`
|
||||
- `modules/pact/README.md`
|
||||
- `docs/plugins/extending.md`
|
||||
|
||||
**Applied fix:**
|
||||
- New `eventLocale(ctx)` returns `primaryLanguage(towel.Locale)`. Admin saves, child writes and reorder now all report it, so a raw header like `pl-PL,pl;q=0.9` becomes `pl-PL`, and reorder no longer reports a different, defaulted code.
|
||||
- The pact doc now defines `Locale` as the primary tag of the request locale. It states that an admin save writes the row in the default content locale and that per-locale work should key on `RecordChange.Locale`.
|
||||
- New unit test `TestRecordEventLocale`.
|
||||
|
||||
I deliberately did not take the reviewer's alternative of switching `Locale` to the default content locale: that changes a field's meaning inside a patch release. No consumer reads `ev.Locale` today; I checked sm-seo-plugin, sm-sitemap-plugin and sm-journal-plugin. A human should confirm that "request locale, normalised" is the meaning we want.
|
||||
|
||||
### WR-04: [WR-A04] Journal API writes can commit changes (including a slug) and fire no RecordSaved
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Repo:** sm-journal-plugin
|
||||
**Commit:** 62c75b1
|
||||
**Files modified:** `controllers/api/posts.go`, `controllers/api/record_events.go`, `record_events_test.go`, `README.md`
|
||||
**Applied fix:**
|
||||
- `Store` and `Update` run `Create`/`Save`, `applyPostAssocs` and `loadPostAssocs` in one `lagoon.Transaction`, with `cabana.EmitRecordSaved(ctx, app, tx, ...)` inside it. The event now follows the commit, and a failure rolls back the row.
|
||||
- The site-cache purge still runs after the commit.
|
||||
- New test step: a PUT with a new slug and an invalid `tags` value returns 500, fires no event and leaves the slug unchanged. It fails without the fix: the slug was `api-lost`.
|
||||
- README updated.
|
||||
|
||||
### WR-05: [WR-A05] Journal `postSavedEvent` reports `Old: nil` for a translated `content_html` that existed, because the body is mutated between the snapshot and the event
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Repo:** sm-journal-plugin
|
||||
**Commit:** 7a03640
|
||||
**Files modified:** `controllers/api/record_events.go`, `record_events_test.go`
|
||||
**Applied fix:**
|
||||
- `submittedTranslations` lists `content_html` whenever a translation sends a non-blank `content`. This mirrors `classes.FormatTranslation`, so the snapshot and the event cover the same fields whether or not the body has been mutated yet.
|
||||
- New test step: updating a pl `content` reports the pl `content_html` change with the old HTML as `Old`. It failed before the fix, with `Old` nil.
|
||||
|
||||
### WR-06: [WR-A06] Tags auto-created by the Journal post API fire no RecordSaved although `journal-tag` is now a content type
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Repo:** sm-journal-plugin
|
||||
**Commit:** a6fc7cd
|
||||
**Files modified:** `controllers/api/posts.go`, `controllers/api/posts_helpers.go`, `controllers/api/record_events.go`, `record_events_test.go`, `README.md`
|
||||
**Applied fix:**
|
||||
- `resolveTagIDs` and `applyPostAssocs` now return the tags created by name. These are unexported signature changes.
|
||||
- The handlers emit `tagSavedEvent` (`Created`, with name and slug changes) for each new tag inside the post write's transaction.
|
||||
- New test step: a PUT with a new tag name fires two events, the post and a `journal-tag` `Created`; reusing that tag fires only the post event.
|
||||
- README updated.
|
||||
|
||||
### WR-07: [WR-A07] `Hide` leaves the owner's relation-manager and partial endpoints of a hidden field reachable
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Repo:** summercms.go
|
||||
**Commit:** 0e187cf
|
||||
**Files modified:** `modules/cabana/form_extensions.go`, `modules/cabana/form_extensions_smoke_test.go`, `modules/pact/capabilities.go`, `docs/backend/admin-controllers.md`
|
||||
**Applied fix:**
|
||||
- `dropHiddenFields` now receives the owner's original field list and works on copies of the maps. It drops:
|
||||
- the relation whose `fieldName` is hidden. This closes the panel, link, unlink, child CRUD and deferred-commit routes, because `relationOf` and `commitDeferred` read `cc.Relations`.
|
||||
- a hidden partial field's path, from `formPartials` and `partials`. A path that is still used by the list header partial, the preview header partial or another owner partial field keeps rendering.
|
||||
- New smoke test `TestFormExtensionHideEndpoints` checks that `relationOf` refuses the hidden relation-manager relation and that the hidden partial answers 404. With no `Hide`, both still work. It fails without the fix.
|
||||
- The pact `Hide` doc and the docs updated.
|
||||
|
||||
### CR-03: [CR-B01] Exact redirects with a trailing slash or upper-case query characters never match at runtime
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** 2d81c26
|
||||
**Files:** `updates/202610280001_add_golem15_seo_redirects_source_key.go` (new migration), `classes/redirects.go`, `redirects_test.go`
|
||||
**Applied fix:** The new migration `202610280001_add_golem15_seo_redirects_source_key` adds `source_key`, a stored generated column. It is the SQL form of `exactKey`: the path lowercased, one trailing slash dropped (the root stays `/`), and the query kept as written. A partial index covers it `WHERE match = 'exact'`. `LoadRedirectSet` now fetches with `source_key IN keys`. Postgres computes the column, so every write path fills it (admin, API, batch, import, undo, address changes) and no released migration was edited. The column is not in the GORM model.
|
||||
**Test:** the DB-backed `TestExactRedirectKeys`:
|
||||
- `/old-page/` fires for both `/old-page` and `/old-page/`.
|
||||
- `/list?Page=2` fires for its own query and not for `/list?page=2`.
|
||||
- An ignore-case `/Mixed/Case/` fires for `/mixed/case`.
|
||||
- The generated keys are asserted for each source, including `/` and `/A/?Q=1`.
|
||||
|
||||
With the old `lower(source)` fetch the test fails.
|
||||
|
||||
### WR-08: [WR-B01] A query-specific exact redirect is silently shadowed by the path-only rule
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed (requires human verification: matching-order logic)
|
||||
**Commit:** 58b2504
|
||||
**Files:** `classes/redirects.go`, `classes/redirect_graph_test.go`, `README.md`
|
||||
**Applied fix:** `exactKeys` now returns `path?query` before `path`, so the more specific exact rule wins. A unit test covers both insertion orders, and the README states the precedence.
|
||||
|
||||
### WR-09: [WR-B02] `AddressChanged` writes redirects without validation or the loop simulation
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed (requires human verification: redirect-graph logic)
|
||||
**Commit:** cb614cb
|
||||
**Files:** `classes/addresses.go`, `redirects_test.go`, `README.md`
|
||||
**Applied fix:**
|
||||
- **Address form:** absolute addresses on the site URL become paths, and the candidate `old → new` must pass `Problems`. A new address that is not a path on the site creates no redirect and logs a warning.
|
||||
- **Shadowing rules:** step 1 now deletes every exact rule that `exactMatches` the new address with its case and slash options, not only an exact literal match.
|
||||
- **Loop check:** steps 2 to 4 (create or update, then re-point) are simulated in memory with `checkRedirectRules` before anything is written. On a loop, no redirect is written, a warning is logged, and only the entry URL moves.
|
||||
- **Entry URL:** still stored as the descriptor wrote it, so later address diffs keep working.
|
||||
|
||||
**Test:** the DB test `TestAddressChangeGuards` covers:
|
||||
- the pattern-loop case;
|
||||
- a case or slash variant that is removed;
|
||||
- an absolute old address;
|
||||
- a `//evil` new address.
|
||||
|
||||
### WR-10: [WR-B03] The save-time loop check races with concurrent writes
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** c2f136a
|
||||
**Files:** `classes/redirect_graph.go`, `classes/addresses.go`, `classes/batch.go`, `redirects_test.go`, `README.md`
|
||||
**Applied fix:** `lockRedirectWrites` runs `SELECT pg_advisory_xact_lock(...)` and is taken in three places:
|
||||
- in `CheckRedirect` before it reads the rules (this covers `SaveRedirect`, the admin extension, undo and the 404 actions);
|
||||
- in `applyAddressRedirects`;
|
||||
- once at the start of every batch, which also covers imports.
|
||||
|
||||
**Test:** `TestConcurrentRedirectWrites` holds A → B uncommitted and checks that a concurrent B → A waits, then is refused as a loop. With the lock removed the test fails.
|
||||
|
||||
### WR-11: [WR-B04] Undo is not idempotent under concurrent requests
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** d20f14f
|
||||
**Files:** `classes/undo.go`, `redirects_test.go`
|
||||
**Applied fix:**
|
||||
- `Undo` loads the revision `FOR UPDATE`.
|
||||
- `UndoBatch` locks `batch_id = ? AND undone_at IS NULL` rows `FOR UPDATE`.
|
||||
- The final mark is `WHERE id = ? AND undone_at IS NULL`. When `RowsAffected == 0` it returns `UndoRefusal{already_undone}`.
|
||||
|
||||
**Test:** `TestConcurrentUndo` checks that the second concurrent undo gets `already_undone`, the redirect is re-created once, and there is one undo history row. Before the fix the second undo hit a unique violation.
|
||||
|
||||
### WR-12: [WR-B05] Public resolve and 404 report answer 500 for NUL or invalid UTF-8 paths
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** 98fbeb6
|
||||
**Files:** `classes/resolver.go`, `classes/notfound.go`, `redirects_test.go`
|
||||
**Applied fix:**
|
||||
- **Resolve:** `parseTarget` answers `ErrBadURL` (422) when the decoded path, the raw query or a decoded query key or value is invalid UTF-8 or holds NUL. `safeText` is the new helper for this check.
|
||||
- **404 report:** `NotFoundPath` applies the same check to the logged address. The query stays escaped there, so it is safe text.
|
||||
- **Referer:** cleaned of NUL and invalid UTF-8.
|
||||
|
||||
**Test:** in `TestNotFoundLog`, `/%00`, `/%FF` and query variants get 422 from resolve. The report refuses the path cases with 422 and never answers 5xx.
|
||||
|
||||
### WR-13: [WR-B06] The runtime cycle log grows without bound and is keyed by attacker-controlled URLs
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** c2ba33e
|
||||
**Files:** `classes/redirects.go`, `classes/redirect_graph_test.go`, `README.md`
|
||||
**Applied fix:** A mutex-guarded map replaces the global `sync.Map`:
|
||||
- it is keyed by the sorted rule IDs of the cycle, not the request URL;
|
||||
- each cycle is logged again at most once an hour;
|
||||
- the map is reset when it reaches 1024 keys.
|
||||
|
||||
**Test:** `TestCycleLogBounded` sends 5000 URLs through one cycle, which leaves one key, and checks that the map never exceeds the cap.
|
||||
|
||||
### WR-14: [WR-B07] Export with a large `page` panics the handler
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** 59c37a8
|
||||
**Files:** `classes/transfer.go`, `controllers/api/auth.go`, `transfer_test.go`
|
||||
**Applied fix:**
|
||||
- **Export:** a page past `Pages` is empty. The page is compared before multiplying, so an empty last page keeps the old semantics.
|
||||
- **List endpoints:** `listParams` caps `page` at `maxPage = 1_000_000`.
|
||||
|
||||
**Test:** `page=9223372036854777` on export and `page=MaxInt64` on a list both answer 200 with no rows.
|
||||
|
||||
### WR-15: [WR-B08] Public throttle buckets key on the SSR server's IP, capping the whole site
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed (documentation only)
|
||||
**Commit:** cab1b9a
|
||||
**Files:** `README.md`, `routes.go` (comment)
|
||||
**Applied fix:** The README has a new paragraph, "Behind the frontend server". It says the SSR host must be in `http.trusted_proxies` and must forward `X-Forwarded-For`. Without that, `seo-resolve` and `seo-notfound` become caps for the whole site, 600 requests a minute each. The `Buckets` doc comment says the same.
|
||||
**Not done (needs a decision):** an authenticated resolve call that skips the throttle or gets a higher limit. It needs a new token or config key and a framework way for a surf `Bucket` to skip or raise its limit per request; today `FixedWindowLimiter` has no such hook. This is a design and framework change, not a plugin patch.
|
||||
|
||||
### WR-16: [WR-B09] Social image values bypass validation on every non-admin write path
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** c8e0961
|
||||
**Files:** `classes/owner.go`, `classes/rules.go`, `classes/settings_write.go`, `mcp_test.go`
|
||||
**Applied fix:** The following now refuse a non-empty value that is not a path or an http(s) URL, with `golem15.seo::lang.image.url_invalid`:
|
||||
- `SetURLSEO` (`og_image`), which covers the API, MCP, batch `set_seo` and the records import;
|
||||
- `SaveRule` (`og_image`);
|
||||
- `SaveSettings` (`default_og_image`, only when that column is sent).
|
||||
|
||||
**Test:** `javascript:`, `data:`, `//` and a value with spaces get 422 on all three MCP routes.
|
||||
|
||||
### WR-17: [WR-B10] Invalid redirect status, match or query values are silently coerced on API, MCP and import
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** 24e6f38
|
||||
**Files:** `classes/batch.go`, `classes/transfer.go`, `controllers/api/redirects.go`, `mcp_test.go`, `batch_test.go`, `transfer_test.go`
|
||||
**Applied fix:** The new `RedirectFields.Problems()` refuses values outside {301, 302, 410}, {exact, pattern, regex} and {ignore, pass} with `api.value_invalid`. An empty match or query still means the default. It is checked before `Apply` in:
|
||||
- API create and update (422 `validation_failed`);
|
||||
- batch create and update redirect;
|
||||
- the CSV redirects import (the row is refused with `transfer.row_invalid`).
|
||||
|
||||
**Tests:** MCP `status: 308`, `match: Regex` and `query: keep` get 422; a batch with 307 gets 422; an import with `glob` or `keep` gives 2 refused rows.
|
||||
|
||||
### WR-18: [WR-B11] `set_url_seo`, batch `set_seo` and the records import accept any locale
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** cff2d29
|
||||
**Files:** `classes/owner.go`, `controllers/api/seo.go` (jsonschema text), `lang/en/lang.yaml`, `lang/pl/lang.yaml`, `mcp_test.go`
|
||||
**Applied fix:** When a locale other than the matched one is given, `SetURLSEO` requires it to be one of the locales the record's descriptor describes (existing `recordLocales`). Otherwise it refuses with the new `api.locale_unknown` (en/pl). This covers the API, MCP, batch and the records import.
|
||||
**Test:** `xx` and `EN ` get 422 on `locale`; `pl` is written.
|
||||
|
||||
### WR-19: [WR-B12] Entry generation overwrites `entry.URL`, which can swallow an address change and its 301
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed (requires human verification: address-change logic in the job)
|
||||
**Commit:** d8aa989
|
||||
**Files:** `classes/generate.go`, `seo_tab_test.go`, `README.md`
|
||||
**Applied fix:** `refreshEntry` (published records only) behaves as follows:
|
||||
- an empty URL is filled;
|
||||
- a URL that differs goes through `AddressChanged` (via auto), which creates the 301 and moves the URL;
|
||||
- it never overwrites the URL silently.
|
||||
|
||||
**Test:** `TestGenerateEntries` covers a slug changed by a direct DB write: the job now creates `/pages/one → /pages/one-renamed` and `/pl/pages/one → /pl/pages/one-renamed`. A third run adds nothing.
|
||||
|
||||
### WR-20: [WR-C01] The social image preview accepts `/\host/...`, so the admin can load an image from an attacker's host
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** 882d4ee
|
||||
**Files:** `assets/src/elements/image.ts`, `assets/dist/seo.js`, `classes/field_types.go`, `classes/urlref_test.go` (new), `tests/elements/image.test.ts` (new)
|
||||
**Applied fix:** `safeImageURL` (`/^\/(?![\/\\])/`) and `ValidURLRef` both refuse a path that starts with `/\`. `ValidURLRef` is also the canonical validator, so canonicals are stricter in the same way.
|
||||
**Tests:** a Go table test and a TS test.
|
||||
|
||||
### WR-21: [WR-C02] The CSV export/import round trip changes cells that already start with an apostrophe followed by a formula character
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** ed2d919
|
||||
**Files:** `classes/csv.go`, `classes/csv_test.go`, `README.md`
|
||||
**Applied fix:**
|
||||
- A new `escapable(s)` helper checks for a formula character after any leading apostrophes.
|
||||
- `escapeCell` prefixes one more apostrophe to such values.
|
||||
- `unescapeCell` strips exactly one apostrophe, so it is the inverse of `escapeCell`.
|
||||
- The round-trip rows now include `'=x`, `''-)` and `'plain`.
|
||||
- The unit expectation for `unescapeCell("''=x")` changed to `'=x`.
|
||||
|
||||
This also resolves IN-08 (IN-B02), which is out of scope.
|
||||
|
||||
### WR-22: [WR-C03] The 404 "Open/Resolved" filter and the redirect "Chains" filter disagree with the runtime matcher
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed (requires human verification: SQL matcher logic). Pattern and regex rules remain a documented gap.
|
||||
**Commits:** 7677d8d, ad419e9 (gofmt follow-up)
|
||||
**Files:** `models/redirect.go`, `models/notfound.go`, `controllers/api/notfound.go` (jsonschema), `redirects_test.go`
|
||||
**Applied fix:** A new `coversSQL(alias, addr)` is the SQL form of `exactMatches`:
|
||||
- the source path is compared with its `ignore_case` and `trailing_slash` options, and the query exactly when the source has one;
|
||||
- the indexed `source_key` from CR-03 serves as a prefilter.
|
||||
|
||||
`coveredSQL` (Open/Resolved, also MCP `list_not_found?status=`) and `chainSQL` (a path target that another rule's source names literally or an exact rule matches) both use it. The MCP `status` schema text now says that an address only a pattern or regex rule answers stays open in the filter but has `resolved: true` in its row.
|
||||
**Test:** `TestCoverAndChainFilters` covers:
|
||||
- `/missing/`, `/missing?utm=x`, `/case/` and `/q?id=1` are resolved;
|
||||
- `/MISSING`, `/other` and `/q?id=2` are open;
|
||||
- each row's badge agrees with the filter;
|
||||
- `/c1 → /c2/` is a chain next to `/c2`.
|
||||
|
||||
### WR-23: [WR-C04] The URL rule address is uncapped but sits in a btree UNIQUE index, so long values return 500 instead of 422
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** 4ca26e9
|
||||
**Files:** `models/rule.go`, `mcp_test.go`
|
||||
**Applied fix:** `models.MaxRuleURL = 2048`, and `Rule.Problems` refuses longer addresses with `rules.url_invalid`. The check covers the admin form, the API, MCP, batches and imports.
|
||||
**Test:** a 3001-byte rule URL gets 422 on `url`.
|
||||
|
||||
### WR-24: [WR-C05] The robots element's grammar drifts from the Go grammar, and an unparseable value is silently wiped on the next edit
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commit:** 923d0f9
|
||||
**Files:** `assets/src/elements/robots.ts`, `labels.ts`, `styles.css`, `assets/dist/seo.js`, `assets/dist/seo.css`, `tests/elements/robots.test.ts`, `classes/robots_value_test.go`
|
||||
**Applied fix:**
|
||||
- **Dates:** the new `validDate` checks a real calendar date and handles leap years. `2027-02-30` is refused, as Go's `time.Parse` refuses it.
|
||||
- **Numbers:** an optional sign is accepted like `strconv.Atoi`, so `+5` reads as 5. The Go side was left unchanged so existing API callers keep working.
|
||||
- **Unparseable stored value:** the element keeps the raw value and shows a note (`robotsUnparsed`, en/pl) in place of the Inherit display. All controls are disabled, `commit` is blocked, and an explicit Reset button emits `''`.
|
||||
|
||||
**Tests:** the Feb-30, Apr-31 and day-00 dates are in the TS malformed list. A leap day and `+5` are accepted. An element test covers keep, disable and Reset. A Go test checks that `+5` normalises to `max-snippet:5`.
|
||||
|
||||
### WR-25: [WR-C06] The element tests never exercise the host protocol; the tester and the image element have no tests
|
||||
|
||||
_Lane: sm-seo-plugin_
|
||||
|
||||
**Status:** fixed
|
||||
**Commits:** 3ecbd1f (fake host, SERP host-protocol tests, `robotstester.test.ts`), 882d4ee (`image.test.ts` `safeImageURL`), 5c2ad6a (transfer host tests, image element tests, README test gate)
|
||||
**Files:** `tests/elements/host.ts`, `serp.test.ts`, `robotstester.test.ts`, `transfer.test.ts`, `image.test.ts`, `README.md`
|
||||
**Applied fix:**
|
||||
- The fake widget host drives serp, robotstester and transfer. The tests cover queueing behind `busy`, `state=error` unblocking, the append-first ordering and dropped actions.
|
||||
- `golem15-seo-image` is tested for safe and unsafe previews, upload id matching (a foreign id is ignored), the error and the `imageFailed` fallback, Remove, and the disabled state.
|
||||
- The README test gate now includes `npm test`.
|
||||
|
||||
|
||||
|
||||
None.
|
||||
|
||||
|
||||
|
||||
- **No schema edits to released migrations:** CR-03 adds the new migration `202610280001_add_golem15_seo_redirects_source_key`. v0.1.0's migrations are untouched.
|
||||
- **Framework half of CR-04:** the `WidgetField.vue` change belongs to the other fixer. The plugin now works with either wiring order.
|
||||
- **Needs human verification of logic:** WR-08, WR-09, WR-19 and WR-22 change matching, redirect-graph or SQL semantics. Syntax checks and DB tests pass, but the logic should be reviewed by a person.
|
||||
- **Behaviour now stricter for callers:**
|
||||
- unknown redirect status, match or query values are refused (WR-17);
|
||||
- unknown locales are refused (WR-18);
|
||||
- invalid social images are refused (WR-16);
|
||||
- `/\` paths are refused as image or canonical URLs (WR-20);
|
||||
- rule URLs over 2048 bytes are refused (WR-23).
|
||||
|
||||
These are worth a changelog line when the plugin is tagged.
|
||||
- **README sections updated:** redirects precedence, address changes, the loop lock, the runtime cycle log, "Behind the frontend server", entry generation, CSV escaping, and the Testing gate.
|
||||
|
||||
---
|
||||
|
||||
_Fixed: 2026-10-27T14:45:18Z_
|
||||
_Fixer: Claude (msd-code-fixer)_
|
||||
_Iteration: 1_
|
||||
|
||||
## Skipped Issues
|
||||
|
||||
### WR-03: [WR-A03] A failing extension `Load` (or plugin-type `Load`) after a successful save rolls back the whole save
|
||||
|
||||
_Lane: summercms.go / sm-journal-plugin_
|
||||
|
||||
**Status:** skipped
|
||||
**File:** `modules/cabana/crud.go:980`, `modules/cabana/form_extensions.go` (`hydrateFormExtensions`)
|
||||
**Reason:** Both suggested fixes have problems that need a design decision:
|
||||
- **Log and omit the extension's keys.** This risks data loss. The admin SPA's `editablePayload` always sends translatable fields (`localeRecord(undefined)`), so a response without them makes the next save post empty locale maps to the extension's `Save`.
|
||||
- **Run hydration after the commit.** This stops the rollback, but the request still answers 500 after a committed write. Show still fails for the same `Load`, so editing stays blocked either way.
|
||||
|
||||
A proper fix needs an "extension unavailable" state in the schema/record (for example, the failing extension's fields marked read-only or failed, so the SPA does not post them). That is beyond a v0.5.2 patch.
|
||||
|
||||
**Original issue:** `hydrateFormExtensions` runs inside the save transaction, so one plugin's read-side failure turns a successful save into a 500 and rolls it back. `ShowRecord` likewise fails the whole record.
|
||||
|
||||
---
|
||||
|
||||
_Fixed: 2026-10-27T15:55:00Z_
|
||||
_Fixer: Claude (msd-code-fixer)_
|
||||
_Iteration: 1_
|
||||
719
.planning/phases/32-seo-foundation/32-REVIEW.md
Normal file
719
.planning/phases/32-seo-foundation/32-REVIEW.md
Normal file
@@ -0,0 +1,719 @@
|
||||
---
|
||||
phase: 32-seo-foundation
|
||||
reviewed: 2026-10-27T13:31:23Z
|
||||
depth: standard
|
||||
files_reviewed: 221
|
||||
lanes: [framework-and-journal (A, 50 files), seo-plugin-core-go (B, 68 files), seo-plugin-rest (C, 103 files)]
|
||||
findings:
|
||||
critical: 4
|
||||
warning: 25
|
||||
info: 23
|
||||
total: 52
|
||||
status: issues_found
|
||||
---
|
||||
|
||||
# Phase 32: Code Review Report
|
||||
|
||||
The scope (221 files across summercms.go, sm-journal-plugin and sm-seo-plugin) was split into three parallel reviewer lanes at standard depth; each lane's report follows verbatim, with finding IDs prefixed A-, B- and C-. Per-lane file lists are in each section's header block.
|
||||
|
||||
**Critical:** CR-01 (CR-A01) (extension `required:` field blocks every host save), CR-02 (CR-A02) (field-type upload ignores extension Permissions/Visible), CR-03 (CR-B01) (exact redirects with trailing slash or upper-case query never match at runtime), CR-04 (CR-C01) (widget host assigns `element` after `append`, so actions sent from `connectedCallback` are dropped: SERP preview and robots tester never load; orchestrator confirmed in `admin/src/components/form/fields/WidgetField.vue:161-162`).
|
||||
|
||||
---
|
||||
|
||||
## Lane A: framework and Journal
|
||||
|
||||
```yaml
|
||||
phase: 32-seo-foundation
|
||||
reviewed: 2026-10-27T13:28:44Z
|
||||
depth: standard
|
||||
files_reviewed: 50
|
||||
findings:
|
||||
critical: 2
|
||||
warning: 7
|
||||
info: 6
|
||||
total: 15
|
||||
status: issues_found
|
||||
```
|
||||
|
||||
### Phase 32: Code Review Report (scope A: framework seams + Journal adoption)
|
||||
|
||||
**Reviewed:** 2026-10-27T13:28:44Z
|
||||
**Depth:** standard
|
||||
**Files Reviewed:** 50
|
||||
**Status:** issues_found
|
||||
|
||||
### Summary
|
||||
|
||||
I reviewed the D-91 form extensions (`cabana/form_extensions.go` and its hooks in crud, http, actions, partial_render, field_ml and field_type), the D-92 record events (`cabana/record_events.go`, `pact/record_events.go` and the emit sites in crud, reorder and relation_child), the D-93 content descriptors (`pact/content.go`, `signpost/content.go`), the apisurface/check-phase32 release gate, and the Journal adoption.
|
||||
|
||||
Parts that hold up:
|
||||
- Transaction boundaries are correct. Every emit site runs inside `lagoon.Transaction`, through `CRUDService.transaction`, `RelationService.transaction` or the `reorderPost` transaction. So events are buffered until the commit and dropped on a rollback, including when a later step such as `projectFullRecord` or hydrate fails. After-commit listeners receive the outer ctx, not the tx ctx.
|
||||
- Extension values are lifted out of the body before any owner path reads it.
|
||||
- Invisible extensions are filtered consistently in the schema, show, save, widget-action and partial routes.
|
||||
|
||||
Problems found:
|
||||
- **Required extension fields (CR-01 (CR-A01)).** A `required: true` field in an extension is turned into a model validation rule on the owner's record. That rule can never pass, so every save of the host form fails.
|
||||
- **Upload route (CR-02 (CR-A02)).** The plugin field-type upload route does not check extension visibility. Administrators who are not allowed to see an extension can still call its `Upload`.
|
||||
- **Record-event coverage and locale (warnings).** Some admin writes fire no event: hasMany link/unlink and the delete of a deferred child. `RecordSaved.Locale` is not a content locale.
|
||||
- **Journal MCP writes (warnings).** These can commit a slug change and fire no event, and they report a wrong `Old` value for derived `content_html` translations.
|
||||
|
||||
### Narrative Findings (AI reviewer)
|
||||
|
||||
### Critical Issues
|
||||
|
||||
### CR-01: [CR-A01] `required: true` on a form extension field makes every save of the host form fail (also for administrators who cannot see the extension)
|
||||
|
||||
**File:** `modules/cabana/crud.go:1353-1361` (mergedRules), `modules/cabana/form_extensions.go:405-443` (compileExtensionKinds accepts `Required`)
|
||||
**Issue:** `compileFormExtensions` places extension fields into `cc.Form.Fields`. `mergedRules` loops over `cc.Form.Fields` and adds `required` for every `field.Required && valueFormField(field)` field, extension fields included. Then `lagoon.Validate` checks those rules against the owner's model. It reads the values through `virtualValuesForRules`/`valuesForRules`, which come from the model's columns. The extension field is not a column, and its value has already been lifted out of the body by `liftExtensionValues`, so the value is always nil and the rule always fails. I confirmed this in a scratch copy of the package. `parseExtensionDoc` accepts `required: true` with no error, and `mergedRules` returns `map[seo_title:required]` → `msgs=map[seo_title:[The seo title field is required.]]`. Nothing in `compileExtensionKinds` refuses or strips `Required`. The impact:
|
||||
- Any extension that marks a field required, which is a natural thing to do for an SEO title or a slug override, bricks create/update of the host controller for everyone.
|
||||
- `mergedRules` does not look at extension visibility, so it also hits administrators who do not hold the extension's `Permissions`.
|
||||
- The 422 names a field that those administrators cannot see in the schema.
|
||||
|
||||
If the extension field's name matches a model column that is not on the owner's form, the rule silently validates the owner's column instead.
|
||||
**Fix:** Keep owner validation away from extension fields. Then either refuse `required` at boot, or check it against the lifted value for visible extensions only:
|
||||
```go
|
||||
// crud.go mergedRules
|
||||
for _, field := range cc.Form.Fields {
|
||||
if cc.extensionOf(field.Name) != nil {
|
||||
continue // D-91: an extension validates its own values (Save / AdminFormErrors)
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
and in `liftExtensionValues`, for a visible extension, add a "The X field is required." detail when `field.Required && contextAllows(...)` and the value is absent or empty (on create; on update only when the key is sent). If you choose to refuse it instead, add to `compileExtensionKinds`:
|
||||
```go
|
||||
if field.Required {
|
||||
return extErr(pluginID, controller, "field %s: required is not supported in a form extension; refuse the value in Save with pact.AdminFormErrors", field.Name)
|
||||
}
|
||||
```
|
||||
Add a Postgres test with a required extension field, saved by an administrator who sees the extension and by one who does not.
|
||||
|
||||
### CR-02: [CR-A02] Plugin field-type upload route ignores the extension's Permissions/Visible, so administrators without them can run its `Upload`
|
||||
|
||||
**File:** `modules/cabana/field_type_upload.go:32-126` (`fieldUpload`), `uploadField` at line 130
|
||||
**Issue:** The other per-field routes of an extension gate on `extensionVisible`: `widgetAction` (actions.go), `partial` (partial_render.go), `formSchema` (http.go) and save/show. `POST .../{id}/fields/{field}/upload` does not. `uploadField` finds the field in `cc.Form.Fields`, which includes the extension's fields, and checks only `contextAllows`. `protect()` checks only the host controller's permissions. So an administrator with access to, say, `acme.blog.posts` but without `golem15.seo.manage` can still run the SEO plugin's `seoimage` `Upload` (D-100). The plugin stores a file in the bucket, inside a transaction on the loaded record, with no admin UI showing it. This is exactly the access that `Permissions` and `Visible` are documented to deny ("Its widget actions and partials answer 404 for them"), and the docs never list the upload route as an exception. It is an authorization gap on a write path.
|
||||
**Fix:**
|
||||
```go
|
||||
field, ok := uploadField(cc, r.PathValue("field"), id)
|
||||
if !ok {
|
||||
writeNotFound(w, r)
|
||||
return
|
||||
}
|
||||
if ext := cc.extensionOf(field.Name); ext != nil {
|
||||
principal, _ := bouncer.User(r.Context())
|
||||
if !extensionVisible(r.Context(), principal, ext) {
|
||||
writeNotFound(w, r)
|
||||
return
|
||||
}
|
||||
}
|
||||
```
|
||||
Add the upload route to the permission tests in `form_extensions_postgres_test.go`. Also audit any other route that resolves a field by name from `cc.Form.Fields` (`uploadField` is the only one I found that accepts extension types today).
|
||||
|
||||
### Warnings
|
||||
|
||||
### WR-01: [WR-A01] Admin writes that change or delete records fire no record event (hasMany link/unlink, deferred child unlink, deferred child commit)
|
||||
|
||||
**File:** `modules/cabana/relation.go:1013` (linkRelated hasMany `Save(related)`), `modules/cabana/relation.go:1316` (unlinkRelated hasMany `Save(child)` with FK nulled + ClearOnChange), `modules/cabana/relation.go:1130` (unlinkDeferred `Delete(child)`), `modules/cabana/deferred.go` (commitDeferred binding children to the new parent)
|
||||
**Issue:** D-92 says "Admin, MCP and imports all go through cabana and emit it", and `pact.RecordSaved` says "The admin framework fires it for every admin write". The SEO plugin relies on it for 301s and for deleting entries with their record. Some admin paths still write records with no event:
|
||||
- `unlinkDeferred` deletes a child that `CreateChild` created. `CreateChild` already fired `RecordSaved{Created: true}` for it after its commit, so subscribers learn about a record that later disappears without a `RecordDeleted`. The SEO entry (or any derived state) is orphaned.
|
||||
- hasMany link and unlink rewrite the child's foreign key and clear its `ClearOnChange` columns (a parent change that can change the child's URL), with no `RecordSaved`.
|
||||
**Fix:** In `unlinkDeferred`, after the delete, call `EmitRecordDeleted(ctx, s.app, tx, pact.RecordDeleted{Controller: s.reg.controllerForRecord(child), Model: recordMorphType(tx, child), ID: recordIDText(child)})`. In linkRelated and unlinkRelated (hasMany), take a snapshot before `setModelColumn` and call `s.emitChildSaved(ctx, tx, child, false, changes)` after `Save`. Do the same for the hasMany children `commitDeferred` attaches. Alternatively, narrow the `pact.RecordSaved` doc and `docs/backend/admin-controllers.md` to the paths that actually fire.
|
||||
|
||||
### WR-02: [WR-A02] `RecordSaved.Locale` is the admin's UI language or the raw `Accept-Language` header, not a content locale, and reorder reports something different
|
||||
|
||||
**File:** `modules/cabana/record_events.go:65`, `modules/cabana/relation_child.go:490`, `modules/cabana/reorder.go:318,337`
|
||||
**Issue:** `pact.RecordSaved.Locale` is documented as "the request's content locale". `emitRecordSaved` and `emitChildSaved` copy `towel.Locale(ctx)`. In the admin that value is set by `surf.Router.locale` to the raw `Accept-Language` header when no `LocaleResolver` is published, for example `pl-PL,pl;q=0.9,en-US;q=0.8`, or by `surf.LocaleFromPrincipal` to the administrator's `PreferredLocale` (the UI language). Journal's `requestLocale` has to parse exactly this raw header, which shows it happens. `reorderPost` instead sets `towel.WithLocale(ctx, schemaLocale(...))`, so reorder events carry a normalised UI code. Admin saves write the default content locale to the row and report the other locales per change, so the event-level Locale has no defined content meaning. A subscriber that keys on it (an SEO 301 per locale) will mis-key.
|
||||
**Fix:** Pick one meaning and enforce it at the emit site. For admin saves, set `Locale` to the default content locale (from `TranslationWriter.DefaultLocale`, or `""` without translate) and leave per-locale changes to `RecordChange.Locale`. At the very least, normalise with `primaryLanguage` the way `schemaLocale` does. Then document it in `pact/record_events.go`.
|
||||
|
||||
### WR-03: [WR-A03] A failing extension `Load` (or plugin-type `Load`) after a successful save rolls back the whole save
|
||||
|
||||
**File:** `modules/cabana/crud.go:980`, `modules/cabana/form_extensions.go:1431-1435`
|
||||
**Issue:** `hydrateFormExtensions` runs as the last statement inside the save transaction closure, and its error is returned from it. The owner row, translations, deferred bindings and every extension's `Save` have all succeeded by then, but a read-side failure in third-party plugin code (an SEO `Load` hitting a missing row, a field type's `Load`) turns the save into a 500 and rolls everything back. `ShowRecord` likewise fails the whole host record when any one extension's `Load` fails. One contributing plugin can block editing of another plugin's records.
|
||||
**Fix:** Run the response hydration after the transaction commits, in a short read transaction, or log the error and omit that extension's keys from `result.Data` instead of returning it. Keep `Save` errors as the rollback path; hydration is presentation only.
|
||||
|
||||
### WR-04: [WR-A04] Journal API writes can commit changes (including a slug) and fire no RecordSaved
|
||||
|
||||
**File:** `../sm-journal-plugin/controllers/api/posts.go:223-236` (Store), `:281-294` (Update)
|
||||
**Issue:** The API handlers write without a transaction: `Save(post)`, then `applyPostAssocs` (categories, tags, and `syncTranslations`, which writes translated slugs), then `loadPostAssocs`. `cabana.EmitRecordSaved` is called only after all of them succeed. If `applyPostAssocs` or `loadPostAssocs` fails, the post row (and possibly some translations) is already committed but no event fires. A slug changed over MCP then gets no 301 (D-102), which is exactly what the change was for.
|
||||
**Fix:** Wrap the write in `lagoon.Transaction(ctx, db, ...)` and call `cabana.EmitRecordSaved(ctx, app, tx, ...)` inside it, so the event follows the commit and a failure rolls back the row too. If that is not possible, emit as soon as `Save` succeeds and emit again (or emit the translation changes) after `applyPostAssocs`.
|
||||
|
||||
### WR-05: [WR-A05] Journal `postSavedEvent` reports `Old: nil` for a translated `content_html` that existed, because the body is mutated between the snapshot and the event
|
||||
|
||||
**File:** `../sm-journal-plugin/controllers/api/record_events.go:54,91`, `../sm-journal-plugin/controllers/api/posts_helpers.go:789`
|
||||
**Issue:** `snapshotPost` reads the old translations of the fields `submittedTranslations(body)` lists *before* the write. `syncTranslations` then calls `classes.FormatTranslation(attrs)` on the same `attrs` map inside `body`, which adds `attrs["content_html"]` whenever `content` is sent. `postSavedEvent` calls `submittedTranslations(body)` again, now sees `content_html`, finds no snapshot for it and reports `Old: nil`. Per `pact.RecordChange`, nil means "a translation that did not exist before", so the event is wrong for every update that sends a translated `content` without `content_html`.
|
||||
**Fix:** Compute the submitted set once, before the write, and pass it to both functions. Or include `content_html` in the snapshot whenever `content` is submitted (mirror `FormatTranslation`). Or copy the body's translation maps before `syncTranslations` mutates them.
|
||||
|
||||
### WR-06: [WR-A06] Tags auto-created by the Journal post API fire no RecordSaved although `journal-tag` is now a content type
|
||||
|
||||
**File:** `../sm-journal-plugin/controllers/api/posts_helpers.go:732-770` (`resolveTagIDs` → `db.Create(&tag)`)
|
||||
**Issue:** D-102 adds the `journal-tag` content descriptor so that tags get SEO entries. The MCP post write creates new `models.Tag` rows on the fly and fires nothing for them. SEO and sitemap subscribers only learn about those tags from a later bulk job.
|
||||
**Fix:** Collect the tags created in `resolveTagIDs` and emit `cabana.EmitRecordSaved(ctx, app, tx, pact.RecordSaved{Model: models.Tag{}.MorphName(), ID: ..., Created: true, Changes: ...})` for each, ideally inside the transaction suggested in WR-04 (WR-A04).
|
||||
|
||||
### WR-07: [WR-A07] `Hide` leaves the owner's relation-manager and partial endpoints of a hidden field reachable
|
||||
|
||||
**File:** `modules/cabana/form_extensions.go:624-641` (`dropHiddenFields`)
|
||||
**Issue:** `dropHiddenFields` removes a hidden field from `Writable`, `files`, `dates`, `permissions` and `FieldRelations`, but not from `cc.Relations` (relation-manager panels and their link, unlink and child CRUD routes, plus `commitDeferred`, which loops over `cc.Relations` and calls `contextAllows`; that returns true for a field no longer in the form) or from `cc.partials`/`cc.formPartials`. The pact doc says hidden fields "leave the schema, show and save", but writes through the relation routes of a hidden relation-manager field still go through, and the partial still renders.
|
||||
**Fix:** For hidden names, also drop the relation whose `fieldName` matches from `cc.Relations`, and drop the names from `cc.partials` and `cc.formPartials` (copy the maps first). Or refuse `Hide` of `relation-manager`/`partial` owner fields at boot.
|
||||
|
||||
### Info
|
||||
|
||||
### IN-01: [IN-A01] Dead check in `BindWritableFields`
|
||||
|
||||
**File:** `modules/cabana/crud.go:259-263`
|
||||
**Issue:** `BindWritableFields` runs in `compileRegistryWithTypes`, before `compileFormExtensions` fills `cc.extensionFields`, and again for relation child forms, which never have extensions. So `cc.extensionOf(field.Name) != nil` is always false there. The comment suggests it protects something it does not.
|
||||
**Fix:** Remove it, or move the guard to where it would matter and say so.
|
||||
|
||||
### IN-02: [IN-A02] Scoped API tokens never see an extension that declares no Permissions, and their posted values are dropped silently
|
||||
|
||||
**File:** `modules/cabana/form_extensions.go:1092-1097`, `modules/cabana/token_scopes.go:246-252`
|
||||
**Issue:** `Allows` returns false under a non-full token scope when `required` is empty. An extension without `Permissions` is therefore invisible to scoped MCP tokens, and a save from such a token drops the extension keys and still answers 200. That is fail-closed, but it is surprising and undocumented in `pact.AdminFormExtension`.
|
||||
**Fix:** Document it next to `Permissions`, or treat an empty `Permissions` as "inherit the host controller's access".
|
||||
|
||||
### IN-03: [IN-A03] `resolveExtensionLocales` wraps a nil error
|
||||
|
||||
**File:** `modules/cabana/form_extensions.go:1129-1131`
|
||||
**Issue:** When `DefaultLocale` returns `("", nil)`, `fmt.Errorf("cabana: default locale: %w", err)` produces `%!w(<nil>)`. The same pattern exists in `hydrateMLRecord`.
|
||||
**Fix:** Use `errors.New("cabana: default locale is empty")` when `err == nil`.
|
||||
|
||||
### IN-04: [IN-A04] `tab: default` on an extension field is refused although `default` names the default tab elsewhere
|
||||
|
||||
**File:** `modules/cabana/form_extensions.go:932-936`
|
||||
**Issue:** The docs say "`default` names the tab of fields without a `tab:`". Anchors and `after:` accept it, but a field with `tab: default` fails with "unknown tab" because `place` does not map it through `tabAnchorKey`.
|
||||
**Fix:** Normalise `field.Tab` with `tabAnchorKey` before the lookup, or say in the docs that a field omits `tab:` for the default tab.
|
||||
|
||||
### IN-05: [IN-A05] Journal `requestLocale` drops the region, so translated slugs in region-coded locales never match
|
||||
|
||||
**File:** `../sm-journal-plugin/controllers/api/posts_helpers.go:806-819`
|
||||
**Issue:** `pt-BR` and `en_GB` become `pt` and `en`. If translate stores region codes, the translated-slug lookup in `findPostBySlugOrID` misses.
|
||||
**Fix:** Try the full normalised code first, then the primary language.
|
||||
|
||||
### IN-06: [IN-A06] The extension's client assets are served to every administrator of the host form
|
||||
|
||||
**File:** `modules/cabana/form_extensions.go:508-543`, `modules/cabana/http.go:851` (`view.Assets = s.controllerAssets(cc)`)
|
||||
**Issue:** The plugin's `AdminClientAssets` JS/CSS is added to `cc.scripts`/`cc.styles` and loaded for every administrator, including those the extension is hidden from. This is not an authorization leak, because the scripts are already served, but it does run the plugin's script on forms where none of its elements exist.
|
||||
**Fix:** Optional. Filter `controllerAssets` by visible extensions, or note the behaviour in the docs.
|
||||
|
||||
|
||||
_Reviewed: 2026-10-27T13:28:44Z_
|
||||
_Reviewer: Claude (msd-code-reviewer)_
|
||||
_Depth: standard_
|
||||
|
||||
---
|
||||
|
||||
## Lane B: sm-seo-plugin core Go
|
||||
|
||||
```yaml
|
||||
phase: 32-seo-foundation
|
||||
reviewed: 2026-10-27T13:28:36Z
|
||||
depth: standard
|
||||
files_reviewed: 68
|
||||
findings:
|
||||
critical: 1
|
||||
warning: 12
|
||||
info: 8
|
||||
total: 21
|
||||
status: issues_found
|
||||
```
|
||||
|
||||
### Phase 32: Code Review Report (scope B: sm-seo-plugin core)
|
||||
|
||||
**Reviewed:** 2026-10-27T13:28:36Z
|
||||
**Depth:** standard
|
||||
**Files Reviewed:** 68
|
||||
**Status:** issues_found
|
||||
|
||||
### Summary
|
||||
|
||||
Reviewed the sm-seo-plugin v0.1.0 core: resolver and precedence, the redirect engine with loop and chain detection, normalisation and strict URLs, the 404 log, robots.txt, verification files, history and undo, batches, CSV transfer, the issue report, the `/_seo/api/v1` management API with its MCP tool table, and the admin controllers and extensions.
|
||||
|
||||
Auth is consistent. Every management route goes through `manage()` (`cabana.ResolveBackend` bearer-only, no cookie, so no CSRF surface, then `cabana.Allows(golem15.seo.manage)`). Every admin controller, action, bulk action, widget action and form extension declares `golem15.seo.manage`. The public endpoints (`/robots.txt`, `/resolve`, `/notfound`, `/verification/{name}`) are throttled. The 404 report token is compared in constant time. Open-redirect hardening on substituted targets (`SafeTarget`, `escapeCapture`) and the normalisation host pinning (`sameSite`) hold up under tracing. Absolute-URL building never uses the Host header. Verification files carry `nosniff` and `sandbox` CSP. Batches and API undo run in one transaction with savepoints. Admin record and bulk actions run inside cabana's action transaction (verified in `cabana/crud.go`).
|
||||
|
||||
Main concerns:
|
||||
|
||||
1. **Exact redirects whose source ends in `/` or has upper-case letters in its query never fire at runtime.** The resolver's on-demand DB lookup compares a different key than the in-memory set the save-time check uses. This also breaks "Create redirect…" from the 404 log on sites that use trailing slashes.
|
||||
2. **The loop guarantee has holes.** The save-time simulation is not serialised, `AddressChanged` skips it entirely, and undo is not idempotent under concurrency.
|
||||
3. **The public resolve endpoint can be driven to 500s and unbounded memory.** NUL or invalid UTF-8 paths cause the 500s; the never-evicted "logged cycle" map grows without bound.
|
||||
4. **Validation differs between paths.** Social images, invalid statuses and locales are checked or rejected in the admin but accepted or silently coerced through the API, MCP, batches and imports.
|
||||
5. **An overflowing `page` on export panics the handler.**
|
||||
|
||||
### Narrative Findings (AI reviewer)
|
||||
|
||||
### Critical Issues
|
||||
|
||||
### CR-03: [CR-B01] Exact redirects with a trailing slash or upper-case query characters never match at runtime
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/redirects.go:119-137, 230-242, 277-289`
|
||||
**Issue:** `LoadRedirectSet`, used by the resolver (`resolver.go:375`), the 404 log's "resolved" state (`controllers/notfound.go:70,205`, `controllers/api/notfound.go:123`) and `ResolveNotFound` (`notfound.go:161`), loads exact rules on demand with
|
||||
`WHERE match = 'exact' AND lower(source) IN (keys)`. The keys come from `exactKeys(path, rawQuery)`, which strips one trailing slash from the path (`trimSlash`) and keeps the query in its original case. The stored `source` is never normalised: `models.Redirect.Normalize` only trims spaces. So:
|
||||
|
||||
- source `/old-page/` gives `lower(source)` = `/old-page/`, but every request key is `/old-page`. The row is never fetched, and the redirect is dead for both `/old-page` and `/old-page/`.
|
||||
- source `/list?Page=2` gives `lower(source)` = `/list?page=2`, but the key is `/list?Page=2`. The row is never fetched.
|
||||
|
||||
I verified both mismatches with a scratch program. The save-time check (`CheckRedirect`, which uses `NewRedirectSet` over all rows in memory with no fetch), the issue report and the list's SQL `coveredSQL` filter all see these rules. So the admin saves them without complaint, the redirects list's "Resolved" SQL filter says the 404 entry is covered, the row badge says it is open, and visitors get a 404.
|
||||
|
||||
This hits real usage directly. On a site with `url_slash: add`, every 404 the frontend reports ends in `/`. **Create redirect…** / `redirect_not_found` stores `source = "/old/"`, which never fires. The next report of the same URL also finds no cover, so the admin can be offered "Create redirect" again, and that fails with `source_taken` instead of `has_rule`. Existing unit tests only exercise `NewRedirectSet` in memory (`classes/redirect_graph_test.go`), never the DB fetch path.
|
||||
**Fix:** Make the DB lookup use the same key function as the in-memory set. Either normalise the stored lookup key at write time, or match on an expression index:
|
||||
|
||||
```go
|
||||
// LoadRedirectSet fetch: compare the same normalised key exactKey() builds
|
||||
err := db.Where(`match = ? AND (
|
||||
rtrim(lower(split_part(source, '?', 1)), '/') ||
|
||||
CASE WHEN position('?' in source) > 0 THEN '?' || substr(source, position('?' in source) + 1) ELSE '' END
|
||||
) IN ?`, models.RedirectExact, keys).Order("id ASC").Find(&out).Error
|
||||
```
|
||||
|
||||
A cleaner option is a stored `source_key TEXT` column, filled from `exactKey(r.Source)` in `SaveRedirect`, `AddressChanged` and the admin `FormBefore*`, with an index, and `WHERE source_key IN ?`. Keep `rtrim` semantics for `/` (the root stays `/`). Add a DB-backed test that resolves `/old/`, `/old` and `/list?Page=2` against stored exact sources.
|
||||
|
||||
### Warnings
|
||||
|
||||
### WR-08: [WR-B01] A query-specific exact redirect is silently shadowed by the path-only rule
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/redirects.go:130-137, 281-289`
|
||||
**Issue:** `exactKeys` returns `[path, path?query]`, and `Match` returns the first hit in that order. With `/products → /shop` and `/products?id=5 → /shop/item-5` both stored, `/products?id=5` always goes to `/shop`, so the more specific rule can never fire. `checkRedirectRules` does not report this: the probe's first hop is the other rule, so the `Hops[0].Rule.ID == r.ID` branches are skipped and the rule is saved without any notice.
|
||||
**Fix:** Try the `path?query` key before the path-only key in `Match`. Alternatively, have `CheckRedirect` refuse or warn when the probe of `r` is answered by a different rule (a "shadowed" problem).
|
||||
|
||||
### WR-09: [WR-B02] `AddressChanged` writes redirects without validation or the loop simulation
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/addresses.go:58-120`
|
||||
**Issue:** Steps 1–4 use raw `tx.Create`, `tx.Save` and `tx.Delete` and never call `Problems()` or `CheckRedirect`. Only exact redirects whose source equals the new address are removed (step 1). Pattern and regex rules, case variants (`ignore_case`) and trailing-slash variants that match the new address survive. The new `old → new` 301 then forms a loop with them. For example, with a pattern `/a/* → /b/*` in place, a record moved from `/b/x` to `/a/x` gets `/b/x → /a/x → /b/x`. The resolver turns this into `not_found` for the record's live address. Re-pointing (step 3) can likewise close a cycle with pattern rules. Also, the descriptor URL is stored as an exact `source` unvalidated: an absolute or `//` URL from a descriptor would be stored and never match.
|
||||
**Fix:** After steps 1–4, run `s.CheckRedirect(ctx, tx, redirect)` and the same for every re-pointed rule. On `Loop`, either skip creating the 301 and log, or delete the conflicting shadowing rule. Validate `res.Old` and `res.New` with `Problems(tx)` before creating.
|
||||
|
||||
### WR-10: [WR-B03] The save-time loop check races with concurrent writes
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/redirect_graph.go:168-177, 276-310`; `controllers/api/auth.go:172-180`
|
||||
**Issue:** `CheckRedirect` reads all rules inside the writer's transaction at READ COMMITTED with no lock. Two concurrent writes (two MCP agents, an import and an admin save, or a batch and a slug change) can each simulate without the other's uncommitted rule. For example, one creates `A → B` while the other creates `B → A`. Both commit, and the stored set contains the loop D-19 promises to refuse. The runtime guard turns it into a 404 for both addresses.
|
||||
**Fix:** Serialise redirect writes. Take `SELECT pg_advisory_xact_lock(<const>)` at the start of `SaveRedirect`, `DeleteRedirect`, `AddressChanged` and `runBatch` before `LoadRedirects`, or run those transactions at `SERIALIZABLE` and retry on 40001.
|
||||
|
||||
### WR-11: [WR-B04] Undo is not idempotent under concurrent requests
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/undo.go:71-83, 291-343`
|
||||
**Issue:** `Undo` reads the revision with `undone_at IS NULL` without locking. It then restores and marks the revision with `UPDATE ... WHERE id = ?`, with no `undone_at IS NULL` condition and no `RowsAffected` check. Two simultaneous undo calls (a double-click in the admin plus a retry, or an MCP agent retrying) can both pass the "already undone" check and both restore. For "deleted" subjects that means two re-created rules, redirects or 404 rows (or a unique-violation 500). In every case it writes two `via undo` history rows. `UndoBatch` has the same pattern.
|
||||
**Fix:** Lock the revision first, `tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("id = ?", id).Find(&rows)`. For batches, lock `WHERE batch_id = ? AND undone_at IS NULL FOR UPDATE`. Also make the final update conditional:
|
||||
|
||||
```go
|
||||
res := tx.Model(&models.Revision{}).Where("id = ? AND undone_at IS NULL", rev.ID).Updates(updates)
|
||||
if res.Error == nil && res.RowsAffected == 0 { return &UndoRefusal{Code: UndoDone, Key: "golem15.seo::lang.history.undo_done"} }
|
||||
```
|
||||
|
||||
### WR-12: [WR-B05] Public resolve and 404 report answer 500 for NUL or invalid UTF-8 paths
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/resolver.go:198-219`; `classes/notfound.go:59-80`; `controllers/api/resolve.go:31-40`
|
||||
**Issue:** `parseTarget` and `NotFoundPath` return `u.Path`, which is percent-decoded. `/%00` or `/%FF` yields a path with a NUL or invalid UTF-8 byte. That path reaches Postgres as a text parameter (`lower(source) IN ?` in the redirect fetch, `url = ?` in `ReportNotFound`), and Postgres rejects it ("invalid byte sequence for encoding UTF8"). The anonymous resolve endpoint then answers 500 and writes a `log.Error` line per request: 600 per minute per IP, more with many IPs. The token-gated 404 report fails the same way for every such URL a visitor hits.
|
||||
**Fix:** In `parseTarget` and `NotFoundPath`, refuse a decoded path that is not `utf8.ValidString` or contains `\x00`, returning `ErrBadURL` / `ErrNotFoundURL` (422). Apply the same check to `rawQuery`.
|
||||
|
||||
### WR-13: [WR-B06] The runtime cycle log grows without bound and is keyed by attacker-controlled URLs
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/redirects.go:529-537`; `classes/resolver.go:358, 385, 635`
|
||||
**Issue:** `redirectHopsLogged` is a process-global `sync.Map` that is never evicted. Its key is `self = site + path?rawQuery`, and the raw query comes straight from the anonymous request (up to 2048 bytes). Once any looping or over-10-hop chain exists (which WR-09 (WR-B02) and WR-10 (WR-B03) make reachable), an unauthenticated client can request `/looping?x=1`, `?x=2`, … Each request stores a new entry and writes a new warning line. Memory grows without limit, and the log is flooded despite the "once per URL" intent.
|
||||
**Fix:** Key the de-duplication on the rule IDs of the cycle (or `npath` without the query), and bound it, for example with a small LRU or a time-based reset like `capWarned` in `notfound.go`.
|
||||
|
||||
### WR-14: [WR-B07] Export with a large `page` panics the handler
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/transfer.go:159-168`; `controllers/api/transfer.go:88-89`
|
||||
**Issue:** `start := (page - 1) * perPage` overflows for large `page` values. `page=9223372036854777` gives `start = -9223372036854775616`, which passes the `start > len(rows)` check, and `rows[start:end]` panics with "slice bounds out of range". I reproduced this. It is reachable from `GET /_seo/api/v1/export?page=…` and from the `seo_export_csv` MCP tool for any holder of `golem15.seo.manage`.
|
||||
**Fix:** Clamp before multiplying:
|
||||
|
||||
```go
|
||||
if page < 1 { page = 1 }
|
||||
if page > out.Pages { page = out.Pages }
|
||||
start := (page - 1) * perPage
|
||||
```
|
||||
|
||||
Apply the same clamp in `listParams` (`controllers/api/auth.go:201-216`), where the multiplication can overflow into a negative offset.
|
||||
|
||||
### WR-15: [WR-B08] Public throttle buckets key on the SSR server's IP, capping the whole site
|
||||
|
||||
**File:** `../sm-seo-plugin/routes.go:91-111`
|
||||
**Issue:** The README says the frontend server calls `/resolve` for every page it renders and reports every 404. Both calls are server-to-server, so `surf.ClientIP` resolves to the SSR host unless that host is configured as a trusted proxy and forwards `X-Forwarded-For`. `seo-resolve` (600/min) and `seo-notfound` (600/min) then become site-wide caps: about 10 rendered pages per second. Beyond that, resolve answers 429 and the frontend either fails or renders without the redirect decision and robots. Nothing in the plugin documents or enforces the trusted-proxy requirement.
|
||||
**Fix:** Let the frontend server authenticate resolve calls with the existing `notfound_token` (or a dedicated `resolve_token`) and exempt or raise the bucket for authenticated calls. At minimum, document in the README that the SSR host must be in the trusted proxies and must forward the visitor IP.
|
||||
|
||||
### WR-16: [WR-B09] Social image values bypass validation on every non-admin write path
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/owner.go:129-150`; `classes/rules.go:33-52`; `classes/settings_write.go:104-105`
|
||||
**Issue:** The admin `seoimage` field type refuses anything but a path or an http(s) URL (`decodeImage` → `ValidImageURL`). `SetURLSEO` (API, MCP, batch `set_seo`, records import), `SaveRule` (API, MCP, batch, rules import) and `SaveSettings` (`default_og_image`) validate `canonical` and `robots` but not `og_image`. Values such as `javascript:alert(1)`, `data:…`, `//evil.example/x.png` or text with spaces are stored. `AbsoluteURL` (`urls.go:125-137`) passes any `IsAbs()` value through, so they come back from `/resolve` as `seo.og.image`. That value goes into `og:image` / `twitter:image` meta content, where crawlers and frontends trust it.
|
||||
**Fix:** Add `case column == "og_image" && v != "" && !ValidImageURL(v):` to `SetURLSEO`. Add the same check for `r.OGImage` in `SaveRule` and for `default_og_image` in `SaveSettings`, using the `golem15.seo::lang.image.url_invalid` problem.
|
||||
|
||||
### WR-17: [WR-B10] Invalid redirect status, match or query values are silently coerced on API, MCP and import
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/batch.go:53-78`; `models/redirect.go:109-129`
|
||||
**Issue:** `RedirectFields.Apply` copies any status, match or query, and `Normalize` replaces unknown values with defaults. A client sending `"status": 308` or `307` gets a 301. `"match": "Regex"` or `"glob"` becomes `exact`, which then fails with a misleading `source_invalid`. `"query": "keep"` becomes `ignore`. All of this is answered with 201. The CSV import has the same behaviour for the `match` and `query` columns. An MCP agent cannot tell that its request was changed.
|
||||
**Fix:** In `RedirectFields.Apply` (or a `Validate` step before `Normalize` on API, batch and import paths), refuse values outside {301, 302, 410}, {exact, pattern, regex} and {ignore, pass} with a `ProblemsError` (`value_invalid`). Leave the defaulting only to fields the caller omitted.
|
||||
|
||||
### WR-18: [WR-B11] `set_url_seo`, batch `set_seo` and the records import accept any locale
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/owner.go:154-173`; `classes/entries.go:176-223`; `classes/transfer.go:536-568`
|
||||
**Issue:** `in.Locale` (or the CSV `locale` cell) overrides the matched locale without checking that the record has that locale. `SaveRecord` creates an entry for `"xx"` or `"EN "` or any string, with an empty URL (`described[locale]` is missing), and records a history row. The answer says `written_to: record`, but the resolver never reads that row. The SEO tab never shows it either, so the agent's change is lost while it is reported as success.
|
||||
**Fix:** In `SetURLSEO`, when `in.Locale` is set, require it to be one of `recordLocales(...)` (or the enabled locales from `Locales()`). Otherwise refuse with `locale_unknown` as a `ProblemsError`.
|
||||
|
||||
### WR-19: [WR-B12] Entry generation overwrites `entry.URL`, which can swallow an address change and its 301
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/generate.go:111-131`; `listeners.go:46-70`
|
||||
**Issue:** Address-change detection (`AddressChanges`) depends on `entry.URL` holding the last address seen. `refreshEntry` sets `url` to the current descriptor URL unconditionally, and the job is queued after every settings save (`settings_write.go:292`) or from the CLI. If a record's slug changes and the job runs before the `RecordSaved` listener's transaction, the listener sees `entry.URL == url` and no 301 is created. This happens with an after-commit listener racing a worker, or with any write path that does not emit `RecordSaved`. The old URL then 404s with no trace in history.
|
||||
**Fix:** In `refreshEntry`, when an existing entry's URL differs from `l.URL` and the record is published, call `AddressChanged` (with via auto) instead of overwriting, or leave `url` untouched and let the listener or SEO tab own it. Only fill `url` when it is empty.
|
||||
|
||||
### Info
|
||||
|
||||
### IN-07: [IN-B01] The `regexCache` / `globCache` maps are never evicted
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/redirects.go:45-72`; `classes/urls.go:13-29`
|
||||
**Issue:** Every distinct source compiled during a save simulation, a dry-run batch, an import preview or a refused (looping) save stays cached for the life of the process. The input is admin/MCP-controlled (up to 512-character regexes), so this is bounded by trusted users, but a long-running MCP agent can grow it steadily.
|
||||
**Fix:** Cache only stored rules (key by rule ID plus `updated_at`), or use a bounded LRU.
|
||||
|
||||
### IN-08: [IN-B02] CSV `unescapeCell` changes legitimate values that start with an apostrophe
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/csv.go:50-57`
|
||||
**Issue:** A stored title such as `'-Mix` is exported unescaped (it does not start with a formula character) and imported back as `-Mix`, because import strips any apostrophe followed by a formula character. Round-trips are therefore not lossless.
|
||||
**Fix:** In `escapeCell`, also prefix values that already start with `'` (so `'x` exports as `''x`), and strip exactly one apostrophe on import.
|
||||
|
||||
### IN-09: [IN-B03] The transfer token has no expiry or user binding, and the fallback key is per process
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/transfer.go:700-788`
|
||||
**Issue:** The apply token carries the file and a fingerprint but no issue time or admin ID, so it can be replayed by any SEO manager at any later time while the data is unchanged. Without an app key, `fallbackKey` is random per process, so with several instances behind a load balancer a preview and its apply land on different keys and fail with `token_invalid`.
|
||||
**Fix:** Add `iat` and `admin_id` to the token and check a TTL (for example 1 h) and the current principal on apply. Refuse to issue tokens when there is no app key, rather than using a per-process key.
|
||||
|
||||
### IN-10: [IN-B04] Uniqueness checks swallow query errors inside the save transaction
|
||||
|
||||
**File:** `../sm-seo-plugin/models/redirect.go:165-174`; `models/rule.go:110-119`
|
||||
**Issue:** `if err := q.Count(&count).Error; err == nil && count > 0` ignores errors. On Postgres a failed statement aborts the transaction, so the next statement fails with "current transaction is aborted", which hides the real cause. If the check is skipped, the unique constraint later surfaces as a 500 instead of `source_taken` / `url_taken`.
|
||||
**Fix:** Return the error, or map a unique-violation (23505) on create or save to the same problem key.
|
||||
|
||||
### IN-11: [IN-B05] `RenderTemplate` trims separators that belong to the content
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/templates.go:29-40`
|
||||
**Issue:** `strings.Trim(out, " \t|-–—·:,")` runs on the whole rendered string. A template that is just `%title%`, or a title such as `Q&A:` or `-20% sale`, loses its own leading or trailing characters (`Q&A`, `20% sale`).
|
||||
**Fix:** Trim only the separators adjacent to placeholders that rendered empty. For example, render each placeholder with a sentinel, collapse `sentinel+separator` runs, then remove the sentinels.
|
||||
|
||||
### IN-12: [IN-B06] Body caps do not account for JSON escaping
|
||||
|
||||
**File:** `../sm-seo-plugin/controllers/api/robots.go:103`; `controllers/api/transfer.go:105-112`
|
||||
**Issue:** `decode` truncates the body at the limit. A 500 KB robots.txt or a 900 KB CSV with many quotes or newlines exceeds the JSON body limit after escaping, so the caller gets a generic `422 The request body is invalid.` instead of `robots.too_large` or `413 too_large`.
|
||||
**Fix:** Detect truncation (read `limit+1` and compare) and answer 413 with the documented code, or size the limits from the worst-case escaped size.
|
||||
|
||||
### IN-13: [IN-B07] `/robots.txt` serves allow-all without the noindex header when the service is nil, even outside production
|
||||
|
||||
**File:** `../sm-seo-plugin/controllers/api/robots.go:20-46`
|
||||
**Issue:** When `service()` is nil (before boot), `staging` stays false and the body is `FallbackRobots` (allow all). A staging instance answering during startup gives crawlers an allow-all file, which contradicts D-22's "outside production always Disallow".
|
||||
**Fix:** When `svc == nil`, read the environment from the app config directly, or default to `NonProductionRobots` with `X-Robots-Tag: noindex, nofollow`.
|
||||
|
||||
### IN-14: [IN-B08] Self canonical and `url` are built from the decoded path
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/resolver.go:358, 476-480`
|
||||
**Issue:** `self := site + path` uses `u.Path`, which is decoded. A page at `/a%3Fb` gets canonical `https://site/a?b` (a different URL), and spaces or non-ASCII characters end up unescaped in `canonical`, `og.url` and `url`. Location headers already use `escapePath`, so canonical and redirect forms disagree.
|
||||
**Fix:** Build `self` from `escapePath(path)` in both places.
|
||||
|
||||
|
||||
_Reviewed: 2026-10-27T13:28:36Z_
|
||||
_Reviewer: Claude (msd-code-reviewer)_
|
||||
_Depth: standard_
|
||||
|
||||
---
|
||||
|
||||
## Lane C: sm-seo-plugin models, config, partials, elements, tests
|
||||
|
||||
```yaml
|
||||
phase: 32-seo-foundation
|
||||
reviewed: 2026-10-27T13:28:38Z
|
||||
depth: standard
|
||||
files_reviewed: 103
|
||||
findings:
|
||||
critical: 1
|
||||
warning: 6
|
||||
info: 9
|
||||
total: 16
|
||||
status: issues_found
|
||||
```
|
||||
|
||||
### Phase 32: Code Review Report (scope C: sm-seo-plugin models, migrations, admin YAML, partials, elements, lang, tests, README)
|
||||
|
||||
**Reviewed:** 2026-10-27T13:28:38Z
|
||||
**Depth:** standard
|
||||
**Files Reviewed:** 103
|
||||
**Status:** issues_found
|
||||
|
||||
### Summary
|
||||
|
||||
I reviewed the remaining sm-seo-plugin v0.1.0 files: GORM models and migrations, the admin list/form/filter YAML, the server-rendered `.htm` partials, the seven light-DOM custom elements, the en/pl phrasebooks, the Go and vitest suites, the build config and the README.
|
||||
|
||||
**What holds up:**
|
||||
- **Partials.** They render through cabana's `html/template` renderer (`modules/cabana/partial_render.go`). It autoescapes, refuses trusted `template.HTML*` types in view models and sanitises the output. No partial interpolates raw HTML, so I found no XSS path in the `.htm` files.
|
||||
- **Elements.** All of them build DOM with `textContent`, `createTextNode` and `setAttribute`. `innerHTML` is never used. Server-supplied links in the SERP duplicates are limited to single-slash paths.
|
||||
- **Lang files.** Both phrasebooks have the same key set (pl adds only CLDR `few`/`many` forms) and the same `:param` sets. Every `golem15.seo::lang.*` key the Go, YAML and `.htm` files reference exists.
|
||||
|
||||
**The one blocker is cross-module.** The SERP preview widget and the robots.txt tester widget both send their first `summer-action` from `connectedCallback`. The framework's `WidgetField.vue` drops that event, because it assigns `element` only after `append()`. Both elements then keep `inflight` set forever, and every later request sits in the queue. Neither widget ever works in the real admin. The plugin's vitest suite does not catch this: it dispatches `summer-result` by hand and never goes through the host. I confirmed the timing with happy-dom from `admin/node_modules`: the listener sees `element === null`.
|
||||
|
||||
The warnings cover:
|
||||
- inconsistent URL safety checks for the social image
|
||||
- a CSV round trip that changes some values
|
||||
- list filters that disagree with the runtime redirect matcher
|
||||
- an uncapped indexed rule URL
|
||||
- grammar drift between the TS and Go robots parsers
|
||||
- gaps in the element tests
|
||||
|
||||
### Critical Issues
|
||||
|
||||
### CR-04: [CR-C01] The SERP preview and the robots.txt tester deadlock: their first action is dropped by the host and `inflight` is never cleared
|
||||
|
||||
**File:** `../sm-seo-plugin/assets/src/elements/serp.ts:172-178, 217-224`; `../sm-seo-plugin/assets/src/elements/robotstester.ts:77-82, 110-117`. Root cause in the framework: `admin/src/components/form/fields/WidgetField.vue:82, 161-162`.
|
||||
|
||||
**Issue:**
|
||||
|
||||
1. Both elements call `this.request({ op: 'context' })` in `connectedCallback`. `request()` sets `this.inflight = payload` and then dispatches `summer-action` synchronously.
|
||||
2. `WidgetField.vue` registers its listener before mounting, but it runs `mountPoint.value.append(created)` (line 161) before `element = created` (line 162). `connectedCallback` runs inside `append()`.
|
||||
3. `onAction` therefore reads `const target = element` as `null` (line 82) and returns without posting, without setting `busy` and without ever dispatching `summer-result` or setting `state=error`.
|
||||
|
||||
`inflight` is only cleared in `onResult` or on `state=error`, so it stays set for the element's lifetime:
|
||||
- **`golem15-seo-serp`** (SEO tab and URL rule form) shows the skeleton with `aria-busy` forever. `scheduleDuplicates` exits early because there is no context, so no duplicate check is ever sent.
|
||||
- **`golem15-seo-robotstester`** puts every **Test URL** click into `queued`. `flush()` only runs when `busy` is removed, and `busy` is never set. The tester never answers.
|
||||
|
||||
Reproduced with happy-dom (`admin/node_modules/happy-dom`) using the same create, listen, append, assign order: the listener observes `element === null`.
|
||||
|
||||
The same deadlock happens if the element is disconnected while a request is in flight: the `summer-result` listener is removed in `disconnectedCallback`, the result is lost, and reconnecting queues behind the stale `inflight`.
|
||||
|
||||
**Fix:** Do both. In the framework, assign the element before connecting it:
|
||||
|
||||
```ts
|
||||
// WidgetField.vue onMounted
|
||||
element = created
|
||||
created.addEventListener(WIDGET_EVENT, listener)
|
||||
mountPoint.value.append(created)
|
||||
status.value = 'ready'
|
||||
```
|
||||
|
||||
In the elements, do not trust that an emitted action was taken. The host sets `busy` synchronously inside `onAction` before its first `await`, so after `dispatchEvent` returns, a missing `busy` attribute means the action was dropped:
|
||||
|
||||
```ts
|
||||
private request(payload: Payload): void {
|
||||
if (this.hasAttribute('busy') || this.inflight) { this.queued = payload; return }
|
||||
this.inflight = payload
|
||||
emit(this, 'summer-action', { payload })
|
||||
if (!this.hasAttribute('busy')) { // host did not take it
|
||||
this.inflight = null
|
||||
this.queued = payload
|
||||
setTimeout(() => this.flush(), 0) // retry once the host is wired
|
||||
}
|
||||
}
|
||||
// and defer the first request:
|
||||
connectedCallback(): void { /* ... */ queueMicrotask(() => this.request({ op: 'context' })) }
|
||||
// and reset on disconnect:
|
||||
disconnectedCallback(): void { /* ... */ this.inflight = null }
|
||||
```
|
||||
|
||||
Add a vitest case that mounts the element through a fake host with the same ordering, and a `robotstester.test.ts`. There is none today.
|
||||
|
||||
### Warnings
|
||||
|
||||
### WR-20: [WR-C01] The social image preview accepts `/\host/...`, so the admin can load an image from an attacker's host
|
||||
|
||||
**File:** `../sm-seo-plugin/assets/src/elements/image.ts:6-8`. Server side: `../sm-seo-plugin/classes/field_types.go:157-163` (`ValidURLRef`, used by `ValidImageURL`).
|
||||
|
||||
**Issue:**
|
||||
- `safeImageURL` only refuses `//`: `/^\/(?!\/)/`.
|
||||
- `ValidURLRef` likewise only refuses `//`.
|
||||
- A stored `og_image` of `/\evil.example/x.png` passes both. Browsers normalise `\` to `/` in http(s) URLs, so `<img src="/\evil.example/x.png">` in the admin loads `https://evil.example/x.png`. That leaks each viewing administrator's IP and session timing to a third party.
|
||||
- Any holder of `golem15.seo.manage`, an MCP caller or a CSV import can set the value.
|
||||
- `models.validTarget` (`models/redirect.go:192-193`) already refuses `/\`, so the two validators are inconsistent.
|
||||
|
||||
**Fix:** Refuse `/\` in both places:
|
||||
|
||||
```ts
|
||||
export function safeImageURL(url: string): boolean {
|
||||
return /^\/(?![\/\\])/.test(url) || /^https?:\/\//i.test(url)
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
if strings.HasPrefix(v, "/") {
|
||||
return !strings.HasPrefix(v, "//") && !strings.HasPrefix(v, "/\\")
|
||||
}
|
||||
```
|
||||
|
||||
### WR-21: [WR-C02] The CSV export/import round trip changes cells that already start with an apostrophe followed by a formula character
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/csv.go:43-57` (exercised by `classes/csv_test.go:60-70`; the claim is in `README.md:38`)
|
||||
|
||||
**Issue:**
|
||||
- `escapeCell` adds `'` only when the cell starts with a formula character.
|
||||
- `unescapeCell` strips a leading `'` whenever the next character is a formula character.
|
||||
- A note, title or target whose real value is `'=x`, `'-)` or `'+48…` is therefore exported unchanged and comes back on import as `=x`, `-)` or `+48…`.
|
||||
- The README promises that the import drops "again" what the export added, and `TestCSVTransfer` asserts that re-importing an export is all `unchanged`. That holds only because no test value starts with `'`. `csv_test.go` checks `unescapeCell("''=x")` but never the round trip of `'=x`.
|
||||
|
||||
**Fix:** Escape an apostrophe-led value too, so `unescapeCell` is the exact inverse:
|
||||
|
||||
```go
|
||||
func escapeCell(s string) string {
|
||||
if formulaStart(s) || (strings.HasPrefix(s, "'") && formulaStart(s[1:])) {
|
||||
return "'" + s
|
||||
}
|
||||
return s
|
||||
}
|
||||
```
|
||||
|
||||
Then add `{"/ap", "/x", "'=x"}` to the round-trip rows in `TestCSV`.
|
||||
|
||||
### WR-22: [WR-C03] The 404 "Open/Resolved" filter and the redirect "Chains" filter disagree with the runtime matcher
|
||||
|
||||
**File:** `../sm-seo-plugin/models/notfound.go:44-61`, `../sm-seo-plugin/models/redirect.go:227-265`. The same scope backs MCP `list_not_found?status=` (`controllers/api/notfound.go:116`).
|
||||
|
||||
**Issue:**
|
||||
- **`coveredSQL`** counts an entry as resolved only when an exact redirect's `source` equals the logged `url`, optionally ignoring case. The runtime also matches:
|
||||
- the source with and without a trailing slash (`trailing_slash`, on by default)
|
||||
- a source without a query against a logged URL with one (`query = ignore`)
|
||||
- patterns and regexes
|
||||
|
||||
So `/missing/` or `/missing?utm=x` stays "Open" in the admin filter and in the MCP list after a redirect for `/missing` already answers it, while the row badge says "Resolved". The pagination totals are wrong too.
|
||||
- **`chainSQL`** compares `next.source = target` literally. It misses targets written as the site's absolute URL, trailing-slash or case variants, and pattern or regex next hops, all of which the save-time check treats as chains. The "Only chains" filter therefore under-reports.
|
||||
|
||||
The code comment admits the pattern/regex gap. The trailing-slash and query gaps are not documented, and the MCP tool presents "open" as "no redirect answers the address yet".
|
||||
|
||||
**Fix:** Pick one approach:
|
||||
- Compute the status from the compiled `RedirectSet` (as the badge does) and filter by IDs.
|
||||
- Add the slash and query cases to the SQL, for example `r.trailing_slash AND rtrim(r.source,'/') = rtrim(split_part(url,'?',1),'/')` plus `r.query = 'ignore' AND r.source = split_part(url,'?',1)`.
|
||||
- Persist a `resolved_by` column that is refreshed on redirect writes.
|
||||
|
||||
Also document the remaining gap in the MCP tool's `jsonschema` text.
|
||||
|
||||
### WR-23: [WR-C04] The URL rule address is uncapped but sits in a btree UNIQUE index, so long values return 500 instead of 422
|
||||
|
||||
**File:** `../sm-seo-plugin/models/rule.go:102-121`; `../sm-seo-plugin/updates/202610270005_create_golem15_seo_rules.go:28`
|
||||
|
||||
**Issue:**
|
||||
- `Rule.Problems` checks the prefix, whitespace and `*`, but not the length.
|
||||
- `UNIQUE (url, match)` is a btree, and Postgres refuses index rows over about 2704 bytes ("index row size exceeds btree version 4 maximum"). Short highly repetitive strings may compress under the limit; random content does not.
|
||||
- A long rule URL from the admin form, MCP `create_rule`/`set_url_seo` (which falls back to a rule) or a records CSV import (a row without a record becomes a rule) therefore fails at the database with a 500. A batch or import fails as a whole with an opaque error, not a per-row refusal.
|
||||
- Redirects cap their sources at `MaxRedirectURL = 2048`; rules have no equivalent.
|
||||
|
||||
**Fix:** Mirror the redirect cap:
|
||||
|
||||
```go
|
||||
const MaxRuleURL = 2048
|
||||
if len(url) > MaxRuleURL || !strings.HasPrefix(url, "/") || ... {
|
||||
out["url"] = []Problem{{Key: errRuleURLInvalid}}
|
||||
return out
|
||||
}
|
||||
```
|
||||
|
||||
### WR-24: [WR-C05] The robots element's grammar drifts from the Go grammar, and an unparseable value is silently wiped on the next edit
|
||||
|
||||
**File:** `../sm-seo-plugin/assets/src/elements/robots.ts:39-98, 136-145`; test claim in `tests/elements/robots.test.ts:75-79`
|
||||
|
||||
**Issue:** `parseRobots` claims "the grammar is the same as `classes/robots_value.go`", but they differ in both directions:
|
||||
|
||||
| Input | TS `parseRobots` | Go `ParseRobots` |
|
||||
|---|---|---|
|
||||
| `unavailable_after:2027-02-30` | accepts (V8 `Date.parse` rolls it over to March) | refuses |
|
||||
| `max-snippet:+5` | refuses (`/^-?\d+$/`) | accepts (`strconv.Atoi`) |
|
||||
|
||||
When `set value` gets a string TS cannot parse, the element:
|
||||
- shows every group as "Inherit" (`parseRobots(next) ?? emptyRobots()`) while `current` still holds the stored value
|
||||
- serialises the empty model on the first click of any control, which silently drops every stored directive
|
||||
|
||||
Today the server normalises the values it writes, so this needs a value written outside those validators: a direct DB write or migrated legacy data. The UI still misrepresents the stored state with no warning. The vitest "refused like the Go grammar" list omits the Feb-30 case, so the drift is untested.
|
||||
|
||||
**Fix:**
|
||||
- Validate the date strictly: round-trip it through `new Date(Date.UTC(y, m-1, d))` and compare the parts.
|
||||
- Accept an optional `+` like Go, or make Go strict.
|
||||
- On a `null` parse, keep the raw value, render an "unrecognised value" note and disable the controls, or require an explicit reset, rather than showing "Inherit".
|
||||
- Add `unavailable_after:2027-02-30` to the TS malformed list.
|
||||
|
||||
### WR-25: [WR-C06] The element tests never exercise the host protocol; the tester and the image element have no tests
|
||||
|
||||
**File:** `../sm-seo-plugin/tests/elements/serp.test.ts:27-38`; no `robotstester.test.ts` or `image.test.ts` exists.
|
||||
|
||||
**Issue:**
|
||||
- The `preview()` helper appends the element, checks that `{op:'context'}` was emitted, then dispatches a `summer-result` itself. It never sets or clears `busy`, never sets `state=error`, and never models the host dropping or answering asynchronously.
|
||||
- The `inflight`/`queued`/`flush` logic in serp, robotstester and transfer is therefore untested, which is how CR-04 (CR-C01) shipped.
|
||||
- `golem15-seo-robotstester` (the queue, the `urlRequired` error, the context rebuild) and `golem15-seo-image` (upload id matching, error display, `safeImageURL`) have no tests at all.
|
||||
|
||||
**Fix:**
|
||||
- Add a small fake host to `tests/elements/` that mirrors `WidgetField.onAction`: synchronously set `busy`, resolve on a microtask, dispatch `summer-result`, then remove `busy`, with a variant that drops the first event.
|
||||
- Assert that a second request queued during `busy` is sent after `busy` clears, and that `state=error` unblocks the next request.
|
||||
- Add `robotstester.test.ts` and `image.test.ts`.
|
||||
|
||||
### Info
|
||||
|
||||
### IN-15: [IN-C01] The regex length refusal puts an untranslated English phrase into the Polish UI
|
||||
|
||||
**File:** `../sm-seo-plugin/models/redirect.go:156`
|
||||
|
||||
**Issue:** `Params{"error": "longer than 512 characters"}` is substituted into `redirects.regex_invalid`. The pl admin shows "To nie jest poprawne wyrażenie regularne: longer than 512 characters".
|
||||
|
||||
**Fix:** Add a `redirects.regex_too_long` phrase (en/pl) with `:max`, and use it here.
|
||||
|
||||
### IN-16: [IN-C02] A migration comment is stale
|
||||
|
||||
**File:** `../sm-seo-plugin/updates/202610270003_create_golem15_seo_settings.go:8-11`
|
||||
|
||||
**Issue:** The comment says "The robots.txt columns are added by a later migration", but robots.txt got its own table (`golem15_seo_robots`, migration 0008) and the settings table never gains such columns.
|
||||
|
||||
**Fix:** Delete the sentence.
|
||||
|
||||
### IN-17: [IN-C03] The SERP preview's template rendering is not single-pass like the Go renderer
|
||||
|
||||
**File:** `../sm-seo-plugin/assets/src/elements/serp.ts:44-53`
|
||||
|
||||
**Issue:** `renderTemplate` replaces placeholders one after another, so a title that contains `%site%` (or a site name that contains `%description%`) is expanded again. Go uses `strings.NewReplacer`, which runs in one pass. The preview can therefore differ from the served title, despite the comment saying "the way classes/templates.go does".
|
||||
|
||||
**Fix:** Use one pass: `tpl.replace(/%(title|description|site)%/g, (_, k) => vars[k] ?? '')`.
|
||||
|
||||
### IN-18: [IN-C04] `plural()` can throw on an unusual `ui-locale`
|
||||
|
||||
**File:** `../sm-seo-plugin/assets/src/elements/labels.ts:402-411`
|
||||
|
||||
**Issue:** `new Intl.PluralRules(locale)` is wrapped in `try`, but `new Intl.NumberFormat(locale)` in the same function is not. `uiLocaleOf` returns the first subtag of any `ui-locale` or `<html lang>` value, so an invalid tag (for example `1` or `x`) throws a `RangeError` during render and leaves the element blank.
|
||||
|
||||
**Fix:** Format the count through the existing `num()` helper, which already catches.
|
||||
|
||||
### IN-19: [IN-C05] Two test names do not describe what they assert
|
||||
|
||||
**File:** `../sm-seo-plugin/classes/owner_test.go:31`; `../sm-seo-plugin/classes/resolver_test.go:19-53`
|
||||
|
||||
**Issue:**
|
||||
- The owner case "double slashes are normalised first" asserts `ErrBadURL`, because `url.Parse("//pages//about")` reads `pages` as the host. Nothing is normalised.
|
||||
- The resolver "chains" subtests run `pick()` against layer orders the test defines itself. They do not exercise the resolver's real precedence, so a reordering in `resolver.go` would not fail them. The Postgres test covers the real path.
|
||||
|
||||
**Fix:** Rename the owner case. Either drop the synthetic chain loop or derive the chains from the resolver's actual candidate lists.
|
||||
|
||||
### IN-20: [IN-C06] The inner controls' accessible name is the machine field name
|
||||
|
||||
**File:** `../sm-seo-plugin/assets/src/elements/text.ts:85-88`; `../sm-seo-plugin/assets/src/elements/robotstxt.ts:174-177`
|
||||
|
||||
**Issue:** The host sets `field-name` to `props.field.name` (for example `seo_title`). The elements copy that into `aria-label`, so screen readers announce "seo_title" and the visible translated label is overridden.
|
||||
|
||||
**Fix:** Have the host pass a translated `field-label` attribute and use that, or rely on `aria-labelledby` pointing at the host's label id.
|
||||
|
||||
### IN-21: [IN-C07] The README test instructions skip the vitest suite, and the test script hides an empty run
|
||||
|
||||
**File:** `../sm-seo-plugin/README.md:227-236`; `../sm-seo-plugin/package.json:11`
|
||||
|
||||
**Issue:**
|
||||
- The Testing section lists `npm ci && npm run typecheck && bash scripts/check-dist.sh` but never `npm test`, so the element tests are not part of the documented gate.
|
||||
- `vitest run --passWithNoTests` makes a broken `include` glob pass silently.
|
||||
- `check-dist.sh` builds with whatever `node_modules` already exists, not the committed lockfile it claims to use.
|
||||
|
||||
**Fix:**
|
||||
- Add `npm test` to the README.
|
||||
- Drop `--passWithNoTests`.
|
||||
- Run `npm ci` unconditionally in `check-dist.sh`.
|
||||
|
||||
### IN-22: [IN-C08] Three partials are maintained twice
|
||||
|
||||
**File:** `../sm-seo-plugin/extension/_seo_effective.htm` / `controllers/rules/_seo_effective.htm`; `extension/_seo_status.htm` / `controllers/rules/_seo_status.htm`; `extension/_type_placeholders.htm` / `controllers/settings/_placeholders.htm`
|
||||
|
||||
**Issue:** These pairs are byte-identical copies, so a fix to one silently misses the other.
|
||||
|
||||
**Fix:** Keep one copy and resolve the other path to it, or add a test that asserts the pairs stay equal.
|
||||
|
||||
### IN-23: [IN-C09] The `disabled` branches in the widget elements are dead, and would be broken if reached
|
||||
|
||||
**File:** `../sm-seo-plugin/assets/src/elements/transfer.ts:265, 296, 378`; `robotstester.ts` `syncControls`; `styles.css:805-809`
|
||||
|
||||
**Issue:**
|
||||
- `WidgetField.vue` never sets a `disabled` attribute on widget elements (only `PluginField` does), so these branches never run.
|
||||
- If they did, `golem15-seo-transfer .seo-transfer__actions { display: flex }` would override the `hidden` attribute, and the Discard and Apply buttons would stay visible (though inert).
|
||||
|
||||
**Fix:** Remove the dead branches. If they are kept, add `[hidden] { display: none }` rules for the affected classes, as `.seo-robots__panel[hidden]` already has.
|
||||
|
||||
|
||||
_Reviewed: 2026-10-27T13:28:38Z_
|
||||
_Reviewer: Claude (msd-code-reviewer)_
|
||||
_Depth: standard_
|
||||
56
.planning/phases/32-seo-foundation/32-UAT.md
Normal file
56
.planning/phases/32-seo-foundation/32-UAT.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
status: testing
|
||||
phase: 32-seo-foundation
|
||||
source: [32-VERIFICATION.md]
|
||||
started: 2026-10-27T15:12:00.387Z
|
||||
updated: 2026-10-27T15:12:00.387Z
|
||||
---
|
||||
|
||||
## Current Test
|
||||
|
||||
number: 1
|
||||
name: MVP user-flow walk-through in the demo admin, built from the CURRENT (unreleased) heads: framework 6472f28, sm-seo-plugin ad419e9, sm-journal-plugin a6fc7cd. Open a Journal post, then a category, then a tag; open the SEO tab; watch the SERP preview load; fill title, description and keyphrase; save; change the post's slug and save; open SEO > Redirects; open SEO > robots.txt, edit, and use the tester; open Settings > SEO and check the per-type tabs. Then GET /_seo/api/v1/resolve?url=<old and new post URL>.
|
||||
expected: |
|
||||
The SEO tab shows on posts, categories and tags. The SERP preview leaves its skeleton and shows the card, counters and duplicate warnings. Saving shows values back. The slug change shows the redirects.auto_created notice and a 301 old->new row appears. The robots tester answers allowed/blocked with the matching line. Settings shows General, one tab per content type, Indexing, Addresses, Verification. Resolve answers redirect 301 for the old URL and the effective SEO with sources for the new one. Also check the E1 320px and E2 360px layout items above.
|
||||
awaiting: user response
|
||||
|
||||
## Tests
|
||||
|
||||
### 1. MVP user-flow walk-through in the demo admin, built from the CURRENT (unreleased) heads: framework 6472f28, sm-seo-plugin ad419e9, sm-journal-plugin a6fc7cd. Open a Journal post, then a category, then a tag; open the SEO tab; watch the SERP preview load; fill title, description and keyphrase; save; change the post's slug and save; open SEO > Redirects; open SEO > robots.txt, edit, and use the tester; open Settings > SEO and check the per-type tabs. Then GET /_seo/api/v1/resolve?url=<old and new post URL>.
|
||||
expected: The SEO tab shows on posts, categories and tags. The SERP preview leaves its skeleton and shows the card, counters and duplicate warnings. Saving shows values back. The slug change shows the redirects.auto_created notice and a 301 old->new row appears. The robots tester answers allowed/blocked with the matching line. Settings shows General, one tab per content type, Indexing, Addresses, Verification. Resolve answers redirect 301 for the old URL and the effective SEO with sources for the new one. Also check the E1 320px and E2 360px layout items above.
|
||||
result: [pending]
|
||||
|
||||
### 2. MCP session from a real Claude client linked to an admin with golem15.seo.manage: get_url_seo for a post URL; set_url_seo noindex by URL; apply_batch with dry_run true (include a redirect that would create a loop), then without the loop; undo_batch from history.
|
||||
expected: The dry run returns the diff and conflicts and writes nothing. The loop is refused with redirect_loop. The applied batch is undone as a whole. A read-only grant lists only GET tools.
|
||||
result: [pending]
|
||||
|
||||
### 3. Release decision for the post-review fixes: framework v0.5.2 (7 code commits after v0.5.1, unpushed), sm-seo-plugin v0.1.1 (20 fix commits after v0.1.0 plus a new migration, unpushed), sm-journal-plugin v0.2.6 (3 commits after v0.2.5, unpushed), then the demo bump.
|
||||
expected: Jakub decides to release or hold. Until then, the released and mounted versions carry the 4 critical findings listed under 'Goal items that depend on unreleased fixes'.
|
||||
result: [pending]
|
||||
|
||||
### 4. Confirm the meaning chosen for pact.RecordSaved.Locale in WR-02: the primary tag of the request locale, not the default content locale.
|
||||
expected: Accept, or ask for the content-locale meaning before v0.5.2 freezes it
|
||||
result: [pending]
|
||||
|
||||
### 5. Review the logic of the fixes the fixer flagged: WR-08 (exact path?query wins over path-only), WR-09 (address-change redirect validation and in-memory loop simulation), WR-19 (generation job routes an unseen URL change through AddressChanged), WR-22 (coversSQL as the SQL form of exactMatches).
|
||||
expected: The matching and redirect-graph semantics are confirmed correct. DB tests pass: TestExactRedirectKeys, TestAddressChangeGuards, TestGenerateEntries, TestCoverAndChainFilters.
|
||||
result: [pending]
|
||||
|
||||
### 6. Decide WR-03 (skipped): a failing extension Load after a successful save rolls back the whole save, and show fails the whole record.
|
||||
expected: Either accept it as a known limitation for v0.5.x, or schedule an 'extension unavailable' state (a todo or a Phase 33 or later item).
|
||||
result: [pending]
|
||||
|
||||
### 7. Judgment-tier prohibitions of 32-06: (a) nothing was pushed, tagged, deployed or posted without Jakub's go-ahead, and no version was hard-coded before the checkpoint; (b) the changelog token was never printed, copied or minted.
|
||||
expected: Confirm, based on 32-06-release-log.md. The log records 'Task 4 answer (Jakub, 2026-10-27)' before step 1 and says the token was read by the script and never printed.
|
||||
result: [pending]
|
||||
|
||||
## Summary
|
||||
|
||||
total: 7
|
||||
passed: 0
|
||||
issues: 0
|
||||
pending: 7
|
||||
skipped: 0
|
||||
blocked: 0
|
||||
|
||||
## Gaps
|
||||
264
.planning/phases/32-seo-foundation/32-VERIFICATION.md
Normal file
264
.planning/phases/32-seo-foundation/32-VERIFICATION.md
Normal file
@@ -0,0 +1,264 @@
|
||||
---
|
||||
phase: 32-seo-foundation
|
||||
verified: 2026-10-27T15:09:40Z
|
||||
status: human_needed
|
||||
score: 5/5 roadmap success criteria verified (plan must-haves: all automatable truths verified; 2 layout backstops and the UI-SPEC visual states routed to human)
|
||||
covered_files:
|
||||
- .planning/phases/32-seo-foundation/32-01-PLAN.md
|
||||
- .planning/phases/32-seo-foundation/32-01-SUMMARY.md
|
||||
- .planning/phases/32-seo-foundation/32-02-PLAN.md
|
||||
- .planning/phases/32-seo-foundation/32-02-SUMMARY.md
|
||||
- .planning/phases/32-seo-foundation/32-03-PLAN.md
|
||||
- .planning/phases/32-seo-foundation/32-03-SUMMARY.md
|
||||
- .planning/phases/32-seo-foundation/32-04-PLAN.md
|
||||
- .planning/phases/32-seo-foundation/32-04-SUMMARY.md
|
||||
- .planning/phases/32-seo-foundation/32-05-PLAN.md
|
||||
- .planning/phases/32-seo-foundation/32-05-SUMMARY.md
|
||||
- .planning/phases/32-seo-foundation/32-06-PLAN.md
|
||||
- .planning/phases/32-seo-foundation/32-06-SUMMARY.md
|
||||
- admin/src/components/form/fields/WidgetField.vue
|
||||
- modules/cabana/actions.go
|
||||
- modules/cabana/contracts.go
|
||||
- modules/cabana/crud.go
|
||||
- modules/cabana/deferred.go
|
||||
- modules/cabana/field_ml.go
|
||||
- modules/cabana/field_type.go
|
||||
- modules/cabana/field_type_upload.go
|
||||
- modules/cabana/form_extensions.go
|
||||
- modules/cabana/http.go
|
||||
- modules/cabana/partial_render.go
|
||||
- modules/cabana/record_events.go
|
||||
- modules/cabana/relation.go
|
||||
- modules/cabana/relation_child.go
|
||||
- modules/cabana/reorder.go
|
||||
- modules/pact/capabilities.go
|
||||
- modules/pact/content.go
|
||||
- modules/pact/record_events.go
|
||||
- modules/signpost/content.go
|
||||
- modules/signpost/signpost.go
|
||||
- scripts/apisurface/main.go
|
||||
- scripts/check-phase32.sh
|
||||
covered_digest: "v2:sha256:3d160533886964f919d0b009ef28fe87e9b314c89b991e50bdff020197a3e7b3"
|
||||
behavior_unverified: 2
|
||||
overrides_applied: 0
|
||||
behavior_unverified_items:
|
||||
- truth: "E1 counter line at 320px container width: status text and count wrap onto two lines without overlap (32-06 backstop)"
|
||||
test: "Open a Journal post's SEO tab in the admin, narrow the form column to about 320px, type a long SEO title"
|
||||
expected: "The status text and the character/pixel count wrap onto two lines and do not overlap"
|
||||
why_human: "tests/elements/text.test.ts asserts the CSS contract (flex, wrap, gap, no fixed width) under happy-dom, which has no layout engine; actual wrapping is not observable in the test"
|
||||
- truth: "E2 at 360px: the two segmented groups stack and no segment label is clipped in either language (32-06 backstop)"
|
||||
test: "Open the SEO tab's robots control at about 360px width in en and in pl"
|
||||
expected: "Index and Follow groups stack on separate lines; no segment label is clipped"
|
||||
why_human: "tests/elements/robots.test.ts checks the wrap rules, not rendered geometry"
|
||||
human_verification:
|
||||
- test: "MVP user-flow walk-through in the demo admin, built from the CURRENT (unreleased) heads: framework 6472f28, sm-seo-plugin ad419e9, sm-journal-plugin a6fc7cd. Open a Journal post, then a category, then a tag; open the SEO tab; watch the SERP preview load; fill title, description and keyphrase; save; change the post's slug and save; open SEO > Redirects; open SEO > robots.txt, edit, and use the tester; open Settings > SEO and check the per-type tabs. Then GET /_seo/api/v1/resolve?url=<old and new post URL>."
|
||||
expected: "The SEO tab shows on posts, categories and tags. The SERP preview leaves its skeleton and shows the card, counters and duplicate warnings. Saving shows values back. The slug change shows the redirects.auto_created notice and a 301 old->new row appears. The robots tester answers allowed/blocked with the matching line. Settings shows General, one tab per content type, Indexing, Addresses, Verification. Resolve answers redirect 301 for the old URL and the effective SEO with sources for the new one. Also check the E1 320px and E2 360px layout items above."
|
||||
why_human: "Visual rendering and the real WidgetField host. CR-04 showed that the fake-host element tests missed a real-admin deadlock in the released v0.5.1 + v0.1.0, so the fix (framework d660cd0 and plugin 3ecbd1f) has never been observed in a real browser."
|
||||
- test: "MCP session from a real Claude client linked to an admin with golem15.seo.manage: get_url_seo for a post URL; set_url_seo noindex by URL; apply_batch with dry_run true (include a redirect that would create a loop), then without the loop; undo_batch from history."
|
||||
expected: "The dry run returns the diff and conflicts and writes nothing. The loop is refused with redirect_loop. The applied batch is undone as a whole. A read-only grant lists only GET tools."
|
||||
why_human: "External client (32-VALIDATION.md manual-only row). TestSEOToolsCatalog and TestMCPSetURLSeoTracer prove the catalog and the routes, not a live client session."
|
||||
- test: "Release decision for the post-review fixes: framework v0.5.2 (7 code commits after v0.5.1, unpushed), sm-seo-plugin v0.1.1 (20 fix commits after v0.1.0 plus a new migration, unpushed), sm-journal-plugin v0.2.6 (3 commits after v0.2.5, unpushed), then the demo bump."
|
||||
expected: "Jakub decides to release or hold. Until then, the released and mounted versions carry the 4 critical findings listed under 'Goal items that depend on unreleased fixes'."
|
||||
why_human: "Pushing and tagging need Jakub's go-ahead (CLAUDE.md)."
|
||||
- test: "Confirm the meaning chosen for pact.RecordSaved.Locale in WR-02: the primary tag of the request locale, not the default content locale."
|
||||
expected: "Accept, or ask for the content-locale meaning before v0.5.2 freezes it"
|
||||
why_human: "Public API semantics inside a patch release; the fixer flagged it for human confirmation."
|
||||
- test: "Review the logic of the fixes the fixer flagged: WR-08 (exact path?query wins over path-only), WR-09 (address-change redirect validation and in-memory loop simulation), WR-19 (generation job routes an unseen URL change through AddressChanged), WR-22 (coversSQL as the SQL form of exactMatches)."
|
||||
expected: "The matching and redirect-graph semantics are confirmed correct. DB tests pass: TestExactRedirectKeys, TestAddressChangeGuards, TestGenerateEntries, TestCoverAndChainFilters."
|
||||
why_human: "Semantic correctness of matching and graph rules beyond what the tests encode (32-REVIEW-FIX.md asks for a human review)."
|
||||
- test: "Decide WR-03 (skipped): a failing extension Load after a successful save rolls back the whole save, and show fails the whole record."
|
||||
expected: "Either accept it as a known limitation for v0.5.x, or schedule an 'extension unavailable' state (a todo or a Phase 33 or later item)."
|
||||
why_human: "Needs a design decision (32-REVIEW-FIX.md, Skipped Issues)."
|
||||
- test: "Judgment-tier prohibitions of 32-06: (a) nothing was pushed, tagged, deployed or posted without Jakub's go-ahead, and no version was hard-coded before the checkpoint; (b) the changelog token was never printed, copied or minted."
|
||||
expected: "Confirm, based on 32-06-release-log.md. The log records 'Task 4 answer (Jakub, 2026-10-27)' before step 1 and says the token was read by the script and never printed."
|
||||
why_human: "unverified-prohibition, human review recommended. The verifier's verdict (consistent with the release log) is a non-authoritative LLM judgment."
|
||||
---
|
||||
|
||||
# Phase 32: SEO foundation Verification Report
|
||||
|
||||
**Phase Goal:** As a site editor on any SummerCMS application, I want per-record and global SEO in the admin, with redirects and robots.txt, all manageable through MCP, so that every site ships correct, editable SEO without per-site work. The framework gains only generic seams; the SEO code lives in a new shared plugin.
|
||||
**Verified:** 2026-10-27T15:09:40Z
|
||||
**Status:** human_needed
|
||||
**Re-verification:** No (initial verification)
|
||||
**Mode:** mvp
|
||||
|
||||
**MVP format note:** `user-story.validate` answers `valid: false` ("Story must include ', I want to [capability],'"). The goal reads "I want per-record and global SEO …" with no "to". The narrowing rule was still applied, using the `[outcome]` clause ("every site ships correct, editable SEO without per-site work"), because the roadmap SCs give a precise contract. To meet the canonical regex, reword the goal through `/msd mvp-phase 32`, for example "I want to manage per-record and global SEO …".
|
||||
|
||||
## User Flow Coverage
|
||||
|
||||
| # | Step of the story | Expected | Evidence in codebase | Status |
|
||||
|---|---|---|---|---|
|
||||
| 1 | The editor opens a record of any registered content type | The SEO tab is there, and the content plugin does not import the SEO plugin | `extensions.go:27` builds one form extension per `reg.ContentTypes()`; Journal declares 3 `Content: &pact.ContentDescriptor` (`classes/menu_item_types.go:124,148,182`); marker stage: "journal: imports neither sm-seo-plugin nor sm-sitemap-plugin"; demo `TestSEOTabMounted` passes for posts (tabs Edit, Manage, Categories, SEO), categories and tags | ✓ |
|
||||
| 2 | The editor edits per-record and global SEO | Values stored per (model type, record id, locale); settings with per-type tabs | `TestSEOTabTracer`, `TestSEOTab`, `TestSettingsTypeTabs`, `TestSEOTabPermission` pass (Docker) | ✓ (visual: human) |
|
||||
| 3 | The frontend asks for the effective SEO of a URL | URL rule > record > global > derived, with sources | `GET /_seo/api/v1/resolve` → `Resolver.Resolve` (`controllers/api/resolve.go:31`); `TestResolverPrecedence` (unit, all layer masks, plus DB) passes | ✓ |
|
||||
| 4 | The editor changes a slug | 301 old→new, chains flattened, loops refused | `TestSlugChange301`, `TestRedirectGraph` (back-and-forth), `TestAddressChangeFromEvent`, `TestLoopRefused` (admin, MCP, batch, import) pass | ✓ |
|
||||
| 5 | The editor manages robots.txt and the AI bots | Served file, tester, staging lock, 11 bots incl. Claude-User | `TestRobotsServed`, `TestRobotsTester`, `TestRobotsMatcherGoogleExamples`, `classes/bots.go:27-37` | ✓ (tester in a real admin: human, CR-04) |
|
||||
| 6 | An agent does all of it through MCP | One tool per admin operation, dry run, undo | 29 tools in `mcp.go`; `TestEveryAdminOperationHasTool` derives the operations from the admin controllers; `TestBatch`, `TestUndo`, `TestConcurrentUndo`; demo `TestSEOToolsCatalog` passes | ✓ (live client: human) |
|
||||
| Outcome | "every site ships correct, editable SEO without per-site work" | The plugin mounts by `summer.yaml` alone; the framework stays generic | The demo mounts `golem15.seo` with no app code beyond the mount (`9451b31`, generated `plugins.gen.go`); marker: no SEO names under `modules/` or `docs/`. Frontend emission of the tags (Nuxt layer) is Phase 33 (D-97) by design | ✓ (backend side) |
|
||||
|
||||
## Goal Achievement
|
||||
|
||||
### Observable Truths (Roadmap Success Criteria)
|
||||
|
||||
| # | Truth | Status | Evidence |
|
||||
|---|---|---|---|
|
||||
| SC-1 | A plugin can add a field between two fields of another plugin's admin form (A, B plus C after A renders A, C, B), and add a tab between two existing tabs; unknown anchors, duplicate names and anchor cycles stop the boot with a clear error | ✓ VERIFIED | `compileFormExtensions(reg, plugins)` is wired at `modules/cabana/http.go:120`. I ran the following in this session: `TestFormExtensionPlacement` (subtests `C_after_A_gives_A_C_B`, `a_new_tab_between_two_tabs`, `a_tab-less_form_gains_the_default_tab_then_the_new_tab`), `TestFormExtensionBootErrors` (`unknown_field_anchor`, `unknown_tab_anchor`, `duplicate_field_name_*`, `duplicate_tab_key_*`, `an_anchor_cycle`, `an_anchor_outside_Requires()`, `a_fileupload_field`, zone refusals) and both matrices: all pass. `TestFormExtensionTracer` (Postgres) asserts the schema `[a c b]` and that the owner row is unchanged. The SPA backstop (FormView.test.ts, "form extensions in compiled order (UI-SPEC C1, D-91)") passes. |
|
||||
| SC-2 | Journal posts, categories and tags show the SEO tab without importing `sm-seo-plugin`, and the frontend gets the effective SEO of any URL with the precedence URL rule > record > global > derived | ✓ VERIFIED | Demo `TestSEOTabMounted` (tagged) passes for posts, categories and tags. The marker stage passes the Journal import check. `TestResolverPrecedence` enumerates every layer mask per value. Note: per P-14 (32-03-PLAN), the per-type and general templates form the "global" layer above content, while the site-wide default description and default image are last-resort fallbacks after content. The approved UI-SPEC copy `settings.default_description_comment` states this. It is a documented reading of D-02, not a deviation. |
|
||||
| SC-3 | Changing a record's slug creates a 301 and flattens existing chains; redirect loops are refused from the admin, MCP and imports | ✓ VERIFIED | Behavioral: `TestSlugChange301` (auto_created notice, 301 old→new, /pages/x flattened, pl locale), `TestAddressChangeFromEvent` (writers outside the admin), the back-and-forth case in `classes/redirect_graph_test.go:87` and `redirects_test.go:293`, and `TestLoopRefused` (admin 422 redirects.loop with nothing saved; MCP `redirect_loop`; MCP batch; CSV import preview `row_loop` and apply `import_refused`). Post-review hardening: `TestAddressChangeGuards` and `TestConcurrentRedirectWrites`. All pass. |
|
||||
| SC-4 | Every SEO operation in the admin is available as an MCP tool, and a batch change can be previewed with dry-run and undone from history | ✓ VERIFIED | `TestEveryAdminOperationHasTool` derives the required operations from the admin controllers' config, actions and extensions (at least 20 operations) and checks that each one maps to a declared tool bound to a registered `/_seo/api/v1/` route. `TestMCPReadToolsAreGET` passes. All 29 management handlers go through `manage()` (401 without an admin, 403 without `golem15.seo.manage`). `TestBatch` checks that a dry run leaves a snapshot of every table unchanged and that a loop refuses the whole batch. `TestUndo` covers stale, loop, gone and batch cases, and `TestConcurrentUndo` passes. |
|
||||
| SC-5 | The framework release with the seams is tagged, and the new code has unit tests, delivered in the phase's last plan | ✓ VERIFIED | `v0.5.1` (tag object aa6e0a5, commit 15b0d0d) is on origin (`git ls-remote` confirmed); `v0.1.0` (9cf0447) and `v0.2.5` are on origin; the demo go.mod requires all three and its submodules are at those tags. The 32-06 unit tests exist and pass: cabana matrices, `TestRecordEventDiff`, signpost `TestContent`, plugin `./classes` (resolver, graph, normalise, robots, templates, CSV, owner, issues) and 77 vitest element tests. |
|
||||
|
||||
**Score:** 5/5 roadmap success criteria verified (0 present-but-behavior-unverified among the SCs).
|
||||
|
||||
### Plan must-haves (summary)
|
||||
|
||||
| Plan | Truths | Result |
|
||||
|---|---|---|
|
||||
| 32-01 (D-91 seam) | 15 incl. 1 backstop | All verified by `TestFormExtension*` (unit and Postgres) and the FormView C1 backstop. "admin/src unchanged by this plan" holds at v0.5.1 (`git diff v0.5.0 v0.5.1 -- admin/src` is empty). WidgetField.vue changed later in the CR-04 fix, outside this plan. |
|
||||
| 32-02 (D-92, D-93, Journal) | 11 | Verified: `TestRecordEvents` (create, update, translated slug, rollback, failing listener, reorder, child write, hasMany link and unlink, deferred children, delete, bulk delete), `TestRecordSavedDescribesNewURL`, `TestAPIRecordEvents`, `TestContentDescriptors(Matrix)`, `TestJournalTagType(Pages)`, `TestTranslatedSlug`. |
|
||||
| 32-03 (plugin core) | 32 | Server-side truths verified (`TestSEOTabTracer`, `TestSEOTab`, `TestSEOTabPermission`, `TestSettingsTypeTabs`, `TestResolverPrecedence`, `TestHistoryRecordsAdminWrite`, `TestEntryDeletedWithRecord`, `TestGenerateEntries`, `TestRuleFormPreview`). The UI-SPEC visual states (skeletons, callouts, badges, truncation) go to the human walk-through. |
|
||||
| 32-04 (redirects, 404, robots) | 21 | Verified: `TestRedirectEngine`, `TestExactRedirectKeys`, `TestNormalize(Matrix)`, `TestStrictURL`, `TestOneHop`, `TestNotFoundLog`, `TestRobotsServed`, `TestRobotsTester`, `TestRobotsScreen`, `TestVerificationFile`, `TestCoverAndChainFilters`. No root route for verification files (`routes.go:36-41`). The staging lock reads only `cfg.Environment()` (`classes/resolver.go:143`). The UI list and screen visuals go to human. |
|
||||
| 32-05 (MCP, batch, CSV, gate) | 14 | Verified: `TestMCPSetURLSeoTracer`, `TestManagementAPI`, `TestIssues` (8 kinds in `classes/issues.go:15-23`), `TestCSVTransfer`, `TestBatch`, `TestUndo`. The demo mount was later done for real (`9451b31`). `check-phase32.sh` has every stage. |
|
||||
| 32-06 (tests, release) | 8 plus 8 backstops | 6 backstops verified by passing vitest (E1 thresholds, E2 grammar, E3 title and truncation, E4 lint per rule, E6 gating, E3 stem matching). 2 layout backstops (E1 320px, E2 360px) are ⚠️ PRESENT_BEHAVIOR_UNVERIFIED. Release truths verified against git and the release log. |
|
||||
|
||||
### Prohibitions
|
||||
|
||||
| Prohibition | Tier | Disposition |
|
||||
|---|---|---|
|
||||
| No breaking framework API change (32-01, 32-02, 32-06) | test | ✓ `check-phase32.sh --additive` passes (HEAD vs v0.5.1: +0 lines in cabana, pact, signpost). The release log records v0.5.1 vs v0.5.0: +2, +87, +8 lines, nothing removed. The self-test proves the stage refuses removals, signature changes and new interface methods. `--compat`: 23 siblings OK. |
|
||||
| Extensions never write owner columns, translation rows or attachments | test | ✓ `TestFormExtensionTracer` (owner row asserted), `a_fileupload_field` boot error |
|
||||
| Framework and docs name no SEO concept or consuming app (D-90) | test | ✓ marker stage |
|
||||
| No record event for an uncommitted write | test | ✓ `TestRecordEvents/rollback` |
|
||||
| Content plugins never import sm-seo-plugin; SEO data not in content tables | test | ✓ marker stage; `golem15_seo_entries` table |
|
||||
| Resolver never answers unpublished SEO and never uses the Host header | test | ✓ `a_draft_is_not_found`; no `r.Host` use in the plugin |
|
||||
| Non-production lock not switchable from admin or MCP | test | ✓ `Staging()` reads only the environment; `the_staging_lock` |
|
||||
| Loops never saved (admin, MCP, import) | test | ✓ `TestLoopRefused` |
|
||||
| /robots.txt never 5xx | test | ✓ `TestRobotsServed` (see IN-13 in Anti-Patterns) |
|
||||
| Regex capture or query never makes an internal target external | test | ✓ `redirects_test.go:314-328`, `:423` |
|
||||
| Batch or import never partial | test | ✓ `TestBatch`, `TestLoopRefused/import` |
|
||||
| Read grant can't write; every management route needs golem15.seo.manage | test | ✓ `TestMCPReadToolsAreGET`; all 29 handlers wrap `manage()` |
|
||||
| Undo never silently overwrites a newer change | test | ✓ `TestUndo` (undo_stale), `TestConcurrentUndo` |
|
||||
| Nothing pushed, tagged or posted without Jakub's go-ahead | judgment | ⚠️ flagged (unverified-prohibition, human review recommended). The LLM verdict is that the release log is consistent with it. |
|
||||
| Changelog token never printed, copied or minted | judgment | ⚠️ flagged (same) |
|
||||
|
||||
### Required Artifacts
|
||||
|
||||
| Artifact | Status | Details |
|
||||
|---|---|---|
|
||||
| `modules/pact/capabilities.go` (`Form *AdminFormExtension`) | ✓ VERIFIED | line 436; types at line 518 and onward |
|
||||
| `modules/cabana/form_extensions.go` | ✓ VERIFIED | 1591 lines; compile, placement, save and hydrate |
|
||||
| `modules/pact/record_events.go`, `content.go` | ✓ VERIFIED | RecordSaved, RecordDeleted, ContentDescriptor |
|
||||
| `modules/cabana/record_events.go` | ✓ VERIFIED | `EmitRecordSaved`; emitted at `crud.go:971` inside the save transaction (after commit) |
|
||||
| `modules/signpost/content.go` | ✓ VERIFIED | `MatchPath` and the rest; `TestContent` |
|
||||
| `../sm-journal-plugin/classes/content_descriptors.go` | ✓ VERIFIED | 3 descriptors wired in `menu_item_types.go` |
|
||||
| `../sm-seo-plugin/*` (plugin.go, extensions.go, classes/resolver.go, migrations, assets/dist/seo.js, mcp.go, operations.go, classes/batch.go, classes/undo.go, classes/redirect_graph.go, classes/addresses.go, classes/robots.go) | ✓ VERIFIED | All present and substantive; `check-dist.sh`: "assets/dist matches a fresh build" |
|
||||
| `.planning/notes/2026-10-27-robots-txt-grobotstxt.md` and the STACK.md row | ✓ VERIFIED | D-99 |
|
||||
| `scripts/check-phase32.sh`, `scripts/apisurface/main.go` | ✓ VERIFIED | `--all` exit 0 in this session |
|
||||
| `32-05-demo-mount.patch`, `../sm-demo-app/seo_mcp_test.go` | ✓ VERIFIED | applied in `9451b31`; `TestSEOToolsCatalog` passes |
|
||||
|
||||
### Key Link Verification
|
||||
|
||||
| From | To | Via | Status |
|
||||
|---|---|---|---|
|
||||
| cabana `http.go` | `form_extensions.go` | `compileFormExtensions(reg, plugins)` (line 120) | ✓ WIRED |
|
||||
| cabana `crud.go` | the extension's Save | `saveFormExtensions` in the save transaction (line 965) → `ext.def.Save(ctx, pact.AdminFormSave{…})` (form_extensions.go:1394) | ✓ WIRED |
|
||||
| cabana `crud.go` | `record_events.go` | `emitRecordSaved(ctx, s.app, tx, …)` (line 971) | ✓ WIRED |
|
||||
| docs/backend/admin-controllers.md | example_form_extension_test.go | `src=` snippet (line 561); docs stage passes | ✓ WIRED |
|
||||
| Journal `controllers/api/posts.go` | `cabana.EmitRecord*` | lines 237, 239, 305, 307, 349 | ✓ WIRED |
|
||||
| Journal `menu_item_types.go` | `pact.ContentDescriptor` | `Content: &pact.ContentDescriptor` ×3 | ✓ WIRED |
|
||||
| seo `extensions.go` | signpost `ContentTypes()` | line 27 | ✓ WIRED |
|
||||
| seo `controllers/api/resolve.go` | `Resolver.Resolve` | line 31 | ✓ WIRED |
|
||||
| seo `listeners.go` | `*pact.RecordDeleted` / `*pact.RecordSaved` | lines 23, 30; `AddressChanged` at line 65 | ✓ WIRED |
|
||||
| seo `extensions.go` | `AddressChanged` | line 337 (in the save transaction) | ✓ WIRED |
|
||||
| seo `routes.go` | `/robots.txt` | line 33, throttled, with no backend middleware | ✓ WIRED |
|
||||
| seo `mcp.go` | `routes.go` | every tool's Method+Path is a registered route (parity test) | ✓ WIRED |
|
||||
| `check-phase32.sh` | apisurface / Journal worktree compat | additive and compat stages pass | ✓ WIRED |
|
||||
| `sm-demo-app/go.mod` | sm-seo-plugin | `sm-seo-plugin v0.1.0`; submodule at b19cd06 (v0.1.0) | ✓ WIRED |
|
||||
|
||||
### Data-Flow Trace (Level 4)
|
||||
|
||||
| Artifact | Data | Source | Real data | Status |
|
||||
|---|---|---|---|---|
|
||||
| SEO tab fields | entry values | extension Load/Save on `golem15_seo_entries` in the owner transaction | yes (`TestSEOTabTracer`) | ✓ FLOWING |
|
||||
| `/resolve` answer | effective SEO plus sources | rules, entries, type settings, settings and signpost Describe (DB) | yes (`TestResolverPrecedence` DB part) | ✓ FLOWING |
|
||||
| E3 SERP preview | context and duplicates | widget actions → plugin `Run` → DB | yes in tests through a fake host; real host per the CR-04 fix (human) | ✓ FLOWING (real-host: human) |
|
||||
| MCP tools | all SEO data | `/_seo/api/v1` handlers → classes.Service → DB | yes (`TestManagementAPI`) | ✓ FLOWING |
|
||||
|
||||
### Behavioral Spot-Checks and Probe Execution (run in this session)
|
||||
|
||||
| Check | Command | Result | Status |
|
||||
|---|---|---|---|
|
||||
| Seam unit tests | `go test -short ./modules/cabana ./modules/signpost ./modules/pact -run 'TestFormExtension\|TestRecordEventDiff\|TestRecordEventLocale\|TestContent'` | ok | ✓ PASS |
|
||||
| Seam Postgres tests | `go test ./modules/cabana -run 'TestFormExtensionTracer\|…Save\|…Required\|…Upload\|TestRecordEvents'` | 5 top-level, 19 subtests PASS | ✓ PASS |
|
||||
| Journal | `go test ./... -run 'TestContentDescriptors\|TestJournalTagType\|TestTranslatedSlug\|TestAPIRecordEvents\|TestRecordSavedDescribesNewURL'` | 8 PASS | ✓ PASS |
|
||||
| sm-seo-plugin full suite (Docker) | `go test -count=1 ./...` | 55 top-level PASS, 0 FAIL | ✓ PASS |
|
||||
| Plugin elements | `npm run test` + typecheck + `scripts/check-dist.sh` | 77/77; dist matches | ✓ PASS |
|
||||
| Admin SPA | `npm --prefix admin run test -- FormView WidgetField` | 84/84 | ✓ PASS |
|
||||
| Demo mount | `go test -tags summercms_mcp -run 'TestGoModRequiresTags\|TestSEOTabMounted\|TestSEOToolsCatalog' .` | 3 PASS | ✓ PASS |
|
||||
| Phase gate (probe) | `bash scripts/check-phase32.sh --all` | exit 0, "Phase 32 gate passed" (self-test, go, plugins, consumers, admin, docs, marker, additive vs v0.5.1, compat across 23 siblings, docker) | ✓ PASS |
|
||||
|
||||
### Requirements Coverage
|
||||
|
||||
REQUIREMENTS.md has no IDs for this phase. The plans declare 51 IDs, and each is accounted for against 32-DECISIONS-MAP.md:
|
||||
|
||||
| IDs | Source plans | Status | Evidence |
|
||||
|---|---|---|---|
|
||||
| SC-1..SC-5 | 32-01..32-06 | ✓ SATISFIED | table above |
|
||||
| D-90, D-91, D-92, D-93, D-98, D-100, D-101, D-104, D-106 | 32-01, 32-02, 32-06 | ✓ SATISFIED | seams, marker, additive and compat, boot errors (zone, fileupload), settings `AdminSingleton` (`controllers/settings.go:134`) |
|
||||
| D-94, D-95, D-96, D-102, D-58 | 32-02, 32-03 | ✓ SATISFIED | D-95's Phase 32 part: `Requires()` returns nil (`plugin.go:51`); Journal descriptors, journal-tag and API events; translated slug |
|
||||
| D-01..D-09, D-13, D-15, D-21, D-23 | 32-03 | ✓ SATISFIED | entries table, rules, settings, resolver, robots grammar, the one permission, SERP and counters (real-host rendering: human) |
|
||||
| D-05, D-06, D-08, D-16..D-20, D-20a/b/c, D-22, D-24, D-25, D-99, D-103, D-105 | 32-04 | ✓ SATISFIED | redirect engine, 404 log, normalise, strict, robots and tester, bots incl. Claude-User, verification API only |
|
||||
| D-10..D-14, D-19 | 32-05 | ✓ SATISFIED | 29 tools, owner resolution, batch, undo, CSV, issues |
|
||||
| Q-01 | 32-06 | ✓ SATISFIED | patch tag v0.5.1 computed at release |
|
||||
|
||||
Orphaned: none. Every map ID with a Phase 32 column entry appears in a plan's `requirements`. Phase-33-only IDs (D-30..D-34, D-40..D-46, D-50..D-57, D-70..D-72, D-80..D-86, D-97) are out of scope by design.
|
||||
|
||||
### Goal items that depend on unreleased fixes
|
||||
|
||||
The released and mounted set is framework v0.5.1, sm-seo-plugin v0.1.0, Journal v0.2.5 and sm-demo-app 9451b31. Everything above was verified at the local heads, which carry the review fixes (unpushed: framework 16 commits after v0.5.1, of which 7 are code; sm-seo-plugin 21 after v0.1.0; Journal 3 after v0.2.5). In the released versions:
|
||||
|
||||
| Goal item | Finding | Released behavior | Fixed in (unreleased) |
|
||||
|---|---|---|---|
|
||||
| SERP preview (D-09, E3) and robots.txt tester (D-22, E5) in the real admin | CR-04 | Deadlock: the skeleton shows forever and the tester never answers | framework d660cd0 (WidgetField.vue and the dist), plugin 3ecbd1f (ActionQueue with retry). Either release alone fixes it. |
|
||||
| Exact redirects (D-16, D-17, SC-3 runtime) | CR-03 | Sources with a trailing slash or a mixed-case query never fire | plugin 2d81c26 plus the new migration `202610280001_add_golem15_seo_redirects_source_key` |
|
||||
| Loops refused on every path (SC-3, D-19) | WR-09, WR-10 | Address-change 301s skip validation and the loop simulation; the loop check races | plugin cb614cb, c2f136a |
|
||||
| Slug change through Journal API or MCP fires the event (SC-3, D-102) | WR-04, WR-06 | A slug can commit with no RecordSaved on a failing association; auto-created tags fire nothing | Journal 62c75b1, a6fc7cd (WR-05: 7a03640) |
|
||||
| Generation job keeps the 301 (SC-3) | WR-19 | The job can overwrite entry.URL and swallow an address change | plugin d8aa989 |
|
||||
| Undo (SC-4) | WR-11 | Concurrent undo is not idempotent | plugin d20f14f |
|
||||
| MCP/import validation (SC-4) | WR-16, WR-17, WR-18, WR-23 | Invalid values are silently coerced or answer 500 | plugin c8e0961, 24e6f38, cff2d29, 4ca26e9 |
|
||||
| D-91 seam generality (SC-1) | CR-01, CR-02, WR-07 | `required` extension fields break host saves; uploads ignore extension visibility; hidden fields' relation and partial routes stay reachable | framework 676ca53, 5471b66, 0e187cf. The SEO plugin itself is not exposed: it declares no `required` fields, and its `seoimage` Upload checks `golem15.seo.manage` itself (32-03 deviation 6). |
|
||||
| D-92 coverage | WR-01, WR-02 | hasMany link/unlink and deferred children fire no events; Locale is inconsistent | framework 468af06, 1583651 |
|
||||
|
||||
The additive stage shows +0 exported lines since v0.5.1, so plugin v0.1.1 needs no new framework API. However, the CR-02, WR-01 and WR-07 fixes reach consumers only through v0.5.2.
|
||||
|
||||
### Anti-Patterns Found
|
||||
|
||||
| File | Pattern | Severity | Impact |
|
||||
|---|---|---|---|
|
||||
| (all phase files in 4 repos) | TBD/FIXME/XXX | none found | — |
|
||||
| sm-seo-plugin, cabana | 23 open info findings (IN-01..IN-23, 32-REVIEW-DISPOSITION.md) | ℹ️ Info | Not blocking. Notable: IN-13 (`/robots.txt` serves allow-all without the noindex header when the service is nil, even outside production; this is an edge of the D-22 lock in a boot-failure state); IN-05 (Journal `requestLocale` drops the region, so translated slugs in region-coded locales never match, which narrows D-58); IN-09 (transfer token has no expiry or user binding) |
|
||||
| modules/cabana/crud.go:982 | WR-03 skipped | ⚠️ Warning | A failing extension Load turns a committed save into a rollback and a 500 (design decision pending) |
|
||||
| 32-VALIDATION.md | stale status | ℹ️ Info | Still `status: draft`, with 32-06-T4 and T5 rows "pending" although both completed and `--all` is green. Update it to validated. |
|
||||
| sm-seo-plugin README | WR-15 documentation-only fix | ℹ️ Info | The public throttle is site-wide unless the SSR host is in `http.trusted_proxies`; a deploy concern for Phase 33 layer integration |
|
||||
|
||||
### Human Verification Required
|
||||
|
||||
1. **MVP user-flow walk-through on the current heads.** Covers the SEO tab, SERP preview, slug-change 301, robots tester and settings tabs, plus the E1 320px and E2 360px layout. CR-04 proved that the fake-host tests can miss a real-admin failure.
|
||||
2. **Live MCP client session.** get/set by URL, dry-run batch with a loop, apply, undo the batch, check the read-only grant.
|
||||
3. **Release decision for the fixes** (v0.5.2, v0.1.1, v0.2.6, then the demo bump). The released set carries the 4 critical findings.
|
||||
4. **WR-02**: confirm the meaning of `RecordSaved.Locale`.
|
||||
5. **Logic review** of WR-08, WR-09, WR-19 and WR-22.
|
||||
6. **WR-03**: design decision.
|
||||
7. **Judgment-tier prohibitions** (release go-ahead, token handling): confirm against the release log.
|
||||
|
||||
### Gaps Summary
|
||||
|
||||
No blocking gaps. Each roadmap success criterion is backed by passing behavioral tests run in this session against the local heads of the four repositories, and the phase gate `check-phase32.sh --all` passes again (exit 0). The framework carries only generic seams (marker and additive stages), and the SEO code lives in sm-seo-plugin. Status is `human_needed` for three reasons:
|
||||
- The visual and real-host behavior of the elements has never been observed in a browser, which matters because CR-04 slipped past the element tests.
|
||||
- A live MCP client session is still to be run.
|
||||
- The released versions (v0.5.1, v0.1.0, v0.2.5, mounted in the demo) predate 28 review fixes, including 4 critical ones. The goal is met in the codebase, but sites on the released tags get a broken SERP preview and robots tester and dead trailing-slash exact redirects until the fixes are released.
|
||||
|
||||
---
|
||||
|
||||
_Verified: 2026-10-27T15:09:40Z_
|
||||
_Verifier: Claude (msd-verifier)_
|
||||
23
.planning/phases/32-seo-foundation/deferred-items.md
Normal file
23
.planning/phases/32-seo-foundation/deferred-items.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# Phase 32 deferred items
|
||||
|
||||
Work left out of plan 32-06 on purpose, each with its next command.
|
||||
|
||||
## Not named in the release go-ahead (Task 4)
|
||||
|
||||
1. **sm-grzybyfunkcjonalne-app: Journal bump.** The app requires sm-journal-plugin as a pseudo-version (`v0.0.0-00010101000000-000000000000`, through a replace) and SummerCMS v0.4.4. Journal v0.2.5 needs SummerCMS v0.5.1, and its layer has no tag pages, so the bump sets `golem15.journal.tag_pages: false`. Next, after Jakub names it:
|
||||
```sh
|
||||
cd ../sm-grzybyfunkcjonalne-app
|
||||
GOWORK=off GOPRIVATE='git.golem15.com/*' go get git.golem15.com/golem15/summercms@v0.5.1 git.golem15.com/golem15/sm-journal-plugin@v0.2.5
|
||||
git -C plugins/golem15/journal fetch --tags origin && git -C plugins/golem15/journal checkout v0.2.5
|
||||
# config: golem15.journal.tag_pages: false
|
||||
go build ./... && go test -short ./...
|
||||
git add go.mod go.sum plugins/golem15/journal <config file> && git commit -m "chore: bump journal to v0.2.5"
|
||||
```
|
||||
2. **sm-summercmsio-app: Journal bump.** The app requires sm-journal-plugin v0.1.0 and SummerCMS v0.5.0. Next, after Jakub names it: the same `go get` of `summercms@v0.5.1` and `sm-journal-plugin@v0.2.5`, the submodule checkout at v0.2.5, build and tests, commit `chore: bump journal to v0.2.5`. Decide whether the changelog site wants tag pages (`golem15.journal.tag_pages`).
|
||||
3. **Plugin release posts.** summercms.io/changelog also carries posts for plugin releases (for example "sm-sociallogin-plugin 0.1.5"). Only the framework post for v0.5.1 was named; sm-journal-plugin v0.2.5 and sm-seo-plugin v0.1.0 have no post of their own (both are listed under "Released together" in the v0.5.1 post). Next, if wanted: the same Journal API post by hand (`../sm-summercmsio-app/DEPLOY.md`, "Posting to the changelog", step 3).
|
||||
4. **Deploy.** Nothing was deployed. demo.summercms.io runs the previous demo build until a deploy per `../sm-demo-app/DEPLOY.md` (the new `location = /robots.txt` nginx block ships with it).
|
||||
|
||||
## Found during the release, not this plan's
|
||||
|
||||
- sm-demo-app: ` M plugins/golem15/oauthserver` (checked out b6a9586, recorded 8bbec72 = v0.1.2) is another session's uncommitted drift. It makes `scripts/check-pins.sh` fail in the live tree; the committed tree passes (`check-pins: ok (17 modules)` in a clean worktree). Left as found.
|
||||
- sm-demo-app: `github.com/gabriel-vasile/mimetype v1.4.15` (indirect) is retracted upstream; `go get` warns. Pre-existing; next: `GOWORK=off go get github.com/gabriel-vasile/mimetype@latest` in a dependency-bump commit.
|
||||
@@ -0,0 +1,249 @@
|
||||
---
|
||||
phase: 32.1
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- modules/pact/capabilities.go
|
||||
- modules/pact/mcp.go
|
||||
- modules/pact/mcp_call_test.go
|
||||
- modules/pact/README.md
|
||||
- modules/pier/dispatch.go
|
||||
- modules/pier/prm.go
|
||||
- modules/pier/stateless.go
|
||||
- modules/pier/mcp_seam_test.go
|
||||
- modules/pier/README.md
|
||||
- modules/wristband/authorize.go
|
||||
- modules/wristband/server.go
|
||||
- modules/wristband/consent.go
|
||||
- modules/wristband/mcp_scopes_smoke_test.go
|
||||
- modules/wristband/README.md
|
||||
- docs/services/mcp.md
|
||||
- docs/services/oauth-server.md
|
||||
- docs/services/authentication.md
|
||||
autonomous: true
|
||||
requirements: []
|
||||
estimate:
|
||||
tokens: 52000
|
||||
raw_tokens: 52000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-1: A wristband MCP server whose Options.ScopesSupported is empty advertises and accepts read, write, ai, offline_access and backend. A non-empty list is used as given, so DefaultOptions still refuses backend. OIDC discovery scopes stay openid, profile, email (D-02)."
|
||||
- "SC-1: pier protected-resource metadata copies pact.MCPAdvertisedScopes from the published verifier when that list is non-empty, and otherwise keeps PRMScopes (D-04). Pier does not read the raw member-token catalog and does not change the read/write ceiling (D-01)."
|
||||
- "SC-2: Every in-process MCP tool call carries pact.MCPCall (Subject, SessionID, Tool) set immediately before bouncer.WithDispatch. MCPCallFrom on a context without that value returns ok false (D-09, D-10, D-11)."
|
||||
- "PendingRequestView.OfflineAccess is filled from the pending row. IssueCode's signature is unchanged."
|
||||
- "pact, pier and wristband READMEs and docs/services/mcp.md, oauth-server.md and authentication.md name only identifiers this plan adds, and never a consuming application."
|
||||
artifacts:
|
||||
- path: modules/pact/mcp.go
|
||||
provides: "MemberTokenScopeCatalog, MCPAdvertisedScopes, MCPCall, WithMCPCall, MCPCallFrom"
|
||||
contains: "MemberTokenScopes"
|
||||
- path: modules/pact/capabilities.go
|
||||
provides: "FrontendTokenScope.Implies"
|
||||
contains: "Implies"
|
||||
- path: modules/pier/dispatch.go
|
||||
provides: "MCPCall set beside WithDispatch"
|
||||
contains: "WithMCPCall"
|
||||
- path: modules/pier/prm.go
|
||||
provides: "PRM scopes from the verifier or PRMScopes"
|
||||
contains: "MCPAdvertisedScopes"
|
||||
- path: modules/wristband/consent.go
|
||||
provides: "PendingRequestView.OfflineAccess"
|
||||
contains: "OfflineAccess"
|
||||
key_links:
|
||||
- from: modules/wristband/server.go Metadata
|
||||
to: modules/wristband/authorize.go allowedAuthorizeScopes
|
||||
via: one resolved scope slice
|
||||
pattern: resolvedScopes
|
||||
- from: modules/pier/prm.go
|
||||
to: pact.MCPAdvertisedScopes
|
||||
via: app.Lookup of MCPTokenVerifier then a type assert
|
||||
pattern: MCPScopesSupported
|
||||
- from: modules/pier/dispatch.go
|
||||
to: pact.MCPCallFrom
|
||||
via: WithMCPCall immediately before WithDispatch
|
||||
pattern: WithMCPCall
|
||||
---
|
||||
|
||||
<objective>
|
||||
Framework seam for SC-1 and SC-2 (D-01, D-02, D-03, D-04, D-05, D-09, D-10, D-11). Publish the catalog and advertised-scope interfaces, carry an MCP call on context, and make the wristband MCP metadata and authorize allow-list share one resolved scope list so an empty Options.ScopesSupported cannot fall back to the four-name map and drop backend.
|
||||
|
||||
Purpose: sm-user-plugin and sm-oauthserver-plugin need these types before they can advertise declared scopes or record who called a tool. The read/write ceiling and the OIDC scope list stay as they are.
|
||||
Output: pact, pier and wristband API plus the three docs pages and module READMEs. One tracer smoke. The broad unit-test pass is plan 05.
|
||||
|
||||
spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).
|
||||
|
||||
Discretion recorded here, not left open:
|
||||
- Catalog interface is pact.MemberTokenScopeCatalog with MemberTokenScopes() []FrontendTokenScope. The method is not named FrontendTokenScopes, because HasFrontendTokenScopes already has that method (D-05).
|
||||
- Advertised list is a second interface pact.MCPAdvertisedScopes with MCPScopesSupported() []string. Do not add a method to pact.MCPTokenVerifier.
|
||||
- pact.MCPCall fields are Subject pact.MCPSubject, SessionID string, Tool string. Setter is pact.WithMCPCall. Accessor is pact.MCPCallFrom (D-10).
|
||||
- MCP flavour only: empty Options.ScopesSupported resolves to read, write, ai, offline_access, backend. Metadata and allowedAuthorizeScopes both use that slice. DefaultOptions stays the non-empty four-name list and still refuses backend. TestMCPScopesSmoke's empty-slice assertion is updated in the same commit. Do not edit modules/wristband/oidc_options.go.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-CONTEXT.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-RESEARCH.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-PATTERNS.md
|
||||
@modules/pact/mcp.go
|
||||
@modules/pact/capabilities.go
|
||||
@modules/pier/dispatch.go
|
||||
@modules/pier/prm.go
|
||||
@modules/pier/stateless.go
|
||||
@modules/pier/session.go
|
||||
@modules/wristband/authorize.go
|
||||
@modules/wristband/server.go
|
||||
@modules/wristband/consent.go
|
||||
@modules/wristband/mcp_scopes_smoke_test.go
|
||||
@modules/bouncer/dispatch.go
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Tracer: one advertised scope list and one MCP call on the dispatch context</name>
|
||||
<reversibility rating="costly">D-03 and D-10 publish a scope list and a pact.MCPCall shape that later grants and callers will store and read.</reversibility>
|
||||
<files>modules/pact/capabilities.go, modules/pact/mcp.go, modules/pact/mcp_call_test.go, modules/wristband/authorize.go, modules/wristband/server.go, modules/wristband/mcp_scopes_smoke_test.go, modules/pier/dispatch.go, modules/pier/prm.go, modules/pier/stateless.go, modules/pier/mcp_seam_test.go</files>
|
||||
<read_first>
|
||||
modules/pact/capabilities.go (FrontendTokenScope at the struct that today has Name, Label, Description only)
|
||||
modules/pact/mcp.go (MCPSubject, MCPTokenVerifier, MCPGrant)
|
||||
modules/bouncer/dispatch.go (WithDispatch context key; do not copy its nil-to-background behaviour)
|
||||
modules/wristband/authorize.go (allowedAuthorizeScopes empty fallback)
|
||||
modules/wristband/server.go (Metadata copies opts.ScopesSupported; flavourMCP versus flavourOIDC)
|
||||
modules/wristband/mcp_scopes_smoke_test.go (empty slice currently expects four names and no backend)
|
||||
modules/pier/prm.go (PRMScopes and mountPRM)
|
||||
modules/pier/dispatch.go (dispatcher.run sets bouncer.WithDispatch at the credential assignment)
|
||||
modules/pier/session.go (toolHandler copies req.Session.ID into callInfo.session; ephemeralSession is the audit word)
|
||||
modules/pier/stateless.go (statelessPath.ServeHTTP)
|
||||
modules/pier/tracer_smoke_test.go (package pier_test mount helper to copy, not to rewrite)
|
||||
modules/pier/filter.go (read only: id.writes ceiling stays)
|
||||
</read_first>
|
||||
<action>
|
||||
Add the pact surface and wire one path through wristband and pier. Do not add a method to pact.MCPTokenVerifier. Do not edit modules/pier/filter.go or modules/wristband/oidc_options.go (D-01, D-02).
|
||||
|
||||
In modules/pact/capabilities.go add Implies string on FrontendTokenScope. Zero value means not implied. Update the comment that says the struct carries no permission patterns so it still says the route middleware is what enforces a member scope, and that Implies is only "", "read" or "write" for a later OAuth MCP check. Do not implement that check in this repo (D-01a is plan 02).
|
||||
|
||||
In modules/pact/mcp.go add MemberTokenScopeCatalog with MemberTokenScopes() []FrontendTokenScope, and MCPAdvertisedScopes with MCPScopesSupported() []string (D-05, D-04). Add MCPCall{Subject MCPSubject, SessionID string, Tool string}, WithMCPCall(ctx, call) context.Context and MCPCallFrom(ctx) (MCPCall, bool) (D-09, D-10). Use an unexported context key. If ctx is nil, WithMCPCall must not invent context.Background; the dispatch context is never nil. MCPCallFrom returns ok false when the value is absent, including a nil context (D-11). Leave MCPSubject's fields unchanged.
|
||||
|
||||
In wristband, add an unexported resolvedScopes on Server used by both Metadata's scopes_supported and allowedAuthorizeScopes. Non-empty Options.ScopesSupported is cloned as-is. Empty or nil, on the MCP flavour only (NewServer, flavour zero value, not flavourOIDC), resolves to exactly read, write, ai, offline_access, backend in that order. That is the fix for the four-name fallback dropping backend. Update TestMCPScopesSmoke so the empty-slice case expects those five names and accepts backend, and keep the DefaultOptions case that still refuses backend because that list is non-empty and has no backend. Do not change PKCE, client lookup, or redirect matching (Authorize still validates those before the /connect redirect).
|
||||
|
||||
In pier mountPRM, keep the issuer lookup. If the looked-up pact.MCPTokenVerifier is non-nil and also implements pact.MCPAdvertisedScopes and MCPScopesSupported() is non-empty, ScopesSupported is a clone of that slice. Otherwise keep a clone of PRMScopes (D-04). Do not import an OAuth plugin and do not read MemberTokenScopeCatalog here.
|
||||
|
||||
In dispatcher.run, immediately before the existing bouncer.WithDispatch line, set callCtx = pact.WithMCPCall(callCtx, pact.MCPCall{Subject: *subject, SessionID: sessionID, Tool: t.name}) where subject is the id.subjectFor(t.guardName) value already computed (D-11). sessionID is info.session, except the audit word ephemeralSession becomes "". Add a stateless bool on callInfo. statelessPath.ServeHTTP sets it true on the bearer token-info extraCall value, writing the struct back, before the handler runs. toolHandler copies req.Session.ID() into info.session only when that flag is false and the id is non-empty. Do not expand scopes in pier. Do not put a raw bearer or a code in a log line.
|
||||
|
||||
Tests, same commit: modules/pact/mcp_call_test.go TestMCPCallRoundTrip proves WithMCPCall then MCPCallFrom returns the same Subject.Guard, SessionID and Tool, and MCPCallFrom(context.Background()) is ok false. modules/pier/mcp_seam_test.go TestMCPSeam, package pier_test, does three things in one test: wristband.NewServer with nil ScopesSupported answers metadata scopes_supported equal to the five fixed names including backend; a server whose ScopesSupported is those five plus acme:read advertises that exact slice; a pier mounted with a fake MCPTokenVerifier that also implements MCPAdvertisedScopes advertises that slice on the protected-resource document, and one tools/call of a frontend tool reaches a handler where pact.MCPCallFrom is ok, Tool is the tool name, and bouncer dispatch is still set. A verifier that does not implement MCPAdvertisedScopes still yields PRMScopes. Commit in this repo only, staging the files listed on this task. Do not git add -A.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test -short -count=1 -run 'TestMCPCallRoundTrip|TestMCPSeam|TestMCPScopesSmoke|TestDiscoveryFields' ./modules/pact ./modules/pier ./modules/wristband</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL, or TestMCPCallRoundTrip or TestMCPSeam has no PASS line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- MCPTokenVerifier still has only MCPVerifyToken and MCPResource.
|
||||
- Empty MCP Options.ScopesSupported metadata and allow-list both include backend. DefaultOptions still refuses backend.
|
||||
- TestDiscoveryFields still expects scopes_supported openid, profile, email on the default OIDC document.
|
||||
- TestMCPSeam PASS shows a declared name on PRM only when the verifier advertises it, and one tool handler observes MCPCall.
|
||||
- filter.go and oidc_options.go have no diff in this commit.
|
||||
</acceptance_criteria>
|
||||
<done>One MCP tool call carries MCPCall, and an empty MCP scope list no longer drops backend. The commit is only the files of this task.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Expose offline_access on the pending consent view</name>
|
||||
<reversibility rating="reversible">OfflineAccess is an additive field on a view struct. IssueCode's signature stays.</reversibility>
|
||||
<files>modules/wristband/consent.go</files>
|
||||
<read_first>
|
||||
modules/wristband/consent.go (PendingRequestView and IssueCode)
|
||||
modules/wristband/authorize.go (offline_access is peeled onto the pending row, not stored in Scopes)
|
||||
</read_first>
|
||||
<action>
|
||||
Add OfflineAccess bool to PendingRequestView and set it in PendingRequest from the pending row's existing OfflineAccess flag. Do not change the IssueCode signature, MarkIssued's wristband parameters, or the redirect URL. Callers that ignore the new field stay valid. Do not treat offline_access as a scope inside wristband. Do not log codes.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test -short -count=1 ./modules/wristband</automated>
|
||||
<fails_when>non-zero exit, or the output contains FAIL</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- PendingRequestView has an exported OfflineAccess field set from the pending row.
|
||||
- IssueCode is still func (s *Server) IssueCode(ctx context.Context, requestID string, userID uint, grantedScopes []string, collectionIDs []uint) (string, error).
|
||||
</acceptance_criteria>
|
||||
<done>Consent show can see the offline_access column without a new IssueCode argument.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Document the seam in READMEs and docs</name>
|
||||
<reversibility rating="reversible">Docs follow the API added in this plan and can be rewritten with it.</reversibility>
|
||||
<files>modules/pact/README.md, modules/pier/README.md, modules/wristband/README.md, docs/services/mcp.md, docs/services/oauth-server.md, docs/services/authentication.md</files>
|
||||
<read_first>
|
||||
modules/pact/README.md
|
||||
modules/pier/README.md
|
||||
modules/wristband/README.md
|
||||
docs/services/mcp.md
|
||||
docs/services/oauth-server.md
|
||||
docs/services/authentication.md
|
||||
modules/pact/mcp.go
|
||||
modules/pier/prm.go
|
||||
</read_first>
|
||||
<action>
|
||||
Document only identifiers this plan added: MemberTokenScopeCatalog, MemberTokenScopes, MCPAdvertisedScopes, MCPScopesSupported, MCPCall, WithMCPCall, MCPCallFrom, FrontendTokenScope.Implies, PendingRequestView.OfflineAccess, and the existing PRMScopes fallback. State the D-03 rule in pier README, docs/services/mcp.md and docs/services/oauth-server.md: fixed names read, write, ai, offline_access, backend are always on the MCP advertised set; an unset host filter means every declared member scope; a set filter means only those declared names; an empty filter means the five fixed names only. Name the host config key golem15.oauthserver.mcp_scopes as the plugin key plan 03 adds. Do not document it as a framework config key. State that pier copies MCPScopesSupported when non-empty and otherwise PRMScopes (D-04). State that Subject.TokenID is a member personal-token id only when ClientID is empty, and is the OAuth access-token row otherwise, and that Subject.Scopes is the grant, not an implied expansion (D-10, D-11). State that the read/write ceiling is unchanged (D-01) and that OIDC discovery stays openid, profile, email (D-02). State that an empty MCP Options.ScopesSupported resolves to the five fixed names, while a non-empty list is used as given. Framework docs and READMEs must not name a consuming application. Config keys are not checked by the docs checker; the prose must still match the key spelling above. Commit in this repo, staging only these doc files plus any code file this task had to touch (it should touch none). Do not git add -A.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check && go vet ./modules/pact ./modules/pier ./modules/wristband && go test -short -count=1 ./modules/pact ./modules/pier ./modules/wristband</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- TestDocsTree and docs:build --check pass.
|
||||
- The three READMEs and three docs pages mention MCPCallFrom and MCPAdvertisedScopes and do not mention a consuming application by name.
|
||||
- go test -short on pact, pier and wristband passes.
|
||||
</acceptance_criteria>
|
||||
<done>SC-4 docs for the framework seam are in the same release as the API they name.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| MCP client to wristband authorize | Untrusted scope string and redirect cross here. This plan only changes which names are legal. |
|
||||
| pier dispatch to route handler | The handler receives MCPCall built from the already-resolved subject, not from tool arguments. |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-32.1-01 | Elevation of privilege | wristband resolvedScopes | high | mitigate | Empty MCP Options.ScopesSupported resolves to the five fixed names including backend. A non-empty list is not widened. OIDC discovery is untouched. |
|
||||
| T-32.1-02 | Elevation of privilege | pier filter.go read/write ceiling | high | mitigate | Do not edit Identity.writes or the ceiling in filter.go (D-01). Implies is data on the catalog only; pier does not expand scopes. |
|
||||
| T-32.1-03 | Spoofing | wristband Authorize redirect | high | mitigate | Do not edit client lookup, exact redirect match, PKCE or the /connect redirect. Scope resolution runs after those checks. |
|
||||
| T-32.1-04 | Information disclosure | pact.MCPCall.Subject.TokenID | medium | mitigate | README states TokenID is a user_api_tokens id only when ClientID is empty. Dispatch logs keep the existing audit line and must not gain the raw bearer or an authorization code. |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
go test -short on pact, pier and wristband passes, TestDiscoveryFields still locks the OIDC scope list, and TestDocsTree passes after the README commit.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- SC-1 and SC-2 have a framework path: one advertised slice drives MCP metadata and authorize, pier PRM reads it from the verifier, and one tool call exposes MCPCall.
|
||||
- D-01 ceiling and D-02 OIDC list are unchanged files.
|
||||
- Docs name the new identifiers and the mcp_scopes rule.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-01-SUMMARY.md` when done.
|
||||
</output>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- pact.MemberTokenScopeCatalog, method MemberTokenScopes
|
||||
- pact.MCPAdvertisedScopes, method MCPScopesSupported
|
||||
- pact.MCPCall, pact.WithMCPCall, pact.MCPCallFrom
|
||||
- FrontendTokenScope.Implies
|
||||
- wristband Server resolvedScopes (unexported), used by Metadata and allowedAuthorizeScopes
|
||||
- PendingRequestView.OfflineAccess
|
||||
- callInfo.stateless (unexported) so MCPCall.SessionID is empty on the stateless path and never the audit word ephemeral
|
||||
@@ -0,0 +1,191 @@
|
||||
---
|
||||
phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||
plan: 01
|
||||
subsystem: auth
|
||||
tags: [mcp, oauth, pact, pier, wristband, scopes]
|
||||
|
||||
requires:
|
||||
- phase: 19.7-generic-mcp-module
|
||||
provides: pier in-process dispatch, PRMScopes and the read/write ceiling
|
||||
- phase: 19.4-oidc-provider-on-wristband
|
||||
provides: OIDC discovery scope list left unchanged
|
||||
provides:
|
||||
- "pact.MemberTokenScopeCatalog, pact.MCPAdvertisedScopes, pact.MCPCall, pact.WithMCPCall, pact.MCPCallFrom"
|
||||
- "pact.FrontendTokenScope.Implies"
|
||||
- "wristband resolvedScopes shared by MCP metadata and authorize"
|
||||
- "wristband.PendingRequestView.OfflineAccess"
|
||||
- "pier PRM copies MCPScopesSupported when non-empty, else PRMScopes, and sets MCPCall beside WithDispatch"
|
||||
affects: [32.1-02, 32.1-03, 32.1-04, 32.1-05]
|
||||
|
||||
actuals:
|
||||
tokens: 17695
|
||||
tasks: 3
|
||||
commits: 3
|
||||
plan_head_before: 2cea3127cc2a2da5f8e0ea6ec47356bfaecc5c67
|
||||
plan_head_after: 876f0f09f2c4a42864941118d12d636123af1594
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "MCPAdvertisedScopes is a second interface; MCPTokenVerifier stays MCPVerifyToken and MCPResource"
|
||||
- "One resolvedScopes slice drives MCP metadata and the authorize allow-list"
|
||||
- "WithMCPCall is set on the dispatch context immediately before WithDispatch; a nil context is not replaced"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- modules/pact/mcp_call_test.go
|
||||
- modules/pier/mcp_seam_test.go
|
||||
modified:
|
||||
- modules/pact/capabilities.go
|
||||
- modules/pact/mcp.go
|
||||
- modules/pact/README.md
|
||||
- modules/pier/dispatch.go
|
||||
- modules/pier/prm.go
|
||||
- modules/pier/session.go
|
||||
- modules/pier/stateless.go
|
||||
- modules/pier/README.md
|
||||
- modules/wristband/authorize.go
|
||||
- modules/wristband/server.go
|
||||
- modules/wristband/consent.go
|
||||
- modules/wristband/mcp_scopes_smoke_test.go
|
||||
- modules/wristband/README.md
|
||||
- docs/services/mcp.md
|
||||
- docs/services/oauth-server.md
|
||||
- docs/services/authentication.md
|
||||
|
||||
key-decisions:
|
||||
- "Empty MCP Options.ScopesSupported resolves to read, write, ai, offline_access, backend; a non-empty list, including DefaultOptions, is used as given"
|
||||
- "Advertised scopes are pact.MCPAdvertisedScopes, not a new method on pact.MCPTokenVerifier"
|
||||
- "Stateless tool calls set callInfo.stateless so MCPCall.SessionID stays empty"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: Metadata and allowedAuthorizeScopes both call Server.resolvedScopes"
|
||||
- "Pattern: pier mountPRM type-asserts MCPAdvertisedScopes and clones a non-empty MCPScopesSupported, else PRMScopes"
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "An empty MCP Options.ScopesSupported advertises and accepts the five fixed names including backend; DefaultOptions still refuses backend; OIDC discovery stays openid, profile, email"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: modules/wristband/mcp_scopes_smoke_test.go#TestMCPScopesSmoke
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: modules/wristband/oidc_discovery_test.go#TestDiscoveryFields
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "pier copies MCPScopesSupported onto protected-resource metadata when non-empty and otherwise keeps PRMScopes, and one frontend tools/call observes MCPCall beside the bouncer dispatch marker"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: modules/pier/mcp_seam_test.go#TestMCPSeam
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "WithMCPCall then MCPCallFrom round-trips Subject.Guard, SessionID and Tool; a context without a call answers ok false"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: modules/pact/mcp_call_test.go#TestMCPCallRoundTrip
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "PendingRequestView.OfflineAccess is set from the pending row; IssueCode's signature is unchanged"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: go test -short ./modules/wristband
|
||||
status: pass
|
||||
human_judgment: true
|
||||
rationale: "No test asserts that PendingRequest copies OfflineAccess; the package suite only proves the field compiles and existing consent tests still pass"
|
||||
- id: D5
|
||||
description: "pact, pier and wristband READMEs and the three service docs name the new identifiers and the mcp_scopes rule without naming a consuming application"
|
||||
verification:
|
||||
- kind: other
|
||||
ref: go test ./cmd/summer -run TestDocsTree && go run ./cmd/summer docs:build --check
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: 12min
|
||||
completed: 2026-10-28
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 32.1 Plan 01: MCP scope list and call context Summary
|
||||
|
||||
**One resolved MCP scope list drives wristband metadata and authorize, pier copies it from the verifier, and every in-process tool call carries pact.MCPCall**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 12 min
|
||||
- **Started:** 2026-10-28T13:25:44Z
|
||||
- **Completed:** 2026-10-28T13:37:30Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 18
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- `pact` publishes `MemberTokenScopeCatalog`, `MCPAdvertisedScopes`, `MCPCall` (`WithMCPCall` / `MCPCallFrom`) and `FrontendTokenScope.Implies`. `MCPTokenVerifier` is still only `MCPVerifyToken` and `MCPResource`.
|
||||
- An empty or nil MCP `Options.ScopesSupported` resolves to `read`, `write`, `ai`, `offline_access`, `backend` for both metadata and the authorize allow-list. `DefaultOptions` stays the four-name list and still refuses `backend`. OIDC discovery stays `openid`, `profile`, `email`.
|
||||
- pier copies `MCPScopesSupported` into protected-resource metadata when that slice is non-empty, otherwise `PRMScopes`. `dispatcher.run` stores `MCPCall` immediately before `bouncer.WithDispatch`. Stateless calls leave `SessionID` empty.
|
||||
- `PendingRequestView.OfflineAccess` is the pending row's flag. `IssueCode`'s signature is unchanged.
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Tracer — one advertised scope list and one MCP call on the dispatch context** - `63d05e8` (feat)
|
||||
2. **Task 2: Expose offline_access on the pending consent view** - `9e29d6f` (feat)
|
||||
3. **Task 3: Document the seam in READMEs and docs** - `876f0f0` (docs)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `modules/pact/mcp.go` - catalog and advertised-scope interfaces, `MCPCall`, `WithMCPCall`, `MCPCallFrom`
|
||||
- `modules/pact/capabilities.go` - `FrontendTokenScope.Implies`
|
||||
- `modules/pact/mcp_call_test.go` - round-trip and absent-context cases
|
||||
- `modules/wristband/server.go` - unexported `resolvedScopes` used by metadata
|
||||
- `modules/wristband/authorize.go` - allow-list uses that same slice
|
||||
- `modules/wristband/consent.go` - `PendingRequestView.OfflineAccess`
|
||||
- `modules/wristband/mcp_scopes_smoke_test.go` - empty list expects the five names and accepts backend
|
||||
- `modules/pier/prm.go` - copy `MCPScopesSupported` or keep `PRMScopes`
|
||||
- `modules/pier/dispatch.go` - `WithMCPCall` immediately before `WithDispatch`; blank the ephemeral audit word
|
||||
- `modules/pier/session.go` - copy the SDK session id only when the call is not stateless
|
||||
- `modules/pier/stateless.go` - mark `callInfo.stateless` before the handler runs
|
||||
- `modules/pier/mcp_seam_test.go` - metadata, PRM and one tool call that observes `MCPCall`
|
||||
- `modules/pact/README.md`, `modules/pier/README.md`, `modules/wristband/README.md` - the new identifiers and the advertised-set rule
|
||||
- `docs/services/mcp.md`, `docs/services/oauth-server.md`, `docs/services/authentication.md` - the same rule, `MCPCallFrom`, and the unchanged ceiling and OIDC list
|
||||
|
||||
## Decisions Made
|
||||
|
||||
None beyond the plan's recorded discretion. `MemberTokenScopeCatalog.MemberTokenScopes` is not named `FrontendTokenScopes`. `MCPAdvertisedScopes` is a separate interface. Empty MCP options resolve to the five fixed names; a non-empty list is cloned as given. `filter.go` and `oidc_options.go` were not edited.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
The framework seam for SC-1 and SC-2 is in place. Later plans in this phase can publish the member-token catalog, build the advertised list from `golem15.oauthserver.mcp_scopes`, and read `MCPCallFrom` on a dispatched route. The read/write ceiling and the OIDC discovery list are unchanged.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: modules/pact/mcp.go
|
||||
- FOUND: modules/pact/mcp_call_test.go
|
||||
- FOUND: modules/pier/mcp_seam_test.go
|
||||
- FOUND: modules/wristband/consent.go
|
||||
- FOUND: modules/pact/README.md
|
||||
- FOUND: docs/services/mcp.md
|
||||
- FOUND: 63d05e8
|
||||
- FOUND: 9e29d6f
|
||||
- FOUND: 876f0f0
|
||||
|
||||
---
|
||||
*Phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con*
|
||||
*Completed: 2026-10-28*
|
||||
@@ -0,0 +1,173 @@
|
||||
---
|
||||
phase: 32.1
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on:
|
||||
- 32.1-01
|
||||
files_modified:
|
||||
- ../sm-user-plugin/classes/api_token_scopes.go
|
||||
- ../sm-user-plugin/classes/mcp_guard.go
|
||||
- ../sm-user-plugin/classes/mcp_guard_test.go
|
||||
- ../sm-user-plugin/plugin.go
|
||||
- ../sm-user-plugin/README.md
|
||||
- ../sm-user-plugin/go.mod
|
||||
autonomous: true
|
||||
requirements: []
|
||||
estimate:
|
||||
tokens: 38000
|
||||
raw_tokens: 38000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-1: On a branch from tag v0.1.14, an OAuth MCP subject (ClientID non-empty) whose grant holds read satisfies a declared scope with Implies read, in both MCPAllows and the credential MCPDispatch builds (D-01a). write does not satisfy Implies read."
|
||||
- "A personal-token subject (ClientID empty) is not expanded. Its credential ID stays subject.TokenID, the v0.1.14 rule (D-11)."
|
||||
- "The compiled catalog is published as pact.MemberTokenScopeCatalog. Implied names are not written onto the token row, the fingerprint, or subject.Scopes (D-05, D-01a)."
|
||||
- "The app submodule at sm-demo-app/plugins/golem15/user is not edited."
|
||||
artifacts:
|
||||
- path: ../sm-user-plugin/classes/mcp_guard.go
|
||||
provides: "OAuth-only Implies expansion shared by MCPAllows and MCPDispatch"
|
||||
contains: "ClientID"
|
||||
- path: ../sm-user-plugin/plugin.go
|
||||
provides: "Publish of MemberTokenScopeCatalog beside the concrete catalog"
|
||||
contains: "MemberTokenScopeCatalog"
|
||||
key_links:
|
||||
- from: classes/mcp_guard.go MCPAllows
|
||||
to: classes/mcp_guard.go MCPDispatch
|
||||
via: one helper that clones scopes only when ClientID is non-empty
|
||||
pattern: ClientID
|
||||
- from: plugin.go bootAPITokenScopes
|
||||
to: pact.MemberTokenScopeCatalog
|
||||
via: app.Publish of the interface
|
||||
pattern: MemberTokenScopeCatalog
|
||||
---
|
||||
|
||||
<objective>
|
||||
sm-user-plugin from tag v0.1.14 publishes the member-token catalog and applies Implies only to OAuth MCP subjects (D-01a, D-05, D-11). Personal tokens keep their scopes and their credential id.
|
||||
|
||||
Purpose: an OAuth grant of read and write can list and run the same tools as a personal token that carries the declared names the plugins marked as implied, without storing those names on the grant.
|
||||
Output: a worktree at the path below, on a branch from v0.1.14, plus one tracer test. The rest of the Implies matrix is plan 05.
|
||||
|
||||
Worktree, exact: /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin
|
||||
Remote: git@git.golem15.com:golem15/sm-user-plugin.git
|
||||
Branch: phase-32.1-mcp-implied-scopes, created from tag v0.1.14 (commit a1b78b80). Do not use sm-demo-app/plugins/golem15/user or any other app submodule. That checkout is v0.1.13 and has the wrong credential-id body.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-CONTEXT.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-RESEARCH.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-PATTERNS.md
|
||||
@modules/pact/capabilities.go
|
||||
@modules/pact/mcp.go
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Tracer: v0.1.14 worktree publishes the catalog and expands one implied scope</name>
|
||||
<precondition>git ls-remote git@git.golem15.com:golem15/sm-user-plugin.git refs/tags/v0.1.14 prints a commit, and /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin is either absent or already this phase's worktree on phase-32.1-mcp-implied-scopes. Halt if that path is any other checkout, including an app submodule.</precondition>
|
||||
<reversibility rating="costly">D-01a: once a plugin marks Implies read or write, live OAuth agents gain those tools. Removing it later shrinks their tool list.</reversibility>
|
||||
<files>../sm-user-plugin/go.mod, ../sm-user-plugin/classes/api_token_scopes.go, ../sm-user-plugin/classes/mcp_guard.go, ../sm-user-plugin/plugin.go, ../sm-user-plugin/classes/mcp_guard_test.go</files>
|
||||
<read_first>
|
||||
The worktree's classes/mcp_guard.go after the branch exists (v0.1.14 MCPDispatch sets credential.ID only when ClientID is empty). Do not read the v0.1.13 submodule as the body to edit.
|
||||
The worktree's classes/api_token_scopes.go CompileAPITokenScopes and builtInAPITokenScopeKeys.
|
||||
The worktree's plugin.go bootAPITokenScopes (today app.Publish of the concrete catalog and of pact.MCPPersonalTokenResolver).
|
||||
modules/pact/mcp.go MemberTokenScopeCatalog in the framework repo.
|
||||
../sm-oauthserver-plugin/go.mod replace line, as the pattern for a sibling replace.
|
||||
</read_first>
|
||||
<action>
|
||||
Fetch the tag and create the worktree with git clone or git worktree add of git@git.golem15.com:golem15/sm-user-plugin.git at /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin, branch phase-32.1-mcp-implied-scopes from v0.1.14. Confirm HEAD's MCPDispatch comment says a personal-token credential ID is subject.TokenID and an OAuth credential keeps ID 0. If the comment still says the credential has ID 0 and never sets credential.ID, stop: that is v0.1.13.
|
||||
|
||||
Point the summercms replace at ../summercms.go so this worktree compiles against plan 01. If go.mod has no replace for git.golem15.com/golem15/summercms, add one. Commit that replace with the feature commit in the plugin repo. Do not retarget any app submodule.
|
||||
|
||||
On *APITokenScopeCatalog add MemberTokenScopes() []pact.FrontendTokenScope returning the compiled list (built-ins and declared). In bootAPITokenScopes, after the existing concrete app.Publish(catalog), also app.Publish the same value as pact.MemberTokenScopeCatalog (D-05). Do not remove the concrete publish or the MCPPersonalTokenResolver publish.
|
||||
|
||||
Extend CompileAPITokenScopes: reject Implies other than "", "read" or "write"; reject a declared name backend or offline_access. Built-in read, write and ai keep Implies empty. Existing rejections of read, write, ai as declared names, duplicates, and empty label or description stay.
|
||||
|
||||
Add one helper used by MCPAllows and MCPDispatch (D-01a). When subject.ClientID is empty, return subject.Scopes unchanged. Otherwise clone subject.Scopes and, for each catalog entry whose Implies is read or write, if the clone contains that stock scope and not the declared name, append the declared name. Never append a name the catalog does not mark. Never let write satisfy Implies read. Do not write the clone back onto subject.Scopes, a token row, or a fingerprint. MCPAllows checks req.Scopes against the helper's slice. MCPDispatch puts that slice on the in-memory models.APIToken.Scopes and still sets credential.ID = subject.TokenID only when ClientID is empty (D-11). Do not set APIToken.OAuthClientID.
|
||||
|
||||
Tracer test TestMCPImpliesOAuth in classes/mcp_guard_test.go: an OAuth subject with ClientID set and scopes read passes MCPAllows for a requirement servers:read when the catalog entry says Implies read, and the MCPDispatch credential HasScope servers:read while its ID stays 0. Commit only in the plugin repo, staging paths under that worktree. Do not git add -A. Do not push or tag.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin test -short -count=1 -run '^TestMCPImpliesOAuth$' .</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- git -C the worktree rev-parse HEAD is a descendant of v0.1.14, not of the v0.1.13 submodule commit 07196a4 alone.
|
||||
- TestMCPImpliesOAuth PASS: OAuth read grant satisfies Implies read, credential ID is 0.
|
||||
- sm-demo-app/plugins/golem15/user has no diff from this task.
|
||||
</acceptance_criteria>
|
||||
<done>The v0.1.14 branch publishes the catalog and one OAuth implied scope works end to end through allow and dispatch.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Reject bad Implies and keep personal tokens unexpanded</name>
|
||||
<reversibility rating="costly">D-01a and D-03: boot errors and the personal-token exemption are part of the contract plugins and grants will rely on.</reversibility>
|
||||
<files>../sm-user-plugin/classes/api_token_scopes.go, ../sm-user-plugin/classes/mcp_guard.go, ../sm-user-plugin/classes/mcp_guard_test.go, ../sm-user-plugin/README.md</files>
|
||||
<read_first>
|
||||
The worktree classes/api_token_scopes.go and classes/mcp_guard.go after the tracer commit.
|
||||
The worktree README.md
|
||||
modules/pact/capabilities.go FrontendTokenScope.Implies comment
|
||||
</read_first>
|
||||
<action>
|
||||
Finish the helper's edges if the tracer left any call site on slices.Clone(subject.Scopes) for the scope check. MCPAllows and MCPDispatch must both call the helper. A personal token (ClientID empty) with only read must not gain a declared name. A grant of write must not satisfy Implies read. A second copy of an already-present declared name is not appended.
|
||||
|
||||
CompileAPITokenScopes error text names the plugin and the bad Implies value or the reserved name backend or offline_access, in the same style as the existing declared-name errors. Phrase-key checks in bootAPITokenScopes stay.
|
||||
|
||||
README: document FrontendTokenScope.Implies (empty, read, or write), that expansion happens only inside MCPAllows and MCPDispatch when ClientID is non-empty, that personal tokens are unchanged, and that the catalog is published as pact.MemberTokenScopeCatalog. Do not name a consuming application. Do not persist implied names. Commit in the plugin repo only. Do not push or tag. Do not edit the framework repo in this plan.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin test -short -count=1 -run 'TestMCP' .</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL, or TestMCPImpliesOAuth has no PASS line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- A personal-token test in this package shows scopes unchanged and credential ID equal to TokenID.
|
||||
- An Implies value other than empty, read, or write fails CompileAPITokenScopes.
|
||||
- README names MemberTokenScopeCatalog and Implies and names no consuming application.
|
||||
</acceptance_criteria>
|
||||
<done>D-01a holds on both call sites, personal tokens are not expanded, and the plugin README matches the API.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| OAuth grant scopes to MCPAllows / user.scope | The grant is the attacker's consented set. Implies may add only names the plugin marked. |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-32.1-05 | Elevation of privilege | MCPUserGuard Implies helper | high | mitigate | Expand only when ClientID is non-empty, only for a catalog Implies of read or write, only the declared name that says so. Do not write the expanded set onto the token, the fingerprint, or subject.Scopes. Personal tokens are returned unchanged (D-01a, D-11). |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
go test -short -run TestMCP in the v0.1.14 worktree passes, including TestMCPImpliesOAuth, and the app submodule is untouched.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Catalog publication and OAuth-only Implies are on a branch from v0.1.14.
|
||||
- Personal-token credential ID behaviour from that tag is intact.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-02-SUMMARY.md` when done.
|
||||
</output>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Worktree /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin branch phase-32.1-mcp-implied-scopes from tag v0.1.14
|
||||
- *APITokenScopeCatalog.MemberTokenScopes
|
||||
- app.Publish of pact.MemberTokenScopeCatalog
|
||||
- CompileAPITokenScopes rejection of bad Implies and of declared names backend and offline_access
|
||||
- Unexported effective-scope helper in classes/mcp_guard.go
|
||||
- TestMCPImpliesOAuth
|
||||
@@ -0,0 +1,194 @@
|
||||
---
|
||||
phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||
plan: 02
|
||||
subsystem: auth
|
||||
tags: [mcp, oauth, scopes, implies, sm-user-plugin]
|
||||
|
||||
requires:
|
||||
- phase: 32.1-01
|
||||
provides: pact.MemberTokenScopeCatalog and FrontendTokenScope.Implies
|
||||
provides:
|
||||
- "sm-user-plugin on phase-32.1-mcp-implied-scopes publishes the compiled catalog as pact.MemberTokenScopeCatalog"
|
||||
- "OAuth MCP subjects expand declared scopes whose Implies is read or write inside MCPAllows and MCPDispatch"
|
||||
- "Personal tokens are not expanded and keep credential ID equal to TokenID"
|
||||
- "CompileAPITokenScopes rejects a bad Implies and the reserved names backend and offline_access"
|
||||
affects: [32.1-03, 32.1-05]
|
||||
|
||||
actuals:
|
||||
tokens: 10492
|
||||
tasks: 2
|
||||
commits: 0
|
||||
plan_head_before: 415a09333bf9bb2cc93ac8324aac794cc74ff818
|
||||
plan_head_after: 415a09333bf9bb2cc93ac8324aac794cc74ff818
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "One unexported helper, mcpEffectiveScopes, feeds MCPAllows and MCPDispatch"
|
||||
- "Expansion clones the grant only when ClientID is non-empty and never writes that clone back"
|
||||
- "The catalog is published twice: the concrete *APITokenScopeCatalog and pact.MemberTokenScopeCatalog"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../sm-user-plugin/mcp_implies_test.go
|
||||
modified:
|
||||
- ../sm-user-plugin/classes/api_token_scopes.go
|
||||
- ../sm-user-plugin/classes/mcp_guard.go
|
||||
- ../sm-user-plugin/plugin.go
|
||||
- ../sm-user-plugin/go.mod
|
||||
- ../sm-user-plugin/README.md
|
||||
|
||||
key-decisions:
|
||||
- "Implies tests live in the plugin root package so go test . runs them; classes/mcp_guard_test.go would report no tests to run"
|
||||
- "The tracer loads a principal from an in-memory database/sql driver so go test -short proves MCPAllows and MCPDispatch without Docker"
|
||||
- "The phase branch replace points at ../summercms.go, the sibling of this checkout, not the old submodule-relative path"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: OAuth effective scopes are a clone plus catalog names whose Implies is exactly the stock scope the grant holds"
|
||||
- "Pattern: a personal token returns subject.Scopes unchanged, including slice identity, and credential.ID stays TokenID"
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "An OAuth subject with ClientID set and scopes read passes MCPAllows for servers:read when Implies is read, and the MCPDispatch credential HasScope servers:read with ID 0. The grant slice is not rewritten. The catalog is published as pact.MemberTokenScopeCatalog."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: mcp_implies_test.go#TestMCPImpliesOAuth
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "A personal token (ClientID empty) with only read does not gain servers:read, and the dispatch credential ID equals TokenID"
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: mcp_implies_test.go#TestMCPImpliesPersonalUnchanged
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "A grant of write does not satisfy Implies read, and a declared name already on the grant is not appended a second time. A catalog entry with empty Implies is not appended."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: mcp_implies_test.go#TestMCPImpliesWriteDoesNotGrantRead
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: mcp_implies_test.go#TestMCPImpliesAlreadyPresent
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "CompileAPITokenScopes fails for Implies other than empty, read, or write, and for declared names backend and offline_access. The error names the plugin and the bad value."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: mcp_implies_test.go#TestMCPImpliesCompileRejects
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D5
|
||||
description: "The plugin README names FrontendTokenScope.Implies, the OAuth-only expansion, unchanged personal tokens, and pact.MemberTokenScopeCatalog, and names no consuming application"
|
||||
verification:
|
||||
- kind: other
|
||||
ref: README.md MemberTokenScopeCatalog and Implies; rg found no consuming-application name
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: 17min
|
||||
completed: 2026-10-28
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 32.1 Plan 02: OAuth implied scopes Summary
|
||||
|
||||
**On a branch from sm-user-plugin v0.1.14, an OAuth MCP grant of read satisfies declared scopes marked Implies read, and a personal token keeps its scopes and credential id**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 17 min
|
||||
- **Started:** 2026-10-28T13:48:50Z
|
||||
- **Completed:** 2026-10-28T14:06:00Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 6
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- The checkout `/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin` is branch `phase-32.1-mcp-implied-scopes` from tag `v0.1.14` (`a1b78b8`). `MCPDispatch` still sets `credential.ID` only when `ClientID` is empty.
|
||||
- `*APITokenScopeCatalog.MemberTokenScopes` returns the compiled list. Boot publishes that value as `pact.MemberTokenScopeCatalog` beside the concrete catalog and still publishes `pact.MCPPersonalTokenResolver`.
|
||||
- `mcpEffectiveScopes` is the only expansion. It returns `subject.Scopes` unchanged when `ClientID` is empty. Otherwise it clones the grant and appends a catalog name only when `Implies` is `read` or `write`, the clone holds that stock scope, and the name is not already present. `MCPAllows` and `MCPDispatch` both use it. The clone is not written onto `subject.Scopes`, a token row, or a fingerprint. `APIToken.OAuthClientID` is not set.
|
||||
- `CompileAPITokenScopes` rejects `Implies` other than empty, `read`, or `write`, and rejects declared names `backend` and `offline_access`. Built-ins keep `Implies` empty. The summercms replace on this branch is `../summercms.go`.
|
||||
|
||||
## Task Commits
|
||||
|
||||
Plugin repo `sm-user-plugin` only. summercms.go had no code commits in this plan (`commits: 0` from `415a093..HEAD` at summary time).
|
||||
|
||||
1. **Task 1: Tracer — v0.1.14 worktree publishes the catalog and expands one implied scope** - `25fd981` (feat)
|
||||
2. **Task 2: Reject bad Implies and keep personal tokens unexpanded** - `193a381` (test)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `../sm-user-plugin/classes/api_token_scopes.go` - `MemberTokenScopes`, `Implies` on the compiled scope, rejection of bad `Implies` and of `backend` / `offline_access`
|
||||
- `../sm-user-plugin/classes/mcp_guard.go` - `mcpEffectiveScopes` shared by `MCPAllows` and `MCPDispatch`
|
||||
- `../sm-user-plugin/plugin.go` - second publish as `pact.MemberTokenScopeCatalog`
|
||||
- `../sm-user-plugin/go.mod` - replace `../summercms.go` so the branch compiles against plan 01
|
||||
- `../sm-user-plugin/mcp_implies_test.go` - OAuth, personal-token, write, duplicate, and compile-rejection tests
|
||||
- `../sm-user-plugin/README.md` - `Implies`, the OAuth-only expansion, and `pact.MemberTokenScopeCatalog`
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- The tests are in the plugin root package (`mcp_implies_test.go`), not `classes/mcp_guard_test.go`. The plan's verify is `go test .`, which does not compile `classes/`.
|
||||
- `MCPAllows` and `MCPDispatch` need a principal before they can return success. Docker-backed tests skip under `-short` (CLAUDE.md), and the verify command is `go test -short`, so the tests answer one user and no group grants from an in-memory `database/sql` driver. No new module dependency.
|
||||
- The existing `go.mod` replace pointed at `../../../../summercms.go` (a submodule layout). This checkout is a sibling of `summercms.go`, so the replace is `../summercms.go`, as the plan required. Do not tag that path as a release for app submodules.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Tests live in the plugin root package**
|
||||
- **Found during:** Task 1 (tracer)
|
||||
- **Issue:** The plan named `classes/mcp_guard_test.go`, but `go -C <plugin> test .` runs package `user`. A test under `classes/` makes that command print `[no tests to run]`.
|
||||
- **Fix:** `TestMCPImpliesOAuth` and the task 2 cases are in `mcp_implies_test.go` at the plugin root.
|
||||
- **Files modified:** `mcp_implies_test.go`
|
||||
- **Verification:** `go test -short -count=1 -run 'TestMCP' .` exits 0; `-v` shows `--- PASS: TestMCPImpliesOAuth`
|
||||
- **Committed in:** `25fd981` (task 1), `193a381` (task 2)
|
||||
|
||||
**2. [Rule 3 - Blocking] In-memory principal instead of testcontainers**
|
||||
- **Found during:** Task 1 (tracer)
|
||||
- **Issue:** A passing `MCPAllows` / `MCPDispatch` loads the user. The admin harness skips under `-short`, so a Docker test would not produce a PASS on the mandated command. CLAUDE.md says Docker-backed tests skip under `-short`.
|
||||
- **Fix:** The tests publish a `*gorm.DB` over a tiny in-memory driver that returns one user row and no group grants. Scope expansion does not read the database.
|
||||
- **Files modified:** `mcp_implies_test.go`
|
||||
- **Verification:** `TestMCPImpliesOAuth` PASS under `-short` with no container
|
||||
- **Committed in:** `25fd981`
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 2 auto-fixed (2 blocking)
|
||||
**Impact on plan:** Both keep the mandated `go test -short` command able to prove the behavior. No production path changed beyond the plan.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
`state.advance-plan` was not run. It has no phase argument and advances whatever Current Position names. That position is phase 33, from another session. Advancing it would move the wrong plan counter. Roadmap progress for 32.1 was updated with `roadmap.update-plan-progress`. STATE.md was updated with phase-scoped handlers where they exist, and was not committed.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Plan 03 can `Lookup` `pact.MemberTokenScopeCatalog` from an app that boots this branch. The catalog includes built-ins (empty `Implies`) then declared scopes.
|
||||
|
||||
Plan 05 should extend `mcp_implies_test.go` in the plugin root, not add `classes/mcp_guard_test.go`, or its `go test .` verify will not see the new tests. These tests already exist and must not be redeclared in package `user`: `TestMCPImpliesOAuth`, `TestMCPImpliesPersonalUnchanged`, `TestMCPImpliesWriteDoesNotGrantRead`, `TestMCPImpliesAlreadyPresent`, `TestMCPImpliesCompileRejects`. `TestMCPImpliesNotPersisted` is not a separate test yet; `TestMCPImpliesOAuth` already checks that `subject.Scopes` keeps its original slice header.
|
||||
|
||||
The app submodule `sm-demo-app/plugins/golem15/user` is still `07196a4` with no diff. This branch was not pushed or tagged. The `../summercms.go` replace is for this sibling checkout only.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: ../sm-user-plugin/classes/mcp_guard.go
|
||||
- FOUND: ../sm-user-plugin/classes/api_token_scopes.go
|
||||
- FOUND: ../sm-user-plugin/plugin.go
|
||||
- FOUND: ../sm-user-plugin/mcp_implies_test.go
|
||||
- FOUND: ../sm-user-plugin/README.md
|
||||
- FOUND: ../sm-user-plugin/go.mod
|
||||
- FOUND: 25fd981
|
||||
- FOUND: 193a381
|
||||
- Demo submodule HEAD 07196a4, status clean
|
||||
- `go test -short -count=1 -run 'TestMCP' .` in the plugin: exit 0
|
||||
|
||||
---
|
||||
*Phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con*
|
||||
*Completed: 2026-10-28*
|
||||
@@ -0,0 +1,303 @@
|
||||
---
|
||||
phase: 32.1
|
||||
plan: 03
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on:
|
||||
- 32.1-01
|
||||
- 32.1-02
|
||||
files_modified:
|
||||
- ../sm-oauthserver-plugin/config/config.yaml
|
||||
- ../sm-oauthserver-plugin/servers.go
|
||||
- ../sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||
- ../sm-oauthserver-plugin/classes/mcp_store.go
|
||||
- ../sm-oauthserver-plugin/classes/mcp_scopes.go
|
||||
- ../sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||
- ../sm-oauthserver-plugin/controllers/authorizations.go
|
||||
- ../sm-oauthserver-plugin/lang/en/lang.yaml
|
||||
- ../sm-oauthserver-plugin/lang/pl/lang.yaml
|
||||
- ../sm-oauthserver-plugin/README.md
|
||||
- ../sm-oauthserver-plugin/authorizations_smoke_test.go
|
||||
- ../sm-oauthserver-plugin/mcp_scopes_test.go
|
||||
- ../sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go
|
||||
autonomous: false
|
||||
requirements: []
|
||||
estimate:
|
||||
tokens: 64000
|
||||
raw_tokens: 64000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-1: golem15.oauthserver.mcp_scopes unset advertises every declared member scope; a set list advertises only those names; an empty list advertises the five fixed names. Fixed names read, write, ai, offline_access, backend are always present. An unknown name fails boot (D-03, D-04)."
|
||||
- "SC-3: An MCP allow upserts golem15_oauthserver_consents for that user and client, replacing scopes. It does not call SaveConsent. A later allow of a smaller set drops the unticked names (D-08, D-12)."
|
||||
- "SC-3: Revoke takes lockUserGrants, deletes the consent, OIDC codes, MCP codes, access tokens and refresh tokens of the pair, then emits MCPSubjectRevoked with ClientID and a zero TokenID (D-12, D-15)."
|
||||
- "GET /oauth/authorizations entries include kind oidc or mcp as the last key. A POST of decision allow with no scopes field still grants the whole request (D-13, D-06)."
|
||||
- "offline_access stays a column flag. The pending view surfaces it. IssueCode's signature is unchanged (D-06)."
|
||||
artifacts:
|
||||
- path: ../sm-oauthserver-plugin/config/config.yaml
|
||||
provides: "golem15.oauthserver.mcp_scopes"
|
||||
contains: "mcp_scopes"
|
||||
- path: ../sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||
provides: "MCPScopesSupported on the existing verifier value"
|
||||
contains: "MCPScopesSupported"
|
||||
- path: ../sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||
provides: "scope_details, logo_url, consent replace"
|
||||
contains: "scope_details"
|
||||
- path: ../sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go
|
||||
provides: "idempotent MCP consent backfill"
|
||||
contains: "golem15_oauthserver_consents"
|
||||
key_links:
|
||||
- from: servers.go NewServers
|
||||
to: classes/mcp_verifier.go MCPScopesSupported
|
||||
via: the same slice assigned to mcpOpts.ScopesSupported
|
||||
pattern: MCPScopesSupported
|
||||
- from: controllers/mcp_consent_api.go MCPConsentDecide
|
||||
to: golem15_oauthserver_consents
|
||||
via: replace upsert after IssueCode, not SaveConsent
|
||||
pattern: ON CONFLICT
|
||||
- from: controllers/authorizations.go revoke
|
||||
to: golem15_oauthserver_mcp_codes
|
||||
via: lockUserGrants then Delete of MCPCode
|
||||
pattern: lockUserGrants
|
||||
---
|
||||
|
||||
<objective>
|
||||
sm-oauthserver-plugin closes SC-1's host filter and SC-3's consent row (D-02, D-03, D-04, D-06, D-07, D-08, D-12, D-13, D-14, D-15). The MCP server's one scope slice is the fixed five plus declared names filtered by golem15.oauthserver.mcp_scopes. Consent JSON gains scope_details and logo_url. A decision replaces the stored scopes. Revoke deletes MCP codes under the grants lock. kind is additive. The backfill is one-way and waits for the checkpoint in this plan.
|
||||
|
||||
Purpose: an agent that consents over MCP can be revoked per client, and the protected-resource list cannot drift from the authorization server.
|
||||
Output: plugin code, phrases, README, the authorizations key-list update, and, after the checkpoint, the backfill migration. Behaviour proofs beyond the existing smoke tests are plan 05.
|
||||
|
||||
Discretion recorded here:
|
||||
- An opt-in name that no plugin declares fails boot. The error names the key golem15.oauthserver.mcp_scopes and the unknown name. A warning would start a server whose metadata disagrees with the file (D-03).
|
||||
- kind is always the string models.ClientKindOIDC or models.ClientKindMCP ("oidc" or "mcp"), never omitted, and it is the last JSON key (D-13).
|
||||
|
||||
Do not bump go.mod require versions to unreleased tags. The existing replace of summercms to ../summercms.go stays. Do not edit views/consent.html.tmpl. Do not edit wristband. Do not force read into a grant.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-CONTEXT.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-RESEARCH.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-PATTERNS.md
|
||||
@../sm-oauthserver-plugin/servers.go
|
||||
@../sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||
@../sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||
@../sm-oauthserver-plugin/controllers/authorizations.go
|
||||
@../sm-oauthserver-plugin/classes/oidc_store.go
|
||||
@../sm-oauthserver-plugin/classes/mcp_store.go
|
||||
@../sm-oauthserver-plugin/classes/mcp_backend_binding.go
|
||||
@../sm-oauthserver-plugin/config/config.yaml
|
||||
@modules/pier/config.go
|
||||
@modules/pact/mcp.go
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Tracer: one MCP scope slice from config to metadata and the verifier</name>
|
||||
<precondition>/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/go.mod exists and its replace points at ../summercms.go. Plan 01's pact.MCPAdvertisedScopes is in that tree.</precondition>
|
||||
<reversibility rating="costly">D-03: scope names published in metadata and later stored on grants are costly to retract.</reversibility>
|
||||
<files>../sm-oauthserver-plugin/config/config.yaml, ../sm-oauthserver-plugin/servers.go, ../sm-oauthserver-plugin/classes/mcp_scopes.go, ../sm-oauthserver-plugin/classes/mcp_verifier.go, ../sm-oauthserver-plugin/mcp_scopes_test.go</files>
|
||||
<read_first>
|
||||
../sm-oauthserver-plugin/servers.go NewServers (mcpOpts := opts then append backend)
|
||||
../sm-oauthserver-plugin/config/config.yaml header (SUMMER_ double-underscore env spelling) and the mcp: block
|
||||
../sm-oauthserver-plugin/classes/mcp_verifier.go MCPTokenVerifier
|
||||
modules/pier/config.go originsKey (the []any / []string / comma-string switch to copy)
|
||||
modules/compass config Has versus String (String is empty for both missing and empty)
|
||||
modules/pact/mcp.go MCPAdvertisedScopes
|
||||
</read_first>
|
||||
<action>
|
||||
Add config key mcp_scopes under the mcp block in config/config.yaml, with a comment that unset means every declared member scope, a YAML list means only those declared names, and an empty list means the five fixed names only. Document the env spelling SUMMER_GOLEM15__OAUTHSERVER__MCP_SCOPES. Do not change mcp.enabled's default of false.
|
||||
|
||||
Add an unexported builder, called from NewServers, that returns the MCP slice and an error. Order is always read, write, ai, offline_access, backend, then declared names in catalog order. Declared names are MemberTokenScopes entries whose name is not read, write or ai. Lookup pact.MemberTokenScopeCatalog. A missing catalog means no declared names. When Config.Has("golem15.oauthserver.mcp_scopes") is false, include every declared name. When it is true, include only declared names the list contains. Read the value with Lookup, accepting []string, []any of strings, or a comma-separated string, the same three shapes originsKey accepts. An unknown name fails boot with an error that contains golem15.oauthserver.mcp_scopes and that name. Do not filter the five fixed names. Never return an empty slice.
|
||||
|
||||
Assign that slice only to mcpOpts.ScopesSupported. mcpOpts := opts is already a struct copy. Do not assign cfg.OIDC.ScopesSupported and do not append backend a second time (D-02). Store the same slice on the MCPTokenVerifier value NewServers already builds, and add MCPScopesSupported() []string so that value implements pact.MCPAdvertisedScopes (D-04). Publish stays the existing verifier publish; the extra method is on that concrete value, not a new method of pact.MCPTokenVerifier.
|
||||
|
||||
TestMCPAdvertisedScopes in mcp_scopes_test.go, no Docker: a fake catalog with acme:read, key unset, yields the five fixed names plus acme:read; key set to acme:read yields the same; key set to empty yields the five only; key set to not-declared returns an error naming the key; the OIDC server's scopes stay openid, profile, email. Hit Metadata on the MCP server from NewServers for the unset case and compare scopes_supported to MCPScopesSupported. Commit in the plugin repo only, those files. Do not git add -A. Do not push or tag.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -short -count=1 -run '^TestMCPAdvertisedScopes$' .</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- TestMCPAdvertisedScopes PASS covers unset, set, empty, and unknown name.
|
||||
- OIDC discovery scopes in that test stay openid, profile, email.
|
||||
- mcpOpts.ScopesSupported is never empty, including the empty-catalog case.
|
||||
</acceptance_criteria>
|
||||
<done>Metadata and the verifier advertise one non-empty slice, and an unknown mcp_scopes name fails boot.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Consent JSON, replace-not-merge, offline_access, revoke, and kind</name>
|
||||
<precondition>docker info exits 0. The plugin tests use testcontainers Postgres and skip the database when Docker is down.</precondition>
|
||||
<reversibility rating="reversible">Consent JSON fields and the revoke delete list are code. The backfill that writes rows on every install is the next task, not this one.</reversibility>
|
||||
<files>../sm-oauthserver-plugin/controllers/mcp_consent_api.go, ../sm-oauthserver-plugin/controllers/authorizations.go, ../sm-oauthserver-plugin/classes/mcp_store.go, ../sm-oauthserver-plugin/lang/en/lang.yaml, ../sm-oauthserver-plugin/lang/pl/lang.yaml, ../sm-oauthserver-plugin/README.md, ../sm-oauthserver-plugin/authorizations_smoke_test.go</files>
|
||||
<read_first>
|
||||
../sm-oauthserver-plugin/controllers/mcp_consent_api.go (show body, grantedScopes, IssueCode call, WithConsentedBackend)
|
||||
../sm-oauthserver-plugin/classes/oidc_store.go SaveConsent (unions; do not call it) and TouchConsent
|
||||
../sm-oauthserver-plugin/classes/mcp_store.go MarkIssued (does not write offline_access today)
|
||||
../sm-oauthserver-plugin/classes/mcp_backend_binding.go WithConsentedBackend and lockUserGrants
|
||||
../sm-oauthserver-plugin/controllers/authorizations.go revoke and the authorization struct
|
||||
../sm-oauthserver-plugin/authorizations_smoke_test.go (len of keys is 6)
|
||||
../sm-oauthserver-plugin/mcp_consent_smoke_test.go the subtest that posts scopes backend and expects 422
|
||||
../sm-oauthserver-plugin/models/client.go ClientKindOIDC and ClientKindMCP
|
||||
modules/phrasebook translator Get
|
||||
</read_first>
|
||||
<action>
|
||||
Keep scopes as []string. Add scope_details objects with name, label, description, locked, and add logo_url on the client object (D-07). locked is true only for read when read was requested. logo_url is classes.ClientLogoURL, empty string when none. Labels: if the catalog text contains "::", resolve it with phrasebook.Translator.Get; otherwise use the literal. backend and offline_access are not in the member catalog. Add phrase keys under consent.mcp in lang/en/lang.yaml and lang/pl/lang.yaml. English: backend label "Also act as an administrator", description "The agent may use the administrator account this page names."; offline_access label "Stay connected", description "The agent may refresh its access without asking you to sign in again." Polish: backend label "Działaj też jako administrator", description "Agent może używać konta administratora, które wskazuje ta strona."; offline_access label "Pozostań połączony", description "Agent może odnawiać dostęp bez ponownego logowania."
|
||||
|
||||
When PendingRequestView.OfflineAccess is true, include offline_access in the show scopes array and in scope_details (locked false). grantedScopes intersects the submitted list with that augmented requested list, not only view.ScopesRequested. Strip the word offline_access before IssueCode. Do not change IssueCode's signature. A submit whose only remaining scope is offline_access still returns 422 no_grantable_scopes. Do not special-case read inside grantedScopes. The existing smoke subtest that posts scopes backend for a read-plus-backend request with no link must still get 422 no_grantable_scopes (D-06).
|
||||
|
||||
Follow WithConsentedBackend with a context value the MCP store reads in MarkIssued. When the POST body omits the scopes field, do not set the override, so the pending row's offline_access flag is kept (old all-or-nothing clients). When scopes is present, set the column from whether offline_access survived the intersection. Absent context means MarkIssued leaves the column as the pending row has it.
|
||||
|
||||
D-08 and D-12, after IssueCode returns nil: load the consent for (userID, clientID). Compare the requested set (data scopes plus offline_access when that flag was on the pending view) to the stored scopes. If a row exists and nothing requested is missing, call TouchConsent only and do not change scopes. If a row exists and something is missing, or there is no row, insert or replace scopes with the granted set, including the word offline_access when the flag was granted. Replace means the stored array becomes the granted set, not a union. Do not call oidc SaveConsent. Deny does not change the row. Add additive consent_required on the show body: false when a row exists and nothing requested is missing, true otherwise. Do not skip the authorize redirect; the user is known only on these jwt.auth routes.
|
||||
|
||||
A POST with decision allow and no scopes field still grants every requested data scope (D-06, old pages). Do not require scope_details or kind on the request.
|
||||
|
||||
revoke (D-12, D-15): inside the existing transaction, call classes.lockUserGrants for the user before the deletes. Then delete the consent, models.AuthCode, models.AccessToken, models.RefreshToken, and models.MCPCode for the same user_id and client_id. Keep 404 errNotFound when no consent exists. After commit, keep the existing MCPSubjectRevoked event with Guard user, ClientID set, and TokenID left zero. Do not add a second event or a second backend revoke. One delete of the access and refresh rows covers backend_user_id on those rows.
|
||||
|
||||
GET /oauth/authorizations: select c.kind, set authorization.Kind with json kind, last field. Always set it from the client kind, oidc or mcp. Update authorizations_smoke_test.go so the key list is client_id, name, logo_url, scopes, first_authorized_at, last_used_at, kind, in that order. The length check must match the new list. Existing OIDC rows in that test get kind oidc.
|
||||
|
||||
README: document mcp_scopes (unset, set, empty, fixed five always, boot error on an unknown name), scope_details and logo_url, consent replace versus the OIDC union, offline_access as a column, kind, and that revoke deletes MCP codes under lockUserGrants. Say that a non-nil DCR scope ceiling still drops names outside that ceiling and this phase does not rewrite old ceilings. Do not name a consuming application. Do not log bearers, codes, or refresh tokens. Commit in the plugin repo only. Do not push or tag. Do not write the backfill file in this task.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 240s -run 'TestMCPConsentSmoke|TestAuthorizationsSmoke|TestMCPAdvertisedScopes' .</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL, or TestAuthorizationsSmoke has no PASS line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- Show JSON still has scopes as a string array, plus scope_details and client.logo_url.
|
||||
- MCPConsentDecide does not call SaveConsent.
|
||||
- authorizations_smoke_test.go expects seven keys ending in kind.
|
||||
- The backend-only consent POST still expects 422 no_grantable_scopes.
|
||||
- revoke deletes models.MCPCode after lockUserGrants, and the revoked event has no TokenID.
|
||||
</acceptance_criteria>
|
||||
<done>Consent, revoke, and the authorizations list behave as D-06 through D-13 and D-15, and the existing smokes pass.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking" auto_select="write-noop-rollback">
|
||||
<name>Confirm the one-way MCP consent backfill</name>
|
||||
<reversibility rating="one-way">D-14 writes consent rows into golem15_oauthserver_consents on every install. A later rollback cannot tell those rows from consents the new code created.</reversibility>
|
||||
<decision>Write the D-14 backfill that inserts one golem15_oauthserver_consents row per live MCP user and client, with Rollback as a no-op?</decision>
|
||||
<context>D-14 is already the chosen behaviour. This checkpoint is the one-way door before the migration file exists. Rollback must not delete every MCP consent, because that would also delete consents created after the migration. The next task writes the file only if write-noop-rollback is accepted. On resume, before that task creates or refuses the migration, write `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-03-backfill-decision.txt` containing only the accepted option id, `write-noop-rollback` or `hold`. Do not create the migration in this task.</context>
|
||||
<options>
|
||||
<option id="write-noop-rollback">
|
||||
<name>Write the backfill, Rollback is a no-op</name>
|
||||
<pros>Live MCP grants become revocable. A second migrate inserts nothing. Rollback cannot destroy later consents.</pros>
|
||||
<cons>Rows stay after a down migration. Undo is a hand-written delete, not the migration Rollback.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Do not write the migration in this run</name>
|
||||
<pros>No rows are inserted on install until a later explicit decision.</pros>
|
||||
<cons>Grants that predate this release still have no consent row, so per-client revoke answers 404 for them. D-14 stays unmet.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Select write-noop-rollback or hold</resume-signal>
|
||||
<read_first>
|
||||
.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-CONTEXT.md D-14
|
||||
../sm-oauthserver-plugin/updates/202610230001_add_backend_user_id.go
|
||||
</read_first>
|
||||
<acceptance_criteria>
|
||||
- The accepted option is recorded before any backfill file is created.
|
||||
- That record is `32.1-03-backfill-decision.txt` in this phase directory and its entire text is `write-noop-rollback` or `hold`.
|
||||
- hold means the next task does not add a migration.
|
||||
</acceptance_criteria>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Backfill MCP consents for live grants</name>
|
||||
<reversibility rating="one-way">D-14 inserts consent rows on every consuming install. Rollback is a no-op and does not delete those rows.</reversibility>
|
||||
<files>../sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go, .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-03-backfill-decision.txt</files>
|
||||
<read_first>
|
||||
../sm-oauthserver-plugin/updates/202610230001_add_backend_user_id.go (Register pattern)
|
||||
../sm-oauthserver-plugin/models/consent.go
|
||||
../sm-oauthserver-plugin/models/access_token.go
|
||||
../sm-oauthserver-plugin/models/refresh_token.go
|
||||
../sm-oauthserver-plugin/models/client.go ClientKindMCP
|
||||
</read_first>
|
||||
<action>
|
||||
Run this task only when the checkpoint option write-noop-rollback was accepted. If the accepted option is hold, stop without creating a migration file and say so in the summary. Do not rewrite `32.1-03-backfill-decision.txt` after this task starts changing the plugin tree. If you resumed and that record is not on disk yet, write the accepted option id into it before creating or deleting the migration, then leave the record unchanged. The verify reads that record and fails when it is absent or disagrees with the migration file.
|
||||
|
||||
Add updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go with migration ID 202610280001_backfill_golem15_oauthserver_mcp_consents, registered from init via Register, so it sorts after 202610230001_add_golem15_oauthserver_backend_user_id. Migrate, in Go on the transaction: one row per (user_id, client_id) where the client kind is mcp and the pair has at least one live access or refresh token. Live means revoked_at IS NULL and (expires_at IS NULL or expires_at is in the future). Skip the pair when any consent row already exists. scopes is the union of those tokens' scopes arrays; if any live token has offline_access true, include the string offline_access. created_at and updated_at are the earliest created_at among the live tokens. last_used_at stays null. A second run inserts nothing. Rollback returns nil and its comment says the writes are one-way and a down migration must not delete MCP consents. Do not delete token rows. Commit in the plugin repo only. Do not push or tag.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>python3 -c 'import pathlib,sys; rec=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/summercms.go/.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-03-backfill-decision.txt"); mig=pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go");
|
||||
assert rec.is_file(), "checkpoint record absent"
|
||||
opt=rec.read_text().strip()
|
||||
exists=mig.is_file()
|
||||
assert opt in ("write-noop-rollback","hold"), "checkpoint record is not an option id"
|
||||
if opt=="hold":
|
||||
assert not exists, "hold but migration file exists"
|
||||
sys.exit(0)
|
||||
text=mig.read_text() if exists else ""
|
||||
assert exists, "write-noop-rollback but migration file missing"
|
||||
for s in ("202610280001_backfill_golem15_oauthserver_mcp_consents","Register","golem15_oauthserver_consents"):
|
||||
assert s in text, "migration missing "+s
|
||||
i=text.find("Rollback")
|
||||
assert i>=0, "Rollback missing"
|
||||
rest=text[i:]
|
||||
nl=rest.find("\nfunc ")
|
||||
body=rest if nl<0 else rest[:nl]
|
||||
assert ".Delete(" not in body and "DELETE FROM" not in body, "Rollback deletes"
|
||||
assert "return nil" in body, "Rollback does not return nil"'</automated>
|
||||
<fails_when>non-zero exit, stdout or stderr contains checkpoint record absent, checkpoint record is not an option id, hold but migration file exists, write-noop-rollback but migration file missing, migration missing, Rollback missing, Rollback deletes, or Rollback does not return nil</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- When write-noop-rollback was accepted, the migration ID sorts after 202610230001_add_golem15_oauthserver_backend_user_id, Rollback does not delete consents, and the file is committed in the plugin repo.
|
||||
- When hold was accepted, that file does not exist.
|
||||
</acceptance_criteria>
|
||||
<done>D-14 is either written as an idempotent no-op-rollback migration or explicitly held. It is not written before the checkpoint.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| Browser POST /oauth/mcp/requests/{request} | Signed-in user submits decision and scopes. The body is untrusted. |
|
||||
| DELETE /oauth/authorizations/{client_id} | Signed-in user names a client. Another user's row must stay. |
|
||||
| Operator config mcp_scopes | Names enter metadata and the allow-list at boot. |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-32.1-06 | Elevation of privilege | MCP consent upsert | high | mitigate | Replace scopes on a real decision. Do not call SaveConsent, which unions. Silent re-grant only TouchConsent. Deny does not change the row (D-08). |
|
||||
| T-32.1-07 | Elevation of privilege | authorizations.revoke | high | mitigate | lockUserGrants exclusive inside the transaction before deletes. Delete models.MCPCode for the pair plus consent, auth codes, access and refresh. Event is MCPSubjectRevoked with ClientID and zero TokenID (D-12, D-15). |
|
||||
| T-32.1-08 | Information disclosure | PendingRequest / IssueCode | high | mitigate | Keep owner checks. Missing, foreign, expired and used stay wristband.ErrPendingNotFound. Do not add a lookup by request id alone. |
|
||||
| T-32.1-09 | Tampering | grantedScopes when scopes is absent | medium | mitigate | A POST of decision allow without scopes still grants the whole requested set. scope_details and kind are response fields. Old pages ignore them. |
|
||||
| T-32.1-10 | Information disclosure | consent and revoke logs | medium | mitigate | Do not log the bearer, the authorization code, or a refresh token. Errors stay the existing JSON codes. |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
TestMCPAdvertisedScopes passes under -short. TestMCPConsentSmoke and TestAuthorizationsSmoke pass against Postgres. The backfill file exists only after write-noop-rollback.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- One scope slice drives the MCP server and the verifier.
|
||||
- Consent replace, offline_access, revoke-deletes-MCP-code, and kind are in the plugin.
|
||||
- D-14 is gated and, when accepted, idempotent with a no-op rollback.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-03-SUMMARY.md` when done.
|
||||
</output>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Config key golem15.oauthserver.mcp_scopes and env SUMMER_GOLEM15__OAUTHSERVER__MCP_SCOPES
|
||||
- Unexported advertised-scope builder used by NewServers
|
||||
- MCPTokenVerifier.MCPScopesSupported
|
||||
- Consent JSON fields scope_details (name, label, description, locked), client.logo_url, consent_required
|
||||
- Phrase keys consent.mcp.backend, consent.mcp.backend_description, consent.mcp.offline_access, consent.mcp.offline_access_description in en and pl
|
||||
- Context override read by mcpTx.MarkIssued for the offline_access column
|
||||
- Replace upsert into golem15_oauthserver_consents
|
||||
- authorization.kind json kind
|
||||
- revoke deletes golem15_oauthserver_mcp_codes under lockUserGrants
|
||||
- Migration ID 202610280001_backfill_golem15_oauthserver_mcp_consents when the checkpoint accepts it
|
||||
@@ -0,0 +1,181 @@
|
||||
---
|
||||
phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||
plan: 03
|
||||
subsystem: auth
|
||||
tags: [mcp, oauth, consent, gormigrate, sm-oauthserver-plugin]
|
||||
|
||||
requires:
|
||||
- phase: 32.1-01
|
||||
provides: pact.MCPAdvertisedScopes and offline access on the pending consent view
|
||||
- phase: 32.1-02
|
||||
provides: pact.MemberTokenScopeCatalog from sm-user-plugin
|
||||
provides:
|
||||
- "One MCP scope slice from golem15.oauthserver.mcp_scopes drives metadata and MCPTokenVerifier.MCPScopesSupported"
|
||||
- "MCP consent replaces stored scopes, revoke deletes MCP codes under lockUserGrants, and authorizations carry kind"
|
||||
- "Migration 202610280001 backfills one consent per live MCP grant and its Rollback does not delete rows"
|
||||
affects: [32.1-05]
|
||||
|
||||
actuals:
|
||||
tokens: 21059
|
||||
tasks: 4
|
||||
commits: 0
|
||||
plan_head_before: 3f52b1ab495b487b03b8e534bdfc6b6676104b00
|
||||
plan_head_after: 3f52b1ab495b487b03b8e534bdfc6b6676104b00
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "MCP scope slice is built once in NewServers and stored on the verifier; OIDC scopes stay untouched"
|
||||
- "MCP consent replace writes golem15_oauthserver_consents directly and does not call SaveConsent"
|
||||
- "The D-14 backfill is one-way: Rollback returns nil and does not delete consents"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go
|
||||
- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-03-backfill-decision.txt
|
||||
modified:
|
||||
- ../sm-oauthserver-plugin/classes/mcp_scopes.go
|
||||
- ../sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||
- ../sm-oauthserver-plugin/controllers/authorizations.go
|
||||
- ../sm-oauthserver-plugin/README.md
|
||||
|
||||
key-decisions:
|
||||
- "Checkpoint write-noop-rollback: backfill live MCP grants into golem15_oauthserver_consents, and Rollback returns nil so a down migration cannot delete consents created later"
|
||||
- "Scope union walks live tokens by created_at (nulls last), then access before refresh, then id; offline_access is appended when any live refresh token has that column set"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: an unknown golem15.oauthserver.mcp_scopes name fails boot and names the key"
|
||||
- "Pattern: MCP revoke takes lockUserGrants, deletes the consent and MCP codes, and emits MCPSubjectRevoked with a zero TokenID"
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Unset mcp_scopes advertises the five fixed names plus every declared member scope; a set list keeps only those declared names; an empty list is the five fixed names; an unknown name fails boot. OIDC discovery scopes stay openid, profile, email."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: mcp_scopes_test.go#TestMCPAdvertisedScopes
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "MCP consent show adds scope_details and client.logo_url, an allow replaces stored scopes instead of calling SaveConsent, revoke deletes MCP codes under lockUserGrants, and GET /oauth/authorizations ends with kind."
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: mcp_consent_smoke_test.go#TestMCPConsentSmoke
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: authorizations_smoke_test.go#TestAuthorizationsSmoke
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "The accepted checkpoint is write-noop-rollback. Migration 202610280001_backfill_golem15_oauthserver_mcp_consents is registered, names golem15_oauthserver_consents, and its Rollback returns nil and does not delete."
|
||||
verification:
|
||||
- kind: other
|
||||
ref: python3 checkpoint record and migration text gate in 32.1-03-PLAN.md task 4
|
||||
status: pass
|
||||
human_judgment: true
|
||||
rationale: "The plan gate checks the decision file and that Rollback returns nil without a delete. It does not insert a live token and migrate twice. Plan 05 TestMCPConsentBackfillIdempotent is the row-level proof."
|
||||
|
||||
duration: 24min
|
||||
completed: 2026-10-28
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 32.1 Plan 03: MCP scope slice, consent replace, and one-way backfill Summary
|
||||
|
||||
**One MCP scope slice drives metadata and the verifier, consent replace and revoke delete MCP codes, and a no-op-rollback migration backfills consents for live grants**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 24 min
|
||||
- **Started:** 2026-10-28T14:18:42Z
|
||||
- **Completed:** 2026-10-28T14:43:00Z
|
||||
- **Tasks:** 4
|
||||
- **Files modified:** 17
|
||||
|
||||
The clock starts at the task 1 commit. This session resumed after the checkpoint.
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- `golem15.oauthserver.mcp_scopes` filters declared member scopes. The fixed names `read`, `write`, `ai`, `offline_access`, and `backend` are always advertised, in that order, then declared names. An unknown name fails boot and names the key. `MCPTokenVerifier.MCPScopesSupported` returns that same slice. OIDC scopes are not rewritten.
|
||||
- An MCP allow replaces `golem15_oauthserver_consents` for the user and client and does not call `SaveConsent`. `offline_access` stays a column, copied into the consent scope list when it was granted. Revoke takes `lockUserGrants`, deletes the consent, OIDC codes, MCP codes, access tokens, and refresh tokens, then emits `MCPSubjectRevoked` with `ClientID` set and `TokenID` left zero. `GET /oauth/authorizations` always ends with `kind` `oidc` or `mcp`.
|
||||
- Checkpoint option `write-noop-rollback` was accepted. The decision file was written before the migration existed. `202610280001_backfill_golem15_oauthserver_mcp_consents` inserts one consent per MCP user and client that has a live access or refresh token and no consent yet. Live means `revoked_at` is null and `expires_at` is null or still in the future. A second run inserts nothing. `Rollback` returns nil and does not delete consents.
|
||||
|
||||
## Task Commits
|
||||
|
||||
Plugin repo `sm-oauthserver-plugin` on `master`. summercms.go had no commits in the measured range `3f52b1ab495b487b03b8e534bdfc6b6676104b00..HEAD` at summary time (`commits: 0`). The decision record is committed with this summary.
|
||||
|
||||
1. **Task 1: Advertise one MCP scope slice** - `644641a` (feat)
|
||||
2. **Task 2: MCP consent replace, revoke, and kind** - `52529c6` (feat)
|
||||
3. **Task 3: Confirm the one-way MCP consent backfill** - option `write-noop-rollback` recorded in `32.1-03-backfill-decision.txt` before the migration file was created. No plugin commit.
|
||||
4. **Task 4: Backfill MCP consents for live grants** - `a409074` (feat)
|
||||
|
||||
**Plan metadata:** this summary, the decision record, and the roadmap progress update.
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `../sm-oauthserver-plugin/config/config.yaml` - `mcp_scopes` and the `SUMMER_GOLEM15__OAUTHSERVER__MCP_SCOPES` spelling
|
||||
- `../sm-oauthserver-plugin/classes/mcp_scopes.go` - the one advertised slice and the unknown-name boot error
|
||||
- `../sm-oauthserver-plugin/classes/mcp_verifier.go` - `MCPScopesSupported`
|
||||
- `../sm-oauthserver-plugin/servers.go` - assigns that slice only to the MCP server
|
||||
- `../sm-oauthserver-plugin/mcp_scopes_test.go` - unset, set, empty, and unknown name
|
||||
- `../sm-oauthserver-plugin/controllers/mcp_consent_api.go` - `scope_details`, `logo_url`, `offline_access`, consent replace
|
||||
- `../sm-oauthserver-plugin/controllers/authorizations.go` - `kind` and revoke of MCP codes under `lockUserGrants`
|
||||
- `../sm-oauthserver-plugin/classes/mcp_store.go` - `MarkIssued` reads the offline-access override
|
||||
- `../sm-oauthserver-plugin/classes/mcp_backend_binding.go` - context value for that override
|
||||
- `../sm-oauthserver-plugin/lang/en/lang.yaml` - backend and offline_access consent phrases
|
||||
- `../sm-oauthserver-plugin/lang/pl/lang.yaml` - the same phrases in Polish
|
||||
- `../sm-oauthserver-plugin/README.md` - scope filter, replace versus the OIDC union, kind, revoke, and old DCR ceilings
|
||||
- `../sm-oauthserver-plugin/authorizations_smoke_test.go` - seven keys ending in `kind`
|
||||
- `../sm-oauthserver-plugin/mcp_consent_smoke_test.go` - smoke expectations kept in step with the new JSON
|
||||
- `../sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go` - idempotent one-way consent backfill
|
||||
- `32.1-03-backfill-decision.txt` - the entire text is `write-noop-rollback`
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- The checkpoint accepted `write-noop-rollback`. Rollback must not delete every MCP consent, because those rows cannot be told from consents the new code creates after the migration. Undo is a hand-written delete, not the migration Rollback.
|
||||
- The union walks live tokens from earliest `created_at` (nulls last), access before refresh on a tie, then id. Empty scope names are dropped. `offline_access` is added at the end when any live refresh token has the column set and the word is not already present. Access tokens have no such column. `created_at` and `updated_at` are that earliest token time, or null when every live token has none. `last_used_at` stays null. A pair with any existing consent row is skipped, and the insert also uses `WHERE NOT EXISTS`.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
`state.advance-plan` was not run. It has no phase argument and advances whatever Current Position names. That position is phase 33, from another session. Advancing it would move the wrong plan counter. Roadmap progress for 32.1 was updated with `roadmap.update-plan-progress`. A phase-scoped decision and metric may be recorded in STATE.md. STATE.md and state.json are not committed.
|
||||
|
||||
`go.work` in sm-oauthserver-plugin was already dirty (one replace line). It was not staged, reverted, or committed.
|
||||
|
||||
The plugin commit is on `master`, which is where tasks 1 and 2 of this plan already landed. This resume required that. Nothing was pushed or tagged.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Plan 05 can add `TestMCPConsentBackfillIdempotent` against this migration. A live MCP access token with no consent should gain one row. A refresh token with `offline_access` true should add that word. A pair that already has a consent must be left unchanged. A second migrate inserts nothing. `Rollback` returns nil.
|
||||
|
||||
Plan 04 (vue-oauth-layer) can read `scope_details`, `logo_url`, `consent_required`, and `kind`. It does not depend on the backfill having run.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: ../sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go
|
||||
- FOUND: ../sm-oauthserver-plugin/config/config.yaml
|
||||
- FOUND: ../sm-oauthserver-plugin/classes/mcp_scopes.go
|
||||
- FOUND: ../sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||
- FOUND: ../sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||
- FOUND: ../sm-oauthserver-plugin/controllers/authorizations.go
|
||||
- FOUND: ../sm-oauthserver-plugin/README.md
|
||||
- FOUND: 32.1-03-backfill-decision.txt (`write-noop-rollback`)
|
||||
- FOUND: 644641a
|
||||
- FOUND: 52529c6
|
||||
- FOUND: a409074
|
||||
- Python task-4 gate: exit 0
|
||||
- `go test -count=1 -timeout 240s -run 'TestAuthorizationsSmoke|TestMCPAdvertisedScopes'` exit 0
|
||||
- `go test -count=1 -timeout 240s -run 'TestMCPConsentSmoke|TestMCPAdvertisedScopes'` exit 0
|
||||
- `TestAuthorizationsSmoke` PASS against Postgres, so the new migration applies on an empty database
|
||||
|
||||
---
|
||||
*Phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con*
|
||||
*Completed: 2026-10-28*
|
||||
@@ -0,0 +1 @@
|
||||
write-noop-rollback
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
phase: 32.1
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 4
|
||||
depends_on:
|
||||
- 32.1-03
|
||||
files_modified:
|
||||
- ../vue-oauth-layer/package.json
|
||||
- ../vue-oauth-layer/nuxt.config.ts
|
||||
- ../vue-oauth-layer/app/pages/connect.vue
|
||||
- ../vue-oauth-layer/app/utils/connectConsent.ts
|
||||
- ../vue-oauth-layer/tests/connect.test.ts
|
||||
- ../vue-oauth-layer/README.md
|
||||
- ../vue-oauth-layer/.playground/nuxt.config.ts
|
||||
autonomous: true
|
||||
requirements: []
|
||||
estimate:
|
||||
tokens: 42000
|
||||
raw_tokens: 42000
|
||||
tasks: 2
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-3: The layer page /connect renders the MCP consent show JSON as checkboxes. read is locked in the UI. The server is not asked to force read into the grant (D-06, D-17)."
|
||||
- "Client name, logo, scope label, scope description and the admin name are text, never raw HTML (D-07)."
|
||||
- "backend shows the also-act-as-admin line when backend_admin is set. A 409 backend_link_changed fetches the show again (D-17)."
|
||||
- "No application /connect page is edited, replaced, or deleted. The repo is not tagged or pushed in this plan."
|
||||
artifacts:
|
||||
- path: ../vue-oauth-layer/app/pages/connect.vue
|
||||
provides: "Nuxt layer page /connect"
|
||||
contains: "connectConsent"
|
||||
- path: ../vue-oauth-layer/app/utils/connectConsent.ts
|
||||
provides: "Pure mapping from show JSON to POST body"
|
||||
contains: "allowBody"
|
||||
- path: ../vue-oauth-layer/tests/connect.test.ts
|
||||
provides: "node:test coverage of the mapping"
|
||||
contains: "node:test"
|
||||
key_links:
|
||||
- from: app/pages/connect.vue
|
||||
to: app/utils/connectConsent.ts
|
||||
via: the page imports the pure functions the tests import
|
||||
pattern: allowBody
|
||||
- from: allowBody
|
||||
to: POST /oauth/mcp/requests/{request}
|
||||
via: JSON decision, scopes, backend_admin
|
||||
pattern: decision
|
||||
---
|
||||
|
||||
<objective>
|
||||
Initial public Nuxt layer vue-oauth-layer, one plan (D-17, D-06, D-07). It provides /connect for redirect consent from the MCP consent JSON plan 03 returns. Apps adopt it later. This plan does not migrate any app and does not tag or push.
|
||||
|
||||
Purpose: a redirect-mode application can render per-scope consent without copying a page, while an application that already has /connect keeps its own page because Nuxt project files win over a layer.
|
||||
Output: a new repo beside vue-menu-layer, with node --test and a README. The first tag is plan 05's checkpoint, not this plan.
|
||||
|
||||
Copy vue-menu-layer's skeleton (fileURLToPath, node --test, no extra runtime dependencies), not vue-journal-layer. Sibling path of the template: /media/nvme/dev/golem15/summercms.io/summercms/vue-menu-layer. New repo path: /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-CONTEXT.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-RESEARCH.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-PATTERNS.md
|
||||
@../vue-menu-layer/package.json
|
||||
@../vue-menu-layer/nuxt.config.ts
|
||||
@../vue-menu-layer/tests/menuLinks.test.ts
|
||||
@../sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Tracer: show JSON maps to a locked-read allow body</name>
|
||||
<precondition>/media/nvme/dev/golem15/summercms.io/summercms/vue-menu-layer/package.json exists, and /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer is either absent or already this phase's new repo. Halt if that path is some other project.</precondition>
|
||||
<reversibility rating="costly">D-17: the layer's /connect props and POST body become the contract apps will pin by tag.</reversibility>
|
||||
<files>../vue-oauth-layer/package.json, ../vue-oauth-layer/nuxt.config.ts, ../vue-oauth-layer/app/utils/connectConsent.ts, ../vue-oauth-layer/app/pages/connect.vue, ../vue-oauth-layer/tests/connect.test.ts, /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer</files>
|
||||
<read_first>
|
||||
../vue-menu-layer/package.json (engines, peer nuxt 4.4.8, dev vue 3.5.35 and typescript 5.9.3, test script)
|
||||
../vue-menu-layer/nuxt.config.ts (fileURLToPath)
|
||||
../vue-menu-layer/tests/menuLinks.test.ts (node:test and node:assert/strict importing a ts util)
|
||||
../sm-oauthserver-plugin/controllers/mcp_consent_api.go show and decide bodies, after plan 03
|
||||
</read_first>
|
||||
<action>
|
||||
Create the repo with git init at /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer. Do not add a remote, do not push, do not tag.
|
||||
|
||||
package.json name vue-oauth-layer, version 0.1.0, private true, type module, main ./nuxt.config.ts, engines node >= 22.18, peerDependency nuxt 4.4.8, devDependencies nuxt 4.4.8, typescript 5.9.3, vue 3.5.35. Script test is node --test --test-reporter=tap tests/*.test.ts. No other runtime dependency. Do not add sanitize-html, an SEO module, or i18n.
|
||||
|
||||
nuxt.config.ts builds every path with fileURLToPath(new URL('.', import.meta.url)). No relative layer path. No Nuxt modules. compatibilityDate 2025-07-15. devtools disabled.
|
||||
|
||||
app/utils/connectConsent.ts exports pure functions the page and the tests both import. scopeBoxes(show) returns one box per scope_details entry, each checked to start, with locked copied from the detail. allowBody(show, clearedNames) returns decision allow. When show.consent_required is false, the body is decision allow and omits scopes, so the server keeps the stored set. Otherwise scopes is the checked names. A box with locked true cannot be cleared: read stays in scopes when it was requested. denyBody returns decision deny. backendAdminLogin(show) is show.backend_admin.login when backend_admin is non-null and backend is among the scopes, else absent. shouldRefetch(status, errorCode) is true only for HTTP 409 and error backend_link_changed.
|
||||
|
||||
app/pages/connect.vue reads the request query, calls those functions, and posts JSON to /oauth/mcp/requests/{request} on the same origin with credentials included. It does not add a Nitro proxy. Render label, description, client name and admin name as text. Do not use v-html. The tracer page must already import connectConsent.ts so the test and the page share one implementation. A 401 redirects to the loginPath prop, default /login.
|
||||
|
||||
tests/connect.test.ts: one show payload with scope_details for read (locked true) and write (locked false), clearing write, allowBody scopes are read only. consent_required false yields a body without a scopes key. The test reads app/pages/connect.vue and fails if the source contains v-html. Run pnpm install in the new repo so the test script's node can resolve the package, then commit only inside vue-oauth-layer. Do not git add -A. Do not edit any app.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pnpm --prefix /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer test</automated>
|
||||
<fails_when>non-zero exit, or the tap output contains `not ok`, or a line `# tests 0`, or a line `# fail` whose count is not 0</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- pnpm test exits 0 and the locked-read case passes.
|
||||
- connect.vue imports the same module the test imports.
|
||||
- No v-html in app/pages/connect.vue.
|
||||
- No app repository has a diff from this task.
|
||||
</acceptance_criteria>
|
||||
<done>A show payload becomes an allow POST that keeps locked read, and the page uses that function.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Finish /connect and the layer README</name>
|
||||
<reversibility rating="costly">The page copy and the README install line are what a later tag publishes (D-17).</reversibility>
|
||||
<files>../vue-oauth-layer/app/pages/connect.vue, ../vue-oauth-layer/app/utils/connectConsent.ts, ../vue-oauth-layer/tests/connect.test.ts, ../vue-oauth-layer/README.md, ../vue-oauth-layer/.playground/nuxt.config.ts, /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer</files>
|
||||
<read_first>
|
||||
../vue-oauth-layer/app/utils/connectConsent.ts
|
||||
../vue-oauth-layer/app/pages/connect.vue
|
||||
../vue-menu-layer/README.md install and extends example, as the shape to copy with this layer's name
|
||||
../sm-oauthserver-plugin/controllers/mcp_consent_api.go backend_link_changed and backend_admin
|
||||
</read_first>
|
||||
<action>
|
||||
Complete the page (D-17). Show the client name and, when logo_url is non-empty, an img whose alt is the client name as text. Every requested scope starts checked. read's checkbox is disabled and checked, and the POST from a shown form always includes read when it was requested. The server does not force read; do not send a flag that would make it do so. offline_access, backend and declared scopes can be cleared. When backend_admin is non-null and backend is requested, show the sentence "also act as admin" followed by the admin name as text, and send backend_admin set to backend_admin.login. Allow posts decision allow. Deny posts decision deny. On 409 with error backend_link_changed, fetch the show JSON again and render it. When consent_required is false, post decision allow immediately and do not render checkboxes.
|
||||
|
||||
Do not log the user in. Do not read a product name from an app. loginPath prop default remains /login, documented as the handoff when the JSON route answers 401.
|
||||
|
||||
Tests cover: locked read stays in the POST when the box cannot be cleared; a cleared write is absent; consent_required false omits scopes; 409 backend_link_changed is the refetch signal and a 422 is not; backend_admin.login is sent only when the line is shown. The source check that rejects v-html stays.
|
||||
|
||||
README: what the layer is, the install shape pnpm add git+https://git.golem15.com/golem15/vue-oauth-layer.git#vX.Y.Z, and extends ['vue-oauth-layer']. Say the tag does not exist until a later release the user accepts. Say an application's own app/pages/connect.vue wins over this layer, and this repo does not edit those pages. Do not name a consuming application. .playground/nuxt.config.ts extends the layer via fileURLToPath of the parent directory so a local dev server resolves the layer. No new dependency. Commit in the layer repo only. Do not push or tag.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pnpm --prefix /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer test</automated>
|
||||
<fails_when>non-zero exit, or the tap output contains `not ok`, or a line `# tests 0`, or a line `# fail` whose count is not 0</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- The page implements allow, deny, locked read, the admin line, and the 409 re-show.
|
||||
- README shows the git pin shape and extends, and does not claim a tag was pushed.
|
||||
- pnpm test passes.
|
||||
</acceptance_criteria>
|
||||
<done>D-17's /connect behaviour is in the layer, tested, and not tagged.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| MCP consent JSON to the browser | Client name, labels and admin name are attacker-influenced (DCR name, phrase text). |
|
||||
| Page POST back to the consent route | The browser can omit fields. The server intersection is the control. This page must not widen it. |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-32.1-11 | Tampering | app/pages/connect.vue | high | mitigate | Render label, description, client name and admin name as text. The unit test fails if the page source contains v-html. Do not bind those strings as HTML. |
|
||||
| T-32.1-12 | Elevation of privilege | read checkbox | low | accept | The checkbox is disabled and the page's own POST includes read when the form was shown. A client that omits read only narrows the grant. The server must not reinsert read, because the existing 422 smoke posts backend alone. Narrowing is not a privilege gain. |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
pnpm test in vue-oauth-layer passes. No app /connect file is modified. No tag and no push.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- /connect maps the consent JSON, locks read in the UI, and refetches on backend_link_changed.
|
||||
- The layer has no runtime dependency beyond the Nuxt peer the menu layer already pins.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-04-SUMMARY.md` when done.
|
||||
</output>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer
|
||||
- Repo /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer
|
||||
- app/pages/connect.vue
|
||||
- app/utils/connectConsent.ts exports scopeBoxes, allowBody, denyBody, backendAdminLogin, shouldRefetch
|
||||
- tests/connect.test.ts
|
||||
- Prop loginPath default /login
|
||||
- README install shape git+https://git.golem15.com/golem15/vue-oauth-layer.git#vX.Y.Z
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||
plan: 04
|
||||
subsystem: auth
|
||||
tags: [nuxt, oauth, mcp, consent, vue-oauth-layer]
|
||||
|
||||
requires:
|
||||
- phase: 32.1-03
|
||||
provides: MCP consent show JSON with scope_details, logo_url, consent_required, and 409 backend_link_changed
|
||||
provides:
|
||||
- "Public Nuxt layer vue-oauth-layer with /connect for MCP redirect consent"
|
||||
- "allowBody keeps locked read, omits scopes when consent_required is false, and sends backend_admin.login only with the admin line"
|
||||
- "A 409 backend_link_changed refetches the show; the layer is not tagged or pushed"
|
||||
affects: [32.1-05]
|
||||
|
||||
actuals:
|
||||
tokens: 65479
|
||||
tasks: 2
|
||||
commits: 0
|
||||
plan_head_before: 23238ccd47b615529948d4f094713928272a308a
|
||||
plan_head_after: 23238ccd47b615529948d4f094713928272a308a
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "vue-oauth-layer copies the vue-menu-layer skeleton: fileURLToPath paths, nuxt 4.4.8 peer, node --test, no extra runtime dependency"
|
||||
- "The page and the tests import app/utils/connectConsent.ts; labels are text interpolations"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- ../vue-oauth-layer/package.json
|
||||
- ../vue-oauth-layer/nuxt.config.ts
|
||||
- ../vue-oauth-layer/app/pages/connect.vue
|
||||
- ../vue-oauth-layer/app/utils/connectConsent.ts
|
||||
- ../vue-oauth-layer/tests/connect.test.ts
|
||||
- ../vue-oauth-layer/README.md
|
||||
- ../vue-oauth-layer/.playground/nuxt.config.ts
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "The new repo's branch is main, matching the other Nuxt layers. It has no remote and no tag."
|
||||
- "A 409 backend_link_changed renders the show again and does not post immediately, so a stored consent cannot loop."
|
||||
- "backend_admin.login is sent when the admin line applies and backend stays in the grant, including when scopes are omitted because consent_required is false."
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: scopeBoxes starts every scope_details entry checked and copies locked. allowBody drops cleared names except locked ones."
|
||||
- "Pattern: loginPath defaults to /login and is only the 401 handoff. The layer does not sign the user in."
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "/connect maps the MCP consent show JSON to checkboxes, keeps locked read in the allow POST, and renders client name, labels, descriptions, and the admin name as text."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: vue-oauth-layer/tests/connect.test.ts
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "The admin line, logo alt text, 409 refetch, and an immediate allow when consent_required is false are implemented and covered. The README shows the git pin shape and says the tag does not exist yet."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: vue-oauth-layer/tests/connect.test.ts
|
||||
status: pass
|
||||
- kind: other
|
||||
ref: README.md install line and empty git tag list
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: 14min
|
||||
completed: 2026-10-28
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 32.1 Plan 04: vue-oauth-layer /connect Summary
|
||||
|
||||
**A new Nuxt layer renders MCP redirect consent at /connect, locks read in the UI, and refetches when the administrator link changes**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 14 min
|
||||
- **Started:** 2026-10-28T14:45:32Z
|
||||
- **Completed:** 2026-10-28T14:59:10Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 13
|
||||
|
||||
`actuals.tokens` is chars/4 of `git log -p` in vue-oauth-layer (261918 / 4). The pnpm lockfile is most of that diff. summercms.go has no production commits in the measured range.
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Created `/media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer` with `git init -b main`. No remote, no tag, no push. Peer dependency is nuxt 4.4.8. Dev dependencies are nuxt 4.4.8, typescript 5.9.3, and vue 3.5.35. There is no other runtime dependency.
|
||||
- `app/utils/connectConsent.ts` maps show JSON to checkboxes and the POST body. Locked `read` stays in `scopes` when it was requested. `consent_required: false` omits `scopes`. `shouldRefetch` is true only for HTTP 409 and `backend_link_changed`.
|
||||
- `app/pages/connect.vue` imports that module, reads `?request=`, and calls `GET` and `POST /oauth/mcp/requests/{request}` on the same origin with credentials included. It does not add a Nitro proxy. Client name, scope label, scope description, logo alt, and the administrator name are text. The page source does not contain `v-html`. A 401 navigates to the `loginPath` prop, default `/login`.
|
||||
- When `backend_admin` is set and `backend` was requested, the page shows "also act as admin" and the administrator name, and the allow body sends `backend_admin.login` unless `backend` was cleared. A non-empty `logo_url` is an image. When `consent_required` is false the page posts allow immediately and does not render checkboxes. A 409 `backend_link_changed` loads the show again and renders it instead of posting again.
|
||||
- `pnpm test` passes: 8 tests, 0 failed.
|
||||
|
||||
## Task Commits
|
||||
|
||||
Layer repo `vue-oauth-layer` on `main`. summercms.go had no commits in the measured range `23238ccd47b615529948d4f094713928272a308a..HEAD` at summary time (`commits: 0`).
|
||||
|
||||
1. **Task 1: Tracer: show JSON maps to a locked-read allow body** - `02c466e` (feat)
|
||||
2. **Task 2: Finish /connect and the layer README** - `37c1e12` (feat)
|
||||
3. **Rule 1 follow-up: empty redirect leaves the page ready** - `7f805b3` (fix)
|
||||
|
||||
**Plan metadata:** this summary and the roadmap progress update, committed in summercms.go after this file was written.
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `../vue-oauth-layer/package.json` - layer package, test script, pinned Nuxt peer
|
||||
- `../vue-oauth-layer/nuxt.config.ts` - absolute css path via fileURLToPath, no modules
|
||||
- `../vue-oauth-layer/app/utils/connectConsent.ts` - scopeBoxes, allowBody, denyBody, backendAdminLogin, shouldRefetch
|
||||
- `../vue-oauth-layer/app/pages/connect.vue` - /connect page
|
||||
- `../vue-oauth-layer/app/assets/css/connect.css` - neutral tokens for the page
|
||||
- `../vue-oauth-layer/tests/connect.test.ts` - node:test mapping and a source check against raw HTML
|
||||
- `../vue-oauth-layer/README.md` - install shape, extends, loginPath, and the unpushed tag
|
||||
- `../vue-oauth-layer/.playground/nuxt.config.ts` - playground extends the layer by an absolute path
|
||||
- `../vue-oauth-layer/tsconfig.json`, `.gitignore`, `.nvmrc`, `pnpm-workspace.yaml`, `pnpm-lock.yaml` - menu-layer skeleton so install and Vite resolve inside the layer
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- The repository branch is `main`, the same branch the sibling layers use. `git init` alone would have created `master` because `init.defaultBranch` is master. The default-branch guard reports `main` as protected: this repo has no `.planning/config.json`, so `git.allow_default_branch_commits` is not set. The commits are on `main` anyway. This is a new repository whose only branch is the one the plan publishes. It is not a commit on summercms.go's default branch. No planning config was added to the layer to silence the guard.
|
||||
- After `409 backend_link_changed` the page fetches the show and renders it. It does not post that show immediately. An immediate allow would send the same decision again and loop while `consent_required` stays false.
|
||||
- `backend_admin` is omitted when the user clears `backend`, because the server only checks that field when `backend` is in the grant. When `consent_required` is false, scopes are omitted and `backend_admin.login` is still sent if the admin line applies, so the full stored grant does not 409 on the linked administrator.
|
||||
- A decision response with an empty `redirect_uri` sets the page back to ready instead of leaving it on Loading.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - Missing critical] Menu-layer skeleton files the plan list did not name**
|
||||
- **Found during:** Task 1
|
||||
- **Issue:** `pnpm install` creates `node_modules`, Vite reads `tsconfig.json` from the layer, and `nuxt.config.ts` was required to build every path with `fileURLToPath`. A config with no path would not satisfy that rule.
|
||||
- **Fix:** Added `.gitignore`, `tsconfig.json`, `.nvmrc`, `pnpm-workspace.yaml` (the menu layer's `allowBuilds`), `pnpm-lock.yaml`, and `app/assets/css/connect.css` wired from the absolute layer directory. `dev` and `dev:prepare` scripts match the menu layer so the playground can start. No package beyond the pinned Nuxt, Vue, and TypeScript set was added.
|
||||
- **Files modified:** those skeleton files in vue-oauth-layer
|
||||
- **Commit:** `02c466e`
|
||||
|
||||
**2. [Rule 1 - Bug] Empty redirect_uri left the page on Loading**
|
||||
- **Found during:** Task 2, after the page commit
|
||||
- **Issue:** A 200 decision body with an empty `redirect_uri` never left `submitting`, so the template stayed on Loading.
|
||||
- **Fix:** Set state back to ready when the body has no redirect.
|
||||
- **Files modified:** `app/pages/connect.vue`
|
||||
- **Commit:** `7f805b3`
|
||||
|
||||
**3. [Rule 3 - Blocking] `git init -b main` instead of the global default `master`**
|
||||
- **Found during:** Task 1
|
||||
- **Issue:** `init.defaultBranch` is `master`. vue-menu-layer, vue-journal-layer, vue-faq-layer, and vue-paymentgateway-layer are all on `main`.
|
||||
- **Fix:** Initialized the repo with `-b main`.
|
||||
- **Files modified:** none (branch name only)
|
||||
- **Commit:** `02c466e` (root commit on `main`)
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
`state.advance-plan` was not run. It has no phase argument and advances whatever Current Position names. That position is phase 33, from another session. Advancing it would move the wrong plan counter. Roadmap progress for 32.1 was updated with `roadmap.update-plan-progress`. A phase-scoped decision and metric may be recorded in STATE.md. STATE.md and state.json are not committed.
|
||||
|
||||
The default-branch guard returned protected for `main` inside the new repo. See Decisions Made. Nothing was pushed or tagged.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
The install line in the README does not resolve until someone accepts a later release and the tag exists. Plan 05 owns that checkpoint. This plan did not create the git remote `git.golem15.com/golem15/vue-oauth-layer.git`.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Plan 05 can run `pnpm test` in vue-oauth-layer. The first tag, if the release checkpoint says so, is v0.1.0 on this repo. An application that already has `app/pages/connect.vue` keeps that page. This plan did not edit one.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: ../vue-oauth-layer/package.json
|
||||
- FOUND: ../vue-oauth-layer/nuxt.config.ts
|
||||
- FOUND: ../vue-oauth-layer/app/pages/connect.vue
|
||||
- FOUND: ../vue-oauth-layer/app/utils/connectConsent.ts
|
||||
- FOUND: ../vue-oauth-layer/tests/connect.test.ts
|
||||
- FOUND: ../vue-oauth-layer/README.md
|
||||
- FOUND: ../vue-oauth-layer/.playground/nuxt.config.ts
|
||||
- FOUND: 02c466e
|
||||
- FOUND: 37c1e12
|
||||
- FOUND: 7f805b3
|
||||
- `pnpm test`: 8 passed, 0 failed, no `not ok`
|
||||
- `git remote` empty, `git tag` empty
|
||||
- `app/pages/connect.vue` does not contain `v-html`
|
||||
|
||||
---
|
||||
*Phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con*
|
||||
*Completed: 2026-10-28*
|
||||
@@ -0,0 +1,383 @@
|
||||
---
|
||||
phase: 32.1
|
||||
plan: 05
|
||||
type: execute
|
||||
wave: 5
|
||||
depends_on:
|
||||
- 32.1-01
|
||||
- 32.1-02
|
||||
- 32.1-03
|
||||
- 32.1-04
|
||||
files_modified:
|
||||
- modules/pact/mcp_call_negative_test.go
|
||||
- modules/pier/dispatch_mcpcall_test.go
|
||||
- modules/pier/prm_scopes_test.go
|
||||
- ../sm-user-plugin/classes/mcp_guard_test.go
|
||||
- ../sm-oauthserver-plugin/mcp_consent_test.go
|
||||
- ../sm-oauthserver-plugin/authorizations_kind_test.go
|
||||
- ../sm-oauthserver-plugin/mcp_backfill_test.go
|
||||
- ../sm-oauthserver-plugin/go.mod
|
||||
autonomous: false
|
||||
requirements: []
|
||||
estimate:
|
||||
tokens: 58000
|
||||
raw_tokens: 58000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "SC-2: MCPCallFrom on a bare context is ok false, and a frontend tool and a backend tool each carry MCPCall for the guard that owns the tool (D-09, D-11)."
|
||||
- "SC-1: Implies cases on the v0.1.14 worktree cover OAuth read, personal-token non-expansion, and write not satisfying Implies read (D-01a). PRM with and without MCPAdvertisedScopes is asserted (D-04)."
|
||||
- "SC-3: Consent replace does not merge, offline_access follows the column, revoke deletes the MCP code, authorizations kind is mcp or oidc, and the backfill is idempotent when the migration exists (D-06, D-08, D-12, D-13, D-14)."
|
||||
- "SC-4: TestDocsTree and docs:build --check pass. Tags, pushes, and the changelog post happen only after the release checkpoint accepts them (D-16)."
|
||||
artifacts:
|
||||
- path: modules/pact/mcp_call_negative_test.go
|
||||
provides: "Bare-context MCPCallFrom and a FrontendTokenScope literal without Implies"
|
||||
contains: "TestMCPCallFromBareContext"
|
||||
- path: modules/pier/dispatch_mcpcall_test.go
|
||||
provides: "Frontend and backend dispatch both set MCPCall"
|
||||
contains: "TestDispatchMCPCallBothGuards"
|
||||
- path: ../sm-oauthserver-plugin/mcp_consent_test.go
|
||||
provides: "Replace, offline_access, and revoke-deletes-code cases"
|
||||
contains: "TestMCPConsentReplace"
|
||||
key_links:
|
||||
- from: modules/pier/dispatch_mcpcall_test.go
|
||||
to: pact.MCPCallFrom
|
||||
via: a real tools/call on each guard
|
||||
pattern: MCPCallFrom
|
||||
- from: mcp_backfill_test.go
|
||||
to: migration 202610280001_backfill_golem15_oauthserver_mcp_consents
|
||||
via: two migrate runs
|
||||
pattern: backfill
|
||||
---
|
||||
|
||||
<objective>
|
||||
Last plan of the phase: the unit tests that prove SC-1, SC-2, SC-3 and SC-4 beyond the tracer smokes of plans 01–04, then a human gate before any tag, push, or changelog post (D-16).
|
||||
|
||||
Purpose: the project rule puts the broad test pass last. Tagging is not part of an autonomous task.
|
||||
Output: test files in the framework repo, the user-plugin worktree, and sm-oauthserver-plugin; pnpm test of vue-oauth-layer; docs checker. Tags only if the checkpoint option is tag-and-publish.
|
||||
|
||||
Do not edit app submodules, do not turn mcp.enabled on in an application, and do not hardcode the next framework version.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-CONTEXT.md
|
||||
@.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-VALIDATION.md
|
||||
@modules/pier/dispatch_test.go
|
||||
@modules/pier/tracer_smoke_test.go
|
||||
@modules/pact/mcp_call_test.go
|
||||
@../sm-oauthserver-plugin/mcp_consent_smoke_test.go
|
||||
@../sm-oauthserver-plugin/testmain_test.go
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Tracer: bare context has no MCP call, and both guards' tool calls do</name>
|
||||
<reversibility rating="reversible">Tests only. They lock the accessor contract already added in plan 01.</reversibility>
|
||||
<files>modules/pact/mcp_call_negative_test.go, modules/pier/dispatch_mcpcall_test.go, modules/pier/prm_scopes_test.go</files>
|
||||
<read_first>
|
||||
modules/pact/mcp_call_test.go (do not weaken TestMCPCallRoundTrip)
|
||||
modules/pier/mcp_seam_test.go
|
||||
modules/pier/dispatch_test.go and modules/pier/tracer_smoke_test.go for the mount helpers
|
||||
modules/pier/backend_guard.go BackendGuard constant
|
||||
modules/pier/prm.go
|
||||
</read_first>
|
||||
<action>
|
||||
Add tests. Do not change production behaviour unless a test shows the plan 01 setter missed a guard; the setter in dispatcher.run is shared, so a miss is a test-setup bug, not a second setter.
|
||||
|
||||
modules/pact/mcp_call_negative_test.go: TestMCPCallFromBareContext asserts MCPCallFrom(context.Background()) and MCPCallFrom on a request context that never called WithMCPCall return ok false (D-11). TestFrontendTokenScopeLiteralWithoutImplies builds FrontendTokenScope{Name, Label, Description} with no Implies field and asserts Implies is empty, so existing composite literals stay valid.
|
||||
|
||||
modules/pier/prm_scopes_test.go: TestPRMUsesAdvertisedScopes mounts pier with a verifier that implements MCPAdvertisedScopes and expects that slice on the protected-resource document, including a declared name. TestPRMFallsBackToPRMScopes mounts pier with a verifier that does not implement the interface and expects PRMScopes, which includes backend (D-04).
|
||||
|
||||
modules/pier/dispatch_mcpcall_test.go: TestDispatchMCPCallBothGuards, package pier_test, calls one frontend tool and one backend tool. Each handler reads pact.MCPCallFrom and records Guard and Tool. The frontend call's Guard is the frontend subject's guard. The backend call's Guard is the backend guard name. SessionID is not the word ephemeral. A personal-token versus OAuth difference is not asserted here; that is the user-plugin test in the next task. Do not print tokens. Commit in the framework repo, staging only these test files. Do not git add -A.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test -short -count=1 -run 'TestMCPCallFromBareContext|TestFrontendTokenScopeLiteralWithoutImplies|TestPRMUsesAdvertisedScopes|TestPRMFallsBackToPRMScopes|TestDispatchMCPCallBothGuards' ./modules/pact ./modules/pier</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL, or any of those five test names has no PASS line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- All five named tests PASS.
|
||||
- The backend tool's recorded guard is the backend guard, and the frontend tool's guard is the frontend subject.
|
||||
- No production file is in this commit.
|
||||
</acceptance_criteria>
|
||||
<done>SC-2's negative and both guards, and SC-1's PRM fallback, are proven in the framework repo.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Plugin, layer, and docs proofs for SC-1 through SC-4</name>
|
||||
<precondition>docker info exits 0; the user-plugin worktree exists at /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin on phase-32.1-mcp-implied-scopes; vue-oauth-layer/package.json exists.</precondition>
|
||||
<reversibility rating="reversible">Tests and a docs-checker run. No schema write except the oauthserver test database.</reversibility>
|
||||
<files>../sm-user-plugin/classes/mcp_guard_test.go, ../sm-oauthserver-plugin/mcp_consent_test.go, ../sm-oauthserver-plugin/authorizations_kind_test.go, ../sm-oauthserver-plugin/mcp_backfill_test.go, /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin, /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer</files>
|
||||
<read_first>
|
||||
The worktree classes/mcp_guard_test.go (keep TestMCPImpliesOAuth)
|
||||
../sm-oauthserver-plugin/mcp_consent_test.go and mcp_consent_smoke_test.go
|
||||
../sm-oauthserver-plugin/testmain_test.go (freshDB skips when testing.Short)
|
||||
../sm-oauthserver-plugin/authorizations_smoke_test.go
|
||||
../sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go if it exists
|
||||
../vue-oauth-layer/tests/connect.test.ts
|
||||
</read_first>
|
||||
<action>
|
||||
sm-user-plugin, on the v0.1.14 worktree, extend classes/mcp_guard_test.go. Do not edit an app submodule. Add TestMCPImpliesPersonalUnchanged: ClientID empty, scopes read, catalog Implies read on servers:read, MCPAllows rejects a requirement of servers:read, and MCPDispatch credential ID equals TokenID and does not HasScope servers:read. Add TestMCPImpliesWriteDoesNotGrantRead: OAuth ClientID set, scopes write, Implies read, MCPAllows rejects servers:read. Add TestMCPImpliesNotPersisted: after MCPDispatch the subject.Scopes slice is unchanged. Keep the v0.1.14 credential-id behaviour. Commit in the plugin repo only.
|
||||
|
||||
sm-oauthserver-plugin, Docker, not -short. Use the package Postgres helper. Add to mcp_consent_test.go: TestMCPConsentReplace allows read and write, then allows only read, and the consent row's scopes are only read (not a union). The test must fail if the code calls SaveConsent. TestMCPOfflineAccessUntick: pending offline_access true, POST scopes without that word, the issued MCP code's offline_access column is false; a POST that omits the scopes field leaves the flag as the pending row had it. TestMCPRevokeDeletesCode: issue an MCP code, DELETE /oauth/authorizations/{client_id}, exchanging that code fails, and a second MCP client of the same user still has its token. The revoked event's ClientID is the revoked client and TokenID is zero.
|
||||
|
||||
authorizations_kind_test.go TestAuthorizationsKind: an OIDC consent lists kind oidc and an MCP consent lists kind mcp, and the keys are client_id, name, logo_url, scopes, first_authorized_at, last_used_at, kind.
|
||||
|
||||
If the D-14 file exists, mcp_backfill_test.go TestMCPConsentBackfillIdempotent: a live MCP access token with no consent gets one row whose scopes union the token scopes and include offline_access when the column is true; a pair that already has a consent is left as it was; a second migrate inserts nothing. If the checkpoint in plan 03 held the migration, do not add this test and say that in the summary.
|
||||
|
||||
Do not log bearer tokens or authorization codes in test output. Assert status codes and ids.
|
||||
|
||||
vue-oauth-layer: pnpm install only if node_modules is missing, then pnpm test. Do not add a dependency.
|
||||
|
||||
Framework: go test ./cmd/summer -run TestDocsTree -count=1 and go run ./cmd/summer docs:build --check, then go vet ./... && go test -short ./... . Commit framework test fixes in the framework repo and plugin tests in each plugin repo. Do not git add -A. Do not tag or push in this task.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin && go test -short -count=1 -run 'TestMCPImplies' .</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL, or TestMCPImpliesPersonalUnchanged has no PASS line</fails_when>
|
||||
<automated>go -C /media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin test -count=1 -timeout 300s -run 'TestMCPConsentReplace|TestMCPOfflineAccessUntick|TestMCPRevokeDeletesCode|TestAuthorizationsKind|TestMCPConsentBackfillIdempotent' .</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]` for a test this command still names, or a line contains FAIL. If plan 03 held the backfill, `[no tests to run]` is a failure only when TestMCPConsentBackfillIdempotent is still named in the -run list; drop that name and record why.</fails_when>
|
||||
<automated>pnpm --prefix /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer test</automated>
|
||||
<fails_when>non-zero exit, or the tap output contains `not ok`, or a line `# tests 0`, or a line `# fail` whose count is not 0</fails_when>
|
||||
<automated>go test ./cmd/summer -run TestDocsTree -count=1 && go run ./cmd/summer docs:build --check && go vet ./... && go test -short ./...</automated>
|
||||
<fails_when>non-zero exit, or the output contains `[no tests to run]`, or a line contains FAIL</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- TestMCPImpliesPersonalUnchanged, TestMCPImpliesWriteDoesNotGrantRead, TestMCPConsentReplace, TestMCPOfflineAccessUntick, TestMCPRevokeDeletesCode and TestAuthorizationsKind each have a PASS line.
|
||||
- TestMCPConsentBackfillIdempotent has a PASS line when the migration file exists, and is absent when the migration was held.
|
||||
- TestDocsTree, docs:build --check, go vet ./... and go test -short ./... pass.
|
||||
- vue-oauth-layer pnpm test passes.
|
||||
</acceptance_criteria>
|
||||
<done>SC-1 through SC-4 have automated proofs beyond the earlier tracer smokes, and no tag has been created.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Whether to tag, push, and post the changelog</name>
|
||||
<reversibility rating="costly">A pushed framework tag is the release other apps will require. It is not created unless this checkpoint accepts it (D-16).</reversibility>
|
||||
<decision>Tag and push the framework 0.5 patch, the sm-user-plugin patch, the sm-oauthserver-plugin patch, and the first vue-oauth-layer tag, then post the framework changelog?</decision>
|
||||
<context>D-16 is patch releases only. The version numbers are computed from existing tags at execution time, never typed in advance. The changelog is the summercms.io post for the framework tag. Plugin repos are pushed before any app pointer bump, and this phase does not bump app pointers. There is no auto_select: an unattended run must stop here. On resume, before the next task changes any ref, write `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-release-decision.txt`. First line is `hold` or `tag-and-publish`. Then four sections in this order: a header line `framework yes` or `framework no`, one local tag name per line, then a line that is only a period, and the same for `user`, `oauth`, and `layer`. The header is yes only when that repo already has a remote named origin. Tag names come from a read-only for-each-ref of refs/tags. Do not create a tag, do not push, and do not publish the changelog in this task.</context>
|
||||
<options>
|
||||
<option id="tag-and-publish">
|
||||
<name>Tag, push, and post the changelog</name>
|
||||
<pros>The three gaps are on patch tags an application can require. The framework tag gets its changelog post the same day.</pros>
|
||||
<cons>The tags are public. A mistake is a further patch, not a rewritten tag.</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Do not tag or push</name>
|
||||
<pros>The code stays local until the user asks again.</pros>
|
||||
<cons>SC-4's patch tags stay unmet until a later go-ahead. No changelog post.</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Select tag-and-publish or hold</resume-signal>
|
||||
<read_first>
|
||||
.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-CONTEXT.md D-16
|
||||
CLAUDE.md section on changelog posts
|
||||
</read_first>
|
||||
<acceptance_criteria>
|
||||
- No git tag, git push, or changelog publish runs before this checkpoint returns.
|
||||
- hold leaves every repo untagged by this plan.
|
||||
- `32.1-05-release-decision.txt` exists before the next task changes any ref, and its first line is the accepted option id.
|
||||
</acceptance_criteria>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Tag and publish only if the checkpoint accepted it</name>
|
||||
<reversibility rating="costly">Pushed tags and a changelog post are the release. hold does none of this.</reversibility>
|
||||
<files>../sm-oauthserver-plugin/go.mod, .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-release-decision.txt, .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-changelog-notes.md</files>
|
||||
<read_first>
|
||||
../sm-oauthserver-plugin/go.mod require lines for summercms and sm-user-plugin
|
||||
CLAUDE.md changelog section (scripts/changelog-post.py, no token printing)
|
||||
../sm-summercmsio-app/DEPLOY.md section Posting to the changelog, if present
|
||||
</read_first>
|
||||
<action>
|
||||
Read `32.1-05-release-decision.txt`. Do not rewrite it after any ref changes. If you resumed and the file is not on disk yet, write it in the form the checkpoint describes, from the accepted option and a read-only for-each-ref of each repo, before changing any ref, then leave the file unchanged. If the first line is hold, do not create a tag, do not push, and do not run the changelog script. Say that in the summary and stop.
|
||||
|
||||
If the accepted option is tag-and-publish (D-16): compute versions from git tag --list. Framework: highest v0.5.* patch, plus one. Never a minor bump and never a version literal written into Go source. sm-user-plugin: highest v0.1.* patch, plus one, on branch phase-32.1-mcp-implied-scopes. sm-oauthserver-plugin: highest v0.1.* patch, plus one. vue-oauth-layer: v0.1.0, the version already in its package.json, only if that tag does not already exist.
|
||||
|
||||
Order: commit any uncommitted test files by explicit path in their own repos. Tag the framework. Tag the user plugin. In sm-oauthserver-plugin, set the require versions of summercms and sm-user-plugin to those new tags, commit that go.mod and go.sum change by path, then tag the plugin. Tag vue-oauth-layer. Do not delete or move the existing summercms replace line.
|
||||
|
||||
Push each repo that already has origin: the branch that was tagged, then the tag. Do not force-push. If vue-oauth-layer has no origin, leave the local tag and stop before inventing a remote; report that the empty remote git@git.golem15.com:golem15/vue-oauth-layer.git still has to be created by the user. Do not bump any app submodule pointer.
|
||||
|
||||
Changelog, only for the framework tag, from ../sm-summercmsio-app: scripts/changelog-post.py source for that tag, then publish `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-changelog-notes.md` with Highlights, Added, Changed, and Fixed. The notes say which framework, sm-user-plugin, sm-oauthserver-plugin and vue-oauth-layer versions close the three gaps, and they may name sm-servers-app as the audience (D-16). Do not put that application name into framework source, READMEs, or docs. No planning IDs, no quick codes, no H1. Do not print, copy, or mint the journal token. If ~/.config/summercms/journal-token is missing or the script refuses it, stop and ask. Do not git add -A. The verify reads the checkpoint record and fails when that record is absent or the local refs, the origin listing, or the changelog post disagree with it. Do not point the verify command at tag creation or at a push.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>python3 -c 'import pathlib, subprocess, sys, urllib.request, urllib.error
|
||||
root = pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/summercms.go")
|
||||
phase = root / ".planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con"
|
||||
rec = phase / "32.1-05-release-decision.txt"
|
||||
notes = phase / "32.1-05-changelog-notes.md"
|
||||
repos = {"framework": root, "user": pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin"), "oauth": pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/sm-oauthserver-plugin"), "layer": pathlib.Path("/media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer")}
|
||||
if not rec.is_file():
|
||||
sys.exit("checkpoint record absent")
|
||||
lines = [ln.strip() for ln in rec.read_text().splitlines()]
|
||||
if not lines or lines[0] not in ("hold", "tag-and-publish"):
|
||||
sys.exit("checkpoint record option is not hold or tag-and-publish")
|
||||
opt = lines[0]
|
||||
sections = {}
|
||||
i = 1
|
||||
for name in ("framework", "user", "oauth", "layer"):
|
||||
if i >= len(lines):
|
||||
sys.exit("checkpoint record missing " + name)
|
||||
head = lines[i].split()
|
||||
i += 1
|
||||
if len(head) != 2 or head[0] != name or head[1] not in ("yes", "no"):
|
||||
sys.exit("checkpoint record bad header " + name)
|
||||
tags = []
|
||||
while i < len(lines) and lines[i] != ".":
|
||||
if lines[i]:
|
||||
tags.append(lines[i])
|
||||
i += 1
|
||||
if i >= len(lines) or lines[i] != ".":
|
||||
sys.exit("checkpoint record missing end " + name)
|
||||
i += 1
|
||||
sections[name] = tags
|
||||
def git_out(path, args):
|
||||
if not path.is_dir():
|
||||
sys.exit("repo missing " + str(path))
|
||||
r = subprocess.run(["git", "-C", str(path), *args], capture_output=True, text=True)
|
||||
if r.returncode != 0:
|
||||
sys.exit("git failed in " + path.name)
|
||||
return r.stdout
|
||||
def current_tags(path):
|
||||
out = git_out(path, ["for-each-ref", "--format=%(refname:short)", "refs/tags"])
|
||||
return [ln.strip() for ln in out.splitlines() if ln.strip()]
|
||||
def has_origin(path):
|
||||
r = subprocess.run(["git", "-C", str(path), "remote", "get-url", "origin"], capture_output=True, text=True)
|
||||
return r.returncode == 0
|
||||
def remote_tags(path):
|
||||
out = git_out(path, ["ls-remote", "--tags", "origin"])
|
||||
names = []
|
||||
for ln in out.splitlines():
|
||||
parts = ln.split()
|
||||
if len(parts) < 2:
|
||||
continue
|
||||
ref = parts[-1]
|
||||
if ref.endswith("^{}"):
|
||||
continue
|
||||
prefix = "refs/tags/"
|
||||
if ref.startswith(prefix):
|
||||
names.append(ref[len(prefix):])
|
||||
return names
|
||||
def bump(tags, prefix):
|
||||
best = None
|
||||
for t in tags:
|
||||
if t.startswith(prefix) and t[len(prefix):].isdigit():
|
||||
n = int(t[len(prefix):])
|
||||
best = n if best is None else max(best, n)
|
||||
if best is None:
|
||||
sys.exit("no baseline tag for " + prefix)
|
||||
return prefix + str(best + 1)
|
||||
if opt == "hold":
|
||||
for name in ("framework", "user", "oauth", "layer"):
|
||||
if set(current_tags(repos[name])) != set(sections[name]):
|
||||
sys.exit("hold but local tags differ " + name)
|
||||
sys.exit(0)
|
||||
expected = {"framework": {bump(sections["framework"], "v0.5.")}, "user": {bump(sections["user"], "v0.1.")}, "oauth": {bump(sections["oauth"], "v0.1.")}, "layer": set() if "v0.1.0" in sections["layer"] else {"v0.1.0"}}
|
||||
fw_tag = None
|
||||
for name in ("framework", "user", "oauth", "layer"):
|
||||
cur = set(current_tags(repos[name]))
|
||||
base = set(sections[name])
|
||||
added = cur - base
|
||||
removed = base - cur
|
||||
if removed:
|
||||
sys.exit("tags removed in " + name)
|
||||
if added != expected[name]:
|
||||
sys.exit("tags disagree in " + name)
|
||||
if has_origin(repos[name]) and not expected[name] <= set(remote_tags(repos[name])):
|
||||
sys.exit("push missing in " + name)
|
||||
if name == "framework":
|
||||
fw_tag = next(iter(expected[name]))
|
||||
token = pathlib.Path.home() / ".config" / "summercms" / "journal-token"
|
||||
if not token.is_file():
|
||||
sys.exit(0)
|
||||
if fw_tag is None or not str(fw_tag).startswith("v"):
|
||||
sys.exit("framework tag missing")
|
||||
ver = fw_tag[1:]
|
||||
if not notes.is_file():
|
||||
sys.exit("changelog notes missing")
|
||||
content = notes.read_text().strip()
|
||||
if (not content) or content.startswith("# "):
|
||||
sys.exit("changelog notes empty or start with an H1")
|
||||
for h in ("## Highlights", "## Added", "## Changed", "## Fixed"):
|
||||
if h not in content:
|
||||
sys.exit("changelog notes missing heading")
|
||||
if ver not in content:
|
||||
sys.exit("changelog notes missing version")
|
||||
url = "https://summercms.io/changelog/summercms-" + ver.replace(".", "-")
|
||||
req = urllib.request.Request(url, headers={"User-Agent": "summercms-plan-verify"})
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=30) as r:
|
||||
body = r.read().decode("utf-8", "replace")
|
||||
except urllib.error.HTTPError as e:
|
||||
body = e.read().decode("utf-8", "replace")
|
||||
except Exception:
|
||||
sys.exit("changelog fetch failed")
|
||||
if ("SummerCMS " + ver) not in body:
|
||||
sys.exit("changelog post missing " + ver)'</automated>
|
||||
<fails_when>non-zero exit. That includes checkpoint record absent, checkpoint record option is not hold or tag-and-publish, checkpoint record missing, checkpoint record bad header, repo missing, git failed, hold but local tags differ, no baseline tag, tags removed, tags disagree, push missing, framework tag missing, changelog notes missing, changelog notes empty or start with an H1, changelog notes missing heading, changelog notes missing version, changelog fetch failed, or changelog post missing.</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- hold: git tag --list in each repo shows no tag created by this task, and the changelog script was not run.
|
||||
- tag-and-publish: the framework tag is the next v0.5 patch, the two plugins are the next v0.1 patches, vue-oauth-layer is v0.1.0, and each repo that had origin was pushed. The framework changelog post was attempted, or the task stopped because the token file was missing.
|
||||
- No app submodule pointer moved.
|
||||
</acceptance_criteria>
|
||||
<done>D-16 either shipped as patch tags plus the framework changelog, or stayed local because the checkpoint said hold.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| Test output and changelog notes | Tokens and authorization codes must not be copied into logs or the public post. |
|
||||
| git push of a release tag | The tag is what other repositories will require. |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-32.1-13 | Information disclosure | tests and changelog-post.py | medium | mitigate | Assert status codes and ids. Do not print bearer tokens, authorization codes, or the journal token. If the token file is missing, stop. |
|
||||
| T-32.1-14 | Spoofing | release tags | low | accept | Tagging does not change PKCE, redirect matching, or the read/write ceiling. The checkpoint is the control on publishing, not a new auth path. |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
The named tests PASS, docs:build --check passes, and no tag exists unless tag-and-publish was accepted.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- SC-1 through SC-4 are covered by the tests named in this plan.
|
||||
- Tags, pushes, and the changelog post are behind the checkpoint.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-SUMMARY.md` when done.
|
||||
</output>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin
|
||||
- /media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer
|
||||
|
||||
Tests added:
|
||||
- TestMCPCallFromBareContext
|
||||
- TestFrontendTokenScopeLiteralWithoutImplies
|
||||
- TestPRMUsesAdvertisedScopes
|
||||
- TestPRMFallsBackToPRMScopes
|
||||
- TestDispatchMCPCallBothGuards
|
||||
- TestMCPImpliesPersonalUnchanged
|
||||
- TestMCPImpliesWriteDoesNotGrantRead
|
||||
- TestMCPImpliesNotPersisted
|
||||
- TestMCPConsentReplace
|
||||
- TestMCPOfflineAccessUntick
|
||||
- TestMCPRevokeDeletesCode
|
||||
- TestAuthorizationsKind
|
||||
- TestMCPConsentBackfillIdempotent when the D-14 migration file exists
|
||||
|
||||
Release, only after tag-and-publish: next framework v0.5 patch tag, next sm-user-plugin v0.1 patch tag, next sm-oauthserver-plugin v0.1 patch tag, vue-oauth-layer v0.1.0, and the framework changelog post.
|
||||
@@ -0,0 +1,206 @@
|
||||
---
|
||||
phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||
plan: 05
|
||||
subsystem: auth
|
||||
tags: [mcp, oauth, release, changelog, scopes]
|
||||
|
||||
requires:
|
||||
- phase: 32.1-01
|
||||
provides: MCP scope list and MCPCall on the tool-call context
|
||||
- phase: 32.1-02
|
||||
provides: OAuth implied scopes in sm-user-plugin
|
||||
- phase: 32.1-03
|
||||
provides: MCP consent replace, kind, and backfill
|
||||
- phase: 32.1-04
|
||||
provides: vue-oauth-layer /connect
|
||||
provides:
|
||||
- "Unit tests for a bare MCP call, both guards, PRM scopes, implied scopes, consent replace, kind, and backfill"
|
||||
- "SummerCMS v0.5.2, sm-user-plugin v0.1.16, sm-oauthserver-plugin v0.1.4, and local vue-oauth-layer v0.1.0"
|
||||
- "Changelog post https://summercms.io/changelog/summercms-0-5-2"
|
||||
affects: [33]
|
||||
|
||||
actuals:
|
||||
tokens: 6474
|
||||
tasks: 4
|
||||
commits: 1
|
||||
plan_head_before: 06a144e19f1bca9b918af7adfc44e7b7a1e3f011
|
||||
plan_head_after: 9094bf9ad99c92b4343d8d3f1062ef4863f58e00
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Patch tags are computed from git tag --list at release time, recorded in 32.1-05-release-decision.txt before any ref changes"
|
||||
- "sm-oauthserver-plugin bumps require versions after those tags are pushed and keeps the summercms replace"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-release-decision.txt
|
||||
- .planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-changelog-notes.md
|
||||
- modules/pact/mcp_call_negative_test.go
|
||||
- modules/pier/dispatch_mcpcall_test.go
|
||||
- modules/pier/prm_scopes_test.go
|
||||
- ../sm-user-plugin/mcp_implies_test.go
|
||||
- ../sm-oauthserver-plugin/mcp_consent_test.go
|
||||
- ../sm-oauthserver-plugin/authorizations_kind_test.go
|
||||
- ../sm-oauthserver-plugin/mcp_backfill_test.go
|
||||
modified:
|
||||
- ../sm-oauthserver-plugin/go.mod
|
||||
- ../sm-oauthserver-plugin/go.sum
|
||||
- .planning/ROADMAP.md
|
||||
|
||||
key-decisions:
|
||||
- "tag-and-publish. Framework v0.5.2 on master, sm-user-plugin v0.1.16 on phase-32.1-mcp-implied-scopes, sm-oauthserver-plugin v0.1.4 on master after the require bump, vue-oauth-layer v0.1.0 local only."
|
||||
- "sm-user-plugin v0.1.16 stays on phase-32.1-mcp-implied-scopes and is not retargeted onto v0.1.15. That tag is not an ancestor."
|
||||
- "vue-oauth-layer has no origin. The tag was not pushed and no remote was created."
|
||||
|
||||
patterns-established:
|
||||
- "Release decision file is written from for-each-ref before the first tag or push and is not rewritten."
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "A bare context has no MCP call, both guards record MCPCall, and PRM uses advertised scopes or falls back."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: modules/pact/mcp_call_negative_test.go#TestMCPCallFromBareContext
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: modules/pier/dispatch_mcpcall_test.go#TestDispatchMCPCallBothGuards
|
||||
status: pass
|
||||
- kind: unit
|
||||
ref: modules/pier/prm_scopes_test.go#TestPRMUsesAdvertisedScopes
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "OAuth implied scopes do not expand a personal token, write does not grant read, and the subject slice is unchanged."
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: sm-user-plugin/mcp_implies_test.go#TestMCPImpliesPersonalUnchanged
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "MCP consent replace, offline_access, revoke, authorization kind, and idempotent backfill."
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: sm-oauthserver-plugin/mcp_consent_test.go#TestMCPConsentReplace
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: sm-oauthserver-plugin/mcp_backfill_test.go#TestMCPConsentBackfillIdempotent
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "Patch tags pushed where origin existed, and the framework changelog post is live."
|
||||
verification:
|
||||
- kind: other
|
||||
ref: python3 plan task-4 verify (exit 0) against 32.1-05-release-decision.txt and https://summercms.io/changelog/summercms-0-5-2
|
||||
status: pass
|
||||
human_judgment: false
|
||||
|
||||
duration: 34min
|
||||
completed: 2026-10-28
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 32.1 Plan 05: Unit tests and patch release Summary
|
||||
|
||||
**SummerCMS v0.5.2, sm-user-plugin v0.1.16, sm-oauthserver-plugin v0.1.4, and local vue-oauth-layer v0.1.0 ship the MCP OAuth scope, caller, and consent gaps, with the framework changelog posted**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 34 min
|
||||
- **Started:** 2026-10-28T15:09:30Z
|
||||
- **Completed:** 2026-10-28T15:42:50Z
|
||||
- **Tasks:** 4
|
||||
- **Files modified:** 12
|
||||
|
||||
`actuals.tokens` is chars/4 of `git show` for `9094bf9`, `756797c`, `4f8618e`, and `a7743e7`, plus the decision file and changelog notes (25896 / 4). This summary is not in that count. `commits: 1` is `git rev-list --count 06a144e19f1bca9b918af7adfc44e7b7a1e3f011..9094bf9` at summary time. The metadata commit is after that range.
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Framework tests prove a bare context has no MCP call, both guards set one, and PRM uses an advertised list or falls back.
|
||||
- sm-user-plugin tests keep implied scopes off the stored subject. sm-oauthserver-plugin tests prove consent replace, offline access, revoke, authorization kind, and an idempotent backfill.
|
||||
- Tags: SummerCMS `v0.5.2` on `9094bf9` (pushed `master`, then the tag), sm-user-plugin `v0.1.16` on `756797c` (pushed `phase-32.1-mcp-implied-scopes`, then the tag), sm-oauthserver-plugin `v0.1.4` on `a7743e7` (pushed `master`, then the tag), vue-oauth-layer `v0.1.0` on `7f805b3` (local only).
|
||||
- Changelog post id 46: https://summercms.io/changelog/summercms-0-5-2. The plan python verify exited 0.
|
||||
- No app submodule pointer moved. `go.work` in sm-oauthserver-plugin stayed unstaged.
|
||||
|
||||
## Task Commits
|
||||
|
||||
The test commits were already on the branches before this continuation. They were not redone.
|
||||
|
||||
1. **Task 1: Tracer: bare context has no MCP call, and both guards' tool calls do** - `9094bf9` (test, summercms.go)
|
||||
2. **Task 2: Plugin, layer, and docs proofs** - `756797c` (test, sm-user-plugin), `4f8618e` (test, sm-oauthserver-plugin). vue-oauth-layer had no new commit in this plan; its tests were already on `7f805b3`.
|
||||
3. **Task 3: Release checkpoint** - no commit. The accepted option is `tag-and-publish`, recorded in `32.1-05-release-decision.txt` before any tag or push. That file was not rewritten.
|
||||
4. **Task 4: Tag and publish** - `a7743e7` (chore, sm-oauthserver-plugin) sets `summercms v0.5.2` and `sm-user-plugin v0.1.16` and keeps the summercms replace. Tags and pushes are listed above. No framework commit in this task before the metadata commit.
|
||||
|
||||
**Plan metadata:** this summary, the decision file, the changelog notes, and the roadmap check, committed in summercms.go after this file was written.
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `modules/pact/mcp_call_negative_test.go` - bare context and a FrontendTokenScope literal without Implies
|
||||
- `modules/pier/dispatch_mcpcall_test.go` - frontend and backend tool calls record MCPCall
|
||||
- `modules/pier/prm_scopes_test.go` - advertised scopes and the PRMScopes fallback
|
||||
- `../sm-user-plugin/mcp_implies_test.go` - personal token, write-does-not-grant-read, subject slice unchanged
|
||||
- `../sm-oauthserver-plugin/mcp_consent_test.go` - replace, offline access, revoke
|
||||
- `../sm-oauthserver-plugin/authorizations_kind_test.go` - kind mcp or oidc
|
||||
- `../sm-oauthserver-plugin/mcp_backfill_test.go` - idempotent backfill
|
||||
- `../sm-oauthserver-plugin/go.mod` - require SummerCMS v0.5.2 and sm-user-plugin v0.1.16
|
||||
- `../sm-oauthserver-plugin/go.sum` - sum for sm-user-plugin v0.1.16
|
||||
- `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-release-decision.txt` - checkpoint record and the tag lists from before the release
|
||||
- `.planning/phases/32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con/32.1-05-changelog-notes.md` - notes published for v0.5.2
|
||||
- `.planning/ROADMAP.md` - 32.1-05 checked, 5/5 plans executed
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- The checkpoint option `tag-and-publish` was applied. Versions came from the tag lists in the decision file: next v0.5 patch is v0.5.2, next user v0.1 patch is v0.1.16, next oauth v0.1 patch is v0.1.4, and vue-oauth-layer is v0.1.0 because that tag did not exist.
|
||||
- sm-user-plugin was tagged on `phase-32.1-mcp-implied-scopes` at `756797c`. `v0.1.15` is not an ancestor. The tag was not moved onto `v0.1.15`. The tag message and the changelog say the missing-scope fields from v0.1.15 are absent. The plugin `go.mod` still requires SummerCMS v0.5.0; the new seams are in v0.5.2, which sm-oauthserver-plugin v0.1.4 requires.
|
||||
- vue-oauth-layer has no `origin`. `v0.1.0` is local. `git@git.golem15.com:golem15/vue-oauth-layer.git` was not created.
|
||||
- STATE.md and state.json were not edited and are not in the metadata commit. Current Position stays phase 33.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
None during the release continuation. The test tasks were already committed.
|
||||
|
||||
The user-plugin test file is `mcp_implies_test.go` at the plugin root, not `classes/mcp_guard_test.go`. That path was chosen by the earlier test commit and was left as committed.
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 0 auto-fixed during the release continuation
|
||||
**Impact on plan:** The release followed the accepted checkpoint. The user-plugin tag is intentionally not based on v0.1.15.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- Pushing summercms.go `master` published 44 commits since v0.5.1, including the phase 32 review fixes and planning commits that were already on local master. The push was a fast-forward. No force-push.
|
||||
- Phase 33 plan 01 reserved the name v0.5.2 for a later tag that would also carry phase 33 seams, and plan 33-14 was going to create that tag. This release took v0.5.2 because it was the next v0.5 patch. Phase 33 must not reuse v0.5.2. The next framework patch is v0.5.3 unless a newer v0.5 tag appears first.
|
||||
- vue-oauth-layer `README.md` inside `v0.1.0` still says the tag does not exist yet. The release order tagged the existing commit and did not add a README commit. The tag was not moved. "No tag has been pushed" is still true, because there is no remote.
|
||||
- `state.advance-plan` was not run. It would move Current Position, which is phase 33. Roadmap 32.1-05 was checked by editing ROADMAP.md directly.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
Create `git@git.golem15.com:golem15/vue-oauth-layer.git`, then push `main` and the annotated tag `v0.1.0` from `/media/nvme/dev/golem15/summercms.io/summercms/vue-oauth-layer`. Do not force-push. Until that remote exists, apps cannot pin the layer. The tagged README still describes the pre-tag install shape.
|
||||
|
||||
No journal token was printed, copied, or minted.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- The three MCP OAuth gaps are on the tags above. No application go.mod or submodule pointer was bumped.
|
||||
- Phase 33's release ledger must treat v0.5.2 as already published. Its framework seams belong on a later patch.
|
||||
- Current Position was left on phase 33.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
- `vue-oauth-layer/README.md` line 9, inside tag `v0.1.0`: "That tag does not exist yet." The local tag exists; the remote does not. Not edited, because editing would require moving the tag.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: `32.1-05-release-decision.txt` (sha256 `3e33d20e4c626c7c43d5da66930ac4b51a0cc02d2995c1fc7e6d5e59f638fa8f`, first line `tag-and-publish`, not rewritten after the tags)
|
||||
- FOUND: `32.1-05-changelog-notes.md`
|
||||
- FOUND: summercms.go `9094bf9`, sm-user-plugin `756797c`, sm-oauthserver-plugin `4f8618e` and `a7743e7`
|
||||
- FOUND remote tags: `v0.5.2`, `v0.1.16`, `v0.1.4`. Local only: vue-oauth-layer `v0.1.0`
|
||||
- Plan task-4 python verify exit 0. Changelog URL https://summercms.io/changelog/summercms-0-5-2 contains the posted title.
|
||||
|
||||
---
|
||||
*Phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con*
|
||||
*Completed: 2026-10-28*
|
||||
@@ -0,0 +1,29 @@
|
||||
## Highlights
|
||||
|
||||
SummerCMS 0.5.2 lets an MCP OAuth agent use the scopes a plugin declares, and lets a tool call see which subject invoked it. sm-user-plugin v0.1.16 applies read and write as implied scopes for OAuth subjects only. sm-oauthserver-plugin v0.1.4 stores one consent per MCP client, replaces it on a later allow, and backfills live grants. vue-oauth-layer v0.1.0 is the `/connect` page for that consent. Together these versions close the three gaps sm-servers-app needs before MCP OAuth can be switched on: the same tool list as a personal token, attribution of the caller, and per-client revoke.
|
||||
|
||||
## Added
|
||||
|
||||
- One MCP scope list. Plugins publish member-token scopes, the OAuth server advertises that list (optionally filtered), and the protected-resource metadata uses the same names. An empty list still means the five fixed scopes, including backend. OIDC discovery is unchanged.
|
||||
- An MCP call on the request context: guard, user, client, token, scopes, session and tool. A request that is not an MCP tool call has none.
|
||||
- A pending consent view reports whether offline access was requested.
|
||||
- sm-user-plugin v0.1.16 expands a declared scope when an OAuth grant holds the read or write that the scope marks as implied. A personal token is not expanded, write does not imply read, and the stored subject scopes stay as issued. The dispatch credential still carries the personal token id.
|
||||
- sm-oauthserver-plugin v0.1.4 records MCP consent per client, shows scope details on the consent JSON, marks authorizations as mcp or oidc, and backfills a consent for each live grant. A second migrate inserts nothing.
|
||||
- vue-oauth-layer v0.1.0 renders `/connect` from that JSON: checkboxes, read locked, the administrator named as text, and a refetch when the backend link changed. The layer's git remote is not published yet, so an app cannot pin the tag until that repository exists.
|
||||
|
||||
## Changed
|
||||
|
||||
- A later MCP allow replaces the stored consent scopes. It does not merge them with the previous grant.
|
||||
- Unticking offline access clears that flag on the issued code. Omitting the scopes field leaves the pending flag as it was.
|
||||
- Revoking an authorized MCP client deletes its unused code and leaves the user's other clients in place.
|
||||
- sm-oauthserver-plugin v0.1.4 requires SummerCMS v0.5.2 and sm-user-plugin v0.1.16.
|
||||
- sm-user-plugin v0.1.16 is not a descendant of v0.1.15. It does not include the missing-scope and missing-permission fields from that tag. Build it with SummerCMS v0.5.2; its go.mod still states v0.5.0 and selects the newer framework only when the application does.
|
||||
|
||||
## Fixed
|
||||
|
||||
- A hidden relation field or partial field no longer keeps its routes after it is removed from the form.
|
||||
- Record events fire when a hasMany child is linked, unlinked, or attached from a deferred commit, and the event locale is the request locale's primary tag.
|
||||
- A widget action dispatched while the widget connects is delivered.
|
||||
- Uploading through a form extension follows that extension's visibility.
|
||||
- A required field that belongs to a form extension is checked on the extension's own value, so saving the host form no longer fails on a rule the owner model cannot satisfy.
|
||||
- The additive API check compares the new release with the previous one after the tree is tagged.
|
||||
@@ -0,0 +1,70 @@
|
||||
tag-and-publish
|
||||
framework yes
|
||||
v0.1.1
|
||||
v0.1.10
|
||||
v0.1.11
|
||||
v0.1.12
|
||||
v0.1.13
|
||||
v0.1.14
|
||||
v0.1.15
|
||||
v0.1.16
|
||||
v0.1.17
|
||||
v0.1.18
|
||||
v0.1.19
|
||||
v0.1.2
|
||||
v0.1.20
|
||||
v0.1.21
|
||||
v0.1.22
|
||||
v0.1.23
|
||||
v0.1.24
|
||||
v0.1.25
|
||||
v0.1.26
|
||||
v0.1.27
|
||||
v0.1.3
|
||||
v0.1.4
|
||||
v0.1.5
|
||||
v0.1.6
|
||||
v0.1.7
|
||||
v0.1.8
|
||||
v0.1.9
|
||||
v0.2.0
|
||||
v0.2.1
|
||||
v0.2.2
|
||||
v0.2.3
|
||||
v0.2.4
|
||||
v0.3.0
|
||||
v0.3.1
|
||||
v0.4.0
|
||||
v0.4.1
|
||||
v0.4.2
|
||||
v0.4.3
|
||||
v0.4.4
|
||||
v0.5.0
|
||||
v0.5.1
|
||||
.
|
||||
user yes
|
||||
v0.1.0
|
||||
v0.1.1
|
||||
v0.1.10
|
||||
v0.1.11
|
||||
v0.1.12
|
||||
v0.1.13
|
||||
v0.1.14
|
||||
v0.1.15
|
||||
v0.1.2
|
||||
v0.1.3
|
||||
v0.1.4
|
||||
v0.1.5
|
||||
v0.1.6
|
||||
v0.1.7
|
||||
v0.1.8
|
||||
v0.1.9
|
||||
.
|
||||
oauth yes
|
||||
v0.1.0
|
||||
v0.1.1
|
||||
v0.1.2
|
||||
v0.1.3
|
||||
.
|
||||
layer no
|
||||
.
|
||||
@@ -0,0 +1,134 @@
|
||||
# Phase 32.1: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent - Context
|
||||
|
||||
**Gathered:** 2026-10-28
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
An agent connected to `/mcp` over OAuth gets the same tools, attribution and revocation as one using a member personal API token, so that a consuming application can switch OAuth sign-in on in production. Three additive gaps are closed:
|
||||
|
||||
1. **Declared scopes over MCP OAuth.** Scopes a plugin declares through `pact.HasFrontendTokenScopes` can be requested, consented to and granted on the MCP OAuth server, and appear in pier's protected-resource metadata. Today the list is fixed to `read`, `write`, `ai`, `offline_access` (+ `backend` on the MCP server).
|
||||
2. **MCP call context.** A route run by an MCP tool call can read who called it (guard, user, client ID, token id, scopes) and the MCP session through a `pact` accessor.
|
||||
3. **MCP consent row.** `sm-oauthserver-plugin` records a consent for MCP grants, so the existing per-client revoke ends one agent's grant and its MCP sessions.
|
||||
|
||||
Everything ships as patch releases: framework 0.5.x, `sm-oauthserver-plugin`, and `sm-user-plugin` (it publishes the scope catalog and applies the implied scopes). Module READMEs and `docs/` pages describe the changes. The phase also starts a public Nuxt layer, `vue-oauth-layer`, with the `/connect` consent page (D-17).
|
||||
|
||||
The three gaps come from sm-servers-app phase 05 (`/media/nvme/dev/pxpx/sm-servers-app/.planning/phases/05-agent-access-over-mcp/05-CONTEXT.md`, D-36 to D-38), escalated as upstream Requests 3, 4 and 5 on 2026-10-28. That app keeps `golem15.oauthserver.mcp.enabled` off in production until they ship. Its expected-gap tests (`TestMCPOAuthToolsMatchPersonal`, `TestMCPOAuthWriteAttribution`) must turn into passing assertions against the released versions without app-side scope middleware.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Declared scopes and the read/write ceiling
|
||||
- **D-01:** **The 19.7 D-20 ceiling stays.** OAuth `read`/`write` remain the ceiling: a non-read-only tool still needs `write`, and a route's `user.scope:<declared>` still needs the declared scope in the grant. A write tool behind `user.scope:bm:write` needs both `write` and `bm:write`, as a personal token with read/write plus declared scopes does today. No pier ceiling change.
|
||||
- **D-01a:** **Declared scopes can be implied by stock `read`/`write` (Request 3).** `pact.FrontendTokenScope` gets an additive field (proposed `Implies`, value `"read"` or `"write"`, empty = not implied). An OAuth MCP grant holding the stock scope also satisfies every declared scope that names it as implied. For example, `servers:read` with `Implies: "read"` is satisfied by a `read` grant, so an agent granted `read write` lists the same servers tools as a personal token with `servers:read servers:write` (sm-servers-app's "OAuth list equals personal list"). The expansion applies only to OAuth MCP subjects, in sm-user-plugin's MCP guard (`MCPAllows`/`MCPDispatch`) or where the subject's scopes are built. A personal token's scopes keep their meaning, and the user still never gets a scope the plugin did not mark as implied. Declared scopes are still advertised (D-03) for clients that want a narrower grant. — **Reversibility:** costly — once apps rely on read/write implying their scopes, removing it shrinks live agents' tool lists.
|
||||
- **D-02:** **Declared scopes are offered on the MCP OAuth server only**, like `backend` (19.7 D-21). The OIDC server keeps its PHP-parity scope list.
|
||||
- **D-03:** **Advertised scopes = fixed scopes + declared scopes, filtered by an optional opt-in list.** When the config list is set, only the declared scopes it names are advertised and accepted. When it is unset, every declared scope is. The fixed scopes (`read`, `write`, `ai`, `offline_access`, `backend`) are always present. The same set drives the wristband MCP server's metadata `scopes_supported`, its authorize allow-list (`allowedAuthorizeScopes`) and pier's PRM `scopes_supported`. This rule must be documented clearly in the oauthserver README, the pier README and `docs/services/oauth-server.md` / `docs/services/mcp.md`. A name in the list that no plugin declares should be a clear boot error or warning; the planner decides which. — **Reversibility:** costly — scope names published in metadata and stored in grants.
|
||||
- **D-04:** **The config key lives in sm-oauthserver-plugin** (proposed `golem15.oauthserver.mcp_scopes`), next to where `NewServers` builds `mcpOpts.ScopesSupported`. **pier reads the list from the published verifier** (`pact.MCPTokenVerifier`, extended additively) instead of its own `PRMScopes` constant, so the PRM and the authorization server cannot drift. `pier.PRMScopes` stays as the fallback when no verifier publishes a list.
|
||||
- **D-05:** **Plumbing: a published pact catalog.** The plugin that owns member tokens (sm-user-plugin, which already compiles and validates `FrontendTokenScopes()` at boot) publishes the compiled list on the app (`app.Lookup[...]`) through a new additive pact interface. sm-oauthserver-plugin and pier read it at boot. Labels and descriptions travel with the names so the consent page can show them.
|
||||
|
||||
### Consent page
|
||||
- **D-06:** **Per-scope checkboxes.** This changes the consent behaviour from 19.4's allow/deny-the-whole-request. Every requested scope starts ticked. `read`, when requested, is locked (cannot be unticked). `offline_access`, `backend` and declared scopes can be unticked. A submit that leaves no data-bearing scope keeps the existing 422 `no_grantable_scopes`. `MCPConsentDecide` already intersects submitted ∩ requested (`grantedScopes`), so the server side mostly exists.
|
||||
- **D-07:** **Both surfaces.** The MCP consent JSON (show answer of `controllers/mcp_consent_api.go`) carries a label and description per requested scope: the FrontendTokenScope label/description resolved through phrasebook for declared scopes, existing text for fixed scopes. It also says whether each scope is locked, so redirect-mode app pages can render checkboxes or keep all-or-nothing (as the consuming app chose in its D-07). The built-in consent page renders the checkboxes. *Research must confirm which built-in page the MCP flow uses today* (`views/consent.html.tmpl` vs redirect-only to an app `/connect` page). If the MCP flow has no built-in page, the checkboxes go wherever the plugin ships its MCP consent rendering, and the planner raises it.
|
||||
- **D-08:** **Re-consent on scope growth.** When a client that already holds a consent requests any scope the recorded consent does not cover, the user goes through the consent page again. After the decision, the stored consent's scopes become the newly granted set.
|
||||
|
||||
### MCP call context accessor
|
||||
- **D-09:** **The accessor lives in `pact`:** `pact.MCPCallFrom(ctx) (MCPCall, bool)` with a matching setter that pier calls next to `bouncer.WithDispatch` in `dispatch.go`. Plugins already import pact, so they need no pier or bouncer import.
|
||||
- **D-10:** **New `pact.MCPCall` wrapper:** `MCPCall{Subject MCPSubject, SessionID string, Tool string}`. `MCPSubject` (the guard-facing type) stays unchanged. `SessionID` is the MCP session id and is empty in pier's stateless mode. `Tool` is the tool name. Exact field names are the planner's call within this shape. — **Reversibility:** costly — exported pact API that consuming apps will read.
|
||||
- **D-11:** **Every MCP tool call carries it:** OAuth and personal-token, frontend and backend guards. The subject is the one pier resolved for that tool's guard (`id.subjectFor(t.guardName)`). Plain HTTP requests have none (`ok == false`). A personal-token call's credential keeps carrying the token id as today (sm-user-plugin v0.1.14); the accessor is additive to it, not a replacement.
|
||||
|
||||
### MCP consent row and revoke
|
||||
- **D-12:** **The same `golem15_oauthserver_consents` table.** When an MCP code is issued (`MCPConsentDecide` → `IssueCode`, and any direct grant path through the MCP store), upsert the (user_id, client_id) row with the granted scopes. MCP clients are DCR clients distinct from OIDC clients, so the unique (user_id, client_id) constraint does not collide. The existing `revoke` (deletes the consent, plus codes, access and refresh tokens of the pair, then emits `MCPSubjectRevoked{ClientID}`, which pier uses to evict sessions) then works unchanged for MCP clients.
|
||||
- **D-13:** **MCP clients appear in `GET /oauth/authorizations`** with an additive kind marker (e.g. `"kind":"mcp"`; OIDC entries get `"oidc"` or omit it, per the planner). Existing fields and order are unchanged.
|
||||
- **D-14:** **A data migration backfills consents** for grants that predate this release: one row per (user, client) with live MCP access or refresh tokens, scopes = union of the tokens' scopes, `created_at` = earliest token. It must be idempotent and skip pairs that already have a consent. — **Reversibility:** one-way — writes rows into a shared table on every consuming install.
|
||||
- **D-15:** **One revoke ends everything for that client:** frontend and backend (`backend_user_id`) access and every MCP session of the client. No separate backend revoke.
|
||||
|
||||
### Consent page as a Nuxt layer
|
||||
- **D-17:** **An initial `vue-oauth-layer` ships in this phase.** It is a new public Nuxt layer repo next to `vue-journal-layer`, `vue-faq-layer`, `vue-menu-layer` and `vue-paymentgateway-layer`, with the same structure and the same pnpm-git-dependency-pinned-by-tag consumption. It provides the `/connect` page of redirect consent mode, rendered from the MCP consent JSON (D-07): client name and logo, per-scope checkboxes with labels and descriptions, `read` locked, the "also act as admin <name>" line for `backend`, allow/deny, and the `backend_link_changed` 409 re-show. Apps adopt it later as their own work, so 32.1 does not migrate any app's existing `/connect` page. The layer gets a tag. It is one plan in the phase.
|
||||
|
||||
### Release
|
||||
- **D-16:** Patch releases only: framework 0.5.x (never hardcode the version), `sm-user-plugin` (catalog publication, implied scopes), `sm-oauthserver-plugin` (scopes, consent JSON/page, consent row, backfill, listing marker), plus the first tag of `vue-oauth-layer`. Commit and push each plugin before bumping pointers in apps. Each pushed framework tag gets a changelog post. The release notes tell sm-servers-app which versions close Requests 3–5.
|
||||
|
||||
### Claude's Discretion
|
||||
- The pact interface name and shape for the published scope catalog (D-05), within "names + label + description, additive".
|
||||
- Whether an opt-in name nobody declares fails boot or warns (D-03).
|
||||
- Field names of `MCPCall` and the setter name (D-10).
|
||||
- How the kind marker is spelled in the authorizations listing (D-13).
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Phase scope
|
||||
- `.planning/ROADMAP.md` § "Phase 32.1" — goal and the four success criteria.
|
||||
|
||||
### Prior decisions this phase builds on
|
||||
- `.planning/phases/19.7-generic-mcp-module/19.7-CONTEXT.md` — pier design; D-10 (tool binds to route, in-process dispatch), D-16 (permissions from route middleware), D-20 (read/write ceiling, kept by D-01), D-21 (`backend` scope on the MCP server only).
|
||||
- `.planning/phases/19.4-oidc-provider-on-wristband/19.4-CONTEXT.md` — sm-oauthserver-plugin's two-Server design, client kinds, consent model, additive wristband interfaces.
|
||||
- `/media/nvme/dev/pxpx/sm-servers-app/.planning/phases/05-agent-access-over-mcp/05-CONTEXT.md` § "Decisions after gap verification (2026-10-28)" — D-36/D-37/D-38, the source of this phase (Requests 3, 4, 5).
|
||||
- `/media/nvme/dev/pxpx/sm-servers-app/.planning/phases/05-agent-access-over-mcp/05-09-PLAN.md` — the expected-gap tests the releases must satisfy (`TestMCPOAuthToolsMatchPersonal`, `TestMCPOAuthWriteAttribution`, `TestMCPOAuthEmptyGrant`) and the rejected app-side scope middleware.
|
||||
- `/media/nvme/dev/pxpx/sm-servers-app/OFFBOARDING.md` § 8 — the request texts (what, why, interim).
|
||||
- `../vue-journal-layer/` (and the faq/menu/paymentgateway layers) — the layer structure and release pattern to copy for `vue-oauth-layer`.
|
||||
- `../sm-bm-app/.planning/phases/03.3-mcp-access-for-bm/03.3-CONTEXT.md` — a consuming app's MCP access decisions (D-07 consent page all-or-nothing in that app; personal tokens alongside OAuth).
|
||||
|
||||
### Docs to update
|
||||
- `modules/pier/README.md`, `modules/wristband/README.md`, `modules/pact/README.md`
|
||||
- `docs/services/mcp.md`, `docs/services/oauth-server.md`, `docs/services/authentication.md`
|
||||
- `../sm-oauthserver-plugin/README.md`, the sm-user-plugin README
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `modules/pact/capabilities.go:821-835`: `FrontendTokenScope{Name, Label, Description}` and `HasFrontendTokenScopes`; `ValidTokenScopeName`.
|
||||
- `modules/pact/mcp.go:134`: `MCPSubject{Guard, UserID, Scopes, ClientID, TokenID}`, wrapped by the new `MCPCall`.
|
||||
- `modules/pact/mcp.go:289-303`: `MCPSubjectChanged` with `MCPSubjectRevoked` + `ClientID`, which pier already uses to evict one client's sessions (`modules/pier/events.go:75-90`).
|
||||
- `../sm-oauthserver-plugin/controllers/mcp_consent_api.go`: `MCPConsentDecide` and `grantedScopes` (submitted ∩ requested) already support partial grants.
|
||||
- `../sm-oauthserver-plugin/controllers/authorizations.go`: `AuthorizationsIndex` and `revoke(userID, clientID)` (consent + codes + access/refresh tokens in one tx, then the revoked event).
|
||||
|
||||
### Established Patterns
|
||||
- Scope lists are hardcoded today: `modules/wristband/server.go:99` (`ScopesSupported`), `modules/wristband/authorize.go:24` (`authorizeAllowedScopes`, used only when `Options.ScopesSupported` is empty), `modules/pier/prm.go:14` (`PRMScopes`).
|
||||
- `../sm-oauthserver-plugin/servers.go:158` builds the MCP server's scopes as OIDC scopes + `backend`; the declared/opt-in set goes in here.
|
||||
- `modules/pier/filter.go:60-70`: the read/write ceiling (`id.writes()`) before the guard's `MCPAllows`; unchanged by D-01.
|
||||
- sm-user-plugin `classes/mcp_guard.go`: `MCPAllows` requires the route's `user.scope` names in `subject.Scopes`; the personal-token `MCPDispatch` builds an in-memory credential carrying the token.
|
||||
- Find-or-publish of shared registries on `backpack.App` (`pact.MCPGuards`) is the model for the published scope catalog.
|
||||
|
||||
### Integration Points
|
||||
- `modules/pier/dispatch.go:177-200`: where `bouncer.WithDispatch` is set; the `MCPCall` setter goes next to it (session id from the call info, tool from `t.name`).
|
||||
- `modules/pier/prm.go:mountPRM`: already looks up `pact.MCPTokenVerifier`; extend it to read the scope list from there.
|
||||
- `../sm-oauthserver-plugin/classes/mcp_store.go`: the MCP grant/token store; the consent upsert hooks in at code issue (and at direct grant minting).
|
||||
- `../sm-oauthserver-plugin/updates/`: new migration for the backfill (D-14).
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- The opt-in-or-all rule (D-03) must be documented with examples: unset = all declared scopes, set = only those listed, fixed scopes always.
|
||||
- A redirect-mode app may keep an all-or-nothing consent page; the JSON must give it enough (label, description, locked) to render either way.
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- Offering declared scopes on the OIDC server (non-MCP OAuth clients). Rejected for this phase (D-02).
|
||||
- Release/rollout order across framework, sm-user-plugin, sm-oauthserver-plugin and the consuming app was not discussed in detail; the planner follows the standard "plugin first, pointer bump second" order.
|
||||
- Moving apps' existing `/connect` pages (sm-servers-app, sm-bm-app, sm-demo-app) onto `vue-oauth-layer`: each app's own work.
|
||||
- Switching OAuth on in sm-servers-app production: that app's decision once the releases land.
|
||||
|
||||
### Reviewed Todos (not folded)
|
||||
- 27 pending todos matched on keywords only (e.g. "Record PHP OIDC parity against WavePath", user-plugin logout cookie, activate-by-code second factor). None touch MCP scopes, call context or MCP consent; none were folded.
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con*
|
||||
@@ -0,0 +1,143 @@
|
||||
# Phase 32.1: MCP OAuth for plugin apps - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-10-28
|
||||
**Phase:** 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||
**Areas discussed:** Declared scopes vs ceiling, Consent page for scopes, MCP subject accessor, MCP consent row & revoke
|
||||
|
||||
---
|
||||
|
||||
## Declared scopes vs ceiling
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Keep both | D-20 read/write ceiling stays; declared scopes are extra gates | ✓ |
|
||||
| Declared scope stands alone | Tools behind a declared scope skip the read/write ceiling | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Fixed + all declared | Every FrontendTokenScope is advertised | |
|
||||
| Fixed + config opt-in list | Only listed declared scopes advertised | |
|
||||
| Other | | ✓ |
|
||||
|
||||
**User's choice:** Opt-in config list if set; if unset, all declared scopes. "Document this properly."
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| MCP server only | Same as `backend` (D-21) | ✓ |
|
||||
| Both servers | OIDC clients could request plugin scopes too | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| You decide | Researcher/planner pick the mechanism | |
|
||||
| Published pact catalog | User plugin publishes the compiled list; oauthserver and pier read it | ✓ |
|
||||
|
||||
---
|
||||
|
||||
## Consent page for scopes
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| oauthserver, pier reads it | `golem15.oauthserver.mcp_scopes`; pier reads from the verifier | ✓ |
|
||||
| pier (mcp.scopes) | MCP module owns the list | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Label+description, all-or-nothing | As in 19.4 | |
|
||||
| Per-scope checkboxes | User can untick individual scopes | ✓ |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Both: JSON + built-in page | Consent JSON carries label/description; built-in page renders them | ✓ |
|
||||
| JSON only | Built-in page shows raw names | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Show consent again | Any uncovered requested scope sends the user through consent | ✓ |
|
||||
| You decide | Follow the OIDC path | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| All ticked, read locked | `read` can't be unticked; others can | ✓ |
|
||||
| All ticked, none locked | Anything can be unticked | |
|
||||
|
||||
---
|
||||
|
||||
## MCP subject accessor
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| pact | `pact.MCPSubjectFrom(ctx)` | ✓ |
|
||||
| pier | `pier.SubjectFrom(ctx)` | |
|
||||
| bouncer | Subject field on `bouncer.Dispatch` | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Every MCP tool call | OAuth + PAT, frontend + backend | ✓ |
|
||||
| OAuth calls only | | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| MCPSubject as is | Guard, UserID, ClientID, TokenID, Scopes | |
|
||||
| Plus the MCP session id | Also Mcp-Session-Id | ✓ |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| New pact.MCPCall wrapper | `MCPCall{Subject, SessionID, Tool}`; MCPSubject unchanged | ✓ |
|
||||
| SessionID field on MCPSubject | Guards see the field too | |
|
||||
|
||||
---
|
||||
|
||||
## MCP consent row & revoke
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Same consents table | Upsert (user, client) at MCP code issue | ✓ |
|
||||
| Separate MCP consents table | New table, revoke/listing look in both | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Yes, with a kind marker | Additive `"kind":"mcp"` | ✓ |
|
||||
| Yes, no new field | | |
|
||||
| Separate MCP list endpoint | | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Migration backfills rows | From live MCP access/refresh tokens | ✓ |
|
||||
| Lazy: write on next refresh | | |
|
||||
| Nothing | | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Yes, one revoke ends all | Frontend + backend + sessions | ✓ |
|
||||
| You decide | | |
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Pact catalog interface name/shape; boot error vs warning for unknown opt-in names; `MCPCall` field and setter names; kind marker spelling.
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Declared scopes on the OIDC server.
|
||||
- Detailed rollout order across repos (planner uses the standard plugin-first order).
|
||||
|
||||
---
|
||||
|
||||
## Follow-up (same day): source notes and Vue layer
|
||||
|
||||
The source notes were found in `/media/nvme/dev/pxpx/sm-servers-app` phase 05 (D-36 to D-38, Requests 3–5). Request 3 asked that OAuth `read`/`write` map onto declared scopes, which differs from the locked "advertise declared scopes" approach.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Both: declared implies + advertise | Additive `Implies` on FrontendTokenScope; declared scopes still advertised | ✓ |
|
||||
| Mapping only | Exactly Request 3; drop advertising | |
|
||||
| Advertise only (as locked) | Clients must request servers:* explicitly | |
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Yes, initial layer in 32.1 | New public vue-oauth-layer with the /connect page | ✓ |
|
||||
| Defer to its own phase | JSON contract only | |
|
||||
@@ -0,0 +1,358 @@
|
||||
# Phase 32.1: MCP OAuth for plugin apps — Pattern Map
|
||||
|
||||
**Mapped:** 2026-10-28
|
||||
**Files analyzed:** 28
|
||||
**Analogs found:** 27 / 28 (the new `vue-oauth-layer` repo has no in-repo file; copy the sibling `vue-menu-layer` git repo)
|
||||
|
||||
Tracked-source check: framework paths are `git ls-files` in this repo. Plugin paths are `git ls-files` inside `sm-oauthserver-plugin` (`df2eddd`, v0.1.3) and the `sm-user-plugin` submodule at `sm-demo-app/plugins/golem15/user` (`07196a4`, **v0.1.13**). That submodule is the only local checkout; **implement the user plugin from tag v0.1.14 (`a1b78b80`), not from this worktree.** `vue-menu-layer` is its own repo (`ef3a090`). Do not edit app submodule pointers.
|
||||
|
||||
## File Classification
|
||||
|
||||
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
||||
|-------------------|------|-----------|----------------|---------------|
|
||||
| `modules/pact/capabilities.go` (`FrontendTokenScope.Implies`) | model | transform | same file, `FrontendTokenScope` / `TokenScope` | exact (in-place) |
|
||||
| `modules/pact/mcp.go` (`MCPCall`, `WithMCPCall`, `MCPCallFrom`, `MCPAdvertisedScopes`) | model | request-response | `modules/bouncer/dispatch.go` + `modules/pact/mcp.go` `MCPTokenVerifier` | exact |
|
||||
| `modules/pier/dispatch.go` | service | request-response | same file, `bouncer.WithDispatch` site | exact (in-place) |
|
||||
| `modules/pier/prm.go` | service | request-response | same file, `mountPRM` | exact (in-place) |
|
||||
| `modules/wristband/consent.go` (`PendingRequestView.OfflineAccess`) | model | CRUD | same file, `PendingRequestView` | exact (in-place) |
|
||||
| `modules/{pact,pier,wristband}/README.md`, `docs/services/{mcp,oauth-server,authentication}.md` | config | transform | the same pages | exact (in-place) |
|
||||
| pact/pier unit tests (new cases) | test | request-response | `modules/wristband/mcp_scopes_test.go`, existing pier tests | role-match |
|
||||
| sm-user-plugin `classes/api_token_scopes.go` | service | transform | same file, `CompileAPITokenScopes` | exact (in-place; branch from v0.1.14) |
|
||||
| sm-user-plugin `classes/mcp_guard.go` | middleware | request-response | same file, `MCPAllows` / `MCPDispatch` | exact (in-place; v0.1.14 body) |
|
||||
| sm-user-plugin `plugin.go` `bootAPITokenScopes` | provider | event-driven (boot) | same function + `app.Publish[pact.MCPPersonalTokenResolver]` | exact |
|
||||
| sm-user-plugin `README.md` | config | transform | same README | exact |
|
||||
| sm-user-plugin `classes/mcp_guard_test.go` (extend) | test | request-response | existing `TestMCP*` in that package | role-match |
|
||||
| sm-oauthserver-plugin `config/config.yaml` (`mcp_scopes`) | config | file-I/O | same file header + `modules/pier/config.go` `originsKey` | role-match |
|
||||
| sm-oauthserver-plugin `servers.go` `NewServers` | service | transform | same function | exact (in-place) |
|
||||
| sm-oauthserver-plugin `classes/mcp_verifier.go` | service | request-response | same type; optional method like `methodAllower` | role-match |
|
||||
| sm-oauthserver-plugin `controllers/mcp_consent_api.go` | controller | request-response | same file | exact (in-place) |
|
||||
| sm-oauthserver-plugin `controllers/authorizations.go` | controller | CRUD | same file `revoke` | exact (in-place) |
|
||||
| sm-oauthserver-plugin `updates/<new backfill>.go` | migration | batch | `updates/202610230001_add_backend_user_id.go` | exact |
|
||||
| sm-oauthserver-plugin `lang/en/lang.yaml`, `lang/pl/lang.yaml` | config | file-I/O | existing oauthserver lang files | exact |
|
||||
| sm-oauthserver-plugin `README.md` | config | transform | same README | exact |
|
||||
| sm-oauthserver-plugin consent/authorizations/backfill tests | test | CRUD | `mcp_consent_smoke_test.go`, `authorizations_smoke_test.go` | exact (extend) |
|
||||
| `vue-oauth-layer` (`package.json`, `nuxt.config.ts`, `app/pages/connect.vue`, `tests/*.test.ts`, README) | component | request-response | `vue-menu-layer` (sibling repo) | role-match |
|
||||
|
||||
## Pattern Assignments
|
||||
|
||||
### `modules/pact/capabilities.go` (model, transform)
|
||||
|
||||
**Analog:** `modules/pact/capabilities.go` (tracked)
|
||||
|
||||
**Core pattern** (lines 814–834) — add `Implies string` only. Zero value keeps existing composite literals valid. Update the comment that says the struct carries no permission patterns.
|
||||
|
||||
```go
|
||||
type FrontendTokenScope struct {
|
||||
Name string
|
||||
Label string
|
||||
Description string
|
||||
}
|
||||
type HasFrontendTokenScopes interface {
|
||||
FrontendTokenScopes() []FrontendTokenScope
|
||||
}
|
||||
```
|
||||
|
||||
Do not add a method named `FrontendTokenScopes` on the new catalog interface (that name is already `HasFrontendTokenScopes`).
|
||||
|
||||
---
|
||||
|
||||
### `modules/pact/mcp.go` (model, request-response)
|
||||
|
||||
**Analogs:** `modules/bouncer/dispatch.go` (context key) and `modules/pact/mcp.go` (interfaces already here).
|
||||
|
||||
**Context-key pattern** (`modules/bouncer/dispatch.go` lines 5–34). Copy the unexported key. Prefer not turning a nil ctx into `context.Background()`: pier's dispatch context is never nil. `MCPCallFrom` returns `ok == false` when the value is absent (plain HTTP).
|
||||
|
||||
```go
|
||||
type dispatchKey struct{}
|
||||
|
||||
func WithDispatch(ctx context.Context, d *Dispatch) context.Context {
|
||||
if ctx == nil {
|
||||
ctx = context.Background()
|
||||
}
|
||||
return context.WithValue(ctx, dispatchKey{}, d)
|
||||
}
|
||||
```
|
||||
|
||||
**Optional interface, not a new method on `MCPTokenVerifier`** (`modules/pact/mcp.go` lines 217–225). A new method would break every fake. Match the second-interface pattern in `modules/pier/backend_guard.go` lines 29–31:
|
||||
|
||||
```go
|
||||
type methodAllower interface {
|
||||
MCPAllowsMethod(ctx context.Context, subject pact.MCPSubject, req pact.MCPRequirements, permissions []string, method string) (bool, error)
|
||||
}
|
||||
```
|
||||
|
||||
Recommended additive types (discretion, already in RESEARCH):
|
||||
|
||||
```go
|
||||
type MemberTokenScopeCatalog interface {
|
||||
MemberTokenScopes() []FrontendTokenScope
|
||||
}
|
||||
type MCPAdvertisedScopes interface {
|
||||
MCPScopesSupported() []string
|
||||
}
|
||||
type MCPCall struct {
|
||||
Subject MCPSubject
|
||||
SessionID string
|
||||
Tool string
|
||||
}
|
||||
```
|
||||
|
||||
`MCPSubject` stays lines 134–140 (`Guard`, `UserID`, `Scopes`, `ClientID`, `TokenID`). Publish lookup shape is `modules/backpack/app.go` lines 59–73: `Publish[T]` / `Lookup[T]`.
|
||||
|
||||
---
|
||||
|
||||
### `modules/pier/dispatch.go` (service, request-response)
|
||||
|
||||
**Analog:** same file, lines 169–208.
|
||||
|
||||
Set the call on the line immediately before `WithDispatch`. `subject` is `id.subjectFor(t.guardName)` (line 169). `Tool` is `t.name`. `SessionID` comes from the call info's session, forced to `""` on the stateless path and never the audit word `"ephemeral"`.
|
||||
|
||||
```go
|
||||
subject := id.subjectFor(t.guardName)
|
||||
// ...
|
||||
credential := disp.Credential
|
||||
if credential == nil && t.guardName == BackendGuard {
|
||||
credential = id.credential
|
||||
}
|
||||
callCtx = bouncer.WithDispatch(callCtx, &bouncer.Dispatch{Guards: disp.Guards, Principal: principal, Credential: credential})
|
||||
```
|
||||
|
||||
Do not expand scopes here. Ceiling stays in `modules/pier/filter.go` (`id.writes()` before `MCPAllows`).
|
||||
|
||||
---
|
||||
|
||||
### `modules/pier/prm.go` (service, request-response)
|
||||
|
||||
**Analog:** same file, lines 12–40.
|
||||
|
||||
```go
|
||||
var PRMScopes = []string{"read", "write", "ai", "offline_access", "backend"}
|
||||
// ...
|
||||
if verifier, ok := p.app.Lookup[pact.MCPTokenVerifier](); ok && verifier != nil {
|
||||
if res := verifier.MCPResource(); res != "" { /* issuer */ }
|
||||
}
|
||||
meta := &oauthex.ProtectedResourceMetadata{
|
||||
Resource: p.cfg.Resource,
|
||||
ScopesSupported: append([]string(nil), PRMScopes...),
|
||||
BearerMethodsSupported: []string{"header"},
|
||||
}
|
||||
```
|
||||
|
||||
Replace only the `ScopesSupported` assignment: if the same verifier also implements `pact.MCPAdvertisedScopes` and the slice is non-empty, clone that; otherwise keep `PRMScopes`. Do not import the oauthserver plugin. Do not read the raw member-token catalog (that skips the opt-in filter).
|
||||
|
||||
---
|
||||
|
||||
### `modules/wristband/consent.go` (model, CRUD)
|
||||
|
||||
**Analog:** same file, lines 35–74. Add `OfflineAccess bool` to `PendingRequestView` and fill it in `PendingRequest`. Do not change `IssueCode`'s signature. The store reads a context value (same idea as `classes.WithConsentedBackend`) so a direct `IssueCode` call keeps today's flag.
|
||||
|
||||
```go
|
||||
type PendingRequestView struct {
|
||||
ClientName string
|
||||
RedirectHost string
|
||||
ScopesRequested []string
|
||||
ExpiresAt time.Time
|
||||
}
|
||||
func (s *Server) IssueCode(ctx context.Context, requestID string, userID uint, grantedScopes []string, collectionIDs []uint) (string, error)
|
||||
```
|
||||
|
||||
Authorize allow-list is already `Options.ScopesSupported` when non-empty (`modules/wristband/authorize.go` `allowedAuthorizeScopes`). No wristband change is required to accept a declared name once the host fills the slice. An empty slice falls back to the PHP four-name map and drops `backend` — the host must never pass an empty slice.
|
||||
|
||||
---
|
||||
|
||||
### sm-user-plugin `classes/api_token_scopes.go` + `plugin.go` (service + boot provider)
|
||||
|
||||
**Analog (structure only):** `sm-demo-app/plugins/golem15/user/classes/api_token_scopes.go` lines 52–127 and `plugin.go` lines 154–195. **Branch from v0.1.14.** Do not edit the submodule.
|
||||
|
||||
`CompileAPITokenScopes` already rejects built-in names `read`/`write`/`ai`, duplicates, empty label/description, and fails boot. Extend that same loop: reject `Implies` other than `""`, `"read"`, `"write"`, and reject declared names `backend` and `offline_access`. Built-ins keep `Implies` empty. Phrase-key check stays in `bootAPITokenScopes` (`tr.Has`).
|
||||
|
||||
Publish the compiled list as the new pact interface, beside the existing concrete publish and the guard publish:
|
||||
|
||||
```go
|
||||
return app.Publish(catalog) // today: *APITokenScopeCatalog
|
||||
// and:
|
||||
return app.Publish[pact.MCPPersonalTokenResolver](guard)
|
||||
```
|
||||
|
||||
The published catalog includes built-ins (labels for consent) plus declared scopes. Advertised declared names are catalog entries whose name is not `read`, `write`, or `ai`. `offline_access` and `backend` are not member-token scopes; oauthserver prepends the fixed five.
|
||||
|
||||
---
|
||||
|
||||
### sm-user-plugin `classes/mcp_guard.go` (middleware, request-response)
|
||||
|
||||
**Analog:** v0.1.13 worktree `MCPAllows` lines 87–136 is the wrong credential body. On **v0.1.14** `MCPDispatch` sets `credential.ID = subject.TokenID` only when `subject.ClientID == ""` and leaves OAuth credentials at ID 0. Keep that. One helper used by both `MCPAllows` and `MCPDispatch`:
|
||||
|
||||
- `ClientID == ""`: return `subject.Scopes` unchanged (personal token).
|
||||
- else: clone scopes; for each catalog entry with `Implies` `"read"` or `"write"`, if the grant contains that stock scope and the declared name is absent, append it.
|
||||
- Never write the expanded set onto the token row, the session fingerprint, or `subject.Scopes` as stored.
|
||||
|
||||
`MCPAllows` today (v0.1.13 lines 90–94), which the helper replaces for the scope check only:
|
||||
|
||||
```go
|
||||
for _, scope := range req.Scopes {
|
||||
if !slices.Contains(subject.Scopes, scope) {
|
||||
return false, nil
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`MCPDispatch` puts the helper's slice on `models.APIToken.Scopes` (`lagoon.Jsonable`). `middleware.Scope` reads `token.HasScope` (`slices.Contains` on that slice). Do not set `APIToken.OAuthClientID`. The OAuth client id belongs on `pact.MCPCall`. Do not expand scopes in pier's backend guard (`modules/pier/backend_guard.go`).
|
||||
|
||||
---
|
||||
|
||||
### sm-oauthserver-plugin `servers.go` + `config/config.yaml` (service + config)
|
||||
|
||||
**Analog:** `servers.go` lines 154–158 and `modules/pier/config.go` `originsKey` lines 230–262.
|
||||
|
||||
```go
|
||||
mcpOpts := opts
|
||||
mcpOpts.Resource = cfg.MCPResource
|
||||
mcpOpts.ScopesSupported = append(slices.Clone(opts.ScopesSupported), "backend")
|
||||
```
|
||||
|
||||
`mcpOpts := opts` is already a struct copy. Build the MCP slice on that copy only: fixed five (`read`, `write`, `ai`, `offline_access`, `backend`), then declared names in catalog order, filtered by `golem15.oauthserver.mcp_scopes` when `Config.Has` is true. Empty list (key set) means fixed five only. Unset means every declared scope. Do not assign `cfg.OIDC.ScopesSupported`. Do not append `"backend"` twice. Unknown opt-in name fails boot (name the key and the name), matching `CompileAPITokenScopes`.
|
||||
|
||||
Read the list with `Lookup` and the `[]any` / `[]string` / comma-string switch from `originsKey` (env `SUMMER_GOLEM15__OAUTHSERVER__MCP_SCOPES`). Config file header documents the env spelling (`config/config.yaml` lines 1–3).
|
||||
|
||||
`classes/mcp_verifier.go` returns `pact.MCPGrant` (lines 109–118) and must also implement `MCPScopesSupported()` with the same slice `NewServers` assigned. Publish both `pact.MCPTokenVerifier` and the optional scopes interface on that value.
|
||||
|
||||
---
|
||||
|
||||
### sm-oauthserver-plugin `controllers/mcp_consent_api.go` (controller, request-response)
|
||||
|
||||
**Analog:** same file. Keep `scopes []string`. Add `scope_details` (`name`, `label`, `description`, `locked`) and `logo_url` on the client. `locked` is true only for requested `read`.
|
||||
|
||||
Show body today (lines 24–43):
|
||||
|
||||
```go
|
||||
type mcpConsentShowBody struct {
|
||||
RequestID string `json:"request_id"`
|
||||
Client mcpConsentClient `json:"client"`
|
||||
Scopes []string `json:"scopes"`
|
||||
ExpiresAt string `json:"expires_at"`
|
||||
BackendAdmin *mcpConsentAdmin `json:"backend_admin"`
|
||||
}
|
||||
```
|
||||
|
||||
Keep `grantedScopes` (lines 168–180). Do not force `read` back in (smoke test posts `scopes: ["backend"]` and expects 422). Augment the requested list with `offline_access` when the pending flag is set, intersect against that, strip the word before `IssueCode`, and set the column from the decision via context. A submit whose only remaining scope is `offline_access` still 422. `read` is data-bearing. `backend` counts only when a link is recorded (existing strip at lines 144–161).
|
||||
|
||||
Labels: catalog phrase through `phrasebook.Translator.Get` when the text contains `::`, else the literal. `backend` and `offline_access` are not in the user catalog; add en+pl phrase keys in this plugin. Logo: `classes.ClientLogoURL` (already used in `authorizations.go` line 81).
|
||||
|
||||
**Do not call `oidcTx.SaveConsent`.** It unions ( `classes/oidc_store.go` lines 328–361). MCP decision replaces scopes (`ON CONFLICT DO UPDATE SET scopes = excluded.scopes`). Silent re-grant (`consent_required: false`, nothing missing) only `TouchConsent` (lines 364–366) and issues the requested subset. First grant inserts. Deny does not change the row. Upsert after `IssueCode` returns nil. Store `offline_access` in the consent scope list when the flag was granted. `models.ClientKindMCP` / `ClientKindOIDC` are `"mcp"` / `"oidc"` (`models/client.go` lines 14–17).
|
||||
|
||||
---
|
||||
|
||||
### sm-oauthserver-plugin `controllers/authorizations.go` (controller, CRUD)
|
||||
|
||||
**Analog:** same file, lines 21–157.
|
||||
|
||||
Add `Kind string \`json:"kind"\`` last on `authorization`. Select `c.kind`. Always set it (`oidc` or `mcp`), do not omit OIDC. Key order stays `client_id`, `name`, `logo_url`, `scopes`, `first_authorized_at`, `last_used_at`, then `kind`. Update `authorizations_smoke_test.go` which requires exactly six keys.
|
||||
|
||||
`revoke` (lines 134–157) locks the consent row then deletes `Consent`, `AuthCode`, `AccessToken`, `RefreshToken`. Also delete `models.MCPCode` for the same pair. Take `classes.lockUserGrants` (exclusive, `classes/mcp_backend_binding.go` lines 61–75) inside the transaction **before** the deletes. Keep 404 `errNotFound` when no consent. Keep the existing `MCPSubjectRevoked` with `ClientID` and **no** `TokenID` (lines 124–126). Do not add a second backend revoke: access/refresh rows already carry `backend_user_id`.
|
||||
|
||||
---
|
||||
|
||||
### sm-oauthserver-plugin backfill migration (migration, batch)
|
||||
|
||||
**Analog:** `updates/202610230001_add_backend_user_id.go` lines 15–35 (`init() { Register(...) }`, ID sorts after `202610230001_add_golem15_oauthserver_backend_user_id`).
|
||||
|
||||
```go
|
||||
var addBackendUserID = []*gormigrate.Migration{{
|
||||
ID: "202610230001_add_golem15_oauthserver_backend_user_id",
|
||||
Migrate: func(tx *gorm.DB) error { return run(tx, []string{ /* SQL */ }) },
|
||||
Rollback: func(tx *gorm.DB) error { return run(tx, []string{ /* SQL */ }) },
|
||||
}}
|
||||
func init() { Register(addBackendUserID...) }
|
||||
```
|
||||
|
||||
A Go loop inside `Migrate` is the practical way to union JSON scope arrays (`models.Strings` is `lagoon.Jsonable[[]string]`). One row per live MCP `(user_id, client_id)`; skip pairs that already have a consent; include `offline_access` from the boolean column; `created_at` = earliest live token; `last_used_at` stays null; second run inserts nothing. `Rollback` no-ops with a comment (D-14 is one-way). Do not delete every MCP consent on rollback.
|
||||
|
||||
---
|
||||
|
||||
### Docs (config, transform)
|
||||
|
||||
**Analogs:** the pages themselves. Identifiers and the code that exports them land in the same commit (`go test ./cmd/summer -run TestDocsTree`). Framework docs never name a consuming app. Document:
|
||||
|
||||
- `pact.MCPCall` / `MCPCallFrom` / setter: `Subject.TokenID` is a `user_api_tokens` id only when `ClientID == ""`; otherwise it is the oauthserver access-token row. `Subject.Scopes` is the grant, not the implied expansion.
|
||||
- `golem15.oauthserver.mcp_scopes`: unset = all declared, set = only those names, empty list = fixed five only, fixed five always. Config keys are not checked by the docs checker; review them by hand.
|
||||
- pier PRM reads the verifier list, else `PRMScopes`.
|
||||
- Existing DCR clients with a non-nil scope ceiling silently drop names outside that ceiling. Do not rewrite old ceilings.
|
||||
|
||||
Do not add checkboxes to `views/consent.html.tmpl` (OIDC page). MCP authorize always redirects to `{issuer}/connect?request=`.
|
||||
|
||||
---
|
||||
|
||||
### `vue-oauth-layer` (component, request-response) — no file in this repo
|
||||
|
||||
**Analog:** sibling repo `/media/nvme/dev/golem15/summercms.io/summercms/vue-menu-layer` (git `ef3a090`), not `vue-journal-layer` (journal pulls SEO/i18n/fonts).
|
||||
|
||||
**package.json** (lines 1–24): `"type": "module"`, `"main": "./nuxt.config.ts"`, `"engines": {"node": ">=22.18"}`, peer `nuxt` 4.4.8, dev `vue` 3.5.35 and `typescript` 5.9.3, `"test": "node --test --test-reporter=tap tests/*.test.ts"`.
|
||||
|
||||
**nuxt.config.ts** (lines 1–13): paths from `fileURLToPath(new URL('.', import.meta.url))`. A relative path resolves against the consuming app.
|
||||
|
||||
**Tests:** `tests/menuLinks.test.ts` lines 1–25 — `node:test` + `node:assert/strict` over pure functions, no browser. Map show JSON → boxes, locked `read`, POST body, 409 re-fetch. Page at `app/pages/connect.vue` (Nuxt merges layer pages; an app's own page wins). Render labels as text, not `v-html`. Do not proxy the OAuth API. 401 redirects to a documented login prop, default `/login`. Do not tag or push the repo in the plan. Do not edit any app's `/connect`.
|
||||
|
||||
README install line shape (`vue-menu-layer/README.md` lines 5–7 and 27–35):
|
||||
|
||||
```bash
|
||||
pnpm add git+https://git.golem15.com/golem15/vue-menu-layer.git#v0.2.0
|
||||
```
|
||||
|
||||
```ts
|
||||
export default defineNuxtConfig({
|
||||
extends: ['vue-menu-layer'],
|
||||
})
|
||||
```
|
||||
|
||||
## Shared Patterns
|
||||
|
||||
### Publish / lookup
|
||||
**Source:** `modules/backpack/app.go` lines 59–73
|
||||
**Apply to:** user-plugin catalog, oauthserver verifier, pier PRM lookup
|
||||
|
||||
```go
|
||||
func (a *App) Publish[T any](value T) error
|
||||
func (a *App) Lookup[T any]() (T, bool)
|
||||
```
|
||||
|
||||
### Optional second interface
|
||||
**Source:** `modules/pier/backend_guard.go` lines 29–31
|
||||
**Apply to:** `pact.MCPAdvertisedScopes` on the existing verifier value. Do not add methods to `MCPTokenVerifier`.
|
||||
|
||||
### Config list (YAML list, string slice, or comma env string)
|
||||
**Source:** `modules/pier/config.go` lines 230–246
|
||||
**Apply to:** `golem15.oauthserver.mcp_scopes`. Use `Config.Has` to tell unset from empty. `Config.String` returns `""` for both.
|
||||
|
||||
### Consent intersection (keep)
|
||||
**Source:** `sm-oauthserver-plugin/controllers/mcp_consent_api.go` lines 168–180
|
||||
**Apply to:** MCP consent decide. Augment requested with `offline_access` first; do not special-case `read`.
|
||||
|
||||
### Consent replace vs union
|
||||
**Source:** `sm-oauthserver-plugin/classes/oidc_store.go` lines 328–366 (`SaveConsent` unions; `TouchConsent` only stamps `last_used_at`)
|
||||
**Apply to:** MCP must not call `SaveConsent`. Decision path replaces `scopes`. Silent path calls `TouchConsent` only.
|
||||
|
||||
### Grants lock then delete
|
||||
**Source:** `classes/mcp_backend_binding.go` lines 43–75 and `controllers/authorizations.go` lines 134–157
|
||||
**Apply to:** per-client revoke, plus `models.MCPCode`. Event stays `MCPSubjectRevoked` + `ClientID` only (`authorizations.go` lines 124–126).
|
||||
|
||||
### Error JSON
|
||||
**Source:** `mcp_consent_api.go` `writeDecision` lines 196–208 and `authorizations.go` lines 116–120
|
||||
**Apply to:** new consent and revoke branches. 401 `unauthenticated`, 404 `request_not_found` / `not_found`, 409 `backend_link_changed`, 422 `no_grantable_scopes`, 500 `server_error`.
|
||||
|
||||
### Boot failure on a bad declaration
|
||||
**Source:** `CompileAPITokenScopes` error strings (`golem15.user: plugin %s declared ...`) and `bootAPITokenScopes` missing phrase key
|
||||
**Apply to:** bad `Implies`, reserved names `backend`/`offline_access`, unknown `mcp_scopes` entry.
|
||||
|
||||
## No Analog Found
|
||||
|
||||
| File | Role | Data Flow | Reason |
|
||||
|------|------|-----------|--------|
|
||||
| `vue-oauth-layer` repo (does not exist) | component | request-response | Not in this module. Copy `vue-menu-layer`, not journal. RESEARCH Pattern 10 is the page behaviour; there is no `/connect` Vue page in the framework. |
|
||||
|
||||
User-plugin files exist only as a v0.1.13 submodule. They are valid structural analogs. The credential-id assignment must be copied from tag v0.1.14, which is not checked out. RESEARCH quotes that function (`classes/mcp_guard.go` lines 115–143 on the tag).
|
||||
|
||||
## Metadata
|
||||
|
||||
**Analog search scope:** `modules/pact`, `modules/pier`, `modules/wristband`, `modules/bouncer`, `modules/backpack`, `modules/compass`; `sm-oauthserver-plugin`; `sm-demo-app/plugins/golem15/user` (v0.1.13, read-only); `vue-menu-layer`.
|
||||
**Files scanned:** the classification table plus `oidc_store.go`, `mcp_backend_binding.go`, `mcp_verifier.go`, `models/client.go`.
|
||||
**Pattern extraction date:** 2026-10-28
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,53 @@
|
||||
---
|
||||
phase: 32.1
|
||||
review: 32.1-REVIEW.md
|
||||
titles: json
|
||||
findings:
|
||||
- id: CR-01
|
||||
severity: critical
|
||||
disposition: fixed
|
||||
title: "An in-flight MCP allow recreates a consent the user just revoked"
|
||||
- id: WR-01
|
||||
severity: warning
|
||||
disposition: open
|
||||
title: "Clearing a declared scope does not stop `read` or `write` from implying it"
|
||||
- id: WR-02
|
||||
severity: warning
|
||||
disposition: open
|
||||
title: "`mcp_scopes` does not limit what an OAuth `read` or `write` grant can call"
|
||||
- id: WR-03
|
||||
severity: warning
|
||||
disposition: open
|
||||
title: "The consent backfill treats unusable tokens as live grants"
|
||||
- id: WR-04
|
||||
severity: warning
|
||||
disposition: open
|
||||
title: "Replacing a consent does not revoke refresh tokens that still carry the removed scopes"
|
||||
- id: WR-05
|
||||
severity: warning
|
||||
disposition: open
|
||||
title: "sm-user-plugin v0.1.16 does not require the framework version it uses"
|
||||
- id: WR-06
|
||||
severity: warning
|
||||
disposition: open
|
||||
title: "`/connect` can allow a stale request after `?request=` changes"
|
||||
open: 6
|
||||
total: 7
|
||||
recorded: 2026-10-28T16:03:08.042Z
|
||||
---
|
||||
|
||||
# Phase 32.1: Code Review Disposition
|
||||
|
||||
| Finding | Severity | Disposition | Source |
|
||||
|---------|----------|-------------|--------|
|
||||
| CR-01 | critical | fixed | sm-oauthserver-plugin 21f5985 (unreleased; ships with the next plugin tag) |
|
||||
| WR-01 | warning | open | - |
|
||||
| WR-02 | warning | open | - |
|
||||
| WR-03 | warning | open | - |
|
||||
| WR-04 | warning | open | - |
|
||||
| WR-05 | warning | open | - |
|
||||
| WR-06 | warning | open | - |
|
||||
|
||||
Dispositions: `open` (recorded, not yet triaged), `fixed`, `skipped`, `deferred`.
|
||||
Set `deferred` by hand and put the reason in the Source cell; both are preserved. A `|` in the reason is kept as prose and escaped on the next run.
|
||||
Re-running the gate keeps every row it can. A row the current review no longer reports is kept and its Source cell flagged, so a finding does not leave this record silently. ONE exception: when a finding id is REUSED by a different finding, the earlier decision cannot keep a row — the id is taken — and it is dropped. A RECORDED decision (anything but `open`) is named on the console when that happens; a row still at `open` is replaced silently, because `open` records no decision to lose.
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
phase: 32.1-mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con
|
||||
reviewed: 2026-10-28T15:58:24Z
|
||||
depth: standard
|
||||
files_reviewed: 53
|
||||
files_reviewed_list:
|
||||
- modules/pact/capabilities.go
|
||||
- modules/pact/mcp.go
|
||||
- modules/pact/mcp_call_test.go
|
||||
- modules/pact/mcp_call_negative_test.go
|
||||
- modules/pact/README.md
|
||||
- modules/pier/dispatch.go
|
||||
- modules/pier/prm.go
|
||||
- modules/pier/session.go
|
||||
- modules/pier/stateless.go
|
||||
- modules/pier/mcp_seam_test.go
|
||||
- modules/pier/dispatch_mcpcall_test.go
|
||||
- modules/pier/prm_scopes_test.go
|
||||
- modules/pier/README.md
|
||||
- modules/wristband/authorize.go
|
||||
- modules/wristband/server.go
|
||||
- modules/wristband/consent.go
|
||||
- modules/wristband/mcp_scopes_smoke_test.go
|
||||
- modules/wristband/README.md
|
||||
- docs/services/authentication.md
|
||||
- docs/services/mcp.md
|
||||
- docs/services/oauth-server.md
|
||||
- sm-user-plugin/classes/api_token_scopes.go
|
||||
- sm-user-plugin/classes/mcp_guard.go
|
||||
- sm-user-plugin/plugin.go
|
||||
- sm-user-plugin/go.mod
|
||||
- sm-user-plugin/mcp_implies_test.go
|
||||
- sm-user-plugin/README.md
|
||||
- sm-oauthserver-plugin/classes/mcp_scopes.go
|
||||
- sm-oauthserver-plugin/classes/mcp_verifier.go
|
||||
- sm-oauthserver-plugin/classes/mcp_backend_binding.go
|
||||
- sm-oauthserver-plugin/classes/mcp_store.go
|
||||
- sm-oauthserver-plugin/controllers/mcp_consent_api.go
|
||||
- sm-oauthserver-plugin/controllers/authorizations.go
|
||||
- sm-oauthserver-plugin/config/config.yaml
|
||||
- sm-oauthserver-plugin/plugin.go
|
||||
- sm-oauthserver-plugin/servers.go
|
||||
- sm-oauthserver-plugin/lang/en/lang.yaml
|
||||
- sm-oauthserver-plugin/lang/pl/lang.yaml
|
||||
- sm-oauthserver-plugin/README.md
|
||||
- sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go
|
||||
- sm-oauthserver-plugin/mcp_scopes_test.go
|
||||
- sm-oauthserver-plugin/mcp_consent_test.go
|
||||
- sm-oauthserver-plugin/mcp_consent_smoke_test.go
|
||||
- sm-oauthserver-plugin/mcp_backfill_test.go
|
||||
- sm-oauthserver-plugin/authorizations_smoke_test.go
|
||||
- sm-oauthserver-plugin/authorizations_kind_test.go
|
||||
- sm-oauthserver-plugin/go.mod
|
||||
- vue-oauth-layer/app/pages/connect.vue
|
||||
- vue-oauth-layer/app/utils/connectConsent.ts
|
||||
- vue-oauth-layer/tests/connect.test.ts
|
||||
- vue-oauth-layer/nuxt.config.ts
|
||||
- vue-oauth-layer/package.json
|
||||
- vue-oauth-layer/README.md
|
||||
findings:
|
||||
critical: 1
|
||||
warning: 6
|
||||
info: 0
|
||||
total: 7
|
||||
status: issues_found
|
||||
---
|
||||
|
||||
# Phase 32.1: Code Review Report
|
||||
|
||||
**Reviewed:** 2026-10-28T15:58:24Z
|
||||
**Depth:** standard
|
||||
**Files Reviewed:** 53
|
||||
**Status:** issues_found
|
||||
|
||||
## Summary
|
||||
|
||||
Reviewed the phase 32.1 commits only: summercms.go `63d05e8`, `9e29d6f`, `876f0f0`, `9094bf9`; sm-user-plugin `25fd981`, `193a381`, `756797c`; sm-oauthserver-plugin `644641a`, `52529c6`, `a409074`, `4f8618e`, `a7743e7`; vue-oauth-layer `02c466e`, `37c1e12`, `7f805b3`. Lockfiles, the vue skeleton, and phase 33 planning commits were not treated as product changes. Advisory only; no product file was modified.
|
||||
|
||||
The scope list, `MCPCall` placement, PRM copy, and the OAuth-only `Implies` expansion match the phase decisions. The consent decision does not. `IssueCode` commits the authorization code, then a later transaction writes the consent row, and neither takes `LockUserGrants`. A revoke that lands in that gap deletes the code and the old consent, and the allow puts the consent back. Separately, clearing a declared scope on `/connect` does not stop the user guard from implying it back from locked `read`/`write`, and a replaced consent does not revoke refresh tokens that still carry the removed scopes.
|
||||
|
||||
## Narrative Findings (AI reviewer)
|
||||
|
||||
## Critical Issues
|
||||
|
||||
### CR-01: An in-flight MCP allow recreates a consent the user just revoked
|
||||
|
||||
**File:** `sm-oauthserver-plugin/controllers/mcp_consent_api.go:221-241`, `sm-oauthserver-plugin/controllers/authorizations.go:138-164`, `sm-oauthserver-plugin/classes/mcp_store.go:256-279`
|
||||
|
||||
**Issue:** `MCPConsentDecide` calls `srv.IssueCode`, which commits `MarkIssued` in its own transaction, and only then calls `recordMCPConsent`. `MarkIssued` does not take `LockUserGrants`. Revoke does: it locks, deletes the consent, and deletes MCP codes, access tokens, and refresh tokens for that user and client.
|
||||
|
||||
This interleaving is possible whenever a consent row already exists (a re-consent, including the silent `consent_required: false` path):
|
||||
|
||||
1. Allow's `IssueCode` commits. The new MCP code exists. The consent row is still the old one, or not yet replaced.
|
||||
2. Revoke commits. It deletes that consent and the new code, then returns `{"revoked": true}`.
|
||||
3. Allow's `recordMCPConsent` runs. `Take` now returns not found, so `replaceMCPConsent` inserts a new row.
|
||||
4. Allow returns 200 and the redirect for a code revoke already deleted.
|
||||
|
||||
The token exchange fails, but the consent row is back. The next authorize for scopes that row covers sets `consent_required` false, and `vue-oauth-layer` posts allow immediately. Revoke did not stick. The same split leaves a live code and a 500 if the consent write fails after `IssueCode` succeeds, because the redirect is withheld while the code hash is already stored.
|
||||
|
||||
**Fix:** Issue the code and upsert the consent in one transaction that holds `LockUserGrants` for the whole unit, the same exclusive lock revoke takes. Revoke then either waits and deletes both rows, or commits first and the allow sees that result inside the lock. Do not write the consent after `IssueCode` returns.
|
||||
|
||||
```go
|
||||
err = s.backend.WithinTx(ctx, func(tx Tx) error {
|
||||
if err := classes.LockUserGrants(ctx, tx.DB(), []uint{userID}); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := tx.MarkIssued(ctx, pending.ID, sha256Hex(code), userID, grantedScopes, collectionIDs, expiresAt); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := tx.MarkConsented(ctx, client.ClientID); err != nil {
|
||||
return err
|
||||
}
|
||||
return replaceMCPConsent(ctx, tx.DB(), userID, client.ClientID, stored, now)
|
||||
})
|
||||
```
|
||||
|
||||
`replaceMCPConsent` has to use that same `tx`. A consent failure must roll the code back.
|
||||
|
||||
## Warnings
|
||||
|
||||
### WR-01: Clearing a declared scope does not stop `read` or `write` from implying it
|
||||
|
||||
**File:** `sm-user-plugin/classes/mcp_guard.go:160-174`, `sm-oauthserver-plugin/controllers/mcp_consent_api.go:408-418`, `vue-oauth-layer/app/pages/connect.vue:147-160`
|
||||
|
||||
**Issue:** `read` is locked whenever it was requested. Declared scopes are checkboxes the user can clear, and `grantedScopes` then omits them from the token and, on a real replace, from the consent row. `mcpEffectiveScopes` adds every catalog name whose `Implies` is `read` or `write` whenever the OAuth grant still holds that stock scope. A grant of only `read` is also what a client receives when the user cleared `servers:read` and left locked `read`. `MCPAllows` and the in-memory `user.scope` credential both see the name again, so the tool still runs. The checkbox is not a denial for any scope implied by a stock scope that remains on the grant.
|
||||
|
||||
**Fix:** Store an explicit denial, or stop presenting an implied name as optional while its stock scope is on the request. If the name stays optional, `mcpEffectiveScopes` must not append a declared name the user cleared on this grant. Absence cannot mean both "never requested" and "user denied" without a separate denial list.
|
||||
|
||||
### WR-02: `mcp_scopes` does not limit what an OAuth `read` or `write` grant can call
|
||||
|
||||
**File:** `sm-user-plugin/classes/mcp_guard.go:165-173`, `sm-oauthserver-plugin/classes/mcp_scopes.go:25-57`, `sm-oauthserver-plugin/config/config.yaml:77-84`
|
||||
|
||||
**Issue:** `AdvertisedMCPScopes` drops declared names that are not in `golem15.oauthserver.mcp_scopes`. An empty list is documented as the five fixed names only, and authorize rejects anything outside the advertised slice. `mcpEffectiveScopes` never reads that slice. It walks the whole member-token catalog. A client that was only allowed to request `read` still satisfies every `Implies: "read"` name, including names the operator excluded and that `/connect` never shows.
|
||||
|
||||
**Fix:** Intersect the expansion with the advertised MCP scope list (the same slice `NewServers` stored on the verifier). An unset filter still implies every declared name. A set or empty filter then matches what metadata, authorize, and the consent page show.
|
||||
|
||||
### WR-03: The consent backfill treats unusable tokens as live grants
|
||||
|
||||
**File:** `sm-oauthserver-plugin/updates/202610280001_backfill_golem15_oauthserver_mcp_consents.go:151-182`
|
||||
|
||||
**Issue:** `loadLiveMCPTokens` keeps a row when `revoked_at` is null and `expires_at` is null or in the future. It does not require an active, unrevoked MCP client, a non-null access-token expiry, or `rotated_to_id IS NULL`. `MCPTokenVerifier` rejects an access token with a nil expiry, a revoked client, or an inactive client (`classes/mcp_verifier.go:103-115`). A refresh token with `rotated_to_id` set is a replay, not a usable grant (`modules/wristband/token.go:332-340`). Those rows still seed `golem15_oauthserver_consents`. The inserted consent outlives the token, so a later authorize for those scopes skips the prompt even though this server would not have honored the source token.
|
||||
|
||||
**Fix:** Match the verifier. Require `c.revoked_at IS NULL AND c.is_active`, `a.expires_at IS NOT NULL AND a.expires_at > NOW()` for access tokens, and `r.rotated_to_id IS NULL` for refresh tokens.
|
||||
|
||||
### WR-04: Replacing a consent does not revoke refresh tokens that still carry the removed scopes
|
||||
|
||||
**File:** `sm-oauthserver-plugin/controllers/mcp_consent_api.go:348-364`, `modules/wristband/token.go:361-370`
|
||||
|
||||
**Issue:** A real allow replaces `golem15_oauthserver_consents.scopes` with the new grant. It does not revoke that client's access or refresh tokens. Refresh rotation copies `rec.Scopes` and `rec.OfflineAccess` from the existing refresh row, not from the consent row. After the user clears `write` or `offline_access` on a later allow, the old refresh token keeps minting access tokens with the old scope set until it expires or the user deletes the whole authorization.
|
||||
|
||||
**Fix:** In the same locked transaction as the consent replace, revoke this client’s access tokens and refresh-token lineages whose scopes are not a subset of the new grant (and whose `offline_access` column is set when the new grant omits it). Leave other clients alone.
|
||||
|
||||
### WR-05: sm-user-plugin v0.1.16 does not require the framework version it uses
|
||||
|
||||
**File:** `sm-user-plugin/go.mod:6`, `sm-user-plugin/go.mod:183`
|
||||
|
||||
**Issue:** The tagged module calls `pact.MemberTokenScopeCatalog` and `FrontendTokenScope.Implies`, which shipped in summercms v0.5.2. `go.mod` still requires `git.golem15.com/golem15/summercms v0.5.0` and replaces it with `../summercms.go`. Downstream modules ignore that replace. An app that selects v0.1.16 without already selecting summercms v0.5.2 does not compile. sm-oauthserver-plugin v0.1.4 happens to require v0.5.2, so the full stack builds only because of that other module.
|
||||
|
||||
**Fix:** Require `git.golem15.com/golem15/summercms v0.5.2` in sm-user-plugin and drop the sibling replace from the release commit. A local replace can stay uncommitted in a development checkout.
|
||||
|
||||
### WR-06: `/connect` can allow a stale request after `?request=` changes
|
||||
|
||||
**File:** `vue-oauth-layer/app/pages/connect.vue:52-68`
|
||||
|
||||
**Issue:** `load` has no generation token. `watch(requestId)` starts another `load` while the previous `$fetch` is in flight, and `consent_required === false` posts allow before render. Whichever response arrives last assigns `show` and, if that body does not require consent, calls `submit('allow')` for the request it loaded, which may no longer be `requestId`. Both requests can be approved, and the browser can be sent to the redirect of the one the user is no longer on.
|
||||
|
||||
**Fix:** Capture a sequence number (or the request id) before the fetch and ignore the response, including the auto-allow, when it is no longer current.
|
||||
|
||||
```ts
|
||||
let loadSeq = 0
|
||||
async function load(fromRefetch = false) {
|
||||
const seq = ++loadSeq
|
||||
const id = requestId.value
|
||||
// ...
|
||||
const body = await $fetch<ConsentShow>(consentUrl(), { credentials: 'include' })
|
||||
if (seq !== loadSeq || id !== requestId.value) return
|
||||
// assign show and maybe submit
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_Reviewed: 2026-10-28T15:58:24Z_
|
||||
_Reviewer: Claude (msd-code-reviewer)_
|
||||
_Depth: standard_
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
phase: "32.1"
|
||||
slug: "mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con"
|
||||
status: verified
|
||||
# threats_open = count of OPEN threats at or above workflow.security_block_on severity (the blocking gate)
|
||||
threats_open: 0
|
||||
asvs_level: 1
|
||||
created: "2026-11-05"
|
||||
---
|
||||
|
||||
# Phase 32.1 — Security
|
||||
|
||||
> Per-phase security contract: threat register, accepted risks, and audit trail. Evidence paths: F = `summercms.go`, U = `sm-user-plugin`, O = `sm-oauthserver-plugin`, V = `vue-oauth-layer`, S = `sm-summercmsio-app` (all under `../`). Baseline for "unchanged" claims: `2cea312`, the commit before the phase.
|
||||
|
||||
---
|
||||
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description | Data Crossing |
|
||||
|----------|-------------|---------------|
|
||||
| MCP client to wristband authorize | Untrusted scope string and redirect cross here; the phase only changes which names are legal | scope string, redirect URI, PKCE challenge (high) |
|
||||
| pier dispatch to route handler | the handler gets an MCPCall built from the resolved subject, not from tool arguments | subject, client id, token id (high) |
|
||||
| OAuth grant scopes to MCPAllows / user.scope | the grant is the consented set; Implies may add only names the plugin marked | granted scopes (high) |
|
||||
| DELETE /oauth/authorizations/{client_id} | a signed-in user names a client; another user's rows must stay | client id, user session (high) |
|
||||
| Operator config `mcp_scopes` | names enter metadata and the allow-list at boot | scope names (medium) |
|
||||
| MCP consent JSON to the browser | client name, labels and admin name are attacker-influenced (DCR name, phrase text) | display strings (medium) |
|
||||
| Page POST back to the consent route | the browser can omit fields; the server intersection is the control | decision, scopes, backend_admin (high) |
|
||||
| Test output and changelog notes | tokens and authorization codes must not reach logs or the public post | test output, release notes (medium) |
|
||||
| git push of a release tag | the tag is what other repositories require | tag (low) |
|
||||
|
||||
---
|
||||
|
||||
## Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation | Status |
|
||||
|-----------|----------|-----------|----------|-------------|------------|--------|
|
||||
| T-32.1-01 | Elevation of privilege | wristband resolvedScopes | high | mitigate | F/modules/wristband/server.go:203 `mcpEmptyScopes` (five names incl. backend); :210-218 never widens a non-empty list; used by metadata :194 and authorize.go:29. `DefaultOptions` and OIDC discovery unchanged | closed |
|
||||
| T-32.1-02 | Elevation of privilege | pier filter.go read/write ceiling | high | mitigate | filter.go and identity.go unchanged since baseline; ceiling identity.go:80-82 `writes()` used at filter.go:66,:75; no `Implies` reference in pier, bouncer or wristband | closed |
|
||||
| T-32.1-03 | Spoofing | wristband Authorize redirect | high | mitigate | 63d05e8 touched only `allowedAuthorizeScopes`; authorize.go order: client lookup :62-82, exact redirect :84-88, PKCE :95-108, scope parse :110 | closed |
|
||||
| T-32.1-04 | Information disclosure | pact.MCPCall.Subject.TokenID | medium | mitigate | TokenID rule in pact/README.md:170, pier/README.md:13 and docs; dispatch.go:211-215 adds no log line; subject from `id.subjectFor` :172; audit.go unchanged | closed |
|
||||
| T-32.1-05 | Elevation of privilege | MCPUserGuard Implies helper | high | mitigate | U/classes/mcp_guard.go:160-175 `mcpEffectiveScopes`: personal tokens unchanged, clone only, read/write Implies only, exact stock scope required, no write-back; both call sites (:94, :145); `CompileAPITokenScopes` rejects backend/offline_access and bad Implies (api_token_scopes.go:139,:148). Residual: WR-01, WR-02 | closed |
|
||||
| T-32.1-06 | Elevation of privilege | MCP consent upsert | high | mitigate | O/controllers/mcp_consent_api.go: deny → `DenyPending` (:180-183); silent re-grant → `TouchConsent` (:355-358); decision → `replaceMCPConsent` ON CONFLICT sets scopes (:382-389), replace not union. Test `TestMCPConsentReplace`. Residual: WR-03, WR-04 (CR-01 fixed in 21f5985) | closed |
|
||||
| T-32.1-07 | Elevation of privilege | authorizations.revoke | high | mitigate | O/controllers/authorizations.go:137-163: `LockUserGrants` advisory lock in-tx before deletes of consent, codes and tokens; `MCPSubjectRevoked` after commit. Test `TestMCPRevokeDeletesCode`. CR-01 fixed in 21f5985: the MCP allow takes the same lock | closed |
|
||||
| T-32.1-08 | Information disclosure | PendingRequest / IssueCode | high | mitigate | F/modules/wristband/consent.go:139-174 `lookupOwnedPending` unchanged, all misses → `ErrPendingNotFound` → 404. Plugin's `mcpPendingClientID` (mcp_consent_api.go:322-332) looks up by request id alone but both callers run it after the owner-checked `PendingRequest` | closed |
|
||||
| T-32.1-09 | Tampering | grantedScopes when scopes is absent | medium | mitigate | mcp_consent_api.go:247-250 absent scopes = requested set; offline override only when present (:224-226); request struct takes decision, scopes, backend_admin only | closed |
|
||||
| T-32.1-10 | Information disclosure | consent and revoke logs | medium | mitigate | phase diff `df2eddd..a7743e7` adds no log line in plugin non-test code; error-code sets unchanged | closed |
|
||||
| T-32.1-11 | Tampering | app/pages/connect.vue | high | mitigate | no `v-html`/innerHTML in V/app/; connect.vue uses text interpolation and attribute bindings; V/tests/connect.test.ts:107-109 asserts no `v-html`. Residual: WR-06 | closed |
|
||||
| T-32.1-12 | Elevation of privilege | read checkbox | low | accept | AR-32.1-01 | closed |
|
||||
| T-32.1-13 | Information disclosure | tests and changelog-post.py | medium | mitigate | phase test messages print only codes, error keys, scope lists and ids; notes contain no token prefixes; S/scripts/changelog-post.py:407-411 exits without token, :318-326 refuses a world-readable token file | closed |
|
||||
| T-32.1-14 | Spoofing | release tags | low | accept | AR-32.1-02 | closed |
|
||||
|
||||
*Status: open · closed · open — below high threshold (non-blocking)*
|
||||
*Severity: critical > high > medium > low — only open threats at or above workflow.security_block_on count toward threats_open*
|
||||
*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
|
||||
|
||||
---
|
||||
|
||||
## Accepted Risks Log
|
||||
|
||||
| Risk ID | Threat Ref | Rationale | Accepted By | Date |
|
||||
|---------|------------|-----------|-------------|------|
|
||||
| AR-32.1-01 | T-32.1-12 | The read checkbox is disabled and the page's own POST includes read. A client that omits read only narrows the grant; the server must not reinsert read because the 422 smoke posts backend alone. Narrowing is not a privilege gain. `grantedScopes` does not special-case read. | 32.1-04-PLAN | 2026-11-05 |
|
||||
| AR-32.1-02 | T-32.1-14 | Tagging does not change PKCE, redirect matching or the read/write ceiling; the checkpoint is the control on publishing, not a new auth path. | 32.1-05-PLAN | 2026-11-05 |
|
||||
|
||||
*Accepted risks do not resurface in future audit runs.*
|
||||
|
||||
---
|
||||
|
||||
## Residual Risk (open review findings, outside the L1 register)
|
||||
|
||||
`32.1-REVIEW-DISPOSITION.md` lists these as `open`. The auditor confirmed each is still present in the code on 2026-11-05. They do not count toward `threats_open` at ASVS L1, but CR-01 would make T-32.1-07 a blocking open threat at L2. CR-01 has since been fixed (sm-oauthserver-plugin 21f5985).
|
||||
|
||||
| Finding | Severity | Touches | Gap |
|
||||
|---------|----------|---------|-----|
|
||||
| CR-01 | critical | T-32.1-07, T-32.1-06 | Fixed in sm-oauthserver-plugin 21f5985 (2026-11-05, unreleased): `MCPConsentDecide` issues the code and writes the consent in one transaction under `classes.WithinUserGrantsLock` (exclusive `LockUserGrants`, the lock revoke takes); a failed consent write rolls the code back. Tests `TestMCPConsentAllowSerializesWithRevoke`, `TestMCPConsentFailureRollsBackCode`. |
|
||||
| CR-01 sibling (OIDC) | high | T-32.1-07 | Fixed in sm-oauthserver-plugin 7b9899f (2026-11-05, unreleased): the OIDC decide was already consistent (consent upsert and code in one transaction, ordered against revoke by the consent row lock; pinned by `TestOIDCConsentAllowThenRevoke`), but a silent resume could issue a code after a revoke, a refresh rotation's successor tokens survived a revoke and a code exchange could deadlock with one. The OIDC store now takes the user's grants lock (shared) before its first grant row. Tests `TestOIDCResumeSerializesWithRevoke`, `TestOIDCRefreshSerializesWithRevoke`, `TestOIDCExchangeSerializesWithRevoke`. |
|
||||
| WR-01, WR-02 | warning | T-32.1-05 | `mcpEffectiveScopes` re-implies a declared scope the user cleared on /connect while read/write remains, and does not intersect the catalog with `golem15.oauthserver.mcp_scopes`. |
|
||||
| WR-04 | warning | T-32.1-06 | narrowing a consent does not revoke refresh tokens carrying the removed scopes or offline_access. |
|
||||
| WR-03 | warning | T-32.1-06 | the consent backfill seeds from tokens the verifier would refuse (nil-expiry, inactive/revoked clients, rotated refresh tokens). |
|
||||
| WR-06 | warning | T-32.1-11 | /connect `load()` has no generation guard; a stale `consent_required:false` can auto-allow a request the user no longer views. |
|
||||
|
||||
---
|
||||
|
||||
## Security Audit Trail
|
||||
|
||||
| Audit Date | Threats Total | Closed | Open | Run By |
|
||||
|------------|---------------|--------|------|--------|
|
||||
| 2026-11-05 | 14 | 14 | 0 | msd-security-auditor (ASVS L1, block_on high) |
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
|
||||
- [x] All threats have a disposition (mitigate / accept / transfer)
|
||||
- [x] Accepted risks documented in Accepted Risks Log
|
||||
- [x] `threats_open: 0` confirmed
|
||||
- [x] `status: verified` set in frontmatter
|
||||
- [x] CR-01 given a disposition in 32.1-REVIEW-DISPOSITION.md (fixed: sm-oauthserver-plugin 21f5985)
|
||||
|
||||
**Approval:** verified 2026-11-05 (ASVS L1; CR-01 fixed in sm-oauthserver-plugin 21f5985, unreleased)
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
phase: "32.1"
|
||||
slug: "mcp-oauth-for-plugin-apps-declared-scopes-mcp-subject-on-con"
|
||||
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
|
||||
# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
|
||||
status: draft
|
||||
nyquist_compliant: false
|
||||
wave_0_complete: false
|
||||
created: "2026-10-28"
|
||||
---
|
||||
|
||||
# Phase 32.1 — Validation Strategy
|
||||
|
||||
> Per-phase validation contract for feedback sampling during execution.
|
||||
> Seeded from `32.1-RESEARCH.md` § Validation Architecture. No REQ-IDs are mapped; rows use success criteria SC-1..SC-4.
|
||||
|
||||
---
|
||||
|
||||
## Test Infrastructure
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Framework** | Go `testing` (stdlib). Plugins use testcontainers-go v0.44.0 off `-short`. vue-oauth-layer uses `node --test`. |
|
||||
| **Config file** | none — Go has no repo-level test config. Layer: `package.json` script `test`, copied from vue-menu-layer. |
|
||||
| **Quick run command** | `go test -short ./modules/pact ./modules/pier ./modules/wristband ./modules/bouncer` |
|
||||
| **Full suite command** | `go test -short ./...` in this repo; `go test ./...` in each plugin repo (Docker); `pnpm test` in vue-oauth-layer |
|
||||
| **Estimated runtime** | ~60 seconds for the quick command; plugin non-short tests depend on Docker |
|
||||
|
||||
---
|
||||
|
||||
## Sampling Rate
|
||||
|
||||
- **After every task commit:** `go test -short` on the packages that commit touched (`./modules/pact`, `./modules/pier`, `./modules/wristband`, or the plugin's `-short` suite), plus `go vet` on those packages.
|
||||
- **After every plan wave:** `go test -short ./...` in the repo that merged. Plugin waves that touch consent or revoke also run the non-short tests named below when Docker is up.
|
||||
- **Before `$msd-verify-work`:** Full `-short` suite in the framework repo, non-short consent/revoke/backfill tests in sm-oauthserver-plugin, `go test -short ./...` in sm-user-plugin on the v0.1.14 branch, `pnpm test` in the layer, `go test ./cmd/summer -run TestDocsTree`.
|
||||
- **Max feedback latency:** 120 seconds
|
||||
|
||||
---
|
||||
|
||||
## Per-Task Verification Map
|
||||
|
||||
| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|
||||
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
|
||||
| 32.1-01-01 | 01 | 1 | SC-1 | — | Declared scope names are advertised and unknown names are rejected; OIDC discovery scopes stay unchanged | unit | `go test -short ./modules/wristband -run 'TestMCPScopes\|TestMetadata' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 32.1-02-01 | 02 | 2 | SC-1 | — | `Implies` applies only to OAuth MCP subjects; personal tokens are not expanded | unit | `go test -short . -run 'TestMCP' -count=1` in sm-user-plugin on v0.1.14 | ❌ W0 | ⬜ pending |
|
||||
| 32.1-01-02 | 01 | 1 | SC-1 | — | pier PRM `scopes_supported` matches the published catalog | unit | `go test -short ./modules/pier -run 'TestPRM\|TestProtected' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 32.1-01-03 | 01 | 1 | SC-2 | — | `MCPCallFrom` returns the call subject on a dispatched tool and is empty on a plain request | unit | `go test -short ./modules/pier -run TestDispatch -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 32.1-03-01 | 03 | 3 | SC-3 | — | Consent replace, revoke of one client, and MCP code deletion do not touch another client | integration | `cd ../sm-oauthserver-plugin && go test -count=1 -run 'TestMCPConsent\|TestAuthorizations\|TestMCPRevocation'` | ❌ W0 | ⬜ pending |
|
||||
| 32.1-04-01 | 04 | 4 | SC-3 | — | Consent page posts scopes as JSON and does not render phrasebook strings as HTML | unit | `pnpm test` in vue-oauth-layer | ❌ W0 | ⬜ pending |
|
||||
| 32.1-05-01 | 05 | 5 | SC-4 | — | Docs identifiers resolve | unit | `go test ./cmd/summer -run TestDocsTree -count=1` | ✅ | ⬜ pending |
|
||||
|
||||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||||
|
||||
Task IDs above are placeholders until plans exist. The executor updates this map to the real task IDs.
|
||||
|
||||
---
|
||||
|
||||
## Wave 0 Requirements
|
||||
|
||||
- [ ] `modules/pact` test that `FrontendTokenScope` still composites without `Implies` and that `MCPCallFrom` is false on a bare context — SC-2 negative
|
||||
- [ ] `modules/pier` PRM test with and without `MCPAdvertisedScopes` — SC-1
|
||||
- [ ] `modules/pier` dispatch test that the context carries `MCPCall` for a frontend tool and a backend tool — SC-2
|
||||
- [ ] sm-user-plugin `mcp_guard_test.go` cases for `Implies`, written against v0.1.14 — SC-1
|
||||
- [ ] sm-oauthserver-plugin consent upsert, replace-not-merge, offline_access flag, revoke-deletes-MCP-code, backfill idempotence — SC-3
|
||||
- [ ] `authorizations_smoke_test.go` key list includes `kind` — SC-3
|
||||
- [ ] vue-oauth-layer `tests/connect.test.ts` — page mapping
|
||||
- [ ] Framework install: none. Layer: `pnpm install` in the new repo once `package.json` exists
|
||||
|
||||
Existing wristband and pier test infrastructure hosts the new cases. No new test dependency.
|
||||
|
||||
---
|
||||
|
||||
## Manual-Only Verifications
|
||||
|
||||
| Behavior | Requirement | Why Manual | Test Instructions |
|
||||
|----------|-------------|------------|-------------------|
|
||||
| Patch tags of the framework and `sm-oauthserver-plugin`, and the changelog post | SC-4 | Tagging and publishing need an explicit user go-ahead and are not plan steps | After the code lands, ask before `git tag` or `scripts/changelog-post.py publish` |
|
||||
|
||||
All other phase behaviors have automated verification.
|
||||
|
||||
---
|
||||
|
||||
## Validation Sign-Off
|
||||
|
||||
- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
|
||||
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
|
||||
- [ ] Wave 0 covers all MISSING references
|
||||
- [ ] No watch-mode flags
|
||||
- [ ] Feedback latency < 120s
|
||||
- [ ] `nyquist_compliant: true` set in frontmatter
|
||||
|
||||
**Approval:** pending
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user