docs(20-01): chat family release summary

2026-10-30 18:25:54 +01:00
parent 677e30f6f5
commit 2d28c9485c
1 changed files with 214 additions and 0 deletions
--- a/.planning/phases/20-demo-instance-with-every-shared-plugin/20-01-SUMMARY.md
+++ b/.planning/phases/20-demo-instance-with-every-shared-plugin/20-01-SUMMARY.md
@@ -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.