feat(04-03): register plugin mail layouts and publish the mailer at boot

- Map short layout names onto dotted layout files and wrap text/HTML
- party.Activate publishes postcard.Mailer before Boot and names missing files
- Hello plugin sends through the app-scoped mailer

Co-authored-by: Cursor <cursoragent@cursor.com>

postcard/mailer.go

@@ -3,6 +3,10 @@ package postcard
 import (
 	"context"
 	"fmt"
+	"strings"
+
+	"git.golem15.com/golem15/summercms/backpack"
+	"git.golem15.com/golem15/summercms/pact"
 )
 
 // Message is the Send contract for plugin callers.
@@ -70,3 +74,44 @@ func (m *mailer) Send(ctx context.Context, msg Message) error {
 	}
 	return nil
 }
+
+// Activate publishes an app-scoped Mailer before plugin Boot. Catalog files
+// are validated later at each plugin's Boot transition.
+func Activate[P interface{ ID() string }](app *backpack.App, _ []P) error {
+	if app == nil {
+		return fmt.Errorf("postcard: app is nil")
+	}
+	opts := Options{}
+	if app.Config != nil {
+		opts.From = strings.TrimSpace(app.Config.String("mail.from"))
+		opts.CSS = app.Config.String("mail.css")
+		opts.BrandCSS = app.Config.String("mail.brandCss")
+	}
+	m := &mailer{
+		catalog: NewCatalog(),
+		driver:  NewMemoryDriver(),
+		opts:    opts,
+	}
+	if err := app.Publish[Mailer](m); err != nil {
+		return fmt.Errorf("postcard: %w", err)
+	}
+	return nil
+}
+
+// BootPlugin registers a plugin's declared mail templates and layouts.
+// Missing files and unknown layout aliases fail with the dotted name.
+func BootPlugin[P interface{ ID() string }](app *backpack.App, p P) error {
+	hm, ok := any(p).(pact.HasMailTemplates)
+	if !ok {
+		return nil
+	}
+	got, ok := app.Lookup[Mailer]()
+	if !ok {
+		return fmt.Errorf("postcard: mailer not published")
+	}
+	m, ok := got.(*mailer)
+	if !ok || m == nil || m.catalog == nil {
+		return fmt.Errorf("postcard: mailer not published")
+	}
+	return m.catalog.Register(p.ID(), hm.MailTemplatesFS(), hm.MailTemplates(), hm.MailLayouts())
+}

postcard/mailer_test.go

@@ -102,3 +102,74 @@ Hello **{{ .Name }}**.
 		}
 	})
 }
+
+func TestMailLayoutSmoke(t *testing.T) {
+	t.Parallel()
+
+	fsys := fstest.MapFS{
+		"views/mail/note.htm": {Data: []byte(`subject = "Hi {{ .Name }}"
+layout = "hello"
+==
+Body **{{ .Name }}**.
+`)},
+		"views/mail/layouts/hello.htm": {Data: []byte(`name = "Hello"
+==
+-- {{ .Content }} --
+==
+<div class="layout-hello">{{ .Content }}</div>
+<style>{{ .brandCss }}{{ .css }}</style>
+`)},
+	}
+	cat := NewCatalog()
+	if err := cat.Register("golem15.hello", fsys, []string{"golem15.hello::mail.note"}, map[string]string{
+		"hello": "golem15.hello::mail.layouts.hello",
+	}); err != nil {
+		t.Fatalf("Register: %v", err)
+	}
+	drv := NewMemoryDriver()
+	mail := NewMailer(cat, drv, Options{CSS: "p{color:red}", BrandCSS: ".brand{color:blue}"})
+	if err := mail.Send(context.Background(), Message{
+		Template: "golem15.hello::mail.note",
+		To:       []string{"ada@example.test"},
+		Vars:     map[string]any{"Name": "Ada"},
+	}); err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+	got := drv.Messages()
+	if len(got) != 1 {
+		t.Fatalf("stored %d messages", len(got))
+	}
+	if !strings.Contains(got[0].Text, "-- Body **Ada**. --") {
+		t.Fatalf("text wrapper = %q", got[0].Text)
+	}
+	if !strings.Contains(got[0].HTML, `class="layout-hello"`) || !strings.Contains(got[0].HTML, "<strong>Ada</strong>") {
+		t.Fatalf("HTML wrapper = %q", got[0].HTML)
+	}
+	if !strings.Contains(got[0].HTML, "p{color:red}") || !strings.Contains(got[0].HTML, ".brand{color:blue}") {
+		t.Fatalf("shared css missing: %q", got[0].HTML)
+	}
+
+	t.Run("missing template fails with name", func(t *testing.T) {
+		err := NewCatalog().Register("golem15.hello", fsys, []string{"golem15.hello::mail.missing"}, nil)
+		if err == nil || !strings.Contains(err.Error(), "golem15.hello::mail.missing") {
+			t.Fatalf("missing template error = %v", err)
+		}
+	})
+	t.Run("unknown layout fails with name", func(t *testing.T) {
+		bad := fstest.MapFS{
+			"views/mail/note.htm": {Data: []byte("subject = \"Hi\"\nlayout = \"plytarium\"\n==\nHi.\n")},
+		}
+		err := NewCatalog().Register("golem15.hello", bad, []string{"golem15.hello::mail.note"}, nil)
+		if err == nil || !strings.Contains(err.Error(), "plytarium") {
+			t.Fatalf("unknown layout error = %v", err)
+		}
+	})
+	t.Run("missing layout file fails with full name", func(t *testing.T) {
+		err := NewCatalog().Register("golem15.hello", fsys, nil, map[string]string{
+			"hello": "golem15.hello::mail.layouts.missing",
+		})
+		if err == nil || !strings.Contains(err.Error(), "golem15.hello::mail.layouts.missing") {
+			t.Fatalf("missing layout error = %v", err)
+		}
+	})
+}