@teamscala/service-boot 0.23.284

package/src/mutable-app-ref.ts

@@ -0,0 +1,68 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Mutable app reference for two-phase boot. Allows swapping the Hono app
+ * atomically after building the full app in the background. The initial app
+ * is a minimal tool-only surface (ORPC, data routes) that starts serving
+ * immediately; the full app (pages, hydration) is built off-to-the-side and
+ * swapped in once complete.
+ *
+ * Thread-safety: Bun is single-threaded, so a simple module-level variable
+ * is sufficient. Atomics are not needed.
+ */
+
+import type { Hono } from "hono";
+
+let currentApp: Hono | null = null;
+let appLabel = "initial";
+
+/**
+ * Create a new mutable app reference initialized with the provided app.
+ * This should be called once at boot time.
+ */
+export function initMutableAppRef(initialApp: Hono, label: string): void {
+	currentApp = initialApp;
+	appLabel = label;
+}
+
+/**
+ * Get the current app. Throws if the ref hasn't been initialized.
+ */
+export function getApp(): Hono {
+	if (!currentApp) {
+		throw new Error("Mutable app reference not initialized");
+	}
+	return currentApp;
+}
+
+/**
+ * Get the current app label for logging.
+ */
+export function getAppLabel(): string {
+	return appLabel;
+}
+
+/**
+ * Atomically swap the app to a new instance. This is called after the
+ * full app is built in the background. Returns the previous label for logging.
+ */
+export function swapApp(newApp: Hono, newLabel: string): string {
+	const oldLabel = appLabel;
+	currentApp = newApp;
+	appLabel = newLabel;
+	return oldLabel;
+}
+
+/**
+ * Fetch handler that routes through the mutable app reference.
+ * This replaces the direct app.fetch call in the serve layer.
+ */
+export function fetchWithMutableApp(
+	req: Request,
+	server: ReturnType<typeof Bun.serve>,
+): Promise<Response> {
+	const app = getApp();
+	return Promise.resolve(app.fetch(req, { server }));
+}

package/src/page-route-shell-types.ts

@@ -0,0 +1,16 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Render mode literal shared across page route registration. The old
+ * shell-variant types (LegacyShell, PageSlugShell, RegionsShell,
+ * PublicShell, ConfigPageRoute) were removed when the Phase 2 deploy-time
+ * `service_install.page_routes[]` path was eliminated — all routing is
+ * now registry-driven `page_route` rows (Phase 1).
+ */
+
+export type RenderModeLiteral =
+	| "public"
+	| "portals"
+	| "utility";

package/src/page-server-orpc/audit-revert-router.ts

@@ -0,0 +1,102 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Audit revert procedure — re-applies an audit_trail row's changes_before to
+ * the entity via the canonical generated Prisma procedure for the entity's
+ * table: INSERT→delete the created row, UPDATE→restore the old values,
+ * DELETE→recreate from the deleted snapshot. The revert write itself fires the
+ * audit extension + DB trigger, recording a NEW forward audit_trail row —
+ * history is never edited (audit-trail-permanent; the undo is itself audited).
+ *
+ * Gated to super-admin (reverting business data is privileged). The caller
+ * must pass the audit_trail row id; the procedure resolves table + action +
+ * before-snapshot from that row.
+ */
+
+import { os } from "@orpc/server";
+import type { PrismaClient } from "@teamscala/db/client";
+import * as v from "valibot";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+
+const procedure = os;
+
+type C = {
+	prisma?: unknown;
+	user?: { id?: string; isSuperAdmin?: boolean } | null;
+};
+
+function getPrisma(context: unknown) {
+	const db = (context as C).prisma;
+	if (!db) throw new Error("auditRevert: context.prisma is required");
+	return db as PrismaClient;
+}
+
+const revertInput = v.object({
+	auditTrailId: v.string(),
+});
+
+export const auditRevertRouter = {
+	/**
+	 * Revert a single audited change by re-applying changes_before through the
+	 * generated Prisma model for the entity's table. Returns the action taken.
+	 */
+	revert: procedure.input(revertInput).handler(async ({ context, input }) => {
+		const user = (context as C).user;
+		if (!user?.isSuperAdmin) {
+			throw new Error("auditRevert: requires super-admin");
+		}
+		const prisma = getPrisma(context) as unknown as Record<string, any>;
+		const log = getAppLogger();
+		const { auditTrailId } = input;
+
+		const row = await prisma.audit_trail.findUnique({
+			where: { id: auditTrailId },
+			select: {
+				entity_type: true,
+				entity_id: true,
+				action: true,
+				changes_before: true,
+				changes_after: true,
+			},
+		});
+		if (!row) {
+			throw new Error(`auditRevert: audit_trail ${auditTrailId} not found`);
+		}
+
+		const table = String(row.entity_type);
+		const model = prisma[table];
+		if (!model || typeof model.delete !== "function") {
+			throw new Error(`auditRevert: table ${table} has no generated Prisma model`);
+		}
+		const entityId = String(row.entity_id ?? "");
+		const act = String(row.action ?? "").toUpperCase();
+		// changes_before is Json? — Prisma returns it parsed.
+		const before = (row.changes_before ?? null) as Record<string, unknown> | null;
+
+		let result: unknown;
+		if (act === "INSERT" || act === "CREATE") {
+			// Entity was created → revert = delete it.
+			if (!entityId) throw new Error("auditRevert INSERT: no entity_id");
+			result = await model.delete({ where: { id: entityId } });
+		} else if (act === "UPDATE") {
+			// Entity was updated → revert = restore changes_before (old values).
+			if (!before) throw new Error("auditRevert UPDATE: no changes_before to restore");
+			result = await model.update({ where: { id: entityId }, data: before });
+		} else if (act === "DELETE") {
+			// Entity was deleted → revert = recreate from changes_before.
+			if (!before) throw new Error("auditRevert DELETE: no changes_before to recreate");
+			result = await model.create({ data: before });
+		} else {
+			throw new Error(`auditRevert: unsupported action ${act}`);
+		}
+
+		log.info(
+			`[auditRevert] ${act} ${table} ${entityId} reverted by ${user.id}`,
+		);
+		return { success: true as const, action: act, table, entityId };
+	}),
+};
+
+export type AuditRevertRouter = typeof auditRevertRouter;

package/src/page-server-orpc/hub-mcp-client.ts

@@ -0,0 +1,20 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Module-level singleton for the hub MCP client. setHubMcpClient(client)
+ * is called once at boot by the host service after creating the multi-
+ * tenant MCP client; createPageHandler's resolve-page-state reads it via
+ * getHubMcpClient to pass through to data loaders.
+ */
+
+let _hubMcpClient: unknown | null = null;
+
+export function setHubMcpClient(client: unknown): void {
+	_hubMcpClient = client;
+}
+
+export function getHubMcpClient(): unknown | undefined {
+	return _hubMcpClient ?? undefined;
+}

package/src/page-server-orpc/portal-diagnostics-router.ts

@@ -0,0 +1,170 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for portal diagnostics. These replace direct Prisma calls
+ * in the portal diagnostic section files with proper ORPC procedures that
+ * receive context.prisma from the router.
+ */
+
+import { os } from "@orpc/server";
+import { BlockSchemaConfigSchema } from "@teamscala/db-validation/registry-schemas/block-schema";
+import { loadRegistryConfigsByType } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+const procedure = os;
+
+const PortalWebsiteSchema = v.object({
+	id: v.string(),
+	name: v.string(),
+	organisation_id: v.nullable(v.string()),
+});
+
+const MemberSchema = v.object({
+	user_id: v.string(),
+});
+
+const PageRowSchema = v.object({
+	id: v.string(),
+	path: v.nullable(v.string()),
+	name: v.string(),
+	puck_data: v.unknown(),
+	updated_at: v.string(),
+});
+
+const BlockSchemaSlugSchema = v.object({
+	slug: v.string(),
+});
+
+export const portalDiagRouter = {
+	findPortalWebsite: procedure
+		.input(v.object({}))
+		.output(v.nullable(PortalWebsiteSchema))
+		.handler(async ({ context }) => {
+			const db = (context as { prisma?: unknown }).prisma;
+			if (!db)
+				throw new Error("portalDiag.findPortalWebsite requires context.prisma");
+
+			return (await (
+				db as {
+					builda_websites: { findFirst: (args: unknown) => Promise<unknown> };
+				}
+			).builda_websites.findFirst({
+				where: { website_type: "portal" },
+				select: { id: true, name: true, organisation_id: true },
+				orderBy: { updated_at: "desc" },
+			})) as {
+				id: string;
+				name: string;
+				organisation_id: string | null;
+			} | null;
+		}),
+
+	findMember: procedure
+		.input(v.object({ organisationId: v.string() }))
+		.output(v.nullable(MemberSchema))
+		.handler(async ({ input, context }) => {
+			const db = (context as { prisma?: unknown }).prisma;
+			if (!db) throw new Error("portalDiag.findMember requires context.prisma");
+
+			return (await (
+				db as {
+					better_auth_member: {
+						findFirst: (args: unknown) => Promise<unknown>;
+					};
+				}
+			).better_auth_member.findFirst({
+				where: { organization_id: input.organisationId },
+				select: { user_id: true },
+			})) as { user_id: string } | null;
+		}),
+
+	countPages: procedure
+		.input(v.object({ websiteId: v.string() }))
+		.output(v.number())
+		.handler(async ({ input, context }) => {
+			const db = (context as { prisma?: unknown }).prisma;
+			if (!db) throw new Error("portalDiag.countPages requires context.prisma");
+
+			return await (
+				db as { builda_pages: { count: (args: unknown) => Promise<number> } }
+			).builda_pages.count({
+				where: { website_id: input.websiteId },
+			});
+		}),
+
+	findPages: procedure
+		.input(
+			v.object({
+				websiteId: v.string(),
+				path: v.optional(v.string()),
+				take: v.optional(v.number()),
+				orderBy: v.optional(v.string()),
+			}),
+		)
+		.output(v.array(PageRowSchema))
+		.handler(async ({ input, context }) => {
+			const db = (context as { prisma?: unknown }).prisma;
+			if (!db) throw new Error("portalDiag.findPages requires context.prisma");
+
+			const where: Record<string, unknown> = { website_id: input.websiteId };
+			if (input.path) where.path = input.path;
+
+			return (await (
+				db as {
+					builda_pages: { findMany: (args: unknown) => Promise<unknown[]> };
+				}
+			).builda_pages.findMany({
+				where,
+				select: {
+					id: true,
+					path: true,
+					name: true,
+					puck_data: true,
+					updated_at: true,
+				},
+				take: input.take,
+				orderBy: input.orderBy ? { [input.orderBy]: "desc" } : undefined,
+			})) as Array<{
+				id: string;
+				path: string | null;
+				name: string;
+				puck_data: unknown;
+				updated_at: string;
+			}>;
+		}),
+
+	findBlockSchemas: procedure
+		.input(v.object({ slugs: v.array(v.string()) }))
+		.output(v.array(BlockSchemaSlugSchema))
+		.handler(async ({ input }) => {
+			const all = await loadRegistryConfigsByType(
+				"block_schema",
+				BlockSchemaConfigSchema,
+			);
+			return all
+				.filter((r) => input.slugs.includes(r.slug))
+				.map((r) => ({ slug: r.slug }));
+		}),
+
+	findWebsites: procedure
+		.input(v.object({ take: v.optional(v.number()) }))
+		.output(v.array(v.object({ id: v.string(), name: v.string() })))
+		.handler(async ({ input, context }) => {
+			const db = (context as { prisma?: unknown }).prisma;
+			if (!db)
+				throw new Error("portalDiag.findWebsites requires context.prisma");
+
+			return (await (
+				db as {
+					builda_websites: { findMany: (args: unknown) => Promise<unknown[]> };
+				}
+			).builda_websites.findMany({
+				select: { id: true, name: true },
+				take: input.take ?? 10,
+			})) as Array<{ id: string; name: string }>;
+		}),
+};
+
+export type PortalDiagRouter = typeof portalDiagRouter;

package/src/page-server-orpc/puck-pages-router.ts

@@ -0,0 +1,272 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for loading Puck pages. These replace the direct Prisma calls
+ * in load-puck-page-by-slug.ts with proper ORPC procedures that receive
+ * context.prisma from the router.
+ */
+
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import { createCache } from "@teamscala/cache/create-cache";
+
+const procedure = os;
+
+const _WebsiteShellSettingsSchema = v.object({
+	website_type: v.nullable(v.string()),
+	layout_settings: v.nullable(v.record(v.string(), v.unknown())),
+	header_settings: v.nullable(v.record(v.string(), v.unknown())),
+	footer_settings: v.nullable(v.record(v.string(), v.unknown())),
+});
+
+const PuckPageRowSchema = v.object({
+	id: v.string(),
+	path: v.nullable(v.string()),
+	puckData: v.unknown(),
+	mode: v.nullable(v.string()),
+	render_mode: v.nullable(v.string()),
+	website_slug: v.string(),
+	organisation_id: v.nullable(v.string()),
+	meta_title: v.nullable(v.string()),
+	meta_description: v.nullable(v.string()),
+	website: v.object({
+		slug: v.string(),
+		name: v.string(),
+		organisation_id: v.nullable(v.string()),
+		website_type: v.nullable(v.string()),
+		layout_settings: v.nullable(v.record(v.string(), v.unknown())),
+		header_settings: v.nullable(v.record(v.string(), v.unknown())),
+		footer_settings: v.nullable(v.record(v.string(), v.unknown())),
+	}),
+});
+
+type PuckPageRow = v.InferOutput<typeof PuckPageRowSchema>;
+
+/**
+ * Right-panel / region pages (AI chat, audit, comments, …) are STATIC website
+ * config — one page row + its website row, no per-user data — so they are safe
+ * to cache across users keyed by website + path. Each cold open otherwise pays
+ * TWO dependent cross-internet DB round-trips (~230ms each against the dev host's
+ * proxied Railway Postgres); caching makes a repeat panel open near-instant.
+ * SWR: fresh 60s, stale-served up to 5min while ONE background refresh runs
+ * (stampede-safe), so a page edit appears within the window without every open
+ * re-querying. No user identity in the key or value — no cross-user leak.
+ */
+const pageCache = createCache<PuckPageRow | null>(
+	"page-server:load-from-website",
+	{ ttlMs: 60_000, staleTtlMs: 5 * 60_000, maxSize: 200, stampedeProtection: true },
+);
+
+export const puckPagesRouter = {
+	loadFromWebsite: procedure
+		.input(v.object({ websiteSlug: v.string(), path: v.string() }))
+		.output(v.nullable(PuckPageRowSchema))
+		.handler(async ({ input, context }) => {
+			const db = (context as { prisma?: unknown }).prisma;
+			if (!db)
+				throw new Error("puckPages.loadFromWebsite requires context.prisma");
+
+			// Normalize the path: builda_pages stores paths WITH a leading slash
+			// ('/chat', '/audit', …), but a panel_view.page_slug + a region
+			// `?right=`/`?panel=` slug conventionally OMIT it ('chat', 'audit').
+			// The SSR panel resolver (resolve-page-puck-data.ts) already prepends
+			// '/' (`/${activePanel}`); match that contract here so a client-side
+			// panel/region load by slug resolves the SAME row a deep-link SSR does.
+			// Without this, regions.loadPage({ path: "chat" }) queried
+			// `WHERE path = 'chat'` → no match → null → the panel dock opened blank
+			// (portal Chat/Audit/Notifications/Utility + the fleet-dashboard region
+			// swap — any page-kind panel opened by click rather than deep link).
+			const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
+
+			return pageCache.fetchOrCompute(
+				`${input.websiteSlug}::${path}`,
+				async () => {
+			const site = (await (
+				db as {
+					builda_websites: { findFirst: (args: unknown) => Promise<unknown> };
+				}
+			).builda_websites.findFirst({
+				// websiteSlug may be a website SLUG or a website ID. The Utility shell
+				// carries the serving website's id (loaderData.*.website_id) but not its
+				// slug, so its region panels pass the id; UUIDs and kebab slugs cannot
+				// collide, so OR-matching both is unambiguous.
+				where: {
+					OR: [{ slug: input.websiteSlug }, { id: input.websiteSlug }],
+					status: { not: "archived" },
+				},
+				select: {
+					id: true,
+					name: true,
+					slug: true,
+					organisation_id: true,
+					website_type: true,
+					layout_settings: true,
+					header_settings: true,
+					footer_settings: true,
+				},
+			})) as {
+				id: string;
+				name: string;
+				slug: string;
+				organisation_id: string | null;
+				website_type: string | null;
+				layout_settings: Record<string, unknown> | null;
+				header_settings: Record<string, unknown> | null;
+				footer_settings: Record<string, unknown> | null;
+			} | null;
+
+			if (!site) return null;
+
+			const row = (await (
+				db as {
+					builda_pages: { findFirst: (args: unknown) => Promise<unknown> };
+				}
+			).builda_pages.findFirst({
+				where: { path, is_active: true, website_id: site.id },
+				select: {
+					id: true,
+					path: true,
+					puck_data: true,
+					meta_title: true,
+					meta_description: true,
+				},
+			})) as {
+				id: string;
+				path: string | null;
+				puck_data: unknown;
+				meta_title: string | null;
+				meta_description: string | null;
+			} | null;
+
+			if (!row) return null;
+
+			return {
+				id: row.id,
+				path: row.path,
+				puckData: row.puck_data,
+				mode: null,
+				render_mode: null,
+				website_slug: site.slug,
+				organisation_id: site.organisation_id,
+				meta_title: row.meta_title,
+				meta_description: row.meta_description,
+				website: {
+					slug: site.slug,
+					name: site.name,
+					organisation_id: site.organisation_id,
+					website_type: site.website_type,
+					layout_settings: site.layout_settings,
+					header_settings: site.header_settings,
+					footer_settings: site.footer_settings,
+				},
+			};
+			});
+		}),
+
+	loadById: procedure
+		.input(v.object({ pageId: v.string() }))
+		.output(v.nullable(PuckPageRowSchema))
+		.handler(async ({ input, context }) => {
+			const db = (context as { prisma?: unknown }).prisma;
+			if (!db) throw new Error("puckPages.loadById requires context.prisma");
+
+			console.log("[DEBUG-loadById] pageId:", input.pageId);
+
+			const row = (await (
+				db as {
+					builda_pages: { findFirst: (args: unknown) => Promise<unknown> };
+				}
+			).builda_pages.findFirst({
+				where: { id: input.pageId, is_active: true },
+				select: {
+					id: true,
+					path: true,
+					puck_data: true,
+					website_id: true,
+					meta_title: true,
+					meta_description: true,
+				},
+			})) as {
+				id: string;
+				path: string | null;
+				puck_data: unknown;
+				website_id: string;
+				meta_title: string | null;
+				meta_description: string | null;
+			} | null;
+
+			if (!row) {
+				console.log("[DEBUG-loadById] NO ROW for pageId:", input.pageId);
+				return null;
+			}
+
+			const pd = row.puck_data as { content?: Array<{ type?: string }> } | null;
+			const types = pd?.content?.map((c) => c.type) ?? [];
+			console.log(
+				"[DEBUG-loadById] row found, content types:",
+				JSON.stringify(types),
+			);
+
+			const site = (await (
+				db as {
+					builda_websites: { findFirst: (args: unknown) => Promise<unknown> };
+				}
+			).builda_websites.findFirst({
+				where: { id: row.website_id, status: { not: "archived" } },
+				select: {
+					id: true,
+					name: true,
+					slug: true,
+					organisation_id: true,
+					website_type: true,
+					layout_settings: true,
+					header_settings: true,
+					footer_settings: true,
+				},
+			})) as {
+				id: string;
+				name: string;
+				slug: string;
+				organisation_id: string | null;
+				website_type: string | null;
+				layout_settings: Record<string, unknown> | null;
+				header_settings: Record<string, unknown> | null;
+				footer_settings: Record<string, unknown> | null;
+			} | null;
+
+			return {
+				id: row.id,
+				path: row.path,
+				puckData: row.puck_data,
+				mode: null,
+				render_mode: null,
+				website_slug: site?.slug ?? "",
+				organisation_id: site?.organisation_id ?? null,
+				meta_title: row.meta_title,
+				meta_description: row.meta_description,
+				website: site
+					? {
+							slug: site.slug,
+							name: site.name,
+							organisation_id: site.organisation_id,
+							website_type: site.website_type,
+							layout_settings: site.layout_settings,
+							header_settings: site.header_settings,
+							footer_settings: site.footer_settings,
+						}
+					: {
+							slug: "",
+							name: "",
+							organisation_id: null,
+							website_type: null,
+							layout_settings: null,
+							header_settings: null,
+							footer_settings: null,
+						},
+			};
+		}),
+};
+
+export type PuckPagesRouter = typeof puckPagesRouter;

package/src/page-server-orpc/server-client.ts

@@ -0,0 +1,31 @@
+/**
+ * @system page-server
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Server-side ORPC client for in-process direct invocation, per the canonical
+ * Vite/Next/Nuxt SSR pattern documented at https://orpc.dev/docs/best-practices/optimize-ssr
+ *
+ * The host service (scala-install) must call `setServerClient(client)` once
+ * at boot, after createRouterClient(appRouter, { context: { prisma } }).
+ * Then page-server's createPageHandler reads `getServerClient()` per request
+ * — no HTTP loopback, just a typed function call.
+ */
+
+import { createRouterClient, os } from "@orpc/server";
+
+const emptyRouter = {};
+
+let serverClient: ReturnType<typeof createRouterClient> | null = null;
+
+export function getServerClient(): ReturnType<typeof createRouterClient> {
+	if (serverClient) return serverClient;
+	serverClient = createRouterClient(emptyRouter, { context: {} });
+	return serverClient;
+}
+
+export function setServerClient(
+	client: ReturnType<typeof createRouterClient>,
+): void {
+	serverClient = client;
+}