docs(19.4.1-05): complete unit tests, phase gate and live verification plan

2026-10-20 20:11:10 +02:00
parent a8f0122041
commit 35d31569b5
1 changed files with 296 additions and 0 deletions
--- a/.planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/19.4.1-05-SUMMARY.md
+++ b/.planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/19.4.1-05-SUMMARY.md
@@ -0,0 +1,296 @@
+---
+phase: 19.4.1-early-public-demo-on-demo-summercms-io
+plan: 05
+subsystem: demo
+status: complete
+tags: [demo, tests, testcontainers, vitest, phase-gate, check-live, todos]
+
+requires:
+  - phase: 19.4.1-04
+    provides: "presentations, phone remote, quizzes and the demo's own Centrifugo, live on demo.summercms.io"
+provides:
+  - "internal/demotest: one postgres:15 container per test binary, a migrated template per plugin list, a fresh database per test with the whole demo booted on it"
+  - "Go unit and database tests for every VALIDATION row of the phase in sm-demo-app, sm-user-plugin and sm-journal-plugin"
+  - "vitest 3.2.7 in vue-demo-app with bm's library tests byte-identical and tests for journalLocale, isNewerBuild and the remote popup"
+  - "scripts/check-all.sh: the phase gate in one run, ending with check-live against https://demo.summercms.io"
+  - "smoke.sh covers every server-rendered page; deck-snapshot.cjs --expect-banner covers the client-only deck pages"
+affects: [19.4.1 verification, sm-demo-app, vue-demo-app, sm-user-plugin, sm-journal-plugin]
+
+actuals:
+  tokens: 58400   # chars/4 over the diffs: sm-demo-app 2258047..ea832fa (go.sum and the pointer excluded) 115272, vue-demo-app 92fd17f..045bcf8 (pnpm-lock.yaml excluded) 108879, user 4619, journal 1856, summercms.go 3161
+  tasks: 7
+  commits: 10     # measured per repo: sm-demo-app 6, vue-demo-app 1, sm-user-plugin 1, sm-journal-plugin 1, summercms.go 1 (git rev-list --count {base}..HEAD)
+plan_head_before: 07f2fb2   # summercms.go ledger
+plan_head_after: a8f0122    # summercms.go HEAD when this SUMMARY was written (git rev-list --count 07f2fb2..HEAD = 1)
+repo_heads:
+  sm-demo-app: "2258047..ea832fa (origin/master = ea832fa)"
+  vue-demo-app: "92fd17f..045bcf8 (origin/master = 045bcf8)"
+  sm-user-plugin: "7b9faa3..1fc0ce7 (origin/master = 1fc0ce7; checkout at ../fonoteka.go/plugins/golem15/user)"
+  sm-journal-plugin: "fe1bbc2..48d6593 (origin/main = 48d6593)"
+
+tech-stack:
+  added:
+    - "vitest@3.2.7 (npm devDependency, exact pin from the RESEARCH legitimacy audit)"
+    - "direct requirements in sm-demo-app's go.mod on testcontainers-go, golang.org/x/mod and goccy/go-yaml (already in the module graph through the plugins)"
+  patterns:
+    - "A migrated template database per plugin list, cloned for every test, instead of truncating between tests"
+    - "Copy a library's tests byte-identical and map the original layout with vitest aliases rather than editing imports"
+    - "One gate script that runs every suite, build and check in order and ends with the live check"
+
+key-files:
+  created:
+    - ../sm-demo-app/internal/demotest/postgres.go
+    - ../sm-demo-app/testmain_test.go
+    - ../sm-demo-app/go_mod_test.go
+    - ../sm-demo-app/seed_test.go
+    - ../sm-demo-app/reset_test.go
+    - ../sm-demo-app/realtime_test.go
+    - ../sm-demo-app/demo_api_test.go
+    - ../sm-demo-app/turnstile_test.go
+    - ../sm-demo-app/plugins/demo/roadmap/roadmap_test.go
+    - ../sm-demo-app/plugins/demo/console/visitor_test.go
+    - ../sm-demo-app/scripts/check-all.sh
+    - ../sm-demo-app/vue-demo-app/vitest.config.ts
+    - ../sm-demo-app/vue-demo-app/app/lib/deck/{clock,compose,engine,reading,remote,styles,themes}.test.ts
+    - ../sm-demo-app/vue-demo-app/app/lib/{realtime,pilot,markdown,remoteWindow}.test.ts
+    - ../sm-demo-app/vue-demo-app/app/lib/api/http.test.ts
+    - ../sm-demo-app/vue-demo-app/app/utils/journalLocale.test.ts
+    - ../sm-demo-app/vue-demo-app/app/utils/buildUpdate.test.ts
+    - ../fonoteka.go/plugins/golem15/user/turnstile_routes_test.go
+    - .planning/todos/done/journal-author-profile-fields.md
+  modified:
+    - ../sm-demo-app/go.mod
+    - ../sm-demo-app/go.sum
+    - ../sm-demo-app/boot_test.go
+    - ../sm-demo-app/plugins/demo/schedule_test.go
+    - ../sm-demo-app/plugins/demo/content/ROADMAP.md
+    - ../sm-demo-app/scripts/check-live.sh
+    - ../sm-demo-app/scripts/smoke.sh
+    - ../sm-demo-app/scripts/deck-snapshot.cjs
+    - ../sm-demo-app/scripts/dev.sh
+    - ../sm-demo-app/README.md
+    - ../sm-demo-app/DEPLOY.md
+    - ../sm-demo-app/vue-demo-app/package.json
+    - ../sm-demo-app/vue-demo-app/pnpm-lock.yaml
+    - ../sm-demo-app/vue-demo-app/README.md
+    - ../sm-journal-plugin/journal_api_authors_test.go
+    - .planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md
+
+key-decisions:
+  - "The demo's database tests boot the whole app on a fresh database cloned from a migrated template per plugin list; one postgres:15 container serves the test binary."
+  - "bm's frontend library tests are copied byte-identical; vitest aliases map bm's @/api, @/deck and ../../deck/ imports onto the demo's layout, so no assertion was adapted."
+  - "check-all.sh runs the local browser checks (check-local back remote) when the local dev stack is up and skips them with a note otherwise; --local makes them required."
+  - "The test-only plugin commits got no tag; the demo keeps requiring the plugins' existing tags, and fonoteka.go's pointer to the user plugin was not bumped."
+
+requirements-completed: [SC-1, SC-2, SC-3, SC-4, SC-5, D-01, D-03, D-05, D-06, D-07, D-09, D-10, D-13, D-15, D-16, D-17, D-18, D-19, D-20, D-22, D-23]
+
+coverage:
+  - id: D1
+    description: "go.mod requires only tags, no replace, every summer.yaml plugin required"
+    requirement: SC-1
+    verification:
+      - kind: unit
+        ref: "TestGoModRequiresTags (sm-demo-app); build.sh release; check-pins.sh (14 modules)"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "Live deploy valid and reachable, admin path refused"
+    requirement: SC-2
+    verification:
+      - kind: e2e
+        ref: "check-deploy.sh ok; check-live.sh https://demo.summercms.io ok (no admin link on any fetched page, banner, test card)"
+        status: pass
+    human_judgment: true
+    rationale: "DNS and certbot were confirmed by the user in plan 02"
+  - id: D3
+    description: "Accounts, visitor, reset job, banner"
+    requirement: SC-3
+    verification:
+      - kind: unit
+        ref: "TestTurnstileRoutes, TestDemoTurnstile, TestSeedVisitorFromConfig, TestResetSchedule"
+        status: pass
+      - kind: integration
+        ref: "TestResetKeepsPlans; smoke.sh banner loop over nine routes; deck-snapshot --expect-banner"
+        status: pass
+    human_judgment: true
+    rationale: "The Stripe test checkout with the visitor was approved by the user at plan 02 Task 7"
+  - id: D4
+    description: "Roadmap decks, EN/PL seed, realtime, quizzes, journal author, ported libraries"
+    requirement: SC-4
+    verification:
+      - kind: unit
+        ref: "TestRoadmapParse, TestRoadmapDeckOrder, TestRoadmapNoClientNames, TestRoadmapPolishTitles, TestRealtime* (4), TestDemoQuizList, TestJournalAuthorProfile, TestBootAllPlugins, vitest 178 tests"
+        status: pass
+      - kind: integration
+        ref: "TestSeedRoadmapUpsert, TestSeedLocales, TestDemoDeckWrites"
+        status: pass
+    human_judgment: true
+    rationale: "The phone remote driving the speaker view was approved at plan 04 Task 7; the OIDC screenshots were stepped through in plans 01 and 04"
+  - id: D5
+    description: "The phase gate passes in one run, including the live check"
+    requirement: SC-5
+    verification:
+      - kind: e2e
+        ref: "scripts/check-all.sh: check-all: ok"
+        status: pass
+    human_judgment: false
+
+duration: ~1h10m wall clock (19:00 to the SUMMARY at about 20:10 +02:00, including the Task 6 go-ahead)
+completed: 2026-10-20
+---
+
+# Phase 19.4.1 Plan 05: Unit tests, phase gate and live verification Summary
+
+**Every behaviour row of 19.4.1-VALIDATION.md now has a passing test under the name it lists, all in one shared Postgres harness that boots the whole demo. bm's eleven frontend library tests run byte-identical under vitest 3.2.7 next to the demo's own tests. One script, `scripts/check-all.sh`, runs every suite, the release build, the pin, deploy and smoke checks and the live check of https://demo.summercms.io, and it ends with `check-all: ok`. The test commits are pushed to all four repositories without tags.**
+
+## Performance
+
+- **Duration:** about 1h10m wall clock, including the Task 6 go-ahead
+- **Started:** 2026-10-20T17:00Z
+- **Completed:** 2026-10-20T18:10Z
+- **Tasks:** 7/7
+- **Files modified:** 46 (24 in sm-demo-app including the vue-demo-app pointer, 18 in vue-demo-app, 1 in sm-user-plugin, 1 in sm-journal-plugin, 2 in summercms.go)
+
+## Accomplishments
+
+- **Database harness.** `internal/demotest` starts one postgres:15 container per test binary (the major version rome runs). It migrates a template database once per plugin list and clones a fresh database from it for every test, and the whole demo boots on that database as the generated main.go boots it. `TestMain` calls `flag.Parse()` and starts the container only when `!testing.Short()`, so `go test -short` passes without Docker.
+- **Go tests (sm-demo-app).** `TestGoModRequiresTags`, `TestSeedRoadmapUpsert`, `TestSeedLocales`, `TestResetKeepsPlans`, `TestDemoQuizList`, `TestDemoDeckWrites`, `TestDemoTurnstile` (a fake siteverify through `bouncer.Turnstile.Endpoint`), the four realtime tests ported from bm, `TestBootAllPlugins` (extended) and `TestAdminLoginThrottle` in the root package. `TestRoadmapParse`, `TestRoadmapDeckOrder`, `TestRoadmapNoClientNames` and `TestRoadmapPolishTitles` are in plugins/demo/roadmap, `TestSeedVisitorFromConfig` is in plugins/demo/console and `TestResetSchedule` is in plugins/demo.
+- **Shared plugin tests.** `TestTurnstileRoutes` in sm-user-plugin covers each value of the key: empty, open, closed, space-padded closed and invalid. `TestJournalAuthorProfile` in sm-journal-plugin now covers a user with only a subtitle and metadata that is empty, null, not JSON or not strings. Both commits change tests only.
+- **vitest.** `vitest@3.2.7` (exact) is the `test` script, run in the Node environment over `app/**/*.test.ts`. bm's deck (7), realtime, pilot, markdown and http tests are byte-identical to `sm-bm-app/frontend/src`. The demo's own tests are `journalLocale.test.ts`, `buildUpdate.test.ts` and `remoteWindow.test.ts`. Result: 14 files and 178 tests passed, none skipped.
+- **Page checks.** `smoke.sh` checks every server-rendered page (/, /blog, a post, /faq, /subscriptions, /register, /login, /contact, /quizzes) for the banner, the test card and the backend call to action. It also fails if a page shows the admin path or the visitor password. `deck-snapshot.cjs --expect-banner` checks the compact banner on the client-only deck pages, and `dev.sh snapshot --site` passes the flag.
+- **Phase gate.** `scripts/check-all.sh` runs go vet and go test without -short, the user and journal plugin suites, vitest, `sync-roadmap.sh --check`, `check-pins.sh`, `build.sh release`, `smoke.sh` and `check-deploy.sh`. It then runs the local browser checks and finally `check-live.sh https://demo.summercms.io`. `check-live.sh` now also checks the test card and the backend call to action on /, the banner on /blog and /faq, and that no page it fetches links to /smbackend or /backend.
+- **Docs and todos.** README.md and DEPLOY.md describe the suites, the harness and the gate, and the steps not yet run on rome are marked as such (the teardown and the manual reset). journal-author-profile-fields moved to todos/done. The reload-on-deploy todo stays pending with a "Progress (Phase 19.4.1)" note: the site half shipped, and the admin half (boardwalk) still needs a framework tag.
+
+## Tests per VALIDATION row
+
+| Criterion | Behaviour | Test | Status |
+|-----------|-----------|------|--------|
+| SC1 | go.mod requires only tags, no replace | TestGoModRequiresTags | pass |
+| SC1 | Release builds without go.work | build.sh release (build 795ab5666f0e) | pass |
+| SC1 | Submodules equal their tags | check-pins.sh (14 modules) | pass |
+| SC2 | nginx/supervisor/Centrifugo config valid, /backend refused | check-deploy.sh | pass |
+| SC2 | Live 200 /, 404 /backend, journal API 200, HSTS | check-live.sh https://demo.summercms.io | pass |
+| SC3 | Turnstile on register/login only when configured | TestTurnstileRoutes (sm-user-plugin); TestDemoTurnstile (end to end) | pass |
+| SC3 | Visitor credentials only from config | TestSeedVisitorFromConfig | pass |
+| SC3 | Reset schedule off by default | TestResetSchedule | pass |
+| SC3 | Reset wipes and reseeds, keeps plans and admins | TestResetKeepsPlans (root package, which compiles every plugin in) | pass |
+| SC3 | Demo banner on every page | smoke.sh (nine server-rendered routes), deck-snapshot --expect-banner, check-live | pass |
+| SC4 | ROADMAP parse and client-name denylist | TestRoadmapParse, TestRoadmapDeckOrder, TestRoadmapNoClientNames, TestRoadmapPolishTitles | pass |
+| SC4 | Roadmap deck upsert keeps public_hash; pxpx slide | TestSeedRoadmapUpsert, TestRoadmapPolishTitles | pass |
+| SC4 | EN/PL seed rows | TestSeedLocales | pass |
+| SC4 | Realtime routes (port of bm) | TestRealtimeDefaultDriver, TestRealtimeRoutes, TestRealtimeConfigDefaults, TestRemoteKeyOverride | pass |
+| SC4 | Ported deck/remote/realtime libs | vitest: bm's 11 tests byte-identical | pass |
+| SC4 | Anonymous quiz list; attempts need JWT | TestDemoQuizList, TestBootAllPlugins | pass |
+| SC4 | Journal author profile keys | TestJournalAuthorProfile (sm-journal-plugin) | pass |
+| SC4 | All 16 plugins boot with demo routes | TestBootAllPlugins | pass |
+| Todo ltcvqext | Update banner on new deploy | buildUpdate.test.ts (isNewerBuild) | pass |
+
+No row is NOT RUN. The Docker-backed tests ran against a live daemon, and none skipped in the gate run.
+
+### Manual-only rows (confirmed by the user earlier in the phase)
+
+| Behaviour | Criterion | Outcome |
+|-----------|-----------|---------|
+| DNS, certbot certificate | SC2 | passed: confirmed in plan 02 |
+| Stripe test checkout with the seeded visitor | SC3 | passed: approved at plan 02 Task 7 |
+| Phone remote drives the speaker view | SC4 | passed: approved at plan 04 Task 7 ("everything passes"); there is no QR code, as plan 04 recorded, and phones follow My presentations' Remote link |
+| OIDC screenshots captured | SC4 | passed: stepped through in plans 01 and 04 |
+
+## Gate results (scripts/check-all.sh)
+
+go vet ok. go test for the app ok, with the root package at 11.4 s on the Docker harness. sm-user-plugin ok and sm-journal-plugin ok. vitest: 14 files and 178 tests passed. sync-roadmap ok, check-pins ok (14 modules), `build: ok release 795ab5666f0e`, smoke ok, check-deploy ok, `check-local: ok back remote` and check-live ok. The last line was **`check-all: ok`**.
+
+## Task Commits
+
+| Task | Repo | Commits |
+|------|------|---------|
+| 1. Tracer: harness, go.mod tags, roadmap upsert | sm-demo-app | fac3128 |
+| 2. Unit tests | sm-demo-app | 5cbe907 |
+| 3. Shared plugin tests | sm-user-plugin; sm-journal-plugin | 1fc0ce7; 48d6593 |
+| 4. vitest, smoke and deck banner | vue-demo-app; sm-demo-app | 045bcf8; 64f4621, 323ad61 (ROADMAP snapshot), ffbb9c2 (pointer) |
+| 5. Gate, docs, todos | sm-demo-app; summercms.go | ea832fa; a8f0122 |
+| 6. Go-ahead (decision) | - | "push" |
+| 7. Push | all four | see below |
+
+## Pushes (Task 7)
+
+These went out in dependency order after the "push" go-ahead. Before each push, `git fetch` showed that no remote head had moved.
+
+| Repo | Branch | Range pushed | Remote = HEAD |
+|------|--------|--------------|---------------|
+| sm-user-plugin (checkout ../fonoteka.go/plugins/golem15/user) | master | 7b9faa3..1fc0ce7 | yes |
+| sm-journal-plugin | main | fe1bbc2..48d6593 | yes |
+| vue-demo-app | master | 92fd17f..045bcf8 | yes |
+| sm-demo-app | master | 2258047..ea832fa | yes |
+
+No tag was pushed, and none of the four HEADs has a tag. The vue-demo-app pointer in sm-demo-app was already at 045bcf8 (ffbb9c2), so Task 7 needed no new pointer commit. fonoteka.go's pointer to the user plugin was not bumped. The Task 7 verify command passed, and `git -C ../sm-demo-app status --porcelain` is empty. There was no redeploy because the plan changed no production code. Nothing needed rome.
+
+## g15office (done by the orchestrator)
+
+The orchestrator holds the g15office tools and made these updates:
+- **esrp4qtx** (journal author profile fields): set to Live, with a one-line comment.
+- **ltcvqext** (reload open apps on deploy): a progress comment. The site half shipped in vue-demo-app, and the admin half remains.
+- **g02hcroj** (Phase 19.4.1): a comment that plans 01 to 05 are executed, and the task set to Testing.
+
+## Deviations from Plan
+
+No production code changed. The tests exposed no bug, so there was no fix commit.
+
+1. **[Rule 3] Harness shape.** `Start(ctx)` returns `(stop, err)` and keeps the DSN inside the package. `App(t, Options)` returns a `*Demo`. Each test gets a fresh database cloned from a migrated template per plugin list, instead of the planned `Reset` truncation. This gives better isolation: no test sees rows another test left behind, and no table list has to be kept for truncation.
+2. **[Rule 3] go.mod.** Direct requirements were added on testcontainers-go, golang.org/x/mod and goccy/go-yaml (for summer.yaml). All three were already in the module graph, so the project has no new dependency.
+3. **Smoke tests absorbed.** `roadmap_smoke_test.go` was replaced by the four TestRoadmap* tests. `schedule_smoke_test.go` became `schedule_test.go`, and the user plugin's `turnstile_routes_smoke_test.go` became `turnstile_routes_test.go`.
+4. **[Rule 2] TestAdminLoginThrottle added.** It pins the admin login throttle (5 attempts a minute per real client IP from X-Forwarded-For behind the trusted proxy, with another visitor not locked out) and `/backend` 404. TestBootAllPlugins also pins Turnstile on POST login and register only.
+5. **TestDemoDeckWrites covers plan 04's later behaviour.** It checks the summer theme in the theme list and the 403 on a PUT to a published deck, beyond the planned list.
+6. **[Rule 3] vitest aliases.** Beyond `@` and `~` to `app/`, the config maps `@/api/` to `app/lib/api/`, `@/deck/` and `../../deck/` to `app/assets/deck/` (bm's layout). bm's tests therefore run byte-identical, and no assertion was adapted, including for the cookie token store, the font loader and navigateTo.
+7. **quizSession.test.ts not ported.** The demo never ported `quizSession.ts`, because it has its own quiz player (plan 04 deviation 7), so bm's test has nothing to test. Eleven bm tests were ported: deck ×7, realtime, pilot, markdown and http.
+8. **[Rule 2] remoteWindow.test.ts added.** It covers plan 04's phone-sized remote popup (`openRemoteWindow`, `remoteLinkClick`): the size, the cut opener, the blocked-popup fallback and modified clicks.
+9. **TestJournalAuthorProfile goes further.** Besides the planned empty and subtitle-only cases, it covers metadata that is null, not JSON or not strings. The key set stays pinned.
+10. **smoke.sh checks more.** Beyond the banner and the admin path, every route is checked for the test card and the backend call to action, and the visitor password must not appear on any page.
+11. **check-all.sh has a browser step.** `check-local.sh back remote` runs between check-deploy and check-live when the local dev stack is up. Without it, the step is skipped with a note, and `--local` makes it required. In the gate run it ran and passed. check-live gained the checks for the test card, the backend call to action, the banner on /blog and /faq, and admin links.
+12. **[Plan 04 open item] ROADMAP snapshot re-synced** (323ad61, from summercms 07f2fb2) before the release, because build.sh release refuses a stale snapshot. The vue-demo-app pointer bump (ffbb9c2) went in the same pass.
+
+The checkpoint report's own text of these deviations was not in this continuation's context. The list above is rebuilt from the plan's commit messages, the diffs and the gate log, and it keeps the same numbering of twelve.
+
+**Impact:** tests, scripts and docs only. No shipped behaviour changed, so there is no tag and no redeploy.
+
+## Threat model update
+
+T-19.4.1-33: the tests generate their own secrets and a fake siteverify and use no production value. check-all's local browser step reads the visitor from the local environment and never prints it. T-19.4.1-34: every mitigation listed there has a pinning test (see the VALIDATION table). T-19.4.1-SC: the only npm package added is vitest@3.2.7. golang.org/x/mod, testcontainers-go and goccy/go-yaml were already in the graph.
+
+## Issues Encountered
+
+None that blocked the plan. The gate passed on its first full run.
+
+## Open items for phase verification and later
+
+- **Stale ROADMAP snapshot.** This plan's ROADMAP commit makes the embedded snapshot in sm-demo-app (`plugins/demo/content/ROADMAP.md`, synced from 07f2fb2) stale again. The next release must run `scripts/sync-roadmap.sh` and commit first, because `build.sh release` refuses a stale snapshot. The live demo is unaffected until then.
+- **Phase 20's goal is out of date.** It still says "The admin backend is not public". Since plan 03 the admin is public behind a login. The ROADMAP text should be reworded when Phase 20 is discussed or planned.
+- **gofmt in sm-journal-plugin.** `classes/blog_editor_test.go` is not gofmt-clean. That is pre-existing and outside this plan's scope.
+- From plan 04, still open: the Accounts tour card links to /register for members, and a QR code for the remote would need an approved package.
+- 19.4.1-VALIDATION.md is still `status: draft`. `/msd-validate-phase` can now map every row to the tests above.
+
+## User Setup Required
+
+None.
+
+## Next Phase Readiness
+
+All five plans are executed. Phase 19.4.1 is ready for phase verification (`/msd-verify-work`), which also marks the phase complete in ROADMAP.md.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None.
+
+## Self-Check: PASSED
+
+- sm-demo-app commits found: fac3128, 5cbe907, 64f4621, 323ad61, ffbb9c2, ea832fa; origin/master = ea832fa = HEAD.
+- vue-demo-app commit found: 045bcf8; origin/master = 045bcf8 = HEAD.
+- sm-user-plugin commit found: 1fc0ce7; origin/master = 1fc0ce7 = HEAD.
+- sm-journal-plugin commit found: 48d6593; origin/main = 48d6593 = HEAD.
+- summercms.go commit found: a8f0122.
+- Files found: internal/demotest/postgres.go, testmain_test.go, scripts/check-all.sh, vue-demo-app/vitest.config.ts, user turnstile_routes_test.go, .planning/todos/done/journal-author-profile-fields.md.
+- Gate: check-all: ok, check-live https://demo.summercms.io ok.