@teamscala/service-boot 0.23.284

package/src/content-page-floor.test.ts

@@ -0,0 +1,127 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Unit proof of the /roadmap fix's core decision (independent of the publish /
+ * deploy — verify-before-done). Exercises the pure floor decision + the floor
+ * render for every case: dead link (no row → 404), empty page (zero blocks →
+ * 200), normal page (renders), resource_type route (handled elsewhere), and
+ * region-slot shell (no page source — untouched).
+ */
+import { test, expect } from "bun:test";
+import {
+	decideContentPageFloor,
+	pageBodyIsEmpty,
+} from "./content-page-floor.ts";
+import {
+	PrimaryResourceMissingError,
+	buildResourceNotFoundResponse,
+} from "./resource-not-found.ts";
+
+test("decideContentPageFloor: no page row → dead-link 404 floor (the /roadmap case)", () => {
+	const e = decideContentPageFloor({
+		hasResourceType: false,
+		hasPageContentSource: true,
+		page: null,
+	});
+	expect(e).toBeInstanceOf(PrimaryResourceMissingError);
+	expect(e!.resourceType).toBe("page");
+	expect(e!.httpStatus).toBe(404);
+	expect(e!.empty).toBe(false);
+});
+
+test("decideContentPageFloor: page row with zero blocks → empty-page 200 floor", () => {
+	const e = decideContentPageFloor({
+		hasResourceType: false,
+		hasPageContentSource: true,
+		page: { id: "p1", puck_data: { content: [], root: { props: {} } } },
+	});
+	expect(e).toBeInstanceOf(PrimaryResourceMissingError);
+	expect(e!.httpStatus).toBe(200);
+	expect(e!.empty).toBe(true);
+});
+
+test("decideContentPageFloor: page row with blocks → null (renders normally)", () => {
+	const e = decideContentPageFloor({
+		hasResourceType: false,
+		hasPageContentSource: true,
+		page: { id: "p1", puck_data: { content: [{ type: "Text", props: {} }] } },
+	});
+	expect(e).toBeNull();
+});
+
+test("decideContentPageFloor: resource_type route → null (handled by the resource-type check)", () => {
+	const e = decideContentPageFloor({
+		hasResourceType: true,
+		hasPageContentSource: true,
+		page: null,
+	});
+	expect(e).toBeNull();
+});
+
+test("decideContentPageFloor: no page source (region-slot shell) → null (untouched)", () => {
+	const e = decideContentPageFloor({
+		hasResourceType: false,
+		hasPageContentSource: false,
+		page: null,
+	});
+	expect(e).toBeNull();
+});
+
+test("pageBodyIsEmpty: absent page → false (not the empty-page case)", () => {
+	expect(pageBodyIsEmpty(null)).toBe(false);
+	expect(pageBodyIsEmpty(undefined)).toBe(false);
+});
+
+test("pageBodyIsEmpty: row with no puck_data → empty", () => {
+	expect(pageBodyIsEmpty({ id: "p1" })).toBe(true);
+});
+
+test("pageBodyIsEmpty: row with empty content array → empty", () => {
+	expect(pageBodyIsEmpty({ id: "p1", puck_data: { content: [] } })).toBe(true);
+});
+
+test("pageBodyIsEmpty: row with content blocks → not empty", () => {
+	expect(
+		pageBodyIsEmpty({ id: "p1", puck_data: { content: [{ type: "Hero" }] } }),
+	).toBe(false);
+});
+
+test("pageBodyIsEmpty: row with string puck_data (raw) — empty", () => {
+	expect(pageBodyIsEmpty({ id: "p1", puck_data: '{"content":[]}' })).toBe(true);
+});
+
+test("pageBodyIsEmpty: row with string puck_data (raw) — non-empty", () => {
+	expect(
+		pageBodyIsEmpty({ id: "p1", puck_data: '{"content":[{"type":"Text"}]}' }),
+	).toBe(false);
+});
+
+test("floor render: dead link → 404 with 'Take me home' + doesn't-exist copy", async () => {
+	const r = buildResourceNotFoundResponse("page", null, 404, { homeUrl: "/" });
+	expect(r.status).toBe(404);
+	const html = await r.text();
+	expect(html).toContain("Take me home");
+	expect(html).toContain("doesn");
+	expect(html).toContain('href="/"');
+	expect(html).toContain("noindex");
+});
+
+test("floor render: empty page → 200 with 'This page is empty' + Take me home", async () => {
+	const r = buildResourceNotFoundResponse("page", null, 200, {
+		homeUrl: "/",
+		empty: true,
+	});
+	expect(r.status).toBe(200);
+	const html = await r.text();
+	expect(html).toContain("This page is empty");
+	expect(html).toContain("Take me home");
+});
+
+test("floor render: bare-root landing → no Take-me-home (it IS home)", async () => {
+	const r = buildResourceNotFoundResponse("page", null, 200);
+	const html = await r.text();
+	expect(html).not.toContain("Take me home");
+	expect(html).toContain("no page at this link");
+});

package/src/content-page-floor.ts

@@ -0,0 +1,70 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Pure decision: does a CONTENT route (no resource_type) whose loader resolved
+ * a `page` body source warrant the branded not-found floor? Extracted from
+ * register-registry-page-route so the rule is unit-testable independent of the
+ * Hono/DB/graph machinery that wraps it (the fix's correctness does not depend
+ * on the publish — verify-before-done).
+ *
+ * Three outcomes:
+ *   - no page row (deleted/unmatched path, e.g. /roadmap) → dead-link 404 floor
+ *   - page row exists but zero content blocks → empty-page 200 floor
+ *   - otherwise → null (render normally)
+ *
+ * The "Vision Toolbar" leak this closes: a content catchall synthesized an empty
+ * page for an unmatched path and served a cacheable 200; resource-not-found-is-
+ * the-root-floor only fired for resource_type routes, so dead content links fell
+ * through. See resource-not-found.ts for the floor + operator ruling 2026-07-21.
+ */
+import { PrimaryResourceMissingError } from "./resource-not-found.ts";
+
+/**
+ * A page ROW exists but its body has zero content blocks — a content gap, not a
+ * dead link. True only when the row is present yet `puck_data` is absent or its
+ * `content` array is empty. Handles string (raw) and object (normalized) puck_data.
+ */
+export function pageBodyIsEmpty(page: unknown): boolean {
+	if (!page || typeof page !== "object") return false;
+	const obj = page as Record<string, unknown>;
+	const raw = obj.puck_data ?? obj.puckData;
+	if (raw == null) return true; // row exists, no puck_data → empty
+	let data: { content?: unknown } | null;
+	if (typeof raw === "string") {
+		try {
+			data = JSON.parse(raw) as { content?: unknown };
+		} catch {
+			return false;
+		}
+	} else {
+		data = raw as { content?: unknown };
+	}
+	return !Array.isArray(data?.content) || (data.content as unknown[]).length === 0;
+}
+
+/**
+ * Decide whether a content route should fall to the branded not-found floor.
+ * Returns the error to throw (mapped to the floor by bind-page-handler), or null
+ * to render normally. `hasResourceType` routes are handled by the existing
+ * resource_type missing check (caller-side) — they return null here.
+ */
+export function decideContentPageFloor(opts: {
+	hasResourceType: boolean;
+	hasPageContentSource: boolean;
+	page: unknown;
+}): PrimaryResourceMissingError | null {
+	// Only content routes (no resource_type) with a `page` body source. Region-
+	// slot shells (no `page` source) and resource_type routes are unaffected.
+	if (opts.hasResourceType || !opts.hasPageContentSource) return null;
+	if (opts.page == null) {
+		// No page row → dead link (deleted/unmatched path).
+		return new PrimaryResourceMissingError("page", 404);
+	}
+	if (pageBodyIsEmpty(opts.page)) {
+		// Row exists, zero blocks → content gap, not a dead link.
+		return new PrimaryResourceMissingError("page", 200, { empty: true });
+	}
+	return null;
+}

package/src/discover-blocks.ts

@@ -0,0 +1,228 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Surgical block discovery: at boot, queries every block_schema row in the
+ * registry whose componentPath starts with one of the service's declared
+ * block_packages, then dynamic-imports each one. Per-block try/catch — one
+ * dead componentPath logs and skips, the rest still register and the page
+ * renders the surviving blocks. This replaces the static
+ * `.scala-install/page-manifest.ts` codegen output, which had the failure
+ * mode of a single dead block_schema row crashing the whole manifest at
+ * compile time.
+ *
+ * Empty block_packages is NOT fatal here: it falls back to scanning all
+ * active block_schema (uninstalled packages skip via the per-block try/catch),
+ * so a service whose row is unpopulated but whose blocks are installed still
+ * renders. The real "booted with zero blocks" fail-closed is at the call site
+ * (loaded.length === 0 → BootFatalError). A DB-unreachable error still throws —
+ * no fallback to a package-side puckBlocks scan, which masked blockless boots.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { BlockSchemaConfigSchema } from "@teamscala/db-validation/registry-schemas/block-schema";
+import { getServerClient } from "@teamscala/orpc/server-client-registry";
+import * as v from "valibot";
+import type { RendererComponentEntry } from "./types.ts";
+
+export interface DiscoveredBlocks {
+	components: Record<string, RendererComponentEntry>;
+	loaded: string[];
+	skipped: string[];
+}
+
+interface BlockSchemaConfig {
+	componentPath?: string;
+	componentExport?: string;
+	fields?: Record<string, unknown>;
+	defaults?: Record<string, unknown>;
+}
+
+interface RegistryEntriesModel {
+	findMany: (args: {
+		where: Record<string, unknown>;
+		select: Record<string, unknown>;
+		orderBy: Record<string, unknown>;
+	}) => Promise<Array<{ slug: string; config: unknown }>>;
+}
+
+interface PrismaWithRegistry {
+	registry_entries: RegistryEntriesModel;
+}
+
+export async function discoverBlocks(
+	blockPackages: string[],
+): Promise<DiscoveredBlocks> {
+	// Scope discovery to what is ACTUALLY INSTALLED, never the authored
+	// `block_packages` list. That list was an authored hint that silently
+	// DRIFTED: a page-used package missing from it caused its blocks to be
+	// skipped and rendered BLANK with only a warning (scala-sign, 2026-06-04 —
+	// SignIn / SignatureField / ScrollProgress all blanked because sign-in-block
+	// had fallen out of the list). The filesystem is the source of truth: a page
+	// can only compose blocks from packages installed as the service's
+	// dependencies, so "installed @teamgbg package" is always a correct superset
+	// of "packages the pages need". A block_schema whose package is installed is
+	// imported; an uninstalled one is skipped (its import would fail anyway).
+	// This makes an authored-list mistake STRUCTURALLY UNABLE to blank a
+	// page-used block. The install dir is also narrower than "all block_schema",
+	// so the 2026-05-29 empty-list-scans-everything incident cannot recur either.
+	const serviceModules = join(process.cwd(), "node_modules");
+	const installedCache = new Map<string, boolean>();
+	const isInstalled = (pkg: string): boolean => {
+		const cached = installedCache.get(pkg);
+		if (cached !== undefined) return cached;
+		const ok = existsSync(join(serviceModules, ...pkg.split("/")));
+		installedCache.set(pkg, ok);
+		return ok;
+	};
+	// `blockPackages` is retained only to surface authored-vs-installed drift to
+	// the operator; it no longer gates discovery, so it can never blank a block.
+	if (blockPackages.length > 0) {
+		const stale = blockPackages.filter((p) => !isInstalled(p));
+		if (stale.length > 0) {
+			console.warn(
+				`[discover-blocks] block_packages lists ${stale.length} package(s) that are not installed (ignored): ${stale.join(", ")}`,
+			);
+		}
+	}
+
+	const components: Record<string, RendererComponentEntry> = {};
+	const loaded: string[] = [];
+	const skipped: string[] = [];
+
+	const prisma = (await getServerClient()) as unknown as PrismaWithRegistry;
+	const rows: Array<{ slug: string; config: unknown }> =
+		await prisma.registry_entries.findMany({
+			where: { type: "block_schema", is_active: true },
+			select: { slug: true, config: true },
+			orderBy: { slug: "asc" },
+		});
+
+	// Parallel block discovery (no-serial-per-unit-work-on-hot-paths: boot is a
+	// recurring cycle via the package-poller's restarts). Previously each block's
+	// component was imported SERIALLY (sum of ~44 import times) under a 3s
+	// timeout — heavy blocks (e.g. AiChat with Plate) exceeded 3s, were SKIPPED
+	// at boot, and paid their full import at first render (cold-start cost).
+	// Bounded-parallel (chunks of 8) collapses boot to ceil(N/8) waves of the
+	// max import time, and the raised 8s timeout lets heavy blocks import at
+	// boot (shifted off the first render). `skipped`/`loaded`/`components`
+	// mutations are safe concurrently (single-threaded; atomic at await points).
+	const loadBlock = async (row: { slug: string; config: unknown }) => {
+		const rawConfig = parseConfig(row.config);
+		const rawComponentPath = getStringProperty(rawConfig, "componentPath");
+		const rawPackage = rawComponentPath
+			? rawComponentPath.split("/").slice(0, 2).join("/")
+			: null;
+		if (!rawPackage || !isInstalled(rawPackage)) {
+			skipped.push(
+				`${row.slug} (${rawPackage ?? "missing componentPath"} not installed)`,
+			);
+			return;
+		}
+
+		let cfg: BlockSchemaConfig;
+		try {
+			cfg = v.parse(BlockSchemaConfigSchema, rawConfig) as BlockSchemaConfig;
+		} catch (err) {
+			skipped.push(
+				`${row.slug} (invalid block_schema config: ${formatValidationError(err)})`,
+			);
+			return;
+		}
+
+		const componentPath = cfg.componentPath;
+		const componentExport = cfg.componentExport;
+		if (!componentPath || !componentExport) {
+			skipped.push(`${row.slug} (missing componentPath/componentExport)`);
+			return;
+		}
+		// Scope to installed packages: each block_schema's componentPath must
+		// start with a package present in the service's node_modules.
+		const pkgPrefix = componentPath.split("/").slice(0, 2).join("/");
+		if (!isInstalled(pkgPrefix)) {
+			skipped.push(`${row.slug} (${pkgPrefix} not installed)`);
+			return;
+		}
+		try {
+			const TIMEOUT_MS = 8_000;
+			const mod = (await Promise.race([
+				import(componentPath),
+				new Promise<never>((_, rej) =>
+					setTimeout(
+						() => rej(new Error(`import timeout >${TIMEOUT_MS}ms`)),
+						TIMEOUT_MS,
+					),
+				),
+			])) as Record<string, unknown>;
+			const component = mod[componentExport] ?? mod.default;
+			if (typeof component !== "function") {
+				skipped.push(
+					`${row.slug} (${componentExport} not a component in ${componentPath})`,
+				);
+				return;
+			}
+			components[row.slug] = {
+				render: component as RendererComponentEntry["render"],
+				fields: (cfg.fields ?? {}) as never,
+				// block_schema.defaults → the SSR component entry, so buildPuckConfig
+				// merges them UNDER authored props at render (blocks-fully-programmable:
+				// DB-declared defaults reach render, never a component parameter
+				// constant). Puck's RSC <Render> ignores defaultProps itself.
+				defaultProps: (cfg.defaults ?? {}) as never,
+			};
+			loaded.push(row.slug);
+		} catch (err) {
+			skipped.push(`${row.slug} (${(err as Error).message})`);
+		}
+	};
+	// Pre-filter to rows the service can actually import, so expected-absent
+	// blocks don't pollute the boot log as "skipped". A service (e.g.
+	// scala-projects) installs only a subset of the platform's ~45 blocks; the
+	// rest are expected-absent (their imports would fail anyway), not warnings.
+	// The filesystem remains the source of truth (block-discovery-scopes-by-
+	// install): an uninstalled block is simply not considered. Rows with a
+	// missing componentPath are kept so `loadBlock` still flags them (real data
+	// signal); `skipped` thus catches only genuine failures (installed package
+	// but import/config/export failed) and the call-site WARN becomes signal.
+	const candidateRows = rows.filter((row) => {
+		const cp = getStringProperty(parseConfig(row.config), "componentPath");
+		if (!cp) return true;
+		const pkg = cp.split("/").slice(0, 2).join("/");
+		return isInstalled(pkg);
+	});
+	// All blocks concurrent (module imports are in-process I/O + V8 compile — no
+	// fork tax, so bounded concurrency isn't needed here; the chunk-of-8 was
+	// needlessly serializing 44 imports into 6 waves when 1 wave suffices).
+	await Promise.all(candidateRows.map(loadBlock));
+
+	return { components, loaded, skipped };
+}
+
+function parseConfig(config: unknown): unknown {
+	if (typeof config !== "string") return config;
+	try {
+		return JSON.parse(config) as unknown;
+	} catch {
+		// Malformed JSON string → absent signal, never the raw string: the caller's
+		// valibot parse then fails and the block is skipped (fail-closed), rather
+		// than a non-object masquerading as config (protective-layers-fail-explicitly).
+		return null;
+	}
+}
+
+function getStringProperty(value: unknown, key: string): string | null {
+	if (!value || typeof value !== "object") return null;
+	const maybe = (value as Record<string, unknown>)[key];
+	return typeof maybe === "string" ? maybe : null;
+}
+
+function formatValidationError(err: unknown): string {
+	if (err && typeof err === "object" && "issues" in err) {
+		const issues = (err as { issues?: Array<{ message?: string }> }).issues;
+		const first = Array.isArray(issues) ? issues[0]?.message : undefined;
+		if (first) return first;
+	}
+	return err instanceof Error ? err.message : String(err);
+}

package/src/expand-roster.ts

@@ -0,0 +1,197 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Server-side roster expansion — the executor that handles "render N of block X
+ * per data row" so the page never needs a domain-specific panel/list block. A
+ * block authored with `props.dataRepeat: "parties"` is a TEMPLATE; before SSR
+ * this clones it once per roster item into its parent slot (top-level content or
+ * any Container's `content` slot), then drops the marker. Each clone:
+ *   - sets `role` + `dataKey` to the item's key, so a prop-driven block (the
+ *     SignatureField cell) finds its own party with no per-clone wiring;
+ *   - substitutes `{{name}}` / `{{role}}` / `{{company}}` / `{{date}}` /
+ *     `{{status}}` placeholders in any string prop (so a recipient row is plain
+ *     `Container` + `Text` primitives — the copy lives on the page, not here).
+ *     `{{status}}` resolves from the template's own `signedLabel` /
+ *     `awaitingLabel` props (DB-driven copy), never hardcoded.
+ * Generic over any roster; the agreement page passes its parties.
+ */
+
+export interface RosterItem {
+	key: string;
+	role: string;
+	name: string;
+	title: string | null;
+	company: string | null;
+	signedAt: string | null;
+	signature: string | null;
+}
+
+interface Block {
+	type?: string;
+	props?: Record<string, unknown>;
+}
+
+function formatDate(iso: string | null): string {
+	if (!iso) return "";
+	try {
+		return new Date(iso).toLocaleDateString("en-AU", {
+			day: "numeric",
+			month: "long",
+			year: "numeric",
+		});
+	} catch {
+		return "";
+	}
+}
+
+/** Resolve a `{{field}}` token for one roster item. */
+function tokenValue(
+	field: string,
+	item: RosterItem,
+	labels: { signed: string; awaiting: string },
+): string {
+	switch (field) {
+		case "name":
+			return item.name;
+		case "role":
+			return item.role;
+		case "company":
+			return item.company ?? "";
+		case "title":
+			return item.title ?? "";
+		case "date":
+			return formatDate(item.signedAt);
+		case "status":
+			return item.signedAt ? labels.signed : labels.awaiting;
+		default:
+			return "";
+	}
+}
+
+/** Replace every `{{field}}` token in a string with the item's value. */
+function substitute(
+	value: string,
+	item: RosterItem,
+	labels: { signed: string; awaiting: string },
+): string {
+	return value.replace(/\{\{\s*(\w+)\s*\}\}/g, (_m, f) =>
+		tokenValue(String(f), item, labels),
+	);
+}
+
+/** The `content` slot arrays a block exposes (Container.props.content, …). */
+function slotArrays(block: Block): unknown[][] {
+	const out: unknown[][] = [];
+	const props = block.props;
+	if (!props) return out;
+	for (const v of Object.values(props)) {
+		if (Array.isArray(v) && v.every((e) => e && typeof e === "object")) {
+			out.push(v as unknown[]);
+		}
+	}
+	return out;
+}
+
+/** Deep-clone a template block, binding it to one roster item. */
+function cloneForItem(template: Block, item: RosterItem): Block {
+	const labels = {
+		signed: String(template.props?.signedLabel ?? ""),
+		awaiting: String(template.props?.awaitingLabel ?? ""),
+	};
+	const walk = (node: unknown): unknown => {
+		if (typeof node === "string") return substitute(node, item, labels);
+		if (Array.isArray(node)) return node.map(walk);
+		if (node && typeof node === "object") {
+			const out: Record<string, unknown> = {};
+			for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+				if (k === "dataRepeat" || k === "signedLabel" || k === "awaitingLabel")
+					continue;
+				out[k] = walk(v);
+			}
+			return out;
+		}
+		return node;
+	};
+	const clone = walk(template) as Block;
+	clone.props = {
+		...(clone.props ?? {}),
+		// fresh id per clone so React keys + hydration stay stable
+		id: `${String(template.props?.id ?? "tmpl")}-${item.key}`,
+		role: item.key,
+		dataKey: item.key,
+	};
+	return clone;
+}
+
+/** Is this block a per-party template to expand? */
+function isPartyTemplate(block: Block): boolean {
+	// Generic marker (any block that declares `dataRepeat`)…
+	if (block?.props?.dataRepeat === "parties") return true;
+	// …plus the natural convention for the signature cell: a SignatureField with
+	// no assigned role IS "all parties". This needs no extra prop, so it survives
+	// Puck's slot serialization (which keeps only component-declared props).
+	if (block?.type === "SignatureField") {
+		const role = block.props?.role;
+		if (!(typeof role === "string" && role.trim())) return true;
+	}
+	return false;
+}
+
+/** Expand every per-party template in a content array, recursing into slots. */
+function expandArray(content: unknown[], parties: RosterItem[]): unknown[] {
+	const out: unknown[] = [];
+	for (const raw of content) {
+		const block = raw as Block;
+		// Recurse into this block's own slots first.
+		for (const slot of slotArrays(block)) {
+			const expanded = expandArray(slot, parties);
+			slot.length = 0;
+			slot.push(...expanded);
+		}
+		if (isPartyTemplate(block)) {
+			for (const party of parties) out.push(cloneForItem(block, party));
+		} else {
+			out.push(block);
+		}
+	}
+	return out;
+}
+
+/** Agreement-level tokens (one substitution, not per-party). */
+export interface RosterMeta {
+	[token: string]: string;
+}
+
+/** Substitute `{{agreement.token}}` placeholders in every string prop, in place. */
+function substituteMeta(node: unknown, meta: RosterMeta): unknown {
+	if (typeof node === "string") {
+		return node.replace(/\{\{\s*agreement\.(\w+)\s*\}\}/g, (_m, t) =>
+			meta[String(t)] != null ? meta[String(t)] : "",
+		);
+	}
+	if (Array.isArray(node)) return node.map((n) => substituteMeta(n, meta));
+	if (node && typeof node === "object") {
+		for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+			(node as Record<string, unknown>)[k] = substituteMeta(v, meta);
+		}
+		return node;
+	}
+	return node;
+}
+
+/** Expand roster templates + bind agreement-meta placeholders across regions. */
+export function expandRosterTemplates(
+	resolved: Record<string, unknown>,
+	parties: RosterItem[],
+	meta?: RosterMeta,
+): void {
+	for (const value of Object.values(resolved)) {
+		const pd = (value as { puck_data?: { content?: unknown[] } } | null)
+			?.puck_data;
+		if (!pd || !Array.isArray(pd.content)) continue;
+		if (parties.length > 0) pd.content = expandArray(pd.content, parties);
+		if (meta) substituteMeta(pd.content, meta);
+	}
+}