From ed17833ab76656ece632e4816220919a726a2476 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Sun, 15 Nov 2026 09:11:11 +0100 Subject: [PATCH] docs(quick-261115-cha): let a mail template use another plugin's layout by full code --- .planning/STATE.md | 11 +- .../261115-cha-PLAN.md | 189 ++++++++++++++++++ .../261115-cha-SUMMARY.md | 93 +++++++++ 3 files changed, 288 insertions(+), 5 deletions(-) create mode 100644 .planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-PLAN.md create mode 100644 .planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-SUMMARY.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 7973147a..0d04f809 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,10 +5,10 @@ current_phase: 35 current_phase_name: Mail templates and layouts editor status: executing stopped_at: Completed 35-09-PLAN.md -last_updated: "2026-11-14T17:48:30.900Z" -last_activity: 2026-11-14 -last_activity_desc: "Completed quick task 261114-p5n: plugin mail layouts styled like the default layout" -state_head: 4ef3aa1f90a9edfd6757f1269904c0ad4109c56d +last_updated: "2026-11-15T08:11:02.263Z" +last_activity: 2026-11-15 +last_activity_desc: "Completed quick task 261115-cha: Let a mail template use another plugin's layout by full code (G-35-9)" +state_head: b8487b028b5ee689dc3c106abda9cc68bfe6ec30 progress: total_phases: 52 completed_phases: 37 @@ -32,7 +32,7 @@ See: .planning/PROJECT.md (updated 2026-10-22) Phase: 35 (Mail templates and layouts editor) — EXECUTING Plan: 9 of 9 Status: Ready to execute -Last activity: 2026-11-14 - Completed quick task 261114-p5n: plugin mail layouts styled like the default layout +Last activity: 2026-11-15 - Completed quick task 261115-cha: Let a mail template use another plugin's layout by full code (G-35-9) Progress: [████████░░] 82% @@ -1269,6 +1269,7 @@ Recent decisions affecting current work: | 261108-pe4 | beachcomber highlights and field projection: Query.IncludeFields/ExcludeFields/Highlight, SearchResult.Hits (plain-text segments), HighlightSearcher + SupportsHighlights; Typesense parses v1 highlights | 2026-11-08 | 7819c67 | [261108-pe4-beachcomber-highlights-and-field-project](./quick/261108-pe4-beachcomber-highlights-and-field-project/) | | 261114-p5m | Fix CR-02 residual: quoted end tags in raw-text elements bypass the postcard scheme check | 2026-11-14 | f1f284a0 | [261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra](./quick/261114-p5m-fix-cr-02-residual-quoted-end-tags-in-ra/) | | 261114-p5n | Style the user and paymentgateway plugin mail layouts like the postcard default layout | 2026-11-14 | 4ef3aa1f | [261114-p5n-style-the-user-and-paymentgateway-plugin](./quick/261114-p5n-style-the-user-and-paymentgateway-plugin/) | +| 261115-cha | Let a mail template use another plugin's layout by full code (G-35-9) | 2026-11-15 | b8487b02 | [261115-cha-let-a-mail-template-use-another-plugin-s](./quick/261115-cha-let-a-mail-template-use-another-plugin-s/) | ## Deferred Items diff --git a/.planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-PLAN.md b/.planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-PLAN.md new file mode 100644 index 00000000..2b0b38e0 --- /dev/null +++ b/.planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-PLAN.md @@ -0,0 +1,189 @@ +--- +phase: quick-261115-cha +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - modules/postcard/templates.go + - modules/postcard/mailer.go + - modules/postcard/layout_ref_test.go + - modules/postcard/README.md + - docs/services/mail.md +autonomous: true +requirements: + - QUICK-261115-cha + +estimate: + tokens: 45000 + raw_tokens: 45000 + tasks: 2 + confidence: low + +must_haves: + truths: + - "A template whose header says layout = \"::mail.layouts.\" naming a layout another plugin already registered in the catalog registers without error, Catalog.Template reports that full code as its Layout, and a send renders the HTML part in that layout's HTML wrapper and the text part in its text wrapper (UAT gap G-35-9, framework half)" + - "A full layout code that no registered plugin declares (owner not registered yet, or a name the owner never declared) fails Catalog.Register with an error that starts with 'postcard: unknown layout ', names the template, and says the owning plugin must be required so it registers first" + - "Another plugin's short alias is still refused: a borrower template with layout = \"card\", where card is only the lender's alias, fails with the unchanged 'postcard: unknown layout card' error" + - "Existing resolution is unchanged: empty and default give the default alias, the plugin's own alias wins, then the built-in aliases system and minimal; the error text of an unknown short alias is byte-identical; every existing postcard and cabana test passes unchanged, and sm-user-plugin and sm-paymentgateway-plugin pass against this checkout (scripts/check-phase35.sh --consumers)" + - "The admin path works with a cross-plugin layout without cabana changes: Editor.Validate accepts a borrower template draft whose Layout is the lender's full code and one with an empty Layout (keeps the file's layout); Editor.Preview renders it in the lender's layout; a TemplateOverride naming the lender's layout and a customized lender layout (Overrides.Layouts) both apply to a borrower template's send; SyncIndex points the borrower template row's layout_id at the lender's layout row" + - "modules/postcard/README.md and docs/services/mail.md describe the full-code form of the layout key, its resolution order and the require-the-owner rule, with an example layout = \"acme.blog::mail.layouts.blog\" line; go test ./cmd/summer -run TestDocsTree and go run ./cmd/summer docs:build --check pass" + artifacts: + - path: modules/postcard/templates.go + provides: "resolveLayoutLocked resolves own alias, then built-in alias, then a full layout code already in c.layouts; new error for an unregistered full code; field and function comments updated" + - path: modules/postcard/mailer.go + provides: "BootPlugin doc comment says unknown layouts (aliases or full codes) fail with the dotted name" + - path: modules/postcard/layout_ref_test.go + provides: "TestCrossPluginLayout (Register/send/errors/precedence), TestCrossPluginLayoutOverride (override, customized owner layout, Editor Validate/Preview) and TestCrossPluginLayoutSync (Docker, SyncIndex layout_id), with acme.lender / acme.borrower fixtures" + - path: modules/postcard/README.md + provides: "Features bullets, Built-in layouts section and the Catalog.Register reference-table row describe full-code layout references" + - path: docs/services/mail.md + provides: "Templates and layouts paragraphs and a short subsection on using another plugin's layout" + key_links: + - from: "modules/party/registry.go boot loop (postcard.BootPlugin per plugin in Requires() topological order)" + to: "modules/postcard/templates.go Catalog.Register -> resolveLayoutLocked" + via: "the owner plugin's MailLayouts are in c.layouts before a requiring plugin's templates resolve, so a full code of the owner's layout is found" + - from: "parsedTemplate.layout (full code after resolveLayoutLocked)" + to: "layoutFor -> layoutByCode (render), TemplateFile.Layout (SyncIndex layout_id subquery by code, cabana diff/file view)" + via: "every consumer already reads the resolved full code from c.layouts with no plugin scoping, so no change there" + - from: "cabana mail_admin.go layout picker (scopeLayouts over catalog Layouts) and save (layoutCode -> postcard.Draft.Layout -> Editor.Validate)" + to: "Catalog.layoutByCode" + via: "already offers and accepts every catalog layout, so a DB override of a borrower template can keep or pick the lender's layout; verified by tests, not edited" +--- + + +Let a mail template use another plugin's layout by its full code, closing the framework half of UAT gap G-35-9 (phase 35). + +Today `Catalog.resolveLayoutLocked` (modules/postcard/templates.go, line ~227) looks a template's `layout` header value up only in the registering plugin's own aliases (`c.aliases[t.pluginID]`) and in `builtinLayoutAliases`. Anything else fails at boot with `postcard: unknown layout `. So the mfa plugin (which requires golem15.user) cannot point its two_factor_code templates at `golem15.user::mail.layouts.user`, and it renders in the bare Default layout. + +Change: after the plugin's own alias and the built-in aliases, a value containing `::` that names a layout already in `c.layouts` resolves to that full code. party boots plugins in `Requires()` order and calls `postcard.BootPlugin` for each one, so a plugin that requires the owner registers after the owner's layouts are in the catalog. A full code no registered plugin declares still fails at Register, with an error that says the owning plugin must be required. Everything downstream (render `layoutFor`/`layoutByCode`, `TemplateFile.Layout`, `SyncIndex` layout_id, the cabana layout picker, `Editor.Validate`) already works on full codes across plugins. The planner read that code: it needs no change and gets tests only. + +Purpose: plugins that depend on another plugin can share its branded layout instead of copying it. Non-breaking: existing templates and the user and paymentgateway plugins on v0.6.0 resolve exactly as before. + +Output: the resolver change, a new test file, README and docs updates (code, tests and docs in one commit, per CLAUDE.md), then a tests-only commit covering the override, editor and index paths. + + + +@~/.claude/msd-core/workflows/execute-plan.md +@~/.claude/msd-core/templates/summary.md + + + +@CLAUDE.md +@.planning/STATE.md +@.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md +@modules/postcard/templates.go +@modules/postcard/README.md +@docs/services/mail.md + +Interfaces the executor uses (already in the tree, read once, do not re-derive): +- `func (c *Catalog) Register(pluginID string, fsys fs.FS, templates []string, layouts map[string]string) error`: layouts are loaded into `c.layouts` before templates resolve, in the same call. +- `func (c *Catalog) Template(name string) (TemplateFile, bool)`: `TemplateFile.Layout` is the resolved full name. +- Test helpers in package postcard: `fakeOverrides{ov: Overrides{...}}` (partials_smoke_test.go:81), `sendTemplate(t, m, drv, name, vars) RenderedMessage` (partials_smoke_test.go:137), `lastMessage(t, drv)` (override_smoke_test.go:245), `mailPostgres(t) *gorm.DB` (override_smoke_test.go:41, skips under -short), `&Editor{m: m.(*mailer)}` (editor_test.go:17). +- `func (e *Editor) Validate(ctx, Draft) *DraftError`, `func (e *Editor) Preview(ctx, Draft) (Preview, error)` with `Preview{Subject, HTML, Text}`. +- `func SyncIndex(ctx, db *gorm.DB, cat *Catalog, locales []string) error`; table names `TemplatesTable`, `LayoutsTable`. +- The fixture names `acme.lender` and `acme.borrower` are unused anywhere in modules/postcard or modules/cabana (planner grep), so the Docker test's rows cannot collide with other tests' acme.blog rows in the shared container. + + + + + + Task 1: Resolve a full layout code of another plugin's layout, end to end through Register, send and docs + modules/postcard/layout_ref_test.go, modules/postcard/templates.go, modules/postcard/mailer.go, modules/postcard/README.md, docs/services/mail.md + + - file_layout_by_full_code: lender (acme.lender, own alias card -> acme.lender::mail.layouts.card) registered first, then borrower (acme.borrower, no MailLayouts) with templates acme.borrower::mail.code and acme.borrower::mail.code-en, both with layout = "acme.lender::mail.layouts.card". Register succeeds; Catalog.Template(...).Layout is acme.lender::mail.layouts.card for both; a send of each renders HTML containing the lender card element with the body's strong text inside it, and Text containing the lender text wrapper's footer line + - owner_registers_later: the borrower registered on a catalog without the lender fails; the error contains "unknown layout acme.lender::mail.layouts.card", the template name acme.borrower::mail.code and the word "required" + - unknown_full_code: lender registered, borrower template with layout = "acme.lender::mail.layouts.nope" fails with "unknown layout acme.lender::mail.layouts.nope" + - other_plugin_alias_refused: lender registered, borrower template with layout = "card" fails and err.Error() equals exactly "postcard: unknown layout card" (the existing message, unchanged) + - precedence_unchanged: the lender's own template with layout = "card" resolves to acme.lender::mail.layouts.card; a borrower template with layout = "system" resolves to postcard::mail.layouts.system; one with no layout key resolves to postcard::mail.layouts.default (Catalog.Template Layout) + - builtin_full_code: a borrower template with layout = "postcard::mail.layouts.minimal" registers and resolves to that code + + +Before editing, run git status --short on the five files; other sessions share this tree, and if any of them shows an uncommitted edit you did not make, stop and report it instead of editing over it. + +RED first: create modules/postcard/layout_ref_test.go (package postcard) with fixture helpers lenderFS() and borrowerFS(header string) returning fstest.MapFS, and TestCrossPluginLayout (t.Parallel()) with the six subtests in , each on its own NewCatalog(). The lender ships views/mail/layouts/card.htm in the layout format: name = "Card", ==, a text wrapper of {{ .Content }}, a blank line and the line "-- Lender card", ==, an HTML wrapper div with class lender-card around {{ .Content }}. The lender also ships views/mail/notice.htm with layout = "card". Give the layout no style block, so inlining does not touch it. The borrower's templates have subject "Code {{ .code }}" and the body "Your code is **{{ .code }}**." Send through NewMailer(cat, NewMemoryDriver(), Options{}) and sendTemplate with Vars code 123456. Run go test -short ./modules/postcard -run 'TestCrossPluginLayout$' and confirm file_layout_by_full_code, owner_registers_later and builtin_full_code fail against the unmodified resolver, which reports "unknown layout acme.lender::mail.layouts.card" with no require hint. + +GREEN, modules/postcard/templates.go, resolveLayoutLocked only. Keep the trimmed value and the empty/default branch as they are. Keep the lookup order: the plugin's own alias first, then builtinLayoutAliases. Only when both miss and the value contains "::", look the value up in c.layouts. If it is there, that value is the full name. If it is not, return the new error, formatted as: postcard: unknown layout in