docs(quick-261114-p5n): style the user and paymentgateway plugin mail layouts
This commit is contained in:
@@ -5,10 +5,10 @@ current_phase: 35
|
||||
current_phase_name: Mail templates and layouts editor
|
||||
status: executing
|
||||
stopped_at: Completed 35-09-PLAN.md
|
||||
last_updated: "2026-11-14T17:38:18.654Z"
|
||||
last_updated: "2026-11-14T17:48:30.900Z"
|
||||
last_activity: 2026-11-14
|
||||
last_activity_desc: "Completed quick task 261114-p5m: CR-02 residual fix"
|
||||
state_head: f1f284a0f93754c03b2f9f0f1a7c060228d9eb39
|
||||
last_activity_desc: "Completed quick task 261114-p5n: plugin mail layouts styled like the default layout"
|
||||
state_head: 4ef3aa1f90a9edfd6757f1269904c0ad4109c56d
|
||||
progress:
|
||||
total_phases: 52
|
||||
completed_phases: 37
|
||||
@@ -32,7 +32,7 @@ See: .planning/PROJECT.md (updated 2026-10-22)
|
||||
Phase: 35 (Mail templates and layouts editor) — EXECUTING
|
||||
Plan: 9 of 9
|
||||
Status: Ready to execute
|
||||
Last activity: 2026-11-14 - Completed quick task 261114-p5m: CR-02 residual fix
|
||||
Last activity: 2026-11-14 - Completed quick task 261114-p5n: plugin mail layouts styled like the default layout
|
||||
|
||||
Progress: [████████░░] 82%
|
||||
|
||||
@@ -1268,6 +1268,7 @@ Recent decisions affecting current work:
|
||||
| 261106-kt2 | deferred:purge, migrate* and queue:clear reuse the app's published database, so the in-server scheduler no longer fails with duplicate provider for *sql.DB | 2026-11-06 | 99abe88 | [261106-kt2-lagoon-deferred-purge-fails-in-the-sched](./quick/261106-kt2-lagoon-deferred-purge-fails-in-the-sched/) |
|
||||
| 261108-pe4 | beachcomber highlights and field projection: Query.IncludeFields/ExcludeFields/Highlight, SearchResult.Hits (plain-text segments), HighlightSearcher + SupportsHighlights; Typesense parses v1 highlights | 2026-11-08 | 7819c67 | [261108-pe4-beachcomber-highlights-and-field-project](./quick/261108-pe4-beachcomber-highlights-and-field-project/) |
|
||||
| 261114-p5m | Fix CR-02 residual: quoted end tags in raw-text elements bypass the postcard scheme check | 2026-11-14 | f1f284a0 | [261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra](./quick/261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra/) |
|
||||
| 261114-p5n | Style the user and paymentgateway plugin mail layouts like the postcard default layout | 2026-11-14 | 4ef3aa1f | [261114-p5n-style-the-user-and-paymentgateway-plugin](./quick/261114-p5n-style-the-user-and-paymentgateway-plugin/) |
|
||||
|
||||
## Deferred Items
|
||||
|
||||
|
||||
@@ -0,0 +1,238 @@
|
||||
---
|
||||
phase: quick-261114-p5n
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- ../sm-user-plugin/views/mail/layouts/user.htm
|
||||
- ../sm-paymentgateway-plugin/views/mail/layouts/paymentgateway.htm
|
||||
- ../sm-demo-app/plugins/golem15/user
|
||||
- ../sm-demo-app/plugins/golem15/paymentgateway
|
||||
autonomous: true
|
||||
requirements:
|
||||
- QUICK-261114-p5n
|
||||
|
||||
estimate:
|
||||
tokens: 80000
|
||||
raw_tokens: 80000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Rendered through the current postcard checkout, golem15.user::mail.activate and golem15.paymentgateway::mail.order.paid have default.htm's structure: a wrapper table (class 'wrapper layout-user' / 'wrapper layout-paymentgateway'), a header row with the logo (alt = site name) or the site name, and no header row when neither is set, the 570px white inner-body card whose content-cell holds the message, and the footer row '© <year> <site name>'"
|
||||
- "With a saved Branding (stub OverrideSource), the Branding colours win over the layout's built-in fallback colours in the inlined HTML; with no Branding and empty mail.brandCss the fallback gives the default look"
|
||||
- "Under framework v0.6.0 (what both plugins' go.mod requires) both layouts register and render without error; HTML and text hold no '<no value>', '<nil>' or '%!'; the card markup and the built-in fallback style are present; the header and footer rows are absent (graceful degradation)"
|
||||
- "Layout codes, file paths, header names and both MailLayouts maps are unchanged; the header and text sections of both layout files are byte-identical to their base commits"
|
||||
- "The plugin mail tests (TestMail, TestPolishMailSubjects; TestMailCatalog, TestMailTracer, TestMailersMatrixSmoke with GOWORK=off) and scripts/check-phase35.sh --consumers pass"
|
||||
- "The demo's UAT override of golem15.user::mail.layouts.user no longer masks the file layout (reset only while it still carries the UAT marker, its old content recorded in the SUMMARY); the golem15.user::mail.activate override is reported, untouched"
|
||||
- "sm-demo-app's two submodule pointers reference the new plugin commits in one separate commit, the demo compiles, nothing is pushed or tagged, and the SUMMARY lists the follow-up that needs the framework tag"
|
||||
artifacts:
|
||||
- path: ../sm-user-plugin/views/mail/layouts/user.htm
|
||||
provides: "golem15.user::mail.layouts.user styled like postcard's default layout, self-contained (inline header/card/footer markup, built-in fallback style before the brand CSS slot)"
|
||||
- path: ../sm-paymentgateway-plugin/views/mail/layouts/paymentgateway.htm
|
||||
provides: "golem15.paymentgateway::mail.layouts.paymentgateway styled the same way, title tag kept"
|
||||
- path: ../sm-demo-app/plugins/golem15/user
|
||||
provides: "submodule pointer at the new sm-user-plugin commit"
|
||||
- path: ../sm-demo-app/plugins/golem15/paymentgateway
|
||||
provides: "submodule pointer at the new sm-paymentgateway-plugin commit"
|
||||
key_links:
|
||||
- from: "layout HTML section"
|
||||
to: "postcard render data"
|
||||
via: "v0.6.0 gives Content/Subject/css/brandCss only; the current checkout adds logoUrl/siteName/year; every use of the newer keys sits behind if/with so missing keys render nothing (missingkey=zero)"
|
||||
pattern: "with .year|or .logoUrl .siteName"
|
||||
- from: "built-in fallback style"
|
||||
to: "postcard.CompileBrandCSS(postcard.DefaultBrand())"
|
||||
via: "pasted verbatim before the brandCss and css slots; go-premailer orders equal-specificity rules by source position, so saved Branding CSS (later) wins"
|
||||
pattern: "brandCss"
|
||||
- from: "plugins' MailLayouts maps (plugin.go, mail.go)"
|
||||
to: "layout files"
|
||||
via: "alias user / paymentgateway to the unchanged full codes; templates name the alias in layout ="
|
||||
pattern: "mail.layouts.(user|paymentgateway)"
|
||||
- from: "sm-demo-app go.work replace"
|
||||
to: "plugins/golem15/{user,paymentgateway} submodule checkouts"
|
||||
via: "the demo builds the plugins from the submodules, so the pointer bump is what puts the new layouts in the demo binary"
|
||||
pattern: "plugins/golem15/(user|paymentgateway)"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Make the user and paymentgateway plugin mail layouts look like postcard's default layout. On the demo instance only the default layout looks right; the two plugin layouts are stubs that put the message in an empty page. The user asked on 2026-11-14 to fix them now, superseding the 2026-11-13 "framework only" deferral for the layouts (35-06-PLAN.md follow-up list).
|
||||
|
||||
Hard constraint: both plugins are core plugins, used by many projects, and their go.mod requires framework v0.6.0. No released framework tag contains phase 35 yet, and v0.6.0 postcard has no partial or markdown template functions and passes layouts only Content, Subject, css and brandCss. Each layout is therefore self-contained: inline header/card/footer markup, plus a built-in copy of the default brand CSS that the real brand CSS overrides. It renders like the default layout on the current checkout and degrades gracefully (no header or footer row, same card and colours) on v0.6.x. Anything that needs the framework bump goes on the follow-up list, not into the files.
|
||||
|
||||
Purpose: plugin mails look finished on every framework version their go.mod allows, without a breaking change.
|
||||
Output: two restyled layout files (one commit per plugin repo), a demo submodule pointer commit, the demo UAT layout override cleared, and a SUMMARY with render evidence and the remaining follow-up.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/STATE.md
|
||||
@CLAUDE.md
|
||||
@.planning/notes/core-plugins-own-repos.md
|
||||
@modules/postcard/assets/default.htm
|
||||
@modules/postcard/assets/partials/header.htm
|
||||
@modules/postcard/assets/partials/footer.htm
|
||||
@modules/postcard/assets/brand.css.tmpl
|
||||
|
||||
Paths used below (absolute):
|
||||
- FW = /media/nvme/dev/golem15/summercms.io/summercms/summercms.go (this repo, framework)
|
||||
- UP = /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin
|
||||
- PG = /media/nvme/dev/golem15/summercms.io/summercms/sm-paymentgateway-plugin
|
||||
- DEMO = /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app
|
||||
- SCRATCH = the executor's session scratchpad directory (never inside a repo)
|
||||
|
||||
Live observations at planning time (2026-11-14), re-check before acting:
|
||||
- UP HEAD b179e6b, PG HEAD 8a88b86, both clean; the DEMO submodules plugins/golem15/user and plugins/golem15/paymentgateway sit at the same commits, clean. DEMO has other sessions' uncommitted edits (plugins.gen.go, scripts/dev.sh): leave them alone.
|
||||
- Only these two plugins ship mail layouts (views/mail/layouts). sm-mfa-plugin and sm-quizzes-plugin declare no layout (MailLayouts returns nil) and use postcard's default. No other plugin's templates name layout "user" or "paymentgateway". 8 user templates and 54 paymentgateway templates use their plugin's layout.
|
||||
- v0.6.0 postcard (git -C FW show v0.6.0:modules/postcard/templates.go) runs layouts through html/template and text/template with Option("missingkey=zero") and no FuncMap. The data is Content, Subject, css and brandCss. brandCss there is the mail.brandCss config value (empty by default). v0.6.0 has no assets/partials.
|
||||
- The current checkout (modules/postcard/templates.go renderParts) adds logoUrl, siteName and year, a partial FuncMap, and CSS inlining via go-premailer v1.38.0. Its rule sort includes ruleSetIndex and ruleIndex, so for equal specificity the later rule wins. CompileBrandCSS (brand.go) already styles default.htm's classes; DefaultBrand BodyBg is #f5f8fa.
|
||||
- The plugins' text sections: user is the stub `-- {{ .Content }} --`, paymentgateway is `{{ .Content }}`. The orchestrator says to keep both unchanged. TestMailCatalog asserts no "<no value>" in the text.
|
||||
- The plugin go.sum files lack the current framework's go-premailer lines, so plugin tests against this checkout run with a scratch modfile (scripts/check-phase35.sh consumer_modfile pattern). The gate refuses a sibling whose git status --porcelain is not empty, so it runs only after the plugin commits.
|
||||
- Demo DB (docker container sm-demo-pg, db and user summercms_demo), table system_mail_layouts: golem15.user::mail.layouts.user has is_custom = t, customized_at 2026-11-13 15:07, and content_html carrying the `<!-- uat -->` marker. This is the UAT leftover that 35-07-SUMMARY.md line 253 says to reset, and it masks the file layout. In system_mail_templates, golem15.user::mail.activate has is_custom = t (subject "Aktywuj swoje konto", 2026-11-13 15:04), also named in 35-07. It does not mask the layout. No custom partials. The paymentgateway layout row is not custom.
|
||||
- The demo runs as `./bin/demo serve --addr 0.0.0.0:8097` (the user's session), built by scripts/dev.sh with `go build -tags summercms_mcp,nodynamic -o bin/demo .`. Mail views are embedded, so the user sees the new layouts only after a rebuild and restart.
|
||||
- Do not touch FW/modules/postcard/safety.go (quick task 261114-p5m edits it and runs first). No framework code changes in this task.
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: Tracer, user layout restyled and rendered on both framework versions</name>
|
||||
<files>../sm-user-plugin/views/mail/layouts/user.htm</files>
|
||||
<precondition>`cd FW && go build ./modules/postcard` succeeds (p5m finished and left postcard compiling), `git -C UP status --porcelain` prints nothing, and the Go module cache holds the framework's dependencies (`cd FW && GOPROXY=off go build ./modules/postcard` works)</precondition>
|
||||
<action>
|
||||
Record BASE_UP=$(git -C UP rev-parse HEAD); b179e6b is expected.
|
||||
|
||||
1. Build a render harness in SCRATCH, outside every repo, as two standalone Go modules. Each has its own go.mod requiring git.golem15.com/golem15/summercms v0.6.0 plus a replace line. Run each with GOWORK=off GOPROXY=off GOSUMDB=off GOFLAGS=-mod=mod.
|
||||
- SCRATCH/p5n-render/cur: replace to FW; go.sum is a copy of FW/go.sum.
|
||||
- SCRATCH/p5n-render/v060: replace to SCRATCH/fw-v060, a plain export made with `git -C FW archive v0.6.0 | tar -x -C SCRATCH/fw-v060` (no git worktree, so the shared .git stays untouched); go.sum is the output of `git -C FW show v0.6.0:go.sum`.
|
||||
- If the v0.6.0 build cannot resolve a dependency offline, fall back to a stdlib-only emulation of v0.6.0's execHTML/execText: html/template and text/template, Option("missingkey=zero"), no FuncMap, data limited to Content, Subject, css and brandCss, the layout split on its two `==` separator lines. Say in the SUMMARY which path ran.
|
||||
- Both programs build postcard.NewCatalog(). They Register the user plugin with pluginID golem15.user, fsys os.DirFS(UP), templates golem15.user::mail.activate, and layouts map user to golem15.user::mail.layouts.user. They Send through postcard.NewMailer with postcard.NewMemoryDriver(), vars Name "Ada", Link "https://example.test/activate?code=X1" and Code "X1", then write each Messages() HTML and text to SCRATCH/p5n-out/<version>-<scenario>-user.{html,txt}.
|
||||
- The cur program also prints postcard.CompileBrandCSS(postcard.DefaultBrand()) to SCRATCH/p5n-out/fallback.css. It renders two scenarios. Scenario plain: Options{} and no OverrideSource. Scenario brand: a stub OverrideSource whose MailOverrides returns Overrides{Brand: &b}, where b is DefaultBrand() with BodyBg #123456, SiteName "Acme" and LogoURL "https://example.test/logo.png". In the brand scenario it also renders a reference message in postcard's default layout: Register pluginID acme with an fstest.MapFS holding views/mail/sample.htm (subject line, `==`, a one-line Markdown body, no layout key) and template acme::mail.sample.
|
||||
- The harness exits non-zero, naming the failed check, unless every check below holds.
|
||||
- cur, plain: the HTML has a table with class "wrapper layout-user", class "inner-body" with width="570", class "content-cell" containing the activate link URL, and the footer row (class "footer") with "© <current year>". It has no class "header". The wrapper table's inlined style contains f5f8fa (the fallback is inlined).
|
||||
- cur, brand: there is a class "header" row whose img has src https://example.test/logo.png and alt "Acme", and the footer reads "© <current year> Acme". The wrapper's inlined style contains 123456 and not f5f8fa, so the Branding wins the cascade. Every class in the reference default-layout render, except layout-default, also appears in the user render.
|
||||
- v060: Send returns nil; the HTML has the wrapper, inner-body and content-cell markup, the activate link, and "#f5f8fa" in its style element; it has no class "header" and no class "footer".
|
||||
- All renders: no "<no value>", "<nil>" or "%!" in HTML or text. Each text part starts with "-- ", ends with " --" and contains "Kod: X1".
|
||||
2. Rewrite only the HTML section of UP/views/mail/layouts/user.htm (after the second `==` line). Keep the header (`name = "User"`) and the text section byte for byte. Mirror FW/modules/postcard/assets/default.htm, but with no template function call of any kind: the partial and markdown functions do not exist in v0.6.0 and would fail the layout's parse at boot, and printf output would show a nil year.
|
||||
- Head: default's DOCTYPE, html and both meta tags (viewport and Content-Type), then one style element. It holds the exact contents of SCRATCH/p5n-out/fallback.css, then the existing brandCss and css actions in that order. Fallback first lets saved Branding and mail.css override it.
|
||||
- Body: the wrapper table with class "wrapper layout-user" (the old layout-user class name kept for custom CSS) and default's attributes.
|
||||
- Header: the inline equivalent of postcard's header partial as default.htm calls it (logo from logoUrl, body from siteName, no url). Wrap it in an if on `or .logoUrl .siteName`. Use an img with class "logo", src from .logoUrl and alt from .siteName when a logo is set, else a span with .siteName.
|
||||
- Card: default's content/body/inner-body/content-cell tables with `{{ .Content }}` in the cell.
|
||||
- Footer: the inline equivalent of the footer partial's HTML (tr, td, table class "footer" width 570, td class "content-cell" align center, a p element). Wrap it in `with .year`; the p reads the copyright sign, the year, and the site name preceded by a space through `with $.siteName`.
|
||||
- Every value comes from a plain field reference inside an HTML text or attribute context, so html/template escapes it. No HTML comments in the file: html/template strips them, and an action inside one still executes.
|
||||
3. Re-run both harness programs until every check passes. Then run the plugin's own mail tests against this checkout with a scratch modfile: copy UP/go.mod to SCRATCH/modfile-up/go.mod, and make SCRATCH/modfile-up/go.sum the sorted union of UP/go.sum and FW/go.sum.
|
||||
4. Commit in UP only, staging the one path explicitly. Message: `fix(quick-261114-p5n): style the user mail layout like the framework's default layout`. No co-author tags (user rule). Do not push or tag.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd SCRATCH/p5n-render/cur && GOWORK=off GOPROXY=off GOSUMDB=off GOFLAGS=-mod=mod go run . && cd SCRATCH/p5n-render/v060 && GOWORK=off GOPROXY=off GOSUMDB=off GOFLAGS=-mod=mod go run . && cd /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin && GOWORK=off GOPROXY=off go test -mod=mod -modfile=SCRATCH/modfile-up/go.mod -count=1 -run '^(TestMail|TestPolishMailSubjects)$' . && git show "$BASE_UP":views/mail/layouts/user.htm > SCRATCH/base-user.htm && diff <(awk '/^==$/{n++} n<2' SCRATCH/base-user.htm) <(awk '/^==$/{n++} n<2' views/mail/layouts/user.htm) && test "$(awk '/^==$/{n++} n>=2' views/mail/layouts/user.htm | grep -c -E '\{\{-?[^}]*\b(partial|markdown|printf)\b')" -eq 0 && test "$(awk '/^==$/{n++} n>=2' views/mail/layouts/user.htm | grep -c -F '<!--')" -eq 0</automated>
|
||||
</verify>
|
||||
<done>Both harness programs exit 0, so the current checkout gives default's structure with the logo/site-name header, the footer and Branding colours winning, and v0.6.0 renders cleanly without header or footer rows and with the fallback look. TestMail and TestPolishMailSubjects pass. The header and text sections are unchanged against BASE_UP. The HTML section calls no template function and has no HTML comment. One commit in sm-user-plugin touching only views/mail/layouts/user.htm, nothing pushed.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Paymentgateway layout in the same shape, then the consumers gate</name>
|
||||
<files>../sm-paymentgateway-plugin/views/mail/layouts/paymentgateway.htm</files>
|
||||
<precondition>`git -C PG status --porcelain` prints nothing; Task 1's harness and SCRATCH/p5n-out/fallback.css exist</precondition>
|
||||
<action>
|
||||
Record BASE_PG=$(git -C PG rev-parse HEAD); 8a88b86 is expected.
|
||||
|
||||
1. Extend both harness programs to also Register the paymentgateway plugin. Use pluginID golem15.paymentgateway, fsys os.DirFS(PG), templates golem15.paymentgateway::mail.order.paid, and layouts map paymentgateway to golem15.paymentgateway::mail.layouts.paymentgateway.
|
||||
- Send that template with these vars: user (map with first_name "Ada"); order (map with code "AB12CD34", items holding one map with description "Vinyl", count 1 and total_gross "PLN 49.00", and total_gross "PLN 49.00"); orderUrl "https://example.test/orders/AB12CD34"; posName "Acme Shop".
|
||||
- Apply the same checks as Task 1 with the class "wrapper layout-paymentgateway". The order URL is in the content-cell, and the text holds "AB12CD34" with no "<no value>". Also check that a title element holding the rendered subject is present. The text-part dash check stays user-only.
|
||||
2. Rewrite only the HTML section of PG/views/mail/layouts/paymentgateway.htm, exactly as Task 1 step 2 did, with three differences:
|
||||
- The wrapper class is "wrapper layout-paymentgateway".
|
||||
- The head keeps the existing title element with the Subject field.
|
||||
- The head keeps both existing meta tags.
|
||||
Keep the header (`name = "Payment gateway"`) and the text section (`{{ .Content }}`) byte for byte. The fallback CSS is the same fallback.css contents, so both layouts and the framework default stay identical in look.
|
||||
3. Run both harness programs and fix until every check passes for both plugins. Then run the paymentgateway mail tests with GOWORK=off and a scratch modfile: SCRATCH/modfile-pg/go.mod copied from PG/go.mod, and go.sum the sorted union of PG/go.sum and FW/go.sum.
|
||||
4. Check whether PG/README.md or UP/README.md describes the layouts' markup or look; today they name only the layout code. Update a README in the same plugin commit only if it does.
|
||||
5. Commit in PG only, staging the one path (plus a README only if step 4 changed it). Message: `fix(quick-261114-p5n): style the paymentgateway mail layout like the framework's default layout`. No co-author tags. Do not push or tag.
|
||||
6. Both sibling trees are now clean. Run `bash FW/scripts/check-phase35.sh --consumers`, which runs vet and the named mail tests of both plugins read-only through scratch modfiles. If it reports a failure unrelated to the layouts (for example a breakage from p5m), report it in the SUMMARY with its output. Do not fix it inside this task.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd SCRATCH/p5n-render/cur && GOWORK=off GOPROXY=off GOSUMDB=off GOFLAGS=-mod=mod go run . && cd SCRATCH/p5n-render/v060 && GOWORK=off GOPROXY=off GOSUMDB=off GOFLAGS=-mod=mod go run . && cd /media/nvme/dev/golem15/summercms.io/summercms/sm-paymentgateway-plugin && GOWORK=off GOPROXY=off go test -mod=mod -modfile=SCRATCH/modfile-pg/go.mod -count=1 -run '^(TestMailCatalog|TestMailTracer|TestMailersMatrixSmoke)$' . && git show "$BASE_PG":views/mail/layouts/paymentgateway.htm > SCRATCH/base-pg.htm && diff <(awk '/^==$/{n++} n<2' SCRATCH/base-pg.htm) <(awk '/^==$/{n++} n<2' views/mail/layouts/paymentgateway.htm) && test "$(awk '/^==$/{n++} n>=2' views/mail/layouts/paymentgateway.htm | grep -c -E '\{\{-?[^}]*\b(partial|markdown|printf)\b')" -eq 0 && bash /media/nvme/dev/golem15/summercms.io/summercms/summercms.go/scripts/check-phase35.sh --consumers</automated>
|
||||
</verify>
|
||||
<done>Both harness programs exit 0 for both plugins on the current checkout and v0.6.0. The three paymentgateway mail tests pass with GOWORK=off. The header and text sections are unchanged against BASE_PG, and no template function is called. check-phase35.sh --consumers prints "phase35 consumers passed". One commit in sm-paymentgateway-plugin, nothing pushed. Both plugin trees are clean.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Demo pointer bump, UAT layout override, follow-up record</name>
|
||||
<files>../sm-demo-app/plugins/golem15/user, ../sm-demo-app/plugins/golem15/paymentgateway</files>
|
||||
<precondition>`docker exec sm-demo-pg pg_isready -U summercms_demo` answers; if it does not, skip step 1, say so in the SUMMARY, and continue with step 2</precondition>
|
||||
<action>
|
||||
1. Demo DB overrides. Use `docker exec sm-demo-pg psql -U summercms_demo -d summercms_demo`.
|
||||
- List the rows with is_custom = true in system_mail_layouts, system_mail_templates and system_mail_partials whose code starts with golem15.user:: or golem15.paymentgateway::.
|
||||
- For golem15.user::mail.layouts.user, first save its content_html, content_text, content_css and customized_at into the SUMMARY (a fenced block) so the edit can be restored.
|
||||
- Then reset it only if it is still the 35-07 UAT leftover. Run one UPDATE that sets is_custom = FALSE, base_hash = NULL, customized_at = NULL, content_css = '' and updated_at = NOW(). Its WHERE clause requires code = 'golem15.user::mail.layouts.user', source IS NOT NULL, is_custom, and content_html containing the uat HTML comment marker. This is ResetOverride's flag change (FW/modules/postcard/store.go). With is_custom false the mailer sends the file version, and SyncIndex re-mirrors the content columns from the file at the demo's next boot.
|
||||
- If the UPDATE reports 0 rows (the marker is gone, so a person edited it since), do not reset. Report that the override masks the file layout and needs the admin's "reset to file version", which is the user's call.
|
||||
- Report the golem15.user::mail.activate override (subject "Aktywuj swoje konto", a UAT leftover per 35-07, does not mask the layout) and any other custom row found. Leave them untouched; give the admin reset action as the way to clear them. Delete no row.
|
||||
2. Submodule pointer bump in DEMO (stage nothing else). Check `git -C DEMO diff --cached --name-only` is empty, and halt and report if another session has staged files.
|
||||
- For each of user/sm-user-plugin and paymentgateway/sm-paymentgateway-plugin: check the submodule checkout DEMO/plugins/golem15/<name> is clean, fetch the new commit from the local plugin repo (`git -C DEMO/plugins/golem15/<name> fetch <absolute plugin repo path> master`), and check out the new plugin HEAD SHA detached.
|
||||
- Check that the demo still compiles with the new checkouts, writing to a scratch binary so the user's running bin/demo is left alone: `cd DEMO && go build -tags summercms_mcp,nodynamic -o SCRATCH/demo-check .`.
|
||||
- Then `git -C DEMO add plugins/golem15/user plugins/golem15/paymentgateway` and commit with `chore: bump user and paymentgateway (mail layouts styled like the default layout)`. No co-author tags. Do not push. Do not restart or kill the running demo process.
|
||||
3. SUMMARY (FW/.planning/quick/261114-p5n-style-the-user-and-paymentgateway-plugin/261114-p5n-SUMMARY.md). Include:
|
||||
- The three commit SHAs (two plugins, demo).
|
||||
- Which harness path ran for v0.6.0 (real export or emulation), the check results, and the paths of the rendered HTML in SCRATCH/p5n-out.
|
||||
- The DB findings and what was reset, with the saved old content.
|
||||
- The note that the user must rebuild and restart the demo (scripts/dev.sh) to load the embedded layouts.
|
||||
- Push order: sm-user-plugin and sm-paymentgateway-plugin before sm-demo-app, because the demo pointers name unpushed commits.
|
||||
- The remaining follow-up, after a framework tag that contains phase 35:
|
||||
- bump the framework requirement in both plugins with go mod tidy (go-premailer go.sum lines);
|
||||
- use the button partial in activate, reactivate, restore and invite (+ -en) and in the order templates, dropping the duplicated order URL;
|
||||
- switch the layouts' inline header and footer to the header and footer partials, so admin partial overrides apply, and decide whether the fallback style is still needed;
|
||||
- fix the user layout's `-- … --` text wrapper and add the footer line to both text parts (kept unchanged here on the orchestrator's instruction);
|
||||
- bump the pointers in the other apps that mount these plugins (sm-bm-app mounts the user plugin) when they next update.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>test "$(docker exec sm-demo-pg psql -U summercms_demo -d summercms_demo -At -c "select count(*) from system_mail_layouts where code = 'golem15.user::mail.layouts.user' and is_custom and content_html like '%<!-- uat -->%'")" = 0 && test "$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app/plugins/golem15/user rev-parse HEAD)" = "$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-user-plugin rev-parse HEAD)" && test "$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app/plugins/golem15/paymentgateway rev-parse HEAD)" = "$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-paymentgateway-plugin rev-parse HEAD)" && CHANGED="$(git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app show --name-only --format= HEAD)" && test "$(printf '%s\n' "$CHANGED" | sort | tr '\n' ' ')" = "plugins/golem15/paymentgateway plugins/golem15/user " && git -C /media/nvme/dev/golem15/summercms.io/summercms/sm-demo-app submodule status plugins/golem15/user plugins/golem15/paymentgateway</automated>
|
||||
</verify>
|
||||
<done>No custom row with the UAT marker remains for golem15.user::mail.layouts.user; it was reset, or it was reported because the marker was gone. Its old content is in the SUMMARY. The activate override is reported and untouched. The demo HEAD commit touches exactly the two submodule paths, which match the plugin repos' HEADs. The demo compiles to a scratch binary. The running demo process was not touched. The SUMMARY lists commits, render evidence, DB findings, the restart note, the push order and the follow-up.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| Branding / mail.from → layout | Site name and logo URL come from admin-edited Branding (or the mail.from display name) and reach the HTML of every plugin mail |
|
||||
| plugin layout file → every consuming app's boot | A layout that fails to parse under the framework version an app runs stops Register, so the app does not boot |
|
||||
| executor → demo database | A direct UPDATE on system_mail_layouts can discard an administrator's real edit |
|
||||
| local commits → other clones | The demo pointers name plugin commits that exist only locally until pushed |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-p5n-01 | Tampering (HTML/URL injection) | logoUrl / siteName in the inline header and footer | medium | mitigate | Values only as plain field references in HTML text or attribute context, so html/template escapes them and filters unsafe URL schemes in img src, the same as postcard's header partial. No template.HTML or other trust conversion. The framework's validateHTML and inliner checks still run on the result (Tasks 1-2 harness). |
|
||||
| T-p5n-02 | Denial of service (breaking change) | layout files under v0.6.x | high | mitigate | No template function call in the HTML section (region-scoped grep gate in Tasks 1-2). Every newer key sits behind if/with. The harness registers and renders both layouts against the real v0.6.0 export (or the documented emulation). Text sections unchanged (diff gate). |
|
||||
| T-p5n-03 | Tampering / repudiation | demo DB reset of golem15.user::mail.layouts.user | medium | mitigate | One UPDATE scoped by code, source IS NOT NULL, is_custom and the UAT marker. Old content saved into the SUMMARY first. Zero rows means report, not force. No DELETE. Other overrides reported only. |
|
||||
| T-p5n-04 | Tampering (supply chain of pointers) | sm-demo-app submodule pointers to unpushed commits | low | accept | Nothing pushed (user rule). The SUMMARY states the push order (plugins first, then demo), so a clone never sees a pointer to a missing commit once the user pushes. |
|
||||
| T-p5n-05 | Information disclosure | stray edits in shared repos | low | mitigate | Stage explicit paths only. Check the demo index is empty before staging. No edits to safety.go or any framework code. Other sessions' uncommitted files left alone. |
|
||||
| T-p5n-SC | Tampering | npm/pip/cargo/go installs | low | accept | No dependency is added. The scratch harness builds only against modules already in the module cache, with GOPROXY=off and outside every repo, so the package-legitimacy gate has nothing to check. |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Harness (SCRATCH/p5n-render/cur and v060) exits 0 for both plugins: default's structure, header and footer on the current checkout, Branding colours winning over the fallback, and clean graceful renders on v0.6.0.
|
||||
- sm-user-plugin TestMail and TestPolishMailSubjects, and sm-paymentgateway-plugin (GOWORK=off) TestMailCatalog, TestMailTracer and TestMailersMatrixSmoke, pass against this checkout via scratch modfiles.
|
||||
- `bash scripts/check-phase35.sh --consumers` passes after the plugin commits.
|
||||
- Header and text sections of both layouts are byte-identical to their base commits; layout codes, file paths and MailLayouts maps are unchanged.
|
||||
- The demo DB UAT layout override is cleared (or reported); the demo pointer commit touches exactly the two submodules; the demo compiles.
|
||||
- No framework file outside .planning/quick/261114-p5n-* is touched by this task; nothing is pushed or tagged.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- A user activation mail and a paymentgateway order mail rendered through postcard look like the default layout (grey page, header with logo or site name, white 570px card, copyright footer) on the current framework, and render cleanly with the same card look on v0.6.0.
|
||||
- Three local commits: sm-user-plugin, sm-paymentgateway-plugin, sm-demo-app (pointers only).
|
||||
- The SUMMARY gives render evidence, DB findings and the restore content, the restart and push-order notes, and the post-tag follow-up.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/quick/261114-p5n-style-the-user-and-paymentgateway-plugin/261114-p5n-SUMMARY.md` when done.
|
||||
</output>
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
phase: quick-261114-p5n
|
||||
plan: 01
|
||||
subsystem: mail (sm-user-plugin, sm-paymentgateway-plugin layouts)
|
||||
tags: [postcard, mail-layouts, core-plugins, demo]
|
||||
status: complete
|
||||
requires:
|
||||
- postcard default layout and brand CSS (modules/postcard/assets/default.htm, brand.css.tmpl)
|
||||
provides:
|
||||
- golem15.user::mail.layouts.user styled like postcard's default layout
|
||||
- golem15.paymentgateway::mail.layouts.paymentgateway styled the same way
|
||||
affects:
|
||||
- every app that mounts sm-user-plugin or sm-paymentgateway-plugin (after a pointer bump)
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "self-contained plugin layout: inline header/card/footer markup, newer render keys behind if/with, built-in brand CSS fallback before the brandCss slot"
|
||||
key-files:
|
||||
created: []
|
||||
modified:
|
||||
- ../sm-user-plugin/views/mail/layouts/user.htm
|
||||
- ../sm-paymentgateway-plugin/views/mail/layouts/paymentgateway.htm
|
||||
- ../sm-demo-app/plugins/golem15/user (submodule pointer)
|
||||
- ../sm-demo-app/plugins/golem15/paymentgateway (submodule pointer)
|
||||
decisions:
|
||||
- "Plugin layouts stay self-contained (no partial/markdown/printf calls) so they parse and render on framework v0.6.0, which both plugins' go.mod requires"
|
||||
- "Built-in copy of CompileBrandCSS(DefaultBrand()) sits before {{ .brandCss }}{{ .css }}; go-premailer's source-order tie-break lets saved Branding win"
|
||||
metrics:
|
||||
duration: ~25min
|
||||
completed: 2026-11-14
|
||||
actuals:
|
||||
tokens: 2900
|
||||
tasks: 3
|
||||
commits: 0
|
||||
plan_head_before: 5735e7c7
|
||||
plan_head_after: 5735e7c7
|
||||
---
|
||||
|
||||
# Quick 261114-p5n: user and paymentgateway mail layouts styled like postcard's default layout
|
||||
|
||||
The two plugin mail layouts now use the same structure as postcard's default layout: a grey wrapper, a header with the logo or site name, the white 570px card and a copyright footer. Each file has its own copy of the default brand CSS, which saved Branding overrides. On framework v0.6.0 both render without error; the header and footer rows are left out and the card look stays.
|
||||
|
||||
`commits: 0` counts framework-repo commits only. Every code commit of this task is in a sibling repository (below), and the framework repo gets only this SUMMARY, which is not committed.
|
||||
|
||||
## Commits
|
||||
|
||||
| Repo | Commit | Message |
|
||||
|------|--------|---------|
|
||||
| sm-user-plugin (master) | `6ec4c85` (base `b179e6b`) | fix(quick-261114-p5n): style the user mail layout like the framework's default layout |
|
||||
| sm-paymentgateway-plugin (main) | `32618fc` (base `8a88b86`) | fix(quick-261114-p5n): style the paymentgateway mail layout like the framework's default layout |
|
||||
| sm-demo-app (master) | `d2dfb19` (base `17467ed`) | chore: bump user and paymentgateway (mail layouts styled like the default layout) |
|
||||
|
||||
Each plugin commit touches only its layout file. The demo commit touches only `plugins/golem15/user` and `plugins/golem15/paymentgateway`. The other sessions' uncommitted `plugins.gen.go` and `scripts/dev.sh` in sm-demo-app were not staged or touched. Nothing was pushed or tagged.
|
||||
|
||||
## What changed in the layouts
|
||||
|
||||
- The header section and text section are byte-identical to the base commits (diff gate passed for both). Layout codes, file paths and both `MailLayouts` maps are unchanged.
|
||||
- HTML section: default.htm's DOCTYPE, html and meta tags. The paymentgateway layout keeps its `<title>{{ .Subject }}</title>` and both meta tags. Then one style element holding the exact output of `postcard.CompileBrandCSS(postcard.DefaultBrand())`, followed by the original `{{ .brandCss }}{{ .css }}`.
|
||||
- `table.wrapper.layout-user` / `table.wrapper.layout-paymentgateway` (the old class names kept for custom CSS), then:
|
||||
- the header partial's markup inline, behind `{{ if or .logoUrl .siteName }}`;
|
||||
- default's content/body/inner-body/content-cell card with `{{ .Content }}`;
|
||||
- the footer partial's markup inline, behind `{{ with .year }}`, with `© {{ . }}{{ with $.siteName }} {{ . }}{{ end }}`.
|
||||
- No `partial`, `markdown` or `printf` call and no HTML comment in either HTML section (grep gates passed). Every value is a plain field reference in HTML text or attribute context, so html/template escapes it (T-p5n-01).
|
||||
- READMEs: both name only the layout code, not its markup or look, so neither was changed.
|
||||
|
||||
## Render evidence
|
||||
|
||||
Harness: two standalone Go modules in the scratchpad, outside every repo, run with `GOWORK=off GOPROXY=off GOSUMDB=off GOFLAGS=-mod=mod`:
|
||||
- `/tmp/claude-1000/-media-nvme-dev-golem15-summercms-io-summercms-summercms-go/0c86abd1-8e0c-485b-8ad1-fd321a8a0fda/scratchpad/p5n-render/cur` (replace to the framework checkout)
|
||||
- `/tmp/claude-1000/-media-nvme-dev-golem15-summercms-io-summercms-summercms-go/0c86abd1-8e0c-485b-8ad1-fd321a8a0fda/scratchpad/p5n-render/v060` (replace to a `git archive v0.6.0` export)
|
||||
|
||||
**The v0.6.0 run used the real export.** It resolved offline, so the stdlib emulation fallback was not needed.
|
||||
|
||||
Both programs exit 0 for both plugins ("cur: all checks passed", "v060: all checks passed"):
|
||||
- cur, plain (no Branding, empty brandCss): the wrapper table has the expected class; inner-body has width 570; the content-cell holds the activate link or order URL; there is a footer with "© 2026" and no header row; the wrapper's inlined style carries `#f5f8fa` (the fallback CSS was inlined).
|
||||
- cur, brand (stub OverrideSource, BodyBg #123456, SiteName Acme, logo URL): the header row has `img src="https://example.test/logo.png" alt="Acme"`; the footer reads "© 2026 Acme"; the wrapper style carries `#123456` and not `#f5f8fa`, so Branding wins the cascade. Every class in the reference default-layout render (other than `layout-default`) also appears in both plugin renders.
|
||||
- v060: Send returns nil; the wrapper, inner-body and content-cell markup and the link are present; `#f5f8fa` is in the style element; there is no header row and no footer row.
|
||||
- All renders: no `<no value>`, `<nil>` or `%!` in HTML or text. The user text is still `-- … --` and contains "Kod: X1". The paymentgateway text contains AB12CD34, and its `<title>` holds the rendered subject.
|
||||
|
||||
Rendered output: `/tmp/claude-1000/-media-nvme-dev-golem15-summercms-io-summercms-summercms-go/0c86abd1-8e0c-485b-8ad1-fd321a8a0fda/scratchpad/p5n-out/` contains `cur-plain-user.html`, `cur-brand-user.html`, `cur-plain-paymentgateway.html`, `cur-brand-paymentgateway.html`, `cur-brand-default.html` (reference), `v060-plain-user.html` and `v060-plain-paymentgateway.html`, each with a `.txt` file, plus `fallback.css`.
|
||||
|
||||
Plugin tests, run against this checkout through scratch modfiles:
|
||||
- sm-user-plugin: TestPolishMailSubjects and TestMail PASS.
|
||||
- sm-paymentgateway-plugin (GOWORK=off): TestMailCatalog, TestMailTracer and TestMailersMatrixSmoke (27 subtests) PASS.
|
||||
- `bash scripts/check-phase35.sh --consumers` printed "phase35 consumers passed": both sibling trees clean before and after, vet clean, 2 and 3 top-level tests passed.
|
||||
|
||||
## Demo database (sm-demo-pg, summercms_demo)
|
||||
|
||||
Custom rows found for `golem15.user::` / `golem15.paymentgateway::`:
|
||||
- `system_mail_layouts`: `golem15.user::mail.layouts.user` (is_custom true, customized_at 2026-11-13 15:07:34.923673+00). It still carried the `<!-- uat -->` marker, so **it was reset**. One `UPDATE` (scoped by code, `source IS NOT NULL`, `is_custom` and the marker) set is_custom FALSE, base_hash NULL, customized_at NULL, content_css '' and updated_at NOW(). It reported `UPDATE 1`. The mailer now uses the file layout. The content columns still hold the old text until SyncIndex re-mirrors them from the file at the demo's next boot.
|
||||
- `system_mail_templates`: `golem15.user::mail.activate` (is_custom true, subject "Aktywuj swoje konto", customized_at 2026-11-13 15:04:07.99898+00). This is a 35-07 UAT leftover. It does not mask the layout and was **left untouched**. To clear it, use "reset to file version" on that template in the admin mail editor.
|
||||
- `system_mail_partials`: no custom rows. The paymentgateway layout row is not custom.
|
||||
- No row was deleted.
|
||||
|
||||
Saved content of the reset layout row, for restore. Before the reset: source golem15.user, disable_auto_inline_css false, base_hash = file_hash = 875d163b0c00b5ada6d012141a2b2b81199d6ff7f92ab739dcb93a1679a57373, updated_at 2026-11-13 15:07:34.923698+00, customized_at 2026-11-13 15:07:34.923673+00.
|
||||
|
||||
content_html:
|
||||
```html
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<!-- uat -->
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||||
<style type="text/css">{{ .brandCss }}{{ .css }}</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="layout-user">{{ .Content }}</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
content_text:
|
||||
```text
|
||||
-- {{ .Content }} --
|
||||
```
|
||||
content_css: empty string.
|
||||
|
||||
## Demo instance
|
||||
|
||||
- The demo compiles with the new submodule checkouts (`go build -tags summercms_mcp,nodynamic -o <scratchpad>/demo-check .` succeeded). The running `./bin/demo serve --addr 0.0.0.0:8097` (pid 2297826) was not stopped or restarted.
|
||||
- **Rebuild and restart required:** mail views are embedded in the binary, so the new layouts reach the demo only after `scripts/dev.sh` rebuilds and restarts it (orchestrator / user).
|
||||
|
||||
## Push order
|
||||
|
||||
When the user pushes, push sm-user-plugin (`master`) and sm-paymentgateway-plugin (`main`) **before** sm-demo-app. The demo's pointers name commits that exist only locally until then.
|
||||
|
||||
## Follow-up (after a framework tag that contains phase 35)
|
||||
|
||||
- Bump the framework requirement in both plugins and run `go mod tidy` (it adds the go-premailer go.sum lines).
|
||||
- Use the button partial in activate, reactivate, restore and invite (and their `-en` versions) and in the order templates, and drop the duplicated order URL.
|
||||
- Switch the layouts' inline header and footer to the header and footer partials so admin partial overrides apply, and decide whether the built-in fallback style is still needed.
|
||||
- Fix the user layout's `-- … --` text wrapper and add the footer line to both text parts (left unchanged here on the orchestrator's instruction).
|
||||
- Bump the pointers in the other apps that mount these plugins (sm-bm-app mounts the user plugin, as do sm-grzybyfunkcjonalne-app, sm-summercmsio-app and fonoteka.go) when they next update.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
**1. [Rule 3 - Blocking] sm-paymentgateway-plugin's branch is `main`, not `master`**
|
||||
- **Found during:** Task 3
|
||||
- **Issue:** The plan's fetch command named `master` for both plugin repos.
|
||||
- **Fix:** Fetched `main` from sm-paymentgateway-plugin. The checkout is the plugin HEAD SHA (32618fc), as the plan intended.
|
||||
|
||||
Otherwise the plan was executed as written. The tracer gate (auto mode off, human_verify_mode end-of-phase, automated-only verify) re-ran Task 1's verify and it passed, so no checkpoint was raised.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None. No new network endpoints, auth paths or schema changes. The header and footer values reach the HTML only through html/template's normal escaping.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: ../sm-user-plugin/views/mail/layouts/user.htm (commit 6ec4c85 in sm-user-plugin)
|
||||
- FOUND: ../sm-paymentgateway-plugin/views/mail/layouts/paymentgateway.htm (commit 32618fc in sm-paymentgateway-plugin)
|
||||
- FOUND: sm-demo-app commit d2dfb19; its submodule pointers equal both plugin HEADs
|
||||
- Demo DB gate: 0 custom rows with the UAT marker for golem15.user::mail.layouts.user
|
||||
Reference in New Issue
Block a user