golem15/summercms
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(19.4.1-03): complete accounts, tour, EN/PL, journal and contact plan

Browse Source
This commit is contained in:
Jakub Zych
2026-10-20 16:32:54 +02:00
parent d04462a224
commit 4964d4d65b
1 changed files with 289 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

289
.planning/phases/19.4.1-early-public-demo-on-demo-summercms-io/19.4.1-03-SUMMARY.md Normal file
View File

@@ -0,0 +1,289 @@
---
phase: 19.4.1-early-public-demo-on-demo-summercms-io
plan: 03
subsystem: demo
status: complete
tags: [demo, turnstile, i18n, journal, feedback, g15office, reset, nuxt-manifest, plugin-tags, deploy, rome]
requires:
- phase: 19.4.1-02
provides: "the live demo on rome, module-mode release from plugin tags, DEPLOY.md, check-live.sh, the admin at /smbackend"
provides:
- "sm-user-plugin v0.1.3: opt-in golem15.user.turnstile (\"\" | open | closed, empty by default) that adds turnstile:{mode} to POST /_user/api/v1/register and /login only"
- "sm-journal-plugin v0.2.1: subtitle, description and avatar on GET /_journal/api/v1/authors/{author}"
- "demo registration and login behind Cloudflare Turnstile (turnstile: closed), with no credential shown or pre-filled"
- "the guided tour homepage (six cards, Payments/Płatności) in the summercms.io look, and the whole site in English and Polish via the locale cookie, SSR included"
- "journal posts in the active language through an app-level useJournalApi override, and SummerCMS Team author cards on posts and /blog/author/summercms-team"
- "/contact posting to the golem15.feedback API; submissions land in Admin, Feedback and as G15Office tasks; no mail"
- "demo:reset --force with a keep-list, and its schedule golem15.demo.reset.{enabled,at}, disabled by default"
- "the reload-on-deploy banner (Nuxt app manifest plus a builds/latest.json check on visibilitychange)"
- "scripts/check-local.sh [turnstile|tour|journal|contact|reset]; check-live.sh with the register, contact, Polish and token-less register checks"
affects: [19.4.1-04, 19.4.1-05, 19.5, sm-demo-app, vue-demo-app, sm-user-plugin, sm-journal-plugin]
actuals:
tokens: 44000 # chars/4 over the diffs: sm-demo-app c94688f..b4caccc and vue-demo-app 79e962a..dc26edf (images and lockfiles excluded), sm-user-plugin 7b9faa3, sm-journal-plugin fe1bbc2
tasks: 8
commits: 16 # measured per repo: sm-demo-app 9 (git rev-list --count c94688f..b4caccc), vue-demo-app 5 (79e962a..dc26edf), sm-user-plugin 1 (7b9faa3), sm-journal-plugin 1 (fe1bbc2)
plan_head_before: d04462a # summercms.go ledger; it carries no code commit of this plan, only this SUMMARY and the ROADMAP update
plan_head_after: d04462a # summercms.go HEAD when this SUMMARY was written (git rev-list --count d04462a..HEAD = 0)
repo_heads: # where the code commits live
sm-demo-app: "c94688f..b4caccc (origin/master = b4caccc)"
vue-demo-app: "79e962a..dc26edf (origin/master = dc26edf)"
sm-user-plugin: "7b9faa3 = v0.1.3 (origin/master = 7b9faa3)"
sm-journal-plugin: "fe1bbc2 = v0.2.1 (origin/main = fe1bbc2)"
tech-stack:
added: []
patterns:
- "Opt-in route middleware in a shared plugin: an empty config key changes nothing; an invalid value fails boot naming the key; a recording pact.Router pins which routes change"
- "@nuxtjs/i18n with strategy no_prefix and the locale in a cookie, so SSR renders the chosen language on unchanged layer routes"
- "App-level composable override (useJournalApi) that maps translations[locale] before a layer's view mappers drop the map"
- "Seed steps that only create missing rows, except named rewrites of known old seeded text"
- "Destructive demo reset: one transaction, explicit keep-list, blob deletion after commit, saved deck hashes written back"
key-files:
created:
- ../fonoteka.go/plugins/golem15/user/turnstile_routes_smoke_test.go
- ../sm-demo-app/plugins/demo/console/reset.go
- ../sm-demo-app/plugins/demo/console/seed_locales.go
- ../sm-demo-app/plugins/demo/console/seed_feedback.go
- ../sm-demo-app/plugins/demo/schedule.go
- ../sm-demo-app/plugins/demo/schedule_smoke_test.go
- ../sm-demo-app/plugins/demo/content/author/summercms-team.webp
- ../sm-demo-app/scripts/check-local.sh
- ../sm-demo-app/vue-demo-app/i18n/locales/en.json
- ../sm-demo-app/vue-demo-app/i18n/locales/pl.json
- ../sm-demo-app/vue-demo-app/app/assets/css/tokens.css
- ../sm-demo-app/vue-demo-app/app/components/SiteHeader.vue
- ../sm-demo-app/vue-demo-app/app/components/SiteFooter.vue
- ../sm-demo-app/vue-demo-app/app/components/HeroSection.vue
- ../sm-demo-app/vue-demo-app/app/components/TourCard.vue
- ../sm-demo-app/vue-demo-app/app/components/LanguageSwitcher.vue
- ../sm-demo-app/vue-demo-app/app/components/TurnstileWidget.vue
- ../sm-demo-app/vue-demo-app/app/components/UpdateBanner.vue
- ../sm-demo-app/vue-demo-app/app/components/Journal/AuthorCard.vue
- ../sm-demo-app/vue-demo-app/app/components/Journal/PostMeta.vue
- ../sm-demo-app/vue-demo-app/app/composables/useJournalApi.ts
- ../sm-demo-app/vue-demo-app/app/utils/journalLocale.ts
- ../sm-demo-app/vue-demo-app/app/utils/buildUpdate.ts
- ../sm-demo-app/vue-demo-app/app/plugins/manifest-update.client.ts
- ../sm-demo-app/vue-demo-app/app/pages/register.vue
- ../sm-demo-app/vue-demo-app/app/pages/contact.vue
modified:
- ../fonoteka.go/plugins/golem15/user/routes.go
- ../fonoteka.go/plugins/golem15/user/config/config.yaml
- ../fonoteka.go/plugins/golem15/user/README.md
- ../sm-journal-plugin/controllers/api/authors.go
- ../sm-journal-plugin/journal_api_authors_test.go
- ../sm-journal-plugin/README.md
- ../sm-demo-app/go.mod
- ../sm-demo-app/go.sum
- ../sm-demo-app/config/golem15.user.yaml
- ../sm-demo-app/plugins/demo/plugin.go
- ../sm-demo-app/plugins/demo/config/config.yaml
- ../sm-demo-app/plugins/demo/console/seed.go
- ../sm-demo-app/plugins/demo/content/content.go
- ../sm-demo-app/plugins/demo/content/ROADMAP.md
- ../sm-demo-app/scripts/dev.sh
- ../sm-demo-app/scripts/check-live.sh
- ../sm-demo-app/deploy/env.example
- ../sm-demo-app/deploy/site.env.example
- ../sm-demo-app/DEPLOY.md
- ../sm-demo-app/README.md
- ../sm-demo-app/vue-demo-app/nuxt.config.ts
- ../sm-demo-app/vue-demo-app/app/assets/css/site.css
- ../sm-demo-app/vue-demo-app/app/layouts/default.vue
- ../sm-demo-app/vue-demo-app/app/components/BackendCta.vue
- ../sm-demo-app/vue-demo-app/app/components/DemoBanner.vue
- ../sm-demo-app/vue-demo-app/app/composables/useDemoAuth.ts
- ../sm-demo-app/vue-demo-app/app/pages/index.vue
- ../sm-demo-app/vue-demo-app/app/pages/login.vue
- ../sm-demo-app/vue-demo-app/app/pages/faq.vue
- ../sm-demo-app/vue-demo-app/app/pages/subscriptions.vue
key-decisions:
- "Tags: sm-user-plugin v0.1.3 (7b9faa3) and sm-journal-plugin v0.2.1 (fe1bbc2), annotated, confirmed with ls-remote; sm-demo-app requires both. Other applications' pins were not touched. Phase 19.5 takes the next free sm-user-plugin tag after v0.1.3."
- "Turnstile is opt-in in the core user plugin: golem15.user.turnstile defaults to empty, which adds no middleware, so fonoteka, bm, grzybyfunkcjonalne and summercms.io keep their behaviour. The demo sets closed."
- "The CTA and the FAQ follow the /smbackend decision: the admin URL is public, credentials are given out on request, and no page links to /smbackend."
- "tokens.css is copied verbatim from vue-summercmsio-app 644f04e; base.css is not copied, because summercms.io is dark-only."
- "The app-level useJournalApi override took precedence over the layer's composable, so the vue-journal-layer fallback tag was not needed; vue-demo-app's layer pin is unchanged."
- "The demo:reset schedule ships disabled (golem15.demo.reset.enabled false); on rome SUMMER_GOLEM15__DEMO__RESET__ENABLED=true is absent."
requirements-completed: [SC-2, SC-3, SC-4, D-03, D-04, D-05, D-07, D-09, D-11, D-12, D-13, D-22, D-23]
coverage:
- id: D1
description: "Turnstile only on register and login, opt-in, invalid value refused"
requirement: D-07
verification:
- kind: unit
ref: "sm-user-plugin TestTurnstileRoutesSmoke (empty, closed, bogus)"
status: pass
- kind: integration
ref: "check-local.sh turnstile (422 without a token, success with the Cloudflare test token, widget container on /register)"
status: pass
human_judgment: false
- id: D2
description: "Guided tour, summercms.io look, EN/PL across UI, FAQ, menu and journal"
requirement: SC-4
verification:
- kind: integration
ref: "check-local.sh tour and journal; the en.json and pl.json key sets are equal"
status: pass
human_judgment: true
rationale: "The look and the Polish copy were judged by the user on the live site (Task 8)"
- id: D3
description: "Author payload carries subtitle, description and avatar"
requirement: "todo esrp4qtx"
verification:
- kind: integration
ref: "sm-journal-plugin TestJournalAuthorProfile; live GET /_journal/api/v1/authors/summercms-team check printed True"
status: pass
human_judgment: false
- id: D4
description: "Contact form to the feedback API, filed as a G15Office task, no mail"
requirement: D-04
verification:
- kind: integration
ref: "check-local.sh contact (allowed origin accepted with a new row, foreign origin refused)"
status: pass
- kind: e2e
ref: "live submission by the user as tester@tester.com became G15Office task ztqpldsk in project summercms"
status: pass
human_judgment: true
rationale: "G15Office delivery was confirmed by the user on the live demo"
- id: D5
description: "demo:reset keeps admins, plans and deck hashes; schedule off by default"
requirement: D-09
verification:
- kind: unit
ref: "TestResetScheduleSmoke"
status: pass
- kind: integration
ref: "check-local.sh reset; reset-enabled count 0 in rome's .env"
status: pass
human_judgment: false
- id: D6
description: "Live on demo.summercms.io from the tagged plugins"
requirement: SC-3
verification:
- kind: e2e
ref: "check-pins.sh; scripts/check-live.sh https://demo.summercms.io (check-live: ok), release 6ce1ec2ef776"
status: pass
human_judgment: true
rationale: "The user browsed the live demo: \"it's beautiful and no errors spotted\""
duration: ~1h50m wall clock (plan 02 closed 14:42 +02:00; last code commit 15:53; redeploy, the user's check and this SUMMARY by 16:31)
completed: 2026-10-20
---
# Phase 19.4.1 Plan 03: Accounts, tour, EN/PL, journal and contact Summary
**demo.summercms.io now lets visitors register and log in behind Cloudflare Turnstile. The homepage is a six-card guided tour in the summercms.io look, and the site, FAQ, menu and journal switch between English and Polish, server-rendered from a cookie. Journal posts show a SummerCMS Team author card fed by the extended author API. "Want to see the backend?" opens a contact form that files G15Office tasks. The demo runs from sm-user-plugin v0.1.3 and sm-journal-plugin v0.2.1, has a disabled demo:reset job, and offers open tabs a reload after each deploy.**
## Performance
- **Duration:** about 1h50m wall clock, including the Task 6 go-ahead, the redeploy and the Task 8 check
- **Started:** 2026-10-20T12:42Z (after plan 02 closed at d04462a)
- **Completed:** 2026-10-20T14:31Z
- **Tasks:** 8/8
- **Files modified:** 58 (23 in sm-demo-app besides the vue-demo-app pointer, 28 in vue-demo-app, 4 in sm-user-plugin, 3 in sm-journal-plugin)
## Accomplishments
- **Turnstile (D-07, D-05).** sm-user-plugin gets `golem15.user.turnstile` (`""` | `open` | `closed`). The empty default adds nothing. `open` or `closed` appends `turnstile:{mode}` to `/login` and `/register` only, and any other value fails boot naming the key. `TestTurnstileRoutesSmoke` pins the result with a recording `pact.Router`. The demo sets `closed`. `/register` (ported from bm) and `/login` render the widget, which resets after each submit. No page shows or pre-fills a credential, and a successful registration logs the visitor in.
- **Tour and look (D-11, D-12).** The hero is followed by six cards in order: Journal, Presentations, Quizzes, Payments (PL Płatności), FAQ, Accounts. A card shows its "Try it" link only when the route exists in the build, so Presentations and Quizzes say "Coming with the next update" until plan 04. SiteHeader and SiteFooter follow the summercms.io markup. tokens.css is a verbatim copy from vue-summercmsio-app at **644f04e**.
- **English and Polish (D-13).** @nuxtjs/i18n uses `no_prefix` with the locale cookie, so SSR renders the chosen language. en.json and pl.json have identical key sets. The seed writes the Polish FAQ row, Polish menu titles, and Polish post and category translations only where none exist.
- **Journal (todo esrp4qtx).** The author object gains `subtitle`, `description` and `avatar`, which is a URL or null (sm-journal-plugin v0.2.1). The seed creates the backend user SummerCMS Team (`summercms-team`, not a superuser, no role, an unusable random password), with subtitle "Golem15" and the sun badge as its avatar. It also assigns that user to the demo posts. **The app-level `useJournalApi` override held**: `applyJournalLocale` maps `translations[locale]` before the layer's mappers run, so the vue-journal-layer fallback was not used and its pin is unchanged. `/blog/author/:author` is enabled.
- **Contact (D-04, revised).** `/contact` posts multipart to `/_feedback/api/v1/{key}/submit` with type `other` and `"{name} ({email}): {message}"`, and the CTA links to it. demo:seed writes the feedback settings (enabled, allowed origins, widget key) from `golem15.demo.feedback.*`. No listener, job or mailer was added. **G15Office delivery is verified on the live demo:** the user submitted as tester@tester.com, and project `summercms` received task ztqpldsk, "Feedback: Mister Tester (tester@tester.com): this is a test" (status To do). Its description carries the page https://demo.summercms.io/contact and the reporter email.
- **Reset (D-09).** `demo:reset` prints what it would wipe and exits 1 without `--force`. With `--force` it wipes in one transaction, deletes blobs after the commit, reseeds and restores the roadmap decks' `public_hash`. It keeps admins, subscription plans, settings, locales, the sitemap, OAuth client logos and the Uncategorized category. The schedule `golem15.demo.reset.{enabled,at}` defaults to off at 04:00, and an invalid `at` fails boot.
- **Reload on deploy (D-22).** `manifest-update.client.ts` listens for `app:manifest:update` (every 5 minutes) and re-checks `builds/latest.json` on `visibilitychange`. UpdateBanner reloads only when the user clicks. There is no service worker.
## Tags (Task 7, each annotated and confirmed with git ls-remote)
| Plugin | Tag | Commit |
|--------|-----|--------|
| sm-user-plugin | v0.1.3 | 7b9faa3 |
| sm-journal-plugin | v0.2.1 | fe1bbc2 |
sm-demo-app `go.mod` requires both tags, and the submodules `plugins/golem15/user` and `plugins/golem15/journal` sit on the tag commits. No other application's pins changed. There is no framework tag, so there is no changelog post.
## Task Commits
| Task | Repo | Commits |
|------|------|---------|
| 1. Tracer: Turnstile register/login | sm-user-plugin; vue-demo-app; sm-demo-app | 7b9faa3; 27ffd9f; b2a3a1a |
| 2. Tour and EN/PL in the summercms.io look | vue-demo-app; sm-demo-app | 55bef4a; a0313ba |
| 3. Journal EN/PL and author cards | sm-journal-plugin; vue-demo-app; sm-demo-app | fe1bbc2 (authors endpoint); 6d7b1f9; f5680b3 |
| 4. Contact form | vue-demo-app; sm-demo-app | c1167ae; e738fb5 |
| 5. demo:reset (schedule off) and reload banner | vue-demo-app; sm-demo-app | dc26edf; 5ced931 |
| Prep: ROADMAP snapshot sync | sm-demo-app | b47d7ad |
| 6. Go-ahead (decision) | - | "release" |
| 7. Tags, pins, pushes, redeploy | sm-demo-app | e06c378 (pins), 4044adf (vue-demo-app pointer), b4caccc (check-live, DEPLOY.md, README) |
| 8. User check | - | approved |
vue-demo-app was pushed before sm-demo-app. Remote masters: sm-demo-app b4caccc, vue-demo-app dc26edf.
## Rome redeploy (Task 7)
- Release **6ce1ec2ef776**: upload, migrate, demo:seed, swap and restart, per DEPLOY.md.
- Keys were appended by the DEPLOY.md script without printing values: 6 in `/srv/summercms-demo/.env` and 2 in `site.env`. The feedback widget key was generated on rome.
- Turnstile widget "demo.summercms.io" (managed mode) was created through the Cloudflare API in the account that holds the summercms.io zone. The site key is public (0x4AAAAAAFdvDSSOYCjhmxLJ). The secret never passed through the session; the user added it to the secrets file.
- check-live printed ok, and the author API check printed True. `SUMMER_GOLEM15__DEMO__RESET__ENABLED=true` count is 0, and both supervisor programs are RUNNING. The FAQ admin answer was updated in EN and PL. The rollback copies `demo.prev` and `.output.prev` are kept.
- The seed printed harmless GORM "record not found" lines from the presentations plugin.
## Deviations from Plan
1. **[Decision follow-up] CTA and FAQ wording.** The wording follows the /smbackend decision: credentials on request, with no link to /smbackend. A seed step rewrites the two old seeded answers word for word, and the live row was updated in EN and PL.
2. **base.css not copied.** tokens.css is verbatim from vue-summercmsio-app 644f04e. base.css is not copied, because summercms.io is dark-only (plan 02 colour decision).
3. **[Rule 1] Banner alignment.** The banner uses `margin-block: 0`.
4. **[Rule 3] Polish menu titles.** MenuEntry is not Translatable, so Polish menu titles come from the locale files through MenuNav's `#item` slot instead of SetTranslated.
5. **[Rule 3] Local registration throttle.** dev.sh turns the registration throttle off for local runs only, so the check-local runs do not hit 429. Production keeps the throttle.
6. **[Rule 2] Reset keep-list.** The reset also keeps OAuth client logos and the Uncategorized category.
7. **[Rule 3] Post author card.** On a post, the author card comes from an override of `Journal/PostMeta.vue`, besides the planned `Journal/AuthorCard.vue` override.
8. **[Rule 1] Language switch refresh.** LanguageSwitcher calls `refreshNuxtData` so fetched content follows the new locale without a reload.
9. **Seed file.** The feedback settings seed step lives in `seed_feedback.go`, not `seed_locales.go`.
10. **Known limitations.** Category names and previous/next post titles stay English. The author description is a single text that is not translated.
11. **Local environment.** An untracked Nuxt dev server on port 3020 was stopped. The deck servers on 8096 and 5173 were left alone.
**Impact:** all deviations are local to the demo or follow the user's /smbackend decision. The shared plugins changed only additively, and the user plugin change is opt-in.
## Threat model update
**T-19.4.1-06** now covers the reachable admin. The admin is at /smbackend and needs a login. Credentials are given out on request. The login is throttled to 5 per minute per real IP, the admin sends noindex, and /backend answers 404. This replaces the SSH-tunnel-only mitigation. T-19.4.1-16 to -24 are mitigated as planned. The token-less register returns 422, which check-local and check-live both assert.
## Issues Encountered
- After this plan's ROADMAP commit, the embedded ROADMAP snapshot in sm-demo-app (`plugins/demo/content/ROADMAP.md`, synced from d04462a in b47d7ad) is stale again. `scripts/build.sh release` refuses a stale snapshot, so **plan 04 must run `scripts/sync-roadmap.sh` before its release**. This plan did not re-sync.
## Open items for later plans
- **Plan 04:** add the summer theme to the ported viewer and to the demo deck API's theme list.
- **Plan 04:** re-sync the ROADMAP snapshot before the release (see above).
- The phase goal in ROADMAP.md is reworded with this SUMMARY (public URL, login required, credentials on request). Phase 20's goal still says "The admin backend is not public". Reword it when Phase 20 is planned.
## User Setup Required
None remaining. The Turnstile secret and site key and the G15Office keys are in `~/.config/summercms/demo-secrets.env` and on rome. No values are recorded here.
## Next Phase Readiness
Ready for 19.4.1-04. Its tour cards for Presentations and Quizzes show their "Try it" links once the pages exist in its build.
## Known Stubs
None that block the goal. The Presentations and Quizzes cards deliberately show "Coming with the next update" until plan 04 adds the pages, and they never link to a 404.
## Threat Flags
None beyond the threat model above.
## Self-Check: PASSED
- sm-user-plugin 7b9faa3 = v0.1.3 (annotated tag 00c494e, ls-remote); origin/master = 7b9faa3.
- sm-journal-plugin fe1bbc2 = v0.2.1 (annotated tag ec2017d, ls-remote); origin/main = fe1bbc2.
- sm-demo-app commits found: b2a3a1a, a0313ba, f5680b3, e738fb5, 5ced931, b47d7ad, e06c378, 4044adf, b4caccc; ls-remote master = b4caccc = HEAD.
- vue-demo-app commits found: 27ffd9f, 55bef4a, 6d7b1f9, c1167ae, dc26edf; ls-remote master = dc26edf = HEAD.
- sm-demo-app go.mod requires sm-user-plugin v0.1.3 and sm-journal-plugin v0.2.1; the submodules sit on 7b9faa3 and fe1bbc2.
- vue-summercmsio-app 644f04e exists.
- Live results (check-live, the author API, reset-enabled 0, supervisor) come from the Task 7 run. Per the instructions, rome was not contacted while this SUMMARY was written.