docs(35): plan gap closure for G-35-1 and G-35-8

Three gap-closure plans confirmed by the user:
- 35-05: one admin record per mail template with a locale switcher (supersedes D-05)
- 35-06: finished built-in layouts, Branding site name, CSS inlining via go-premailer (supersedes D-10's inlining claim)
- 35-07: unit tests for both gaps and a read-only scratch-modfile consumers stage
This commit is contained in:
Jakub Zych
2026-11-13 16:43:14 +01:00
parent b8c177fca8
commit 293400e61f
4 changed files with 996 additions and 1 deletions

View File

@@ -1936,7 +1936,7 @@ Plans:
**Requirements**: TBD
**Depends on:** Phase 34
**Context:** postcard already loads plugin templates and layouts from `views/mail/` (`pact.HasMailTemplates`, `postcard.BootPlugin`); this phase adds the editable database layer, admin screens and image handling on top. To confirm in discussion: partials (WinterCMS mail partials), preview and test send, per-locale variants, and whether the screens live in cabana or in a plugin.
**Plans:** 4/4 plans executed
**Plans:** 4/7 plans executed
Plans:
**Wave 1**
@@ -1950,3 +1950,12 @@ Plans:
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 35-04-PLAN.md — unit tests for the D-21 list and `scripts/check-phase35.sh` (incl. user and paymentgateway mail tests)
**Wave 5** *(gap closure G-35-1, blocked on Wave 4 completion)*
- [ ] 35-05-PLAN.md — one admin record per mail template with a locale switcher, fallback-locale versions, send resolution of `<template>-<locale>`, decision note superseding D-05
**Wave 6** *(gap closure G-35-8, blocked on Wave 5 completion)*
- [ ] 35-06-PLAN.md — finished default/system/minimal layouts (logo or site name header, card, footer), Branding site name, CSS inlining via go-premailer with a per-layout opt-out, decision note superseding D-10
**Wave 7** *(gap closure, blocked on Wave 6 completion)*
- [ ] 35-07-PLAN.md — unit tests for both gaps and `scripts/check-phase35.sh` with a read-only scratch-modfile consumers stage

View File

@@ -0,0 +1,351 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 05
type: execute
wave: 5
depends_on: ["35-04"]
gap_closure: true
gap_ids: [G-35-1]
files_modified:
- modules/postcard/store.go
- modules/postcard/templates.go
- modules/postcard/mailer.go
- modules/postcard/editor.go
- modules/postcard/override_smoke_test.go
- modules/postcard/README.md
- modules/cabana/mail_admin.go
- modules/cabana/mail_routes.go
- modules/cabana/crud.go
- modules/cabana/relation_field.go
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml
- modules/cabana/backendscreens/controllers/mailtemplates/_info.htm
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/mail_unit_test.go
- modules/cabana/README.md
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- admin/openapi/admin.json
- admin/src/api/schema.d.ts
- admin/src/views/FormView.vue
- admin/src/components/form/LocaleVariantSwitcher.vue
- admin/tests/form/LocaleVariantSwitcher.test.ts
- modules/boardwalk/dist
- docs/services/mail.md
- docs/backend/forms.md
- .planning/notes/2026-11-13-mail-template-locale-groups.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
autonomous: true
requirements: [G-35-1, D-05, D-06, D-07, D-13, D-16]
estimate:
tokens: 150000
raw_tokens: 150000
tasks: 3
confidence: low
must_haves:
truths:
- "Settings → Mail templates shows one row per template (its base code, the locale suffix stripped), however many locales the application has; acme.blog::mail.welcome and acme.blog::mail.welcome-en are one row (G-35-1, supersedes D-05)"
- "Each list row says which locales are customized (Customized locales column), and carries the Customized / File changed badges when any of its locales is customized / drifted; the status filter works on the whole template (D-07)"
- "The template form has a locale switcher listing Default, every locale with its own file, and every other application locale; choosing one opens that locale's version in the same screen, behind the existing unsaved-changes confirm"
- "A locale with neither a file nor a customization shows the default-locale version (what that locale sends today); saving it creates that locale's own customized version; Reset to file version returns it to the default-locale version; File changed shows when the file it was based on changes (D-06, D-07)"
- "Sending <template>-<locale> uses that locale's file or customization first, then the default-locale customization, then the default-locale file; sending a name that has its own file is unchanged, so sm-user-plugin and sm-paymentgateway-plugin send exactly as before"
- "Saves, preview and test send of any locale go through postcard's Editor exactly as before (D-13, D-16)"
- "D-05 is superseded by a decision note and the UI-SPEC carries the locale switcher contract"
prohibitions:
- statement: "pact.HasMailTemplates, postcard.Mailer, Message, Catalog.Register, OverrideSource and SyncIndex keep their signatures; every postcard and cabana API change is additive (check-phase35.sh additive stage)."
status: unresolved
verification: automated
- statement: "No file in a sibling repository (sm-user-plugin, sm-paymentgateway-plugin or any other) is changed by this plan."
status: unresolved
verification: judgment
- statement: "Nothing is pushed or tagged."
status: unresolved
verification: judgment
artifacts:
- path: "modules/postcard/store.go"
provides: "base_code migration and EnsureLocaleRows"
contains: "func EnsureLocaleRows"
- path: "modules/postcard/templates.go"
provides: "TemplateBase and Catalog.TemplateFor"
contains: "func (c *Catalog) TemplateFor"
- path: "modules/cabana/relation_field.go"
provides: "RecordMeta.LocaleVariants"
contains: "LocaleVariants"
- path: "admin/src/components/form/LocaleVariantSwitcher.vue"
provides: "locale switcher in the update form"
contains: "data-locale-variant"
- path: ".planning/notes/2026-11-13-mail-template-locale-groups.md"
provides: "decision note superseding D-05"
contains: "D-05"
key_links:
- from: "modules/postcard/mailer.go"
to: "modules/postcard/templates.go"
via: "render resolves a fallback-locale name to its base file through the catalog resolver"
pattern: "TemplateFor|resolveTemplate"
- from: "modules/cabana/mail_admin.go"
to: "modules/postcard/store.go"
via: "the index sync and the show hook create the fallback-locale rows"
pattern: "postcard.EnsureLocaleRows"
- from: "admin/src/views/FormView.vue"
to: "admin/src/components/form/LocaleVariantSwitcher.vue"
via: "FormView renders the switcher from meta.localeVariants"
pattern: "localeVariants"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel. This gap-closure plan fixes UAT gap G-35-1: locale variants of one template were separate list rows (D-05), which does not scale to a site with many locales. After this plan a template is one record with a locale switcher, and a locale that ships no file can still get its own customized version.
Source: 35-UAT.md (G-35-1, test 1, severity major), user decision of 2026-11-13 confirming three gap-closure plans (this one is framework only; the decision note supersedes D-05).
<objective>
Turn mail templates into one admin record per template with per-locale versions:
- postcard groups template rows by a base code, creates rows for application locales that ship no file, and resolves `<template>-<locale>` at send time to that locale's file or customization first, then the default-locale version;
- cabana lists one row per template with the customized locales and grouped row states, and the template form shows a locale switcher; customized / reset / drift status stays per locale;
- the SPA renders the switcher from a new `meta.localeVariants` on the record response;
- a decision note supersedes D-05 and the UI-SPEC gets the switcher contract.
Purpose: a site with 50 locales gets one row per template, not 50, and administrators can write mail for locales the plugins never shipped.
Output: commits in this repository only (code, one dist rebuild, one planning-docs commit). Nothing in sibling repositories, nothing pushed or tagged.
**Planner decisions recorded here (Claude's discretion within the user's 2026-11-13 decision):**
- **Group key.** `base_code` is the template code with a locale suffix stripped, using the same rule as `postcard.TemplateLocale` (suffix after a dash in the last dotted segment, one of the mail locales). A code without such a suffix is its own base.
- **Mail locales** (cabana): the phrasebook translator's `Locales("")` (today's source) plus, when a `cabana.TranslationWriter` is published and answers, its `EnabledLocales`; the default locale is the writer's `DefaultLocale` when published, otherwise the translator's `Locale()`. This is what makes a 50-locale site (locales enabled through a translate plugin) show 50 entries in the switcher.
- **Variants of one template** (switcher order): Default (the unsuffixed file, labelled with the existing `mail.template.locale_default`), then by locale code: every locale with its own file, every other mail locale except the default ("fallback locale": no file, a row created by `postcard.EnsureLocaleRows`), and any customized row of a locale that is no longer enabled. The default locale gets no fallback row because the unsuffixed file already is the default-locale version. A group whose base has no file (only `x-en.htm` shipped) has no Default and no fallback rows.
- **Send resolution** (postcard, independent of any locale list, so `queue:work` needs no cabana): a name with its own file renders exactly as today. A name the catalog does not hold of the form `<base>-<tag>`, where `<base>` is a registered template and `<tag>` is a two-letter language optionally followed by `-` or `_` and a 2–8 character alphanumeric subtag (case-insensitive; the longest registered base wins), renders the base file with: the name's own customized row, else the base's customized row, else nothing (the base file). Any other unknown name fails with today's "unknown template" error text.
- **What a not-customized fallback row shows**: the default-locale version as it is sent now (the base row's effective subject, body and layout), substituted into the show response; saving it makes the row customized with `base_hash` = the base file's hash; its `file_hash` follows the base file, so drift shows when the default file changes; reset returns it to the base file.
- **Switcher data** travels on the show response as `meta.localeVariants` (`cabana.RecordMeta.LocaleVariants`, omitempty), set through an unexported controller interface like `recordDeletable`, so no other controller's payload changes. Labels and state words are translated on the server; the SPA shows them as text.
- **The list locale filter is removed** (one row per template makes it meaningless); the status filter stays and applies to the whole template.
- New copy keys (en/pl, Polish as design language): `form.locale_variant` ("Language" / "Język"), `mail.template.customized_locales` ("Customized locales" / "Dostosowane języki"), `mail.info_locale_default` ("Default version: sent for every locale that has neither its own file nor a customized version." / "Wersja domyślna: wysyłana dla każdego języka, który nie ma własnego pliku ani dostosowanej wersji."), `mail.info_locale_fallback` ("Locale :locale has no file of its own. Until you customize it, the default version is sent." / "Język :locale nie ma własnego pliku. Dopóki go nie dostosujesz, wysyłana jest wersja domyślna.").
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-CONTEXT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md
@CLAUDE.md
<interfaces>
postcard (35-01):
- modules/postcard/templates.go: `lookupTemplate(name)` (~243) is the one lookup that send, preview and validation go through; `(*Catalog).render` (~492); `TemplateFile` (~760); `(*Catalog).Template(name)` (~862); `TemplateLocale(name, locales)` (~924) is the suffix rule to reuse.
- modules/postcard/mailer.go: `(*mailer).render` (~103) pre-checks `lookupTemplate(msg.Template)` then asks `m.overrides(ctx, msg.Template)` (~157) once; `Send` doc comment (~67) says postcard performs no locale selection.
- modules/postcard/store.go: `Migrations` (~37, one migration today); `dbSource.MailOverrides` (~209) reads `WHERE t.code = ? AND t.is_custom`; `syncLockKey` + `SyncIndex(ctx, db, cat, locales)` (~341-436) upserts one row per file with `locale = TemplateLocale(...)`; `ResetOverride` (~452) refuses a code `cat.Template` does not hold.
- modules/postcard/editor.go: `renderTemplate` (~209) calls `cat.lookupTemplate(d.Name)` and uses its samples.
- modules/postcard/override_smoke_test.go: `mailPostgres(t)`, `bootMailApp`; subtest `migrations_roll_back` (~531) calls `RollbackLast` once and expects no mail table left (must roll back every migration once a second one exists); `unknown_template` (~523) must keep its error text.
cabana (35-02):
- modules/cabana/mail_admin.go: `locales()` (~166), `sync` (~172), `syncOnDatabase` (~185), `ensureSynced` (~194); `MailTemplate` model (~283) and its `FilterScopes`/`FilterScope` (~304-320); `scopeTemplates` (~438), `ListExtendQuery`, `FormExtendQuery`, `ListExtendRecords` (~459, Default label), `ListRowStates` (~491), `FilterOptions` (~505), `AdminRecordActions` reset (~525), `PartialData` (~537), `FormBeforeUpdate` (~573, `catalog().Template(t.Code)`), `FormAfterUpdate` (~594); `recordDeletable` interface (~643); `mailInfoView` (~1302).
- modules/cabana/mail_routes.go: `mailTemplateDraft` (~507) refuses a code `editor.Catalog().Template` does not hold.
- modules/cabana/crud.go: `ShowRecord` (~517) sets `Meta.Deletable` through `recordDeletable` (~553); `recordDataExtender` (~697) lets this package's controllers add or replace keys in the record data.
- modules/cabana/relation_field.go: `RecordMeta` (~104) with `Deletable *bool` as the precedent for a controller-decided meta key.
- modules/cabana/field_ml.go: `TranslationWriter` (~24: `DefaultLocale`, `EnabledLocales`); modules/cabana/http.go `enabledContentLocales` (~1182) shows the lookup.
- modules/phrasebook/translator.go: `Locale()` (~143), `Locales(prefix)` (~544).
- modules/cabana/mail_screens_smoke_test.go: `newMailScreensEnvWith` (~152) with fixture plugin acme.blog (`blogWelcome`, `blogWelcomeEn` ~45); subtest `templates` (~252) asserts the locale column; `drift` (~542) uses the locale filter.
admin (35-03):
- admin/src/views/FormView.vue: record meta read (~266-268, `deletable`), header with title and FormTabs (~695-710), `onBeforeRouteLeave`/`onBeforeRouteUpdate(guard)` (~664) with the unsaved-changes confirm.
- admin/src/App.vue keys the RouterView by path, so navigating to another record id remounts FormView (fresh load).
- admin/src/api/types.ts: `RecordMeta = Schemas['cabana.RecordMeta']` (regenerated by scripts/check-admin-openapi.sh).
</interfaces>
</context>
## Execution units and resume points
- Other sessions edit cabana and the SPA concurrently. Before each task run `git status --short modules/postcard modules/cabana modules/phrasebook admin modules/boardwalk docs` and stop if another session holds uncommitted edits in files this task touches; re-check the line numbers in `<interfaces>` before editing.
- Stage files by explicit path; never `git add -A`. Code and planning docs go in separate commits. Each commit keeps `go vet ./...` and `go test ./...` green.
- Docker-backed tests run without `-short` (through `sudo -u golem` if the Docker socket is denied although the user is in the docker group).
- Resume check: `git log --format=%s -F --grep='<subject>'`.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `feat(mail): one admin record per mail template with a locale switcher` | TestMailScreensSmoke/locales and TestMailOverrideSmoke/locale_fallback pass |
| 2 | `feat(cabana): mail templates list grouped by template with per-locale status` then `build(admin): rebuild the embedded admin for the mail locale switcher` | TestMailScreensSmoke/locales_list passes; scripts/check-admin-dist.sh passes |
| 3 | `docs(35): decision note superseding D-05 and the locale switcher contract` | the note exists and 35-UI-SPEC.md has the C16 section |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "an administrator opens acme.blog::mail.welcome, switches to a locale without a file (de), saves a subject, and sending acme.blog::mail.welcome-de uses it" — one fallback locale only</name>
<reversibility rating="costly">The base_code column and the fallback-locale rows are part of postcard's table schema (a gormigrate migration on every install); RecordMeta.LocaleVariants is a published admin API field.</reversibility>
<precondition>35-04 is complete: `git log --format=%s -F --grep='test(35): phase gate script check-phase35.sh'` prints one line, and `grep -n "func SyncIndex" modules/postcard/store.go` prints one line</precondition>
<files>modules/postcard/store.go, modules/postcard/templates.go, modules/postcard/mailer.go, modules/postcard/editor.go, modules/postcard/override_smoke_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/crud.go, modules/cabana/relation_field.go, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, admin/openapi/admin.json, admin/src/api/schema.d.ts, admin/src/views/FormView.vue, admin/src/components/form/LocaleVariantSwitcher.vue, admin/tests/form/LocaleVariantSwitcher.test.ts, docs/services/mail.md, docs/backend/forms.md</files>
<read_first>
- modules/postcard/templates.go (whole file), modules/postcard/mailer.go (~60-175), modules/postcard/store.go (whole file), modules/postcard/editor.go (~185-240)
- modules/postcard/override_smoke_test.go (~1-120 helpers, ~281-315 override subtest, ~523-548)
- modules/cabana/mail_admin.go (~1-660), modules/cabana/mail_routes.go (~488-660), modules/cabana/crud.go (~505-560 and ~697-755), modules/cabana/relation_field.go (~95-125), modules/cabana/field_ml.go (~1-40), modules/cabana/http.go (~1175-1205)
- modules/cabana/mail_screens_smoke_test.go (~1-260)
- admin/src/views/FormView.vue (~80-120, ~250-290, ~620-720), admin/src/components/form/fields/MLField.vue (the locale select markup and classes to copy), admin/tests/form/FormViewMail.test.ts (mount helpers)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md (G-35-1)
</read_first>
<action>
Supersedes D-05 per the user's 2026-11-13 decision (G-35-1); D-13 and D-16 paths are reused unchanged. Build the thinnest complete path through postcard, cabana and the SPA:
- postcard, store.go: append migration `202611130001_mail_template_base_code` adding nullable `base_code TEXT` to the templates table plus an index `system_mail_templates_base_code_index`; its Rollback drops both. `SyncIndex` writes `base_code` (the new `TemplateBase`, with the same locales it already receives) and its WHERE clause also refreshes a row whose base_code differs. New exported `EnsureLocaleRows(ctx, db, cat, defaultLocale string, locales []string, bases ...string) error`: for every catalog template that is a base (TemplateBase(name) == name; all of them when `bases` is empty, else only those listed) and every locale in `locales` other than `defaultLocale` for which the catalog has no `<base>-<locale>` file, upsert a row with code `<base>-<locale>`, source = the base's plugin ID, locale, base_code = base, description, subject, body and layout_id from the base file, file_hash = the base file's hash; on conflict a customized row keeps its content columns while file_hash, description and base_code follow the base; a matching row is not written; no row is deleted; it takes the same advisory lock as SyncIndex. `ResetOverride` is untouched in this task (Task 2).
- postcard, templates.go: exported `TemplateBase(name string, locales []string) string` (the name without the suffix TemplateLocale finds, else the name) and `(*Catalog) TemplateFor(name string) (TemplateFile, bool)` returning the file a name renders from: its own file, or, for a fallback-locale name per this plan's send-resolution rule, the base template's file (the returned Name is the base's, which is how callers tell the two apart). Route every internal send/preview/validate lookup that today calls lookupTemplate with a message or draft name through one unexported resolver implementing the same rule; the "postcard: unknown template <name>" text is unchanged for names that resolve to nothing.
- postcard, mailer.go: when the resolver maps msg.Template to a different base, ask the override source for msg.Template first and, when that returns no template override, for the base and take only its template override (layouts, partials and Branding are identical in both answers). Render the base file with that override. Update the Send doc comment: postcard still picks no locale; it resolves a missing `<template>-<locale>` to the default-locale version.
- postcard, editor.go: template drafts accept a fallback-locale name (resolver), using the base file's samples.
- postcard tests (smoke, Postgres): new subtest `locale_fallback` in TestMailOverrideSmoke: with a customized row for `acme.blog::mail.welcome-de` (created through EnsureLocaleRows then updated is_custom) Send of `welcome-de` uses its subject; Send of `welcome-fr` (no row) sends the base file, and after customizing the base row it sends the base customization; Send of `welcome-en` (own file) is unchanged; Send of `acme.blog::mail.missing-de` keeps the unknown-template error. Update `migrations_roll_back` to roll back every migration (one RollbackLast per entry of Migrations) before asserting no mail table is left.
- cabana, mail_admin.go: replace `locales()` by a `mailLocales(ctx)` returning the default and the union described in this plan's decisions (translator plus TranslationWriter when published). `sync` calls SyncIndex and then EnsureLocaleRows for all bases, remembers the locale set it synced with, and `ensureSynced` re-syncs when the current set differs. `FormExtendQuery` (record lookups) admits every row whose code is a catalog template or whose base_code is a catalog template's base (fallback rows); `ListExtendQuery` is unchanged in this task. `FormRecordTitle` shows the row's base code. `FormBeforeUpdate` stamps base_hash/file_hash from `catalog().TemplateFor(t.Code)` (the base file's hash for a fallback row). The mail templates controller implements a new unexported interface (sibling of recordDeletable, e.g. `recordLocaleVariants`) that first calls EnsureLocaleRows for this record's base only (idempotent; it keeps a newly enabled locale reachable without a restart) and then returns the variants of the record's group in the switcher order of this plan, each with the row id, locale, a translated label (`mail.template.locale_default` for Default, else the locale code), translated state words (`mail.state_customized`, `mail.state_outdated`) and Current for the open row.
- cabana, mail_routes.go: `mailTemplateDraft` accepts a code `TemplateFor` resolves (preview and test send of a fallback row).
- cabana, relation_field.go + crud.go: `RecordMeta.LocaleVariants []RecordLocaleVariant` with json `localeVariants,omitempty`; exported `RecordLocaleVariant{ID uint, Locale string, Label string, States []string, Current bool}` (json camelCase); ShowRecord fills it inside its transaction when the controller implements the unexported interface. Regenerate `admin/openapi/admin.json` and `admin/src/api/schema.d.ts` with `scripts/check-admin-openapi.sh`.
- SPA: new `admin/src/components/form/LocaleVariantSwitcher.vue`: a labelled native select (label text `backend::lang.form.locale_variant`, markup and classes copied from MLField's locale select, attribute `data-locale-variant`), one option per variant with the text "Label" or "Label — state, state", the current one selected. On change it router-pushes the same route with the chosen id; when the navigation is refused (unsaved-changes confirm cancelled) it puts the selection back. FormView reads `record.meta.localeVariants` next to `deletable` and renders the switcher in the header under the title when there are two or more variants. Copy `form.locale_variant` en/pl in the phrasebook.
- Tests in this task (smoke): `TestMailScreensSmoke/locales` in mail_screens_smoke_test.go, on an env with a fake TranslationWriter published (EnabledLocales pl, en, de; DefaultLocale pl): GET of welcome's update record returns localeVariants Default (current), de (no states), en; GET of the de id shows code-based title welcome; PUT a subject on the de row gives 200 and is_custom; the published Mailer's Send of `acme.blog::mail.welcome-de` uses that subject and Send of `acme.blog::mail.welcome` does not; POST /mail/preview for the de id answers 200. `admin/tests/form/LocaleVariantSwitcher.test.ts`: renders options with labels and states, marks the current one, pushes the sibling id on change and restores the selection when the push is rejected.
- Docs in the same commit (CLAUDE.md documentation rules): postcard README (API reference rows for TemplateBase, Catalog.TemplateFor and EnsureLocaleRows; the send-resolution rule in Usage; the base_code column under "Index rows, drift and reset"), cabana README (RecordMeta.LocaleVariants row, the mail locales source), docs/services/mail.md ("Sending": replace the "postcard does not pick a locale" paragraph with the resolution rule and the dash-suffix convention), docs/backend/forms.md (`meta.localeVariants` next to `meta.deletable`).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailOverrideSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailOverrideSmoke/locale_fallback" line</fails_when>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- |FAIL|ok|PASS)' | tail -30</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailScreensSmoke/locales" line</fails_when>
<automated>npm --prefix admin run test -- tests/form/LocaleVariantSwitcher.test.ts tests/form/FormViewMail.test.ts 2>&1 | tail -8 && npm --prefix admin run typecheck</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go vet ./... && go test -short ./... && bash scripts/check-admin-openapi.sh --check</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "202611130001_mail_template_base_code" modules/postcard/store.go` prints one line
- `grep -n "^func EnsureLocaleRows\|^func TemplateBase\|^func (c \*Catalog) TemplateFor" modules/postcard/*.go` prints three lines
- `grep -n "localeVariants,omitempty" modules/cabana/relation_field.go` prints one line and `grep -c "localeVariants" admin/openapi/admin.json` prints a number above 0
- `grep -n "postcard.EnsureLocaleRows" modules/cabana/mail_admin.go` prints at least two lines (sync and the show hook)
- `grep -n "LocaleVariantSwitcher" admin/src/views/FormView.vue` prints at least one line
- `grep -n "locale_variant" modules/phrasebook/backend/lang/en/lang.yaml modules/phrasebook/backend/lang/pl/lang.yaml` prints two lines
- `grep -n "EnsureLocaleRows\|TemplateFor" modules/postcard/README.md` prints at least two lines
</acceptance_criteria>
<done>An administrator can open a template, switch to a locale that ships no file, save its own version, and mail sent for that locale uses it, while every file-backed name sends as before.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: One list row per template with customized locales and grouped states; per-locale info, file version, show and reset for fallback locales; dist rebuild</name>
<reversibility rating="reversible">List presentation and partial content only; no schema or published API change beyond Task 1.</reversibility>
<files>modules/postcard/store.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/backendscreens/models/mailtemplate/columns.yaml, modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml, modules/cabana/backendscreens/controllers/mailtemplates/_info.htm, modules/cabana/mail_screens_smoke_test.go, modules/cabana/mail_unit_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md, modules/boardwalk/dist</files>
<behavior>
- The templates list of the fixture (welcome, welcome-en, a fallback de row) has exactly one row for welcome; its Customized locales value is empty, then "de" after the de row is saved, then "Default, de" after the base is saved too
- Saving only the de row gives the welcome list row the customized badge; a changed base file after that gives it the outdated badge too; the status filter customized / not_customized / outdated returns the welcome row accordingly
- GET of a not-customized de row returns the base row's current subject, body and layout (the base customization when there is one); after a de save it returns de's own values
- The info partial of a de row says the fallback line with :locale de; of the Default row the default line; the file version partial of a de row compares with the base file
- The reset record action on a customized de row returns it to not customized and its show to the default version; ResetOverride of a fallback code no longer errors
- The list config no longer declares a locale filter scope, and `FilterOptions` no longer serves one
</behavior>
<read_first>
- modules/cabana/mail_admin.go (~281-330 model and filter scopes, ~438-610, ~654-760 status helpers and reset action, ~1290-1420 info/file version views)
- modules/cabana/backendscreens/models/mailtemplate/columns.yaml, controllers/mailtemplates/config_filter.yaml, _info.htm, _file_version.htm
- modules/cabana/list_schema.go (~280-290: a `gorm:"-"` field filled by ListExtendRecords is an unstored, unsortable column)
- modules/postcard/store.go ResetOverride (~452-497)
- modules/cabana/mail_screens_smoke_test.go (Task 1's locales subtest, ~252-300 templates, ~542-600 drift)
</read_first>
<action>
Per G-35-1 (supersedes D-05; D-06 reset and D-07 drift now per locale):
- List scope: `ListExtendQuery` keeps one representative row per group: the base row when the base has a file, otherwise the group's lowest code (computed in Go from the catalog and the current mail locales); search, sort and paging work on those rows as before.
- Columns: replace the locale column with `customized_locales` (label `mail.template.customized_locales`), an unstored `gorm:"-"` field on MailTemplate filled in ListExtendRecords from one grouped query over the page's base codes: the labels of the customized rows (Default for the base, else the locale code) joined by ", ", at most three then " +N"; empty when none. Keep code, subject, description, layout and customized_at.
- Row states: `ListRowStates` aggregates per group (one grouped query per page): customized when any row of the group is customized, outdated when any customized row's base_hash differs from its file_hash. The status filter applies to the group (base_code in / not in the set of customized, resp. outdated, groups). Remove the locale scope from config_filter.yaml and the locale branch of FilterScopes, FilterScope and FilterOptions; drop the now-unused Default label code in ListExtendRecords.
- Show: a not-customized fallback row's show data carries the base row's current subject, body and layout (and the layout relation label), through the existing recordDataExtender seam or an equivalent unexported seam, so the form shows what that locale sends now.
- Partials: `_info` adds, for a group with two or more variants, `mail.info_locale_default` on the Default row and `mail.info_locale_fallback` (:locale) on a fallback row; a fallback row's file line names the base file. `_file_version` of a fallback row compares the override with the base file (TemplateFor) and, when not customized, shows the base file under the existing not-customized text.
- Reset: `postcard.ResetOverride(KindTemplate, code)` accepts a fallback-locale code (TemplateFor): it writes the base file's subject, body, layout and hash and clears the override columns; the record action's Applies stays "customized". Update the postcard README reset paragraph in this commit.
- Copy en/pl: `mail.template.customized_locales`, `mail.info_locale_default`, `mail.info_locale_fallback` with this plan's texts.
- Tests (smoke): `TestMailScreensSmoke/locales_list` covering the behavior list; update `templates` (no locale column; one welcome row) and `drift` (no locale filter); in mail_unit_test.go drop or rewrite any test of the removed locale filter options (TestMailLocale of TemplateLocale itself stays).
- Docs in the same commit: cabana README (Mail templates paragraph: one row per template, customized locales column, the switcher, the status filter only; the TestMailScreensSmoke description), docs/services/mail.md ("Editing mail in the admin": replace the "one row per file" sentence).
- Then rebuild the embedded admin (`npm --prefix admin ci` when node_modules is missing, `npm --prefix admin run build`), commit `modules/boardwalk/dist` alone with the build subject, and run `scripts/check-admin-dist.sh`.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke|TestMailLocale|TestMailDrift|TestMailReset|TestMailSave' -count=1 -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|locales_list' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailScreensSmoke/locales_list" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>bash scripts/check-admin-dist.sh && go run ./cmd/summer docs:build --check 2>&1 | tail -3</automated>
<fails_when>non-zero exit or an "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "customized_locales" modules/cabana/backendscreens/models/mailtemplate/columns.yaml` prints one line
- `grep -c "scope:" modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml` prints 1
- `grep -n "info_locale_fallback\|info_locale_default" modules/cabana/backendscreens/controllers/mailtemplates/_info.htm` prints at least one line
- `grep -n "customized_locales\|info_locale_fallback" modules/phrasebook/backend/lang/pl/lang.yaml` prints at least two lines
- `git log -1 --format=%s -- modules/boardwalk/dist` prints `build(admin): rebuild the embedded admin for the mail locale switcher`
</acceptance_criteria>
<done>The templates list has one row per template whatever the number of locales, each locale has its own customized / reset / drift status inside the one record, and the embedded admin carries the switcher.</done>
</task>
<task type="auto">
<name>Task 3: Decision note superseding D-05 and the UI-SPEC locale switcher contract</name>
<files>.planning/notes/2026-11-13-mail-template-locale-groups.md, .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md</files>
<read_first>
- .planning/notes/2026-11-06-admin-code-editor-codemirror.md (note format: Date, Status, Context, Decision, Rejected alternatives)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md sections "Lists", "C3b. Template form", "C9" and the UI Considerations rows on the locale filter
- Task 1 and Task 2 commits (`git show --stat HEAD~2..HEAD`) and the SUMMARY notes of what shipped
</read_first>
<action>
Planning docs only, one commit, separate from code (CLAUDE.md):
- `.planning/notes/2026-11-13-mail-template-locale-groups.md` (Status: Accepted; Context: 35-UAT G-35-1, user decision 2026-11-13): states that D-05 ("locale variants stay separate templates") is superseded; records as shipped the group key (base_code), the mail-locales source (translator plus TranslationWriter, default locale), the variant set and order, fallback-locale rows and what they show, per-locale customize / reset / drift, the send-resolution rule with its tag pattern and the unchanged behaviour for names with files (core plugins unaffected), the removed locale filter, `RecordMeta.LocaleVariants`; rejected alternatives: multilingual fields (mltext/mlmarkdown) in one record (no per-locale layout, reset or drift), a form-level `?locale=` query parameter (FormView changes for every controller), rows for every locale created only on first save (a locale not yet customized could not be opened). Follow-up (out of this phase): plugins that want per-locale admin versions pass `<template>-<locale>` for every locale (sm-user-plugin's MailTemplate maps only en today); postcard resolves a missing file to the default-locale version.
- 35-UI-SPEC.md: add a section "C16. Template locale switcher (gap closure G-35-1, supersedes the D-05 parts of C3b)" with the switcher markup (labelled native select from MLField, `data-locale-variant`, option text "Label — states"), placement (header under the title, two or more variants), navigation and the unsaved-changes confirm, the variant order, the list changes (one row per template, Customized locales column, no locale filter, grouped badges), the info lines and the four new copy keys with en/pl text; mark the superseded rows in "Lists", C3b and the UI Considerations table with "superseded by C16" rather than deleting them.
Commit as listed in Execution units.
</action>
<verify>
<automated>test -f .planning/notes/2026-11-13-mail-template-locale-groups.md && grep -c "D-05" .planning/notes/2026-11-13-mail-template-locale-groups.md && grep -n "C16" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md | head -3</automated>
<fails_when>non-zero exit, a count of 0, or no C16 line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "superseded" .planning/notes/2026-11-13-mail-template-locale-groups.md` prints at least one line
- `grep -c "superseded by C16" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` prints a number above 0
- `git log -1 --format=%s -- .planning/notes/2026-11-13-mail-template-locale-groups.md` prints the Task 3 subject and that commit touches no file outside .planning/
</acceptance_criteria>
<done>The superseded decision and the shipped switcher contract are on record for verification and later phases.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin browser → cabana mail template routes | administrators holding system.manage_mail_templates read and save template rows, now including fallback-locale rows |
| plugin code → postcard Send | plugins pass template names; a name without a file now resolves to its base |
| cabana show hook → database | a GET may insert missing fallback-locale index rows |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-29 | Elevation of privilege | locale variant ids in meta.localeVariants | medium | mitigate | the switcher only lists rows of the same group; every id is still loaded through the controller's RequiredPermissions and FormExtendQuery scope (catalog templates and their fallback rows), so an id outside the catalog is a 404 (TestMailScreensSmoke/locales) |
| T-35-30 | Tampering | fallback-locale saves | high | mitigate | FormAfterUpdate validates through postcard Editor.Validate exactly as file rows (D-13); a refused draft rolls the save back |
| T-35-31 | Spoofing | send-time name resolution | low | mitigate | only a two-letter language tag after a dash, on a registered base of the same name, resolves; the base is in the same plugin namespace, so no plugin can reach another plugin's template through a suffix; other unknown names keep the unknown-template error |
| T-35-32 | Denial of service | EnsureLocaleRows on show and sync | low | mitigate | the show hook ensures only its own group; the full ensure runs at sync under the shared advisory lock; inserts are idempotent and bounded by templates × locales |
| T-35-33 | Information disclosure | localeVariants labels | low | accept | labels are locale codes and state words the administrator already sees in the list |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package (npm ci only restores the committed lockfile) |
</threat_model>
<verification>
- `go vet ./... && go test -short ./...` and `go test ./modules/postcard ./modules/cabana` green after every code commit.
- `scripts/check-admin-openapi.sh --check` and `scripts/check-admin-dist.sh` pass after Task 2.
- `npm --prefix admin run test` and `npm --prefix admin run typecheck` pass.
- `go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree'` and `go run ./cmd/summer docs:build --check` pass.
- `bash scripts/check-phase35.sh --consumers --additive` passes (core plugins send unchanged; postcard and cabana changes additive).
</verification>
<success_criteria>
- One list row per template; customized locales and grouped badges shown; locale filter gone.
- Locale switcher in the template form; per-locale customize, reset and drift; fallback locales show and send the default version until customized.
- Send of `<template>-<locale>` resolves file → customization → default customization → default file; file-backed names unchanged.
- D-05 superseded on record; UI-SPEC C16 added; READMEs and docs updated in the code commits; nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md` when done; list the exact exported names (TemplateBase, Catalog.TemplateFor, EnsureLocaleRows, RecordMeta.LocaleVariants, RecordLocaleVariant), the migration ID, the copy keys and the test names, because 35-06 and 35-07 build on them.
</output>
## Follow-ups outside this phase (not planned here)
- sm-user-plugin: `classes.MailTemplate` could pass `<base>-<locale>` for every resolved locale (not only en) so per-locale admin versions apply to its mail; postcard already resolves a locale without a file to the default version. This belongs to the plugin follow-up after the framework tag, together with the button partial and layout work of G-35-8.
- sm-demo-app: before re-running UAT test 1, reset the UAT overrides of `golem15.user::mail.activate` and `golem15.user::mail.layouts.user` (35-UAT G-35-8 "Demo" item).
</content>
</invoke>

View File

@@ -0,0 +1,362 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 06
type: execute
wave: 6
depends_on: ["35-05"]
gap_closure: true
gap_ids: [G-35-8]
files_modified:
- modules/postcard/assets/default.htm
- modules/postcard/assets/system.htm
- modules/postcard/assets/minimal.htm
- modules/postcard/assets/brand.css.tmpl
- modules/postcard/assets/partials/header.htm
- modules/postcard/assets/partials/footer.htm
- modules/postcard/templates.go
- modules/postcard/partials.go
- modules/postcard/mailer.go
- modules/postcard/brand.go
- modules/postcard/store.go
- modules/postcard/editor.go
- modules/postcard/inline.go
- modules/postcard/brand_smoke_test.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/override_smoke_test.go
- modules/postcard/override_test.go
- modules/postcard/mailer_test.go
- modules/postcard/README.md
- go.mod
- go.sum
- modules/cabana/mail_admin.go
- modules/cabana/mail_routes.go
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
- modules/cabana/backendscreens/models/maillayout/fields.yaml
- modules/cabana/mail_screens_smoke_test.go
- modules/cabana/README.md
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- docs/services/mail.md
- .planning/research/STACK.md
- .planning/notes/2026-11-13-mail-layouts-css-inlining.md
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
autonomous: true
requirements: [G-35-8, D-10, D-11, D-12, D-14]
estimate:
tokens: 130000
raw_tokens: 130000
tasks: 3
confidence: low
must_haves:
truths:
- "A template previewed or sent in the default layout shows a white card on the body background, a header with the Branding logo (or the site name when no logo is set) and a footer with the copyright year and site name, as WinterCMS's default layout does (G-35-8)"
- "The system layout has the same header (logo or name) and footer and its content cell has side padding; the minimal layout shows the logo above the message when one is set (G-35-8)"
- "Mail branding has a Site name field; when it is empty the display name of mail.from is used; the header, footer and the logo's alt text use it (supersedes part of D-10)"
- "Sent and previewed HTML carries the brand and layout CSS inline on each element (the button partial's link has the brand button colour in its style attribute), so mail clients that drop the style block still show the design; rules that cannot be inlined (media queries) stay in a style block (supersedes D-10's inlining claim)"
- "A layout opts out of inlining with the file header key disable_auto_inline_css or the layout form's switch, and then keeps only its style block (WinterCMS parity)"
- "A failing inliner never stops mail: the message is sent with the style block only and a rate-limited warning is logged (D-14 spirit)"
- "Mail that works today keeps working: sm-user-plugin and sm-paymentgateway-plugin mail tests pass against this checkout without any change to those repositories"
prohibitions:
- statement: "No file in sm-user-plugin, sm-paymentgateway-plugin or any other sibling repository is changed; plugin layouts, templates and go.mod bumps are the follow-up after the framework tag."
status: unresolved
verification: judgment
- statement: "The new Go dependency is github.com/vanng822/go-premailer pinned exactly at v1.38.0, recorded in a decision note and a STACK.md row committed before go.mod changes; no other new direct dependency."
status: unresolved
verification: automated
- statement: "Every postcard and cabana API change is additive (check-phase35.sh additive stage); pact is untouched."
status: unresolved
verification: automated
- statement: "Nothing is pushed or tagged."
status: unresolved
verification: judgment
artifacts:
- path: "modules/postcard/assets/default.htm"
provides: "WinterCMS default layout port with header, card and footer"
contains: "layout-default"
- path: "modules/postcard/assets/partials/header.htm"
provides: "built-in header partial (logo or name)"
contains: "logo"
- path: "modules/postcard/inline.go"
provides: "CSS inlining at render"
contains: "premailer"
- path: ".planning/notes/2026-11-13-mail-layouts-css-inlining.md"
provides: "decision note: go-premailer, supersedes D-10 inlining claim and the 35-01 default.htm gate"
contains: "go-premailer"
key_links:
- from: "modules/postcard/templates.go"
to: "modules/postcard/inline.go"
via: "renderParts inlines the HTML wrapper output unless the layout opts out"
pattern: "inlineCSS"
- from: "modules/postcard/mailer.go"
to: "modules/postcard/assets/default.htm"
via: "siteName and year layout keys feed the header and footer partial calls"
pattern: "siteName"
- from: "modules/postcard/store.go"
to: "modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml"
via: "the site_name column of the branding row is the Branding form's Site name field"
pattern: "site_name"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, and the mail looks finished out of the box. This gap-closure plan fixes the framework part of UAT gap G-35-8: no shipped layout printed the logo, the default layout was a bare block, the system layout had no header, footer or side padding, and CSS was never inlined although D-10 and the UI-SPEC said it was.
Source: 35-UAT.md (G-35-8, test 8, severity major), .planning/debug/mail-layouts-unstyled.md (root cause), user decision of 2026-11-13 (framework only; plugin layouts and templates follow after the framework tag).
<objective>
- Port WinterCMS's default layout (wrapper, header with logo or name, white card, footer) to postcard's `default.htm` and its text wrapper, with built-in `header` and `footer` partials.
- Give the header and footer a display name: a new Site name in Mail branding, falling back to the display name of `mail.from`.
- Finish `system.htm` (header, logo, footer, side padding) and `minimal.htm` (logo), and the brand CSS rules they need.
- Inline CSS onto elements at render through github.com/vanng822/go-premailer, with a per-layout opt-out (file header key and layout form switch), recorded in a decision note and STACK.md.
- Update the postcard and cabana READMEs, docs/services/mail.md and the UI-SPEC texts; the decision note supersedes D-10's inlining claim and lifts 35-01's "default.htm unchanged" gate.
Purpose: an application that never touches the mail screens sends good-looking mail, and Branding (colours, logo, name) shows in every built-in layout, in the preview and in real mail clients.
Output: commits in this repository only (code, planning docs separately). Nothing in sibling repositories, nothing pushed or tagged.
**Planner decisions recorded here (Claude's discretion within the user's 2026-11-13 decision):**
- **Layout keys.** Both wrappers of every layout get two new keys next to `Content`, `Subject`, `css`, `brandCss` and `logoUrl`: `siteName` (Branding Site name, else the display name of `mail.from` parsed with net/mail, else empty) and `year` (the current year at render).
- **Header partial** `postcard::mail.partials.header` (callable as `header`): arguments `logo` (URL), `body` (name), optional `url` (link around logo or name). HTML: a table row with `td.header` holding `img.logo` (alt = body) when logo is set, else a `span` with the name; text section: the name. **Footer partial** `footer`: argument `body` rendered as Markdown inside Winter's `table.footer` row; text section: a rule line and the body.
- **Footer text is language-neutral**: `© <year> <siteName>` (just `© <year>` when there is no name). Winter's English "All rights reserved." is left out because a built-in layout serves every locale; an administrator can override the layout.
- **Header shows logo or name, not the subject** (Winter shows the subject; the user asked for logo or name). The header row is omitted when there is neither.
- **Inlining** runs inside postcard's render path, so preview, test send and real sends match: after the HTML wrapper renders and passes the safety checks, unless the layout opts out, the HTML is passed through go-premailer with its default options (CSS also mirrored to attributes such as bgcolor/width; classes kept so plugin CSS hooks still match), and the final HTML is checked again. An inliner error keeps the un-inlined HTML and logs a rate-limited warning. The text part is never touched.
- **Opt-out** keeps WinterCMS's option name: file layout header key `disable_auto_inline_css` (true, 1 or yes, any case) and a boolean column of the same name on the layouts table, edited by a switch on the layout form's CSS tab. Built-in layouts all inline.
- **New copy** (en/pl): `mail.brand.site_name` ("Site name" / "Nazwa witryny"), `mail.brand.site_name_comment` ("Shown in the header and footer of the built-in layouts. Leave it empty to use the sender name from mail.from." / "Wyświetlana w nagłówku i stopce wbudowanych układów. Zostaw puste, aby użyć nazwy nadawcy z mail.from."), `mail.layout.disable_inline_css` ("Do not inline CSS" / "Nie wstawiaj CSS do elementów"), `mail.layout.disable_inline_css_comment` ("By default the CSS is also copied into each element's style attribute, so mail clients that drop the style block still show it. Turn this on to keep the style block only." / "Domyślnie CSS jest też kopiowany do atrybutu style każdego elementu, aby klienty poczty usuwające blok stylów nadal go pokazywały. Włącz, aby zostawić tylko blok stylów."); changed: `mail.brand.logo_comment` ("The built-in layouts show the logo in their header. Your own layouts show it where they use {{ .logoUrl }}." / "Wbudowane układy pokazują logo w nagłówku. Własne układy pokazują je tam, gdzie używają {{ .logoUrl }}.").
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
@.planning/debug/mail-layouts-unstyled.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-CONTEXT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md
@CLAUDE.md
<interfaces>
- modules/postcard/assets/: default.htm (bare `content-body` block today), system.htm (Winter wrapper/content/body/inner-body/content-cell tables and the subcopy partial, no header/footer), minimal.htm (bare body), brand.css.tmpl (Winter rules incl. `.header`, `.footer`, `.button-*`; `.wrapper.layout-system .content-cell { padding: 35px 0; }` removes the side padding), partials/{button,panel,subcopy,table}.htm (header `name`, `==` text `==` HTML).
- WinterCMS reference: ../examples/golem15-wintercms-starter/modules/system/views/mail/layout-default.php, layout-system.php, partial-header.php, partial-footer.php; modules/system/classes/MailManager.php renderTemplate (~173-199: CssToInlineStyles unless the layout option disable_auto_inline_css).
- modules/postcard/templates.go: `builtinPartials` (~41), `NewCatalog` (~105) loads built-in layouts and partials, `parseLayout` (~345, header keys via parseINI), `renderOptions` (~465: css, brandCSS, logoURL, overrides, warn), `renderParts` (~571: HTML wrapper exec ~625, validateHTML ~635), `renderLayout` (~652), `layoutByCode` (~687), `LayoutFile` (~777), `FormatLayout` (~904).
- modules/postcard/mailer.go: `Options.From`, `(*mailer).options(brand)` (~139) builds renderOptions from config and Branding; `warn` (~183) is rate-limited.
- modules/postcard/brand.go: `Brand` (colours + LogoURL), `DefaultBrand`, `CompileBrandCSS` (only colours reach the CSS).
- modules/postcard/store.go: `Migrations` (35-05 added `202611130001_mail_template_base_code`), `LayoutOverride{Name, HTML, Text, CSS}` (~177), `dbSource.MailOverrides` layouts query (~248), `dbSource.brand` (~281), `SyncIndex` layouts upsert (~369), `ResetOverride` layouts (~471).
- modules/postcard/editor.go: `Draft` (~30), `renderLayout` (~240), `renderBrand` (~313) sets brandCSS and logoURL from the draft.
- Tests asserting today's default layout markup (`content-body`): brand_smoke_test.go (~194), override_smoke_test.go (~322, ~334), override_test.go (~189), mailer_test.go (~91); partials_smoke_test.go (~351) asserts the minimal layout's exact body.
- modules/cabana/mail_admin.go: `MailBrandSetting` (~1475, Fillable, Rules, BeforeValidate), `MailLayout` (~333, Fillable ~773); modules/cabana/mail_routes.go `mailLayoutDraft` (~535), `mailBrandDraft` (~574).
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml (logo first, then colours, then `_preview`), models/maillayout/fields.yaml (CSS tab: `content_css`, `_preview_css`).
- Sibling consumers use `replace git.golem15.com/golem15/summercms => ../summercms.go`; their go.sum lacks any new module, so checks against this checkout must use a scratch `-modfile` copy (never write their go.mod/go.sum).
- go-premailer (checked at planning, 2026-11-13): module github.com/vanng822/go-premailer, package `premailer`, v1.38.0 published 2026-11-04 (v1.37.0 2026-10-02; roughly monthly releases), MIT, imported by 246 packages; API `NewPremailerFromString(doc string, options *Options) (Premailer, error)`, `Premailer.Transform() (string, error)`, `NewOptions(...)` with `RemoveClasses` (false), `CssToAttributes` (true), `KeepBangImportant`; it collects the document's style elements, applies rules by specificity and puts rules it cannot inline back in a style element. Its go.mod requires PuerkitoBio/goquery v1.13.0, inbucket/html2text v1.0.0, vanng822/css v1.0.1 and golang.org/x/net v0.62.0 (this repository is at v0.58.0, so MVS raises x/net).
</interfaces>
</context>
## Execution units and resume points
- Other sessions edit postcard, cabana and docs concurrently. Before each task run `git status --short modules/postcard modules/cabana modules/phrasebook docs go.mod go.sum .planning/research` and stop if another session holds uncommitted edits in files this task touches. `examples/hello/plugins.gen.go` carries another session's edit: never stage it.
- Stage by explicit path; code and planning docs in separate commits; `go vet ./...` and `go test ./...` green at every code commit. Docker-backed tests without `-short` (through `sudo -u golem` if the socket is denied).
- Resume check: `git log --format=%s -F --grep='<subject>'`.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `feat(postcard): finished default layout with logo header, footer and site name` | TestMailBrandSmoke/default_layout passes |
| 2 | `docs(35): decision note for mail CSS inlining with go-premailer` then `feat(postcard): inline mail CSS at render with a per-layout opt-out` | TestMailPartialsSmoke/inline passes; consumers pass with a scratch modfile |
| 3 | `feat(postcard): header, logo, footer and padding in the system and minimal layouts` then `docs(35): UI-SPEC copy for inlining, site name and the layout opt-out` | TestMailPartialsSmoke/built_in_layouts passes; UI-SPEC updated |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "Branding with a logo and a site name is saved, and a template previewed and sent in the default layout shows the logo header, the white card, a styled button and the footer" — default layout only</name>
<reversibility rating="costly">The site_name column is a migration on postcard's branding table; the header and footer partial names and the siteName/year layout keys become part of the published layout format plugins and administrators write against.</reversibility>
<precondition>35-05 is complete: `git log --format=%s -F --grep='docs(35): decision note superseding D-05'` prints one line</precondition>
<files>modules/postcard/assets/default.htm, modules/postcard/assets/partials/header.htm, modules/postcard/assets/partials/footer.htm, modules/postcard/assets/brand.css.tmpl, modules/postcard/templates.go, modules/postcard/partials.go, modules/postcard/mailer.go, modules/postcard/brand.go, modules/postcard/store.go, modules/postcard/editor.go, modules/postcard/brand_smoke_test.go, modules/postcard/override_smoke_test.go, modules/postcard/override_test.go, modules/postcard/mailer_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md</files>
<read_first>
- ../examples/golem15-wintercms-starter/modules/system/views/mail/layout-default.php, partial-header.php, partial-footer.php (structure to port)
- modules/postcard/assets/ (all files), modules/postcard/templates.go (~21-140 and ~465-700), modules/postcard/partials.go (how built-in partials are named and called), modules/postcard/mailer.go (~37-155), modules/postcard/brand.go, modules/postcard/store.go (~37-130 Migrations, ~279-338 brand), modules/postcard/editor.go (~305-330)
- modules/postcard/brand_smoke_test.go (~150-240 and the logo subtest), the assertions listed in interfaces
- modules/cabana/mail_admin.go (~1470-1560), modules/cabana/mail_routes.go (~570-620), modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
- .planning/debug/mail-layouts-unstyled.md (Resolution)
</read_first>
<action>
Lifts the 35-01 "default.htm unchanged" gate per the user's 2026-11-13 decision; extends D-10's Branding with a site name; D-11 precedence and D-12 partials are reused unchanged.
- postcard, brand.go: `Brand.SiteName string` (doc: shown by the built-in layouts' header and footer; not part of the CSS); CompileBrandCSS ignores it.
- postcard, store.go: append migration `202611130002_mail_brand_site_name` adding `site_name TEXT NOT NULL DEFAULT ''` to the branding table (Rollback drops it); `dbSource.brand` reads it into Brand.SiteName.
- postcard, templates.go/mailer.go: renderOptions gains `siteName` and `year`; `(*mailer).options` sets siteName from the trimmed Brand.SiteName when non-empty, else from the display name of `Options.From` (net/mail.ParseAddress; empty on error or no name), and year from the current time; renderParts passes `siteName` and `year` to both wrappers. Editor.renderBrand uses the draft brand's SiteName with the same From fallback.
- postcard, partials: add `header` and `footer` to the built-in partials with the argument contract in this plan's decisions; files `assets/partials/header.htm` and `assets/partials/footer.htm` in the file format (`name = "Header"` / `"Footer"`, `==` text, `==` HTML), HTML ported from Winter's partial-header/partial-footer (img.logo inside `td.header`, optionally wrapped in a link when `url` is given; footer `table.footer` with a `td.content-cell` holding the Markdown body).
- postcard, assets/default.htm: port Winter's layout-default: viewport meta, the existing style block, `table.wrapper.layout-default`; the header partial call when logoUrl or siteName is set; the content/body/inner-body/content-cell card holding Content; the footer partial with the language-neutral copyright. Text wrapper: Content, a blank line, the footer partial's text form. Keep `name = "Default"`.
- postcard, brand.css.tmpl: an `img.logo` rule (border 0, display inline-block, max-width 200px, max-height 60px, height auto, so the aspect ratio is kept) and `.header` spacing that fits a logo.
- Update every test that asserted the old bare `content-body` block (interfaces list) to the new card markup, in this commit. New subtest `TestMailBrandSmoke/default_layout`: a template using the button partial, sent with a Brand carrying LogoURL and SiteName, gives HTML with the logo URL in an `img` whose alt is the site name inside `td.header`, `class="inner-body"`, `class="button button-primary"` and `© <current year> <SiteName>`; with no logo the header holds the name in a span; with no Branding row and From "Acme <no-reply@acme.test>" header and footer say Acme; with no name and no logo there is no header row and the footer says only the year.
- cabana: `MailBrandSetting.SiteName` (column site_name) in Fillable and Rules (`nullable|max:255`), trimmed in BeforeValidate; fields.yaml `site_name` (text, span left, label/comment keys) right after the logo; `mailBrandDraft` maps `site_name` so the Branding preview shows it. Extend `TestMailScreensSmoke/branding`: saving site_name persists it and POST /mail/preview mode branding with values carrying site_name returns HTML containing it.
- Copy en/pl: `mail.brand.site_name`, `mail.brand.site_name_comment`, the changed `mail.brand.logo_comment` (texts in this plan's decisions).
- Docs in the same commit: postcard README (Built-in layouts table: default = Winter's default layout with header, card and footer; the header and footer partials and their arguments; layout keys `siteName` and `year`; Branding: Brand.SiteName and the mail.from fallback), cabana README (Branding fields include site_name), docs/services/mail.md (Built-in layouts, Partials, Branding).
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -run 'TestMailBrandSmoke|TestMailOverrideSmoke|TestMailPartialsSmoke|TestMailRenderSmoke|TestMailLayoutSmoke' -count=1 -v 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|default_layout' | tail -20</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailBrandSmoke/default_layout" line</fails_when>
<automated>go test ./modules/cabana -run 'TestMailScreensSmoke' -count=1 2>&1 | tail -3</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go vet ./... && go test -short ./... && (cd examples/hello && go test ./... 2>&1 | tail -3)</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "layout-default" modules/postcard/assets/default.htm` prints at least one line and `grep -n 'partial "header"' modules/postcard/assets/default.htm` prints one line
- `grep -n "202611130002_mail_brand_site_name" modules/postcard/store.go` prints one line
- `grep -n "SiteName" modules/postcard/brand.go` prints at least one line and `grep -n "siteName" modules/postcard/templates.go` prints at least two lines
- `grep -n "site_name" modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml` prints one line
- `grep -n "site_name" modules/phrasebook/backend/lang/en/lang.yaml modules/phrasebook/backend/lang/pl/lang.yaml` prints at least two lines
- `grep -n "siteName" modules/postcard/README.md docs/services/mail.md` prints at least two lines
</acceptance_criteria>
<done>Out of the box, mail in the default layout shows the Branding logo or the site name, a white card, a styled button and a footer, in the preview and in sent mail.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Decision note and STACK row for go-premailer, then CSS inlining at render with the per-layout opt-out</name>
<reversibility rating="costly">A new Go module in the framework's go.mod that every application and plugin building against postcard must carry in go.sum; the disable_auto_inline_css column and header key are part of the layout format.</reversibility>
<files>.planning/notes/2026-11-13-mail-layouts-css-inlining.md, .planning/research/STACK.md, go.mod, go.sum, modules/postcard/inline.go, modules/postcard/templates.go, modules/postcard/store.go, modules/postcard/editor.go, modules/postcard/partials_smoke_test.go, modules/postcard/brand_smoke_test.go, modules/postcard/override_smoke_test.go, modules/postcard/override_test.go, modules/postcard/mailer_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/backendscreens/models/maillayout/fields.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md</files>
<behavior>
- The default layout's HTML after render has a style attribute on the button partial's link containing the brand primary colour, keeps the DOCTYPE line, keeps class attributes, and still passes postcard's safety checks
- A media-query rule in a layout's CSS ends up in a style element of the output, not on elements
- A file layout with header key disable_auto_inline_css = true renders with its style block and no inlined style attribute on the button; a database layout with the column set does the same; a layout draft with the flag previews the same way
- An inliner error (forced through a test seam) sends the un-inlined HTML and logs one warning
- The plain-text part is identical with and without inlining
</behavior>
<read_first>
- .planning/notes/2026-10-28-webp-gen2brain.md (dependency note format) and .planning/research/STACK.md "Supporting Libraries" table
- ../examples/golem15-wintercms-starter/modules/system/classes/MailManager.php (~173-199)
- modules/postcard/templates.go (~345-365 parseLayout, ~565-700 renderParts/renderLayout/layoutByCode, ~777-786 LayoutFile), modules/postcard/store.go (~170-190 LayoutOverride, ~240-256, ~369-388, ~471-478), modules/postcard/editor.go (~28-50 Draft, ~240-270 renderLayout)
- modules/cabana/mail_admin.go (~333-350 MailLayout, ~769-780 Fillable, layout FormBeforeUpdate), modules/cabana/mail_routes.go (~535-556 mailLayoutDraft), modules/cabana/backendscreens/models/maillayout/fields.yaml
- scripts/check-phase35.sh run_consumers and workspace_check (how consumers resolve this checkout)
</read_first>
<action>
Supersedes D-10's claim that postcard already inlines the brand CSS (it only placed it in a style block); WinterCMS parity with MailManager::renderTemplate.
- First, planning docs commit: verify the module before writing (`go list -m -versions github.com/vanng822/go-premailer`; `go mod download -json github.com/vanng822/go-premailer@v1.38.0` for Time and Origin; the LICENSE is MIT; v1.38.0 was published at least 7 days ago). Write `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` (Status: Accepted; Context: 35-UAT G-35-8, debug session mail-layouts-unstyled, user decision 2026-11-13) recording: D-10's inlining sentence superseded; 35-01's "default.htm unchanged" gate lifted (default layout is now Winter's default layout with header and footer partials); Branding gains Site name with the mail.from fallback; the inlining decision (go-premailer exactly v1.38.0, default options, where it runs, error fallback, opt-out name and places); facts checked (publish dates, licence, maintainer, importers, its requirements, the x/net raise from v0.58.0 to what MVS selects, the transitive modules `go mod tidy` adds); the consequence that applications and plugins building with a `replace` to this checkout need `go mod tidy` (follow-up); rejected alternatives: an in-house inliner on x/net/html with douceur and cascadia (selector specificity and edge cases to own), github.com/aymerick/douceur/inliner (unmaintained since 2016), no inlining (UAT gap stays for clients that drop style blocks). Add a "Supporting Libraries" row to .planning/research/STACK.md naming the note. Commit these two files alone with the first subject.
- Then code: `go get github.com/vanng822/go-premailer@v1.38.0` and `go mod tidy` (commit go.mod and go.sum; if examples/hello needs go.sum lines, tidy its go.mod/go.sum only). If the module fails a fit check that its options cannot fix (lost DOCTYPE, output failing validateHTML, an error on the brand CSS selectors), stop and report instead of swapping libraries or hand-rolling.
- `modules/postcard/inline.go`: unexported `inlineCSS(html string) (string, error)` wrapping NewPremailerFromString + Transform with default options.
- templates.go: parseLayout reads `disable_auto_inline_css`; `LayoutFile.DisableAutoInlineCSS bool`; renderLayout carries the flag from the file or the override; renderParts, after the HTML wrapper passed validateHTML, inlines unless the flag is set, keeps the un-inlined HTML and calls opts.warn (key `inline:<layout code>`) on an inliner error, and runs validateHTML on the final HTML.
- store.go: append migration `202611130003_mail_layout_disable_auto_inline_css` (boolean NOT NULL DEFAULT FALSE on the layouts table); `LayoutOverride.DisableAutoInlineCSS bool` read by MailOverrides; SyncIndex mirrors the file header value for rows that are not customized; ResetOverride writes the file's value back.
- editor.go: `Draft.DisableAutoInlineCSS bool`, applied to layout drafts.
- cabana: `MailLayout.DisableAutoInlineCSS` in Fillable; maillayout fields.yaml gets a `disable_auto_inline_css` switch on the CSS tab above `content_css` with the label/comment keys; mailLayoutDraft maps it; a new custom layout starts with it off. Copy en/pl `mail.layout.disable_inline_css[_comment]`.
- Tests: update existing assertions that the inlined output changes (style attributes on elements, serializer differences) in this commit; new subtest `TestMailPartialsSmoke/inline` for the behavior list; extend `TestMailScreensSmoke/layouts` with a saved switch whose next send keeps the button without an inlined style attribute.
- Consumers without writing their trees: for each of ../sm-user-plugin and ../sm-paymentgateway-plugin copy go.mod and go.sum into a fresh scratch directory and run their named mail tests with `-mod=mod -modfile=<scratch>/go.mod` (after confirming with `go list -m -mod=mod -modfile=<scratch>/go.mod -f '{{.Replace.Dir}}' git.golem15.com/golem15/summercms` that the framework resolves to this checkout); `git -C <repo> status --porcelain` must stay empty.
- Docs in the same code commit: postcard README (Features and Usage: CSS inlined at render, the opt-out key and column, LayoutFile/LayoutOverride/Draft fields, error fallback; Dependencies: go-premailer), cabana README (layout form switch), docs/services/mail.md (Templates and layouts: style block plus inlining; the opt-out).
Commit as listed in Execution units (planning docs commit first, then the code commit).
</action>
<verify>
<automated>go test ./modules/postcard -count=1 -v -run 'TestMailPartialsSmoke' 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|/inline' | tail -12</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailPartialsSmoke/inline" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4 && (cd examples/hello && go test ./... 2>&1 | tail -3)</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>for r in ../sm-user-plugin ../sm-paymentgateway-plugin; do S=$(mktemp -d) && cp "$r/go.mod" "$r/go.sum" "$S"/ && (cd "$r" && go list -m -mod=mod -modfile="$S/go.mod" -f '{{.Replace.Dir}}' git.golem15.com/golem15/summercms) || exit 1; done; S=$(mktemp -d) && cp ../sm-user-plugin/go.mod ../sm-user-plugin/go.sum "$S"/ && (cd ../sm-user-plugin && go test -mod=mod -modfile="$S/go.mod" -short -count=1 -run '^(TestMail|TestPolishMailSubjects)$' . 2>&1 | tail -3); S=$(mktemp -d) && cp ../sm-paymentgateway-plugin/go.mod ../sm-paymentgateway-plugin/go.sum "$S"/ && (cd ../sm-paymentgateway-plugin && go test -mod=mod -modfile="$S/go.mod" -short -count=1 -run '^(TestMailCatalog|TestMailTracer|TestMailersMatrixSmoke)$' . 2>&1 | tail -3); git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "FAIL" line, a Replace.Dir that is not this checkout, or any porcelain output from either sibling repository</fails_when>
<automated>go run ./cmd/summer docs:build --check 2>&1 | tail -3 && bash scripts/check-phase35.sh --additive</automated>
<fails_when>non-zero exit or an "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "github.com/vanng822/go-premailer v1.38.0" go.mod` prints one line
- `grep -n "go-premailer" .planning/research/STACK.md` prints at least one line and `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` contains "D-10"
- `git log --format=%s -- .planning/notes/2026-11-13-mail-layouts-css-inlining.md` lists the docs subject on a commit older than the one that changed go.mod (`git log --format=%s -1 -- go.mod` is the feat subject)
- `grep -n "202611130003_mail_layout_disable_auto_inline_css" modules/postcard/store.go` prints one line
- `grep -n "disable_auto_inline_css" modules/cabana/backendscreens/models/maillayout/fields.yaml` prints one line
- `grep -n "go-premailer" modules/postcard/README.md` prints at least one line
</acceptance_criteria>
<done>Mail reaches clients with the design on every element unless the layout opts out, the dependency is on record before it entered go.mod, and the core plugins still pass against this checkout without being touched.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: Header, logo, footer and side padding in the system layout, logo in the minimal layout; UI-SPEC copy for inlining, site name and the opt-out</name>
<reversibility rating="reversible">Built-in asset markup and CSS only; the UI-SPEC text is documentation.</reversibility>
<files>modules/postcard/assets/system.htm, modules/postcard/assets/minimal.htm, modules/postcard/assets/brand.css.tmpl, modules/postcard/partials_smoke_test.go, modules/postcard/README.md, docs/services/mail.md, .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md</files>
<behavior>
- The system layout with a logo renders `img.logo` in `td.header` above the card, a footer row with the copyright line, and its content cell keeps the 35px side padding (no rule overrides it to 0)
- The system layout with no logo and a site name shows the name in the header
- The minimal layout with a logo shows the logo image above the message; without a logo its body holds only the message as before
- All three built-in layouts render the button partial with the brand button class and, after inlining, the brand colour on the link
</behavior>
<read_first>
- ../examples/golem15-wintercms-starter/modules/system/views/mail/layout-system.php
- modules/postcard/assets/system.htm, minimal.htm, brand.css.tmpl (as left by Tasks 1 and 2)
- modules/postcard/partials_smoke_test.go `built_in_layouts` subtest (~340-360)
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md sections C5 (CSS comment), C12 (Branding table), "Branding page" copy table and the `mail.brand.logo_comment` row
</read_first>
<action>
Finishes G-35-8 for the framework's built-in layouts (D-08's predefined layouts; D-10 Branding shown everywhere):
- system.htm: add the header partial call (logo or site name, same guard as default.htm) as the first row of `table.wrapper`, keep the card with Content and the subcopy, add the footer partial row after the card; text wrapper keeps its automatic-message line and ends with the footer's text form.
- brand.css.tmpl: drop the rule that sets the system layout's content cell padding to `35px 0` so the Winter `.content-cell` padding (35px) applies; check `.footer` and `.footer .content-cell` spacing against Winter's footer and keep the footer text centred.
- minimal.htm: when logoUrl is set, an `img.logo` (alt = siteName) in a paragraph above Content; nothing else changes.
- Tests: update `TestMailPartialsSmoke/built_in_layouts` for the behavior list (its exact-body assertion on the minimal layout becomes the without-logo case).
- Docs in the code commit: postcard README Built-in layouts table rows for system and minimal; docs/services/mail.md Built-in layouts.
- Then a planning-docs commit for 35-UI-SPEC.md: C5 CSS comment now true (inlining) plus a row for the `disable_auto_inline_css` switch on the CSS tab with its copy; C12 Branding table gets the `site_name` row after the logo with its copy, and the changed `mail.brand.logo_comment` text; a short note under C12 that the built-in layouts show logo or site name in the header and the copyright footer, referencing `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` as superseding D-10's inlining claim.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/postcard -count=1 -v -run 'TestMailPartialsSmoke' 2>&1 | grep -E '^\s*(--- FAIL|--- SKIP|FAIL|ok|PASS)|built_in_layouts' | tail -12</automated>
<fails_when>a "FAIL" line, a "--- SKIP" line, or no "--- PASS: TestMailPartialsSmoke/built_in_layouts" line</fails_when>
<automated>go vet ./... && go test -short ./... && go test ./modules/postcard ./modules/cabana -count=1 2>&1 | tail -4 && go run ./cmd/summer docs:build --check 2>&1 | tail -3</automated>
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -n 'partial "header"' modules/postcard/assets/system.htm` and `grep -n 'partial "footer"' modules/postcard/assets/system.htm` each print one line
- `grep -n "logoUrl" modules/postcard/assets/minimal.htm` prints at least one line
- `grep -c "layout-system .content-cell" modules/postcard/assets/brand.css.tmpl` prints 0
- `grep -n "site_name" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` and `grep -n "disable_auto_inline_css" .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md` each print at least one line
</acceptance_criteria>
<done>Every built-in layout (default, system, minimal) shows the Branding logo or name, and the design contract describes inlining, the site name and the opt-out as shipped.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| admin browser → Branding settings | administrators with system.manage_mail_layouts set the site name shown in every mail |
| admin browser → layout overrides | administrators write layout HTML and CSS that the inliner now copies onto elements |
| Go module proxy → go.mod | a new third-party module enters the framework binary |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-34 | Tampering | site name in layouts | medium | mitigate | the name reaches mail only through html/template (HTML-escaped, alt attribute contextually escaped) and the text template of the text part; it never goes into a header line; saved trimmed with max 255 characters (TestMailBrandSmoke/default_layout, TestMailScreensSmoke/branding) |
| T-35-35 | Tampering | CSS moved onto elements by the inliner | high | mitigate | layout CSS keeps the closing-style and dangerous-scheme checks at save; validateHTML runs on the final inlined HTML at every render, so a javascript:/vbscript:/data: URL that reaches a style attribute fails the render and the file version is sent (D-14) |
| T-35-36 | Denial of service | inliner on large or odd HTML | low | mitigate | content is administrator-authored and per message; an inliner error falls back to the un-inlined HTML with a rate-limited warning, mail is never blocked |
| T-35-37 | Tampering | github.com/vanng822/go-premailer and its requirements | medium | mitigate | exact pin v1.38.0 (published 2026-11-04, past the 7-day cooldown), go.sum verified against the checksum database, MIT licence and maintainer checked and recorded in the decision note before go.mod changes; transitive modules listed in the note |
| T-35-38 | Information disclosure | mail.from display name fallback | low | accept | the display name is already in every message's From header |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no npm, pip or cargo package; the Go module is T-35-37 |
</threat_model>
<verification>
- `go vet ./... && go test -short ./...`, `go test ./modules/postcard ./modules/cabana` and `cd examples/hello && go test ./...` green after every code commit.
- Consumer mail tests of sm-user-plugin and sm-paymentgateway-plugin pass through a scratch `-modfile` with their working trees unchanged. Until 35-07 Task 1 bakes that into the gate, `bash scripts/check-phase35.sh --consumers` (and so `--all`) is expected to fail on the siblings' missing go.sum lines for go-premailer; that is not a regression of this plan, but run the scratch-modfile command in Task 2's verify instead.
- `go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree'`, `go run ./cmd/summer docs:build --check` and `bash scripts/check-phase35.sh --additive` pass.
- No change under admin/ is expected; if one was needed, `npm --prefix admin run build`, the dist commit and `scripts/check-admin-dist.sh` are required (CLAUDE.md).
</verification>
<success_criteria>
- default, system and minimal layouts are finished (logo or name header, card, footer, padding) and the button partial is styled in all of them.
- Branding has Site name with the mail.from fallback.
- CSS is inlined at render with a per-layout opt-out; go-premailer recorded in a decision note and STACK.md before it entered go.mod.
- READMEs, docs and UI-SPEC describe what ships; D-10's inlining claim and the 35-01 default.htm gate are superseded on record; nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md` when done; list the migration IDs, the new layout keys, partial arguments, the exported fields (Brand.SiteName, LayoutFile/LayoutOverride/Draft DisableAutoInlineCSS), the exact go.mod changes (direct and indirect), the copy keys and the test names, because 35-07 tests them.
</output>
## Follow-ups outside this phase (not planned here)
After the framework release tag that contains 35-05 and 35-06 (tag only at phase completion, on the default branch, with Jakub's go-ahead):
- sm-user-plugin: bump the framework requirement (and `go mod tidy` for go-premailer); activate/restore/invite (+ -en) use `{{ partial "button" ... }}` instead of Markdown links; replace `layouts/user.htm` with a full layout built on the framework's structure and partials, keeping the name; fix its text wrapper.
- sm-paymentgateway-plugin: bump the framework requirement; order templates use the button partial and drop the duplicated URL; replace `layouts/paymentgateway.htm` keeping the name.
- Applications building with a `replace` to this checkout (sm-demo-app and others) run `go mod tidy` to pick up go-premailer's go.sum lines.
- sm-demo-app: reset the UAT overrides of `golem15.user::mail.layouts.user` and `golem15.user::mail.activate` before re-running UAT test 8.
</content>
</invoke>

View File

@@ -0,0 +1,273 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 07
type: execute
wave: 7
depends_on: ["35-05", "35-06"]
gap_closure: true
gap_ids: [G-35-1, G-35-8]
files_modified:
- scripts/check-phase35.sh
- modules/postcard/locale_test.go
- modules/postcard/locale_postgres_test.go
- modules/postcard/layouts_test.go
- modules/postcard/inline_test.go
- modules/cabana/mail_locale_postgres_test.go
- modules/cabana/mail_brand_layout_postgres_test.go
- admin/tests/form/LocaleVariantSwitcher.test.ts
- admin/tests/form/FormViewMail.test.ts
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
autonomous: true
requirements: [G-35-1, G-35-8, D-21]
estimate:
tokens: 110000
raw_tokens: 110000
tasks: 3
confidence: low
must_haves:
truths:
- "scripts/check-phase35.sh runs the consumer plugins through a scratch -modfile so it stays read-only with the new go-premailer requirement, refuses when a sibling tree becomes dirty, requires every new test by name, and --all passes (D-21)"
- "Unit tests cover locale grouping: TemplateBase and Catalog.TemplateFor rules (own file, fallback tag, pt-BR, longest base, non-locale suffixes, unknown names), the send order code-<locale> customization → default customization → default file with file-backed names unchanged, EnsureLocaleRows (rows only for non-default locales without files, idempotent, customized content kept, file_hash following the base), base_code in SyncIndex and reset of a fallback code (G-35-1)"
- "Unit tests cover the admin side of locale grouping: one list row per template, the customized-locales value, grouped badges and status filter, localeVariants order, labels, states and current flag, the default version shown on a not-customized fallback row, save then send, reset, drift through the base file, the file version against the base file, out-of-group ids and the permission split on fallback rows (G-35-1)"
- "Unit tests show a logo img (alt = site name) in the header of the default and system layouts and above the message in the minimal layout whenever Branding has a logo, the site name or nothing when it does not, the mail.from display-name fallback, and the footer's year and name (G-35-8)"
- "Unit tests show the button partial's output (class, href, type variants) in every built-in layout, CSS inlined onto elements with the DOCTYPE kept and media queries left in a style block, the plain-text part unchanged, the safety check on the inlined output, the per-layout opt-out (file header key, override column, layout draft, layout form switch) and the fallback when the inliner fails (G-35-8)"
- "SPA tests cover the locale switcher (options, current, navigation, restored selection when the unsaved-changes confirm is cancelled) and FormView showing it only with two or more variants (G-35-1)"
- "go vet ./... and go test ./... stay green; 35-VALIDATION.md maps G-35-1 and G-35-8"
prohibitions:
- statement: "No production code changes except fixes for defects the new tests expose, each in its own fix commit and recorded as a deviation in the SUMMARY."
status: unresolved
verification: judgment
- statement: "Tests and the gate never write into a sibling repository (git status --porcelain of sm-user-plugin and sm-paymentgateway-plugin stays empty) and never reach the network beyond localhost, httptest servers and testcontainers."
status: unresolved
verification: automated
- statement: "Nothing is pushed or tagged (tag only at phase completion, on the default branch, after Jakub's go-ahead)."
status: unresolved
verification: judgment
artifacts:
- path: "scripts/check-phase35.sh"
provides: "phase gate including the gap-closure tests (tracer)"
contains: "modfile"
- path: "modules/postcard/locale_test.go"
provides: "locale resolution unit tests"
contains: "func TestTemplateFor"
- path: "modules/postcard/inline_test.go"
provides: "CSS inlining and opt-out tests"
contains: "func TestInlineCSSOptOut"
- path: "modules/cabana/mail_locale_postgres_test.go"
provides: "grouped templates admin tests"
contains: "func TestMailLocaleGroups"
key_links:
- from: "scripts/check-phase35.sh"
to: "../sm-user-plugin"
via: "consumers stage runs the mail tests with a scratch -modfile copy of go.mod and go.sum"
pattern: "modfile"
- from: "scripts/check-phase35.sh"
to: "modules/cabana/mail_locale_postgres_test.go"
via: "DOCKER_TESTS requires TestMailLocaleGroups by name"
pattern: "TestMailLocaleGroups"
- from: "modules/postcard/layouts_test.go"
to: "modules/postcard/assets/default.htm"
via: "logo, header and footer assertions on the built-in layouts"
pattern: "TestBuiltinLayoutsLogo"
---
## Phase Goal
ROADMAP Goal (not in user-story format; no story is invented): administrators edit every mail the application sends from the admin panel, and mail that already works keeps working. Project rule 2 puts unit tests in the last plan of the phase; this plan is the last plan of the 35 gap closure and proves G-35-1 (35-05) and G-35-8 (35-06) with unit tests and the extended phase gate.
<objective>
- `scripts/check-phase35.sh`: a read-only scratch-modfile consumers stage (the core plugins' go.sum does not carry go-premailer yet), a dirty-tree refusal, and every new test required by name.
- postcard unit tests for locale resolution and fallback rows, built-in layouts (logo, header, footer, site name), the button partial and CSS inlining with its opt-out and failure fallback.
- cabana Postgres tests for the grouped templates screen, the Branding site name and the layout inlining switch; SPA tests for the locale switcher.
- `--all` green; 35-VALIDATION.md updated.
Purpose: D-21's "unit tests last" rule for the gap closure; the gate is what `/msd-verify-work` runs before UAT tests 1 and 8 are re-checked.
Output: test and gate-script commits in this repository; one planning-docs commit for 35-VALIDATION.md. No sibling repository is changed; nothing is pushed or tagged.
</objective>
<execution_context>
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
<context>
@.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md
@.planning/phases/35-mail-templates-and-layouts-editor/35-04-SUMMARY.md
@CLAUDE.md
<interfaces>
- Names to test come from 35-05-SUMMARY.md and 35-06-SUMMARY.md (where they differ from this plan, the SUMMARY wins): postcard.TemplateBase, (*Catalog).TemplateFor, postcard.EnsureLocaleRows, migration IDs 202611130001..003, Brand.SiteName, LayoutFile/LayoutOverride/Draft DisableAutoInlineCSS, layout keys siteName and year, built-in partials header and footer, unexported inlineCSS; cabana.RecordMeta.LocaleVariants / RecordLocaleVariant, MailTemplate customized_locales, MailBrandSetting.SiteName, MailLayout.DisableAutoInlineCSS; SPA LocaleVariantSwitcher.vue.
- Existing helpers: modules/postcard/override_smoke_test.go `mailPostgres(t)` (fresh migrated database per call) and `bootMailApp`; modules/postcard/override_test.go fake OverrideSource patterns; modules/cabana/mail_screens_smoke_test.go `newMailScreensEnvWith(t, mailEnvOptions{files, keep, mutate})` with fixture plugin acme.blog (`blogWelcome`, `blogWelcomeEn`), the fake TranslationWriter 35-05 added for the locales subtest, login/request helpers; admin/tests/form/FormViewMail.test.ts mount and router helpers.
- scripts/check-phase35.sh: GO_TESTS (Docker-free, never skip under -short), DOCKER_TESTS, ADMIN_FILES, ADMIN_BROWSER_FILES, USER_MAIL_TESTS, PAYMENTGATEWAY_MAIL_TESTS (~60-125); `go_named` anchors names (`^(A|B)$`, ~277); `workspace_check` (~348) runs `go list -m` in the sibling; `run_consumers` (~597) runs workspace_check, `go_vet` and `go_named` per sibling; `run_self_test` (~418) plants cases; `scratch_init`/`scratch_cleanup` (~685-700); `run_all` prints "Phase 35 gate passed" (~789).
- 35-06 Task 2 ran the consumer tests by hand with `-mod=mod -modfile=<scratch>/go.mod` and checked `Replace.Dir`; that is the command shape to bake in.
- Existing test names that must not be reused: TestOverride, TestFallback, TestPartial, TestSample, TestValidateDraft, TestBrand, TestStore, TestSync, TestMailLocale, TestMailDiff, TestMailFieldSchema, TestMailPermissions, TestMailSave, TestMailDrift, TestMailReset, TestMailLayoutDelete, TestMailBrand, TestMailTestSend and the *Smoke tests.
</interfaces>
</context>
## Execution units and resume points
- Before each task run `git status --short modules/postcard modules/cabana admin/tests scripts` and stop if another session holds uncommitted edits in files this task touches.
- Stage by explicit path. Tests are written against the shipped code; a defect a test exposes gets its own `fix(<module>): ...` commit before the test commit, recorded as a deviation. `go vet ./...` and `go test ./...` green at every commit. Docker-backed tests without `-short` (through `sudo -u golem` if the socket is denied).
- Each test task adds its new names to the gate's required arrays in the same commit as the tests, so the gate never requires a test that does not exist yet.
- Resume check: `git log --format=%s -F --grep='<subject>'`.
| Task | Commit subject | Resume point |
|------|----------------|--------------|
| 1 | `test(35): read-only consumers with a scratch modfile in check-phase35.sh` | `--self-test` and `--consumers` pass, sibling trees clean |
| 2 | `test(postcard): locale fallback, built-in layouts, partials and CSS inlining` | `--go` passes with the new names |
| 3 | `test(cabana): grouped mail templates, site name and the inlining switch`, `test(admin): mail template locale switcher`, then `docs(35): validation map for the gap closure` | `bash scripts/check-phase35.sh --all` passes |
<tasks>
<task type="tracer">
<name>Task 1: End-to-end "one command proves the gap closure leaves the core plugins' mail working, with the new go-premailer requirement, without writing their trees" — the consumers stage only</name>
<files>scripts/check-phase35.sh</files>
<read_first>
- scripts/check-phase35.sh (whole file)
- .planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md (the scratch-modfile command that worked, the go.mod changes)
</read_first>
<action>
Per D-21:
- Consumers stage: for each sibling, copy its go.mod and go.sum into a scratch directory created through the existing scratch helpers (removed by scratch_cleanup) and pass `-mod=mod -modfile=<scratch>/go.mod` to workspace_check's `go list -m`, to `go vet ./...` and to the named mail tests, so the framework's new requirement resolves without writing the sibling tree; after the runs, refuse with a `refuse:` line when `git -C <sibling> status --porcelain` prints anything. Keep the Docker rule (no -short when Docker answers). Update the stage's header comment.
- Self-test: add a planted case proving the dirty-tree refusal (a scratch git repository with an untracked file), and a planted case proving workspace_check under a modfile refuses a framework that resolves elsewhere; every existing self-test case stays green.
Commit as listed in Execution units.
</action>
<verify>
<automated>bash scripts/check-phase35.sh --self-test 2>&1 | tail -5</automated>
<fails_when>non-zero exit, or a planted case reported as undetected</fails_when>
<automated>bash scripts/check-phase35.sh --consumers 2>&1 | tail -6; git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "refuse:" or "FAIL" line, no "phase35 consumers passed" line, or any porcelain output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "modfile" scripts/check-phase35.sh` prints at least two lines
- `grep -n "status --porcelain" scripts/check-phase35.sh` prints at least one line
</acceptance_criteria>
<done>The gate proves the core plugins still send their mail against this checkout, read-only, even though their go.sum does not yet know go-premailer.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: postcard unit tests for locale resolution, fallback rows, built-in layouts, partials and CSS inlining</name>
<files>modules/postcard/locale_test.go, modules/postcard/locale_postgres_test.go, modules/postcard/layouts_test.go, modules/postcard/inline_test.go, scripts/check-phase35.sh</files>
<behavior>
- TestTemplateBase: welcome-en with locales en, pl gives welcome; welcome-pt-BR with pt-BR gives welcome; cancel-notice (not a locale) gives itself; a name without "::" gives itself
- TestTemplateFor: an own file returns itself; welcome-de (no file) returns the welcome file; welcome-pt-BR resolves per the shipped tag rule; order-paid-en picks order-paid over order when both exist; welcome-now, missing-de and a name in another namespace return false
- TestSendLocaleFallback (fake OverrideSource recording the names asked): welcome-de with a de override sends it; without it the welcome override; without both the welcome file; welcome-en (own file) asks only for welcome-en and is unchanged; the unknown-template error text is unchanged
- TestEnsureLocaleRows (Postgres): with locales pl, en, de and default pl over a catalog holding welcome and welcome-en, exactly one row welcome-de is created (none for pl or en) with base_code welcome and the base file's hash; a second run writes nothing (updated_at unchanged); a customized welcome-de keeps its subject when the base file changes while its file_hash follows; SyncIndex writes base_code for welcome-en; ResetOverride of welcome-de restores the base file content and clears the override; every migration rolls back and re-applies
- TestBuiltinLayoutsLogo: default, system and minimal with a Brand logo show an img with that URL and alt = site name (header cell in default and system, above the message in minimal); without a logo none shows it; without logo and with a name the default and system headers show the name; with neither, no header row
- TestHeaderFooterPartials: header with logo, with name only, with url (link wraps the content); footer holds © plus the current year and the name, or only the year; their text forms
- TestButtonPartial: class button button-primary by default, button-positive and button-negative with type, href is the url, the text form is "body <url>", in the default, system and minimal layouts
- TestSiteName: Brand.SiteName wins; empty uses the display name of mail.from; From without a display name or unparsable gives an empty name
- TestInlineCSS: the button link carries the brand primary colour in its style attribute; the DOCTYPE line is kept; a media-query rule from layout CSS stays in a style element; the text part equals the text part of the same message with inlining off; a dangerous URL that inlining moves into a style attribute fails the safety check and the file version is sent
- TestInlineCSSOptOut: file layout header key, LayoutOverride column and layout draft each leave the button without an inlined style while the style block remains
- TestInlineFailure: an inliner error (through the seam 35-06 shipped, or a package-level variable swapped in the test) sends the un-inlined HTML and logs one warning per key per minute
</behavior>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md and 35-06-SUMMARY.md (exact names, seams, test helpers)
- modules/postcard/templates.go, mailer.go, store.go, inline.go (as shipped)
- modules/postcard/override_test.go and override_smoke_test.go helpers; modules/postcard/brand_test.go (table-test style)
</read_first>
<action>
Per D-21 (unit tests last) for G-35-1 and G-35-8. Docker-free tests (every test above except TestEnsureLocaleRows) never call t.Skip under -short; TestEnsureLocaleRows lives in locale_postgres_test.go, skips under -short like the other Postgres tests and uses `mailPostgres(t)`. Use small fstest.MapFS catalogs; compare HTML with substring and attribute checks, not whole-document equality. Put the year expectation on time.Now().Year() (or the clock seam 35-06 shipped). If a behavior above differs from what 35-05/35-06 recorded as shipped, the SUMMARY wins and the test follows it; a real defect gets its own fix commit first. In the same commit add the ten Docker-free names to GO_TESTS (./modules/postcard:TestTemplateBase … TestInlineFailure) and ./modules/postcard:TestEnsureLocaleRows to DOCKER_TESTS.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test -short ./modules/postcard -count=1 -run '^(TestTemplateBase|TestTemplateFor|TestSendLocaleFallback|TestBuiltinLayoutsLogo|TestHeaderFooterPartials|TestButtonPartial|TestSiteName|TestInlineCSS|TestInlineCSSOptOut|TestInlineFailure)$' -v 2>&1 | grep -E '^(--- |FAIL|ok|PASS)' | tail -20</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or fewer than ten "--- PASS" lines</fails_when>
<automated>go test ./modules/postcard -count=1 -run '^TestEnsureLocaleRows$' -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -5 && go vet ./... && go test -short ./... && bash scripts/check-phase35.sh --go 2>&1 | tail -4</automated>
<fails_when>non-zero exit, a "FAIL", "refuse:" or "--- SKIP" line, or no "--- PASS: TestEnsureLocaleRows" line</fails_when>
</verify>
<acceptance_criteria>
- `grep -c "^func Test" modules/postcard/locale_test.go modules/postcard/layouts_test.go modules/postcard/inline_test.go modules/postcard/locale_postgres_test.go` totals at least 11
- `grep -n "t.Skip" modules/postcard/locale_test.go modules/postcard/layouts_test.go modules/postcard/inline_test.go` prints nothing
- `grep -n "TestInlineCSSOptOut\|TestEnsureLocaleRows" scripts/check-phase35.sh` prints at least two lines
</acceptance_criteria>
<done>Every postcard behavior of the gap closure is pinned by a named unit test that runs in the fast loop, plus one Postgres test for the fallback rows, all required by the gate.</done>
</task>
<task type="auto" tdd="true">
<name>Task 3: cabana Postgres tests and SPA tests for grouped templates, the site name and the inlining switch; gate --all; validation map</name>
<files>modules/cabana/mail_locale_postgres_test.go, modules/cabana/mail_brand_layout_postgres_test.go, admin/tests/form/LocaleVariantSwitcher.test.ts, admin/tests/form/FormViewMail.test.ts, scripts/check-phase35.sh, .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md</files>
<behavior>
- TestMailLocaleGroups: with a fake TranslationWriter (pl, en, de; default pl) the list has one welcome row; customized_locales is empty, then "de", then "Default, de"; badges and the status filter follow any customized / drifted row of the group; GET of the welcome record returns localeVariants Default (current), de, en in that order with translated labels and states; a not-customized de row shows the base row's current subject, body and layout (the base customization when present); PUT on de then Send of welcome-de uses it; the reset action on de returns the default version; a changed base file marks de outdated; the file version partial of de compares with the base file; the info partial of de holds the fallback line; an id outside the catalog is 404; a role with only system.manage_mail_layouts gets 403 on the de id; a newly enabled locale (writer answers fr too) appears in localeVariants on the next GET without a restart; the locale-set change re-syncs the list
- TestMailBrandSiteName: saving site_name persists it trimmed; more than 255 characters is a 422 on site_name; preview mode branding shows the name in the header; with no logo and no name the preview has no header row
- TestMailLayoutInlineOptOut: saving the switch on a file layout makes its next send keep the button without an inlined style; reset restores the file value; a custom layout created with the switch off inlines
- LocaleVariantSwitcher.test.ts: one option per variant with "Label — states" text, the current one selected, change pushes the sibling id, a rejected navigation restores the selection, the select has an accessible label
- FormViewMail.test.ts: FormView renders the switcher only when meta.localeVariants has two or more entries; with unsaved edits switching asks the existing confirm and stays on cancel
</behavior>
<read_first>
- .planning/phases/35-mail-templates-and-layouts-editor/35-05-SUMMARY.md and 35-06-SUMMARY.md
- modules/cabana/mail_screens_smoke_test.go (env, fixture, fake TranslationWriter, request helpers) and modules/cabana/mail_lifecycle_postgres_test.go (style of 35-04's Postgres tests)
- admin/tests/form/FormViewMail.test.ts, admin/tests/form/LocaleVariantSwitcher.test.ts (35-05 smoke), admin/src/components/form/LocaleVariantSwitcher.vue
- .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md
</read_first>
<action>
Per D-21 for G-35-1 and G-35-8:
- The two Go files are Postgres tests in package cabana_test that skip under -short like the existing mail Postgres tests and reuse newMailScreensEnvWith; build a second process over a changed MapFS with `keep: true` for the drift case, as the drift subtest does. Add ./modules/cabana:TestMailLocaleGroups, TestMailBrandSiteName and TestMailLayoutInlineOptOut to DOCKER_TESTS in the same commit.
- Extend the 35-05 smoke vitest file rather than duplicating it; add tests/form/LocaleVariantSwitcher.test.ts to ADMIN_FILES in the admin test commit. Admin source is not changed by this task; a defect gets its own fix commit (and, if admin source changed, the dist rebuild commit and scripts/check-admin-dist.sh per CLAUDE.md).
- Run `bash scripts/check-phase35.sh --all` (Docker host; PHASE35_ALLOW_NO_DOCKER only when no daemon answers, which must then be stated in the SUMMARY).
- Planning-docs commit: 35-VALIDATION.md rows for G-35-1 (locale grouping: postcard unit + Postgres, cabana Postgres, SPA) and G-35-8 (layouts, partials, inlining, site name, consumers with the scratch modfile), marking the D-05 row and the "default layout output unchanged" byte-identity row as superseded by the decision notes of 35-05 and 35-06; Manual-Only rows for re-running UAT tests 1 and 8 on sm-demo-app after resetting the UAT overrides of golem15.user::mail.activate and golem15.user::mail.layouts.user, and for a real-inbox check of inlined mail.
Commit as listed in Execution units.
</action>
<verify>
<automated>go test ./modules/cabana -count=1 -run '^(TestMailLocaleGroups|TestMailBrandSiteName|TestMailLayoutInlineOptOut)$' -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -8</automated>
<fails_when>a "FAIL" or "--- SKIP" line, or fewer than three "--- PASS" lines</fails_when>
<automated>npm --prefix admin run test -- tests/form/LocaleVariantSwitcher.test.ts tests/form/FormViewMail.test.ts 2>&1 | tail -8 && npm --prefix admin run typecheck && go vet ./... && go test -short ./...</automated>
<fails_when>non-zero exit or a "FAIL" line</fails_when>
<automated>bash scripts/check-phase35.sh --all 2>&1 | tail -15; git -C ../sm-user-plugin status --porcelain; git -C ../sm-paymentgateway-plugin status --porcelain</automated>
<fails_when>a "refuse:" line, no "Phase 35 gate passed" line, or any porcelain output</fails_when>
</verify>
<acceptance_criteria>
- `grep -n "^func TestMailLocaleGroups\|^func TestMailBrandSiteName\|^func TestMailLayoutInlineOptOut" modules/cabana/*_test.go` prints three lines
- `grep -c "localeVariants" admin/tests/form/FormViewMail.test.ts` prints a number above 0
- `grep -n "TestMailLocaleGroups\|LocaleVariantSwitcher.test.ts" scripts/check-phase35.sh` prints at least two lines
- `grep -n "G-35-1\|G-35-8" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints at least two lines
</acceptance_criteria>
<done>The admin side of both gaps is pinned by named tests, one command proves the whole gap closure plus the unchanged core plugins, and the validation map records how.</done>
</task>
</tasks>
<threat_model>
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| gate script → sibling repositories | the consumers stage builds and tests code in repositories this phase must not change |
| tests → Docker | Postgres tests start containers on the local daemon |
## STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-35-39 | Tampering | consumers stage with a new framework dependency | medium | mitigate | scratch -modfile copies of go.mod/go.sum, a workspace_check that the framework resolves to this checkout, and a refusal when either sibling's git status is not clean (self-test planted cases) |
| T-35-40 | Repudiation | skipped or missing tests passing the gate | medium | mitigate | every new test is required by name; detect_go refuses skips, zero matches and missing names (existing rules) |
| T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package |
</threat_model>
<verification>
- `go vet ./... && go test ./...` green; `npm --prefix admin run test`, `test:browser` and `typecheck` green.
- `bash scripts/check-phase35.sh --all` passes; sibling working trees unchanged.
- 35-VALIDATION.md maps both gaps.
</verification>
<success_criteria>
- Named unit tests pin G-35-1 and G-35-8 behaviour in postcard, cabana and the SPA.
- The phase gate requires them and stays read-only against the core plugins with the new dependency.
- Ready for `/msd-verify-work 35` (re-run UAT tests 1 and 8 on sm-demo-app after resetting the two UAT overrides); nothing pushed or tagged.
</success_criteria>
<output>
Create `.planning/phases/35-mail-templates-and-layouts-editor/35-07-SUMMARY.md` when done, with the gate output summary, the list of required test names and any fix commits recorded as deviations.
</output>
## Follow-ups outside this phase (not planned here)
- Plugin follow-up after the framework tag (sm-user-plugin, sm-paymentgateway-plugin): framework requirement bump with `go mod tidy`, button partial in their templates, full layouts keeping their names, per-locale template names; once their go.sum carries go-premailer, the scratch modfile in the consumers stage is a no-op and can stay.
</content>
</invoke>