@teamscala/service-boot 0.23.329 → 0.23.331

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/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>;

package/src/auth-gate.test.ts

@@ -1,70 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * The signed-out screen must be able to render its own branding.
- */
-
-import { describe, expect, test } from "bun:test";
-import { isStaticAssetPath } from "./auth-gate.ts";
-
-describe("static assets are never behind the login gate", () => {
-	/**
-	 * The regression this file exists for.
-	 *
-	 * Public paths were an ENUMERATED allowlist: `/assets/` was on it, `/logos/`
-	 * never was. So `/logos/cropped.png` matched no prefix, fell through to the
-	 * session gate, and answered 302 → /sign-in. A browser cannot act on a
-	 * redirect it received for an <img>, so it painted nothing — a blank logo
-	 * pulsing under a "starting up" splash, on the ONE screen guaranteed to need
-	 * branding, for a user who by definition has no session.
-	 *
-	 * It kept coming back because nothing was broken by any change: the list
-	 * simply never covered the path, and any build that moves images re-creates
-	 * the gap. Enumerating what is public makes every new asset private by
-	 * default; a predicate makes that unrepresentable.
-	 */
-	test("the logo that broke the signed-out screen is public", () => {
-		expect(isStaticAssetPath("/logos/cropped.png")).toBe(true);
-		expect(isStaticAssetPath("/logos/companyLogo.png")).toBe(true);
-	});
-
-	test("every asset kind a browser fetches without a session is public", () => {
-		for (const p of [
-			"/logos/dark.svg",
-			"/img/hero.webp",
-			"/brand/mark.avif",
-			"/fonts/inter.woff2",
-			"/styles/main.css",
-			"/assets/chunk-4efmn1eh.js",
-			"/favicon.ico",
-		]) {
-			expect(isStaticAssetPath(p)).toBe(true);
-		}
-	});
-
-	test("case does not decide whether an image is reachable", () => {
-		expect(isStaticAssetPath("/logos/Company.PNG")).toBe(true);
-		expect(isStaticAssetPath("/logos/Mark.SVG")).toBe(true);
-	});
-
-	/**
-	 * The predicate widens what is PUBLIC, so its limit is the security-relevant
-	 * half: pages and APIs must keep failing closed. A path is an asset because
-	 * of its EXTENSION, never because it merely contains an asset-looking word.
-	 */
-	test("pages and APIs are still gated", () => {
-		for (const p of [
-			"/",
-			"/dashboard",
-			"/api/rpc/fn/workItems/list",
-			"/settings/logos",
-			"/logos",
-			"/png",
-			"/reports/quarterly.pdf",
-		]) {
-			expect(isStaticAssetPath(p)).toBe(false);
-		}
-	});
-});

package/src/fn-routers/task-sync-lane.test.ts

@@ -1,36 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Behavioral tests for canonical CLI-session lane resolution.
- */
-import { describe, expect, it } from "bun:test";
-import { resolveLaneWorkName } from "./task-sync-lane.ts";
-
-describe("resolveLaneWorkName", () => {
-	it("reads the visible label from the active cli_sessions route", async () => {
-		let query: unknown;
-		const name = await resolveLaneWorkName(
-			{
-				cli_sessions: {
-					findFirst: async (args: unknown) => {
-						query = args;
-						return { id: "session-1", label: "ZeroStack" };
-					},
-				},
-			} as never,
-			"tmux:%7",
-		);
-		expect(name).toBe("ZeroStack");
-		expect(query).toMatchObject({ where: { host_route: { path: ["pane_id"], equals: "tmux:%7" } } });
-	});
-
-	it("returns no unverified title when no active session owns the pane", async () => {
-		const name = await resolveLaneWorkName(
-			{ cli_sessions: { findFirst: async () => null } } as never,
-			"tmux:%8",
-		);
-		expect(name).toBeNull();
-	});
-});

package/src/handlers/sweep-host-cache.test.ts

@@ -1,133 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * Unit tests for the `retention_dirs` helpers (`expandGlob`, `checkDirStale`) —
- * the whole-directory prune that bounds Rust `target/` waste. The file-by-mtime
- * `retention` path is unchanged; these cover ONLY the new build-cache model:
- * (1) glob expansion reaches every repo's target dir; (2) an actively-built dir
- * is kept (short-circuits on a fresh file); (3) an abandoned dir is reported
- * stale with its full size. Lives next to the handler per co-located-test rule.
- */
-import { describe, expect, test, beforeEach, afterEach } from "bun:test";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { expandGlob, checkDirStale, parseRootDiskPct } from "./sweep-host-cache.ts";
-
-const DAY = 86_400_000;
-const now = Date.now();
-const daysAgo = (n: number) => new Date(now - n * DAY);
-const touch = (p: string, t: Date) => utimesSync(p, t, t);
-
-let root: string;
-beforeEach(() => {
-	root = mkdtempSync(join(tmpdir(), "sweep-"));
-});
-afterEach(() => {
-	rmSync(root, { recursive: true, force: true });
-});
-
-describe("expandGlob", () => {
-	test("expands a single-segment wildcard to concrete dirs", () => {
-		mkdirSync(join(root, "scala-rust", "target"), { recursive: true });
-		mkdirSync(join(root, "scala-os", "target"), { recursive: true });
-		mkdirSync(join(root, "scala-os", "src"), { recursive: true });
-		const matches = expandGlob(`${root}/*/target`).sort();
-		expect(matches).toEqual(
-			[join(root, "scala-os", "target"), join(root, "scala-rust", "target")].sort(),
-		);
-	});
-	test("literal segment matches only itself", () => {
-		mkdirSync(join(root, "scala-rust", "target"), { recursive: true });
-		mkdirSync(join(root, "other", "target"), { recursive: true });
-		const matches = expandGlob(`${root}/scala-rust/target`);
-		expect(matches).toEqual([join(root, "scala-rust", "target")]);
-	});
-	test("no matches when the wildcard segment has no children", () => {
-		const matches = expandGlob(`${root}/does-not-exist/*/target`);
-		expect(matches).toEqual([]);
-	});
-});
-
-describe("checkDirStale", () => {
-	test("stale dir: all files older than cutoff → stale + full size", async () => {
-		const dir = join(root, "target");
-		mkdirSync(join(dir, "debug", "deps"), { recursive: true });
-		writeFileSync(join(dir, "debug", "deps", "a.o"), "x".repeat(40));
-		writeFileSync(join(dir, "debug", "deps", "b.o"), "y".repeat(60));
-		touch(join(dir, "debug", "deps", "a.o"), daysAgo(40));
-		touch(join(dir, "debug", "deps", "b.o"), daysAgo(35));
-		const res = await checkDirStale(dir, now - 30 * DAY);
-		expect(res.stale).toBe(true);
-		expect(res.fileCount).toBe(2);
-		expect(res.bytes).toBe(100);
-	});
-	test("active dir: a file newer than cutoff → not stale (short-circuit)", async () => {
-		const dir = join(root, "target");
-		mkdirSync(join(dir, "debug"), { recursive: true });
-		writeFileSync(join(dir, "debug", "old.o"), "x".repeat(40));
-		touch(join(dir, "debug", "old.o"), daysAgo(40));
-		writeFileSync(join(dir, "debug", "fresh.o"), "y".repeat(60));
-		touch(join(dir, "debug", "fresh.o"), daysAgo(1));
-		const res = await checkDirStale(dir, now - 30 * DAY);
-		expect(res.stale).toBe(false);
-	});
-	test("empty dir → stale with zero bytes", async () => {
-		const dir = join(root, "target");
-		mkdirSync(dir, { recursive: true });
-		const res = await checkDirStale(dir, now - 30 * DAY);
-		expect(res.stale).toBe(true);
-		expect(res.bytes).toBe(0);
-		expect(res.fileCount).toBe(0);
-	});
-});
-
-describe("parseRootDiskPct", () => {
-	test("extracts root-fs Use% from df --output=pcent,target output", () => {
-		const df =
-			"Use% Mounted on\n" +
-			"  97% /\n" +
-			"  45% /home\n";
-		expect(parseRootDiskPct(df)).toBe(97);
-	});
-	test("picks the root mount (/) over nested mounts", () => {
-		const df =
-			"Use% Mounted on\n" +
-			"  10% /proc/x\n" +
-			"  76% /\n";
-		expect(parseRootDiskPct(df)).toBe(76);
-	});
-	test("returns null when no root-mount line present", () => {
-		const df = "Use% Mounted on\n  40% /mnt/other\n";
-		expect(parseRootDiskPct(df)).toBeNull();
-	});
-	test("returns null on empty / malformed output", () => {
-		expect(parseRootDiskPct("")).toBeNull();
-		expect(parseRootDiskPct("Use% Mounted on")).toBeNull();
-	});
-});
-
-describe("disk-threshold early-warning regression lock", () => {
-	const { readFileSync } = require("node:fs");
-	// Source-shape lock (same pattern as singleton-tools-currency-watch.test.ts):
-	// the df-check that rides this periodic sweep was once removed in favour of an
-	// in-process interval watchdog — the wrong architecture (interval watchdogs
-	// are forbidden; observability is event-driven). This asserts the corrected
-	// shape survives: the sweep handler MUST carry the event-driven host.disk.high
-	// emission (logger.warn -> GlitchTip) + the pure parseRootDiskPct helper that
-	// backs it. Removing either fails this test. The asserted surface is the
-	// disk early-warning cell of host-resources-have-complete-monitoring.
-	const src = readFileSync(import.meta.dir + "/sweep-host-cache.ts", "utf-8");
-	test("handler emits the host.disk.high event (event-driven, not an interval)", () => {
-		expect(src).toContain('log.warn("host.disk.high"');
-		expect(src).toContain('kind: "host.disk.high"');
-	});
-	test("handler reads df via the sanctioned spawn (no in-process poller)", () => {
-		expect(src).toContain('command: ["df", "--output=pcent,target"]');
-	});
-	test("threshold parse is the exported pure helper", () => {
-		expect(src).toContain("export function parseRootDiskPct");
-	});
-});

package/src/serve/stamp-transport-identity.test.ts

@@ -1,24 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { summariseLocalCommand } from "./stamp-transport-identity.ts";
-
-describe("local command attribution", () => {
-	test("never copies command arguments into telemetry", () => {
-		const token = "operator-token-must-not-appear";
-		const summary = summariseLocalCommand([
-			"curl",
-			"-H",
-			`x-operator-spawn-token: ${token}`,
-			"http://127.0.0.1:3021/rpc/spawn",
-		]);
-		expect(summary).toBe("curl [arguments redacted]");
-		expect(summary).not.toContain(token);
-	});
-
-	test("keeps a lone executable name", () => {
-		expect(summariseLocalCommand(["scala-picker"])).toBe("scala-picker");
-	});
-
-	test("omits an empty command line", () => {
-		expect(summariseLocalCommand([])).toBeNull();
-	});
-});

package/src/two-phase-health-gate-client-only.test.ts

@@ -1,77 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * A CLIENT-ONLY service (`render_mode=client`) must reach ready, even though it
- * never registers an SSR page handler.
- *
- * Separate file from `two-phase-health-gate.test.ts` on purpose: `fullAppReady`
- * is module state that only transitions false -> true and has no reset hook, so
- * the two ready-paths cannot both be exercised in one module instance. A reset
- * hook would exist only for tests.
- *
- * THE REGRESSION THIS LOCKS (measured 2026-08-07 on scala-agents-ui). Readiness
- * used to be flipped INSIDE `setPageHandler`, which was honest while every
- * service was SSR. `render_mode=client` made a service that completes phase 2
- * and never calls it, so `/health` answered `{"status":"starting"}` FOREVER
- * while the process was healthy and serving — boot completed in 5023ms, "Full
- * app built: 50 block(s)" logged, `GET /` correctly 302'd to sign-in, and three
- * untouched UI services reported ok beside it.
- *
- * That is precisely what `readiness-gated-boot` forbids ("binary: fully-ready or
- * cleanly-unavailable"): a permanently-un-ready health signal makes the
- * activator's wake gate and every health-gated router treat a working service as
- * down. Exercised through a real Hono request against the REAL exported handler
- * (`proxy-is-not-behaviour`) — a source grep would prove the call exists, never
- * that the endpoint answers 200.
- */
-
-import { beforeAll, describe, expect, test } from "bun:test";
-import { Hono } from "hono";
-import {
-	__resetPhase2StateForTest,
-	getPageHandlerState,
-	healthHandler,
-	markFullAppReady,
-} from "./two-phase-boot.ts";
-
-/** Mount the real handler exactly as buildMinimalApp does. */
-const app = new Hono().get("/health", healthHandler);
-
-describe("/health for a client-only service", () => {
-	// Bun shares one module instance across every test file in a run, so the SSR
-	// readiness test's setPageHandler leaks into this file when both run together.
-	// Without this reset the suite passes file-by-file and fails in CI.
-	beforeAll(() => {
-		__resetPhase2StateForTest();
-	});
-
-	test("before phase 2 completes it reports 503, not ready", async () => {
-		expect(getPageHandlerState().ready).toBe(false);
-
-		const res = await app.request("/health");
-
-		expect(res.status).toBe(503);
-		expect(await res.json()).toEqual({ status: "starting" });
-	});
-
-	test("reaches ready without an SSR page handler", async () => {
-		// The real client-only phase-2 path: buildFullApp finishes and marks the
-		// app ready WITHOUT setPageHandler, because there is no SSR handler.
-		markFullAppReady();
-
-		const state = getPageHandlerState();
-		expect(state.ready).toBe(true);
-		// The discriminator: ready is true while hasHandler stays false. Asserting
-		// both is what separates this from the SSR path — a fix that flipped ready
-		// by registering a dummy handler would pass `ready` and fail here.
-		expect(state.hasHandler).toBe(false);
-
-		const res = await app.request("/health");
-
-		expect(res.status).toBe(200);
-		expect(res.ok).toBe(true);
-		expect(await res.json()).toEqual({ status: "ok" });
-	});
-});