diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW-DISPOSITION.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW-DISPOSITION.md new file mode 100644 index 00000000..fa2edd2a --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW-DISPOSITION.md @@ -0,0 +1,19 @@ +--- +phase: 35 +source: 35-REVIEW.md +created: 2026-11-13 +--- + +# Review Disposition — Phase 35 + +| ID | Severity | Disposition | Notes | +|----|----------|-------------|-------| +| WR-01 | warning | open | Layout status filter hides database-only layouts | +| WR-02 | warning | open | Unknown filterStatus leaves query unfiltered | +| WR-03 | warning | open | Mail image upload ignores field-level validation details | +| WR-04 | warning | open | Partial preview gated only on content_html | +| IN-01 | info | open | Stale preview HTML after clear-then-retype | +| IN-02 | info | open | Color picker swatch shows last valid when text empty | +| IN-03 | info | open | ListExtendRecords mutates locale/source pointers for display | + +All findings left `open` at execute-phase disposition (advisory; does not block). diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md new file mode 100644 index 00000000..a0ce8346 --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-REVIEW.md @@ -0,0 +1,216 @@ +--- +phase: 35-mail-templates-and-layouts-editor +reviewed: 2026-11-13T13:39:18Z +depth: standard +files_reviewed: 91 +files_reviewed_list: + - admin/src/api/schema.d.ts + - admin/src/api/types.ts + - admin/src/components/form/codeeditor/editor.ts + - admin/src/components/form/codeeditor/load.ts + - admin/src/components/form/fields/CodeEditorField.vue + - admin/src/components/form/fields/ColorPickerField.vue + - admin/src/components/form/fields/DatepickerField.vue + - admin/src/components/form/fields/MailImageField.vue + - admin/src/components/form/fields/MailPreviewField.vue + - admin/src/components/form/fields/MarkdownField.vue + - admin/src/components/form/fields/PartialField.vue + - admin/src/components/form/formContext.ts + - admin/src/components/form/registry.ts + - admin/src/components/list/DataTable.vue + - admin/src/components/list/RowStateBadges.vue + - admin/src/components/mail/insertImage.ts + - admin/src/components/mail/MailImagePicker.vue + - admin/src/styles/main.css + - admin/src/views/FormView.vue + - admin/src/views/ListView.vue + - admin/src/views/SettingsFormView.vue + - modules/beachcomber/engines.go + - modules/beachcomber/searchable.go + - modules/beachcomber/typesense/engine.go + - modules/beachcomber/typesense/highlights.go + - modules/cabana/admin_openapi.go + - modules/cabana/backendscreens/controllers/mailimages/config_form.yaml + - modules/cabana/backendscreens/controllers/maillayouts/config_filter.yaml + - modules/cabana/backendscreens/controllers/maillayouts/config_form.yaml + - modules/cabana/backendscreens/controllers/maillayouts/config_list.yaml + - modules/cabana/backendscreens/controllers/maillayouts/_file_version.htm + - modules/cabana/backendscreens/controllers/maillayouts/_info.htm + - modules/cabana/backendscreens/controllers/mailpartials/config_filter.yaml + - modules/cabana/backendscreens/controllers/mailpartials/config_form.yaml + - modules/cabana/backendscreens/controllers/mailpartials/config_list.yaml + - modules/cabana/backendscreens/controllers/mailpartials/_file_version.htm + - modules/cabana/backendscreens/controllers/mailpartials/_info.htm + - modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml + - modules/cabana/backendscreens/controllers/mailtemplates/config_form.yaml + - modules/cabana/backendscreens/controllers/mailtemplates/config_list.yaml + - modules/cabana/backendscreens/controllers/mailtemplates/_file_version.htm + - modules/cabana/backendscreens/controllers/mailtemplates/_info.htm + - modules/cabana/backend_screens.go + - modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml + - modules/cabana/backendscreens/models/mailimagelibrary/fields.yaml + - modules/cabana/backendscreens/models/maillayout/columns.yaml + - modules/cabana/backendscreens/models/maillayout/fields.yaml + - modules/cabana/backendscreens/models/mailpartial/columns.yaml + - modules/cabana/backendscreens/models/mailpartial/fields.yaml + - modules/cabana/backendscreens/models/mailtemplate/columns.yaml + - modules/cabana/backendscreens/models/mailtemplate/fields.yaml + - modules/cabana/crud.go + - modules/cabana/extension.go + - modules/cabana/field_file.go + - modules/cabana/field_mail.go + - modules/cabana/form_schema.go + - modules/cabana/http.go + - modules/cabana/mail_admin.go + - modules/cabana/mail_diff.go + - modules/cabana/mail_routes.go + - modules/cabana/messages.go + - modules/cabana/query.go + - modules/cabana/relation_field.go + - modules/cabana/schema_types.go + - modules/cabana/settings.go + - modules/conga/commands.go + - modules/lagoon/attach/absolute.go + - modules/lagoon/commands.go + - modules/lagoon/migrations.go + - modules/pact/capabilities.go + - modules/phrasebook/backend/lang/en/lang.yaml + - modules/phrasebook/backend/lang/pl/lang.yaml + - modules/pier/pier.go + - modules/postcard/assets/brand.css.tmpl + - modules/postcard/assets/minimal.htm + - modules/postcard/assets/partials/button.htm + - modules/postcard/assets/partials/panel.htm + - modules/postcard/assets/partials/subcopy.htm + - modules/postcard/assets/partials/table.htm + - modules/postcard/assets/sample.htm + - modules/postcard/assets/system.htm + - modules/postcard/brand.go + - modules/postcard/editor.go + - modules/postcard/mailer.go + - modules/postcard/partials.go + - modules/postcard/samples.go + - modules/postcard/store.go + - modules/postcard/templates.go + - modules/surf/serve.go + - modules/wristband/authorize.go + - scripts/check-phase35.sh +findings: + critical: 0 + warning: 4 + info: 3 + total: 7 +status: issues_found +--- + +# Phase 35: Code Review Report + +**Reviewed:** 2026-11-13T13:39:18Z +**Depth:** standard +**Files Reviewed:** 91 +**Status:** issues_found + +## Summary + +Phase 35 (mail templates/layouts editor) was reviewed at standard depth across postcard, cabana mail screens/routes, and the admin SPA mail editor. Security posture is solid: permission gates, `interactiveOnly` test-send, recipient-key refusal, rate limiting, sandboxed preview iframe (`sandbox=""`), HTML/CSS unsafe-tag checks, colour validation, and image upload limits. Draft validation runs inside the form save transaction (`FormAfterUpdate`), so invalid overrides roll back. Findings below are correctness/UX gaps, not blockers. + +## Narrative Findings (AI reviewer) + +## Warnings + +### WR-01: Layout status filter hides every database-only layout + +**File:** `modules/cabana/mail_admin.go:682-688` +**Issue:** `mailStatusScope` treats "customized" and "outdated" as file-backed only (`is_custom AND source IS NOT NULL`), while "not_customized" is `NOT is_custom`. Database-only layouts have `source IS NULL` and `is_custom = true`, so they match none of the three values. Choosing any status on the layouts list silently drops all custom layouts. +**Fix:** Include database-only layouts under customized (and keep outdated file-backed-only), e.g.: + +```go +case mailStatusCustomized: + return db.Where(table + ".is_custom") +case mailStatusNotCustomized: + return db.Where("NOT " + table + ".is_custom") +case mailStatusOutdated: + return db.Where(table + ".is_custom AND " + table + ".source IS NOT NULL AND " + table + ".base_hash IS DISTINCT FROM " + table + ".file_hash") +``` + +### WR-02: Unknown `filterStatus` value leaves the query unfiltered + +**File:** `modules/cabana/mail_admin.go:677-689` +**Issue:** When `name == mailFilterStatus` but `value` is not one of the three known statuses, the function returns `db` unchanged (all rows). Wrong scope names correctly match nothing (`1 = 0`); wrong values do the opposite. +**Fix:** + +```go + switch value { + case mailStatusCustomized: + // ... + case mailStatusNotCustomized: + // ... + case mailStatusOutdated: + // ... + default: + return db.Where("1 = 0") + } +``` + +### WR-03: Mail image upload errors ignore field-level validation details + +**File:** `admin/src/components/mail/MailImagePicker.vue:180-182` +**Issue:** Upload failures from the API use `ValidationError` details shaped as `{ file: ["…"] }` (`mail_routes.go` via `writeCRUDError`). The picker reads `details.message`, which is absent, so operators usually see the generic top-level `"Validation failed"` instead of the attach limit/type message. +**Fix:** Prefer the first string under `details.file` (or any field array), then fall back: + +```ts +const err = (error as { error?: { message?: string; details?: Record } } | undefined)?.error +const fieldDetails = err?.details?.file +const fromFile = Array.isArray(fieldDetails) ? fieldDetails.find((v) => typeof v === 'string') : undefined +uploadError.value = + (typeof fromFile === 'string' && fromFile) || + (typeof err?.details?.message === 'string' && err.details.message) || + err?.message || + t('backend::lang.mail.picker.load_failed') +``` + +### WR-04: Partial preview/test-send gated only on `content_html` + +**File:** `admin/src/components/form/fields/MailPreviewField.vue:47-66` +**Issue:** For `mode === 'partial'` (and `layout`), `draftEmpty` only inspects `content_html`. A text-only partial draft (empty HTML, non-empty `content_text`) shows the empty state and disables test-send on the text tab, even though the server draft can render text. +**Fix:** Treat the draft as non-empty when any relevant content field is present: + +```ts +const draftEmpty = computed(() => { + if (mode.value === 'branding') return false + if (mode.value === 'template') { + const raw = formValues.value.body + return raw === null || raw === undefined || String(raw).trim() === '' + } + const html = String(formValues.value.content_html ?? '').trim() + const text = String(formValues.value.content_text ?? '').trim() + const css = mode.value === 'layout' ? String(formValues.value.content_css ?? '').trim() : '' + return html === '' && text === '' && css === '' +}) +``` + +## Info + +### IN-01: Stale preview HTML after clear-then-retype + +**File:** `admin/src/components/form/fields/MailPreviewField.vue:117-121` +**Issue:** When the draft becomes empty, `hasRender` / `html` / `text` / `subject` are left as-is. While empty the UI shows the empty state, but the first keystroke after that briefly shows the previous render until the debounced preview returns. +**Fix:** Clear `hasRender`, `html`, `text`, and `subject` in the `draftEmpty` early-return paths (watch + `renderPreview`). + +### IN-02: Color picker swatch shows last valid colour when text is empty + +**File:** `admin/src/components/form/fields/ColorPickerField.vue:14-22` +**Issue:** An empty model value still drives the native swatch from `lastValid` (default `#ffffff`), which can look like a chosen white while the field is "not set" and the server treats empty as the brand default. +**Fix:** When `text` is empty, disable the swatch or show a neutral placeholder instead of `lastValid`. + +### IN-03: ListExtendRecords mutates stored locale/source pointers for display + +**File:** `modules/cabana/mail_admin.go:459-471`, `modules/cabana/mail_admin.go:878-891` +**Issue:** List hooks rewrite `Locale` / `Source` in place with translated display labels. Safe for the list JSON path today, but fragile if those model instances are reused for writes or exports. +**Fix:** Prefer a DTO / computed column for display (as other list extend examples do with unstored badge fields) instead of mutating override/index columns. + +--- + +_Reviewed: 2026-11-13T13:39:18Z_ +_Reviewer: the agent (msd-code-reviewer, generic-agent workaround)_ +_Depth: standard_ diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md new file mode 100644 index 00000000..f2b53a9c --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md @@ -0,0 +1,40 @@ +--- +status: testing +phase: 35-mail-templates-and-layouts-editor +source: [35-VERIFICATION.md] +started: 2026-11-13T13:46:04.193Z +updated: 2026-11-13T13:46:04.193Z +--- + +## Current Test + +number: 1 +name: Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates (e.g. user plugin templates). +expected: | + All registered templates appear; customize subject/body/layout; save; Reset to file version restores file content; drift callout appears after file change. +awaiting: user response + +## Tests + +### 1. Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates (e.g. user plugin templates). +expected: All registered templates appear; customize subject/body/layout; save; Reset to file version restores file content; drift callout appears after file change. +result: [pending] + +### 2. Edit a layout in codeeditor (HTML/text/CSS tabs); insert an image from the library; save Branding colours and logo; preview HTML/plain text; Send test to me. +expected: CodeMirror highlighting/focus feels correct; inserted URL is absolute server URL; preview iframe is sandboxed server HTML; test mail arrives only at the signed-in admin address (Mailpit). +result: [pending] + +### 3. Confirm judgment-tier prohibition: postcard imports modules/lagoon/attach for AbsolutePublicURL. +expected: Accept as intentional (D-24 / 35-01 SUMMARY threat_flag dependency-surface) or request a follow-up to move AbsolutePublicURL out of lagoon. +result: [pending] + +## Summary + +total: 3 +passed: 0 +issues: 0 +pending: 3 +skipped: 0 +blocked: 0 + +## Gaps diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-VERIFICATION.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-VERIFICATION.md new file mode 100644 index 00000000..ebada98e --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-VERIFICATION.md @@ -0,0 +1,352 @@ +--- +phase: 35-mail-templates-and-layouts-editor +verified: 2026-11-13T13:43:11Z +status: human_needed +score: 12/12 must-haves verified +covered_files: + - .planning/phases/35-mail-templates-and-layouts-editor/35-01-PLAN.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-01-SUMMARY.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-02-PLAN.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-02-SUMMARY.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-03-PLAN.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-04-PLAN.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-04-SUMMARY.md + - admin/openapi/admin.json + - admin/package-lock.json + - admin/package.json + - admin/src/api/schema.d.ts + - admin/src/api/types.ts + - admin/src/components/form/codeeditor/editor.ts + - admin/src/components/form/fields/CodeEditorField.vue + - admin/src/components/form/fields/ColorPickerField.vue + - admin/src/components/form/fields/MailImageField.vue + - admin/src/components/form/fields/MailPreviewField.vue + - admin/src/components/form/fields/MarkdownField.vue + - admin/src/components/form/fields/PartialField.vue + - admin/src/components/form/registry.ts + - admin/src/components/list/DataTable.vue + - admin/src/components/list/RowStateBadges.vue + - admin/src/components/mail/MailImagePicker.vue + - admin/src/components/mail/insertImage.ts + - admin/src/styles/main.css + - admin/src/views/FormView.vue + - admin/src/views/ListView.vue + - admin/src/views/SettingsFormView.vue + - admin/tests/browser/codeeditor-smoke.test.ts + - admin/tests/browser/codeeditor.test.ts + - admin/tests/form/CodeEditorField.test.ts + - admin/tests/form/ColorPickerField.test.ts + - admin/tests/form/FormViewMail.test.ts + - admin/tests/form/MailImageField.test.ts + - admin/tests/form/MailImagePicker.test.ts + - admin/tests/form/MailPreviewField.test.ts + - admin/tests/form/insertImage.test.ts + - admin/tests/form/mail-smoke.test.ts + - admin/tests/list/RowStateBadges.test.ts + - admin/tests/views/SettingsFormView.test.ts + - docs/backend/admin-spa.md + - docs/backend/forms.md + - docs/backend/lists-and-filters.md + - docs/backend/settings.md + - docs/backend/users-and-permissions.md + - docs/database/migrations.md + - docs/plugins/registration.md + - docs/services/mail.md + - docs/services/rate-limiting.md + - docs/services/storage.md + - modules/boardwalk/dist/assets/dm-mono-latin-400-normal--0xN8mdc.woff + - modules/boardwalk/dist/assets/dm-mono-latin-400-normal-4GdczIuU.woff2 + - modules/boardwalk/dist/assets/dm-mono-latin-500-normal-CN8Miw6E.woff + - modules/boardwalk/dist/assets/dm-mono-latin-500-normal-DRMDZjhP.woff2 + - modules/boardwalk/dist/assets/dm-mono-latin-ext-400-normal-1aZr6b2b.woff + - modules/boardwalk/dist/assets/dm-mono-latin-ext-400-normal-C2zvOubV.woff2 + - modules/boardwalk/dist/assets/dm-mono-latin-ext-500-normal-BtRyHRi6.woff2 + - modules/boardwalk/dist/assets/dm-mono-latin-ext-500-normal-Dw3M13d8.woff + - modules/boardwalk/dist/assets/dm-sans-latin-400-normal-BwCSEQnW.woff + - modules/boardwalk/dist/assets/dm-sans-latin-400-normal-CW0RaeGs.woff2 + - modules/boardwalk/dist/assets/dm-sans-latin-500-normal-B9HHJjqV.woff2 + - modules/boardwalk/dist/assets/dm-sans-latin-500-normal-Dr3UlScf.woff + - modules/boardwalk/dist/assets/dm-sans-latin-600-normal-Aqo67rzb.woff2 + - modules/boardwalk/dist/assets/dm-sans-latin-600-normal-BmdmIIQ2.woff + - modules/boardwalk/dist/assets/dm-sans-latin-700-normal-CUSSCpQX.woff + - modules/boardwalk/dist/assets/dm-sans-latin-700-normal-DvUfVpUG.woff2 + - modules/boardwalk/dist/assets/dm-sans-latin-ext-400-normal-BjWJ59Pq.woff + - modules/boardwalk/dist/assets/dm-sans-latin-ext-400-normal-BtiwyxMk.woff2 + - modules/boardwalk/dist/assets/dm-sans-latin-ext-500-normal-BJfUCQsA.woff2 + - modules/boardwalk/dist/assets/dm-sans-latin-ext-500-normal-DR84L5F-.woff + - modules/boardwalk/dist/assets/dm-sans-latin-ext-600-normal-4vooXBpG.woff2 + - modules/boardwalk/dist/assets/dm-sans-latin-ext-600-normal-DRtaDpgU.woff + - modules/boardwalk/dist/assets/dm-sans-latin-ext-700-normal-BLI3TTWz.woff + - modules/boardwalk/dist/assets/dm-sans-latin-ext-700-normal-CJIcxD6K.woff2 + - modules/boardwalk/dist/assets/editor-Bd7FUlHB.js + - modules/boardwalk/dist/assets/editor-uDgt9VKj.js + - modules/boardwalk/dist/assets/index-Bvfii4cZ.css + - modules/boardwalk/dist/assets/index-C4FC7bPJ.js + - modules/boardwalk/dist/assets/index-Vcq4gwWv.js + - modules/boardwalk/dist/assets/load-BWLbnrie.js + - modules/boardwalk/dist/favicon.ico + - modules/boardwalk/dist/index.html + - modules/cabana/README.md + - modules/cabana/admin_openapi.go + - modules/cabana/backend_screens.go + - modules/cabana/backendscreens/controllers/mailimages/config_form.yaml + - modules/cabana/backendscreens/controllers/maillayouts/_file_version.htm + - modules/cabana/backendscreens/controllers/maillayouts/_info.htm + - modules/cabana/backendscreens/controllers/maillayouts/config_filter.yaml + - modules/cabana/backendscreens/controllers/maillayouts/config_form.yaml + - modules/cabana/backendscreens/controllers/maillayouts/config_list.yaml + - modules/cabana/backendscreens/controllers/mailpartials/_file_version.htm + - modules/cabana/backendscreens/controllers/mailpartials/_info.htm + - modules/cabana/backendscreens/controllers/mailpartials/config_filter.yaml + - modules/cabana/backendscreens/controllers/mailpartials/config_form.yaml + - modules/cabana/backendscreens/controllers/mailpartials/config_list.yaml + - modules/cabana/backendscreens/controllers/mailtemplates/_file_version.htm + - modules/cabana/backendscreens/controllers/mailtemplates/_info.htm + - modules/cabana/backendscreens/controllers/mailtemplates/config_filter.yaml + - modules/cabana/backendscreens/controllers/mailtemplates/config_form.yaml + - modules/cabana/backendscreens/controllers/mailtemplates/config_list.yaml + - modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml + - modules/cabana/backendscreens/models/mailimagelibrary/fields.yaml + - modules/cabana/backendscreens/models/maillayout/columns.yaml + - modules/cabana/backendscreens/models/maillayout/fields.yaml + - modules/cabana/backendscreens/models/mailpartial/columns.yaml + - modules/cabana/backendscreens/models/mailpartial/fields.yaml + - modules/cabana/backendscreens/models/mailtemplate/columns.yaml + - modules/cabana/backendscreens/models/mailtemplate/fields.yaml + - modules/cabana/crud.go + - modules/cabana/field_mail.go + - modules/cabana/field_mail_test.go + - modules/cabana/form_schema.go + - modules/cabana/http.go + - modules/cabana/mail_admin.go + - modules/cabana/mail_diff.go + - modules/cabana/mail_lifecycle_postgres_test.go + - modules/cabana/mail_permissions_postgres_test.go + - modules/cabana/mail_routes.go + - modules/cabana/mail_screens_smoke_test.go + - modules/cabana/mail_test_send_postgres_test.go + - modules/cabana/mail_unit_test.go + - modules/cabana/messages.go + - modules/cabana/openapi_conformance_test.go + - modules/cabana/phase10_coverage_test.go + - modules/cabana/query.go + - modules/cabana/relation_field.go + - modules/cabana/security_coverage_test.go + - modules/cabana/settings.go + - modules/cabana/token_routes_test.go + - modules/lagoon/README.md + - modules/lagoon/attach/absolute.go + - modules/lagoon/attach/absolute_test.go + - modules/lagoon/migrations.go + - modules/lagoon/pending_test.go + - modules/pact/README.md + - modules/pact/capabilities.go + - modules/pact/capabilities_test.go + - modules/phrasebook/backend/lang/en/lang.yaml + - modules/phrasebook/backend/lang/pl/lang.yaml + - modules/postcard/README.md + - modules/postcard/assets/brand.css.tmpl + - modules/postcard/assets/minimal.htm + - modules/postcard/assets/partials/button.htm + - modules/postcard/assets/partials/panel.htm + - modules/postcard/assets/partials/subcopy.htm + - modules/postcard/assets/partials/table.htm + - modules/postcard/assets/sample.htm + - modules/postcard/assets/system.htm + - modules/postcard/brand.go + - modules/postcard/brand_smoke_test.go + - modules/postcard/brand_test.go + - modules/postcard/editor.go + - modules/postcard/editor_smoke_test.go + - modules/postcard/editor_test.go + - modules/postcard/mailer.go + - modules/postcard/override_smoke_test.go + - modules/postcard/override_test.go + - modules/postcard/partials.go + - modules/postcard/partials_smoke_test.go + - modules/postcard/partials_test.go + - modules/postcard/samples.go + - modules/postcard/samples_test.go + - modules/postcard/store.go + - modules/postcard/store_postgres_test.go + - modules/postcard/templates.go + - modules/surf/README.md + - modules/surf/serve.go + - modules/surf/store_lookup_test.go + - scripts/check-phase35.sh +covered_digest: "v2:sha256:402ba8f1c62f397e73e8ea69cc9299bbf5c8aa2dc727d51a0fe6484b18b419ba" +behavior_unverified: 0 +overrides_applied: 0 +advisory: + - finding: "Layout status filter hides database-only layouts (WR-01)" + category: other + reason: "35-REVIEW.md WR-01 — filter customized/outdated require source IS NOT NULL; custom layouts vanish under any status value. Does not break default unfiltered list or editability must-haves." + evidence_status: "code present; advisory from code review" + - finding: "Unknown filterStatus value leaves query unfiltered (WR-02)" + category: other + reason: "35-REVIEW.md WR-02 — soft filter hygiene; wrong values should match nothing." + evidence_status: "code present; advisory from code review" + - finding: "Mail image upload errors ignore field-level ValidationError details (WR-03)" + category: other + reason: "35-REVIEW.md WR-03 — UX; operators often see generic Validation failed." + evidence_status: "code present; advisory from code review" + - finding: "Partial/layout draftEmpty only checks content_html (WR-04)" + category: other + reason: "35-REVIEW.md WR-04 — text-only drafts show empty preview state; server can still render text." + evidence_status: "code present; advisory from code review" +human_verification: + - test: "Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates (e.g. user plugin templates)." + expected: "All registered templates appear; customize subject/body/layout; save; Reset to file version restores file content; drift callout appears after file change." + why_human: "List/form UX, Winter-shaped flow and empty-state copy need visual confirmation beyond unit/API tests." + - test: "Edit a layout in codeeditor (HTML/text/CSS tabs); insert an image from the library; save Branding colours and logo; preview HTML/plain text; Send test to me." + expected: "CodeMirror highlighting/focus feels correct; inserted URL is absolute server URL; preview iframe is sandboxed server HTML; test mail arrives only at the signed-in admin address (Mailpit)." + why_human: "35-VALIDATION.md manual-only rows (D-09 feel, D-17 inbox rendering); visual appearance and real mail-client rendering cannot be proven by grep." + - test: "Confirm judgment-tier prohibition: postcard imports modules/lagoon/attach for AbsolutePublicURL." + expected: "Accept as intentional (D-24 / 35-01 SUMMARY threat_flag dependency-surface) or request a follow-up to move AbsolutePublicURL out of lagoon." + why_human: "PLAN prohibition said postcard must not import lagoon; implementation imports attach by design. Judgment-tier — needs explicit human resolution." +--- + +# Phase 35: Mail templates and layouts editor Verification Report + +**Phase Goal:** Administrators edit every mail the application sends from the admin panel, as in WinterCMS's Mail templates screen. System mail and the templates plugins register through `pact.HasMailTemplates` appear in a list. Each template can get a database override of its subject and body, and the override can be reset to the file version. Layouts become admin-editable records assigned to templates, with a few predefined layouts seeded. Images can be uploaded and placed in layouts and templates. postcard renders the override when one exists, otherwise the plugin's file, so mail that already works keeps working. + +**Verified:** 2026-11-13T13:43:11Z +**Status:** human_needed +**Re-verification:** No — initial verification + +## Goal Achievement + +Roadmap lists **Requirements: TBD** and no Success Criteria block for Phase 35. Must-haves are derived from the ROADMAP goal (Option C) and merged with PLAN frontmatter truths (D-01..D-25). `check.decision-coverage-verify`: **25/25** CONTEXT decisions honored. + +### Observable Truths + +| # | Truth | Status | Evidence | +| --- | --- | --- | --- | +| 1 | Administrators edit mail from Settings → Mail screens (templates, layouts, partials, branding, images) with no top-level nav | ✓ VERIFIED | `modules/cabana/mail_admin.go` + `backend_screens.go` register five Settings entries and controllers; smoke `TestMailScreensSmoke`; SPA generic FormView/ListView/SettingsFormView | +| 2 | Templates from `pact.HasMailTemplates` (and file catalog) appear as list rows after SyncIndex | ✓ VERIFIED | `postcard.SyncIndex` in `store.go`; cabana `http.go` → `mail.syncOnDatabase` → `postcard.SyncIndex`; list YAML under `backendscreens/controllers/mailtemplates/` | +| 3 | Template DB override of subject, Markdown body and layout; Reset clears override and re-mirrors file | ✓ VERIFIED | `mailer.go` per-send `NewDBSource`; `ResetOverride` in `store.go`; `go test -short ./modules/postcard -run 'TestOverride'` PASS; cabana `TestMailReset` exists | +| 4 | Layouts are admin-editable (file override + custom create/delete); predefined `default`, `system`, `minimal` seeded as files | ✓ VERIFIED | assets `default.htm`/`system.htm`/`minimal.htm`; layout form + `TestMailLayoutDelete`; template `fields.yaml` layout dropdown | +| 5 | Images uploadable via mail library and insertable into templates/layouts/partials | ✓ VERIFIED | `GET/POST /mail/images` in `mail_routes.go`; `MailImagePicker.vue` + `insertImage.ts`; SPA tests `insertImage`/`MailImagePicker` PASS | +| 6 | postcard renders override when present, else file; fallback on failure; no boot-time snapshot | ✓ VERIFIED | `mailer.render` / `overrides()` once per send; `TestOverride`+`TestFallback` PASS; Activate installs `NewDBSource(app)` | +| 7 | Partials via additive `pact.HasMailPartials`; built-ins button/panel/table/subcopy; Markdown-safe `partial` | ✓ VERIFIED | `capabilities.go` HasMailPartials; `partials.go`; `TestPartial` PASS | +| 8 | Branding colours + logo replace `mail.brandCss` once row exists; logoUrl absolute at send time | ✓ VERIFIED | `brand.go` CompileBrandCSS; `store.go` calls `attach.AbsolutePublicURL`; `TestBrand` PASS | +| 9 | Live draft preview (sandboxed iframe) and test-send to signed-in admin only, rate-limited | ✓ VERIFIED | `MailPreviewField.vue` `sandbox=""`; `mailTestSend` refuses recipient; SPA MailPreviewField tests PASS (sequence guard); `TestMailTestSend` exists | +| 10 | Permission split `system.manage_mail_templates` / `system.manage_mail_layouts`; no default role grants | ✓ VERIFIED | `backend_screens.go` constants; `TestMailPermissions` listed; smoke asserts zero default grants | +| 11 | Drift: customized + outdated when `base_hash` ≠ `file_hash`; File version diff; re-save clears | ✓ VERIFIED | SyncIndex hash columns; cabana row states; `TestMailDrift` exists; `mail_diff.go` | +| 12 | D-21 gate: `scripts/check-phase35.sh` + unit/SPA coverage map filled | ✓ VERIFIED | `--self-test` PASS; `35-VALIDATION.md` nyquist_compliant + Wave 0 checked; artifact tests present | + +**Score:** 12/12 truths verified (0 present, behavior-unverified) + +Granular PLAN truths (35-01..04) map onto the rows above; spot-checks did not find a PLAN truth that fails while the parent row holds. Advisory WR-01..04 do not falsify these truths. + +### Required Artifacts + +All PLAN `must_haves.artifacts` passed `verify.artifacts` (01: 8/8, 02: 6/6, 03: 6/6, 04: 5/5). + +| Artifact | Expected | Status | Details | +| -------- | -------- | ------ | ------- | +| `modules/postcard/store.go` | NewDBSource, SyncIndex, ResetOverride | ✓ VERIFIED | exists, substantive, wired from Activate/mailer | +| `modules/postcard/editor.go` | Editor Validate/Preview/SendDraft | ✓ VERIFIED | used by cabana FormAfterUpdate + mail routes | +| `modules/cabana/mail_admin.go` | screens, permissions, reset | ✓ VERIFIED | wired via backend_screens EditorFrom | +| `modules/cabana/mail_routes.go` | preview, test-send, images | ✓ VERIFIED | OpenAPI + SPA calls | +| `admin/.../MailPreviewField.vue` | sandboxed preview | ✓ VERIFIED | `sandbox=""`, POST /mail/preview | +| `admin/.../CodeEditorField.vue` | lazy CodeMirror | ✓ VERIFIED | dynamic import of editor.ts | +| `scripts/check-phase35.sh` | phase gate | ✓ VERIFIED | self-test PASS | + +### Key Link Verification + +| From | To | Via | Status | Details | +| ---- | --- | --- | ------ | ------- | +| `mailer.go` | `store.go` | `NewDBSource(app)` | ✓ WIRED | pattern found | +| `lagoon/migrations.go` | `store.go` | `postcard.Migrations` | ✓ WIRED | pattern found | +| `brand.go` → AbsolutePublicURL | `attach/absolute.go` | logo at send | ✓ WIRED (alt path) | mechanical pattern in brand.go MISSING; call is in `store.go:330` (`attach.AbsolutePublicURL`) per 35-01 SUMMARY plan inconsistency note — same intent | +| `mailer.go` | `pact` | `HasMailPartials` | ✓ WIRED | pattern found | +| `mail_admin.go` | `editor.go` | `.Validate(ctx` | ✓ WIRED | pattern found | +| `http.go` → SyncIndex | `store.go` | serve-start sync | ✓ WIRED (alt path) | mechanical `postcard.SyncIndex` not in http.go; `http.go` → `mail.syncOnDatabase` → `mail_admin.sync` → `postcard.SyncIndex` | +| `mail_routes.go` | cooler | Attempter | ✓ WIRED | pattern found | +| `backend_screens.go` | mail_admin | EditorFrom | ✓ WIRED | pattern found | +| SPA preview/picker/registry | cabana routes | api.POST | ✓ WIRED | plan 03 4/4 | +| check-phase35 consumers/additive | plugins / apisurface | stages | ✓ WIRED | plan 04 2/2 | + +### Data-Flow Trace (Level 4) + +| Artifact | Data Variable | Source | Produces Real Data | Status | +| -------- | ------------- | ------ | ------------------ | ------ | +| Template list | rows | `system_mail_templates` via SyncIndex + GORM list | Yes | ✓ FLOWING | +| Override at send | Overrides | `NewDBSource` SQL per send | Yes | ✓ FLOWING | +| Preview iframe srcdoc | html | POST /mail/preview → postcard.Editor | Yes (server HTML only) | ✓ FLOWING | +| Image insert URL | absolute URL | GET/POST /mail/images meta | Yes | ✓ FLOWING | +| Brand logoUrl | LogoURL | system_files + AbsolutePublicURL | Yes | ✓ FLOWING | + +### Behavioral Spot-Checks + +| Behavior | Command | Result | Status | +| -------- | ------- | ------ | ------ | +| Override/fallback/partial/brand/sample/validate | `go test -short ./modules/postcard -run 'TestOverride\|TestFallback\|TestPartial\|TestBrand\|TestSample\|TestValidateDraft'` | ok | ✓ PASS | +| HasMailTemplates / row states pin | `go test -short ./modules/pact -run 'TestHasMailTemplates\|TestRowState'` | ok | ✓ PASS | +| SPA preview/codeeditor/insertImage | `npm --prefix admin run test -- --run MailPreviewField insertImage CodeEditorField` | 16 passed | ✓ PASS | +| Phase gate self-test | `bash scripts/check-phase35.sh --self-test` | phase35 self-test passed | ✓ PASS | +| Cabana mail locale/unit (short) | `go test -short ./modules/cabana -run 'TestMailLocale\|TestMailUnit\|TestFieldMail'` | ok | ✓ PASS | +| Full docker mail postgres suite | (not run — Docker/stateful) | — | ? SKIP (tests exist: TestMailPermissions, TestMailTestSend, TestMailDrift, …) | + +### Probe Execution + +No phase-declared `scripts/*/tests/probe-*.sh`. N/A. + +### Requirements Coverage + +REQUIREMENTS.md has **no Phase 35 IDs** (ROADMAP `Requirements: TBD`). Plans declare CONTEXT **D-*** IDs. + +| Requirement | Source Plan | Description | Status | Evidence | +| ----------- | ---------- | ----------- | ------ | -------- | +| D-01..D-25 | 35-01..04 + CONTEXT | Full decision set | ✓ SATISFIED | `check.decision-coverage-verify` 25/25 honored | +| (v1 REQ IDs) | — | none mapped to phase 35 | N/A | no orphaned Phase 35 rows in REQUIREMENTS.md | + +### Anti-Patterns Found + +| File | Line | Pattern | Severity | Impact | +| ---- | ---- | ------- | -------- | ------ | +| — | — | TBD/FIXME/XXX in key phase files | none found | — | +| `modules/postcard/store.go` | import | imports `lagoon/attach` | ℹ️ Info / judgment prohibition | Intentional for AbsolutePublicURL (D-24); conflicts with written prohibition text | +| 35-REVIEW WR-01..04 | — | filter/UX gaps | 📋 Advisory | Do not fail must-haves; recorded in advisory frontmatter | + +### Prohibitions (judgment-tier) + +| Statement | LLM judgment | Flag | +| --------- | ------------- | ---- | +| HasMailTemplates / Mailer signatures additive only | Holds — HasMailPartials additive; interface methods unchanged | unverified-prohibition — human review recommended | +| Byte-identical file mail without override | Holds — TestOverride/file path + consumer stage in gate | unverified-prohibition — human review recommended | +| goldmark not unsafe | Holds — `goldmark.New()` / Table only; no WithUnsafe | unverified-prohibition — human review recommended | +| postcard does not import cabana or lagoon | **Partial:** no cabana; **does** import `lagoon/attach` | unverified-prohibition — human resolution required (see Human Verification #3) | +| No free-text recipient on mail screens | Holds — test-send posts no recipient; server refuses recipient key | unverified-prohibition — human review recommended | +| No default role grants for mail permissions | Holds — smoke/permission tests assert zero grants | unverified-prohibition — human review recommended | + +### Human Verification Required + +### 1. Winter-shaped Settings → Mail flow + +**Test:** Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates. +**Expected:** Templates listed; override save/reset/drift behave as Winter-like; empty-state copy correct. +**Why human:** Visual list/form UX beyond API tests. + +### 2. Codeeditor, branding, preview, real test-send + +**Test:** Edit layout in codeeditor; insert image; save Branding; preview; Send test to me; check Mailpit. +**Expected:** Editor feel OK; absolute URLs; sandboxed preview; mail only to admin. +**Why human:** 35-VALIDATION.md manual-only (D-09, D-17). + +### 3. Accept postcard → lagoon/attach import + +**Test:** Review prohibition vs D-24 AbsolutePublicURL placement. +**Expected:** Accept deviation or schedule follow-up extraction. +**Why human:** Judgment-tier prohibition conflict with intentional implementation. + +### Gaps Summary + +No must-have truths FAILED. Automated goal-backward evidence is green (12/12). Status is `human_needed` because Step 8 human items (visual UAT + judgment prohibition resolution) are non-empty — not because of implementation gaps. Advisory code-review warnings (WR-01..04) noted; they do not alone fail verification. + +--- + +_Verified: 2026-11-13T13:43:11Z_ +_Verifier: the agent (msd-verifier)_