@teamscala/service-boot 0.23.516 → 0.23.518

package/src/handlers/whatsapp-liveness-handler.test.ts

@@ -1,56 +0,0 @@
-// @system codegen
-// @status generated
-// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
-//
-// This suite's assertions are OWNED by the codegen band: the band module
-// carries them verbatim, this file is the emission, and hand edits here are
-// overwritten on the next run. The rationale each assertion carries moved
-// with it into the band.
-
-import { beforeEach, expect, mock, test } from "bun:test";
-
-const recordEventCalls: Array<{ kind: string; payload: Record<string, unknown> }> = [];
-
-// The live device list the mocked /mcp forwarder returns — mutated per test.
-let mockDevices: { results: Array<{ id: string; state?: string; jid?: string }> };
-
-mock.module("@teamscala/event-log/record-event", () => ({
-	recordEvent: (e: { kind: string; payload: Record<string, unknown> }) => {
-		recordEventCalls.push(e);
-	},
-}));
-mock.module("@teamscala/chat-completion/central-tool-forwarder", () => ({
-	forwardToolToCentralMcp: async () => mockDevices,
-}));
-
-const { pollWhatsAppLiveness } = await import("./whatsapp-liveness.ts");
-
-beforeEach(() => {
-	recordEventCalls.length = 0;
-});
-
-test("connected → disconnected emits a device.disconnected recordEvent", async () => {
-	// Poll 1: device healthy — seeds the baseline, no event.
-	mockDevices = { results: [{ id: "scala-community", state: "logged_in", jid: "447@s.whatsapp.net" }] };
-	await pollWhatsAppLiveness({ config: {} as never });
-	expect(recordEventCalls, "no event while connected").toEqual([]);
-
-	// Poll 2: device dropped — transition fires the alert.
-	mockDevices = { results: [{ id: "scala-community", state: "logged_out", jid: "447@s.whatsapp.net" }] };
-	await pollWhatsAppLiveness({ config: {} as never });
-
-	expect(recordEventCalls).toHaveLength(1);
-	expect(recordEventCalls[0]!.kind).toBe("messaging.whatsapp.device.disconnected");
-	expect(recordEventCalls[0]!.payload).toMatchObject({
-		device_id: "scala-community",
-		state: "logged_out",
-		jid: "447@s.whatsapp.net",
-	});
-});
-
-test("staying connected across polls emits nothing", async () => {
-	mockDevices = { results: [{ id: "stable-dev", state: "logged_in" }] };
-	await pollWhatsAppLiveness({ config: {} as never });
-	await pollWhatsAppLiveness({ config: {} as never });
-	expect(recordEventCalls).toEqual([]);
-});

package/src/handlers/whatsapp-liveness-logic.ts

@@ -1,53 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * Pure transition-detection logic for the WhatsApp linked-device liveness monitor
- * (`whatsapp-liveness` handler). Split out from the GOWA-coupled handler so the
- * logic is unit-testable with zero adapter dependencies, and the handler is a thin
- * poll→detect→emit shell. The connection signal is the GOWA device `state` field
- * (`"logged_in"` == connected) — see `whatsapp-remote-logout-monitor`.
- */
-
-/** GOWA device `state` value meaning the linked phone is connected + authenticated. */
-export const GOWA_CONNECTED_STATE = "logged_in";
-
-export interface WhatsAppDeviceState {
-	id: string;
-	state: string;
-	jid?: string;
-	display_name?: string;
-}
-
-export interface LivenessTransitions {
-	disconnected: WhatsAppDeviceState[];
-	reconnected: WhatsAppDeviceState[];
-}
-
-/**
- * Detect connected↔disconnected transitions between the last-known and the freshly
- * observed device states.
- *
- * `prev` is the last-known `state` per device id. A device ABSENT from `prev` is a
- * first sighting: it seeds the baseline and yields NO transition (so the monitor
- * never alerts on a state it never observed the device leave, and a process restart
- * re-baselines without false positives). A device present in `prev` is compared:
- * connected→not is `disconnected`; not→connected is `reconnected`.
- */
-export function detectLivenessTransitions(
-	prev: Map<string, string>,
-	curr: WhatsAppDeviceState[],
-): LivenessTransitions {
-	const disconnected: WhatsAppDeviceState[] = [];
-	const reconnected: WhatsAppDeviceState[] = [];
-	for (const dev of curr) {
-		const prevState = prev.get(dev.id);
-		if (prevState === undefined) continue; // first sighting — baseline, no alert
-		const wasConnected = prevState === GOWA_CONNECTED_STATE;
-		const nowConnected = dev.state === GOWA_CONNECTED_STATE;
-		if (wasConnected && !nowConnected) disconnected.push(dev);
-		else if (!wasConnected && nowConnected) reconnected.push(dev);
-	}
-	return { disconnected, reconnected };
-}

package/src/handlers/whatsapp-liveness.test.ts

@@ -1,78 +0,0 @@
-// @system codegen
-// @status generated
-// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
-//
-// This suite's assertions are OWNED by the codegen band: the band module
-// carries them verbatim, this file is the emission, and hand edits here are
-// overwritten on the next run. The rationale each assertion carries moved
-// with it into the band.
-
-import { expect, test } from "bun:test";
-import { detectLivenessTransitions } from "./whatsapp-liveness-logic.ts";
-
-const dev = (id: string, state: string) => ({ id, state });
-
-test("first sighting of a device is baseline — no transition", () => {
-	const prev = new Map<string, string>(); // never seen
-	const curr = [dev("scala-community", "logged_in"), dev("new-number", "logged_in")];
-	expect(detectLivenessTransitions(prev, curr)).toEqual({
-		disconnected: [],
-		reconnected: [],
-	});
-});
-
-test("connected → disconnected transition is detected", () => {
-	const prev = new Map([["scala-community", "logged_in"]]);
-	const curr = [dev("scala-community", "logged_out")];
-	const out = detectLivenessTransitions(prev, curr);
-	expect(out.disconnected).toHaveLength(1);
-	expect(out.disconnected[0]!.id).toBe("scala-community");
-	expect(out.reconnected).toEqual([]);
-});
-
-test("any non-logged_in state counts as disconnected", () => {
-	const prev = new Map([["d", "logged_in"]]);
-	for (const state of ["logged_out", "connecting", "qr_required", "unknown", ""]) {
-		const out = detectLivenessTransitions(prev, [dev("d", state)]);
-		expect(out.disconnected, `state=${state}`).toHaveLength(1);
-	}
-});
-
-test("disconnected → connected recovery is detected", () => {
-	const prev = new Map([["d", "logged_out"]]);
-	const curr = [dev("d", "logged_in")];
-	const out = detectLivenessTransitions(prev, curr);
-	expect(out.reconnected).toHaveLength(1);
-	expect(out.disconnected).toEqual([]);
-});
-
-test("unchanged state yields no transition", () => {
-	const prev = new Map([
-		["a", "logged_in"],
-		["b", "logged_out"],
-	]);
-	const curr = [dev("a", "logged_in"), dev("b", "logged_out")];
-	expect(detectLivenessTransitions(prev, curr)).toEqual({
-		disconnected: [],
-		reconnected: [],
-	});
-});
-
-test("mixed: one disconnects, one recovers, one baselines, one stable", () => {
-	const prev = new Map<string, string>([
-		["keep-connected", "logged_in"],
-		["will-drop", "logged_in"],
-		["will-recover", "logged_out"],
-		["stays-down", "logged_out"],
-	]);
-	const curr = [
-		dev("keep-connected", "logged_in"),
-		dev("will-drop", "logged_out"),
-		dev("will-recover", "logged_in"),
-		dev("stays-down", "logged_out"),
-		dev("brand-new", "logged_in"), // first sighting — baseline, ignored
-	];
-	const out = detectLivenessTransitions(prev, curr);
-	expect(out.disconnected.map((d) => d.id)).toEqual(["will-drop"]);
-	expect(out.reconnected.map((d) => d.id)).toEqual(["will-recover"]);
-});

package/src/handlers/whatsapp-liveness.ts

@@ -1,138 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * The `whatsapp-liveness` pg-boss handler — polls GOWA `listDevices` and emits a
- * `messaging.whatsapp.device.disconnected` recordEvent + operator alert when a
- * WhatsApp linked device's `state` transitions away from `logged_in`. A phone-side
- * remote-logout (REMOTE_LOGOUT) emits NO GOWA webhook (its webhook set is
- * message/ack/group only), so the platform would otherwise only discover the loss
- * when a tool next needs the device (incident 2026-07-02: ~12h silent drop). This
- * monitor closes that gap with a ~5min poll (`whatsapp-remote-logout-monitor`).
- *
- * The device list is fetched by DISPATCHING the `api_gowa_devices.listDevices` tool
- * through the central `/mcp` loopback (`forwardToolToCentralMcp`) — reusing the
- * gateway's single sealed GOWA-credential resolution surface (no cred duplication,
- * no second resolver, no new process.env injection). The handler carries no GOWA
- * secrets; it authenticates to its own /mcp with `MCP_CHAT_LOOPBACK_TOKEN` as the
- * system caller (`MCP_SYSTEM_USER_ID`/`MCP_SYSTEM_ORG_ID` — a platform system
- * action, not a user-scoped one). The connection signal is the device `state` field
- * (`"logged_in"` == connected); the pure transition detector + its 8 tests live in
- * the dependency-free sibling `whatsapp-liveness-logic.ts`. State is held in-process
- * (Map<deviceId,state>); a process restart re-baselines every device.
- *
- * Registered under `@teamscala/service-boot:whatsapp-liveness`.
- */
-import type { ExecutionContext } from "@teamscala/os/contracts/mcp";
-import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import { recordEvent } from "@teamscala/event-log/record-event";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
-import { detectLivenessTransitions, type WhatsAppDeviceState } from "./whatsapp-liveness-logic.ts";
-import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
-import * as v from "valibot";
-import { createCache } from "@teamscala/cache/create-cache";
-
-/** In-process last-known device state, keyed by GOWA device id. */
-const lastKnown = new Map<string, string>();
-
-/** The subset of GOWA's `/devices` response this monitor reads. */
-interface GowaListDevicesResponse {
-	results?: Array<{
-		id: string;
-		state?: string;
-		jid?: string;
-		display_name?: string;
-	}>;
-}
-
-const systemIdentityCache = createCache<{
-	userId: string | undefined;
-	organisationId: string | undefined;
-}>("service-boot:whatsapp-liveness-system-identity", {
-	ttlMs: Number.POSITIVE_INFINITY,
-	maxSize: 1,
-});
-
-/** The system-caller identity for platform-action tool dispatches — shared by
- * the sibling handlers that dispatch GOWA reads through the central /mcp
- * (messaging-send-recording-watch reconcile sweep). */
-export async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
-	const hit = systemIdentityCache.get("default");
-	if (hit) return hit;
-	const row = await loadRegistryConfig("config", "system-identity", v.looseObject({}));
-	const identity = {
-		userId: row?.system_user_id as string | undefined,
-		organisationId: row?.system_org_id as string | undefined,
-	};
-	systemIdentityCache.set("default", identity);
-	return identity;
-}
-
-export async function pollWhatsAppLiveness({
-	config: _config,
-}: {
-	config: ScheduledJobConfig;
-}): Promise<void> {
-	const log = getAppLogger();
-
-	// System-caller identity (platform action, not user-scoped) — matches the
-	// gateway's system caller; the /mcp resolves it to cross-org super-admin.
-	const { userId, organisationId } = await getSystemIdentity();
-	const systemCtx: ExecutionContext = { userId, organisationId } as ExecutionContext;
-
-	let devices: WhatsAppDeviceState[];
-	try {
-		const { forwardToolToCentralMcp } = await import("@teamscala/chat-completion/central-tool-forwarder");
-		const res = (await forwardToolToCentralMcp(
-			"api_gowa_devices",
-			{ action: "listDevices" },
-			systemCtx,
-		)) as GowaListDevicesResponse | undefined;
-		devices = (res?.results ?? []).map((d) => ({
-			id: d.id,
-			state: d.state ?? "unknown",
-			jid: d.jid,
-			display_name: d.display_name,
-		}));
-	} catch (err) {
-		log.warn(
-			`[whatsapp-liveness] GOWA listDevices via /mcp failed: ${err instanceof Error ? err.message : String(err)}`,
-		);
-		return;
-	}
-
-	const { disconnected, reconnected } = detectLivenessTransitions(lastKnown, devices);
-
-	for (const dev of disconnected) {
-		recordEvent({
-			kind: "messaging.whatsapp.device.disconnected",
-			payload: {
-				device_id: dev.id,
-				jid: dev.jid,
-				display_name: dev.display_name,
-				state: dev.state,
-			},
-		});
-		log.warn(
-			`[whatsapp-liveness] device "${dev.id}" (${dev.jid ?? "?"}) DISCONNECTED (state=${dev.state}) — operator alert emitted`,
-		);
-	}
-	for (const dev of reconnected) {
-		recordEvent({
-			kind: "messaging.whatsapp.device.reconnected",
-			payload: { device_id: dev.id, jid: dev.jid, display_name: dev.display_name },
-		});
-		log.info(`[whatsapp-liveness] device "${dev.id}" (${dev.jid ?? "?"}) reconnected`);
-	}
-
-	// Advance the baseline to the freshly-observed states.
-	for (const dev of devices) lastKnown.set(dev.id, dev.state);
-
-	log.info(
-		`[whatsapp-liveness] poll complete — ${devices.length} device(s), ${disconnected.length} disconnect(s), ${reconnected.length} reconnect(s)`,
-	);
-}
-
-pgBossHandlerRegistry.register("@teamscala/service-boot:whatsapp-liveness", pollWhatsAppLiveness);

package/src/interpolate-meta.ts

@@ -1,123 +0,0 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Template interpolation against URL params and resolved loader data:
- * resolveParamRef, interpolateTemplate, and the meta-context filler.
- *
- * interpolateTemplate moved here from resolve-from-loader-config.ts
- * (file-size-budget): interpolation is its own canonical unit and the meta
- * filler already consumed it, so the import direction now points at the
- * family home instead of the wave resolver.
- *
- * An unresolved ref keeps its literal template rather than becoming
- * undefined — a page whose brand failed should show a raw `:brand.companyName`
- * somewhere visible rather than silently dropping its title.
- */
-
-export function resolveParamRef(
-	ref: string,
-	params: Record<string, unknown>,
-	resolved: Record<string, unknown>,
-): unknown {
-	const parts = ref.split(".");
-	// A bare (no-dot) ref can name either a resolved source key (e.g. `:response`
-	// passes the whole resolved source object to a resolver_fn) or a URL param
-	// (e.g. `:id`). Prefer the resolved source key, then fall back to the param.
-	// Dotted refs (`:response.total_score`) always read from `resolved`.
-	if (parts.length === 1) {
-		if (resolved != null && typeof resolved === "object" && ref in resolved) {
-			return (resolved as Record<string, unknown>)[ref];
-		}
-		if (params != null && typeof params === "object" && ref in params) {
-			return (params as Record<string, unknown>)[ref];
-		}
-		return undefined;
-	}
-	let current: unknown = resolved;
-	for (const part of parts) {
-		if (current == null || typeof current !== "object") return undefined;
-		current = readField(current as Record<string, unknown>, part);
-	}
-	return current;
-}
-
-/**
- * A resource_loader row spells DATABASE COLUMN NAMES — `page_id`,
- * `organisation_id`, `prepared_for` — because that is what the schema calls
- * them. The ORM hands back CAMELCASE keys — `pageId`, `organisationId`,
- * `preparedFor`. Nothing reconciled the two, so a `:proposal.page_id` ref read
- * a key the object does not have and returned undefined.
- *
- * MEASURED 2026-09-03, and the consequence is far worse than a missing value.
- * `interpolateTemplate` DROPS a key whose value is undefined, so a dependent
- * source declared `where: { id: ":proposal.page_id" }` was issued as
- * `where: {}` — and findFirst with an empty filter returns AN ARBITRARY FIRST
- * ROW. A client proposal page therefore loaded an unrelated builda_page,
- * rendered a stranger's content under the correct brand chrome, and answered
- * 200 throughout. Instrumenting the live resolver showed every dependent
- * source doing it: page, website, contact, partnerOrg and clientOrg all with
- * `where={}`; only `proposal` was correct, because its ref is the URL param
- * `:id` rather than a sibling source.
- *
- * Read the spelled key first, then its camelCase equivalent. Column names stay
- * the authoring vocabulary and a row never has to know what the ORM did to its
- * keys.
- */
-function readField(source: Record<string, unknown>, key: string): unknown {
-	if (key in source) return source[key];
-	const camel = key.replace(/_([a-z0-9])/g, (_m, c: string) => c.toUpperCase());
-	return camel === key ? undefined : source[camel];
-}
-
-export function interpolateTemplate(
-	template: unknown,
-	params: Record<string, unknown>,
-	resolved: Record<string, unknown>,
-): unknown {
-	if (typeof template === "string") {
-		const exactMatch = template.match(/^:([a-zA-Z0-9_.]+)$/);
-		if (exactMatch) {
-			return resolveParamRef(exactMatch[1], params, resolved);
-		}
-		if (template.includes(":")) {
-			return template.replace(
-				/:([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*)/g,
-				(_match, ref: string) => {
-					const value = resolveParamRef(ref, params, resolved);
-					return value != null ? String(value) : _match;
-				},
-			);
-		}
-		return template;
-	}
-	if (Array.isArray(template)) {
-		return template.map((v) => interpolateTemplate(v, params, resolved));
-	}
-	if (template != null && typeof template === "object") {
-		const out: Record<string, unknown> = {};
-		for (const [k, v] of Object.entries(template)) {
-			const result = interpolateTemplate(v, params, resolved);
-			if (result !== undefined) out[k] = result;
-		}
-		return out;
-	}
-	return template;
-}
-
-export function interpolateMeta(
-	template: Record<string, unknown>,
-	data: Record<string, unknown>,
-): Record<string, unknown> {
-	const out: Record<string, unknown> = {};
-	for (const [k, v] of Object.entries(template)) {
-		if (v != null && typeof v === "object" && !Array.isArray(v)) {
-			out[k] = interpolateMeta(v as Record<string, unknown>, data);
-		} else {
-			const result = interpolateTemplate(v, {}, data);
-			out[k] = result ?? v;
-		}
-	}
-	return out;
-}

package/src/load-service-prisma-client.ts

@@ -1,53 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * Loads the service's own generated PrismaClient from
- * <cwd>/prisma/generated/prisma/client.ts. Each service repo generates its own
- * client from its own schema.prisma; resolving a static import would pick up
- * whichever @prisma/generated bun resolves first in a multi-service workspace,
- * which is wrong.
- *
- * No fallback: if the generated client is missing the deploy is broken — fail
- * loud with the remediation step.
- */
-
-export type ServicePrismaClientConstructor = new (args: {
-	adapter: unknown;
-}) => unknown;
-
-export async function loadServicePrismaClient(
-	serviceSlug: string,
-): Promise<ServicePrismaClientConstructor> {
-	// Per `near-empty-services`, the platform owns one Prisma client (in
-	// @teamscala/db) shared by every service. Service-local Prisma clients
-	// remain supported when a service ships its own `prisma/schema.prisma`.
-	const fs = await import("node:fs");
-	const servicePath = `${process.cwd()}/prisma/generated/prisma/client.ts`;
-	// `@teamscala/db/client` is the sanctioned subpath that re-exports the
-	// generated PrismaClient (per `@teamscala/db/package.json#exports`).
-	// The previous import of `@teamscala/db/generated/client/client.ts`
-	// reached into an internal path that isn't exported; under bun
-	// isolated-linker + node's exports-field enforcement, that path
-	// fails to resolve at runtime even though the file is on disk.
-	const platformPath = "@teamscala/db/client";
-	const path = fs.existsSync(servicePath) ? servicePath : platformPath;
-	let mod: { PrismaClient?: ServicePrismaClientConstructor };
-	try {
-		mod = (await import(path)) as {
-			PrismaClient?: ServicePrismaClientConstructor;
-		};
-	} catch (err) {
-		throw new Error(
-			`[scala-install:${serviceSlug}] Failed to load Prisma client at ${path}. ` +
-				`Cause: ${err instanceof Error ? err.message : err}`,
-		);
-	}
-	if (!mod.PrismaClient) {
-		throw new Error(
-			`[scala-install:${serviceSlug}] Prisma client at ${path} has no PrismaClient export.`,
-		);
-	}
-	return mod.PrismaClient;
-}

package/src/loader-errors.ts

@@ -1,41 +0,0 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Error vocabulary for resource_loader source resolution. Split out of
- * resolve-from-loader-config (file-size-budget): the classes are the
- * name-matched contract other layers key on, and they belong where they
- * can be imported without dragging the wave resolver with them.
- */
-
-export class MissingLoaderModelCapabilityError extends Error {
-	constructor(model: string, sourceKey: string) {
-		super(
-			`[resource_loader] source "${sourceKey}" requires model "${model}", but the generated server client does not expose findFirst for it — regenerate the service schema from its page loaders`,
-		);
-		this.name = "MissingLoaderModelCapabilityError";
-	}
-}
-
-/**
- * A Prisma/pg query rejected an interpolated URL param as not a valid uuid
- * (pg 22P02 surfaced as the generated client's SqlQueryError). The value came
- * from the URL, so the URL names no row — the same state as a deleted row,
- * not a renderer failure. Deliberately a tight name+message match: a
- * genuinely malformed query is a config fault and must keep failing loudly.
- *
- * Measured 2026-09-12 on scala-quiz prod: scanner paths (/.env, /robots.txt,
- * *.php) and slug links each threw `invalid input syntax for type uuid` as a
- * 500 after a ~2.5s DB round trip, and the page-server:render-budget breaker
- * counted them as CONSECUTIVE render failures — 53 in a row on 2026-09-11 —
- * so the layer sat DEGRADED fail-closed and every real quiz page 503'd for
- * hours while the only successful render in the window was a crawler.
- */
-export function isUrlRefNotUuidError(err: unknown): boolean {
-	return (
-		err instanceof Error &&
-		err.name === "SqlQueryError" &&
-		err.message.includes("invalid input syntax for type uuid")
-	);
-}

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

@@ -1,36 +0,0 @@
-/**
- * @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";
-}