@teamscala/service-boot 0.23.284 → 0.23.286

package/src/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Shared type definitions for service-boot boot helpers.
+ */
+type RendererComponent = (props: Record<string, unknown>) => unknown;
+export interface RendererComponentEntry {
+    render: RendererComponent;
+    fields?: Record<string, {
+        type: string;
+    }>;
+    /** block_schema.defaults, carried onto the entry by discoverBlocks so
+     *  buildPuckConfig merges them under authored props at SSR
+     *  (blocks-fully-programmable). */
+    defaultProps?: Record<string, unknown>;
+}
+export interface PageHandlerExtras {
+    htmlTemplate: string;
+    userId?: string;
+    orgId?: string;
+    searchParams?: Record<string, string>;
+    nonce?: string;
+}
+export type CreatePageHandler = (config: PageHandlerConfig) => (request: Request, extras: PageHandlerExtras) => Promise<Response>;
+export interface PageHandlerConfig {
+    components: Record<string, RendererComponentEntry>;
+    providers?: string[];
+    loadData: (request: Request) => Promise<unknown>;
+    renderMode?: "public" | "portals" | "utility";
+    /**
+     * Owning service slug — used by the page-server render catch to resolve
+     * the branded logo on the render-error page. Mirrors service-runtime's
+     * PageHandlerConfig.
+     */
+    serviceSlug?: string;
+    /**
+     * Redirect a signed-in user's `/` to their org-scoped portal dashboard.
+     * Set only for services serving a `/*` catchall page_route (the portal);
+     * single-site portal-mode services serve their real page at `/`.
+     * Mirrors service-runtime's PageHandlerConfig (1.15.82).
+     */
+    portalHomeRedirect?: boolean;
+}
+export type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";

package/src/ui-service.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Boots a `kind: "ui"` service. Reads the service_install registry row and
+ * orchestrates a fixed pipeline of single-purpose stages onto one Hono app
+ * served by @teamscala/service-runtime/serve (one Bun.serve in dev and prod).
+ */
+import { Hono } from "hono";
+import type { ServiceInstallConfig } from "./load-service-install-row.ts";
+export interface ResolvedBlock {
+    slug: string;
+    packagePath: string;
+}
+export interface UiServiceBootResult {
+    kind: "ui";
+    blocks: ResolvedBlock[];
+    routes: string[];
+    port: number;
+    app: Hono;
+}
+/**
+ * Page-server symbols injected by the caller. service-boot is tier 4
+ * (server) and must not import from tier 2 (`@teamscala/service-runtime`)
+ * per `installer-and-runtime` Rule 1. The runtime's bin entrypoint
+ * boot pipeline imports these from `page-server/` (same package —
+ * legal) and passes them down here.
+ */
+export interface PageServerDeps {
+    createPageHandler: import("./types.ts").CreatePageHandler;
+}
+/**
+ * Boots a UI service using two-phase boot for fast availability.
+ *
+ * Phase 1 (fast): Build and serve minimal tool-only app (ORPC, data routes,
+ * auth gates). This becomes available within ~10s, enabling the MCP tool
+ * surface to accept requests immediately after restart.
+ *
+ * Phase 2 (background): Build full app (pages, hydration) and atomically swap
+ * it in. The readiness gate flips to ready after Phase 1, not Phase 2.
+ *
+ * The interim mitigation (503 + gateway retry + circuit breaker) remains in
+ * place and is NOT undone.
+ */
+export declare function bootUiService(config: ServiceInstallConfig, serviceSlug: string, deps: PageServerDeps, databaseUrl: string): Promise<UiServiceBootResult>;

package/src/ui-service.ts

@@ -103,7 +103,16 @@ export async function bootUiService(
 	// Phase 2: Build full app in background (non-blocking)
 	;(async () => {
 		try {
-			const fullAppResult = await buildFullApp(minimalAppResult, deps);
+			const PHASE2_TIMEOUT_MS = 120_000;
+			const fullAppResult = await Promise.race([
+				buildFullApp(minimalAppResult, deps),
+				new Promise<never>((_, reject) =>
+					setTimeout(
+						() => reject(new Error(`buildFullApp timed out after ${PHASE2_TIMEOUT_MS / 1000}s — phase 2 hung silently, see step logs`)),
+						PHASE2_TIMEOUT_MS,
+					),
+				),
+			]);
 			const fullBuildTime = Date.now();
 			const fullDuration = fullBuildTime - startTime;
 

package/src/ws-boot-self-test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Post-listen WebSocket self-test. Runs after serveStart binds the port.
+ * For each declared websocket_routes path, opens a synthetic WebSocket
+ * connection and asserts 101 upgrade. Non-101 → BootFatalError.
+ *
+ * This catches the class of bugs where:
+ * - WS route registered after ORPC catch-all (order-dependent 404)
+ * - fetchWithPeerPort clones the Request on WS upgrade (breaks Bun.upgrade identity)
+ * - websocket_routes config row is stale / missing a handler
+ *
+ * Runs synchronously after serveStart so the boot aborts before the service
+ * reports healthy.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+export declare function runWsBootSelfTest(config: ServiceInstallConfig, serviceSlug: string, port: number): Promise<void>;