@sigil-dev/grimoire 0.3.0

package/src/typegen.ts

@@ -0,0 +1,263 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import type { RouteFile, RouteTree } from "./scanner";
+
+export interface TypegenConfig {
+	projectRoot: string;
+	routesDir: string;
+	outDir: string; // absolute path to .grimoire/types
+}
+
+export interface RouteGroup {
+	dir: string;
+	paramNames: string[];
+	page?: RouteFile;
+	pageServer?: RouteFile;
+	layout?: RouteFile;
+	layoutServer?: RouteFile;
+	server?: RouteFile;
+	error?: RouteFile;
+}
+
+// On Windows, relative() returns the absolute `to` path when src and dest are on
+// different drives. Detect that and fall back to routes-dir-relative so join()
+// doesn't produce an invalid double-rooted path like "D:\out\C:\Users\...".
+function safeRelativeDir(
+	projectRoot: string,
+	routesDir: string,
+	groupDir: string,
+): string {
+	const rel = relative(projectRoot, groupDir);
+	return isAbsolute(rel) ? relative(routesDir, groupDir) : rel;
+}
+
+export function groupByDirectory(tree: RouteTree): Map<string, RouteGroup> {
+	const groups = new Map<string, RouteGroup>();
+
+	// Only process + convention files — simple files don't get $types
+	const files: RouteFile[] = [
+		...tree.routes.filter((f) => f.type !== "simple"),
+		...tree.layouts,
+		...tree.servers,
+		...tree.errors,
+	];
+
+	for (const file of files) {
+		const dir = dirname(file.filePath);
+		if (!groups.has(dir)) {
+			groups.set(dir, { dir, paramNames: file.paramNames });
+		}
+		const g = groups.get(dir)!;
+		if (file.paramNames.length > g.paramNames.length) {
+			g.paramNames = file.paramNames;
+		}
+		switch (file.type) {
+			case "page":
+				g.page = file;
+				break;
+			case "pageServer":
+				g.pageServer = file;
+				break;
+			case "layout":
+				g.layout = file;
+				break;
+			case "layoutServer":
+				g.layoutServer = file;
+				break;
+			case "server":
+				g.server = file;
+				break;
+			case "error":
+				g.error = file;
+				break;
+		}
+	}
+
+	return groups;
+}
+
+export function toImportPath(from: string, to: string): string {
+	return relative(from, to)
+		.replace(/\\/g, "/")
+		.replace(/\.tsx?$/, ".js");
+}
+
+export function buildParams(paramNames: string[]): string {
+	if (paramNames.length === 0) return "{}";
+	const props = paramNames.map((p) => `  ${p}: string;`).join("\n");
+	return `{\n${props}\n}`;
+}
+
+function generateTypesForGroup(group: RouteGroup, outFileDir: string): string {
+	const lines: string[] = [
+		"// Auto-generated by @sigil-dev/grimoire — do not edit",
+		"",
+	];
+
+	const paramsType = buildParams(group.paramNames);
+
+	// --- Params ---
+	lines.push(`export type Params = ${paramsType};`, "");
+
+	// --- PageData from +page.server.ts ---
+	if (group.pageServer) {
+		const imp = toImportPath(outFileDir, group.pageServer.filePath);
+		// Use `typeof import(...)` (not `import type * as NS`) so the module type
+		// can be used in `keyof` and indexed access without TS2709.
+		lines.push(
+			`type _PS = typeof import("${imp}");`,
+			`export type PageData = "load" extends keyof _PS`,
+			`  ? Awaited<ReturnType<_PS["load"]>>`,
+			`  : Record<string, never>;`,
+			"",
+		);
+		lines.push(`export type PageProps = PageData & { params: Params };`, "");
+		// PageServerLoad — annotate parameter, NOT return type, to preserve inference
+		lines.push(
+			`/** Annotate the load() parameter only — not the return type — or PageData loses its concrete keys. */`,
+			`export type PageServerLoad = (ctx: {`,
+			`  params: Params;`,
+			`  request: Request;`,
+			`  url: URL;`,
+			`  locals: App.Locals;`,
+			`}) => Record<string, unknown> | Promise<Record<string, unknown>>;`,
+			"",
+		);
+		// Actions — all exports except load and default
+		lines.push(
+			`type _ActionKeys = Exclude<keyof _PS, "load" | "default">;`,
+			`export type Actions = {`,
+			`  [K in _ActionKeys]: (ctx: {`,
+			`    params: Params;`,
+			`    request: Request;`,
+			`    url: URL;`,
+			`    locals: App.Locals;`,
+			`  }) => unknown | Promise<unknown>;`,
+			`};`,
+			"",
+		);
+	} else {
+		lines.push(
+			`export type PageData = Record<string, never>;`,
+			`export type PageProps = { params: Params };`,
+			`export type PageServerLoad = never;`,
+			`export type Actions = Record<string, never>;`,
+			"",
+		);
+	}
+
+	// --- LayoutData from +layout.server.ts ---
+	if (group.layoutServer) {
+		const imp = toImportPath(outFileDir, group.layoutServer.filePath);
+		lines.push(
+			`type _LS = typeof import("${imp}");`,
+			`export type LayoutData = "load" extends keyof _LS`,
+			`  ? Awaited<ReturnType<_LS["load"]>>`,
+			`  : Record<string, never>;`,
+			"",
+		);
+	} else {
+		lines.push(`export type LayoutData = Record<string, never>;`);
+	}
+
+	lines.push(
+		`export type LayoutProps = LayoutData & { params: Params; children?: unknown };`,
+		`export type LayoutServerLoad = (ctx: {`,
+		`  params: Params;`,
+		`  request: Request;`,
+		`  url: URL;`,
+		`  locals: App.Locals;`,
+		`}) => Record<string, unknown> | Promise<Record<string, unknown>>;`,
+		"",
+	);
+
+	// --- +server.ts API route handlers ---
+	if (group.server) {
+		const imp = toImportPath(outFileDir, group.server.filePath);
+		lines.push(
+			`type _SRV = typeof import("${imp}");`,
+			`type _HttpMethods = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";`,
+			`type _ServerKeys = Extract<keyof _SRV, _HttpMethods>;`,
+			`export type ServerHandlers = {`,
+			`  [K in _ServerKeys]: (ctx: {`,
+			`    params: Params;`,
+			`    request: Request;`,
+			`    url: URL;`,
+			`    locals: App.Locals;`,
+			`  }) => Response | Promise<Response>;`,
+			`};`,
+			"",
+		);
+	}
+
+	// --- +error.tsx ---
+	if (group.error) {
+		lines.push(
+			`export type ErrorProps = { status: number; message: string };`,
+			"",
+		);
+	}
+
+	return lines.join("\n");
+}
+
+function generateAmbient(): string {
+	return [
+		"// Auto-generated by @sigil-dev/grimoire — do not edit",
+		"",
+		"declare namespace App {",
+		"  // Extend this interface in your app's src/app.d.ts to add typed locals",
+		"  interface Locals extends Record<string, unknown> {}",
+		"}",
+		"",
+	].join("\n");
+}
+
+function generateTsConfig(): string {
+	return JSON.stringify(
+		{
+			compilerOptions: {
+				// Merges ".." (project root) and "./types" (.grimoire/types) into one
+				// virtual root so `import from './$types'` resolves without path aliases.
+				rootDirs: ["..", "./types"],
+			},
+			include: ["types/**/*.d.ts"],
+		},
+		null,
+		2,
+	);
+}
+
+export async function generateTypes(
+	tree: RouteTree,
+	config: TypegenConfig,
+): Promise<void> {
+	const { projectRoot, outDir } = config;
+
+	await rm(outDir, { recursive: true, force: true });
+	await mkdir(outDir, { recursive: true });
+
+	const groups = groupByDirectory(tree);
+
+	for (const group of groups.values()) {
+		const routeRelDir = safeRelativeDir(
+			projectRoot,
+			config.routesDir,
+			group.dir,
+		);
+		const outFileDir = join(outDir, routeRelDir);
+		await mkdir(outFileDir, { recursive: true });
+
+		const content = generateTypesForGroup(group, outFileDir);
+		await writeFile(join(outFileDir, "$types.d.ts"), content, "utf-8");
+	}
+
+	await writeFile(join(outDir, "ambient.d.ts"), generateAmbient(), "utf-8");
+
+	const grimoireDir = dirname(outDir);
+	await writeFile(
+		join(grimoireDir, "tsconfig.generated.json"),
+		generateTsConfig(),
+		"utf-8",
+	);
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+export interface Route {
+	path: string; // /blog/:slug
+	params: Record<string, string>;
+	filePath: string; // absolute path to +page.tsx
+	loadPath?: string; // absolute path to +page.ts
+	serverPath?: string; // absolute path to +server.ts
+	layoutPath?: string; // absolute path to +layout.tsx
+}
+
+export interface RouteInfo {
+	path: string; // /blog/:slug
+	filePath: string; // absolute path
+	type: string; // page, layout etc
+}
+
+export interface LoadContext {
+	request: Request;
+	params: Record<string, string>;
+	url: URL;
+	locals: Record<string, unknown>; // set by plugins/hooks
+}
+
+export interface TypedLoadContext<
+	P extends Record<string, string> = Record<string, string>,
+> {
+	request: Request;
+	params: P;
+	url: URL;
+	locals: App.Locals;
+}
+
+export interface RenderContext {
+	route: RouteInfo;
+	request: Request;
+	params: Record<string, string>;
+	data: unknown; // return value of load()
+}
+
+export interface BuildResult {
+	success: boolean;
+	outputs: string[];
+	errors: string[];
+}
+export type Server = { port: number; hostname: string; stop(): void };
+
+export interface GrimoirePlugin {
+	name: string;
+
+	// server lifecycle
+	onStart?(server: Server): void | Promise<void>;
+	onStop?(): void | Promise<void>;
+
+	// request pipeline
+	onRequest?(
+		req: Request,
+		next: () => Promise<Response>,
+	): Response | Promise<Response>;
+
+	// route lifecycle
+	onRouteLoad?(route: Route, context: LoadContext): void | Promise<void>;
+	onRouteRender?(
+		html: string,
+		context: RenderContext,
+	): string | Promise<string>;
+
+	// build
+	onBuildStart?(): void | Promise<void>;
+	onBuildEnd?(result: BuildResult): void | Promise<void>;
+
+	// config
+	config?: (config: GrimoireConfig) => GrimoireConfig | undefined;
+}
+
+export interface GrimoireConfig {
+	port?: number;
+	host?: string;
+	plugins?: GrimoirePlugin[];
+	routes?: string; // glob, default 'src/routes/**';
+	dev?: boolean;
+	vitePort?: number;
+}
+
+export function defineConfig(config: GrimoireConfig): GrimoireConfig {
+	return config;
+}

package/src/vite-plugin.ts

@@ -0,0 +1,72 @@
+import { isAbsolute, join, resolve } from "node:path";
+import type { Plugin } from "vite";
+import { renderRoute } from "./renderer";
+import { matchRoute } from "./router";
+import { scanRoutes } from "./scanner";
+
+const CLIENT_ENTRY = resolve(import.meta.dir, "./client.ts");
+
+export function grimoire(options: { routes?: string } = {}): Plugin {
+	let isBuild = false;
+
+	return {
+		name: "grimoire",
+
+		configResolved(config) {
+			isBuild = config.command === "build";
+		},
+
+		configureServer(vite) {
+			const routesDir = isAbsolute(options.routes ?? "src/routes")
+				? options.routes!
+				: join(process.cwd(), options.routes ?? "src/routes");
+
+			// client entry
+			vite.middlewares.use("/__grimoire__/client.js", async (req, res) => {
+				const result = await vite.transformRequest(CLIENT_ENTRY);
+				if (!result) {
+					res.statusCode = 404;
+					res.end();
+					return;
+				}
+				res.setHeader("Content-Type", "application/javascript");
+				res.end(result.code);
+			});
+
+			// page routes
+			vite.middlewares.use(async (req, res, next) => {
+				const url = new URL(req.url!, "http://localhost");
+				if (url.pathname.startsWith("/__") || url.pathname.includes(".")) {
+					return next();
+				}
+				try {
+					const tree = await scanRoutes(routesDir, process.cwd());
+					const matched = matchRoute(tree, url);
+					if (!matched) return next();
+
+					const response = await renderRoute(
+						matched,
+						new Request(`http://localhost${req.url}`),
+						(path) => vite.ssrLoadModule(path), // Vite transforms SSR files correctly
+					);
+
+					const html = await response.text();
+					res.setHeader("Content-Type", "text/html");
+					res.end(html);
+				} catch (e) {
+					vite.ssrFixStacktrace(e as Error);
+					next(e);
+				}
+			});
+		},
+
+		buildStart() {
+			if (!isBuild) return;
+			this.emitFile({
+				type: "chunk",
+				id: CLIENT_ENTRY,
+				fileName: "client.js",
+			});
+		},
+	};
+}

package/test/context.test.ts

@@ -0,0 +1,52 @@
+// 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";
+
+const UserKey = createContext<string>();
+const ThemeKey = createContext<string>();
+
+// 1. Basic: does it work at all
+test("getContext returns value set in same context", async () => {
+	await runWithContext(async () => {
+		setContext(UserKey, "cane");
+		expect(getContext(UserKey)).toBe("cane");
+	});
+});
+
+// 2. Isolation: the whole point of AsyncLocalStorage
+test("concurrent requests do not bleed context", async () => {
+	let resolveA!: () => void;
+	let resolveB!: () => void;
+
+	const barrier = {
+		a: new Promise<void>((r) => (resolveA = r)),
+		b: new Promise<void>((r) => (resolveB = r)),
+	};
+
+	const requestA = runWithContext(async () => {
+		setContext(UserKey, "request-A");
+		await barrier.a; // suspend, let B run
+		// if context bleeds, this returns "request-B"
+		return getContext(UserKey);
+	});
+
+	const requestB = runWithContext(async () => {
+		setContext(UserKey, "request-B");
+		resolveA(); // wake A up
+		await barrier.b;
+		return getContext(UserKey);
+	});
+
+	resolveB();
+	const [a, b] = await Promise.all([requestA, requestB]);
+
+	expect(a).toBe("request-A"); // fails if bleed
+	expect(b).toBe("request-B");
+});
+
+// 3. Outside context: should not throw, returns undefined
+test("getContext outside runWithContext returns undefined gracefully", () => {
+	const val = getContext(UserKey);
+	expect(val).toBeUndefined();
+});

package/test/fail.test.ts

@@ -0,0 +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);
+	});
+});

package/test/headers.test.ts

@@ -0,0 +1,96 @@
+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");
+	});
+});