diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-05-PLAN.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-05-PLAN.md index 6f404591..07e5aabf 100644 --- a/.planning/phases/35-mail-templates-and-layouts-editor/35-05-PLAN.md +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-05-PLAN.md @@ -163,6 +163,7 @@ admin (35-03): - Stage files by explicit path; never `git add -A`. Code and planning docs go in separate commits. Each commit keeps `go vet ./...` and `go test ./...` green. - Docker-backed tests run without `-short` (through `sudo -u golem` if the Docker socket is denied although the user is in the docker group). - Resume check: `git log --format=%s -F --grep=''`. +- The tracer task (Task 1) is large under the lean-planning rule. It may land as several sub-commits (for example postcard, then cabana, then admin) as long as each one keeps `go vet ./...` and `go test ./...` green and carries its own README/docs changes. The last sub-commit uses the subject listed below, so the resume check still works. | Task | Commit subject | Resume point | |------|----------------|--------------| @@ -318,7 +319,7 @@ admin (35-03): |-----------|----------|-----------|----------|-------------|-----------------| | T-35-29 | Elevation of privilege | locale variant ids in meta.localeVariants | medium | mitigate | the switcher only lists rows of the same group; every id is still loaded through the controller's RequiredPermissions and FormExtendQuery scope (catalog templates and their fallback rows), so an id outside the catalog is a 404 (TestMailScreensSmoke/locales) | | T-35-30 | Tampering | fallback-locale saves | high | mitigate | FormAfterUpdate validates through postcard Editor.Validate exactly as file rows (D-13); a refused draft rolls the save back | -| T-35-31 | Spoofing | send-time name resolution | low | mitigate | only a two-letter language tag after a dash, on a registered base of the same name, resolves; the base is in the same plugin namespace, so no plugin can reach another plugin's template through a suffix; other unknown names keep the unknown-template error | +| T-35-31 | Spoofing | send-time name resolution | low | mitigate | only a locale tag after a dash (a two-letter language, optionally followed by `-` or `_` and a 2–8 character alphanumeric subtag, such as de or pt-BR), on a registered base of the same name, resolves; the base is in the same plugin namespace, so no plugin can reach another plugin's template through a suffix; other unknown names keep the unknown-template error | | T-35-32 | Denial of service | EnsureLocaleRows on show and sync | low | mitigate | the show hook ensures only its own group; the full ensure runs at sync under the shared advisory lock; inserts are idempotent and bounded by templates × locales | | T-35-33 | Information disclosure | localeVariants labels | low | accept | labels are locale codes and state words the administrator already sees in the list | | T-35-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package (npm ci only restores the committed lockfile) | diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-06-PLAN.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-06-PLAN.md index cae0a2bd..e9ba5f05 100644 --- a/.planning/phases/35-mail-templates-and-layouts-editor/35-06-PLAN.md +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-06-PLAN.md @@ -28,6 +28,8 @@ files_modified: - modules/postcard/README.md - go.mod - go.sum + - examples/hello/go.mod + - examples/hello/go.sum - modules/cabana/mail_admin.go - modules/cabana/mail_routes.go - modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml @@ -160,6 +162,7 @@ Output: commits in this repository only (code, planning docs separately). Nothin - Other sessions edit postcard, cabana and docs concurrently. Before each task run `git status --short modules/postcard modules/cabana modules/phrasebook docs go.mod go.sum .planning/research` and stop if another session holds uncommitted edits in files this task touches. `examples/hello/plugins.gen.go` carries another session's edit: never stage it. - Stage by explicit path; code and planning docs in separate commits; `go vet ./...` and `go test ./...` green at every code commit. Docker-backed tests without `-short` (through `sudo -u golem` if the socket is denied). - Resume check: `git log --format=%s -F --grep=''`. +- The tracer task (Task 1) is large under the lean-planning rule. It may land as several sub-commits (for example postcard, then cabana) as long as each one keeps `go vet ./...` and `go test ./...` green and carries its own README/docs changes. The last sub-commit uses the subject listed below. | Task | Commit subject | Resume point | |------|----------------|--------------| @@ -219,7 +222,7 @@ Output: commits in this repository only (code, planning docs separately). Nothin Task 2: Decision note and STACK row for go-premailer, then CSS inlining at render with the per-layout opt-out A new Go module in the framework's go.mod that every application and plugin building against postcard must carry in go.sum; the disable_auto_inline_css column and header key are part of the layout format. - .planning/notes/2026-11-13-mail-layouts-css-inlining.md, .planning/research/STACK.md, go.mod, go.sum, modules/postcard/inline.go, modules/postcard/templates.go, modules/postcard/store.go, modules/postcard/editor.go, modules/postcard/partials_smoke_test.go, modules/postcard/brand_smoke_test.go, modules/postcard/override_smoke_test.go, modules/postcard/override_test.go, modules/postcard/mailer_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/backendscreens/models/maillayout/fields.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md + .planning/notes/2026-11-13-mail-layouts-css-inlining.md, .planning/research/STACK.md, go.mod, go.sum, examples/hello/go.mod, examples/hello/go.sum, modules/postcard/inline.go, modules/postcard/templates.go, modules/postcard/store.go, modules/postcard/editor.go, modules/postcard/partials_smoke_test.go, modules/postcard/brand_smoke_test.go, modules/postcard/override_smoke_test.go, modules/postcard/override_test.go, modules/postcard/mailer_test.go, modules/postcard/README.md, modules/cabana/mail_admin.go, modules/cabana/mail_routes.go, modules/cabana/backendscreens/models/maillayout/fields.yaml, modules/cabana/mail_screens_smoke_test.go, modules/cabana/README.md, modules/phrasebook/backend/lang/en/lang.yaml, modules/phrasebook/backend/lang/pl/lang.yaml, docs/services/mail.md - The default layout's HTML after render has a style attribute on the button partial's link containing the brand primary colour, keeps the DOCTYPE line, keeps class attributes, and still passes postcard's safety checks - A media-query rule in a layout's CSS ends up in a style element of the output, not on elements @@ -237,7 +240,7 @@ Output: commits in this repository only (code, planning docs separately). Nothin Supersedes D-10's claim that postcard already inlines the brand CSS (it only placed it in a style block); WinterCMS parity with MailManager::renderTemplate. - First, planning docs commit: verify the module before writing (`go list -m -versions github.com/vanng822/go-premailer`; `go mod download -json github.com/vanng822/go-premailer@v1.38.0` for Time and Origin; the LICENSE is MIT; v1.38.0 was published at least 7 days ago). Write `.planning/notes/2026-11-13-mail-layouts-css-inlining.md` (Status: Accepted; Context: 35-UAT G-35-8, debug session mail-layouts-unstyled, user decision 2026-11-13) recording: D-10's inlining sentence superseded; 35-01's "default.htm unchanged" gate lifted (default layout is now Winter's default layout with header and footer partials); Branding gains Site name with the mail.from fallback; the inlining decision (go-premailer exactly v1.38.0, default options, where it runs, error fallback, opt-out name and places); facts checked (publish dates, licence, maintainer, importers, its requirements, the x/net raise from v0.58.0 to what MVS selects, the transitive modules `go mod tidy` adds); the consequence that applications and plugins building with a `replace` to this checkout need `go mod tidy` (follow-up); rejected alternatives: an in-house inliner on x/net/html with douceur and cascadia (selector specificity and edge cases to own), github.com/aymerick/douceur/inliner (unmaintained since 2016), no inlining (UAT gap stays for clients that drop style blocks). Add a "Supporting Libraries" row to .planning/research/STACK.md naming the note. Commit these two files alone with the first subject. - - Then code: `go get github.com/vanng822/go-premailer@v1.38.0` and `go mod tidy` (commit go.mod and go.sum; if examples/hello needs go.sum lines, tidy its go.mod/go.sum only). If the module fails a fit check that its options cannot fix (lost DOCTYPE, output failing validateHTML, an error on the brand CSS selectors), stop and report instead of swapping libraries or hand-rolling. + - Then code: `go get github.com/vanng822/go-premailer@v1.38.0` and `go mod tidy` (commit go.mod and go.sum; if examples/hello needs go.sum lines, tidy and stage examples/hello/go.mod and examples/hello/go.sum by path, never examples/hello/plugins.gen.go, which holds another session's edit). If the module fails a fit check that its options cannot fix (lost DOCTYPE, output failing validateHTML, an error on the brand CSS selectors), stop and report instead of swapping libraries or hand-rolling. - `modules/postcard/inline.go`: unexported `inlineCSS(html string) (string, error)` wrapping NewPremailerFromString + Transform with default options. - templates.go: parseLayout reads `disable_auto_inline_css`; `LayoutFile.DisableAutoInlineCSS bool`; renderLayout carries the flag from the file or the override; renderParts, after the HTML wrapper passed validateHTML, inlines unless the flag is set, keeps the un-inlined HTML and calls opts.warn (key `inline:`) on an inliner error, and runs validateHTML on the final HTML. - store.go: append migration `202611130003_mail_layout_disable_auto_inline_css` (boolean NOT NULL DEFAULT FALSE on the layouts table); `LayoutOverride.DisableAutoInlineCSS bool` read by MailOverrides; SyncIndex mirrors the file header value for rows that are not customized; ResetOverride writes the file's value back. @@ -357,6 +360,6 @@ After the framework release tag that contains 35-05 and 35-06 (tag only at phase - sm-user-plugin: bump the framework requirement (and `go mod tidy` for go-premailer); activate/restore/invite (+ -en) use `{{ partial "button" ... }}` instead of Markdown links; replace `layouts/user.htm` with a full layout built on the framework's structure and partials, keeping the name; fix its text wrapper. - sm-paymentgateway-plugin: bump the framework requirement; order templates use the button partial and drop the duplicated URL; replace `layouts/paymentgateway.htm` keeping the name. - Applications building with a `replace` to this checkout (sm-demo-app and others) run `go mod tidy` to pick up go-premailer's go.sum lines. -- sm-demo-app: reset the UAT overrides of `golem15.user::mail.layouts.user` and `golem15.user::mail.activate` before re-running UAT test 8. +- sm-demo-app: reset the UAT overrides of `golem15.user::mail.layouts.user` and `golem15.user::mail.activate` before re-running UAT test 8. After this phase that re-run covers the built-in layouts only (35-07 records G-35-8 as framework-closed). The activate CTA rendering as a button and the finished user/paymentgateway layouts are checked after the plugin follow-up. diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-07-PLAN.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-07-PLAN.md index 9d46da07..8f79718f 100644 --- a/.planning/phases/35-mail-templates-and-layouts-editor/35-07-PLAN.md +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-07-PLAN.md @@ -17,6 +17,7 @@ files_modified: - admin/tests/form/LocaleVariantSwitcher.test.ts - admin/tests/form/FormViewMail.test.ts - .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md + - .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md autonomous: true requirements: [G-35-1, G-35-8, D-21] @@ -35,6 +36,7 @@ must_haves: - "Unit tests show the button partial's output (class, href, type variants) in every built-in layout, CSS inlined onto elements with the DOCTYPE kept and media queries left in a style block, the plain-text part unchanged, the safety check on the inlined output, the per-layout opt-out (file header key, override column, layout draft, layout form switch) and the fallback when the inliner fails (G-35-8)" - "SPA tests cover the locale switcher (options, current, navigation, restored selection when the unsaved-changes confirm is cancelled) and FormView showing it only with two or more variants (G-35-1)" - "go vet ./... and go test ./... stay green; 35-VALIDATION.md maps G-35-1 and G-35-8" + - "G-35-8 is recorded as framework-closed with its plugin part deferred, in 35-VALIDATION.md and in a closure note on the G-35-8 entry of 35-UAT.md. The re-run of UAT test 8 is scoped to what this phase ships: preview a template in the default and system layouts with a Branding logo and Site name and a body override that calls the button partial. The activate CTA as a button and the finished user/paymentgateway layouts are listed as a deferred follow-up check for the plugin follow-up after the framework tag." prohibitions: - statement: "No production code changes except fixes for defects the new tests expose, each in its own fix commit and recorded as a deviation in the SUMMARY." status: unresolved @@ -81,7 +83,7 @@ ROADMAP Goal (not in user-story format; no story is invented): administrators ed - `scripts/check-phase35.sh`: a read-only scratch-modfile consumers stage (the core plugins' go.sum does not carry go-premailer yet), a dirty-tree refusal, and every new test required by name. - postcard unit tests for locale resolution and fallback rows, built-in layouts (logo, header, footer, site name), the button partial and CSS inlining with its opt-out and failure fallback. - cabana Postgres tests for the grouped templates screen, the Branding site name and the layout inlining switch; SPA tests for the locale switcher. -- `--all` green; 35-VALIDATION.md updated. +- `--all` green; 35-VALIDATION.md updated; G-35-8 recorded as framework-closed with the plugin part deferred (35-VALIDATION.md and a closure note in 35-UAT.md), with a UAT test 8 re-run scoped to the built-in layouts. Purpose: D-21's "unit tests last" rule for the gap closure; the gate is what `/msd-verify-work` runs before UAT tests 1 and 8 are re-checked. @@ -163,7 +165,7 @@ Output: test and gate-script commits in this repository; one planning-docs commi - TestHeaderFooterPartials: header with logo, with name only, with url (link wraps the content); footer holds © plus the current year and the name, or only the year; their text forms - TestButtonPartial: class button button-primary by default, button-positive and button-negative with type, href is the url, the text form is "body ", in the default, system and minimal layouts - TestSiteName: Brand.SiteName wins; empty uses the display name of mail.from; From without a display name or unparsable gives an empty name - - TestInlineCSS: the button link carries the brand primary colour in its style attribute; the DOCTYPE line is kept; a media-query rule from layout CSS stays in a style element; the text part equals the text part of the same message with inlining off; a dangerous URL that inlining moves into a style attribute fails the safety check and the file version is sent + - TestInlineCSS: the button link carries the brand primary colour in its style attribute; the DOCTYPE line is kept; a media-query rule from layout CSS stays in a style element; the text part equals the text part of the same message with inlining off; a layout override whose CSS holds a javascript: URL fails the safety check (before or after inlining) and the file version is sent. That override is a raw fixture that never passed save validation: it is injected through the `fakeOverrides` OverrideSource and checked with `assertFileFallback`, as TestFallback's unsafe_override case does, because Editor.Validate would refuse it at save - TestInlineCSSOptOut: file layout header key, LayoutOverride column and layout draft each leave the button without an inlined style while the style block remains - TestInlineFailure: an inliner error (through the seam 35-06 shipped, or a package-level variable swapped in the test) sends the un-inlined HTML and logs one warning per key per minute @@ -192,7 +194,7 @@ Output: test and gate-script commits in this repository; one planning-docs commi Task 3: cabana Postgres tests and SPA tests for grouped templates, the site name and the inlining switch; gate --all; validation map - modules/cabana/mail_locale_postgres_test.go, modules/cabana/mail_brand_layout_postgres_test.go, admin/tests/form/LocaleVariantSwitcher.test.ts, admin/tests/form/FormViewMail.test.ts, scripts/check-phase35.sh, .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md + modules/cabana/mail_locale_postgres_test.go, modules/cabana/mail_brand_layout_postgres_test.go, admin/tests/form/LocaleVariantSwitcher.test.ts, admin/tests/form/FormViewMail.test.ts, scripts/check-phase35.sh, .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md, .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md - TestMailLocaleGroups: with a fake TranslationWriter (pl, en, de; default pl) the list has one welcome row; customized_locales is empty, then "de", then "Default, de"; badges and the status filter follow any customized / drifted row of the group; GET of the welcome record returns localeVariants Default (current), de, en in that order with translated labels and states; a not-customized de row shows the base row's current subject, body and layout (the base customization when present); PUT on de then Send of welcome-de uses it; the reset action on de returns the default version; a changed base file marks de outdated; the file version partial of de compares with the base file; the info partial of de holds the fallback line; an id outside the catalog is 404; a role with only system.manage_mail_layouts gets 403 on the de id; a newly enabled locale (writer answers fr too) appears in localeVariants on the next GET without a restart; the locale-set change re-syncs the list - TestMailBrandSiteName: saving site_name persists it trimmed; more than 255 characters is a 422 on site_name; preview mode branding shows the name in the header; with no logo and no name the preview has no header row @@ -211,7 +213,18 @@ Output: test and gate-script commits in this repository; one planning-docs commi - The two Go files are Postgres tests in package cabana_test that skip under -short like the existing mail Postgres tests and reuse newMailScreensEnvWith; build a second process over a changed MapFS with `keep: true` for the drift case, as the drift subtest does. Add ./modules/cabana:TestMailLocaleGroups, TestMailBrandSiteName and TestMailLayoutInlineOptOut to DOCKER_TESTS in the same commit. - Extend the 35-05 smoke vitest file rather than duplicating it; add tests/form/LocaleVariantSwitcher.test.ts to ADMIN_FILES in the admin test commit. Admin source is not changed by this task; a defect gets its own fix commit (and, if admin source changed, the dist rebuild commit and scripts/check-admin-dist.sh per CLAUDE.md). - Run `bash scripts/check-phase35.sh --all` (Docker host; PHASE35_ALLOW_NO_DOCKER only when no daemon answers, which must then be stated in the SUMMARY). - - Planning-docs commit: 35-VALIDATION.md rows for G-35-1 (locale grouping: postcard unit + Postgres, cabana Postgres, SPA) and G-35-8 (layouts, partials, inlining, site name, consumers with the scratch modfile), marking the D-05 row and the "default layout output unchanged" byte-identity row as superseded by the decision notes of 35-05 and 35-06; Manual-Only rows for re-running UAT tests 1 and 8 on sm-demo-app after resetting the UAT overrides of golem15.user::mail.activate and golem15.user::mail.layouts.user, and for a real-inbox check of inlined mail. + - Planning-docs commit: + - 35-VALIDATION.md rows for G-35-1 (locale grouping: postcard unit + Postgres, cabana Postgres, SPA) and G-35-8 (layouts, partials, inlining, site name, consumers with the scratch modfile). + - In 35-VALIDATION.md, mark the D-05 row and the "default layout output unchanged" byte-identity row as superseded by the decision notes of 35-05 and 35-06. + - Record G-35-8 as framework-closed with its plugin part deferred: the plugin templates' CTA through the button partial, the replaced user/paymentgateway layouts and the plugins' framework bump. + - Manual-Only rows: + - Re-run UAT test 1 on sm-demo-app. + - Re-run UAT test 8 on sm-demo-app, scoped to the built-in layouts. First reset the UAT overrides of golem15.user::mail.activate and golem15.user::mail.layouts.user. Save Branding with a logo and a Site name. Then preview a template switched to the default layout, and to the system layout, with a body override that calls the button partial. Expect the logo header (or the name), the white card, the styled button and the footer. + - A real-inbox check of inlined mail. + - A "deferred follow-up check" row: the activate CTA renders as a button and the user/paymentgateway layouts look finished, checked after the plugin follow-up ships. + - 35-UAT.md: append to the G-35-8 entry under Gaps, without changing `status`, the test results or the Summary counts (those belong to /msd-verify-work): + - a `closure_note` line: framework part closed by 35-05..35-07 (built-in layouts, logo, site name, button partial support, CSS inlining); plugin part deferred to the follow-up after the framework tag; + - a `rerun_scope` line: the scoped test 8 re-run above, plus the deferred plugin check. Commit as listed in Execution units. @@ -227,6 +240,8 @@ Output: test and gate-script commits in this repository; one planning-docs commi - `grep -c "localeVariants" admin/tests/form/FormViewMail.test.ts` prints a number above 0 - `grep -n "TestMailLocaleGroups\|LocaleVariantSwitcher.test.ts" scripts/check-phase35.sh` prints at least two lines - `grep -n "G-35-1\|G-35-8" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints at least two lines + - `grep -n "closure_note\|rerun_scope" .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md` prints at least two lines, and `grep -n "^status: diagnosed" .planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md` still prints one line + - `grep -in "deferred" .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` prints at least one line naming the plugin follow-up check The admin side of both gaps is pinned by named tests, one command proves the whole gap closure plus the unchanged core plugins, and the validation map records how. @@ -259,7 +274,8 @@ Output: test and gate-script commits in this repository; one planning-docs commi - Named unit tests pin G-35-1 and G-35-8 behaviour in postcard, cabana and the SPA. - The phase gate requires them and stays read-only against the core plugins with the new dependency. -- Ready for `/msd-verify-work 35` (re-run UAT tests 1 and 8 on sm-demo-app after resetting the two UAT overrides); nothing pushed or tagged. +- G-35-8 is recorded as framework-closed with the plugin part deferred (35-VALIDATION.md and the 35-UAT.md closure note). +- Ready for `/msd-verify-work 35`: re-run UAT test 1 in full; re-run test 8 scoped to the built-in layouts (default and system, with logo, Site name and the button partial in a body override) after resetting the two UAT overrides; the plugin CTA and plugin layouts stay a deferred follow-up check. Nothing pushed or tagged.