feat(engagement): templates — the email block family, renderer and seeded set (engagement Phase 5a)

Every subject and body moves out of `mailer.js` into `engagement_templates` rows an
operator can edit. A relocation, not a regression: nothing that sends mail today
starts depending on an operator authoring something first.

- `email.*` block family in its own registry, sharing the page family's envelope
  walk and validate-then-sanitize order by binding rather than by copy.
- A server-side renderer producing both parts of a multipart message; the text
  part is byte-identical to the literals this commit deletes.
- Nine seeded templates, six of them wired now; the seeder's `customized = 0`
  guard lives in the UPDATE's own WHERE.
- `renderByKey` falls back to the shipped seed when a row is missing or unusable,
  so no failure of the table can stop a password reset.

Also fixes `check:hosts` reading the template key `auth.email-verify` as the
hostname `auth.email`.

Co-Authored-By: Claude <noreply@anthropic.com>

server/src/engagement/templates.js

@@ -0,0 +1,190 @@
+// ── Templates: resolve, render, seed ───────────────────────────────────────
+//
+// The seam between a stored `engagement_templates` row and the two body parts a
+// transport sends. Everything that needs a database happens here; `emailBlocks/`
+// stays pure and synchronous below it.
+//
+// **A missing row renders the shipped default rather than nothing.** `renderByKey`
+// falls back to `templateSeeds.js` whenever the row is absent or its blocks will
+// not parse. This is not defensive padding — it is what makes it safe for
+// `mailer` to depend on the database for a password-reset body at all. Before the
+// first seed runs, after a restore that dropped the table, on a deployment whose
+// operator deleted a row by hand: the mail still goes out, in the shipped wording,
+// and the `protected` flag stops the last of those from being reachable through
+// the API. The same posture `settingsJson` and `resolveThemeTokens` take — a
+// stored value that is unusable is treated as absent, never as an error.
+
+const templatesDb = require('../model/engagement/engagementTemplates.db')
+const settings = require('../model/settings/settings.model')
+const brand = require('../config/brand')
+const emailBlocks = require('../emailBlocks')
+const { SEEDS, AMBIENT_VARIABLES, seedByKey } = require('./templateSeeds')
+// The trigger registry lives with the module registries, not here — a trigger is
+// something a MODULE declares (see engagement/index.js's header).
+const { eventTrigger } = require('../modules/registries')
+const log = require('../utils/logger')('templates')
+
+const baseUrl = () => (process.env.APP_BASE_URL || brand.url || 'http://localhost:5173').replace(/\/+$/, '')
+
+/**
+ * The brand values every template may reference, resolved from the same places
+ * the site's own chrome resolves them (§4.6.1 property 2).
+ *
+ * **They are merged OVER the caller's values, not under.** A caller supplies the
+ * message; the deployment supplies its identity. Letting a caller pass its own
+ * `siteName` would mean a module — or a bug — could send mail that claims to be
+ * from somewhere else, which is precisely the thing a recipient cannot check.
+ *
+ * Never throws: a settings read that fails degrades to the BRAND_* env values, so
+ * mail is branded slightly less specifically rather than not sent.
+ */
+async function ambient() {
+  let name = brand.name
+  let logo = brand.logo
+  let theme = null
+  try {
+    name = await settings.getInstanceName()
+    const shell = await settings.getShellBrand()
+    logo = shell.logo || brand.logo
+    theme = shell.theme
+  } catch (err) {
+    log.warn('brand resolution failed; falling back to BRAND_* env', { message: err.message })
+  }
+  const base = baseUrl()
+  const absLogo = logo && logo.startsWith('/') ? `${base}${logo}` : logo || ''
+  return {
+    values: {
+      siteName: name,
+      siteUrl: base,
+      logoUrl: absLogo,
+      year: String(new Date().getUTCFullYear()),
+    },
+    // resolveThemeTokens speaks CSS custom properties; the renderer speaks colour
+    // names. One mapping, here, rather than the renderer knowing about CSS.
+    theme: { accent: theme ? theme['--accent'] : undefined },
+    baseUrl: base,
+  }
+}
+
+/**
+ * Which variables a template may reference — the input to Phase 5b's palette and
+ * to its save-time "undeclared variable" refusal.
+ *
+ * Two sources, because a template has two possible origins. One tied to a trigger
+ * reads §4.3's declaration, which is the authority for anything a module emits.
+ * One with no trigger — every transactional seed is one; `mailer` renders them by
+ * key with no rule involved — has no trigger to ask, so its shipped definition
+ * carries the list. Ambient brand variables are appended to both.
+ *
+ * @param {{ trigger_id?: string|null, seed_key?: string|null }} template
+ * @returns {Array<{name: string, type: string, required: boolean, example: unknown}>}
+ */
+function variablesFor(template) {
+  const own = []
+  if (template && template.trigger_id) {
+    const declared = eventTrigger(template.trigger_id)
+    if (declared && Array.isArray(declared.variables)) own.push(...declared.variables)
+  } else if (template && template.seed_key) {
+    const seed = seedByKey(template.seed_key)
+    if (seed) own.push(...seed.variables)
+  }
+  const names = new Set(own.map((v) => v.name))
+  return [...own, ...AMBIENT_VARIABLES.filter((v) => !names.has(v.name))]
+}
+
+/**
+ * Render one template into its two body parts.
+ *
+ * @param {object} template a row, or a seed definition
+ * @param {Record<string, unknown>} values
+ * @param {object} resolved the result of ambient()
+ * @returns {{ subject: string, html: string, text: string, missing: string[] }}
+ */
+function renderTemplate(template, values, resolved) {
+  const merged = { ...values, ...resolved.values }
+  const missing = new Set()
+  const ctx = emailBlocks.buildContext({
+    values: merged,
+    theme: resolved.theme,
+    baseUrl: resolved.baseUrl,
+    missing,
+  })
+  const rendered = emailBlocks.renderBlocks(template.blocks, ctx)
+  const subject = template.subject ? ctx.t(template.subject) : ''
+  // An authored `text_body` REPLACES the generated one (§4.4), and is interpolated
+  // like any other authored string. It is a per-template override, not an addition.
+  const text = template.text_body ? ctx.t(template.text_body) : rendered.text
+  return {
+    subject,
+    html: emailBlocks.renderDocument(rendered.html, ctx, subject),
+    text,
+    missing: [...missing],
+  }
+}
+
+/**
+ * Render the template stored under `key`, falling back to its shipped default.
+ * @returns {Promise<{subject: string, html: string, text: string, missing: string[]}|null>}
+ *          null only when `key` names neither a row nor a seed.
+ */
+async function renderByKey(key, values = {}) {
+  const resolved = await ambient()
+  let template = null
+  try {
+    template = await templatesDb.getByKey(key)
+  } catch (err) {
+    log.warn('template read failed; using the shipped default', { key, message: err.message })
+  }
+  if (!template || !Array.isArray(template.blocks) || template.blocks.length === 0) {
+    const seed = seedByKey(key)
+    if (!seed) return null
+    if (template) log.warn('stored template is unusable; using the shipped default', { key })
+    template = { subject: seed.subject, blocks: seed.blocks, text_body: null }
+  }
+  return renderTemplate(template, values, resolved)
+}
+
+/**
+ * Ensure every shipped template exists, and bring un-customized rows up to the
+ * current seed. Idempotent: a second run reports nine skips and writes nothing.
+ *
+ * Never throws — it is called from `seedDefaults()` on the boot path, and a
+ * template that failed to seed costs the shipped default (see the header note),
+ * not the deployment.
+ */
+async function seedTemplates() {
+  const counts = { inserted: 0, updated: 0, skipped: 0, invalid: 0 }
+  for (const seed of SEEDS) {
+    // Validated against the registry before it is stored, even though a seed is
+    // code rather than input. The alternative is a shipped block array that no
+    // renderer understands sitting in the table, which reads to an operator as
+    // their deployment being broken; refusing to write it leaves `renderByKey`'s
+    // fallback in charge and puts the reason in the boot log.
+    const { valid, errors } = emailBlocks.validateEmailBlocks(seed.blocks)
+    if (!valid) {
+      log.error('shipped template is invalid and was not seeded', { key: seed.key, errors })
+      counts.invalid += 1
+      continue
+    }
+    try {
+      counts[await templatesDb.seedOne(seed)] += 1
+    } catch (err) {
+      log.error('template seed failed', { key: seed.key, message: err.message })
+    }
+  }
+  // The third arm of §4.6.1 property 3: a customized row is never touched, and the
+  // fact that a better default now exists is surfaced instead of applied.
+  let stale = []
+  try {
+    stale = await templatesDb.staleCustomized(SEEDS.map((s) => ({ key: s.key, seedVersion: s.seedVersion })))
+  } catch {
+    stale = []
+  }
+  if (stale.length) {
+    log.info('customized templates have a newer shipped default', { keys: stale.map((t) => t.key) })
+  }
+  log.info('engagement templates ensured', counts)
+  return { ...counts, stale: stale.map((t) => t.key) }
+}
+
+module.exports = { ambient, variablesFor, renderTemplate, renderByKey, seedTemplates, baseUrl }