docs(quick-261115-cha): let a mail template use another plugin's layout by full code
This commit is contained in:
@@ -5,10 +5,10 @@ current_phase: 35
|
||||
current_phase_name: Mail templates and layouts editor
|
||||
status: executing
|
||||
stopped_at: Completed 35-09-PLAN.md
|
||||
last_updated: "2026-11-14T17: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
|
||||
|
||||
|
||||
@@ -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 = \"<vendor.plugin>::mail.layouts.<name>\" 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 <code>', 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"
|
||||
---
|
||||
|
||||
<objective>
|
||||
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 <value>`. 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.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@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.
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer" tdd="true">
|
||||
<name>Task 1: Resolve a full layout code of another plugin's layout, end to end through Register, send and docs</name>
|
||||
<files>modules/postcard/layout_ref_test.go, modules/postcard/templates.go, modules/postcard/mailer.go, modules/postcard/README.md, docs/services/mail.md</files>
|
||||
<behavior>
|
||||
- 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
|
||||
</behavior>
|
||||
<action>
|
||||
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 <behavior>, 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 <value> in <template name>: no registered plugin declares it (the plugin that owns it must be required, so it registers first). A value without "::" that misses both maps keeps the existing error, byte for byte (postcard: unknown layout <value>). Keep the final c.layouts presence check for alias results. Do not touch Register's alias loop, the reserved default alias, the duplicate checks or assertOwner: a plugin still declares only layouts in its own namespace and only uses other plugins' layouts. Update the parsedTemplate.layout field comment (the header's alias or full layout code; after resolveLayoutLocked the full name or the default alias), and add a doc comment on resolveLayoutLocked describing the three-step order. In modules/postcard/mailer.go, change only the BootPlugin doc comment's last sentence so that it says unknown layouts (aliases or full layout codes) fail with the dotted name. Leave pact's HasMailTemplates comment alone, since MailLayouts still maps aliases.
|
||||
|
||||
Docs, in the same commit (CLAUDE.md documentation rule). Use neutral names only: acme.blog owns the layout acme.blog::mail.layouts.blog, and acme.shop requires acme.blog. Never name golem15.user, mfa or another consuming plugin or app.
|
||||
- modules/postcard/README.md, Features: in the bullet at line ~25, "unknown layout aliases fail at boot" becomes "unknown layouts fail at boot". The bullet at line ~27 gains a sentence: a template may also name a layout another plugin registered by its full name.
|
||||
- modules/postcard/README.md, Built-in layouts and partials section: after the paragraph at line ~182 that starts "A template selects one with", add a paragraph. It gives the resolution order (empty or default, the plugin's own alias, the built-in alias, then the full name of any registered layout, a built-in one included). It says another plugin's short alias is not visible, and that a full name must belong to a plugin that is already registered: list the owner in Requires(), and party boots it first. Otherwise start-up fails with postcard: unknown layout. Include the example line layout = "acme.blog::mail.layouts.blog" in a template of acme.shop.
|
||||
- modules/postcard/README.md, reference table (the section after Usage): the postcard.Catalog.Register row adds that a template's layout may be an alias or the full name of a layout already in the catalog.
|
||||
- docs/services/mail.md, line ~13: "an unknown layout alias fails the start-up" becomes "a layout the template names that is not registered fails the start-up". Line ~15: "the `layout` alias" becomes "the `layout` (an alias or a full layout name)".
|
||||
- docs/services/mail.md, after the Built-in layouts table and the "A plugin's own alias wins" line: add a short subsection "Another plugin's layout". It shows the acme.shop template header with layout = "acme.blog::mail.layouts.blog", the require-the-owner rule, and that another plugin's alias does not work. It also says the admin's layout picker already lists every layout, so a customized template can keep or change it.
|
||||
Every backticked Go identifier you add must exist (the docs checker enforces it). Grep the package before writing one, and prefer prose over new identifiers.
|
||||
|
||||
Run the verify gates, then commit only these five paths, staged by explicit path: feat(quick-261115-cha): let a mail template use another plugin's layout by full code. No co-author tags.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./modules/postcard && go test -short -count=1 ./modules/postcard && test "$(go test -short -count=1 -v ./modules/postcard -run 'TestCrossPluginLayout$' | grep -cE -- '--- PASS: TestCrossPluginLayout/')" -ge 6 && go test -count=1 ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented' && go run ./cmd/summer docs:build --check && grep -q 'layout = "acme.blog::mail.layouts.blog"' modules/postcard/README.md && grep -q 'layout = "acme.blog::mail.layouts.blog"' docs/services/mail.md && git diff --quiet -- go.mod go.sum modules/cabana</automated>
|
||||
</verify>
|
||||
<done>The six TestCrossPluginLayout subtests pass, and the three that need the new behaviour were seen failing before the resolver change. The whole short postcard suite passes unchanged. A borrower template renders HTML and text in the lender's layout by full code. An unregistered full code fails with the require hint, and another plugin's alias fails with the unchanged message. README and docs describe the rule and pass the docs checker. One commit holds templates.go, mailer.go, layout_ref_test.go, README.md and docs/services/mail.md. go.mod, go.sum and modules/cabana are untouched.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Cover the override, editor and index paths with a cross-plugin layout, and prove nothing else moved</name>
|
||||
<files>modules/postcard/layout_ref_test.go</files>
|
||||
<precondition>Docker is reachable for the testcontainers Postgres test: docker info succeeds directly, or through sudo -u golem as CLAUDE.md describes for a shell that predates the docker group.</precondition>
|
||||
<behavior>
|
||||
- TestCrossPluginLayoutOverride/override_layout_full_code: borrower template acme.borrower::mail.plain with no layout key (default layout); Overrides{Template: &TemplateOverride{Subject, Body, Layout: "acme.lender::mail.layouts.card"}} via fakeOverrides; the send's HTML has the lender card element, and its Text has the lender footer line
|
||||
- TestCrossPluginLayoutOverride/customized_owner_layout: the borrower code template (file layout = lender card) sent with Overrides.Layouts["acme.lender::mail.layouts.card"] = LayoutOverride{HTML: a section with id customized-card around {{ .Content }}, Text: "{{ .Content }}"}; HTML has the customized section and not the file's lender-card class
|
||||
- TestCrossPluginLayoutOverride/editor_validate_and_preview: Editor.Validate returns nil for a KindTemplate draft of acme.borrower::mail.code with Layout "acme.lender::mail.layouts.card", and also with Layout "" (keeps the file layout); Editor.Preview of the empty-Layout draft has HTML with the lender card element
|
||||
- TestCrossPluginLayoutSync (Docker, skips under -short): after SyncIndex(ctx, mailPostgres(t), cat, []string{"en"}) on a catalog with lender then borrower registered, the borrower code and code-en rows join through layout_id to the LayoutsTable row whose code is acme.lender::mail.layouts.card; a second SyncIndex leaves the same layout_id
|
||||
</behavior>
|
||||
<action>
|
||||
Append TestCrossPluginLayoutOverride (t.Parallel()) and TestCrossPluginLayoutSync to modules/postcard/layout_ref_test.go. Reuse the Task 1 fixtures, extending borrowerFS with the plain template if needed rather than adding a second fixture style. TestCrossPluginLayoutSync starts with mailPostgres(t), which already skips under -short. Query the join with gdb.Raw over TemplatesTable and LayoutsTable, selecting the layout code for each borrower template code. Run the subtests and confirm that the existing code (render layoutFor/layoutByCode, Editor.renderTemplate's layoutByCode check, SyncIndex's layout_id subquery by code) passes them with no production change. That is the expected outcome, because all of them resolve a full code against the whole catalog with no plugin scoping. If a subtest fails, read the path at fault and fix it in modules/postcard. Update README.md and docs/services/mail.md in the same commit if the fix changes described behaviour, and record the deviation in the SUMMARY. Do not edit modules/cabana: its picker (scopeLayouts over the catalog's Layouts) and save (layoutCode, then postcard.Draft.Layout, then Editor.Validate) already accept any catalog layout.
|
||||
|
||||
Then run the regression gates in <verify>. Run the Docker test directly. If the docker socket is denied, rerun the same go test through sudo -u golem. Run scripts/check-phase35.sh --consumers. It runs sm-user-plugin and sm-paymentgateway-plugin read-only against this checkout and proves that the plugins on v0.6.0 behave identically. If it refuses only because a sibling working tree is dirty from another session, do not touch the sibling. Record the refusal in the SUMMARY with the per-plugin commands the script prints, and run those by hand under the scratch modfile it describes.
|
||||
|
||||
Commit only modules/postcard/layout_ref_test.go (plus any fix files from the deviation path), staged by explicit path: test(quick-261115-cha): cover cross-plugin mail layouts through overrides, the editor and the index. No co-author tags. Do not touch .planning/G15OFFICE.md, .planning/state.json, the phase 35 deferred-items.md or examples/hello/plugins.gen.go.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./... && go test -short -count=1 ./modules/postcard/... ./modules/cabana/... && test "$(go test -short -count=1 -v ./modules/postcard -run 'TestCrossPluginLayoutOverride' | grep -cE -- '--- PASS: TestCrossPluginLayoutOverride/')" -ge 3 && go test -count=1 -v ./modules/postcard -run 'TestCrossPluginLayoutSync' | grep -q -- '--- PASS: TestCrossPluginLayoutSync' && git diff --quiet -- go.mod go.sum modules/cabana && scripts/check-phase35.sh --consumers</automated>
|
||||
</verify>
|
||||
<done>The three TestCrossPluginLayoutOverride subtests pass, so a DB template override and a customized owner layout both work for a borrower template, and Editor.Validate and Preview accept and render the lender's layout. TestCrossPluginLayoutSync passes on Docker (not skipped), with layout_id pointing at the lender's row. go vet ./... and the short postcard and cabana suites are green. The consumers stage passes, or its dirty-sibling refusal is recorded together with the hand-run results. modules/cabana, go.mod and go.sum are unchanged. One tests-only commit.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| plugin mail files -> catalog at boot | Template headers come from compiled-in plugin assets; a header can now name a layout owned by another plugin |
|
||||
| admin template override -> render | An administrator's saved layout choice (layout_id) reaches the render as a full layout code |
|
||||
| framework change -> consuming apps | User and paymentgateway plugins on v0.6.0 boot against this resolver; a behaviour change breaks their start-up |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-cha-01 | Tampering | resolveLayoutLocked full-code branch | low | accept | Only layouts already registered by compiled-in plugins (or postcard built-ins) can be named; a plugin still cannot register a layout outside its namespace (assertOwner untouched), and every rendered layout passes validateHTML before send exactly as before |
|
||||
| T-cha-02 | Denial of service | boot ordering (owner not required) | low | mitigate | Fails closed at Register with an error naming the code, the template and the require rule (owner_registers_later subtest); docs state the Requires() rule |
|
||||
| T-cha-03 | Denial of service (breaking change) | existing alias resolution | medium | mitigate | Own alias and built-in lookups run first and unchanged; the short-alias error is asserted byte-identical (other_plugin_alias_refused); full postcard/cabana short suites and scripts/check-phase35.sh --consumers (user, paymentgateway) must pass |
|
||||
| T-cha-04 | Elevation of privilege | admin layout picker | low | accept | No cabana change; the picker was already scoped to catalog layouts plus database-only layouts and gated by the existing mail permissions |
|
||||
| T-cha-SC | Tampering | npm/pip/cargo/go installs | low | accept | No dependency added; gate git diff --quiet -- go.mod go.sum |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- go vet ./... clean; go test -short ./modules/postcard/... ./modules/cabana/... green.
|
||||
- TestCrossPluginLayout (6 subtests) and TestCrossPluginLayoutOverride (3 subtests) pass; TestCrossPluginLayoutSync passes on Docker.
|
||||
- go test ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented' and go run ./cmd/summer docs:build --check pass.
|
||||
- scripts/check-phase35.sh --consumers passes (or its dirty-sibling refusal is recorded with hand-run plugin results).
|
||||
- git diff --quiet -- go.mod go.sum modules/cabana.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- A template header layout = "<owner>::mail.layouts.<name>" renders in that registered layout (HTML and text) when the owner registered first; an unregistered full code fails at boot with the require hint; another plugin's alias is still refused with the unchanged message.
|
||||
- Overrides, the editor's validate/preview and the index all work with the cross-plugin layout with no cabana change.
|
||||
- Existing plugins and templates behave identically; README and docs updated in the code commit.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/quick/261115-cha-let-a-mail-template-use-another-plugin-s/261115-cha-SUMMARY.md` when done. It must include this follow-up line verbatim under a "Follow-up" heading:
|
||||
|
||||
- sm-mfa-plugin sets `layout = "golem15.user::mail.layouts.user"` in both two_factor_code templates after requiring the framework version that ships this.
|
||||
|
||||
Also note that UAT gap G-35-9 stays open until that plugin follow-up lands (the framework half is done here), and record the Docker and consumers gate outcomes.
|
||||
</output>
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
phase: quick-261115-cha
|
||||
plan: 01
|
||||
subsystem: postcard
|
||||
status: complete
|
||||
tags: [mail, layouts, postcard, cross-plugin]
|
||||
requires: []
|
||||
provides:
|
||||
- "A mail template's layout header may name another registered plugin's layout by full code"
|
||||
affects:
|
||||
- modules/postcard
|
||||
- docs/services/mail.md
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Layout resolution order: default -> own alias -> built-in alias -> full code already in the catalog"
|
||||
key-files:
|
||||
created:
|
||||
- modules/postcard/layout_ref_test.go
|
||||
modified:
|
||||
- modules/postcard/templates.go
|
||||
- modules/postcard/mailer.go
|
||||
- modules/postcard/README.md
|
||||
- docs/services/mail.md
|
||||
decisions:
|
||||
- "A full layout code resolves only against layouts already in the catalog; the owner must be in Requires() so party registers it first, otherwise Register fails with a require hint"
|
||||
- "Another plugin's short alias stays invisible and its error text is byte-identical (postcard: unknown layout <alias>)"
|
||||
metrics:
|
||||
duration: 4m
|
||||
completed: 2026-11-15
|
||||
actuals:
|
||||
tokens: 6200
|
||||
tasks: 2
|
||||
commits: 2
|
||||
plan_head_before: 42ab223e79254ad6899659ce159220faf433f6ba
|
||||
plan_head_after: b8487b028b5ee689dc3c106abda9cc68bfe6ec30
|
||||
---
|
||||
|
||||
# Phase quick-261115-cha Plan 01: Cross-plugin mail layouts by full code Summary
|
||||
|
||||
A mail template can now set `layout = "<owner>::mail.layouts.<name>"` to use a layout another, already registered plugin declares. `Catalog.resolveLayoutLocked` tries the plugin's own alias, then the built-in aliases, then (for a value containing `::`) any full layout code in the catalog. An unregistered full code fails at boot with `postcard: unknown layout <code> in <template>: no registered plugin declares it (the plugin that owns it must be required, so it registers first)`.
|
||||
|
||||
## Tasks
|
||||
|
||||
| Task | Name | Commit | Files |
|
||||
|------|------|--------|-------|
|
||||
| 1 (tracer, TDD) | Resolve a full layout code of another plugin's layout, end to end through Register, send and docs | 1fb42542 | templates.go, mailer.go, layout_ref_test.go, README.md, docs/services/mail.md |
|
||||
| 2 (TDD) | Cover the override, editor and index paths with a cross-plugin layout | b8487b02 | layout_ref_test.go |
|
||||
|
||||
## What changed
|
||||
|
||||
- `modules/postcard/templates.go`: `resolveLayoutLocked` has a new full-code branch and a doc comment that gives the resolution order. The `parsedTemplate.layout` field comment is updated. Register's alias loop, the reserved `default` alias, the duplicate checks and `assertOwner` are unchanged.
|
||||
- `modules/postcard/mailer.go`: the `BootPlugin` doc comment now says unknown layouts (aliases or full layout names) fail.
|
||||
- `modules/postcard/README.md`: the Features bullets, a resolution-order paragraph with the `acme.shop` / `acme.blog::mail.layouts.blog` example, and the `postcard.Catalog.Register` row are updated.
|
||||
- `docs/services/mail.md`: the Templates and layouts wording is updated, and a new "Another plugin's layout" subsection covers the example, the require-the-owner rule, the alias limit and the admin picker.
|
||||
|
||||
## TDD Gate Compliance
|
||||
|
||||
- RED: before the resolver change, `file_layout_by_full_code`, `owner_registers_later` and `builtin_full_code` failed. The old error was `postcard: unknown layout acme.lender::mail.layouts.card`, with no template name and no require hint. `unknown_full_code`, `other_plugin_alias_refused` and `precedence_unchanged` passed as expected, because they pin behaviour that did not change.
|
||||
- GREEN: all 6 `TestCrossPluginLayout` subtests pass after the change.
|
||||
- Task 2: the 3 `TestCrossPluginLayoutOverride` subtests and `TestCrossPluginLayoutSync` passed against the existing code with no production change, as the plan expected (these are regression and coverage tests).
|
||||
|
||||
## Verification gates
|
||||
|
||||
- `go vet ./...`: clean.
|
||||
- `go test -short ./modules/postcard/... ./modules/cabana/...`: green. Existing tests are unchanged.
|
||||
- `go test ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented'` and `go run ./cmd/summer docs:build --check`: pass ("no problems found").
|
||||
- Docker: `docker info` worked directly, with no `sudo -u golem` needed. `TestCrossPluginLayoutSync` ran (it was not skipped) and passed. The borrower `code` and `code-en` rows join to the `acme.lender::mail.layouts.card` layout row, and their `layout_id` stays the same on a second `SyncIndex`.
|
||||
- `scripts/check-phase35.sh --consumers`: passed. Both sibling trees were clean before and after. sm-user-plugin: 2 top-level tests passed. sm-paymentgateway-plugin: 3 top-level tests passed. Both ran against this checkout.
|
||||
- `git diff --quiet -- go.mod go.sum modules/cabana`: unchanged.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None. The plan executed exactly as written.
|
||||
|
||||
Minor placement note: the docs subsection "Another plugin's layout" sits at the end of the Built-in layouts section, after the "Every layout gets these values" paragraph. Putting it straight after the "A plugin's own alias wins" line would have split that section's paragraphs.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## UAT gap G-35-9
|
||||
|
||||
This closes the framework half of G-35-9. The gap stays open until the plugin follow-up below lands.
|
||||
|
||||
## Follow-up
|
||||
|
||||
- sm-mfa-plugin sets `layout = "golem15.user::mail.layouts.user"` in both two_factor_code templates after requiring the framework version that ships this.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: modules/postcard/layout_ref_test.go, modules/postcard/templates.go, modules/postcard/mailer.go, modules/postcard/README.md, docs/services/mail.md
|
||||
- FOUND: 1fb42542, b8487b02
|
||||
Reference in New Issue
Block a user