@sigil-dev/grimoire 0.4.0 → 0.6.0

package/src/{transform-routes.ts → routing/transform-routes.ts}

@@ -1,6 +1,7 @@
 import { transformSync } from "@babel/core";
 import sigilPlugin from "@sigil-dev/compiler/babel";
 import { basename, dirname, join, relative, resolve } from "path";
+import type { GrimoirePlugin } from "../types";
 import type { RouteFile } from "./scanner";
 
 const STYLE_RE = /<style[^>]*>([\s\S]*?)<\/style>/gi;
@@ -56,6 +57,7 @@ export async function transformRoutes(
 	routes: RouteFile[],
 	outDir: string,
 	mode: "hydrate" | "dom",
+	plugins: GrimoirePlugin[] = [],
 ): Promise<Map<string, string>> {
 	const map = new Map<string, string>();
 	const transpiler = new Bun.Transpiler({ loader: "tsx", target: "browser" });
@@ -76,7 +78,11 @@ export async function transformRoutes(
 				],
 				filename: route.filePath,
 			});
-			const out = transpiler.transformSync(res?.code ?? "");
+			let out = transpiler.transformSync(res?.code ?? "");
+			for (const plugin of plugins) {
+				if (plugin.transform)
+					out = (await plugin.transform(out, route.filePath)) ?? out;
+			}
 			const rel = relative(process.cwd(), route.filePath)
 				.replace(/\.[cm]?[jt]sx?$/, "")
 				.replace(/[^a-zA-Z0-9._-]/g, "_");

package/src/{fail.ts → sentinels/fail.ts}

@@ -35,7 +35,7 @@ export function isFailResult(value: unknown): value is FailResult {
 	return (
 		typeof value === "object" &&
 		value !== null &&
-		 "__fail" in value &&
+		"__fail" in value &&
 		(value as any).__fail === true
 	);
 }

package/src/server/build.ts

@@ -0,0 +1,90 @@
+import { sigil } from "@sigil-dev/compiler/bun";
+import { mkdir } from "fs/promises";
+import { isAbsolute, join } from "path";
+import { generateManifest } from "../routing/manifest-gen";
+import type { RouteTree } from "../routing/scanner";
+import { scanRoutes } from "../routing/scanner";
+import { transformRoutes } from "../routing/transform-routes";
+import { generateTypes } from "../typegen";
+import type { BuildResult, GrimoireConfig, GrimoirePlugin } from "../types";
+import { runHook } from "./plugins";
+
+export async function buildProject(
+	config: GrimoireConfig,
+	plugins: GrimoirePlugin[] = [],
+): Promise<{ result: BuildResult; tree: RouteTree }> {
+	await runHook(plugins, "onBuildStart");
+
+	const { routes = "src/routes" } = config;
+
+	const routesDir = isAbsolute(routes)
+		? routes.replace(/\0/g, "")
+		: join(process.cwd(), routes).replace(/\0/g, "");
+	const tree = await scanRoutes(routesDir, process.cwd());
+
+	await mkdir(join(process.cwd(), ".grimoire"), { recursive: true });
+
+	await generateTypes(tree, {
+		projectRoot: process.cwd(),
+		routesDir,
+		outDir: join(process.cwd(), ".grimoire/types"),
+	});
+
+	const compiledDir = join(process.cwd(), ".grimoire/compiled");
+	await mkdir(compiledDir, { recursive: true });
+
+	const pageRoutes = tree.routes.filter(
+		(r) => r.type === "page" || r.type === "simple",
+	);
+	const [hydrateFiles, domFiles] = await Promise.all([
+		transformRoutes(pageRoutes, compiledDir, "hydrate", plugins),
+		transformRoutes(pageRoutes, compiledDir, "dom", plugins),
+	]);
+
+	const hydrateManifest = join(process.cwd(), ".grimoire/_routes.hydrate.js");
+	const domManifest = join(process.cwd(), ".grimoire/_routes.dom.js");
+	await Promise.all([
+		Bun.write(hydrateManifest, generateManifest(pageRoutes, hydrateFiles)),
+		Bun.write(domManifest, generateManifest(pageRoutes, domFiles)),
+	]);
+
+	const makeRoutesPlugin = (manifestPath: string) => ({
+		name: "grimoire-routes",
+		setup(build: any) {
+			build.onResolve({ filter: /^#grimoire-routes$/ }, () => ({
+				path: manifestPath,
+			}));
+		},
+	});
+
+	const [hydrateResult, domResult] = await Promise.all([
+		Bun.build({
+			entrypoints: [join(import.meta.dir, "../rendering/hydrate.ts")],
+			outdir: join(process.cwd(), "public/__grimoire__"),
+			plugins: [sigil({ mode: "hydrate" }), makeRoutesPlugin(hydrateManifest)],
+		}),
+		Bun.build({
+			entrypoints: [join(import.meta.dir, "../client/index.ts")],
+			outdir: join(process.cwd(), "public/__grimoire__"),
+			plugins: [sigil({ mode: "dom" }), makeRoutesPlugin(domManifest)],
+		}),
+	]);
+
+	if (!hydrateResult.success) {
+		for (const log of hydrateResult.logs) console.error(log);
+	}
+	if (!domResult.success) {
+		for (const log of domResult.logs) console.error(log);
+	}
+
+	const result: BuildResult = {
+		success: hydrateResult.success && domResult.success,
+		outputs: [...hydrateResult.outputs, ...domResult.outputs].map(
+			(o) => o.path,
+		),
+		errors: [...hydrateResult.logs, ...domResult.logs].map(String),
+	};
+
+	await runHook(plugins, "onBuildEnd", result);
+	return { result, tree };
+}

package/src/{cookie-utils.ts → server/cookie-utils.ts}

@@ -1,66 +1,66 @@
-/**
- * Parse cookies from a Cookie header string.
- */
-export function parseCookies(cookieHeader: string): Map<string, string> {
-	const map = new Map<string, string>();
-	if (!cookieHeader) return map;
-	for (const pair of cookieHeader.split(";")) {
-		const [name, ...rest] = pair.split("=");
-		if (name) map.set(name.trim(), rest.join("=").trim());
-	}
-	return map;
-}
-
-/**
- * Build a Set-Cookie header from name, value, and options.
- */
-export function serializeCookie(
-	name: string,
-	value: string,
-	options?: {
-		path?: string;
-		domain?: string;
-		maxAge?: number;
-		expires?: Date;
-		httpOnly?: boolean;
-		secure?: boolean;
-		sameSite?: "strict" | "lax" | "none";
-	},
-): string {
-	let cookie = `${name}=${encodeURIComponent(value)}`;
-	if (options?.path) cookie += `; Path=${options.path}`;
-	if (options?.domain) cookie += `; Domain=${options.domain}`;
-	if (options?.maxAge != null) cookie += `; Max-Age=${options.maxAge}`;
-	if (options?.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
-	if (options?.httpOnly) cookie += "; HttpOnly";
-	if (options?.secure) cookie += "; Secure";
-	if (options?.sameSite) cookie += `; SameSite=${options.sameSite}`;
-	return cookie;
-}
-
-/**
- * Create a Cookies helper from a Cookie header string.
- */
-export function createCookies(
-	cookieHeader: string,
-): import("./hooks").Cookies & { toHeaders(): string[] } {
-	const store = parseCookies(cookieHeader);
-	const pending: string[] = [];
-
-	return {
-		get(name: string) {
-			return store.get(name);
-		},
-		set(name: string, value: string, options?: any) {
-			store.set(name, value);
-			pending.push(serializeCookie(name, value, options));
-		},
-		delete(name: string) {
-			store.delete(name);
-			pending.push(serializeCookie(name, "", { maxAge: 0 }));
-		},
-		toHeaders() {
-			return pending;
-		},
-	};
-}
+/**
+ * Parse cookies from a Cookie header string.
+ */
+export function parseCookies(cookieHeader: string): Map<string, string> {
+	const map = new Map<string, string>();
+	if (!cookieHeader) return map;
+	for (const pair of cookieHeader.split(";")) {
+		const [name, ...rest] = pair.split("=");
+		if (name) map.set(name.trim(), rest.join("=").trim());
+	}
+	return map;
+}
+
+/**
+ * Build a Set-Cookie header from name, value, and options.
+ */
+export function serializeCookie(
+	name: string,
+	value: string,
+	options?: {
+		path?: string;
+		domain?: string;
+		maxAge?: number;
+		expires?: Date;
+		httpOnly?: boolean;
+		secure?: boolean;
+		sameSite?: "strict" | "lax" | "none";
+	},
+): string {
+	let cookie = `${name}=${encodeURIComponent(value)}`;
+	if (options?.path) cookie += `; Path=${options.path}`;
+	if (options?.domain) cookie += `; Domain=${options.domain}`;
+	if (options?.maxAge != null) cookie += `; Max-Age=${options.maxAge}`;
+	if (options?.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+	if (options?.httpOnly) cookie += "; HttpOnly";
+	if (options?.secure) cookie += "; Secure";
+	if (options?.sameSite) cookie += `; SameSite=${options.sameSite}`;
+	return cookie;
+}
+
+/**
+ * Create a Cookies helper from a Cookie header string.
+ */
+export function createCookies(
+	cookieHeader: string,
+): import("./hooks").Cookies & { toHeaders(): string[] } {
+	const store = parseCookies(cookieHeader);
+	const pending: string[] = [];
+
+	return {
+		get(name: string) {
+			return store.get(name);
+		},
+		set(name: string, value: string, options?: any) {
+			store.set(name, value);
+			pending.push(serializeCookie(name, value, options));
+		},
+		delete(name: string) {
+			store.delete(name);
+			pending.push(serializeCookie(name, "", { maxAge: 0 }));
+		},
+		toHeaders() {
+			return pending;
+		},
+	};
+}

package/src/server/coordinator.ts

@@ -0,0 +1,297 @@
+import { type Subprocess, spawn } from "bun";
+import { join } from "path";
+import { matchRoute } from "../routing/router";
+import { type RouteFile, type RouteTree, scanRoutes } from "../routing/scanner";
+import type {
+	CoordinatorContext,
+	GrimoireConfig,
+	GrimoirePlugin,
+	Route,
+	WorkerDescriptor,
+	WorkerMode,
+} from "../types";
+import { buildProject } from "./build";
+import {
+	runHook,
+	runRouteRequest,
+	runSerializeLocals,
+	runWorkerSpawn,
+} from "./plugins";
+
+async function waitForWorkers(
+	workers: LiveWorker[],
+	timeoutMs = 10_000,
+): Promise<void> {
+	const ready = new Set<number>();
+	const start = Date.now();
+
+	while (ready.size < workers.length) {
+		if (Date.now() - start > timeoutMs) {
+			const pending = workers
+				.filter((w) => !ready.has(w.descriptor.globalIndex))
+				.map(
+					(w) =>
+						w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`,
+				)
+				.join(", ");
+			throw new Error(
+				`Grimoire: workers timed out waiting to become ready: ${pending}`,
+			);
+		}
+		for (const w of workers) {
+			if (ready.has(w.descriptor.globalIndex)) continue;
+			if (w.descriptor.pid != null) {
+				ready.add(w.descriptor.globalIndex);
+			}
+		}
+		await Bun.sleep(50);
+	}
+}
+
+function roundRobin(workers: WorkerDescriptor[]): WorkerDescriptor {
+	const idx = roundRobinCounter++ % workers.length;
+	return workers[idx];
+}
+let roundRobinCounter = 0;
+
+function consistentHash(
+	req: Request,
+	workers: WorkerDescriptor[],
+): WorkerDescriptor {
+	const key = req.headers.get("cookie") ?? req.url;
+	let hash = 0;
+	for (let i = 0; i < key.length; i++) {
+		hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+	}
+	return workers[hash % workers.length];
+}
+
+function defaultRoute(
+	req: Request,
+	workers: WorkerDescriptor[],
+	tree: RouteTree,
+): WorkerDescriptor {
+	const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
+
+	if (isWs) {
+		const wsWorkers = workers.filter(
+			(w) => w.mode === "ws" || w.mode === "full",
+		);
+		if (wsWorkers.length) return consistentHash(req, wsWorkers);
+	}
+
+	const url = new URL(req.url);
+	const matched = matchRoute(tree, url);
+
+	if (matched?.route.type === "server") {
+		const apiWorkers = workers.filter(
+			(w) => w.mode === "api" || w.mode === "full",
+		);
+		if (apiWorkers.length) return roundRobin(apiWorkers);
+	}
+
+	const frontendWorkers = workers.filter(
+		(w) => w.mode === "frontend" || w.mode === "full",
+	);
+	if (frontendWorkers.length) return roundRobin(frontendWorkers);
+
+	// fallback — should not happen if scale spec is valid
+	return workers[0];
+}
+
+export interface ScaleSpec {
+	api?: number;
+	frontend?: number;
+	ws?: number;
+	[mode: string]: number | undefined;
+}
+
+export interface CoordinatorOptions {
+	config: GrimoireConfig;
+	plugins: GrimoirePlugin[];
+	scale: ScaleSpec;
+	noBuild: boolean;
+}
+
+interface LiveWorker {
+	descriptor: WorkerDescriptor;
+	process: Subprocess;
+	port: number;
+}
+
+export async function startCoordinator(options: CoordinatorOptions) {
+	const { config, plugins, scale, noBuild } = options;
+	const { port = 3000, host = "localhost", routes = "src/routes" } = config;
+	let stopping = false;
+
+	// 1. build if needed
+	if (!noBuild) {
+		const { result } = await buildProject(config, plugins);
+		if (!result.success) throw new Error("Grimoire: build failed");
+	}
+
+	// 2. generate ephemeral secret
+	const secret = crypto.randomUUID() + crypto.randomUUID(); // 72 hex chars
+
+	// 3. scan routes once — coordinator owns the route tree
+	const routesDir = /* resolve */ routes;
+	const tree = await scanRoutes(routesDir, process.cwd());
+
+	// 4. derive route slices per mode
+	const slices: Record<string, RouteFile[]> = {
+		api: tree.routes.filter((r) => r.type === "server"),
+		ws: tree.routes.filter((r) => r.type === "server"),
+		frontend: tree.routes.filter(
+			(r) => r.type === "page" || r.type === "simple",
+		),
+		full: [...tree.routes],
+	};
+
+	// 5. spawn workers
+	const liveWorkers: LiveWorker[] = [];
+	let globalIndex = 0;
+	let nextPort = port + 1;
+
+	for (const [mode, count = 0] of Object.entries(scale)) {
+		for (let i = 0; i < count; i++) {
+			const workerPort = nextPort++;
+			const descriptor: WorkerDescriptor = {
+				mode: mode as WorkerMode,
+				index: i + 1,
+				globalIndex: globalIndex++,
+				internalUrl: `http://127.0.0.1:${workerPort}`,
+				routes: slices[mode] ?? slices.full,
+			};
+
+			// let plugins inject env and name
+			const workerEnv = await runWorkerSpawn(plugins, descriptor);
+			const workerEntry = join(import.meta.dir, "./worker.ts");
+			if (workerEnv.name) descriptor.name = workerEnv.name;
+
+			const proc = spawn(["bun", "run", workerEntry], {
+				env: {
+					...process.env,
+					...workerEnv.env,
+					GRIMOIRE_MODE: mode,
+					GRIMOIRE_WORKER_INDEX: String(i),
+					GRIMOIRE_WORKER_PORT: String(workerPort),
+					GRIMOIRE_INTERNAL_SECRET: secret,
+					GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
+				},
+				ipc(message) {
+					// worker sends { ready: true } when Bun.serve is up
+					if (message?.ready) {
+						descriptor.pid = proc.pid;
+						runHook(plugins, "onWorkerReady", descriptor);
+					}
+				},
+				onExit(proc, exitCode) {
+					const intentional = stopping;
+					runHook(
+						plugins,
+						"onWorkerDeath",
+						descriptor,
+						intentional ? "intentional" : "crash",
+					);
+					if (!intentional) {
+						console.error(
+							`[grimoire] worker ${descriptor.name ?? descriptor.mode + "-" + descriptor.index} crashed (exit ${exitCode}), respawning...`,
+						);
+						// respawn: same descriptor, same port
+						// (simplified — plugin-scale can override this behavior)
+					}
+				},
+			});
+
+			liveWorkers.push({ descriptor, process: proc, port: workerPort });
+		}
+	}
+
+	// 6. wait for all workers ready (with timeout)
+	// workers send IPC { ready: true } — coordinator waits up to 10s
+	await waitForWorkers(liveWorkers);
+
+	// 7. fire onCoordinatorStart
+	const ctx: CoordinatorContext = {
+		workers: liveWorkers.map((w) => w.descriptor),
+		port,
+		secret,
+		routes: tree,
+	};
+	await runHook(plugins, "onCoordinatorStart", ctx);
+
+	// 8. start coordinator Bun.serve
+
+	const server = Bun.serve({
+		port,
+		hostname: host,
+		fetch: async (req) => {
+			// run hooks.server.ts to populate locals
+			const locals: App.Locals = {};
+			// ... same handle() chain as createServer but resolve() just
+			// forwards instead of rendering
+
+			// pick worker
+			const descriptors = liveWorkers.map((w) => w.descriptor);
+			const chosen =
+				(await runRouteRequest(plugins, req, descriptors, tree)) ??
+				defaultRoute(req, descriptors, tree);
+
+			// serialize locals
+			const serialized =
+				(await runSerializeLocals(plugins, locals)) ??
+				defaultSerialize(locals, secret);
+
+			// forward
+			return fetch(chosen.internalUrl + new URL(req.url).pathname, {
+				method: req.method,
+				headers: {
+					//@ts-expect-error shut Up
+					...Object.fromEntries(req.headers),
+					"X-Grimoire-Locals": serialized,
+					"X-Grimoire-Internal": secret,
+				},
+				body: req.body,
+			});
+		},
+	});
+
+	// 9. shutdown
+	const handleShutdown = async () => {
+		if (stopping) return;
+		stopping = true;
+		await runHook(plugins, "onStop", "shutdown");
+		for (const w of liveWorkers) w.process.kill();
+		server.stop();
+		process.exit(0);
+	};
+	process.on("SIGINT", handleShutdown);
+	process.on("SIGTERM", handleShutdown);
+
+	return {
+		server,
+		workers: liveWorkers.map((w) => ({
+			name: w.descriptor.name,
+			mode: w.descriptor.mode,
+			port: w.port,
+			index: w.descriptor.index,
+		})),
+	};
+}
+
+function defaultSerialize(locals: App.Locals, secret: string): string {
+	const payload = JSON.stringify(locals);
+	const sig = new Bun.CryptoHasher("sha256")
+		.update(secret + payload)
+		.digest("hex");
+	return Buffer.from(JSON.stringify({ payload, sig })).toString("base64");
+}
+
+function defaultDeserialize(raw: string, secret: string): App.Locals {
+	const { payload, sig } = JSON.parse(Buffer.from(raw, "base64").toString());
+	const expected = new Bun.CryptoHasher("sha256")
+		.update(secret + payload)
+		.digest("hex");
+	if (sig !== expected) throw new Error("Grimoire: locals signature invalid");
+	return JSON.parse(payload);
+}

package/src/{hooks.ts → server/hooks.ts}

@@ -1,7 +1,7 @@
 /**
  * SvelteKit-style server hooks.
  *
- * Create a hooks.server.ts in your project root:
+ * Create a hooks.index.ts in your project root:
  *
  *   import type { Handle } from "@sigil-dev/grimoire/hooks";
  *