@teamscala/service-boot 0.23.388 → 0.23.391

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.388",
+  "version": "0.23.391",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

package/src/fn-routers/email-defaults.ts

@@ -3,20 +3,26 @@
  * @status handwritten
  * @edit edit directly
  *
- * Cached reader for the `email-defaults` config row's `default_sender` — the
- * from-address for outbound transactional email (agreement/proposal/assessment
- * senders). Replaces the former process.env.DEFAULT_EMAIL_SENDER read
- * (configured-primitives: the registry row is the source of truth, not env).
+ * Hot snapshot of `email-defaults.default_sender` (outbound transactional
+ * from-address). Replaces the former process.env.DEFAULT_EMAIL_SENDER read.
+ * Invalidated by NOTIFY on `registry_config_changed`; `staleAfterMs` is the
+ * safety ceiling for an upstream regression that drops notifications.
  */
+import { createNotifyCache } from "@teamscala/notify-cache/create-notify-cache";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import * as v from "valibot";
 
 const FALLBACK_SENDER = "noreply@gateway.scala.business";
-let cached: string | undefined;
+const defaultSenderCache = createNotifyCache<string>({
+	name: "service-boot:default-email-sender",
+	load: async () => {
+		const row = await loadRegistryConfig("config", "email-defaults", v.looseObject({}));
+		return (row?.default_sender as string | undefined) ?? FALLBACK_SENDER;
+	},
+	invalidateOn: ["registry_config_changed"],
+	staleAfterMs: 5 * 60 * 1000,
+});
 
 export async function getDefaultEmailSender(): Promise<string> {
-	if (cached !== undefined) return cached;
-	const row = await loadRegistryConfig("config", "email-defaults", v.looseObject({}));
-	cached = (row?.default_sender as string | undefined) ?? FALLBACK_SENDER;
-	return cached;
+	return defaultSenderCache.get();
 }

package/src/fn-routers/email-link-ttl.ts

@@ -3,21 +3,26 @@
  * @status handwritten
  * @edit edit directly
  *
- * Cached reader for the `email-links` config row's `email_link_ttl_ms` — the
- * validity window for agreement/proposal email-access magic links (dedup'd
- * across the 3 fn-routers that mint them). Replaces the former per-file
- * hardcoded EMAIL_LINK_TTL_MS constant (config-constants: the registry row is
- * the source of truth, not the literal).
+ * Hot snapshot of `email-links.email_link_ttl_ms` (magic-link validity
+ * window, dedup'd across the 3 fn-routers that mint them). Replaces the
+ * former per-file EMAIL_LINK_TTL_MS constant. Invalidated by NOTIFY on
+ * `registry_config_changed`.
  */
+import { createNotifyCache } from "@teamscala/notify-cache/create-notify-cache";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import * as v from "valibot";
 
 const DEFAULT_EMAIL_LINK_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-let cached: number | undefined;
+const emailLinkTtlCache = createNotifyCache<number>({
+	name: "service-boot:email-link-ttl",
+	load: async () => {
+		const row = await loadRegistryConfig("config", "email-links", v.looseObject({}));
+		return (row?.email_link_ttl_ms as number | undefined) ?? DEFAULT_EMAIL_LINK_TTL_MS;
+	},
+	invalidateOn: ["registry_config_changed"],
+	staleAfterMs: 5 * 60 * 1000,
+});
 
 export async function getEmailLinkTtlMs(): Promise<number> {
-	if (cached !== undefined) return cached;
-	const row = await loadRegistryConfig("config", "email-links", v.looseObject({}));
-	cached = (row?.email_link_ttl_ms as number | undefined) ?? DEFAULT_EMAIL_LINK_TTL_MS;
-	return cached;
+	return emailLinkTtlCache.get();
 }

package/src/fn-routers/public-assessment-router.ts

@@ -25,10 +25,11 @@ import * as v from "valibot";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { sendEmail, initResendClient } from "@teamscala/api-resend/send-email";
 import { applyTemplateVars, lookupTemplate } from "@teamscala/email/templates/lookup";
+import { resolveEmailSender } from "@teamscala/email/identity/resolve-email-sender";
 import { decryptSecretConfig } from "@teamscala/encryption/crypto/secret-config";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { fetchOrgBrand } from "@teamscala/resolver-engine/data-resolvers/fetch-org-brand";
 import { recordEvent } from "@teamscala/event-log/record-event";
-import { getDefaultEmailSender } from "./email-defaults.ts";
 
 interface Context {
 	prisma: any;
@@ -106,9 +107,9 @@ function bandForScore(
 
 /**
  * Best-effort branded Authority Index Report email. Self-contained: loads its
- * own Resend secret, swallows every error — a send failure is logged and NEVER
- * undoes the submit (the agreement-completion-email pattern). Fire-and-forget
- * from the submit handler.
+ * own Resend secret, swallows every error. Sender identity + brand tokens
+ * come from resolveEmailSender (per-org email_sender row). On Resend refusal
+ * the call falls back to the platform sender and logs the reason.
  */
 async function sendAuthorityReportEmail(opts: {
 	to: string;
@@ -117,6 +118,9 @@ async function sendAuthorityReportEmail(opts: {
 	bandLabel: string;
 	categoryScores: Record<string, number>;
 	ctaUrl?: string;
+	organisationId?: string | null;
+	brand?: import("@teamscala/email/identity/resolve-email-sender").OrgBrandTokens;
+	prisma: any;
 }): Promise<void> {
 	const log = getAppLogger();
 	const rawSecret = await loadRegistryConfig(
@@ -132,17 +136,26 @@ async function sendAuthorityReportEmail(opts: {
 		return;
 	}
 	initResendClient(decrypted.token);
-	const from = await getDefaultEmailSender();
+
+	const sender = await resolveEmailSender(opts.organisationId ?? null);
+	const primary = sender.brand.primaryColor;
+	const muted = "#6b7280"; // structural neutral for body labels
+	const logoUrl = sender.brand.logoUrl;
+	const logoHtml =
+		logoUrl && /^https?:\/\//.test(logoUrl)
+			? `<p style="margin:0 0 20px"><img src="${logoUrl}" alt="${sender.brand.orgName || ""}" style="max-height:56px;display:block"></p>`
+			: "";
+
 	// Subject + body from the `authority-index-report` email_template row, not
-	// literals here (email-template-registry-type). The per-pillar rows and the
-	// optional CTA are the only DYNAMIC markup, so they are rendered here and
-	// passed as merge vars — the row still owns all the copy and the layout.
+	// literals here (email-template-registry-type). Dynamic markup is rendered
+	// here and passed as merge vars — the row owns copy + layout; colours +
+	// logo come from the org brand tokens, NOT inline literals.
 	const pillarRows = (
 		Object.entries(opts.categoryScores) as Array<[string, number]>
 	)
 		.map(
 			([name, score]) =>
-				`<tr><td style="padding:6px 0;color:#374151">${name}</td><td style="padding:6px 0;text-align:right;font-weight:600;color:#111827">${score} / 100</td></tr>`,
+				`<tr><td style="padding:6px 0;color:${muted}">${name}</td><td style="padding:6px 0;text-align:right;font-weight:600;color:${primary}">${score} / 100</td></tr>`,
 		)
 		.join("");
 	const pillarsText = (
@@ -156,27 +169,80 @@ async function sendAuthorityReportEmail(opts: {
 		bandLabel: opts.bandLabel,
 		pillarRows,
 		pillarsText,
+		brandPrimaryColor: primary,
+		brandAccentColor: sender.brand.accentColor ?? primary,
+		brandLogoHtml: logoHtml,
+		orgName: sender.brand.orgName,
 		ctaHtml: opts.ctaUrl
-			? `<p style="margin:24px 0 0"><a href="${opts.ctaUrl}" style="display:inline-block;background:#111827;color:#ffffff;text-decoration:none;font-weight:600;padding:12px 22px;border-radius:8px">Book your Authority Growth Session</a></p>`
+			? `<p style="margin:24px 0 0"><a href="${opts.ctaUrl}" style="display:inline-block;background:${primary};color:#ffffff;text-decoration:none;font-weight:600;padding:12px 22px;border-radius:8px">Book your Authority Growth Session</a></p>`
 			: "",
 		ctaText: opts.ctaUrl ? `\nBook your Authority Growth Session: ${opts.ctaUrl}` : "",
 	});
-	const res = await sendEmail({
-		from,
-		to: opts.to,
-		subject: tpl.subject,
-		html: tpl.bodyHtml,
-		text: tpl.bodyText,
-	});
+
+	const sendOnce = async (fromHeader: string, replyToHeader: string | undefined) =>
+		sendEmail({
+			from: fromHeader,
+			to: opts.to,
+			subject: tpl.subject,
+			html: tpl.bodyHtml,
+			text: tpl.bodyText,
+			reply_to: replyToHeader,
+		});
+
+	let res = await sendOnce(sender.from, sender.replyTo);
+	let usedFrom = sender.from;
+	if (!res.success) {
+		// Resend refused the org sender (likely unverified domain). Fall back
+		// to the platform sender; never fail because a verification lookup
+		// failed — the resolver returns the row, the failure is at Resend.
+		const platformRow = await loadRegistryConfig(
+			"config",
+			"email-defaults",
+			v.looseObject({ default_sender: v.optional(v.string()) }),
+		).catch(() => null);
+		const fallbackFrom =
+			(platformRow?.default_sender as string | undefined)?.trim() ||
+			"scala <noreply@gateway.scala.business>";
+		log.warn(
+			`[authority-report-email] org sender ${sender.from} refused by Resend (${res.error ?? "unknown"}); falling back to platform ${fallbackFrom}`,
+		);
+		res = await sendOnce(fallbackFrom, undefined);
+		usedFrom = fallbackFrom;
+	}
+
 	if (res.success) {
 		log.info(
-			`[authority-report-email] sent to ${opts.to}${res.id ? ` (id ${res.id})` : ""}`,
+			`[authority-report-email] sent to ${opts.to}${res.id ? ` (id ${res.id})` : ""} from=${usedFrom}${sender.isOrgIdentity ? "" : " (platform fallback)"}`,
 		);
 	} else {
 		log.error(
 			`[authority-report-email] failed to ${opts.to}: ${res.error ?? "unknown"}`,
 		);
 	}
+
+	// email-send-audited: best-effort audit row. Guarded so a stale prisma
+	// client (scala-quiz schema predates email_send_log) skips cleanly.
+	try {
+		const auditPrisma = opts.prisma as {
+			email_send_log?: { create: (args: unknown) => Promise<unknown> };
+		};
+		if (auditPrisma?.email_send_log) {
+			await auditPrisma.email_send_log.create({
+				data: {
+					to_address: opts.to,
+					template_slug: "authority-index-report",
+					status: res.success ? "sent" : "failed",
+					provider_message_id: res.id ?? null,
+					error: res.success ? null : (res.error ?? "unknown"),
+					from_address: usedFrom,
+				},
+			});
+		}
+	} catch (auditErr) {
+		log.warn(
+			`[authority-report-email] audit row write failed: ${auditErr instanceof Error ? auditErr.message : String(auditErr)}`,
+		);
+	}
 }
 
 function scoreAnswers(
@@ -375,6 +441,21 @@ export const publicAssessmentRouter = {
 				(typeof assessment.cta_url === "string" && assessment.cta_url) ||
 				undefined;
 			if (band) {
+				const prisma = (context as { prisma: unknown }).prisma;
+				const brandRow = opts.organisationId
+					? await fetchOrgBrand(
+							prisma as Parameters<typeof fetchOrgBrand>[0],
+							opts.organisationId,
+						).catch(() => null)
+					: null;
+				const brand = brandRow
+					? {
+							orgName: brandRow.companyName ?? "",
+							primaryColor: brandRow.primaryColor,
+							accentColor: brandRow.accentColor ?? null,
+							logoUrl: brandRow.logo.light ?? null,
+						}
+					: undefined;
 				void sendAuthorityReportEmail({
 					to: email,
 					firstName,
@@ -382,6 +463,9 @@ export const publicAssessmentRouter = {
 					bandLabel: band.label,
 					categoryScores,
 					ctaUrl,
+					organisationId: opts.organisationId,
+					brand,
+					prisma,
 				}).catch((e) =>
 					log.error(
 						`[publicAssessment.submit] report email non-fatal: ${e instanceof Error ? e.message : String(e)}`,

package/src/module-not-found.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Locks the mount candidate-chain regression (2026-08-24): scala-agents-ui
+ * crash-looped at boot because @teamscala/cli-session exports ./boot/mount.ts
+ * and not ./mount.ts. The chain already listed boot/mount.ts as a fallback,
+ * but Bun names an unexported subpath by its BARE package, so the first
+ * candidate's miss was classified as a real error and boot died before the
+ * fallback ran. The whole value of the chain is that candidate 1 may be absent.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { barePackageOf, isModuleNotFound } from "./module-not-found";
+
+describe("barePackageOf", () => {
+	it("keeps the scope for scoped packages", () => {
+		expect(barePackageOf("@teamscala/cli-session/mount.ts")).toBe(
+			"@teamscala/cli-session",
+		);
+		expect(barePackageOf("@teamscala/cli-session")).toBe(
+			"@teamscala/cli-session",
+		);
+	});
+
+	it("takes the first segment for unscoped packages", () => {
+		expect(barePackageOf("hono/mount.ts")).toBe("hono");
+		expect(barePackageOf("hono")).toBe("hono");
+	});
+});
+
+describe("isModuleNotFound", () => {
+	// The exact shape Bun emits for an unexported subpath: it names the
+	// PACKAGE, never the subpath that was asked for.
+	const bunSubpathMiss = {
+		message:
+			"Cannot find package '@teamscala/cli-session' imported from /srv/node_modules/@teamscala/service-boot/src/mount-server-packages.ts",
+	};
+
+	it("treats an unexported subpath as not-found so the chain falls through", () => {
+		expect(
+			isModuleNotFound(bunSubpathMiss, "@teamscala/cli-session/mount.ts"),
+		).toBe(true);
+	});
+
+	it("still matches when the error names the full specifier", () => {
+		expect(
+			isModuleNotFound(
+				{ message: "Cannot find module '@teamscala/x/mount.ts'" },
+				"@teamscala/x/mount.ts",
+			),
+		).toBe(true);
+	});
+
+	it("does NOT swallow a transitive miss of a DIFFERENT module", () => {
+		// A file inside the candidate failing to resolve something else must
+		// surface as a real error, or the true cause hides behind "not found".
+		expect(
+			isModuleNotFound(
+				{ message: "Cannot find package '@teamscala/some-other-dep'" },
+				"@teamscala/cli-session/mount.ts",
+			),
+		).toBe(false);
+	});
+
+	it("does NOT swallow a syntax or runtime error", () => {
+		expect(
+			isModuleNotFound(
+				new SyntaxError("Unexpected token"),
+				"@teamscala/cli-session/mount.ts",
+			),
+		).toBe(false);
+	});
+
+	it("reads non-Error throwables defensively (Bun ResolveMessage is not an Error)", () => {
+		expect(
+			isModuleNotFound(
+				"Cannot find package '@teamscala/cli-session'",
+				"@teamscala/cli-session/mount.ts",
+			),
+		).toBe(true);
+	});
+});

package/src/module-not-found.ts

@@ -0,0 +1,39 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Classifies a failed dynamic import as "this candidate is absent" vs a real
+ * error, for the server_package mount candidate chain. Extracted from
+ * mount-server-packages so the classification is testable: as a closure it
+ * could not be exercised, and it shipped wrong.
+ */
+
+/** `@scope/name/sub/path.ts` -> `@scope/name`; `name/sub` -> `name`. */
+export function barePackageOf(specifier: string): string {
+	const parts = specifier.split("/");
+	return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+/**
+ * True when the import failed because `requestedPath` itself is absent.
+ *
+ * Bun reports an unexported SUBPATH as `Cannot find package '<bare>'`, naming
+ * the package rather than the subpath, so the bare name of THIS candidate
+ * counts as not-found. Without that the first candidate's miss is
+ * misclassified as fatal and the fallbacks never run (measured 2026-08-24:
+ * scala-agents-ui crash-looped because cli-session exports ./boot/mount.ts and
+ * not ./mount.ts). A transitive miss naming a DIFFERENT module still surfaces.
+ */
+export function isModuleNotFound(err: unknown, requestedPath: string): boolean {
+	const msg =
+		(err as { message?: string })?.message ??
+		(typeof err === "string" ? err : String(err));
+	const bare = barePackageOf(requestedPath);
+	return (
+		msg.includes(`Cannot find module '${requestedPath}'`) ||
+		msg.includes(`Cannot find package '${requestedPath}'`) ||
+		msg.includes(`Cannot find module '${bare}'`) ||
+		msg.includes(`Cannot find package '${bare}'`)
+	);
+}

package/src/mount-server-packages.ts

@@ -20,6 +20,7 @@ import {
 	type MountRegistry,
 } from "@teamscala/os/runtime-contracts/mount-context";
 import type { Hono } from "hono";
+import { isModuleNotFound } from "./module-not-found";
 
 type ServerPackageMount = (ctx: MountContext) => Promise<void> | void;
 
@@ -68,19 +69,7 @@ export async function mountServerPackages(
 		return mountRegistry;
 	}
 
-	const isModuleNotFound = (err: unknown, requestedPath: string): boolean => {
-		// Bun's ResolveMessage is not an Error subclass — read message defensively.
-		// Match ONLY when the missing module is the candidate path itself; transitive
-		// not-found errors (e.g. a file inside the candidate fails to resolve a
-		// different module) must surface, not be swallowed as "not found here".
-		const msg =
-			(err as { message?: string })?.message ??
-			(typeof err === "string" ? err : String(err));
-		return (
-			msg.includes(`Cannot find module '${requestedPath}'`) ||
-			msg.includes(`Cannot find package '${requestedPath}'`)
-		);
-	};
+
 
 	for (const pkg of serverPackages) {
 		try {