From ee0bbc27f8be6e8850766cd175e4ade6cae949d3 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 13:15:24 +0100 Subject: [PATCH] docs(31): record planned phase and patterns --- .planning/STATE.md | 10 +- .../31-PATTERNS.md | 1490 +++++++++++++++++ .planning/state.json | 44 +- 3 files changed, 1532 insertions(+), 12 deletions(-) create mode 100644 .planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 2e036f9f..a2db037d 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -1,14 +1,14 @@ --- msd_state_version: "1.0" milestone: v1.0 -current_phase: 35 -current_phase_name: Mail templates and layouts editor +current_phase: 31 +current_phase_name: Chat polish against WavePath clients status: executing stopped_at: Completed 35-02-PLAN.md -last_updated: "2026-11-13T12:05:49.081Z" +last_updated: "2026-11-13T12:15:09.412Z" last_activity: 2026-11-13 last_activity_desc: Phase 35 execution resumed (wave continue) -state_head: 399ba5fb60c907dd0e3f48a111145ac698385d92 +state_head: 52204e171d71d7e520adf153ff36ce934a0501e4 progress: total_phases: 52 completed_phases: 37 @@ -29,7 +29,7 @@ See: .planning/PROJECT.md (updated 2026-10-22) ## Current Position -Phase: 35 (Mail templates and layouts editor) — EXECUTING +Phase: 31 (Chat polish against WavePath clients) — READY TO EXECUTE Plan: 3 of 4 Status: Ready to execute Last activity: 2026-11-13 — Phase 35 execution resumed (wave continue) diff --git a/.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md b/.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md new file mode 100644 index 00000000..365bb072 --- /dev/null +++ b/.planning/phases/31-chat-polish-against-wavepath-clients/31-PATTERNS.md @@ -0,0 +1,1490 @@ +# Phase 31: Chat polish against WavePath clients - Pattern Map + +**Mapped:** 2026-11-13 +**Files analyzed:** 46 new or modified files (grouped; the app plugin's handler files are listed per family) +**Analogs found:** 41 / 46 + +Scope is D-16 only: tide T-1 to T-10, the `sm-wavepath-app` skeleton and harness, recording, the foundation slice of the app plugin, the three folded todos and unit tests. Messaging, satellites, video, guests, forums and notes handlers (Phases 31.1, 31.2) are not mapped. + +Paths are relative to `/media/nvme/dev/golem15/summercms.io/summercms/` (the meta repo). `summercms.go/` is this repository. Every analog below was checked with `git ls-files` in its own repository and is tracked. `sm-bm-app/plugins/jz/bm` is a nested submodule; its files are tracked inside that submodule. + +Line numbers were read on 2026-11-13. Re-open a range before copying a value into code. + +## Findings that change the plan + +These came out of reading the analogs and settle four items the research left as `[ASSUMED]` or open. + +| # | Finding | Evidence | Consequence | +|---|---------|----------|-------------| +| F-1 | **Research A7 is true.** surf bucket names are global; a second registration is a boot error. | `summercms.go/modules/surf/limiter.go:84-86`: `return fmt.Errorf("surf: bucket %q already registered by %s", name, existing)` | The app plugin cannot declare `community-join` (owned by `sm-userfriends-plugin/routes.go:22`) or `call-link` (sm-chatvideo-plugin). Reference the plugins' buckets by name (`"throttle:"+userfriends.JoinBucket`) or register app-prefixed names. Both existing buckets are 10/min, the PHP value. | +| F-2 | **Research A8 is true, and the group alias already exists.** `Registry.Add` refuses a duplicate alias, and sm-userfriends-plugin already adds `friendgroup` with the PHP class string. | `sm-chat-plugin/contracts/registry.go:74-76`; `sm-userfriends-plugin/classes/friends_context_adapter.go:19-23, 41-47` | The app plugin must not `reg.Add` a group alias. It uses `userfriendsclasses.FriendGroupAlias`. Only the channel alias (`chanmodels.ChannelAlias`) is added by the host, as the demo does. | +| F-3 | A lighthouse namespace registered twice is an error. `wave` is free. The authorizer receives the full channel including a `presence:` prefix. | `summercms.go/modules/lighthouse/registry.go:36-39, 80-82` | One `Register("wave", …)` call. How lighthouse picks the namespace of `presence:wave:group:{id}` was not read (`modules/lighthouse/channel.go:156`); the planner's executor reads it before writing the presence authorizer. The chat authorizer strips one `presence:` prefix itself (`sm-chat-plugin/classes/authorizer.go:17-20`). | +| F-4 | fonoteka's `TestMain` scans `os.Args` for `-test.short`, the form CLAUDE.md forbids. | `fonoteka.go/parity/synthetic_test.go:57-64` | Copy the container start from fonoteka but the `TestMain` shape from `sm-demo-app/testmain_test.go:17-30`. | +| F-5 | fonoteka's `parity/fixtureplugin` is a DATA-11 callback fixture (66 lines), not the scenario seeder. The seeder is `parity/fonoteka_seed_test.go`. | `fonoteka.go/parity/fixtureplugin/plugin.go:24-45` | D-04 asks for a fixture plugin that seeds. Take the plugin shell from `fixtureplugin`, the seeding style from `fonoteka_seed_test.go`. | +| F-6 | `php_parity.sh` and `fonoteka_reset.php` are SQLite-specific (`sqlite_sequence`, `sqlite3 -readonly`). | `fonoteka.go/parity/php_parity.sh:37-38, 210`; `fonoteka_reset.php:17-24` | No analog for the MariaDB container (D-20), the id floors on MariaDB (`ALTER TABLE … AUTO_INCREMENT`) or the snapshot restore per case. See "No Analog Found". | +| F-7 | `sm-user-plugin` and `sm-userfriends-plugin` have no `contracts.Rejection` type and no pre-save event. Only chat and forum have them. | `grep "type Rejection"` returns `sm-chat-plugin/contracts/rejection.go:11` and `sm-forum-plugin/contracts/rejection.go:12` only | The two new seams each add an event and a rejection type, copied from chat. | +| F-8 | Several tide tests pin the behaviour T-8 and T-9 change. | `modules/tide/rules_test.go:54-56` (client `browser` must fail); `modules/tide/centrifugo_test.go:45-57` (static presence answer, presence and unsubscribe not recorded) | The tide plan edits these assertions in the same commit as the change. | +| F-9 | tide parses every YAML file with `yaml.DisallowUnknownField()` and writes flows with a hand-written marshaller. | `modules/tide/fixture.go:48, 135-166`; `manifest.go:96`; `rules.go:50` | A new field (T-7 extra headers, T-10 `repeat`, T-4 credential class) is added to the struct, to `writeStep`/`writeRequest` in `fixture.go`, and to the round-trip test, or old fixtures and new ones stop loading. | + +## File Classification + +### Area 1: tide additions (`summercms.go/modules/tide/`) + +| New/Modified File | Role | Data Flow | Closest Analog | Match Quality | +|-------------------|------|-----------|----------------|---------------| +| `modules/tide/normalize.go` (T-1) | utility | transform | same file, `isDateKey` / `maskDate` | exact | +| `modules/tide/centrifugo_golden.go` (T-3) | utility | transform | same file, `normalizer.walk` | exact | +| `modules/tide/manifest.go` + `centrifugo.go` (T-2 broadcast sidecars) | service | batch, file-I/O | `modules/tide/upstream.go` (`UpstreamPath`, `LoadUpstream`, `WriteUpstream`) | role-match | +| `modules/tide/upstream.go` (T-4 minted credentials, T-5 body comparer) | service | request-response | same file, `fullyMasked`, `UpstreamFake.compare` | exact | +| `modules/tide/variables.go` (T-6 `response.cookie`) | utility | transform | same file, `extractCapture` | exact | +| `modules/tide/record.go` + `diff.go` (T-7 extra headers) | utility | request-response | same files, `recordedHeaderNames`, `extraCompareHeaders`, `Step.Headers` | exact | +| `modules/tide/rules.go` (T-8 client label) | config | transform | same file, `validateRules` | exact | +| `modules/tide/centrifugo.go` (T-9 unsubscribe, presence script) | service | event-driven | same file, `CentrifugoRecorder.ServeHTTP` | exact | +| `modules/tide/flow.go` + `fixture.go` + `manifest.go` (T-10 `repeat`) | model | batch | same files, `Step`, `RouteCase`, `recordRoute` | exact | +| `cmd/summer/parity.go` (flags for T-2, T-9) | controller (CLI) | request-response | same file, `parityRecordCommand` | exact | +| `modules/tide/README.md` | docs | — | same file, "API reference" table | exact | +| `docs/services/parity-testing.md` | docs | — | same file, sections "Broadcast goldens", "Upstream exchanges" | exact | +| `modules/tide/*_test.go` (one per addition) | test | — | `normalize_phase13_test.go`, `centrifugo_test.go`, `upstream_test.go`, `rules_test.go` | exact | + +### Area 2: `sm-wavepath-app` skeleton and harness (new repo) + +| New File | Role | Data Flow | Closest Analog | Match Quality | +|----------|------|-----------|----------------|---------------| +| `summer.yaml` | config | — | `sm-demo-app/summer.yaml` | exact | +| `go.mod`, `go.work` | config | — | `sm-demo-app/go.mod`, `sm-demo-app/go.work` | exact | +| `.gitmodules` | config | — | `sm-demo-app/.gitmodules` | exact | +| `app/app.go` (`Handler`, `PluginIDs`) | provider | request-response | `fonoteka.go/app/app.go` | exact | +| `parity/manifest.yaml` | config | batch | `fonoteka.go/parity/manifest.yaml` | exact | +| `parity/fixtures/seed/bootstrap.yaml` | config | batch | `fonoteka.go/parity/fixtures/seed/bootstrap.yaml` | role-match (D-21: no login step) | +| `parity/php_parity.sh` | utility (script) | file-I/O | `fonoteka.go/parity/php_parity.sh` | role-match (SQLite there, MariaDB here) | +| `parity/wavepath_reset.php` | migration (seeder) | CRUD | `fonoteka.go/parity/fonoteka_reset.php` | role-match | +| `parity/fixtureplugin/plugin.go` | provider | CRUD | `fonoteka.go/parity/fixtureplugin/plugin.go` (shell) + `fonoteka.go/parity/fonoteka_seed_test.go` (seeding) | role-match | +| `scripts/parity-stack.sh` | utility (script) | event-driven | `fonoteka.go/scripts/dev-stack.sh` | role-match | +| `parity/check_corpus.go` | utility | batch, file-I/O | `fonoteka.go/parity/check_corpus.go` | exact | +| `parity/routes.snapshot` | config | — | `fonoteka.go/parity/routes.snapshot` | exact | +| `scripts/check-parity.sh` (gate) | utility (script) | batch | `summercms.go/scripts/check-phase19.1.sh` (fail-closed stages) + `sm-demo-app/scripts/check-all.sh` (sibling repo steps) | role-match | +| `parity/accepted-differences.yaml` | config | — | `sm-oauthserver-plugin/testdata/parity/deviations.yaml` | role-match | +| `parity/README.md` | docs | — | `fonoteka.go/parity/README.md` | exact | + +### Area 3: recording + +| New File | Role | Data Flow | Closest Analog | Match Quality | +|----------|------|-----------|----------------|---------------| +| `parity/capture-rules.yaml` | config | transform | `fonoteka.go/parity/capture-rules.yaml` | exact | +| `parity/capture_clients.mjs` | utility (script) | event-driven | `fonoteka.go/parity/capture_clients.mjs` | role-match (SPA + bot, no MCP) | +| `parity/fixtures/routes/*.yaml` spec flows | config | batch | `sm-oauthserver-plugin/testdata/parity/flows/discovery.yaml` (requests-only spec) | exact | +| `parity/fixtures/routes/*.broadcasts.yaml` | config | event-driven | `fonoteka.go/parity/fixtures/broadcasts/created.yaml` | role-match (per-case sidecar is new, T-2) | +| `parity/upstream/scripts/*.yaml` | config | request-response | `fonoteka.go/parity/upstream/scripts/discogs-release.yaml` | role-match (JSON there; protobuf and ciphertext here) | +| `parity/parity_test.go` | test | batch | `fonoteka.go/parity/parity_test.go` | exact | +| `parity/testmain_test.go` | test | — | `sm-demo-app/testmain_test.go` + `fonoteka.go/parity/synthetic_test.go:66-104` | exact | +| `parity/broadcast_test.go` | test | event-driven | `fonoteka.go/parity/broadcast_goldens_test.go` | role-match | +| `parity/upstream_replay_test.go` | test | request-response | `fonoteka.go/parity/upstream_replay_test.go` | exact | + +### Area 4: `wavepath` app plugin, foundation slice (`sm-wavepath-app/plugins/golem15/wavepath/`) + +| New File | Role | Data Flow | Closest Analog | Match Quality | +|----------|------|-----------|----------------|---------------| +| `plugin.go` | provider | — | `sm-demo-app/plugins/demo/plugin.go` | exact | +| `api/response.go` (envelope) | utility | request-response | `sm-chat-plugin/api/errors.go` | role-match (different envelope) | +| `api/actor.go` (cookie actor, gates) | middleware | request-response | `sm-userfriends-plugin/api/auth.go:49-65` + `sm-demo-app/plugins/demo/chat_api.go:113-127` | role-match | +| `buckets.go` | config | request-response | `sm-userfriends-plugin/routes.go:67-87` + `sm-demo-app/plugins/demo/routes.go:26-47` | exact | +| `routes.go` | route | request-response | `sm-userfriends-plugin/routes.go:28-65` + `sm-demo-app/plugins/demo/routes.go:59-90` | exact | +| `chat.go` (context alias, access resolvers) | provider | — | `sm-demo-app/plugins/demo/chat.go` | exact | +| `classes/context.go`, `classes/channel_access.go`, `classes/forum_access.go` | service | CRUD | `sm-demo-app/plugins/demo/classes/chat_context.go`, `forum_access.go`; `sm-bm-app/plugins/jz/bm/classes/chat_context.go` | exact | +| `classes/authorizer.go` (`wave`, presence) | middleware | pub-sub | `sm-chat-plugin/classes/authorizer.go` + `sm-chat-plugin/boot.go:64-84` | exact | +| `realtime.go` (lighthouse wiring, realtime routes) | provider | pub-sub | `sm-demo-app/plugins/demo/realtime.go` + `routes.go:81-90` + `realtime_access.go` | exact | +| `api/groups.go`, `api/members.go`, `api/invites.go`, `api/join.go` | controller | CRUD | `sm-userfriends-plugin/api/groups.go` | role-match (same service, other envelope) | +| `api/friends.go` | controller | CRUD | `sm-userfriends-plugin/api/` friends handlers (routes at `routes.go:30-36, 61`) | role-match | +| `lifecycle.go` (group created, deleted, member joined) | hook | event-driven | `sm-chatvideo-plugin/boot.go:139-175` | role-match (other event types) | +| `updates/` (host tables, user companion columns) | migration | CRUD | `fonoteka.go/parity/fixtureplugin/migrations.go` + `sm-demo-app/plugins/demo/updates/` | role-match | + +### Area 5: folded todos + +| New/Modified File | Role | Data Flow | Closest Analog | Match Quality | +|-------------------|------|-----------|----------------|---------------| +| `sm-oauthserver-plugin/testdata/parity/flows/*.yaml` (recorded in place), `seed.json`, `winter-export.jsonl`, `id_token_shape.json` | config | batch | the ten existing spec flows + `testdata/parity/README.md` runbook | exact | +| `vue-chat-layer/app/composables/useChat.ts` | store | request-response | same file, `send` (818-829), `runCommand` (1182-1206), `loadCommands` (1150-1165) | exact | +| `vue-chat-layer/tests/store.test.ts` | test | — | same file, slash cases at 409-438 | exact | +| `sm-chat-plugin/events/events.go` (filenames on `MessageSaving`) | model (event) | event-driven | same file, `MessageSaving` | exact | +| `sm-chat-plugin/classes/service.go` (fill the new field) | service | CRUD | same file, 314-320 | exact | +| `sm-userfriends-plugin/events/events.go` + `classes/group_service.go` (`GroupSaving`) | model + service | event-driven | `sm-forum-plugin/events/events.go` + `sm-forum-plugin/classes/forum_service.go:284-291` | exact | +| `sm-userfriends-plugin/contracts/rejection.go` (new) + `api/errors.go` mapping | utility | request-response | `sm-chat-plugin/contracts/rejection.go` + `sm-chat-plugin/api/errors.go:59-68` | exact | +| `sm-user-plugin/classes/events.go` + `controllers/registration.go` + `controllers/api_controller.go` (`user.Saving`) | model + controller | event-driven | `sm-user-plugin/controllers/registration.go:141-192` (Fire helpers) + chat's `MessageSaving` | role-match | +| `sm-demo-app/plugins/demo/moderation.go` | hook | event-driven | same file, `checkMessage`, `checkPost` | exact | +| `sm-demo-app/moderation_test.go` | test | — | same file, `TestDemoModeration` | exact | + +### Area 6: unit tests + +| New File | Role | Closest Analog | Match Quality | +|----------|------|----------------|---------------| +| `summercms.go/modules/tide/*_test.go` | test | see area 1 | exact | +| `sm-wavepath-app/plugins/golem15/wavepath/**/*_test.go` | test | `sm-demo-app/plugins/demo/classes/chat_context_test.go`, `sm-demo-app/plugins/demo/chatbots_test.go` | role-match | +| `sm-chat-plugin/saving_test.go` (extend), new `saving_test.go` in userfriends and user | test | `sm-chat-plugin/saving_test.go` | exact | +| `sm-wavepath-app/parity/check_corpus_test.go` | test | `fonoteka.go/parity/check_corpus_test.go` | exact | + +## Pattern Assignments + +### tide T-1: `modules/tide/normalize.go` (utility, transform) + +**Analog:** the file itself. A new mask class slots into `maskLeaf` next to the date and id branches. + +**Dispatch to extend** (lines 71-102): +```go +func maskLeaf(path string, val any, step Step, opts maskOptions, diffs *[]Diff) any { + key := lastPathKey(path) + if key == "slug" || disabledPath(step, path, key) { + return val + } + ... + if isDateKey(key) { + return maskDate(path, val, diffs) + } + if isIDKey(key) { + return maskIDValue(path, val, diffs) + } + return val +} +``` + +**Shape-checked mask to copy** (lines 112-126): a mask never hides a wrong shape; it emits a `Diff` and returns the value. +```go +func maskDate(path string, val any, diffs *[]Diff) any { + if val == nil { + return nil + } + s, ok := val.(string) + if !ok { + *diffs = append(*diffs, Diff{Path: path, Expected: "Carbon +00:00 string or null", Actual: formatValue(val)}) + return val + } + if !carbonOffsetRe.MatchString(s) { + *diffs = append(*diffs, Diff{Path: path, Expected: "Carbon +00:00", Actual: strconvQuote(s)}) + return val + } + return maskDatetime +} +``` + +**Key predicate** (lines 144-146): `isDateKey` is `strings.HasSuffix(key, "_at") || key == "checkpoint"`. T-1 adds a sibling predicate for `_human` keys (non-empty string, else a `Diff`). The per-step opt-out already works through `disabledPath` (173-184), so a route can switch the new mask off with `normalize: [{path: created_at_human, disable: true}]`. + +**Test analog:** `modules/tide/normalize_phase13_test.go:12-51`, a table of `{name, got, diff bool}` cases, package `tide` (internal), neutral names (`acme`, `export-…csv`). + +--- + +### tide T-3: `modules/tide/centrifugo_golden.go` (utility, transform) + +**Analog:** `normalizer.walk` in the same file. + +**The album-shaped rules to generalise** (lines 288-289 and 330-332): +```go +case path == "$.data.payload.created_at" && v.kind == kindString && carbonOffsetRe.MatchString(v.str): + return &onode{kind: kindString, str: "{{datetime}}"} +... +case kindString: + if strings.HasPrefix(path, "$.data.payload.album.") && strings.HasSuffix(key, "_at") && carbonOffsetRe.MatchString(v.str) { + return &onode{kind: kindString, str: "{{datetime}}"} + } +``` +T-3 widens the prefix test to any path under `$.data.payload.` Keep the id rule as it is (321-328, 333-337): an id becomes a placeholder only when it equals a captured `id:*` variable, which is why the scenario needs deterministic ids. The doc comment of `NormalizePublications` (lines 160-176) lists every rule and is updated with the code. + +**Test analog:** `normalize_phase13_test.go:53-60` (`TestNormalizeNotificationPublication`): two publications with different ids and dates normalise equal; a `Z` date and a string id stay visible. + +--- + +### tide T-2: broadcast sidecars in `modules/tide/manifest.go` and `centrifugo.go` (service, batch) + +**Analog:** upstream sidecars. The naming rule, the strict loader and the "write beside the fixture" convention already exist for vendor traffic. + +**Sidecar path rule to mirror** (`upstream.go:130-136`): +```go +// UpstreamPath maps a fixture path to its sidecar path: x.yaml becomes +// x.upstream.yaml. +func UpstreamPath(fixturePath string) string { + for _, ext := range []string{".yaml", ".yml"} { + if strings.HasSuffix(fixturePath, ext) { + return strings.TrimSuffix(fixturePath, ext) + ".upstream.yaml" +``` + +**Where the recorder attaches** (`manifest.go:382-424`, `recordRoute`): one `RecordFlow` per case, then `SaveFlow`. The sidecar is written at the same point, from `rec.Publications()` after a settle wait and `rec.Reset()` before the case. + +**Recorder lifecycle and normalisation to reuse** (`centrifugo.go:229-236, 260-285`): +```go +rec := NewCentrifugoRecorder(CentrifugoRecorderOptions{APIKey: cfg.APIKey}) +srvCtx, cancel := context.WithCancel(ctx) +defer cancel() +errCh := make(chan error, 1) +go func() { errCh <- rec.ListenAndServe(srvCtx, listen) }() +if err := waitListening(ctx, listen, errCh); err != nil { + return BroadcastGolden{}, err +} +... +norm, err := NormalizePublications(pubs, idStore) +... +for i, p := range norm { + if strings.Contains(string(p.Body), cfg.APIKey) { + return BroadcastGolden{}, fmt.Errorf("tide: publication %d body contains the Centrifugo API key", i) + } +} +``` +Difference to `RecordBroadcasts`: it fails when nothing is published (261-263). A manifest case that writes nothing must record "no sidecar", so the empty case is not an error there. + +**Golden format** stays `BroadcastGolden` (`Version`, `Name`, `Flow`, `Publications`), read with `LoadBroadcastGolden`, written with `WriteBroadcastGolden` (README lines 131-133). + +--- + +### tide T-4, T-5: `modules/tide/upstream.go` (service, request-response) + +**Analog:** the file itself. + +**Compared headers** (lines 118-128): `Authorization` is in `UpstreamCompareHeaders`. + +**The refusal T-4 relaxes for a declared class** (lines 635-638, 655-666): +```go +for name, v := range req.Headers { + if isCredentialHeader(name) && !fullyMasked(v) { + return UpstreamSidecar{}, fmt.Errorf("tide: upstream exchange %d: %s header is not masked by a vars entry; refusing to write a live credential", i, name) + } +} +... +var credentialResidueRe = regexp.MustCompile(`^(?:[A-Za-z]+(?:\s+[A-Za-z_]+=)?)?$`) +``` +A minted credential is written as a shape placeholder; the refusal stays for everything not declared. Never weaken the default. + +**Where a body comparer hooks in** (lines 200-229, `RoundTrip`, and 252, `compare`): the fake reads the body, takes the next exchange in order, calls `f.compare(ex.Request, req, body)` and collects problems as strings. T-5 adds an optional comparer consulted inside `compare` for the body only. `NewUpstreamFake(s UpstreamSidecar, store *Store)` (line 195) is called by apps (`fonoteka.go/parity/upstream_replay_test.go:50,55`), so keep its signature and add the option as a setter or a second constructor. + +**Binary bodies already round-trip** through `binaryScalar` (lines 84-116); use it for protobuf and ciphertext answers. + +**Test analog:** `modules/tide/upstream_test.go:16-60`: a `upstreamTestSidecar()` builder, an `upstreamCall` struct with a `send` helper, host `api.example.test`. + +--- + +### tide T-6: `modules/tide/variables.go` (utility, transform) + +**Analog:** `extractCapture` (lines 265-350). Each source is one `case` returning `(string, error)` with a "missing …" error. + +```go +case "response.header": + v := headerValue(resp.Headers, rule.Name) + if v == "" { + return "", fmt.Errorf("missing response header %s", rule.Name) + } + return v, nil +``` +`response.cookie` is a new case that parses `Set-Cookie` (joined with `\n` by `filterHeaders`, `rules.go:137-141`) and returns the value of the cookie named `rule.Name`. + +**Scrubber pattern to generalise** (line 24): `cookieRe = regexp.MustCompile(`(?i)auth_token=([^;]+)`)`, tied to one cookie name. + +**Test analog:** `modules/tide/capture_test.go` (551 lines, same package). + +--- + +### tide T-7: `modules/tide/record.go` and `diff.go` (utility) + +**Fixed recorded list** (`record.go:125-140`) and **fixed compared lists** (`diff.go:35-52`): +```go +var extraCompareHeaders = []string{ + "Cache-Control", + "Pragma", + "WWW-Authenticate", + "Content-Disposition", + "Link", + "Location", +} +``` +`compareHeaders(want, got, extra map[string]string)` (`diff.go:62`) already takes a per-step `extra` map, fed from `Step.Headers` (`flow.go:35`), which `recordRoute` fills from `mergeHeaders(route.Headers, c.Headers)` (`manifest.go:406`). T-7 reuses that route and case `headers` map to name extra recorded headers; `keepResponseHeaders` (`record.go:121-123`) then needs the step. + +**Test analog:** `modules/tide/headers_test.go` (99 lines). + +--- + +### tide T-8: `modules/tide/rules.go` (config) + +**The check to relax** (lines 60-65): +```go +switch rules.Client { +case ClientNuxt, ClientMCP: +default: + return fmt.Errorf("tide: rules client must be %q or %q", ClientNuxt, ClientMCP) +} +``` +Keep the constants (apps and `fonoteka.go/parity/capture-rules.yaml:4` use `nuxt`). `proxy.go` uses the client as an output directory name, so the new rule must still reject path separators and dots. Update `rules_test.go:54-56`. + +--- + +### tide T-9: `modules/tide/centrifugo.go` (service, event-driven) + +**The handler to extend** (lines 63-101): +```go +path := strings.TrimRight(r.URL.Path, "/") +recorded := strings.HasSuffix(path, "/publish") || strings.HasSuffix(path, "/broadcast") +answered := strings.HasSuffix(path, "/presence") || strings.HasSuffix(path, "/unsubscribe") || strings.HasSuffix(path, "/info") +... +if strings.HasSuffix(path, "/presence") { + _, _ = io.WriteString(w, `{"result":{"presence":{}}}`) + return +} +``` +Both additions are options on `CentrifugoRecorderOptions` (line 40-44) so the default stays as tested. Authorization is compared in constant time and never stored (103-109); a recorded `unsubscribe` uses the same `Publication` struct. + +**Test analog:** `modules/tide/centrifugo_test.go:17-68` (`postJSON` helper, `httptest.NewServer(rec)`). + +--- + +### tide T-10: `repeat` on a step or case (model, batch) + +**Structs** (`flow.go:28-36`, `manifest.go:61-69`): +```go +type RouteCase struct { + ID string `yaml:"id"` + Identity string `yaml:"identity,omitempty"` + Status int `yaml:"status,omitempty"` + Headers map[string]string `yaml:"headers,omitempty"` + Fixture string `yaml:"fixture,omitempty"` + Request *Request `yaml:"request,omitempty"` + Capture []CaptureRule `yaml:"capture,omitempty"` +} +``` +**Execution point:** `RecordFlow`'s loop (`record.go:33-58`) and the replay loop in `replay.go`. Only the last response is kept. See F-9: add the field to `writeStep` (`fixture.go:152`). + +--- + +### tide docs: `modules/tide/README.md` and `docs/services/parity-testing.md` + +**README table row shape** (lines 100-147): one row per exported identifier, `tide.` prefixed, a one-clause description. +``` +| `tide.UpstreamFake` | Asserting `http.RoundTripper` over a sidecar: `tide.UpstreamFake.RoundTrip`, `tide.UpstreamFake.Verify`. | +``` +Every identifier named must exist (`summer docs:build --check`, `go test ./cmd/summer -run TestDocsTree`). CLI flag changes go in README "CLI commands" (line 158) and in `cmd/summer/parity.go:58-71` (`bonfire.Flag{Name, Description}`; true/false flags take the words). No application name anywhere in `summercms.go`. + +--- + +### `sm-wavepath-app/summer.yaml`, `go.mod`, `go.work`, `.gitmodules` (config) + +**Analog:** `sm-demo-app`. + +**summer.yaml** (`sm-demo-app/summer.yaml`, the eight entries this app needs, then the app plugin last): +```yaml +module: git.golem15.com/golem15/sm-demo-app +binary: demo +plugins: + - id: golem15.user + module: git.golem15.com/golem15/sm-user-plugin + - id: golem15.chat + module: git.golem15.com/golem15/sm-chat-plugin + - id: golem15.chatchannels + module: git.golem15.com/golem15/sm-chatchannels-plugin + - id: golem15.chatbots + module: git.golem15.com/golem15/sm-chatbots-plugin + - id: golem15.chatvideo + module: git.golem15.com/golem15/sm-chatvideo-plugin + - id: golem15.forum + module: git.golem15.com/golem15/sm-forum-plugin + - id: golem15.herald + module: git.golem15.com/golem15/sm-herald-plugin + - id: golem15.userfriends + module: git.golem15.com/golem15/sm-userfriends-plugin + ... + - id: golem15.demo + module: git.golem15.com/golem15/sm-demo-app/plugins/demo +``` +Order matters: the demo's wiring fails with "must be listed before" when a plugin it looks up boots later (`plugins/demo/chat.go:37, 59, 66`). + +**go.work** (`sm-demo-app/go.work`): `use` every submodule, `replace` the framework, and replace the user plugin instead of listing it under `use`: +``` +replace git.golem15.com/golem15/summercms => ../summercms.go + +replace ( + ... + git.golem15.com/golem15/sm-user-plugin => ./plugins/golem15/user +) +``` +The demo's comment explains why some modules are replaced, not used. Check whether that reason applies here before copying it. + +**.gitmodules** (`sm-demo-app/.gitmodules:1-4`): +``` +[submodule "plugins/golem15/user"] + path = plugins/golem15/user + url = git@git.golem15.com:golem15/sm-user-plugin.git + branch = master +``` +Branch names differ per plugin (`master` for user, `main` for others); read each from the demo's file. Use `ssu` for submodule management (user rule). + +**In-repo app plugin as its own module:** fonoteka's entry is `git.golem15.com/golem15/fonoteka/plugins/golem15/fonoteka` with its own `go.mod` and a `v0.0.0` require in the root `go.mod` (`fonoteka.go/go.mod:8`), listed under `use` in `go.work`. The demo's plugin (`sm-demo-app/plugins/demo`) lives in the root module instead. Research suggests the fonoteka form. + +--- + +### `sm-wavepath-app/app/app.go` (provider) + +**Analog:** `fonoteka.go/app/app.go` (55 lines). The parity suite needs an in-process handler over an existing pool. + +```go +// PluginIDs is the compiled plugin list the generated binary also activates. +var PluginIDs = []string{"golem15.user", "golem15.golem", "golem15.feedback", "golem15.fonoteka"} + +func Handler(ctx context.Context, cfg *compass.Config, pluginIDs []string, sqlDB *sql.DB) (http.Handler, error) { + ... + application := backpack.New(cfg) + gdb, err := lagoon.Use(ctx, sqlDB) + ... + if err := lagoon.Publish(application, sqlDB, gdb); err != nil { + return nil, err + } + bucket, err := attach.OpenBucket(ctx, cfg) + ... + plugins, err := party.Activate(application, pluginIDs) + if err != nil { + return nil, err + } + return surf.Assemble(application, plugins) +} +``` +Plugins are blank-imported at the top (lines 9-12). The fixture plugin is not: it is constructed in process (see below). + +--- + +### `sm-wavepath-app/parity/manifest.yaml` (config, batch) + +**Analog:** `fonoteka.go/parity/manifest.yaml:1-35`. +```yaml +version: 1 +auth_groups: + - jwt_locale + - jwt + ... +seed: + spec: seed/bootstrap.yaml + fixture: seed/bootstrap.yaml +routes: + - id: "GET /_fonoteka/api/v1/me/locale jwt_locale" + method: GET + path: "/_fonoteka/api/v1/me/locale" + auth_group: jwt_locale + status: ported + seed_hook: genres + identities: + - alice + cases: + - id: case + identity: alice + status: 200 + fixture: routes/GET___fonoteka_api_v1_me_locale_jwt_locale.yaml + request: + method: GET + path: /_fonoteka/api/v1/me/locale + headers: + Accept: application/json + Authorization: "Bearer {{jwt:alice}}" +``` +Conventions: route id is `" "`; fixture name is the id with `/` and spaces replaced (`sanitizeFile`, `check_corpus.go:717`). For this corpus the auth header is `Cookie: "token={{jwt:alice}}"` (D-21). The manifest struct has no field for freeze commits (`manifest.go:31-36`, strict parse), so D-12's commits go in `parity/README.md` and `routes.snapshot`, or tide gains a field; decide in the plan. + +--- + +### `sm-wavepath-app/parity/php_parity.sh` (script, file-I/O) + +**Analog:** `fonoteka.go/parity/php_parity.sh` (220 lines). Copy the structure whole; replace the SQLite parts. + +**Refusals first** (lines 10-33): +```bash +refuse_db() { + local base abs php_abs parity_abs + base="$(basename "$DB")" + if [[ "$base" != *parity* ]]; then + echo "refuse: database not named for parity: $DB" >&2 + exit 1 + fi +``` + +**Environment overlay as exports, never a file in the checkout** (lines 35-73): +```bash +export_env() { + refuse_db + export DB_CONNECTION=sqlite + export DB_DATABASE="$DB" + export CACHE_DRIVER=file + export SESSION_DRIVER=array + export QUEUE_CONNECTION="${QUEUE_CONNECTION:-sync}" + ... + export CENTRIFUGO_API_URL="${CENTRIFUGO_API_URL:-http://127.0.0.1:8424/api}" + export CENTRIFUGO_API_KEY="${CENTRIFUGO_API_KEY:-parity-centrifugo-api-key}" +``` +fonoteka sets `BROADCAST_DRIVER=log` and `BROADCAST_ENABLED=false` (48-49); this corpus needs `centrifugo` and `true` (research, PHP stack item 3). + +**Serve through the upstream proxy with the parity CA** (lines 130-146): +```bash +upstream_ca +export HTTPS_PROXY=http://127.0.0.1:8425 https_proxy=http://127.0.0.1:8425 +export NO_PROXY=127.0.0.1,localhost no_proxy=127.0.0.1,localhost +cd "$PHP_ROOT" +exec php -d curl.cainfo="$PARITY_UPSTREAM_CA" -d openssl.cafile="$PARITY_UPSTREAM_CA" \ + -S 127.0.0.1:8423 "$PHP_ROOT/vendor/laravel/framework/src/Illuminate/Foundation/resources/server.php" +``` +For this corpus the proxy is mandatory, not optional: with `QUEUE_CONNECTION=sync` a missing proxy would reach real push services. + +**Subcommands** (line 217): `reset|serve|serve-mail|invite-token|artisan |script [args]|rows