@teamscala/service-boot 0.23.284

package/src/proposal-chat-inject.ts

@@ -0,0 +1,141 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Injects the ProposalChatLauncher block into an AUTHORISED proposal page (called
+ * from proposalGateConfig.onAuthorized — so the bubble lives strictly behind the
+ * email gate, and every proposal gets it with no per-page Puck edit). It builds
+ * the proposal's full page content into a runtime-context string and passes it to
+ * the launcher, which forwards it to the chat as <runtime_context> — so ONE shared
+ * "Proposal Assistant" agent answers about whichever proposal is being viewed.
+ *
+ * The agent id is config, not code (registries-are-source-of-truth): the
+ * `config / proposal-assistant-agent` row carries { agentId }. No row (or no
+ * agent) → no injection, the page renders exactly as before (fail-soft).
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { getServerClient } from "./page-server-orpc/server-client.ts";
+import * as v from "valibot";
+
+const AgentConfigSchema = v.object({ agentId: v.string() });
+
+/** Serialise the entire page content tree as text for the GPT context. */
+async function buildProposalContext(resolved: Record<string, unknown>): Promise<string> {
+	const proposal = resolved.proposal as Record<string, unknown> | undefined;
+	const parts: string[] = [];
+
+	if (typeof proposal?.name === "string" && proposal.name) {
+		parts.push(`Proposal title: ${proposal.name}`);
+	}
+	if (typeof proposal?.client_name === "string" && proposal.client_name) {
+		parts.push(`Prepared for: ${proposal.client_name}`);
+	}
+	if (typeof proposal?.description === "string" && proposal.description) {
+		parts.push(`Description: ${proposal.description}`);
+	}
+
+	// Dump the entire page content tree — every block, every prop, verbatim.
+	const page = (resolved.page as { puck_data?: { content?: unknown[] } } | undefined)?.puck_data;
+	if (page && Array.isArray(page.content)) {
+		parts.push("\n--- Page content ---");
+		parts.push(JSON.stringify(page.content, null, 2));
+	}
+
+	// Resolve DB-backed product tiers so the GPT sees actual pricing data.
+	const client = getServerClient() as {
+		products?: {
+			findFirst: (args: {
+				where: { id: string };
+				select: { id: true; billing_type: true; tiers: true; components: true };
+			}) => Promise<{
+				id: string;
+				billing_type: string;
+				tiers: unknown;
+				components: unknown;
+			} | null>;
+		};
+	};
+
+	for (const block of (page?.content ?? []) as Array<Record<string, unknown>>) {
+		if (block?.type !== "ProductTiers") continue;
+		const props = block.props as Record<string, unknown> | undefined;
+		if (!props) continue;
+
+		const productIds = [
+			props.productId,
+			props.productId2,
+			props.productId3,
+		].filter((id): id is string => typeof id === "string" && id.trim().length > 0);
+
+		for (const pid of productIds) {
+			try {
+				const product = await client.products?.findFirst({
+					where: { id: pid },
+					select: { id: true, billing_type: true, tiers: true, components: true },
+				});
+				if (product) {
+					parts.push(`\n--- Product tiers (productId: ${pid}) ---`);
+					parts.push(JSON.stringify(product, null, 2));
+				}
+			} catch {
+				// best-effort
+			}
+		}
+	}
+
+	return parts.join("\n");
+}
+
+function brandPrimaryColor(resolved: Record<string, unknown>): string {
+	const brand = resolved.brand as { primaryColor?: unknown } | undefined;
+	return typeof brand?.primaryColor === "string" ? brand.primaryColor : "";
+}
+
+export async function injectProposalChatLauncher(
+	resolved: Record<string, unknown>,
+	viewerEmail: string,
+): Promise<void> {
+	const page = (resolved.page as { puck_data?: { content?: unknown[] } } | undefined)?.puck_data;
+	if (!page || !Array.isArray(page.content)) return;
+
+	const proposal = resolved.proposal as Record<string, unknown> | undefined;
+	const organisationId =
+		typeof proposal?.organisation_id === "string" ? proposal.organisation_id : "";
+	if (!organisationId) return;
+
+	let agentId = "";
+	try {
+		agentId = (
+			await loadRegistryConfig("config", "proposal-assistant-agent", AgentConfigSchema)
+		).agentId;
+	} catch {
+		return; // no agent configured yet → no bubble (fail-soft, page unchanged)
+	}
+	if (!agentId) return;
+
+	try {
+		const runtimeContext = await buildProposalContext(resolved);
+		(page.content as Array<Record<string, unknown>>).push({
+			type: "ChatLauncherBlock",
+			props: {
+				id: "proposal-chat-launcher",
+				agentId,
+				organisationId,
+				viewerEmail,
+				runtimeContext,
+				primaryColor: brandPrimaryColor(resolved),
+				title: "Proposal Assistant",
+				welcomeMessage:
+					"Hi! Ask me anything about this proposal — scope, pricing, timeline or next steps.",
+				launchLabel: "Ask about this proposal",
+			},
+		});
+	} catch (err) {
+		getAppLogger().error(
+			`[proposal-chat] launcher injection failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+}

package/src/proposal-gate.ts

@@ -0,0 +1,175 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The PROPOSAL content gate, expressed as config for the content-gate primitive
+ * (content-gate/). No bespoke gate plumbing — just the proposal-specific bits:
+ * which resource (resolved.proposal.id), who's authorized (issuing-org team +
+ * recipient), what to seed (initialVisitor for the chat), and how to withhold
+ * (replace the proposal body with an injected SignIn gate block + neutralize the
+ * meta tags). The engine handles cookie/token/verify/orchestration.
+ *
+ * Universal: every proposal route exposes resolved.proposal, so this gates every
+ * proposal (existing + new) with no per-page block or migration.
+ */
+
+import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
+import { signAccessToken, verifyAccessToken } from "./content-gate/token.ts";
+import { resolveProposalAuthorizedEmails } from "./proposal-authorized-emails.ts";
+import { injectProposalChatLauncher } from "./proposal-chat-inject.ts";
+import { propTtlMs } from "./gate-ttls.ts";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+/**
+ * Proposal gate display + behaviour, DB-driven (config/content-gate-proposal),
+ * never hardcoded. requireOtp is the per-gate OTP switch (proposals default
+ * off — email-only; agreements opt in). A missing/invalid row falls back to the
+ * proposal-appropriate defaults so the gate UI ALWAYS renders.
+ */
+interface ProposalGateSettings {
+	title: string;
+	subtitle: string;
+	submitLabel: string;
+	requireOtp: boolean;
+}
+
+const PROPOSAL_GATE_DEFAULTS: ProposalGateSettings = {
+	title: "This proposal is private",
+	subtitle: "Enter the email this proposal was shared with to view it.",
+	submitLabel: "View proposal",
+	requireOtp: false,
+};
+
+const ProposalGateSettingsSchema = v.object({
+	title: v.optional(v.string(), PROPOSAL_GATE_DEFAULTS.title),
+	subtitle: v.optional(v.string(), PROPOSAL_GATE_DEFAULTS.subtitle),
+	submitLabel: v.optional(v.string(), PROPOSAL_GATE_DEFAULTS.submitLabel),
+	requireOtp: v.optional(v.boolean(), PROPOSAL_GATE_DEFAULTS.requireOtp),
+});
+
+async function loadProposalGateSettings(): Promise<ProposalGateSettings> {
+	try {
+		return await loadRegistryConfig(
+			"config",
+			"content-gate-proposal",
+			ProposalGateSettingsSchema,
+		);
+	} catch {
+		return PROPOSAL_GATE_DEFAULTS;
+	}
+}
+
+const PROP_COOKIE = "prop_token";
+
+interface PuckHolder {
+	puck_data?: { content?: unknown[] };
+}
+
+function brandPrimaryColor(resolved: Record<string, unknown>): string {
+	const brand = resolved.brand as { primaryColor?: unknown } | undefined;
+	return typeof brand?.primaryColor === "string" ? brand.primaryColor : "";
+}
+
+function buildGateBlock(
+	proposalId: string,
+	primaryColor: string,
+	settings: ProposalGateSettings,
+) {
+	return {
+		type: "SignIn",
+		props: {
+			id: "proposal-gate",
+			mode: "gate",
+			gateContextField: "proposalId",
+			gateContextValue: proposalId,
+			gateAction: "/api/proposal-access",
+			// Display + behaviour are DB-driven (config/content-gate-proposal),
+			// not hardcoded. requireOtp is the per-gate OTP switch.
+			title: settings.title,
+			subtitle: settings.subtitle,
+			gateRequireOtp: settings.requireOtp,
+			gateSubmitLabel: settings.submitLabel,
+			primaryColor,
+			showBackToHome: false,
+		},
+	};
+}
+
+export const proposalGateConfig: ContentGateConfig = {
+	cookieName: PROP_COOKIE,
+	getResourceId(resolved) {
+		const proposal = resolved.proposal as { id?: unknown } | null | undefined;
+		return typeof proposal?.id === "string" ? proposal.id : "";
+	},
+	verifyToken(token, resourceId, nowMs) {
+		const email = verifyAccessToken(token, PROP_COOKIE, resourceId, nowMs);
+		return email ? { email } : null;
+	},
+	// Baked-in unified auth (engine default): a logged-in viewer whose session
+	// email is in this set (issuing-org team ∪ recipient ∪ partner) is released
+	// with no email/OTP entry. Just exposing the resolver opts this gate into the
+	// platform-wide behaviour — no per-gate session code.
+	resolveAuthorizedEmails: resolveProposalAuthorizedEmails,
+	async onAuthorized(resolved, _resourceId, { email }) {
+		// Seed the verified viewer identity (building-applications initialVisitor).
+		(resolved as { initialVisitor?: { email: string } }).initialVisitor = {
+			email,
+		};
+		// Inject the floating Proposal Assistant chat bubble — strictly behind the
+		// gate, so only an authorised viewer ever sees it. Content otherwise intact.
+		await injectProposalChatLauncher(resolved, email);
+	},
+	async onUnauthorized(resolved, resourceId) {
+		const settings = await loadProposalGateSettings();
+		// Replace the proposal BODY with the gate block — no proposal content
+		// reaches the HTML. Header/footer chrome stays branded.
+		const page = resolved.page as
+			| (PuckHolder & {
+					meta_title?: unknown;
+					meta_description?: unknown;
+					name?: unknown;
+			  })
+			| null
+			| undefined;
+		if (page?.puck_data && Array.isArray(page.puck_data.content)) {
+			page.puck_data.content = [
+				buildGateBlock(resourceId, brandPrimaryColor(resolved), settings),
+			];
+		}
+		// Neutralize the PAGE record's meta too: page.meta_title/meta_description
+		// feed pageData.meta → the <title>/og tags AND the __PAGE_DATA__ hydration
+		// JSON. Without this the proposal topic + partner name leak via meta even
+		// though the body is withheld (the 2026-06-13 meta-leak: a gated proposal
+		// still exposed "Webinar Campaign · in partnership with <partner>").
+		if (page) {
+			page.meta_title = "Private proposal";
+			page.meta_description = "";
+			page.name = "Private proposal";
+		}
+		// Neutralize the proposal record so the meta_context resolver + any block
+		// reading it can't leak name/partner/cover/recipient.
+		const prop = resolved.proposal as Record<string, unknown> | undefined;
+		if (prop) {
+			prop.name = "Private proposal";
+			prop.description = "";
+			prop.client_name = "";
+			prop.prepared_for = "";
+			prop.cover_image_url = "";
+		}
+	},
+};
+
+export const proposalAccessConfig: AccessConfig = {
+	path: "/api/proposal-access",
+	cookieName: PROP_COOKIE,
+	get ttlMs() {
+		return propTtlMs();
+	},
+	recordIdField: "proposalId",
+	resolveAuthorizedEmails: resolveProposalAuthorizedEmails,
+	signToken(resourceId, email, nowMs) {
+		return signAccessToken(PROP_COOKIE, resourceId, email, nowMs, propTtlMs());
+	},
+};

package/src/read-html-template.test.ts

@@ -0,0 +1,74 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Regression guard for the manifest-keyed HTML cache. The lifetime-pinned
+ * cache served a deleted bundle hash after a post-boot rebuild (scala-docs
+ * 2026-06-13): build-client-assets rewrites asset-manifest.json + deletes the
+ * old hashed bundle, but the cached HTML kept the old hash → 404 → no
+ * hydration. These tests pin that a manifest change re-substitutes the HTML.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readHtmlTemplate } from "./read-html-template.ts";
+
+let dir: string;
+let origCwd: string;
+
+function writeManifest(hydrate: string, styles: string): void {
+	writeFileSync(
+		join(dir, "dist", "client", "asset-manifest.json"),
+		`${JSON.stringify({ stylesPath: styles, hydratePath: hydrate }, null, 2)}\n`,
+	);
+}
+
+beforeEach(() => {
+	origCwd = process.cwd();
+	dir = mkdtempSync(join(tmpdir(), "read-html-template-"));
+	mkdirSync(join(dir, "src"), { recursive: true });
+	mkdirSync(join(dir, "dist", "client"), { recursive: true });
+	writeFileSync(
+		join(dir, "src", "index.html"),
+		'<link href="{{stylesPath}}"><script src="{{hydratePath}}"></script>',
+	);
+	process.chdir(dir);
+});
+
+afterEach(() => {
+	process.chdir(origCwd);
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("readHtmlTemplate manifest-keyed cache", () => {
+	test("substitutes the current manifest hashes", async () => {
+		writeManifest("/assets/hydrate-aaa.js", "/assets/styles-aaa.css");
+		const html = await readHtmlTemplate();
+		expect(html).toContain("/assets/hydrate-aaa.js");
+		expect(html).toContain("/assets/styles-aaa.css");
+	});
+
+	test("re-substitutes after a post-boot manifest change (the 404 regression)", async () => {
+		writeManifest("/assets/hydrate-old.js", "/assets/styles-old.css");
+		const first = await readHtmlTemplate();
+		expect(first).toContain("/assets/hydrate-old.js");
+
+		// Simulate build-client-assets rebuilding: new manifest, old bundle gone.
+		// mtime must advance for the stat-keyed cache to invalidate.
+		await Bun.sleep(10);
+		writeManifest("/assets/hydrate-new.js", "/assets/styles-new.css");
+
+		const second = await readHtmlTemplate();
+		expect(second).toContain("/assets/hydrate-new.js");
+		expect(second).not.toContain("/assets/hydrate-old.js");
+	});
+
+	test("falls back to fixed paths when the manifest is absent", async () => {
+		const html = await readHtmlTemplate();
+		expect(html).toContain("/assets/hydrate.js");
+		expect(html).toContain("/assets/styles.css");
+	});
+});

package/src/read-html-template.ts

@@ -0,0 +1,102 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Reads the per-service HTML template (codegen'd from
+ * `@teamscala/scala-install/src/runtime/index.html`) and substitutes the
+ * `{{stylesPath}}` / `{{hydratePath}}` placeholders with the current
+ * content-hashed asset URLs from `dist/client/asset-manifest.json`.
+ *
+ * Build-time produces hashed filenames (e.g. `styles-abc123.css`); the
+ * static-asset handler serves them with `cache-control: immutable`. New
+ * deployments emit new hashes → new URLs → browsers refetch without ever
+ * holding a stale copy. Without the substitution, a fixed
+ * `/assets/styles.css` paired with `immutable` would pin every visitor to
+ * whatever version they first downloaded.
+ *
+ * Cached per service process, keyed on the manifest's mtime. The cache MUST
+ * invalidate when `asset-manifest.json` changes: `buildClientAssets` can
+ * rebuild the bundle AFTER the first request — producing a new content hash,
+ * rewriting the manifest, AND deleting the old hashed bundle
+ * (`removeStaleHashedFiles`). A lifetime-pinned HTML cache then keeps serving
+ * the OLD hash, which now 404s → hydration never runs → the page renders SSR
+ * HTML but is dead client-side (the doc-editor overlay never mounts; scala-docs
+ * 2026-06-13, exposed by the ui-foundation publish-storm's repeated rebuilds).
+ * Re-stat'ing the tiny manifest per request is negligible (OS-cached, no
+ * network); the substituted HTML is reused while the mtime is unchanged.
+ *
+ * NO-SILENT-REVERTS: when the manifest is a TOMBSTONE (the last client build
+ * failed), the served HTML is stamped with a `<meta name="x-client-build-status"
+ * content="failed">` tag in <head> so any operator / chrome-devtools / theme
+ * probe inspecting the page can see the served bundle is STALE (a published fix
+ * that reached node_modules but failed to bundle is silently served from the
+ * prior bundle otherwise — scala-agents 2026-07-18, the white-on-white toolbar
+ * regression that looked "not fixed" while the bundle kept serving pre-fix
+ * bytes across restarts).
+ */
+
+import { readClientBuildStatus } from "./build-client-assets.ts";
+import { join } from "node:path";
+
+interface AssetManifest {
+	stylesPath: string;
+	hydratePath: string;
+}
+
+const FALLBACK: AssetManifest = {
+	stylesPath: "/assets/styles.css",
+	hydratePath: "/assets/hydrate.js",
+};
+
+let cached: { html: string; manifestMtime: number } | null = null;
+
+function manifestPath(): string {
+	return join(process.cwd(), "dist", "client", "asset-manifest.json");
+}
+
+async function manifestMtimeMs(): Promise<number> {
+	try {
+		return (await Bun.file(manifestPath()).stat()).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+
+async function loadManifest(): Promise<AssetManifest> {
+	const path = manifestPath();
+	if (await Bun.file(path).exists()) {
+		try {
+			const parsed = await Bun.file(path).json() as Partial<AssetManifest>;
+			if (parsed.stylesPath && parsed.hydratePath) {
+				return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
+			}
+		} catch {}
+	}
+	return FALLBACK;
+}
+
+export async function readHtmlTemplate(): Promise<string> {
+	const mtime = await manifestMtimeMs();
+	if (cached && cached.manifestMtime === mtime) return cached.html;
+	const templatePath = join(process.cwd(), "src", "index.html");
+	const raw = await Bun.file(templatePath).text();
+	const manifest = await loadManifest();
+	let html = raw
+		.replace(/\{\{stylesPath\}\}/g, manifest.stylesPath)
+		.replace(/\{\{hydratePath\}\}/g, manifest.hydratePath);
+	// Tombstone stamp — surfaces a failed client build at the served layer.
+	// `<meta>` in <head> is the minimum-invasive vehicle (no layout shift, no
+	// JS dependency, visible via view-source / devtools / a future status
+	// probe). `x-` prefix keeps it out of any standard meta namespace.
+	const status = await readClientBuildStatus();
+	if (status.failed) {
+		const reason = (status.reason ?? "unknown").replace(/"/g, "'").slice(0, 200);
+		const meta = `<meta name="x-client-build-status" content="failed" data-reason="${reason}" data-at="${status.at ?? ""}">`;
+		html = html.includes("</head>")
+			? html.replace("</head>", `${meta}</head>`)
+			: `${meta}${html}`;
+	}
+	cached = { html, manifestMtime: mtime };
+	return html;
+}

package/src/read-viewport-from-request.ts

@@ -0,0 +1,36 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Server-side viewport detection from request headers. Two tiers:
+ * desktop (tablets, laptops, desktops) and mobile (phones).
+ *
+ * Tablets are NOT a separate tier — CSS handles responsive layout
+ * within the desktop tier via flex min/max and @container queries.
+ * Only phones (where the layout is fundamentally single-pane) get
+ * a different server-rendered page.
+ *
+ * Order of authority:
+ * cookie → Sec-CH-UA-Mobile client hint → User-Agent regex → desktop default.
+ */
+
+export type ViewportTier = "desktop" | "mobile";
+
+const PHONE_UA_RE =
+	/iPhone|iPod|Android.*Mobile|Mobile Safari|Opera Mini|IEMobile|webOS|BlackBerry/i;
+
+export function readViewportFromRequest(request: Request): ViewportTier {
+	const cookie = request.headers.get("cookie") ?? "";
+	const cookieMatch = cookie.match(/(?:^|;\s*)viewport=(mobile|desktop)\b/);
+	if (cookieMatch?.[1] === "mobile") return "mobile";
+	if (cookieMatch?.[1] === "desktop") return "desktop";
+
+	const chMobile = request.headers.get("sec-ch-ua-mobile");
+	if (chMobile === "?1") return "mobile";
+
+	const ua = request.headers.get("user-agent") ?? "";
+	if (PHONE_UA_RE.test(ua)) return "mobile";
+
+	return "desktop";
+}

package/src/readiness-gate.ts

@@ -0,0 +1,39 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Readiness gate — returns 503 + Retry-After: 1 until the boot pipeline
+ * flips the ready flag true as its last step. Registered as the FIRST
+ * middleware in both UI and backend boot paths per readiness-gated-boot.
+ *
+ * The gate fails open: if it ever throws, the request passes through to
+ * the normal handler rather than producing a hard 500.
+ */
+
+import type { Context, Next } from "hono";
+
+let _ready = false;
+
+export function isReady(): boolean {
+	return _ready;
+}
+
+export function setReady(): void {
+	_ready = true;
+}
+
+export async function readinessGate(c: Context, next: Next): Promise<Response | void> {
+	try {
+		if (_ready) return next();
+		return c.json({ status: "starting" }, 503, { "Retry-After": "1" });
+	} catch (err) {
+		// Fail-open-NOISY (protective-layers-fail-explicitly): a thrown gate
+		// must never hard-500 (readiness-gated-boot) — it passes through to the
+		// handler — but the failure must be OBSERVABLE, not silent. Practically
+		// unreachable (the body is pure reads of module flags + c.req.path); the
+		// log surfaces a regression if it ever fires.
+		console.error("[readiness-gate] gate threw — failing open to handler", err);
+		return next();
+	}
+}