@teamscala/service-boot 0.23.284

package/src/resource-chat-inject.ts

@@ -0,0 +1,168 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Injects the generic ResourceChatLauncher block into an AUTHORISED resource
+ * page (proposal, agreement, or any gated document) — called from a gate's
+ * onAuthorized, so the floating GPT bubble lives strictly behind the email gate
+ * and every resource of that type gets it with no per-page Puck edit. It builds
+ * the resource's 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
+ * assistant agent answers about whichever resource is being viewed.
+ *
+ * RESOURCE-AGNOSTIC by design (one-ai-chat-system / chat-ui-is-one-canonical-block):
+ * the launcher, the chat engine, and this injector are generic; only the
+ * per-resource CONFIG differs (which agent, the copy, which resolved key holds
+ * the record). The agent id is config, not code (registries-are-source-of-truth):
+ * each resource type names a `config / <slug>-assistant-agent` row carrying
+ * { agentId }. No row (or no agent) → no injection, page renders unchanged
+ * (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() });
+
+/** Per-resource-type injection config — the only thing that varies. */
+export interface ResourceChatOptions {
+	/** Key in `resolved` holding the record (e.g. "proposal", "agreement"). */
+	resourceKey: string;
+	/** `config` row slug carrying { agentId } (e.g. "agreement-assistant-agent"). */
+	agentConfigSlug: string;
+	/** Org id to scope the chat. If omitted, read from resolved[resourceKey].organisation_id
+	 *  (proposals); agreements pass it explicitly (org isn't on the resolved record). */
+	organisationId?: string;
+	/** Overlay title-bar label (e.g. "Agreement Assistant"). */
+	title: string;
+	/** Floating button label / speech bubble (e.g. "Ask about this agreement"). */
+	launchLabel: string;
+	/** First assistant message. */
+	welcomeMessage?: string;
+	/** Input placeholder. */
+	placeholder?: string;
+	/** Suggested starter questions. */
+	conversationStarters?: string[];
+}
+
+/** Serialise the resource record + entire page content tree as text for the GPT. */
+async function buildResourceContext(
+	resolved: Record<string, unknown>,
+	resourceKey: string,
+): Promise<string> {
+	const record = resolved[resourceKey] as Record<string, unknown> | undefined;
+	const parts: string[] = [];
+
+	if (typeof record?.name === "string" && record.name) {
+		parts.push(`Title: ${record.name}`);
+	}
+	if (typeof record?.client_name === "string" && record.client_name) {
+		parts.push(`For: ${record.client_name}`);
+	}
+	if (typeof record?.description === "string" && record.description) {
+		parts.push(`Description: ${record.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--- Document content ---");
+		parts.push(JSON.stringify(page.content, null, 2));
+	}
+
+	// Resolve DB-backed product tiers when present (proposals) so the GPT sees
+	// real pricing. Harmless for resources with no ProductTiers blocks.
+	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 : "";
+}
+
+/**
+ * Inject the generic ResourceChatLauncher behind the gate. `opts` is the only
+ * per-resource-type variation; everything else is shared.
+ */
+export async function injectResourceChatLauncher(
+	resolved: Record<string, unknown>,
+	viewerEmail: string,
+	opts: ResourceChatOptions,
+): Promise<void> {
+	const page = (resolved.page as { puck_data?: { content?: unknown[] } } | undefined)?.puck_data;
+	if (!page || !Array.isArray(page.content)) return;
+
+	const record = resolved[opts.resourceKey] as Record<string, unknown> | undefined;
+	const organisationId =
+		opts.organisationId ||
+		(typeof record?.organisation_id === "string" ? record.organisation_id : "");
+	if (!organisationId) return;
+
+	let agentId = "";
+	try {
+		agentId = (
+			await loadRegistryConfig("config", opts.agentConfigSlug, AgentConfigSchema)
+		).agentId;
+	} catch {
+		return; // no agent configured → no bubble (fail-soft, page unchanged)
+	}
+	if (!agentId) return;
+
+	try {
+		const runtimeContext = await buildResourceContext(resolved, opts.resourceKey);
+		(page.content as Array<Record<string, unknown>>).push({
+			type: "ResourceChatLauncher",
+			props: {
+				id: `${opts.resourceKey}-chat-launcher`,
+				agentId,
+				organisationId,
+				viewerEmail,
+				runtimeContext,
+				primaryColor: brandPrimaryColor(resolved),
+				title: opts.title,
+				welcomeMessage: opts.welcomeMessage,
+				launchLabel: opts.launchLabel,
+				placeholder: opts.placeholder,
+				conversationStarters: opts.conversationStarters,
+			},
+		});
+	} catch (err) {
+		getAppLogger().error(
+			`[resource-chat] launcher injection failed (${opts.resourceKey}): ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+}

package/src/resource-not-found.ts

@@ -0,0 +1,263 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * One cohesive unit — the branded resource-not-found / holding page: the
+ * PrimaryResourceMissingError trigger, the org-logo resolver the page
+ * renders, and the HTML builder are tightly coupled (the builder consumes
+ * the logo; the error drives the page) and cannot be split without churn.
+ *
+ * Branded 404 for registry page routes whose PRIMARY resource is missing.
+ *
+ * A route that declares `resource_type` (proposal, form, quiz, agreement…)
+ * is meaningless without that entity. Before this existed, a dead link
+ * (wrong id, deleted row) fell through the loader with nulls and rendered
+ * whatever default content the shell could scrape together — leaking
+ * internal pages (the "Vision Toolbar" incident, operator-observed
+ * 2026-06-05) on the org's own branded host, with a 200 status that
+ * search engines and link unfurlers would happily cache.
+ *
+ * The replacement: loadData throws PrimaryResourceMissingError; the page
+ * binder maps it to a minimal branded 404 — correct status, noindex, the
+ * host's own favicon (which resolves the owning org per brand_org), and a
+ * plain human sentence. Deliberately NOT a puck page: the error surface
+ * must render even when data loading is the thing that failed. A
+ * website-editable /404 puck page can layer on top later; this is the
+ * floor that must always exist.
+ */
+
+import { getClient } from "@teamscala/aws/create/client/get-client";
+import { createCache } from "@teamscala/cache/create-cache";
+import { getServerClient } from "@teamscala/orpc/server-client-registry";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { toAssetPath } from "@teamscala/formatters/asset-url";
+import { brandLogoImgTag } from "@teamscala/os/brand/brand-logo-img-tag";
+import { ServiceInstallConfigSchema } from "./load-service-install-row.ts";
+
+const RESOURCE_LABELS: Record<string, string> = {
+	proposal: "proposal",
+	form: "form",
+	quiz: "quiz",
+	agreement: "agreement",
+	agent: "assistant",
+};
+
+const logoCache = createCache<string | null>("service-boot:error-page-logo", {
+	ttlMs: 5 * 60_000,
+	maxSize: 8,
+});
+
+/**
+ * The host org's LOGO (wordmark) for the dark error page — the favicon is a
+ * tab glyph, the wrong asset at page scale (operator-observed: a lone "h"
+ * where the launcha wordmark belonged). Resolution: the service's own
+ * install row names its owner (brand_org); the org's dark-theme logo (a
+ * light-coloured mark, correct on the dark page) is preferred, light-theme
+ * second. Every step skew-tolerant: any miss → null → the builder renders a
+ * logo-less dark page.
+ *
+ * Returns the logo as an INLINE data URI (not a `/api/assets/` proxy URL) so
+ * the branded holding/error page ships the logo IN the initial HTML bytes —
+ * no second fetch, no post-paint pop-in, no dependency on the asset proxy the
+ * degraded service is failing to serve (incident 2026-07-27: the logo on a
+ * DEGRADED render-layer holding page appeared after the page painted). The
+ * logo sibling of icons-render-ssr-inline. Size-capped: a pathological
+ * (>MAX_INLINE_LOGO_BYTES) logo falls back to null rather than bloating the
+ * HTML; the page renders logo-less, never broken.
+ */
+export async function resolveErrorPageLogo(
+	serviceSlug: string,
+): Promise<string | null> {
+	return logoCache.fetchOrCompute(serviceSlug, async () => {
+		try {
+			const cfg = await loadRegistryConfig(
+				"service_install",
+				serviceSlug,
+				ServiceInstallConfigSchema,
+			);
+			const org = (cfg as { brand_org?: string }).brand_org;
+			if (!org) return null;
+			const prisma = (await getServerClient()) as {
+				organisation_profile?: {
+					findFirst?: (a: unknown) => Promise<unknown>;
+				};
+			};
+			const row = (await prisma.organisation_profile?.findFirst?.({
+				where: { id: org },
+				select: {
+					company_logo_for_dark_theme: true,
+					company_logo_for_light_theme: true,
+				},
+			})) as {
+				company_logo_for_dark_theme?: string | null;
+				company_logo_for_light_theme?: string | null;
+			} | null;
+			const stored =
+				row?.company_logo_for_dark_theme ||
+				row?.company_logo_for_light_theme ||
+				null;
+			return stored ? inlineLogoAsDataUri(stored) : null;
+		} catch {
+			return null;
+		}
+	});
+}
+
+/** Above this byte size, inlining bloats the HTML more than it helps — fall
+ * back to a logo-less page. Typical org logos are 5–30 KB, so this only
+ * catches a genuinely oversized upload. */
+const MAX_INLINE_LOGO_BYTES = 100 * 1024;
+
+const ASSETS_PREFIX = "/api/assets/";
+
+/**
+ * Inline a stored logo value as a `data:<mime>;base64,…` URI by fetching its
+ * bytes from S3 (the same store `/api/assets/` proxies to). Mirrors the asset
+ * proxy's key extraction: `toAssetPath` normalises every stored form (bare
+ * key, `/api/files/`, tigris URL) to `/api/assets/<key>`, and the proxy
+ * decodes that path segment to the S3 key. Skew-tolerant: any miss → null.
+ */
+async function inlineLogoAsDataUri(
+	stored: string,
+): Promise<string | null> {
+	try {
+		const assetPath = toAssetPath(stored);
+		if (!assetPath.startsWith(ASSETS_PREFIX)) return null;
+		const key = decodeURIComponent(assetPath.slice(ASSETS_PREFIX.length));
+		const s3 = await getClient();
+		if (!s3) return null;
+		const bytes = await s3.file(key).arrayBuffer();
+		if (bytes.byteLength === 0 || bytes.byteLength > MAX_INLINE_LOGO_BYTES) {
+			return null;
+		}
+		const mime = mimeFromKey(key) ?? "image/png";
+		const base64 = Buffer.from(bytes).toString("base64");
+		return `data:${mime};base64,${base64}`;
+	} catch {
+		return null;
+	}
+}
+
+function mimeFromKey(key: string): string | null {
+	const ext = key.split(".").pop()?.toLowerCase();
+	switch (ext) {
+		case "png":
+			return "image/png";
+		case "jpg":
+		case "jpeg":
+			return "image/jpeg";
+		case "webp":
+			return "image/webp";
+		case "gif":
+			return "image/gif";
+		case "svg":
+			return "image/svg+xml";
+		case "avif":
+			return "image/avif";
+		default:
+			return null;
+	}
+}
+
+export class PrimaryResourceMissingError extends Error {
+	readonly resourceType: string;
+	// HTTP status for the holding page. 404 for a genuinely missing/invalid
+	// resource (a dead /:id link); 200 for the bare root of a UUID-driven site
+	// ("no <resource> selected") — the root is a valid landing, not an error,
+	// and kind:ui services must answer GET / with 200 (verify-prod-persistent-slot).
+	readonly httpStatus: number;
+	// A page ROW exists but has zero content blocks — a content gap, not a dead
+	// link (operator ruling 2026-07-21: "if the page is empty, it should have a
+	// Puck block that says this page is empty... and then take me home"). The
+	// floor renders the "This page is empty" surface (200) instead of the dead-
+	// link "doesn't exist" surface (404). Distinct from a dead link (no row).
+	readonly empty: boolean;
+	constructor(resourceType: string, httpStatus = 404, opts?: { empty?: boolean }) {
+		super(`primary resource "${resourceType}" not found`);
+		this.name = "PrimaryResourceMissingError";
+		this.resourceType = resourceType;
+		this.httpStatus = httpStatus;
+		this.empty = opts?.empty === true;
+	}
+}
+
+export function buildResourceNotFoundResponse(
+	resourceType: string,
+	logoUrl?: string | null,
+	status = 404,
+	// Optional 4th arg keeps the existing 3-arg call sites working while letting
+	// the page binder add a "Take me home" action (operator-requested) and the
+	// empty-page variant.
+	opts?: { homeUrl?: string; empty?: boolean },
+): Response {
+	const label = RESOURCE_LABELS[resourceType] ?? "page";
+	// Single-owner hosts show the owner's wordmark; multi-tenant hosts
+	// (no brand_org — a dead id's org is unknowable) stay platform-neutral.
+	// The helper emits the inline data-URI src with reserved width+height
+	// (logos-inline-on-branded-server-pages).
+	const logoImg = brandLogoImgTag(logoUrl, { height: 40, width: 160 });
+	// Three surfaces share this one floor (resource-not-found-is-the-root-floor):
+	//   200 root  — the BARE ROOT of a UUID-driven host ("no <resource> selected").
+	//   404 dead  — a content path with NO page row (a deleted/moved page, e.g.
+	//              /roadmap) OR a dead /:id: a link that genuinely doesn't resolve.
+	//   200 empty — a page ROW exists but has zero blocks (a content gap, not a
+	//              dead link): "This page is empty", still take-me-home.
+	const isEmpty = opts?.empty === true;
+	const isRoot = status === 200 && !isEmpty;
+	const title = isEmpty ? "Nothing here yet" : isRoot ? `No ${label} here` : "Not found";
+	const heading = isEmpty
+		? `This page is empty`
+		: isRoot
+			? `There&rsquo;s no ${label} at this link`
+			: `This ${label} doesn&rsquo;t exist`;
+	const body = isEmpty
+		? `There&rsquo;s nothing on this page yet. Head back home to keep going.`
+		: isRoot
+			? `This is where ${label}s are shared. Open the ${label} link you were
+			   sent to view it — there&rsquo;s nothing to see at the bare address.`
+			: `The page you&rsquo;re looking for may have been moved or removed, or the
+			   link may be incomplete.`;
+	// "Take me home" — operator-requested action on every not-found/empty surface.
+	// Omitted on the bare-root landing (it IS home). Defaults to the host root.
+	const homeUrl = opts?.homeUrl ?? "/";
+	const homeLink = isRoot
+		? ""
+		: `<p><a href="${homeUrl}" style="display:inline-block;margin-top:1.25rem;padding:.6rem 1.1rem;border-radius:.5rem;background:#e7e7e7;color:#0a0e1a;text-decoration:none;font-weight:600;font-size:.95rem">Take me home</a></p>`;
+	const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${title}</title>
+<link rel="icon" href="/favicon.ico">
+<style>
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center;
+         justify-content: center; background: #0a0e1a; color: #e7e7e7;
+         font-family: system-ui, sans-serif; text-align: center; }
+  main { padding: 2rem; max-width: 28rem; }
+  img  { height: 48px; width: auto; margin-bottom: 1.5rem; }
+  h1   { font-size: 1.25rem; font-weight: 600; margin: 0 0 .5rem; }
+  p    { color: #9aa0ab; line-height: 1.5; margin: 0; }
+  a:hover { opacity: .9; }
+</style>
+</head>
+<body>
+<main>
+  ${logoImg}
+  <h1>${heading}</h1>
+  <p>${body}</p>
+  ${homeLink}
+</main>
+</body>
+</html>`;
+	return new Response(html, {
+		status,
+		headers: {
+			"content-type": "text/html; charset=utf-8",
+			"cache-control": "no-store, no-transform",
+		},
+	});
+}

package/src/run-boot-hook-list.ts

@@ -0,0 +1,75 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Runs the service's boot hooks. A server_package registers a hook via
+ * ctx.registerBootHook during the mount phase; a hook registered by an
+ * INSTALLED server_package is intended to run (the package is installed
+ * because the service wants it). This therefore invokes EVERY registered
+ * hook — those declared in `service_install.boot_hooks[]` first (preserving
+ * their declared order), then any registered-but-undeclared hooks. Requiring a
+ * hook to be BOTH registered by its package AND re-declared in boot_hooks is a
+ * double-declaration footgun — it left the realtime-utils pg-notify bridge
+ * registered-but-never-invoked (boot_hooks was null), so the live-refresh
+ * relay never started (2026-06-29).
+ */
+
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
+import type { BootHookHandler, MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+
+export async function runBootHookList(
+	config: ServiceInstallConfig,
+	mountRegistry: MountRegistry,
+	serviceSlug: string,
+): Promise<void> {
+	const log = getAppLogger();
+	const ran = new Set<string>();
+	const invoke = async (
+		handlerSlug: string,
+		handler: BootHookHandler,
+	): Promise<void> => {
+		try {
+			await handler({ serviceSlug, config });
+			log.info(
+				`[scala-install:${serviceSlug}] boot_hook "${handlerSlug}" complete`,
+			);
+		} catch (err) {
+			throw new BootFatalError(
+				"run-boot-hook-list",
+				serviceSlug,
+				`boot_hook "${handlerSlug}" threw: ${err instanceof Error ? err.message : err}`,
+				err,
+			);
+		}
+	};
+
+	// Declared hooks (config.boot_hooks) in declared order — preserves ordering.
+	for (const rawHook of config.boot_hooks ?? []) {
+		const hook = rawHook as {
+			slug: string;
+			handler_slug?: string;
+			[key: string]: unknown;
+		};
+		const handlerSlug = hook.handler_slug ?? hook.slug;
+		const handler = mountRegistry.bootHooks.get(handlerSlug);
+		if (!handler) {
+			throw new BootFatalError(
+				"run-boot-hook-list",
+				serviceSlug,
+				`boot_hook "${hook.slug}" has no registered handler`,
+			);
+		}
+		await invoke(handlerSlug, handler);
+		ran.add(handlerSlug);
+	}
+
+	// Registered-but-undeclared hooks run too — a server_package registering a
+	// boot hook intends it to run when installed (see file header).
+	for (const [handlerSlug, handler] of mountRegistry.bootHooks) {
+		if (ran.has(handlerSlug)) continue;
+		await invoke(handlerSlug, handler);
+	}
+}

package/src/run-boot-hooks.ts

@@ -0,0 +1,97 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Runs service_install.boot_hooks in declaration order. A boot hook is a
+ * registry-declared, one-shot startup function that needs to execute after
+ * prisma + registry are ready but before the HTTP server starts serving.
+ * Used for custom startup logic (stale-run reconciliation, cache hydration,
+ * ALS seeding, long-running watcher start) that doesn't fit the pg-boss
+ * recurring model and is too specific to be a generic installer step.
+ *
+ * Each hook is resolved by dynamic-importing its handler_slug (or slug when
+ * handler_slug is absent) and awaiting its default export. The export must
+ * be an async function accepting a BootHookContext. Hooks are invoked in
+ * ascending order of their `order` field (default 100).
+ *
+ * Failures are fatal. The installer has no partial-boot concept: if a
+ * declared hook cannot run, the service is broken, and booting anyway would
+ * mask the regression. BootFatalError is thrown to propagate to the
+ * top-level boot-error handler.
+ */
+
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
+
+export interface BootHookContext {
+	serviceSlug: string;
+	config: ServiceInstallConfig;
+}
+
+export type BootHookHandler = (ctx: BootHookContext) => Promise<void> | void;
+
+interface BootHookEntry {
+	slug: string;
+	handler_slug?: string;
+	order: number;
+}
+
+export async function runBootHooks(
+	serviceSlug: string,
+	config: ServiceInstallConfig,
+): Promise<{ ran: string[] }> {
+	const hooks = (config.boot_hooks ?? []) as BootHookEntry[];
+	if (hooks.length === 0) {
+		return { ran: [] };
+	}
+
+	const ordered = [...hooks].sort(
+		(a, b) => (a.order ?? 100) - (b.order ?? 100),
+	);
+
+	const ran: string[] = [];
+	const ctx: BootHookContext = { serviceSlug, config };
+
+	for (const hook of ordered) {
+		const specifier = hook.handler_slug ?? hook.slug;
+		let mod: { default?: unknown };
+		try {
+			mod = await import(specifier);
+		} catch (err) {
+			throw new BootFatalError(
+				serviceSlug,
+				"boot-hooks.import",
+				`Boot hook "${hook.slug}" failed to import from "${specifier}": ` +
+					`${err instanceof Error ? err.message : err}`,
+				err,
+			);
+		}
+
+		const handler = mod.default;
+		if (typeof handler !== "function") {
+			throw new BootFatalError(
+				serviceSlug,
+				"boot-hooks.missing-default",
+				`Boot hook "${hook.slug}" module "${specifier}" has no default export or ` +
+					`the default export is not a function (got ${typeof handler}).`,
+			);
+		}
+
+		try {
+			await (handler as BootHookHandler)(ctx);
+		} catch (err) {
+			throw new BootFatalError(
+				serviceSlug,
+				"boot-hooks.execution",
+				`Boot hook "${hook.slug}" threw during execution: ` +
+					`${err instanceof Error ? err.message : err}`,
+				err,
+			);
+		}
+
+		ran.push(hook.slug);
+	}
+
+	return { ran };
+}