@sigil-dev/grimoire 0.4.0 → 0.6.0

package/src/types.ts

@@ -1,3 +1,14 @@
+import type { ServerWebSocket } from "bun";
+import type { RouteFile, RouteTree } from "./routing/scanner";
+
+/// <reference types="bun-types">
+declare global {
+	namespace App {
+		// augment in your own project
+		interface Locals {}
+	}
+}
+
 export interface Route {
 	path: string; // /blog/:slug
 	params: Record<string, string>;
@@ -48,7 +59,7 @@ export interface GrimoirePlugin {
 
 	// server lifecycle
 	onStart?(server: Server): void | Promise<void>;
-	onStop?(): void | Promise<void>;
+	onStop?(reason: "shutdown" | "restart"): void | Promise<void>;
 
 	// request pipeline
 	onRequest?(
@@ -58,6 +69,13 @@ export interface GrimoirePlugin {
 
 	// route lifecycle
 	onRouteLoad?(route: Route, context: LoadContext): void | Promise<void>;
+	/**
+	 * Called after the page HTML is fully rendered.
+	 * NOTE: When any plugin implements this hook, the streaming response is
+	 * buffered into a single string. Streaming is preserved for routes where
+	 * no plugin uses this hook. To avoid buffering, use onRequest to intercept
+	 * at the Response level.
+	 */
 	onRouteRender?(
 		html: string,
 		context: RenderContext,
@@ -69,6 +87,79 @@ export interface GrimoirePlugin {
 
 	// config
 	config?: (config: GrimoireConfig) => GrimoireConfig | undefined;
+
+	// process lifecycle
+
+	/**
+	 * Runs AFTER Sigil/Babel compilation. Receives compiled JS, not source TSX.
+	 * Suitable for string-level transforms (import rewriting, comment injection, etc.).
+	 * Return null/undefined to pass through unchanged.
+	 */
+	transform?(
+		code: string,
+		id: string,
+	): string | null | undefined | Promise<string | null | undefined>;
+
+	/**
+	 * Fires once after all workers are spawned and ready.
+	 * Use for coordinator-level setup (e.g. opening a shared store).
+	 */
+	onCoordinatorStart?(ctx: CoordinatorContext): void | Promise<void>;
+
+	/**
+	 * Fires for each worker before Bun.spawn is called.
+	 * Return WorkerEnv to inject env vars or set the worker name.
+	 * ALL plugins are called and results are merged.
+	 */
+	// biome-ignore lint/suspicious/noConfusingVoidType: doesn't have to return a thing.
+	onWorkerSpawn?(
+		worker: WorkerDescriptor,
+	): WorkerEnv | void | Promise<WorkerEnv | void>;
+
+	/**
+	 * Fires when a worker process is up and accepting requests.
+	 */
+	onWorkerReady?(worker: WorkerDescriptor): void | Promise<void>;
+
+	/**
+	 * Fires when a worker process exits.
+	 * reason "crash" = unexpected exit, "intentional" = coordinator stopped it.
+	 * Use for cleanup or respawn logic (see plugin-scale).
+	 */
+	onWorkerDeath?(
+		worker: WorkerDescriptor,
+		reason: "crash" | "intentional",
+	): void | Promise<void>;
+
+	// ── Locals boundary ────────────────────────────────────────
+
+	/**
+	 * Called by coordinator before forwarding a request to a worker.
+	 * Return a serialized string representation of locals.
+	 * First plugin to return non-null wins. Default: signed JSON header.
+	 */
+	serializeLocals?(locals: App.Locals): string | Promise<string>;
+
+	/**
+	 * Called by worker on receiving a forwarded request.
+	 * Return the deserialized locals object.
+	 * First plugin to return non-null wins. Default: verify + JSON.parse.
+	 */
+	deserializeLocals?(raw: string): App.Locals | Promise<App.Locals>;
+
+	// ── Routing policy ─────────────────────────────────────────
+
+	/**
+	 * Called by coordinator to decide which worker handles a request.
+	 * First plugin to return non-null wins.
+	 * Default: ws routes → consistent hash, everything else → round robin.
+	 * routes is the full RouteTree so plugins can make route-aware decisions.
+	 */
+	routeRequest?(
+		req: Request,
+		workers: WorkerDescriptor[],
+		routes: RouteTree,
+	): WorkerDescriptor | Promise<WorkerDescriptor>;
 }
 
 export interface GrimoireConfig {
@@ -78,8 +169,92 @@ export interface GrimoireConfig {
 	routes?: string; // glob, default 'src/routes/**';
 	dev?: boolean;
 	vitePort?: number;
+	_skipBuild?: boolean;
 }
 
 export function defineConfig(config: GrimoireConfig): GrimoireConfig {
 	return config;
 }
+
+/** Generic load type for +page.server.ts. For per-route typed params import PageServerLoad from './$types'. */
+export type PageServerLoad<
+	P extends Record<string, string> = Record<string, string>,
+> = (
+	ctx: TypedLoadContext<P>,
+) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Generic load type for +layout.server.ts. For per-route typed params import LayoutServerLoad from './$types'. */
+export type LayoutServerLoad<
+	P extends Record<string, string> = Record<string, string>,
+> = (
+	ctx: TypedLoadContext<P>,
+) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Generic handler type for +server.ts API routes. For per-route typed params import RequestHandler from './$types'. */
+export type RequestHandler<
+	P extends Record<string, string> = Record<string, string>,
+> = (ctx: TypedLoadContext<P>) => Response | Promise<Response>;
+
+/**
+ * Shape of the `websocket` export in a +server.ts file.
+ * T is the resolved ws.data shape (params + upgrade() return value).
+ * For per-route typing import WebSocketHandler from './$types'.
+ */
+export interface WsRouteHandler<T = Record<string, unknown>> {
+	open?(ws: ServerWebSocket<T>): void | Promise<void>;
+	message?(ws: ServerWebSocket<T>, data: string | Buffer): void | Promise<void>;
+	close?(
+		ws: ServerWebSocket<T>,
+		code: number,
+		reason?: string,
+	): void | Promise<void>;
+	drain?(ws: ServerWebSocket<T>): void | Promise<void>;
+}
+
+// ***BIG ONE***
+
+/**
+ * Built-in worker modes understood by the coordinator.
+ * Plugins may define custom modes via WorkerMode.
+ */
+export type BuiltinWorkerMode = "api" | "frontend" | "ws" | "full";
+
+/**
+ * Open union — (string & {}) preserves autocomplete for built-in
+ * values while allowing plugin-defined modes like "db" or "queue".
+ */
+export type WorkerMode = BuiltinWorkerMode | (string & {});
+
+/**
+ * Describes a single worker process managed by the coordinator.
+ * Coordinator derives behavior from routes, not mode string —
+ * mode is informational and for plugin use only.
+ */
+export interface WorkerDescriptor {
+	mode: WorkerMode;
+	index: number; // index within this mode (api-0, api-1...)
+	globalIndex: number; // index across all workers
+	internalUrl: string; // coordinator → worker base URL
+	name?: string; // set by namepool or onWorkerSpawn
+	routes: RouteFile[]; // route slice assigned by coordinator
+	pid?: number; // set after Bun.spawn
+}
+
+/**
+ * Return value of onWorkerSpawn. All plugins are called and results
+ * are merged — env from all plugins is combined, last name wins.
+ */
+export interface WorkerEnv {
+	env?: Record<string, string>;
+	name?: string;
+}
+
+/**
+ * Passed to onCoordinatorStart once the coordinator is fully initialized.
+ */
+export interface CoordinatorContext {
+	workers: WorkerDescriptor[];
+	port: number;
+	secret: string; // ephemeral signing secret, generated per-run
+	routes: RouteTree;
+}

package/test/context.test.ts

@@ -1,7 +1,7 @@
 // packages/grimoire/src/context.test.ts
 import { describe, expect, test } from "bun:test";
 import { createContext, getContext, setContext } from "@sigil-dev/runtime";
-import { runWithContext } from "../src/context";
+import { runWithContext } from "../src/server/context";
 
 const UserKey = createContext<string>();
 const ThemeKey = createContext<string>();

package/test/fail.test.ts

@@ -1,46 +1,46 @@
-import { describe, expect, test } from "bun:test";
-import { fail, isFailResult } from "../src/fail";
-
-describe("fail()", () => {
-	test("returns a FailResult with status and data", () => {
-		const result = fail(400, { name: "required" });
-		expect(result).toEqual({
-			__fail: true,
-			status: 400,
-			data: { name: "required" },
-		});
-	});
-
-	test("isFailResult returns true for fail()", () => {
-		const result = fail(422, { errors: { email: "invalid" } });
-		expect(isFailResult(result)).toBe(true);
-	});
-
-	test("isFailResult returns false for plain objects", () => {
-		expect(isFailResult({ redirect: "/foo" })).toBe(false);
-		expect(isFailResult(null)).toBe(false);
-		expect(isFailResult(undefined)).toBe(false);
-		expect(isFailResult("string")).toBe(false);
-	});
-
-	test("preserves complex data structures", () => {
-		const data = {
-			formData: { email: "test@example.com", name: "" },
-			errors: {
-				name: "Name is required",
-				email: null,
-			},
-			timestamp: Date.now(),
-		};
-		const result = fail(400, data);
-		expect(result.data).toEqual(data);
-		expect(result.status).toBe(400);
-	});
-
-	test("works with different status codes", () => {
-		expect(fail(400, {}).status).toBe(400);
-		expect(fail(403, {}).status).toBe(403);
-		expect(fail(422, {}).status).toBe(422);
-		expect(fail(500, {}).status).toBe(500);
-	});
-});
+import { describe, expect, test } from "bun:test";
+import { fail, isFailResult } from "../src/sentinels/fail.ts";
+
+describe("fail()", () => {
+	test("returns a FailResult with status and data", () => {
+		const result = fail(400, { name: "required" });
+		expect(result).toEqual({
+			__fail: true,
+			status: 400,
+			data: { name: "required" },
+		});
+	});
+
+	test("isFailResult returns true for fail()", () => {
+		const result = fail(422, { errors: { email: "invalid" } });
+		expect(isFailResult(result)).toBe(true);
+	});
+
+	test("isFailResult returns false for plain objects", () => {
+		expect(isFailResult({ redirect: "/foo" })).toBe(false);
+		expect(isFailResult(null)).toBe(false);
+		expect(isFailResult(undefined)).toBe(false);
+		expect(isFailResult("string")).toBe(false);
+	});
+
+	test("preserves complex data structures", () => {
+		const data = {
+			formData: { email: "test@example.com", name: "" },
+			errors: {
+				name: "Name is required",
+				email: null,
+			},
+			timestamp: Date.now(),
+		};
+		const result = fail(400, data);
+		expect(result.data).toEqual(data);
+		expect(result.status).toBe(400);
+	});
+
+	test("works with different status codes", () => {
+		expect(fail(400, {}).status).toBe(400);
+		expect(fail(403, {}).status).toBe(403);
+		expect(fail(422, {}).status).toBe(422);
+		expect(fail(500, {}).status).toBe(500);
+	});
+});

package/test/headers.test.ts

@@ -1,96 +1,100 @@
-import { describe, expect, test } from "bun:test";
-import { securityHeaders } from "../src/headers";
-
-function fakeRequest(path = "/") {
-	return new Request(`http://localhost${path}`);
-}
-
-async function runPlugin(
-	config: Parameters<typeof securityHeaders>[0],
-	req?: Request,
-): Promise<Headers> {
-	const plugin = securityHeaders(config);
-	const res = new Response("<html></html>", {
-		headers: { "Content-Type": "text/html" },
-	});
-	const result = await plugin.onRequest!(req ?? fakeRequest(), async () => res);
-	return result.headers;
-}
-
-describe("securityHeaders()", () => {
-	test("applies default headers", async () => {
-		const headers = await runPlugin({});
-		expect(headers.get("X-Content-Type-Options")).toBe("nosniff");
-		expect(headers.get("X-Frame-Options")).toBe("DENY");
-		expect(headers.get("Referrer-Policy")).toBe("strict-origin-when-cross-origin");
-		expect(headers.get("Permissions-Policy")).toBe(
-			"camera=(), microphone=(), geolocation=()",
-		);
-		expect(headers.get("X-XSS-Protection")).toBe("0");
-	});
-
-	test("applies CSP by default", async () => {
-		const headers = await runPlugin({});
-		expect(headers.get("Content-Security-Policy")).toContain("default-src 'self'");
-	});
-
-	test("allows overriding individual headers", async () => {
-		const headers = await runPlugin({
-			frameOptions: "SAMEORIGIN",
-			contentTypeOptions: false,
-		});
-		expect(headers.get("X-Frame-Options")).toBe("SAMEORIGIN");
-		expect(headers.has("X-Content-Type-Options")).toBe(false);
-	});
-
-	test("disables headers when set to false", async () => {
-		const headers = await runPlugin({
-			contentSecurityPolicy: false,
-			strictTransportSecurity: false,
-			permissionsPolicy: false,
-		});
-		expect(headers.has("Content-Security-Policy")).toBe(false);
-		expect(headers.has("Strict-Transport-Security")).toBe(false);
-		expect(headers.has("Permissions-Policy")).toBe(false);
-	});
-
-	test("applies route overrides", async () => {
-		const headers = await runPlugin(
-			{
-				frameOptions: "DENY",
-				routes: {
-					"/admin": { frameOptions: "SAMEORIGIN" },
-				},
-			},
-			fakeRequest("/admin/settings"),
-		);
-		expect(headers.get("X-Frame-Options")).toBe("SAMEORIGIN");
-	});
-
-	test("route override only applies to matching prefix", async () => {
-		const headers = await runPlugin(
-			{
-				frameOptions: "DENY",
-				routes: {
-					"/admin": { frameOptions: "SAMEORIGIN" },
-				},
-			},
-			fakeRequest("/dashboard"),
-		);
-		expect(headers.get("X-Frame-Options")).toBe("DENY");
-	});
-
-	test("preserves existing response headers", async () => {
-		const plugin = securityHeaders({});
-		const res = new Response("<html></html>", {
-			headers: {
-				"Content-Type": "text/html",
-				"Set-Cookie": "session=abc",
-			},
-		});
-		const result = await plugin.onRequest!(fakeRequest(), async () => res);
-		expect(result.headers.get("Content-Type")).toBe("text/html");
-		expect(result.headers.get("Set-Cookie")).toBe("session=abc");
-		expect(result.headers.get("X-Frame-Options")).toBe("DENY");
-	});
-});
+import { describe, expect, test } from "bun:test";
+import { securityHeaders } from "../src/headers";
+
+function fakeRequest(path = "/") {
+	return new Request(`http://localhost${path}`);
+}
+
+async function runPlugin(
+	config: Parameters<typeof securityHeaders>[0],
+	req?: Request,
+): Promise<Headers> {
+	const plugin = securityHeaders(config);
+	const res = new Response("<html></html>", {
+		headers: { "Content-Type": "text/html" },
+	});
+	const result = await plugin.onRequest!(req ?? fakeRequest(), async () => res);
+	return result.headers;
+}
+
+describe("securityHeaders()", () => {
+	test("applies default headers", async () => {
+		const headers = await runPlugin({});
+		expect(headers.get("X-Content-Type-Options")).toBe("nosniff");
+		expect(headers.get("X-Frame-Options")).toBe("DENY");
+		expect(headers.get("Referrer-Policy")).toBe(
+			"strict-origin-when-cross-origin",
+		);
+		expect(headers.get("Permissions-Policy")).toBe(
+			"camera=(), microphone=(), geolocation=()",
+		);
+		expect(headers.get("X-XSS-Protection")).toBe("0");
+	});
+
+	test("applies CSP by default", async () => {
+		const headers = await runPlugin({});
+		expect(headers.get("Content-Security-Policy")).toContain(
+			"default-src 'self'",
+		);
+	});
+
+	test("allows overriding individual headers", async () => {
+		const headers = await runPlugin({
+			frameOptions: "SAMEORIGIN",
+			contentTypeOptions: false,
+		});
+		expect(headers.get("X-Frame-Options")).toBe("SAMEORIGIN");
+		expect(headers.has("X-Content-Type-Options")).toBe(false);
+	});
+
+	test("disables headers when set to false", async () => {
+		const headers = await runPlugin({
+			contentSecurityPolicy: false,
+			strictTransportSecurity: false,
+			permissionsPolicy: false,
+		});
+		expect(headers.has("Content-Security-Policy")).toBe(false);
+		expect(headers.has("Strict-Transport-Security")).toBe(false);
+		expect(headers.has("Permissions-Policy")).toBe(false);
+	});
+
+	test("applies route overrides", async () => {
+		const headers = await runPlugin(
+			{
+				frameOptions: "DENY",
+				routes: {
+					"/admin": { frameOptions: "SAMEORIGIN" },
+				},
+			},
+			fakeRequest("/admin/settings"),
+		);
+		expect(headers.get("X-Frame-Options")).toBe("SAMEORIGIN");
+	});
+
+	test("route override only applies to matching prefix", async () => {
+		const headers = await runPlugin(
+			{
+				frameOptions: "DENY",
+				routes: {
+					"/admin": { frameOptions: "SAMEORIGIN" },
+				},
+			},
+			fakeRequest("/dashboard"),
+		);
+		expect(headers.get("X-Frame-Options")).toBe("DENY");
+	});
+
+	test("preserves existing response headers", async () => {
+		const plugin = securityHeaders({});
+		const res = new Response("<html></html>", {
+			headers: {
+				"Content-Type": "text/html",
+				"Set-Cookie": "session=abc",
+			},
+		});
+		const result = await plugin.onRequest!(fakeRequest(), async () => res);
+		expect(result.headers.get("Content-Type")).toBe("text/html");
+		expect(result.headers.get("Set-Cookie")).toBe("session=abc");
+		expect(result.headers.get("X-Frame-Options")).toBe("DENY");
+	});
+});

package/test/hydration.test.ts

@@ -38,7 +38,7 @@ function runHydrate(routes: Record<string, (props: any) => any>) {
 	}
 }
 
-// simulate initRouter (same logic as client-router.ts)
+// simulate initRouter (same logic as router.ts)
 let clickHandlerAttached = false;
 function initRouter(routes: Record<string, (props: any) => any>) {
 	document.addEventListener("click", () => {});