From db86b51a51529abb74cbbf8a2a55be1b1a47e073 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 11:11:01 +0100 Subject: [PATCH] docs(35-01): complete mail domain layer plan --- .planning/ROADMAP.md | 4 +- .planning/STATE.md | 207 ++++++++++-- .../35-01-SUMMARY.md | 307 ++++++++++++++++++ .../deferred-items.md | 10 + 4 files changed, 501 insertions(+), 27 deletions(-) create mode 100644 .planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md create mode 100644 .planning/phases/35-mail-templates-and-layouts-editor/deferred-items.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b239424b..f4e1d203 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -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 diff --git a/.planning/STATE.md b/.planning/STATE.md index 943d06d4..96db4854 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -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--.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:, category::), 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 diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md new file mode 100644 index 00000000..ce2634dd --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md @@ -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. 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 + XX, 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. 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.` 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 + `XX` (the plan wrote `MAILPARTIAL`); 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 ("`