docs(35-01): complete mail domain layer plan

This commit is contained in:
Jakub Zych
2026-11-13 11:11:01 +01:00
parent 2bf9081c1b
commit db86b51a51
4 changed files with 501 additions and 27 deletions

View File

@@ -1870,11 +1870,11 @@ 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 plans
**Plans:** 1/4 plans executed
Plans:
**Wave 1**
- [ ] 35-01-PLAN.md — pact `HasMailPartials`, postcard-owned mail tables and migrations, per-send override lookup with file fallback, partials, sample vars, Branding CSS, index sync, Editor API, docs
- [x] 35-01-PLAN.md — pact `HasMailPartials`, postcard-owned mail tables and migrations, per-send override lookup with file fallback, partials, sample vars, Branding CSS, index sync, Editor API, docs
**Wave 2** *(blocked on Wave 1 completion)*
- [ ] 35-02-PLAN.md — cabana Settings → Mail screens, two permission codes, reset/delete rules, drift notice and diff, server field types, preview and own-address test send, OpenAPI, en/pl copy

View File

@@ -1,19 +1,19 @@
---
msd_state_version: "1.0"
milestone: v1.0
current_phase: "19.7"
current_phase_name: Generic MCP module (INSERTED)
status: verifying
stopped_at: Phase 32 context gathered
last_updated: "2026-10-25T21:26:24.117Z"
last_activity: 2026-10-23
last_activity_desc: "Completed 19.7-08: plugin gap closure, E-1 logo, E-2 member token scopes; paused before 19.7-09"
state_head: 9a76c7ec1c0c17e93e00086231af78648eb40c43
current_phase: 35
current_phase_name: Mail templates and layouts editor
status: executing
stopped_at: Completed 35-01-PLAN.md
last_updated: "2026-11-13T10:11:00.377Z"
last_activity: 2026-11-13
last_activity_desc: Phase 35 execution started
state_head: 2bf9081c1bd8385b45210ead8524eda5512b3ca1
progress:
total_phases: 47
total_phases: 50
completed_phases: 37
total_plans: 242
completed_plans: 238
total_plans: 288
completed_plans: 285
gsd_state_version: "1.0"
milestone_name: milestone
---
@@ -25,14 +25,14 @@ milestone_name: milestone
See: .planning/PROJECT.md (updated 2026-10-22)
**Core value:** An existing WinterCMS-shaped app can be ported plugin by plugin to a single Go binary without its frontend noticing: the PHP version's API contract is the acceptance test.
**Current focus:** Phase 19.7 — Generic MCP module (INSERTED)
**Current focus:** Phase 35 — Mail templates and layouts editor
## Current Position
Phase: 19.7 (Generic MCP module (INSERTED)) — EXECUTING
Plan: 5 of 5
Status: Phase complete — ready for verification
Last activity: 2026-11-08 - Completed quick task 261108-pe4: beachcomber highlights and field projection
Phase: 35 (Mail templates and layouts editor) — EXECUTING
Plan: 2 of 4
Status: Ready to execute
Last activity: 2026-11-13 — Phase 35 execution started
Progress: [████████░░] 82%
@@ -278,6 +278,42 @@ Progress: [████████░░] 82%
| Phase 19.6.1 P05 | 4 min | 2 tasks | 7 files |
| Phase 19.7 P01 | 52 min | 5 tasks | 64 files |
| Phase 19.7 P02 | 38 min | 4 tasks | 36 files |
| Phase 19.6 P01 | 61min | 5 tasks | 33 files |
| Phase 19.6 P02 | 25min | 3 tasks | 47 files |
| Phase 19.6 P03 | 100min | 6 tasks | 52 files |
| Phase 19.6 P04 | 96 min | 6 tasks | 40 files |
| Phase 32 P01 | 32 min | 4 tasks | 17 files |
| Phase 32 P02 | 37 min | 4 tasks | 34 files |
| Phase 32 P03 | 48 min | 5 tasks | 89 files |
| Phase 32 P04 | 43 min | 4 tasks | 66 files |
| Phase 32 P05 | 45 min | 4 tasks | 51 files |
| Phase 32 P06 | 1h 25m | 5 tasks | 47 files |
| Phase 32.1 P01 | 12 min | 3 tasks | 18 files |
| Phase 32.1 P02 | 17 min | 2 tasks | 6 files |
| Phase 32.1 P03 | 24 min | 4 tasks | 17 files |
| Phase 32.1 P04 | 14 min | 2 tasks | 13 files |
| Phase 34 P01 | 22 min | 5 tasks | 44 files |
| Phase 34 P03 | 51 min | 4 tasks | 70 files |
| Phase 34 P04 | 34 min | 4 tasks | 14 files |
| Phase 34 P05 | 28min | 3 tasks | 33 files |
| Phase 34 P02 | 25min | 5 tasks | 82 files |
| Phase 34 P06 | 40min | 5 tasks | 25 files |
| Phase 33 P01 | 22 min | 4 tasks | 19 files |
| Phase 33 P07 | 25min | 4 tasks | 57 files |
| Phase 33 P02 | 60 min | 4 tasks | 63 files |
| Phase 33 P03 | 43min | 4 tasks | 78 files |
| Phase 33 P08 | 27min | 3 tasks | 68 files |
| Phase 33 P04 | 30min | 3 tasks | 38 files |
| Phase 33 P05 | 70min | 3 tasks | 61 files |
| Phase 33 P09 | 51min | 4 tasks | 88 files |
| Phase 33 P06 | 105min | 4 tasks | 45 files |
| Phase 33 P10 | 75min | 4 tasks | 65 files |
| Phase 33 P11 | 75min | 4 tasks | 72 files |
| Phase 33 P12 | 50min | 3 tasks | 12 files |
| Phase 33 P13 | 105min | 4 tasks | 6 files |
| Phase 33 P16 | 19min | 4 tasks | 41 files |
| Phase 33 P15 | 2h15m | 6 tasks | 70 files |
| Phase 35 P01 | 55 min | 5 tasks | 30 files |
## Accumulated Context
@@ -317,6 +353,9 @@ Progress: [████████░░] 82%
- Phase 32 added: SEO foundation: per-record and global SEO, structured data per page type, sitemap boost and HTML sitemap, pagination, redirects, robots.txt, canonical, meta robots, social tags, headings, hreflang, noindex policy, SSR for headless frontends
- Phase 32 edited: narrowed to framework seams and sm-seo-plugin core (split decided 2026-10-25)
- Phase 33 added: SEO output, audit and content; large phase, lean-planning exception
- Phase 32.1 inserted after Phase 32: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (requested by a consuming app's agent-access work) (URGENT)
- Phase 34 added: Plugin marketplace: summercms.io/marketplace, summer plugin:install (registry ID or git URL), read-only admin Plugins screen
- Phase 35 added: Mail templates and layouts editor: DB overrides of plugin-registered mail, editable seeded layouts, images; integer phase so follow-ups land as 35.x
### Decisions
@@ -954,6 +993,108 @@ Recent decisions affecting current work:
- [Phase 19.7]: Once the user confirms all in-flight msd-quick tasks are finished: release the framework as the next v0.4.x patch (carrying the quick patches and 19.7 work so far) and tag the held user-plugin fixes; plugins may be tagged mid-phase. Framework v0.5.0 stays reserved for full MCP usability at phase 19.7 completion — User decision 2026-10-23: plugins can be tagged now, framework 0.5 means the MCP phase is finished; wait for the user's word that the last quick agent is done
- [Phase 19.7]: 19.7-02: pier serves 2025-11-25 clients through its own session router over StreamableServerTransport (Redis-shared sessions, D-25) and 2026-07-28 clients through the SDK stateless handler; plan 02 closed without a tag, pier ships opt-in in v0.4.4 (summercms_mcp tag plus mcp.enabled, default off)
- [Phase 19.7]: Released framework v0.4.4 (e2759d6, changelog id 39) and sm-user-plugin v0.1.9 (3828a65; requires v0.4.3); sm-demo-app bumped to user v0.1.9 locally (a25444e, unpushed). Other apps not bumped yet — User go-ahead 2026-10-23 after all quick tasks finished; all release gates green at e2759d6
- [Phase 19.6]: 19.6-01: sm-user-plugin seams built on v0.1.11 (origin/master 50da92c), not v0.1.5; plan 04's additive check uses base 50da92c
- [Phase 19.6]: 19.6-01: the D-07 password-change hook is the existing classes.AccessRevokedEvent (fired in-transaction by reset, change and admin set) with the new (*AccessRevokedEvent).PasswordChanged(); no separate PasswordChangedEvent. sm-mfa-plugin (plan 02) listens to AccessRevokedEvent
- [Phase 19.6]: 19.6-01: device table migration ID is 202610260001_create_device_auth_sessions (after 202610220001 backend links); golem15.user.frontend_url is reused, new keys golem15.user.device_auth.auth_url and .ttl_minutes
- [Phase 19.6]: 19.6-02: sm-mfa-plugin listens on AccessRevokedEvent with PasswordChanged() for D-07 and deletes trusted devices in the password write's transaction
- [Phase 19.6]: 19.6-02: failure cap ignores the caller's in-flight attempt (FailureCapReached inFlight), TOTP step acceptance is a guarded UPDATE in the completion transaction
- [Phase 19.6]: 19.6-02: sm-mfa-plugin migrations 202610220001..05; 202610220006 reserved for plan 03 WebAuthn credentials
- [Phase 19.6]: 19.6-03: sm-demo-app mounts golem15.mfa v0.1.0 (optional, totp and email, social sign-ins unchallenged, no webauthn on the demo); the private sm-mfa-plugin repo means the demo's module-mode release build needs git.golem15.com credentials or a public repo (deferred, user decides)
- [Phase 19.6]: An empty mfa settings list falls back to the configuration (sm-mfa-plugin 71d8f27, released as v0.1.1)
- [Phase 19.6]: Finding F-1 (activate-by-code skips the second factor when require_activation is off) deferred by the user; todo 2026-10-26-activate-by-code-second-factor
- [Phase 32]: D-91 Go shape is the yaml-document form: AdminFormExtension.Fields (AdminFS path) or FieldsYAML (bytes built at boot) carries a fields.yaml-format document with before:/after:/zone: and a tabs: list; pact.AdminFormTab/AdminFormField are not published
- [Phase 32]: Form extension Hide is static for every administrator; Permissions/Visible gate the extension's own fields on schema, show and save
- [Phase 32]: Form extension Save runs after the owner's FormAfter* hooks in the save transaction on every create/update of a visible extension; Load runs on show and in the save response
- [Phase 32]: 32-02: D-92/D-93 Go shapes adopted as planned (P-07 to P-10, incl. optional Match/MatchPath)
- [Phase 32]: 32-02: RecordChange.Locale empty = record's own row; no-op saves fire with empty Changes; reorder fires per moved node
- [Phase 32]: 32-02: signpost MatchPath = first exact match in registration order, else first inexact; Records without func = empty page
- [Phase 32]: 32-02: journal-tag with golem15.journal.tag_pages false resolves to nothing, empty URLs, never matches
- [Phase 32]: 32-04: redirect writes go through one service path (SaveRedirect, AddressChanged, ResolveNotFound) with a save-time loop simulation; resolve is the one-hop redirect decision (normalisation, redirects, strict URLs, then SEO)
- [Phase 32]: 32-04: the robots.txt editor, tester and AI bot switches are fields of the plugin's own form extension on golem15.seo.robots, because an owner-form widget may fill built-in scalar fields only
- [Phase 32]: SEO management API: every admin operation is an MCP tool on a /_seo/api/v1 route with golem15.seo.manage; AdminOperations + parity test guard drift
- [Phase 32]: Batches run in one transaction with per-change savepoints; dry run rolls back, a refused change refuses the whole batch
- [Phase 32]: Undo restores through the service with undo_stale/undo_loop/undo_gone guards; an undo is itself a revision
- [Phase 32]: Import apply token: gzip file + fingerprint signed with HMAC-SHA256 under an app.key-derived key; apply re-runs the preview (transfer.stale)
- [Phase 32]: Demo mount waits for the plugin tag: 32-05-demo-mount.patch carries the mount and the two demo SEO tests for plan 32-06
- [Phase 32]: Released SummerCMS v0.5.1, sm-journal-plugin v0.2.5 and sm-seo-plugin v0.1.0 (pushed); sm-demo-app mounts golem15.seo v0.1.0 (pushed, not deployed)
- [Phase 32]: check-phase32 additive stage compares with the newest tag not containing HEAD, so a post-release run compares with the previous release
- [Phase 32.1]: Empty MCP Options.ScopesSupported resolves to read, write, ai, offline_access, backend; a non-empty list, including DefaultOptions, is used as given
- [Phase 32.1]: Advertised scopes are pact.MCPAdvertisedScopes, not a new method on pact.MCPTokenVerifier
- [Phase 32.1]: Stateless tool calls set callInfo.stateless so MCPCall.SessionID stays empty
- [Phase 32.1]: Implies tests live in the sm-user-plugin root package so go test . runs them
- [Phase 32.1]: OAuth Implies tests load a principal from an in-memory SQL driver so go test -short does not skip
- [Phase 32.1]: 32.1-03 backfill is write-noop-rollback: live MCP grants get a consent row, and Rollback returns nil so a down migration does not delete consents created later.
- [Phase 32.1]: vue-oauth-layer /connect locks read in the UI, omits scopes when consent is already stored, and refetches on 409 backend_link_changed. The new repo is on main with no remote and no tag.
- [Phase 34]: kiosk module: plugin.yaml format, registry v1 wire types and version rules exist once in Go; Task 1 answered as-planned (P34-01..P34-04, v0.6.0 framework minimum)
- [Phase 34]: kiosk.ReadIdentity resolves constant plugin IDs statically (go/parser + go list -m), shared with plugin:add
- [Phase 34]: summer build bakes PluginInfo and FrameworkVersion into plugins.gen.go; generated main calls party.Describe before Activate; metadata failures warn and fall back to IDs
- [Phase 34]: 34-03: the registry API encodes only kiosk wire types; ingest-now and admin live in the site plugin golem15.summercms
- [Phase 34]: 34-03: registry token scope declares GET, HEAD and POST (the framework requires GET in every scope)
- [Phase 34]: 34-03: sm-summercmsio-app go.mod requires summercms v0.6.0 with the site plugin; release needs the v0.6.0 tag and a main.go/plugins.gen.go regeneration
- [Phase 34]: 34-03: marketplace categories content, users, commerce, communication, seo, tools are a contract between the site plugin and the marketplace pages
- [Phase 34]: plugin:install picks the newest release the effective framework allows and never moves the framework; plugin:update applies what resolves and reports the rest
- [Phase 34]: go.work overrides for submodule plugins: app replace target, versioned replace for workspace modules (Go refuses whole-path replaces of them), else a version pin that follows the app's require
- [Phase 34]: 34-05: the Plugins settings entry is added by Registry.Metadata only when backend.view_plugins is declared, the code plugins is free and the principal is allowed (SettingsEntry.Path opens /system/plugins)
- [Phase 34]: 34-05: cabana builds the registry catalog in Activate; registry calls run detached from the request with a 4 s timeout, 4 concurrent lookups, cache 5/15/1 min, and failures are a payload status, never a non-200
- [Phase 34]: 34-05: marketplace entries are limited to plugin-ID-shaped IDs and https icons because the ID ends up in a copied shell command
- [Phase 34]: 34-02 Task 4 answered defer: no app submodule pointer bumps in phase 34; 32 pending gitlinks (5 apps) and the chat/chatbots/chatchannels rebase blockers go to the 34-06 release ledger
- [Phase 34]: 34-02: research F8 applied to chatbots, chatchannels and chatvideo (sm-chat-plugin v0.0.0 -> v0.1.3, local replace kept)
- [Phase 34]: Release: every plugin with a 34-02 plugin.yaml plus sm-summercmsio-plugin gets the next patch tag (v0.1.0 if untagged); no /changelog/plugins posts, the v0.6.0 post and tag message list the bumps
- [Phase 34]: check-phase34.sh skips sm-user-plugin TestRegisterCORSPath via PHASE34_PLUGIN_SKIP (pre-existing, needs an app around it)
- [Phase 33]: 33-01 Task 1: P33-01 descriptor fields and P33-02 FormFieldType.RequestOptions adopted as planned (no renames)
- [Phase 33]: 33-01 Task 1: WR-02 accepted, pact.RecordSaved.Locale stays the request locale's primary tag (released in v0.5.2)
- [Phase 33]: 33-01 Task 1: Phase 33 delivers SummerCMS v0.6.1 (patch, additive); additive and marker stages compare with v0.6.0; plan mentions of v0.5.1/v0.5.2 mean v0.6.0/v0.6.1
- [Phase 33]: 33-07 Task 1 (Jakub 2026-11-04): the shared layer is vue-seo-layer, extended in place from v0.1.1 (no tea repo creation in 33-14; next layer tag v0.2.0)
- [Phase 33]: 33-07: seo.cms is an alias of public.seo.enabled; v0.1.1 config keys and behaviour preserved
- [Phase 33]: 33-07: root-file proxies and the root_files rule apply only after a v0.2.0 site answer; older or unreachable backends keep v0.1.1 behaviour
- [Phase 33]: 33-02: Journal H1 setting default on; EffectiveH1ToH2 = settings row, else golem15.journal.content_h1_to_h2, else true; conversion on every Journal rich-text write path (admin, API/MCP, markdown, import, category pillar text)
- [Phase 33]: 33-02: images/alt defaults dry_run false, fix-headings dry_run true; editor schema keeps H5/H6 while the toolbar offers H2-H4 (or H1-H4)
- [Phase 33]: 33-02: MediaFileName slugs both the editor upload and POST /media/upload (D-85); response shape unchanged
- [Phase 33]: 33-03 Task 1 answered as-proposed (Jakub 2026-11-04): /sitemap.xml index, /sitemap-<slug>-<n>.xml via /_sitemap/files/{file}, XSL removed, one settings singleton, definitions table kept unread
- [Phase 33]: 33-03: sitemap Filter/Listing seam lives in git.golem15.com/golem15/sm-sitemap-plugin/contract (no init); SEO implements contract.Filter, sitemap publishes classes.Listing as contract.Listing
- [Phase 33]: 33-03: sitemap settings validation runs in the controller FormBeforeUpdate (cabana turns BeforeValidate errors into 500)
- [Phase 33]: 33-03: additional address lastmod is a YYYY-MM-DD text field until cabana repeaters accept a datepicker (deferred)
- [Phase 33]: 33-08: the vue-seo-layer build guard runs when pages are resolved (nitro:config fires first); production build and generate fail, nuxt dev and prepare only warn
- [Phase 33]: 33-08: vue-seo-layer app/utils helpers are seo-prefixed (seoPaginationWindow, seoPageHref) because vue-journal-layer auto-imports its own paginationWindow
- [Phase 33]: 33-08: HTML sitemap pages answer 404 unless the CMS site answer has the HTML sitemap on for the locale, 503 with the backend unreachable; an app page at the same path wins
- [Phase 33]: 33-04: the HTML sitemap API answers the contract vue-seo-layer 33-08 reads (groups by file slug: key, slug, title, total, more, entries with children; group page: group, title, page, pages, entries)
- [Phase 33]: 33-04: the HTML sitemap address per locale is a JSONB map (html_paths) edited through the plugin's form extension, not the translation writer
- [Phase 33]: 33-04: News sources is a taglist with custom tags plus a partial listing the values (type:<key>, category:<key>:<id>), checked on save, because taglist options are fixed YAML
- [Phase 33]: 33-04: IndexNow retries 429, 5xx and network errors within five attempts; 400, 403 and 422 are recorded without retry; requests only in production
- [Phase 33]: 33-05: Registry addresses and names per locale live in urls/titles JSONB through the plugin's own form extension (fields url and title), so Match finds a page by any locale's address
- [Phase 33]: 33-05: The registry content type is labelled Site page (pages.type), not Page, to avoid a duplicate SEO settings tab label
- [Phase 33]: 33-05: The sitemap filter decides on production values and also excludes addresses the address rules would 301 (reason redirect)
- [Phase 33]: 33-05: robots.txt names the sitemap plugin's index (ListingSettings.IndexURL) unless golem15.seo.robots_sitemaps is set
- [Phase 33]: 33-05: sm-sitemap-plugin contract.ListingSettings.TypesOff (additive) feeds P1 status.excluded_type
- [Phase 33]: 33-05: Site-cache purge after SEO writes is queued in Service.Record once per transaction (kind seo)
- [Phase 33]: 33-09: vue-journal-layer, vue-menu-layer and vue-faq-layer extend vue-seo-layer through a link dependency during development (33-14 pins the git tag); the journal layer drops @nuxtjs/seo and its sitemap source
- [Phase 33]: 33-09: the post title is h1 while the Journal API reports content_h1_to_h2 on (or absent) and p.journal-post__title while off; journal.postTitleTag overrides; category pillar text follows the category row's setting
- [Phase 33]: 33-09: the deprecated POST /api/__journal__/cache/purge keeps its own helpers: a bare import of vue-seo-layer's .ts library would be externalized by Nitro in git-installed apps
- [Phase 33]: 33-09: Journal related posts opt-in (golem15.journal.related_mode scored, related_count 3-6); scored mode adds previous_in_category/next_in_category; default answer unchanged
- [Phase 33]: 33-09: an app without pages that extends vue-seo-layer sets seo.htmlSitemap false, else the sitemap pages turn the router on
- [Phase 33]: 33-06 Task 4: chromedp approved, pin v0.21.0; gen2brain/webp approved, pin v0.6.4 (Jakub 2026-11-04)
- [Phase 33]: 33-06: every JSON-LD graph carries the full WebSite and publisher nodes
- [Phase 33]: 33-06: site answer home_crumb is {name, url, names} (layer reads name/url; names per locale)
- [Phase 33]: 33-10: chromedp v0.21.0 renders the optional raw-versus-rendered comparison; Chrome's host-resolver-rules list the site hosts first and MAP * ~NOTFOUND last (first matching rule wins)
- [Phase 33]: 33-10: GET /_seo/api/v1/issues reads stored issues (CMS checks refreshed until the first crawl, then the newest crawl's) and defaults to status open
- [Phase 33]: 33-10: crawl issues route to the record type's Tools for content, to seo_ tools for data, else fix code with details.what; no issue has neither
- [Phase 33]: 33-10: the Site audit status filter cannot default to Open (cabana filters have no default); ignored rows are badged, the API defaults to open
- [Phase 33]: 33-11: gen2brain/webp pinned at v0.6.4 in the framework (modules/lagoon/attach/webp only); its fallback is wasm2go-transpiled libwebp, not wazero; importing it makes binaries glibc-dynamic unless built with -tags nodynamic (33-14 decides per app)
- [Phase 33]: 33-11: auto-link locale stored as '' for every locale (not NULL); history subject autolink purges every page (*)
- [Phase 33]: 33-11: E10 internal links omitted for collection and profile kinds and the page registry (Words is a per-record fact)
- [Phase 33]: 33-11: Journal variants carry the original's source_width/source_height on each featured_images[].variants entry; no foreign key to system_files
- [Phase 33]: 33-12: the demo keeps cookie-based Polish (D-13); its /pl/ alternates and sitemap addresses answer 404, so moving to prefix_except_default is a decision for 33-14 before the demo patches are applied
- [Phase 33]: 33-12: demo sitemaps go through Nuxt (vue-seo-layer root files); nginx has no /sitemap*, /_sitemap or /_seo location and check-deploy.sh refuses one
- [Phase 33]: 33-13: grzybyfunkcjonalne.pl deploys after the tags, to production (no separate uat since the 2026-10-31 cutover); en off and the copied Additional addresses removed at the 33-14 release checkpoint
- [Phase 33]: 33-14: the demo moves to prefix_except_default (English at /, Polish at /pl/), reversing D-13
- [Phase 33]: 33-16: vue-seo-layer adds its HTML sitemap pages from a pages:resolved hook registered on ready, after @nuxtjs/i18n has localised the routes (modules:done ran before i18n's handler)
- [Phase 33]: 33-16: the route report drops every noindex entry before cutting routes, so the JSON body stays within the older plugin's 4,113,024 bytes
- [Phase 33]: 33-16: HTML sitemap pages are not registered over an app catch-all unless seo.htmlSitemap.overCatchAll; an app with only app.vue needs no htmlSitemap: false
- [Phase 33]: 33-15: the route report's noindex key replaces the stored noindex set (golem15_seo_noindex_paths) and the SEO sitemap filter leaves those paths out with reason noindex; a changed set asks for a rebuild through contract.Rebuilder
- [Phase 33]: 33-15: Journal descriptors give a locale a URL only when the record has content in it (posts/categories by own translation, tags/authors through a translated published post, default locale always); menu Resolve unchanged
- [Phase 33]: 33-15: a crawl's job owns its terminal status (cancel records cancel_requested_at), finishes on a detached 10-minute context, writes heartbeat_at every minute; RecoverStale ends running rows without a heartbeat for 10 minutes
- [Phase 33]: 33-15: sitemap rebuilds run under pg_advisory_xact_lock(hashtext('golem15.sitemap.rebuild')) around settings, collect and apply; apply never writes a content row's lastmod
- [Phase 33]: 33-15: G2 (journal-tag pattern while tag pages are off) deferred to v0.6.2: signpost.Activate refuses a type without a DefaultPattern starting with /
### Pending Todos
@@ -999,13 +1140,11 @@ Recent decisions affecting current work:
- pending: push sm-user-plugin — 12.1-05 Task 3 condition (c) failed (`git ls-remote --tags origin v0.1.3` empty). Push summercms.go master and annotated tag v0.1.3 (local on df5cace) first, then the plugin, then fonoteka.go. Recorded in 12.1-05-SUMMARY.md.
- 16.2-05 open UAT items: re-save HTML post 1 untouched (D-03 evidence vacuous), D-19 category edit check, root vhost install (frame-src), unpublish/delete test post 105
- Phase 19.4: review warnings WR-01..06 are open (19.4-REVIEW-DISPOSITION.md); WR-01 (a replayed code does not revoke rotated refresh tokens) must be fixed before any client enables refresh. Release still pending: tag summercms, bump sm-oauthserver-plugin go.mod to sm-user-plugin v0.1.1 / summercms v0.2.4.
- 19.6-03 Task 6 (1): sm-demo-app plugins/golem15/user carries another session's uncommitted move to v0.1.11; user decision needed before bumping it to v0.1.12
- 19.6-04 Task 5: go-ahead to release sm-mfa-plugin fix 71d8f27 (v0.1.1, demo and bm bumps) and a decision on finding F-1 (activate-by-code without the second factor when require_activation is off)
- 33-02 deferred: lagoon.Validate rejects string/url rule tokens, so the Journal admin settings save answers 500 (pre-existing); framework fix needed for the Headings and links switch in the admin
- 33-14 Task 3 release checkpoint: awaiting Jakub's go-ahead (versions, pushes, posts, deploys)
| 261028-rqb | Admin SPA reload on deploy (todo .planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md, admin half only; site half already shipped in vue-demo-app): boardwalk exposes a build version derived from the embedded dist (header like X-Summer-Build on admin API responses and/or a version endpoint), the admin SPA records the version it booted with and shows a non-blocking reload banner when a newer build is seen (focus/visibility/interval check), plus a reload-once guard on Vite chunk-load errors (vite:preloadError + sessionStorage flag); unit tests; boardwalk README; rebuild admin and commit modules/boardwalk/dist (scripts/check-admin-dist.sh must pass) | 2026-10-28 | c8a22e3 | .planning/quick/261028-rqb-admin-spa-reload-on-deploy-todo-planning-todos-pending-2026 |
| 261028-rqc | Quiet plugin boot logs on console commands like --help, framework side only (todo .planning/todos/pending/2026-10-21-quiet-plugin-boot-logs-on-console-commands.md): help/list/completion style commands must not print plugin Register/Boot Info logs (e.g. raise the default console log level for non-serve introspection commands or defer Boot for them), without hiding logs for serve/worker/migrate; no sm-* plugin edits (plugin-side Info->Debug changes are a separate follow-up); docs for the behaviour | 2026-10-28 | 6c606c6 | .planning/quick/261028-rqc-quiet-plugin-boot-logs-on-console-commands-like-help-framewo |
| 261028-rqd | Console review info findings IN-01..IN-13 and the delegate signal exit code 128+n (todo .planning/todos/pending/2026-10-22-console-review-info-findings.md, review .planning/phases/19.8-console-commands-overhaul/19.8-REVIEW.md); all 14 verified still open on 2026-10-28 in modules/bonfire, modules/diary, cmd/summer, scripts/check-phase19.8.sh; fix each, keep behaviour backward compatible, update docs/console pages and TestDelegateExitCodePassthrough for 128+n | 2026-10-28 | 202d38b | .planning/quick/261028-rqd-console-review-info-findings-in-01-in-13-and-the-delegate-si |
| 261028-rqe | attach.Store writes non-inline types with a non-rendering disposition (todo .planning/todos/pending/2026-10-28-attach-store-public-content-type.md): in modules/lagoon/attach/store.go pass Content-Disposition attachment (blob.WriterOptions) for anything not in an inline-safe raster allow-list (jpeg, png, gif, webp, avif), keep the DB ContentType unchanged, additive and non-breaking; tests; lagoon README and docs/services/storage.md deploy note updated | 2026-10-28 | 4957e5c | .planning/quick/261028-rqe-attach-store-writes-non-inline-types-with-a-non-rendering-di |
| 261028-rqf | Audit-log successful admin action runs with the admin id (todo .planning/todos/pending/admin-action-audit-log.md): in modules/cabana/actions.go runAction log success with admin_id (bouncer.User(ctx).ID), controller, action and kind (toolbar/field), matching the existing bulk/record action log fields; tests | 2026-10-28 | 61d1043 | .planning/quick/261028-rqf-audit-log-successful-admin-action-runs-with-the-admin-id-tod |
| 261028-rqg | Show the administrators holding a role on the Roles screen (todo .planning/todos/pending/roles-screen-holders-list.md, origin .planning/phases/19.6.1-backend-administrators-screen/19.6.1-UAT.md:44): read-only list of holders on the Roles form/preview in modules/cabana backend_roles_admin.go (and admin SPA if needed), superusers hidden from non-superuser editors (D-03), assignment stays on the Administrators form; tests; if admin/ changes, rebuild and commit modules/boardwalk/dist | 2026-10-28 | 653d95a | .planning/quick/261028-rqg-show-the-administrators-holding-a-role-on-the-roles-screen-t |
### Quick Tasks Completed
| # | Description | Date | Commit | Directory |
@@ -1065,9 +1204,27 @@ Recent decisions affecting current work:
| 261022-wah | User plugin opt-in golem15.user.jwt.token_cookie (default off) sets the HttpOnly auth.cookie session cookie on /login, /register and /activate-by-code instead of the body token; a /refresh carried by the auth.cookie cookie rewrites it (sm-user-plugin 846087d, 8bdf2c7, ships v0.5.0; verified) | 2026-10-22 | 846087d, 8bdf2c7 (sm-user-plugin) | [261022-wah-opt-in-httponly-session-cookie-on-user-p](./quick/261022-wah-opt-in-httponly-session-cookie-on-user-p/) |
| 261022-x7a | User plugin golem15.user.password.public_routes (default true): false leaves POST /login, /forgot-password and /reset-password unregistered so they 404 like unknown paths; /register and the rest unchanged (sm-user-plugin 3828a65, ships v0.5.0; verified) | 2026-10-22 | e5dd457 | [261022-x7a-user-plugin-golem15-user-password-public](./quick/261022-x7a-user-plugin-golem15-user-password-public/) |
| 55 | fix(cabana): backend subject events reach pier as *pact.MCPSubjectChanged after commit | 2026-10-23 | 7c43820 | — |
| 261028-fsq | sm-user-plugin MCPDispatch credential carries the personal token id (plugin a1b78b8) | 2026-10-28 | 7c4dbb1 | [261028-fsq-sm-user-plugin-mcpdispatch-credential-ca](./quick/261028-fsq-sm-user-plugin-mcpdispatch-credential-ca/) |
| 261028-pq8 | Fix the four internal/build scaffolder todos (make:plugin vendor path, make:admin-controller output, scaffold header and make:command deps, same-second migration order) | 2026-10-28 | 8bc18c9 | [261028-pq8-fix-the-four-internal-build-scaffolder-t](./quick/261028-pq8-fix-the-four-internal-build-scaffolder-t/) |
| 261028-r16 | Fix the two lagoon todos: stored-upload extension from sniffed MIME (tests + deploy note) and the lagoon README after-commit callback order | 2026-10-28 | 36092f5 | [261028-r16-fix-the-two-lagoon-todos-derive-stored-u](./quick/261028-r16-fix-the-two-lagoon-todos-derive-stored-u/) |
| fast | ensureToolchain keeps an existing toolchain line instead of adding a second one | 2026-10-28 | 6ea2cb7 | — |
| 261028-rqb | Admin SPA reload on deploy (todo .planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md, admin half only; site half already shipped in vue-demo-app): boardwalk exposes a build version derived from the embedded dist (header like X-Summer-Build on admin API responses and/or a version endpoint), the admin SPA records the version it booted with and shows a non-blocking reload banner when a newer build is seen (focus/visibility/interval check), plus a reload-once guard on Vite chunk-load errors (vite:preloadError + sessionStorage flag); unit tests; boardwalk README; rebuild admin and commit modules/boardwalk/dist (scripts/check-admin-dist.sh must pass) | 2026-10-28 | c8a22e3 | .planning/quick/261028-rqb-admin-spa-reload-on-deploy-todo-planning-todos-pending-2026 |
| 261028-rqc | Quiet plugin boot logs on console commands like --help, framework side only (todo .planning/todos/pending/2026-10-21-quiet-plugin-boot-logs-on-console-commands.md): help/list/completion style commands must not print plugin Register/Boot Info logs (e.g. raise the default console log level for non-serve introspection commands or defer Boot for them), without hiding logs for serve/worker/migrate; no sm-* plugin edits (plugin-side Info->Debug changes are a separate follow-up); docs for the behaviour | 2026-10-28 | 6c606c6 | .planning/quick/261028-rqc-quiet-plugin-boot-logs-on-console-commands-like-help-framewo |
| 261028-rqd | Console review info findings IN-01..IN-13 and the delegate signal exit code 128+n (todo .planning/todos/pending/2026-10-22-console-review-info-findings.md, review .planning/phases/19.8-console-commands-overhaul/19.8-REVIEW.md); all 14 verified still open on 2026-10-28 in modules/bonfire, modules/diary, cmd/summer, scripts/check-phase19.8.sh; fix each, keep behaviour backward compatible, update docs/console pages and TestDelegateExitCodePassthrough for 128+n | 2026-10-28 | 202d38b | .planning/quick/261028-rqd-console-review-info-findings-in-01-in-13-and-the-delegate-si |
| 261028-rqe | attach.Store writes non-inline types with a non-rendering disposition (todo .planning/todos/pending/2026-10-28-attach-store-public-content-type.md): in modules/lagoon/attach/store.go pass Content-Disposition attachment (blob.WriterOptions) for anything not in an inline-safe raster allow-list (jpeg, png, gif, webp, avif), keep the DB ContentType unchanged, additive and non-breaking; tests; lagoon README and docs/services/storage.md deploy note updated | 2026-10-28 | 4957e5c | .planning/quick/261028-rqe-attach-store-writes-non-inline-types-with-a-non-rendering-di |
| 261028-rqf | Audit-log successful admin action runs with the admin id (todo .planning/todos/pending/admin-action-audit-log.md): in modules/cabana/actions.go runAction log success with admin_id (bouncer.User(ctx).ID), controller, action and kind (toolbar/field), matching the existing bulk/record action log fields; tests | 2026-10-28 | 61d1043 | .planning/quick/261028-rqf-audit-log-successful-admin-action-runs-with-the-admin-id-tod |
| 261028-rqg | Show the administrators holding a role on the Roles screen (todo .planning/todos/pending/roles-screen-holders-list.md, origin .planning/phases/19.6.1-backend-administrators-screen/19.6.1-UAT.md:44): read-only list of holders on the Roles form/preview in modules/cabana backend_roles_admin.go (and admin SPA if needed), superusers hidden from non-superuser editors (D-03), assignment stays on the Administrators form; tests; if admin/ changes, rebuild and commit modules/boardwalk/dist | 2026-10-28 | 653d95a | .planning/quick/261028-rqg-show-the-administrators-holding-a-role-on-the-roles-screen-t |
| 261028-wqu | summercms.io Changelog dropdown (Framework/Plugins): /changelog = framework category, /changelog/plugins = plugins category; changelog-post.py categories + backfill (sm-summercmsio-app 29dd1b3) | 2026-10-28 | bac8e7e | [261028-wqu-summercms-io-changelog-dropdown-framewor](./quick/261028-wqu-summercms-io-changelog-dropdown-framewor/) |
| 261029-1r3 | Derive the summercms.io landing version from go.mod | 2026-10-29 | app b688a80 | [261029-1r3-derive-the-summercms-io-landing-version-](./quick/261029-1r3-derive-the-summercms-io-landing-version-/) |
| 261029-d9j | User plugin mail locale: normalize Accept-Language, configurable fallback, Polish subjects | 2026-10-29 | user 6bf219f | [261029-d9j-user-plugin-mail-locale-normalize-accept](./quick/261029-d9j-user-plugin-mail-locale-normalize-accept/) |
| 261105-din | Fix 32.1 CR-01: serialize MCP consent allow with revoke under LockUserGrants (sm-oauthserver-plugin 21f5985) | 2026-11-05 | 8c6b317 | [261105-din-fix-32-1-cr-01-serialize-mcp-consent-all](./quick/261105-din-fix-32-1-cr-01-serialize-mcp-consent-all/) |
| 261105-eab | Fix OIDC grant flows racing revoke: resume, refresh, exchange under LockUserGrants (sm-oauthserver-plugin 7b9899f) | 2026-11-05 | f925527 | [261105-eab-fix-oidc-consent-decide-race-with-revoke](./quick/261105-eab-fix-oidc-consent-decide-race-with-revoke/) |
| 261105-oc5 | 2FA hardening (todos 2026-10-26-activate-by-code-second-factor.md and 2026-10-26-mfa-factor-changes-need-reauth.md): sm-user-plugin ActivateByCode runs CheckLoginGates after VerifyActivationCode (finding F-1); sm-mfa-plugin requires password confirmation on factor-changing routes (WR-05) and vue-demo-app security.vue asks for the password | 2026-11-05 | b179e6b | .planning/quick/261105-oc5-2fa-hardening |
| 261105-oc6 | Chatchannels pin policy (todo chatchannels-pin-policy.md): sm-chatchannels-plugin PinMessage/UnpinMessage require CanManageContext or an optional contracts.PinPolicy, and verify the message belongs to the channel conversation; sm-demo-app answers the policy from its moderator group | 2026-11-05 | a042536 | .planning/quick/261105-oc6-chatchannels-pin-policy |
| 261105-oc7 | Chatvideo hardening (todos chatvideo-live-membership.md, chatvideo-dm-only-host-hook.md, chatvideo-incoming-handle-leak.md): sm-chatvideo-plugin honours LiveMembership and removes banned participants from the LiveKit room, adds an optional CanStartCall host hook for a DM-only rule; vue-chatvideo-layer useIncomingCalls closes stale session handles | 2026-11-05 | f996156 | .planning/quick/261105-oc7-chatvideo-hardening |
| 261105-oc8 | lagoon/attach StaticHandler and StaticHandlerPublic send the stored Content-Disposition and X-Content-Type-Options nosniff (todo 2026-10-28-attach-static-handler-disposition.md) | 2026-11-05 | 27c98bf | .planning/quick/261105-oc8-lagoon-attach-statichandler-and-statichandlerpublic-send-the |
| 261105-oc9 | sm-demo-app hardening (todos check-local-jwt-out-of-argv.md, demo-chat-members-read-only.md, demo-nginx-livekit-rtc-only.md, demo-seed-moderation-lists-once.md, demo-vapid-runbook-pipefail.md) | 2026-11-05 | 9595606 | .planning/quick/261105-oc9-sm-demo-app-hardening |
| 261106-d20 | fonoteka.go uploads named after the sniffed type and stored with attach.UploadWriterOptions; framework exports attach.UploadWriterOptions (todos 2026-10-28-fonoteka-uploads-use-disk-extension.md, 2026-11-06-blob-writers-set-content-disposition.md) | 2026-11-06 | 903859a | [261106-d20-fix-stored-xss-in-fonoteka-go-uploads-an](./quick/261106-d20-fix-stored-xss-in-fonoteka-go-uploads-an/) |
| 261106-dv0 | shared plugins log boot details at Debug: paymentgateway operators registered, paymentgatewaysubscriptions registries collected through diary.For (todo 2026-10-28-plugins-log-boot-details-at-debug.md) | 2026-11-06 | 8a88b86, 1df6a26 | [261106-dv0-plugin-boot-logs-at-debug](./quick/261106-dv0-plugin-boot-logs-at-debug/) |
| 261106-e5v | purge token rename leftovers: grzybyfunkcjonalne check-deploy refuses NUXT_SITE_* keys, journal/menu/faq READMEs name NUXT_CACHE_PURGE_TOKEN (todo 2026-10-20-rename-site-cache-purge-env-in-consumers.md) | 2026-11-06 | 4e2cf0c, f61c90a, 128a33d, a53511b | [261106-e5v-purge-token-rename-leftovers](./quick/261106-e5v-purge-token-rename-leftovers/) |
| 261106-jhk | wristband MCP authorize drops OIDC identity scopes (openid, profile, email) so the ChatGPT connector can connect | 2026-11-06 | aba678b | [261106-jhk-wristband-mcp-authorize-ignores-oidc-ide](./quick/261106-jhk-wristband-mcp-authorize-ignores-oidc-ide/) |
@@ -1085,6 +1242,6 @@ Items acknowledged and carried forward from previous milestone close:
## Session Continuity
Last session: 2026-10-24T14:47:37.432Z
Stopped at: Phase 32 context gathered
Resume file: .planning/phases/32-seo-foundation/32-CONTEXT.md
Last session: 2026-11-13T10:10:59.057Z
Stopped at: Completed 35-01-PLAN.md
Resume file: None

View File

@@ -0,0 +1,307 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 01
subsystem: mail
tags: [postcard, mail, gorm, gormigrate, goldmark, html-template, pact, attach, postgres]
# Dependency graph
requires:
- phase: 04-cli-scaffolding-i18n-and-mail
provides: postcard Catalog, Mailer, drivers and pact.HasMailTemplates
- phase: lagoon attach (system_files, public URLs)
provides: attach.Migrations, attach.BlobKey, storage.uploads.* config keys
provides:
- "postcard-owned mail tables (system_mail_templates, _layouts, _partials, _brand_settings, _image_library) as the framework migration set summercms.postcard"
- "per-send override lookup (OverrideSource, NewDBSource) with fallback to the file version"
- "pact.HasMailPartials, the partial template func, built-in partials button/panel/table/subcopy and layouts system/minimal"
- "sample.<path> header keys and the placeholder walker"
- "file hashes, the catalog read API, SyncIndex and ResetOverride"
- "postcard.Editor: Validate, Preview and SendDraft for template, layout, partial and Branding drafts"
- "Branding: Brand, DefaultBrand, CompileBrandCSS, the logoUrl layout key"
- "attach.AbsolutePublicURL and attach.ErrNoAbsoluteURL"
- "pact.RowStateCustomized and pact.RowStateOutdated"
affects: [35-02, 35-03, 35-04, cabana, admin-spa]
# Actuals (#2632)
actuals:
tokens: 69814 # chars/4 over this plan's realized diff (modules/ and docs/, 279256 chars)
tasks: 5 # the Task 1 decision checkpoint and Tasks 2-5
commits: 6 # MEASURED: git rev-list --count; 5 are this plan's, 1 (f8fa0f1 docs(31)) is another session's
plan_head_before: 3198bbe1aa96781b18398a3651b7de6d37939fba
plan_head_after: 2bf9081c1bd8385b45210ead8524eda5512b3ca1
# Tech tracking
tech-stack:
added: []
patterns:
- "A module that lagoon must migrate but that cannot import lagoon ships its own gormigrate set and reads the *gorm.DB through backpack per call"
- "Template funcs that must survive Markdown return a per-render random alphanumeric token, swapped after conversion"
- "Drafts are rendered by the send path with the draft injected as an override, so previews and save checks cannot drift from sends"
key-files:
created:
- modules/postcard/store.go
- modules/postcard/partials.go
- modules/postcard/samples.go
- modules/postcard/editor.go
- modules/postcard/brand.go
- modules/postcard/assets/system.htm
- modules/postcard/assets/minimal.htm
- modules/postcard/assets/sample.htm
- modules/postcard/assets/brand.css.tmpl
- modules/postcard/assets/partials/button.htm
- modules/postcard/assets/partials/panel.htm
- modules/postcard/assets/partials/table.htm
- modules/postcard/assets/partials/subcopy.htm
- modules/postcard/override_smoke_test.go
- modules/postcard/partials_smoke_test.go
- modules/postcard/editor_smoke_test.go
- modules/postcard/brand_smoke_test.go
- modules/lagoon/attach/absolute.go
modified:
- modules/postcard/mailer.go
- modules/postcard/templates.go
- modules/postcard/README.md
- modules/pact/capabilities.go
- modules/pact/README.md
- modules/lagoon/migrations.go
- modules/lagoon/pending_test.go
- modules/lagoon/README.md
- docs/services/mail.md
- docs/services/storage.md
- docs/plugins/registration.md
- docs/database/migrations.md
key-decisions:
- "35-01 Task 1 answered as-planned: P35-01 schema, P35-02 partial syntax and built-ins, P35-03 sample.* keys, P35-04 layout CSS slot and logoUrl, P35-05 names adopted without changes"
- "35-01: postcard logs 'override failed, sending the file version' only when the file version then renders; when both fail, the file version's error is returned as before"
- "35-01: a partial call in a body leaves the token MAILPARTIAL + 32 hex nonce + X<n>X, swapped in one pass after goldmark; raw HTML stays disabled for bodies"
- "35-01: Editor.Validate refuses a template body whose source holds a script, iframe, object or embed tag, because Markdown would drop it silently at send"
- "35-01: Branding (compiled CSS and logoUrl) also applies to the file version sent after a failing override; an invalid stored colour keeps mail.brandCss with a warning"
- "35-01: pact has five row states; cabana keeps only three until 35-02 updates rowStateOrder and docs/backend/lists-and-filters.md"
patterns-established:
- "Override source per send: Send asks OverrideSource once, renders with the result, and renders the files alone when the lookup or the override fails"
- "Typed render errors (part, template, unsafe snippet) keep send error texts unchanged and let the editor report field and rule"
requirements-completed: [D-01, D-04, D-05, D-06, D-07, D-08, D-10, D-11, D-12, D-13, D-14, D-15, D-16, D-17, D-19, D-22, D-23, D-24, D-25]
coverage:
- id: D1
description: "A customized row in system_mail_templates changes the subject, body and layout of the mail a process sends with only postcard.Activate and a published *gorm.DB; no row, no database, missing tables or a failing override send the file version"
requirement: "D-22"
verification:
- kind: integration
ref: "modules/postcard/override_smoke_test.go#TestMailOverrideSmoke (override, override_layout, layouts_and_partials, file, fallback, caller_subject, missing_table, no_db, unknown_template, migrations_roll_back)"
status: pass
- kind: integration
ref: "modules/lagoon/pending_test.go#TestMigrateStatusJSON"
status: pass
human_judgment: false
- id: D2
description: "Plugins declare partials through pact.HasMailPartials; bodies and layouts call them with {{ partial ... }}; built-in partials and the system and minimal layouts; layout and partial overrides apply at send"
requirement: "D-12"
verification:
- kind: unit
ref: "modules/postcard/partials_smoke_test.go#TestMailPartialsSmoke (capability, partials_only_plugin, body, forged_token, errors, built_in_layouts, layout_partials, overrides)"
status: pass
- kind: other
ref: "go doc ./modules/pact HasMailTemplates (three methods, unchanged)"
status: pass
human_judgment: false
- id: D3
description: "sample.<path> header keys, the placeholder walker, file hashes, the catalog read API, TemplateLocale, SyncIndex, ResetOverride, and Editor Validate, Preview and SendDraft for template, layout and partial drafts"
requirement: "D-13"
verification:
- kind: integration
ref: "modules/postcard/editor_smoke_test.go#TestMailEditorSmoke (samples, walker, validate, preview, send_draft, hash, locale, sync, reset)"
status: pass
human_judgment: false
- id: D4
description: "attach.AbsolutePublicURL builds an absolute public URL from configuration alone"
requirement: "D-19"
verification:
- kind: unit
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke/absolute_url"
status: pass
human_judgment: false
- id: D5
description: "Branding: compiled brand CSS replaces mail.brandCss once the settings row exists, mail.css still follows, layouts get logoUrl built at send time, and the editor previews and validates a Branding draft"
requirement: "D-11"
verification:
- kind: integration
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke (defaults, compile, preview, precedence, logo)"
status: pass
human_judgment: false
- id: D6
description: "Existing mail renders unchanged when no override exists: the default layout file is untouched and the consumer plugins' mail tests pass against this checkout"
verification:
- kind: unit
ref: "go test -short ./modules/postcard (TestMailRenderSmoke, TestMailLayoutSmoke, TestMailRecipientsAndSafety unchanged)"
status: pass
- kind: other
ref: "(cd ../sm-user-plugin && go test -run 'TestMail|TestPolishMailSubjects' ./...) and (cd ../sm-paymentgateway-plugin && go test -run 'TestMailCatalog|TestMailTracer|TestMailersMatrixSmoke' ./...)"
status: pass
- kind: other
ref: "git diff a024280 --stat -- modules/postcard/assets/default.htm (empty)"
status: pass
human_judgment: false
- id: D7
description: "READMEs and docs pages describe the new API, the mail tables, partials, sample values, the editor and Branding accurately and readably"
verification:
- kind: other
ref: "go test ./cmd/summer -run 'TestCommandsDocumented|TestDocsTree' and summer docs:build --check (identifiers, links, anchors)"
status: pass
human_judgment: true
rationale: "The docs checker proves identifiers and links exist, not that the prose is correct and clear; config keys are reviewed by hand per CLAUDE.md"
# Metrics
duration: 55 min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 01: Mail domain layer in postcard Summary
**postcard now owns the mail tables and reads template, layout, partial and Branding overrides from Postgres on every send, with file fallback, a partials capability, sample-value placeholders and an Editor that validates, previews and test-sends drafts through the send path**
## Performance
- **Duration:** 55 min (this continuation; the Task 1 checkpoint was handled by the previous agent)
- **Started:** 2026-11-13T09:15:32Z
- **Completed:** 2026-11-13T10:10:00Z
- **Tasks:** 5 of 5 (Task 1 decision checkpoint, Tasks 2-5 executed)
- **Files modified:** 30 (18 created, 12 modified)
## Task 1 answer (recorded verbatim)
The user's response to the Task 1 decision checkpoint: **"as-planned (Recommended)"**
Adopted without adjustment: P35-01 (schema), P35-02 (partial call syntax; built-in partials button, panel, table, subcopy; built-in layouts default, system, minimal), P35-03 (`sample.*` dotted header keys), P35-04 (layout CSS slot and `logoUrl`), P35-05 (permission codes, controller IDs, row states, routes, test-send limit, image picker upload rule) and the reset semantics as written in the plan's objective.
## Accomplishments
- **Database overrides with file fallback (Task 2, tracer).** `postcard.Migrations` creates the five `system_mail_*` tables; lagoon runs it as the framework set `summercms.postcard` after `summercms.attach`. `Mailer.Send` asks an `OverrideSource` once per message; `NewDBSource` looks the `*gorm.DB` up on the app per call and caches nothing. No database, missing tables, a failed lookup or an override that does not render or fails the safety checks sends the file version.
- **Partials and built-in layouts (Task 3).** `pact.HasMailPartials` (additive; `HasMailTemplates` is byte-identical), `Catalog.RegisterPartials`, the `partial` template func in bodies and layouts, `markdown` inside partials, built-in partials and the `system` and `minimal` layouts. Customized and database-only layouts and customized partials apply at send.
- **Samples, hashes, index rows and the Editor (Task 4).** `sample.<path>` header keys, a parse-tree walker that fills every other variable with `[path]`, sha256 hashes of CRLF-normalized files, `SyncIndex`, `ResetOverride`, and `Editor.Validate`, `Preview` and `SendDraft`.
- **Branding (Task 5).** `attach.AbsolutePublicURL`, `Brand`, `DefaultBrand`, `CompileBrandCSS`, the `logoUrl` layout key, the D-11 precedence over `mail.brandCss`, and the Branding draft in the Editor.
## Task Commits
1. **Task 1: decision checkpoint**: no commit (answer recorded above)
2. **Task 2: database overrides (tracer)**: `7e5d2c7` (feat)
3. **Task 3: partials, built-in layouts, layout and partial overrides**: `5df1ec2` (feat)
4. **Task 4: samples, hashes, index sync, draft editor**: `495319e` (feat)
5. **Task 5: Branding**: `935e4bf` (feat(attach)), then `2bf9081` (feat(postcard))
**Plan metadata:** committed together with this summary (docs).
Commit subjects are the ones the plan's "Execution units" table fixes; each body ends with "Plan 35-01, task N". The measured commit count since the plan's base is 6: `f8fa0f1 docs(31): capture phase context` was committed on master by another session during this run and is not part of this plan.
## Verification results
| Check | Result |
|-------|--------|
| `go vet ./... && go test -short ./...` | pass (after every commit) |
| `go test ./modules/postcard/... ./modules/lagoon/... ./modules/pact/...` (Docker) | pass |
| `TestMailOverrideSmoke`, `TestMailPartialsSmoke`, `TestMailEditorSmoke`, `TestMailBrandSmoke` | pass, no skips without `-short` |
| `go test ./cmd/summer -run 'TestCommandsDocumented\|TestDocsTree'`, `summer docs:build --check` | pass ("no problems found") |
| `cd examples/hello && go test ./...` | pass |
| sm-user-plugin `TestMail\|TestPolishMailSubjects` | pass, working tree unchanged |
| sm-paymentgateway-plugin `TestMailCatalog\|TestMailTracer\|TestMailersMatrixSmoke` | pass, working tree unchanged |
| Every task's acceptance criteria | pass |
| Tracer gate after Task 2 (interactive, end-of-phase, automated-only verify) | re-run, pass, continued without a checkpoint |
Not committed, run once as a scratch check: the placeholder walker rendered all 172 real template files found in the sibling plugin repositories without error (research Pitfall 3).
## Names for 35-02, 35-03 and 35-04
Every name fixed by P35-01..P35-05 is as the plan states. Names and behaviours the plan left open, or where the code is more specific than the plan's text:
- **Partial token:** `MAILPARTIAL` + 32 upper-case hex digits + `X<n>X` (the plan wrote `MAILPARTIAL<nonce><n>`); the terminator keeps one token from being a prefix of another.
- **Index on templates:** `system_mail_templates_layout_id_index`.
- **`postcard.Kind` values:** `"template"`, `"layout"`, `"partial"`, `"brand"`.
- **`DraftError.Rule` values:** `parse`, `render`, `unsafe`, `subject_line`, `layout`, `partial`, `no_content`, `colour`. A `partial` call with an odd argument count or a non-string key is `render`, not `partial`; `partial` is only "no such partial" and sets `Name`.
- **`DraftError.Field` for Branding:** the colour's column name (`body_bg` ... `table_border_color`); `Message` is empty for `colour`, `layout`, `no_content` and `subject_line`.
- **`Draft`:** `Layout` empty on a template draft keeps the file's layout. A layout draft with an empty `Name` is rendered under the code `draft`. A Branding draft uses `Draft.Brand`; nil is the default brand.
- **Template drafts need a catalog template:** `Validate` and `Preview` of a `KindTemplate` draft whose `Name` is not registered return rule `render` on `body`.
- **`TemplateLocale`:** matches the longest listed locale after a dash in the last dotted segment, ignoring case, and returns it as spelled in `locales` (so `-pt-BR` works).
- **`FormatLayout`:** a non-empty `css` is appended as a fourth `==` section, for display and comparison only (layout files have no CSS section).
- **`SyncIndex`:** serialized by `pg_advisory_xact_lock(hashtext('summercms.postcard.sync'))`; a row that already matches is not written, so `updated_at` does not move. It returns an error when the tables are missing (35-02 retries on the first list request, as planned).
- **`ResetOverride`:** returns an error for a code the catalog does not hold, for a database-only layout, for `KindBrand`, and when no file-backed row has that code.
- **Layout name:** `SyncIndex` always sets `name` from the file header for file layouts and partials, as the plan says, so `name` is not an override column for them.
- **Sample message:** `assets/sample.htm`, parsed as `postcard::mail.sample`; it is not registered in the catalog and cannot be sent by name.
- **Smoke test names:** `TestMailOverrideSmoke`, `TestMailPartialsSmoke`, `TestMailEditorSmoke`, `TestMailBrandSmoke`. The `-run` patterns in 35-VALIDATION.md (`TestOverride`, `TestStore`, `TestPartial`, `TestSample`, `TestValidateDraft`, `TestBrand`, `TestSync`) match none of them; 35-04 either adds tests under those names or updates the map.
- **Test helper:** `mailPostgres(t)` in `override_smoke_test.go` gives each caller a fresh migrated database on one shared container.
## Decisions Made
- **The override-failure log is written only when the file version then renders.** The plan orders "log, then render the file version". When both renders fail (a caller subject with a line break, for example) the cause is the caller's, so the file version's error is returned and nothing claims a file version was sent.
- **`Validate` checks a template body's source for script, iframe, object and embed tags** in addition to the rendered output. Markdown drops such a tag silently at send, so without the source check the behaviour the plan lists ("`<script>` gives rule unsafe") could not occur for a template body.
- **Branding is part of the file version.** `Overrides.empty()` ignores `Brand`, and the fallback render keeps the compiled CSS and logo.
- **Logo problems travel as warnings on `Overrides`** (an unexported field) and are logged by the mailer through its rate limiter, so the source needs no logger. The files table is read under a savepoint, so a failure there does not lose the other overrides.
- **`NewDBSource` silences GORM's logger for its own queries.** The mailer reports a failed lookup once a minute; GORM's line per send would repeat it.
- **Typed errors keep send texts unchanged.** `renderError`, `tmplError`, `unsafeError` and `partialError` print what the old `fmt.Errorf` calls printed.
## Deviations from Plan
### Auto-fixed Issues
None. No bug, missing critical piece or blocker outside the plan's text came up.
### CLAUDE.md-driven adjustments
**1. [Rule 2 - CLAUDE.md] No separate RED commits for the `tdd="true"` tasks**
- **Found during:** Tasks 3, 4 and 5
- **Issue:** The MSD TDD flow commits a failing test first. CLAUDE.md requires `go vet` and `go test` green at every commit, and the plan's "Execution units" table fixes one commit per task.
- **Adjustment:** Tests were written before the implementation and each task was committed once, green.
- **What was and was not observed:** For Task 3 and Task 5 the test was run against signature-only stubs first and every target subtest failed on its assertions. For **Task 4 no RED run was observed**: the implementation was written straight after the test file and passed on the first run. To check that those tests can fail, five mutations were applied afterwards (placeholder format, sync overwriting a customized subject, sync always writing, hash without CRLF normalization, editor keeping the stored template override); each was caught by the expected subtest and reverted. No `tdd-red-evidence` records were persisted.
### Plan inconsistencies (reported, not changed)
- **`key_links` names `modules/postcard/brand.go` for `attach.AbsolutePublicURL`.** The Task 5 action and its acceptance criterion put the call in `NewDBSource`, so it is in `modules/postcard/store.go`. `brand.go` does not contain the pattern; a mechanical key-link check will report it.
- **`pact.ListRowStates` doc comment now says five constants are kept**, as the plan instructs. cabana's `rowStateOrder` still lists three and drops the two new ones until 35-02 changes it; `docs/backend/lists-and-filters.md` still describes three and is 35-02's to update.
---
**Total deviations:** 1 CLAUDE.md-driven adjustment (commit shape of TDD tasks), 0 auto-fixes.
**Impact on plan:** None on scope or API. The TDD evidence is weaker than the MSD reference asks for on Task 4.
## Issues Encountered
- **One unrelated test failure under load.** `modules/pier` `TestStatelessFanOut` failed once in the first full `go test -short ./...` run and passed alone and in five later full runs. Logged in `deferred-items.md`; not investigated.
- **A hung background command of my own.** A mutation-check script stalled on the shell's interactive `cp` alias while `modules/postcard/samples.go` held a deliberate mutation. I stopped that script (my own two processes), restored the file from the backup taken at the start of the script, confirmed all four backed-up files were identical to their backups, and re-ran the checks non-interactively. Nothing mutated was committed.
- **A concurrent commit on master.** Another session committed `f8fa0f1` between Task 4 and Task 5. It touches only Phase 31 planning files.
## Threat Flags
| Flag | File | Description |
|------|------|-------------|
| threat_flag: mail-relay | modules/postcard/editor.go | `Editor.SendDraft` delivers to whatever single address it is given and applies no recipient rule or rate limit. The plan assigns both to the caller (35-02: the admin's own address, 5 per 10 minutes); until that route exists nothing calls it. |
| threat_flag: dependency-surface | modules/postcard/store.go | postcard now imports `modules/lagoon/attach` (as the plan specifies), which brings gocloud blob and the imaging packages into postcard's import graph. No new module in go.mod. |
The threat register's mitigations are in place: validateHTML on bodies, partial outputs and the final HTML (T-35-01); per-render crypto/rand nonce (T-35-02); CR/LF refusal and rule `subject_line` (T-35-03); strict hex colours and the closing-style check on layout CSS (T-35-04); file version on any lookup error (T-35-05); scrubbed `DraftError.Message` (T-35-06); logo URL from operator config only (T-35-07); no cache (T-35-08).
## Known Stubs
None.
## User Setup Required
None. No external service or new configuration key. An application picks up the new tables with its next `migrate`.
## Next Phase Readiness
- 35-02 can build on the API as listed in its `<interfaces>` block; its precondition (`feat(postcard): mail branding and the logo URL` in the log, `func EditorFrom` in `editor.go`) holds.
- 35-02 owns: cabana's `rowStateOrder`, messages and `docs/backend/lists-and-filters.md` for the two new row states; the serve-start `SyncIndex` call; the recipient rule and rate limit around `SendDraft`.
- Nothing was pushed or tagged. No file in a sibling repository was changed.
## Self-Check: PASSED
- All 18 created files exist on disk.
- Commits `7e5d2c7`, `5df1ec2`, `495319e`, `935e4bf`, `2bf9081` are in `git log`.
- `must_haves.artifacts` patterns are present in their files; of the four `key_links`, three match and the `brand.go` one does not (see "Plan inconsistencies").
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*

View File

@@ -0,0 +1,10 @@
# Phase 35: deferred items
Out-of-scope discoveries made while executing Phase 35 plans. Not fixed here.
## Deferred Items
- `modules/pier` `TestStatelessFanOut` failed once under the full `go test -short ./...` run during 35-01
status: open
**What:** subtest "a stateless-only instance applies a revocation from the other instance" reported "B never evicted its stateless server: the revocation did not reach it" after its 10 s wait. It passed when the package was run alone and in every later full run (five more). It looks timing-sensitive under parallel package load.
**Why deferred:** pier is unrelated to the mail work; 35-01 changed nothing it uses at run time.