@teamscala/service-boot 0.23.284

package/src/register-static-assets.ts

@@ -0,0 +1,180 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Routes every service exposes regardless of registry config: /health
+ * (liveness probe), /favicon.svg (default brand mark), /api/assets/*
+ * (S3 asset proxy), and /assets/* (client bundle + stylesheet produced
+ * by build-client-assets.ts into dist/client/, served identically in
+ * dev and prod per scala-os/ui.md `bun-build-only`).
+ */
+
+import { join } from "node:path";
+import type { Hono } from "hono";
+import { etag } from "hono/etag";
+import { buildErrorReport } from "@teamscala/os/errors/error-report";
+import { handleAssetProxy } from "./asset-proxy";
+import { resolveBrandFaviconPath, warmBrandFaviconCache } from "./resolve-brand-favicon";
+
+const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#6366f1"/><text x="16" y="23" text-anchor="middle" font-size="20" font-family="system-ui" fill="white">S</text></svg>`;
+
+export async function registerStaticAssets(
+	app: Hono,
+	serviceSlug: string,
+	brandOrg?: string,
+): Promise<void> {
+	// Warm the brand-favicon cache at boot — the S3 existence probe is a 6-21s
+	// cold call that otherwise stalls the first /favicon.ico after every
+	// restart. Fire-and-forget; never blocks boot or a request.
+	warmBrandFaviconCache(brandOrg);
+
+	app.get("/health", (c) =>
+		c.json({
+			status: "ok",
+			service: serviceSlug,
+			timestamp: new Date().toISOString(),
+		}),
+	);
+
+	// Localhost-gated heap-attribution probe — restores the object-composition
+	// data the removed /_healthz surface exposed: the heapSize-vs-RSS split
+	// (JS heap vs native — OTel/Prisma-engine/buffers/compiled code) plus the
+	// top object types by count. Read-only, no secrets; gated to a localhost
+	// Host so it never answers over the public domain. Registered here (before
+	// auth + page routes) so it is reachable on every service kind, like
+	// /health (`verify-via-127.0.0.1`, sibling of `runtime-metrics-via-railway-cli`).
+	app.get("/_heap", async (c) => {
+		const host = c.req.header("host") ?? "";
+		const isLocal =
+			host.startsWith("127.0.0.1") || host.startsWith("localhost") || host.startsWith("[::1]");
+		if (!isLocal) return c.json({ error: "localhost only" }, 403);
+		try {
+			const { heapStats } = await import("bun:jsc");
+			const s = heapStats() as unknown as {
+				heapSize: number;
+				heapCapacity: number;
+				objectCount: number;
+				objectTypeCounts?: Record<string, number>;
+			};
+			const rss = process.memoryUsage.rss();
+			const topObjectTypes = Object.fromEntries(
+				Object.entries(s.objectTypeCounts ?? {})
+					.sort((a, b) => b[1] - a[1])
+					.slice(0, 40),
+			);
+			return c.json({
+				service: serviceSlug,
+				rss,
+				heapSize: s.heapSize,
+				heapCapacity: s.heapCapacity,
+				objectCount: s.objectCount,
+				nativeApprox: Math.max(0, rss - s.heapSize),
+				topObjectTypes,
+			});
+		} catch (err) {
+			const report = buildErrorReport(err, { service: serviceSlug, url: c.req.url });
+			return new Response(JSON.stringify(report.http.body), {
+				status: report.http.status,
+				headers: report.http.headers,
+			});
+		}
+	});
+
+	// Build-id: the content hash of the CURRENT client bundle, read FRESH from
+	// the asset manifest on every call (never a process-pinned copy) so a
+	// post-restart rebuild reports its new id immediately. The client self-heal
+	// (page-client/boot/build-self-heal) polls this on tab refocus; if it differs
+	// from the build the tab booted with, a new build shipped and the open tab is
+	// stale → it reloads. no-store HTML + immutable hashed assets already prevent
+	// staleness on every FRESH load; this is what closes the one remaining hole —
+	// a tab left OPEN across a deploy, holding old HTML pinned to old asset
+	// hashes, with nothing telling it to re-fetch (the "my tablet still shows the
+	// old broken page" class). The id derives from hydratePath exactly as the
+	// SSR-stamped window.__SCALA_BUILD__ does (render-page-html), so they can
+	// never structurally disagree and trigger a reload loop.
+	app.get("/api/build-id", async (c) => {
+		const path = join(process.cwd(), "dist", "client", "asset-manifest.json");
+		let build = "dev";
+		try {
+			const raw = await Bun.file(path).text();
+			const manifest = JSON.parse(raw) as { hydratePath?: string };
+			build = /hydrate-([a-z0-9]+)\.js/.exec(manifest.hydratePath ?? "")?.[1] ?? "dev";
+		} catch {}
+		return c.json({ build }, 200, { "cache-control": "no-store" });
+	});
+
+	// A branded host (service_install.config.brand_org) never serves the
+	// generic platform mark — both favicon paths resolve the owning org's
+	// icon from its asset store; the generic SVG remains only for hosts
+	// with no declared owner (multi-tenant / infra).
+	app.get("/favicon.svg", async (_c) => {
+		const brand = await resolveBrandFaviconPath(brandOrg);
+		if (brand)
+			return new Response(null, {
+				status: 302,
+				headers: { location: brand, "cache-control": "public, max-age=300" },
+			});
+		return new Response(FAVICON_SVG, {
+			headers: {
+				"content-type": "image/svg+xml",
+				"cache-control": "public, max-age=3600",
+			},
+		});
+	});
+
+	app.get("/favicon.ico", async (c) => {
+		const brand = await resolveBrandFaviconPath(brandOrg);
+		// 302 (not 301): the brand asset is row-driven and must stay
+		// re-resolvable — a permanent redirect would pin stale targets in
+		// browser caches, the exact failure this route exists to end.
+		// cache-control lets the browser cache the redirect (5min) so it
+		// doesn't re-hit the origin per page load — mirrors /favicon.svg.
+		c.header("cache-control", "public, max-age=300");
+		return c.redirect(brand ?? "/favicon.svg", 302);
+	});
+
+	// Same-origin S3 asset proxy: /api/assets/<key> → bucket. Public,
+	// immutable cache, no auth. Canonical URL form for every logo, favicon,
+	// avatar, uploaded asset — emitted by toAssetPath() in @teamscala/core-ui/theme.
+	app.get("/api/assets/*", (c) => handleAssetProxy(c.req.raw));
+
+	app.use("/assets/*", etag());
+
+	app.get("/assets/*", async (c) => {
+		const distPath = join(
+			process.cwd(),
+			"dist",
+			"client",
+			c.req.path.replace(/^\/assets\//, ""),
+		);
+		const file = Bun.file(distPath);
+		if (await file.exists()) {
+			return new Response(file, {
+				headers: { "cache-control": "public, max-age=31536000, immutable" },
+			});
+		}
+		return c.notFound();
+	});
+
+	// Extension auto-update files (.crx + updates.xml) served from ./ext/.
+	// Chrome's extension updater fetches updates.xml over plain HTTPS with no
+	// auth, so this route is registered before any auth gate and on every UI
+	// service. Files are served with short-lived cache so updates propagate
+	// promptly. The ./ext/ directory is gitignored and populated by the
+	// extension build pipeline.
+	app.get("/ext/*", async (c) => {
+		const filePath = join(
+			process.cwd(),
+			"ext",
+			c.req.path.replace(/^\/ext\//, ""),
+		);
+		const file = Bun.file(filePath);
+		if (await file.exists()) {
+			return new Response(file, {
+				headers: { "cache-control": "public, max-age=3600" },
+			});
+		}
+		return c.notFound();
+	});
+}

package/src/register-ws-routes.ts

@@ -0,0 +1,180 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Registers each `service_install.websocket_routes[]` entry as a Hono WS route.
+ * The ORPC WS (`/api/rpc/ws`) is mounted by the canonical primitive
+ * `mountOrpcWs` (@teamscala/orpc/ws/server) over the FULLY-COMPOSED app router —
+ * this runs AFTER registerFnRouters, so the eager RPCHandler snapshots every
+ * namespace, and any `output: eventIterator(...)` procedure dispatches (rule
+ * `orpc-ws-via-mount-orpc-ws`). It is NOT a server_package WsRouteHandler — it
+ * is exempt from the legacy invariant below.
+ *
+ * The legacy `WsRouteHandler` interface (open/message/close on a Bun
+ * ServerWebSocket) is preserved by an adapter for already-migrated
+ * server_packages (terminal-ws); new WS handlers should use Hono's WSEvents
+ * directly.
+ *
+ * INVARIANT (legacy paths only): every handler registered via
+ * mountCtx.registerWsRoute MUST have a matching entry in config.websocket_routes
+ * (minus /api/rpc/ws), and vice versa. A mismatch is fatal — the service cannot
+ * boot with handlers declared but never wired (silent 404 on upgrade), or routes
+ * that point at handlers no server_package registered.
+ */
+
+import { getAppRouter } from "@teamscala/orpc/app-router";
+import { mountOrpcWs } from "@teamscala/orpc/ws/server";
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { BootFatalError } from "@teamscala/os/errors/boot-error";
+import type {
+	MountRegistry,
+	WsRouteHandler,
+} from "@teamscala/os/runtime-contracts/mount-context";
+import type { Context, Hono } from "hono";
+import * as v from "valibot";
+import { upgradeWebSocket } from "./serve/serve.ts";
+
+const ORPC_WS_PATH = "/api/rpc/ws";
+
+export async function registerWsRoutes(
+	app: Hono,
+	config: ServiceInstallConfig,
+	mountRegistry: MountRegistry,
+	serviceSlug: string,
+): Promise<number> {
+	const log = getAppLogger();
+	const allDeclared = new Set(
+		(config.websocket_routes ?? []).map((r) => (r as { path: string }).path),
+	);
+
+	// ORPC WS: mounted by mountOrpcWs over the app router. Not a legacy
+	// server_package handler — exempt from the invariant + the count below.
+	if (allDeclared.has(ORPC_WS_PATH)) {
+		const router = await getAppRouter();
+		// WS keepalive cadence is an operational tunable sourced from the
+		// registry (configured-primitives + operator ruling "move stuff out of
+		// code") — changing it is a registry_edit on config/orpc-ws, never a
+		// republish of @teamscala/orpc. Missing/empty row falls back to the
+		// primitive's default interval.
+		const wsCfg = await loadOrpcWsConfig(log, serviceSlug);
+		// Casts: mountOrpcWs's hand-rolled UpgradeWebSocket/Router types can't
+		// exactly mirror the injected hono upgradeWebSocket + getAppRouter's
+		// AppRouter at this configured-primitive boundary (mirroring would need
+		// importing hono/bun, unpairing createBunWebSocket). orpc type cleanup is
+		// a follow-up; the runtime shapes are correct.
+		mountOrpcWs(app, router as never, upgradeWebSocket as never, {
+			path: ORPC_WS_PATH,
+			pingIntervalMs: wsCfg.pingIntervalMs,
+		});
+		log.info(
+			`[scala-install:${serviceSlug}] /api/rpc/ws mounted via mountOrpcWs (${Object.keys(router).length} router keys)`,
+		);
+	}
+
+	// Legacy declared paths (every non-ORPC route): require a server_package
+	// WsRouteHandler + wire via the adapter.
+	const legacyPaths = [...allDeclared].filter((p) => p !== ORPC_WS_PATH);
+	for (const path of legacyPaths) {
+		const handler = mountRegistry.wsRoutes.get(path);
+		if (!handler) {
+			throw new BootFatalError(
+				"register-ws-routes",
+				serviceSlug,
+				`websocket_route "${path}" declared in service_install but no server_package registered a handler for it. ` +
+					`Either remove the route declaration or add a server_package that calls ctx.registerWsRoute("${path}", handler).`,
+			);
+		}
+		app.get(path, adaptLegacyWsHandler(handler, path));
+	}
+
+	// Unwired: handlers registered by a server_package for a path NOT declared
+	// in config.websocket_routes. (/api/rpc/ws is never registered by a
+	// server_package — it is mounted by mountOrpcWs above.)
+	const unwired = [...mountRegistry.wsRoutes.keys()].filter(
+		(p) => !allDeclared.has(p),
+	);
+	if (unwired.length > 0) {
+		throw new BootFatalError(
+			"register-ws-routes",
+			serviceSlug,
+			`server_package(s) registered WS handler(s) for path(s) not declared in config.websocket_routes: [${unwired.map((p) => `"${p}"`).join(", ")}]. ` +
+				`These handlers would never receive upgrades. Add the missing path(s) to service_install.websocket_routes or remove the registration.`,
+		);
+	}
+
+	const count = allDeclared.size;
+	log.info(
+		`[scala-install:${serviceSlug}] ${count} WS route(s) registered, 0 unwired handler(s)`,
+	);
+	return count;
+}
+
+function adaptLegacyWsHandler(legacy: WsRouteHandler, pattern: string) {
+	return upgradeWebSocket((c: Context) => {
+		const params = c.req.param() as Record<string, string>;
+		const upgradeReq = c.req.raw;
+		let extraData: Record<string, unknown> = {};
+		return {
+			async onOpen(_evt: Event, wsc: { raw?: unknown }) {
+				const ws = wsc.raw as never as { data: Record<string, unknown> };
+				if (legacy.upgradeData) {
+					extraData = await legacy.upgradeData(upgradeReq, params);
+				}
+				ws.data = { ...ws.data, route: pattern, params, ...extraData };
+				await legacy.open?.(ws as never);
+			},
+			async onMessage(
+				evt: MessageEvent<string | ArrayBuffer>,
+				wsc: { raw?: unknown },
+			) {
+				const ws = wsc.raw as never;
+				const msg =
+					typeof evt.data === "string"
+						? evt.data
+						: Buffer.from(evt.data as ArrayBuffer);
+				await legacy.message?.(ws, msg);
+			},
+			async onClose(evt: CloseEvent, wsc: { raw?: unknown }) {
+				const ws = wsc.raw as never;
+				await legacy.close?.(ws, evt.code, evt.reason);
+			},
+		} as Parameters<typeof upgradeWebSocket>[0] extends (
+			c: infer _Context,
+		) => infer R
+			? R
+			: never;
+	});
+}
+
+/**
+ * WS keepalive tunable, sourced from the `config/orpc-ws` registry row so the
+ * cadence is a `registry_edit` — never a republish of `@teamscala/orpc`
+ * (`configured-primitives` + operator ruling "move stuff out of code"). Loose
+ * schema: an absent `pingIntervalMs` (or a missing row on a fresh install)
+ * returns `{}`, and `mountOrpcWs` then falls back to its built-in default
+ * interval, so a misconfigured/missing row never fatals the WS mount.
+ */
+const orpcWsConfigSchema = v.looseObject({
+	pingIntervalMs: v.optional(v.number()),
+});
+
+async function loadOrpcWsConfig(
+	log: { info(msg: string): void; warn(msg: string): void },
+	serviceSlug: string,
+): Promise<{ pingIntervalMs?: number }> {
+	try {
+		return (await loadRegistryConfig(
+			"config",
+			"orpc-ws",
+			orpcWsConfigSchema,
+		)) as { pingIntervalMs?: number };
+	} catch (err) {
+		log.warn(
+			`[scala-install:${serviceSlug}] config/orpc-ws not readable (${err instanceof Error ? err.message : String(err)}); /api/rpc/ws keepalive using the primitive default interval`,
+		);
+		return {};
+	}
+}

package/src/resolve-app-base-url.ts

@@ -0,0 +1,28 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The scala-projects app's own public hostname, read from its `service_install`
+ * row rather than hardcoded — a service knows its own deploy config only
+ * through the registry (registries-are-source-of-truth), never a literal in
+ * source. Cached for the process lifetime: this changes only on a redeploy,
+ * not per-request. Shared by every server-side path that builds a link back
+ * into the app (approval emails, mention emails, digest emails).
+ */
+
+import { ServiceInstallConfigSchema } from "@teamscala/db-validation/registry-schemas/service-install";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+
+let cachedAppUrl: string | null = null;
+
+export async function resolveAppBaseUrl(): Promise<string> {
+	if (cachedAppUrl) return cachedAppUrl;
+	try {
+		const config = await loadRegistryConfig("service_install", "scala-projects", ServiceInstallConfigSchema);
+		cachedAppUrl = `https://${config.public_hostname}`;
+	} catch {
+		cachedAppUrl = "https://projects.scala.business";
+	}
+	return cachedAppUrl;
+}

package/src/resolve-brand-favicon.ts

@@ -0,0 +1,65 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Host-level brand favicon resolution. A single-brand UI service's host has
+ * a KNOWN owner (`service_install.config.brand_org`) — serving the generic
+ * platform "S" at the implicit /favicon.ico path there is a defect: browsers
+ * and crawlers hit that path directly and their favicon caches are sticky
+ * (operator-observed 2026-06-05 on launcha's proposal pages).
+ *
+ * Resolution is by convention from the org's asset store:
+ * `<brand_org>/logos/favicon.png`. Existence is probed once through the
+ * in-process asset proxy and cached (positive AND negative) so the favicon
+ * route never adds S3 latency per request. No brand_org, or no asset at the
+ * convention key → null, and the caller serves the generic fallback.
+ */
+
+import { createCache } from "@teamscala/cache/create-cache";
+import { handleAssetProxy } from "./asset-proxy";
+
+// The brand favicon path is a CONVENTION (`<brandOrg>/logos/favicon.png`) —
+// the key never changes for a given host, only the image at that key does
+// (served + cached separately by /api/assets/*). So the resolved PATH is
+// stable for the process lifetime; a long TTL is safe + avoids re-probing S3
+// (a cold stat takes 6-21s — see warmBrandFaviconCache).
+const cache = createCache<string | null>("service-boot:brand-favicon", {
+	ttlMs: 30 * 60_000,
+	maxSize: 8,
+});
+
+export async function resolveBrandFaviconPath(
+	brandOrg: string | undefined,
+): Promise<string | null> {
+	if (!brandOrg) return null;
+	return cache.fetchOrCompute(brandOrg, async () => {
+		const key = `${brandOrg}/logos/favicon.png`;
+		const path = `/api/assets/${encodeURIComponent(key)}`;
+		try {
+			const probe = await handleAssetProxy(
+				new Request(`http://favicon.local${path}`),
+			);
+			return probe.ok ? path : null;
+		} catch {
+			// Asset store unreachable — degrade to the generic fallback rather
+			// than failing the favicon route (block-level fail-open, loud at
+			// the proxy's own logging).
+			return null;
+		}
+	});
+}
+
+/**
+ * Eagerly resolve + cache the favicon at boot so the FIRST user request never
+ * pays the S3 existence-probe latency. The probe (`handleAssetProxy` →
+ * `s3.file(key).stat()`) is a COLD S3 call — the connection setup to the asset
+ * store takes 6s locally / up to 21s in prod, and the in-process cache resets
+ * on every restart (deploys, package-poller). Without warming, the first
+ * /favicon.ico after each restart stalls for that duration (operator-reported
+ * 23s). Fire-and-forget — runs in the background during boot, never blocks.
+ */
+export function warmBrandFaviconCache(brandOrg: string | undefined): void {
+	if (!brandOrg) return;
+	void resolveBrandFaviconPath(brandOrg);
+}

package/src/resolve-from-loader-config.test.ts

@@ -0,0 +1,44 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * resolve-from-loader-config.test.ts — locks in the interpolation contract that
+ * resolver_fn sources depend on: a bare `:sourceKey` ref passes the WHOLE
+ * resolved source object (so a resolver_input like {response: ":response"}
+ * reaches the resolver), while a URL param (e.g. :id) still resolves from params.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { interpolateMeta } from "./resolve-from-loader-config";
+
+describe("interpolateMeta (resolver_input ref contract)", () => {
+	test("a bare :sourceKey ref passes the whole resolved source object", () => {
+		const out = interpolateMeta(
+			{ response: ":response", assessment: ":assessment" },
+			{
+				response: { total_score: 48, category_scores: { "Be Seen": 46 } },
+				assessment: { title: "Launcha" },
+			},
+		);
+		// Whole objects flow through — the bug that blanked every report was these
+		// resolving to undefined (bare refs read from URL params, not resolved).
+		expect(out.response).toEqual({ total_score: 48, category_scores: { "Be Seen": 46 } });
+		expect(out.assessment).toEqual({ title: "Launcha" });
+	});
+
+	test("a bare ref with no resolved source key is left as the literal (interpolateMeta fallback)", () => {
+		// `:id` has no resolved source named "id" and params is empty here, so it
+		// does not resolve — interpolateMeta leaves the literal in place.
+		const out = interpolateMeta({ id: ":id" }, {});
+		expect(out.id).toBe(":id");
+	});
+
+	test("a dotted ref still reads a field off a resolved source", () => {
+		const out = interpolateMeta(
+			{ score: ":response.total_score" },
+			{ response: { total_score: 48 } },
+		);
+		expect(out.score).toBe(48);
+	});
+});