@sigil-dev/grimoire 0.8.0 → 0.8.2

package/src/dev/hmr-server.ts

@@ -1,11 +1,14 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import type { ServerWebSocket } from "bun";
+import { log } from "../logger/instance";
 import { compileForBrowser } from "./compile-module";
 import type { DevGraph } from "./graph";
 import { normalizePath } from "./paths";
 import { safeRead } from "./watcher";
 
+const logger = log.scope("hmr");
+
 export class HmrServer {
 	private clients = new Set<ServerWebSocket<any>>();
 	private v = 0;
@@ -31,7 +34,7 @@ export class HmrServer {
 	}
 
 	reload() {
-		console.log("[sigil hmr] sending reload to", this.clients.size, "clients");
+		logger.info("sending reload to", this.clients.size, "clients");
 		this.batch([{ kind: "reload" }]);
 	}
 
@@ -69,7 +72,7 @@ export async function compileAndSwap(
 	graph: DevGraph,
 	hmr: HmrServer,
 	projectRoot: string,
-	routeTree: any,
+	_routeTree: any,
 ): Promise<void> {
 	const key = normalizePath(filePath);
 	const node = graph.get(key);
@@ -105,7 +108,7 @@ export async function compileAndSwap(
 
 		if (!routeFile) {
 			// no route found — fall back to reload
-			console.log("[sigil hmr] no route affected, reloading");
+			logger.info("no route affected, reloading");
 			hmr.reload();
 			return;
 		}
@@ -114,7 +117,7 @@ export async function compileAndSwap(
 		const clientPath = relative(projectRoot, filePath).replace(/\\/g, "/");
 		const modUrl = `${clientPath}.js`;
 
-		console.log("[sigil hmr] compiled:", filePath, `v=${v}`);
+		logger.info(`compiled: ${filePath}, v=${v}`);
 
 		const payloads: object[] = [];
 
@@ -144,10 +147,7 @@ export async function compileAndSwap(
 				patterns: otherRoutes.map((r) => r.path),
 			});
 		}
-		console.log(
-			"[sigil hmr] sending batch:",
-			JSON.stringify(payloads, null, 2),
-		);
+		logger.info("sending batch:", JSON.stringify(payloads, null, 2));
 		hmr.batch(payloads);
 	} catch (e: any) {
 		const loc = extractLoc(e, filePath);
@@ -161,7 +161,7 @@ export async function handleChange(
 	filePath: string,
 	graph: DevGraph,
 	hmr: HmrServer,
-	srcDir: string,
+	_srcDir: string,
 	projectRoot: string,
 	routeTree: any,
 ): Promise<void> {
@@ -177,11 +177,11 @@ export async function handleChange(
 	}
 	const node = graph.get(key);
 	if (!node) {
-		console.log("[sigil hmr] unknown file, reloading:", filePath);
+		logger.info("unknown file, reloading:", filePath);
 		hmr.reload();
 		return;
 	}
 
-	console.log("[sigil hmr] changed:", filePath);
+	logger.info("changed:", filePath);
 	await compileAndSwap(filePath, graph, hmr, projectRoot, routeTree);
 }

package/src/dev/runtime-bundle.ts

@@ -1,5 +1,8 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { log } from "../logger/instance";
+
+const logger = log.scope("runtime-bundle");
 
 export async function ensureRuntimeBundle(projectRoot: string): Promise<void> {
 	const outDir = join(projectRoot, "public/__grimoire__");
@@ -8,7 +11,7 @@ export async function ensureRuntimeBundle(projectRoot: string): Promise<void> {
 	// runtime
 	const runtimeOut = join(outDir, "runtime.js");
 	if (!(await Bun.file(runtimeOut).exists())) {
-		console.log("[sigil hmr] bundling runtime...");
+		logger.debug("bundling runtime...");
 		const result = await Bun.build({
 			entrypoints: [
 				join(projectRoot, "node_modules/@sigil-dev/runtime/index.ts"),
@@ -20,8 +23,8 @@ export async function ensureRuntimeBundle(projectRoot: string): Promise<void> {
 			minify: false,
 		});
 		if (!result.success)
-			console.error("[sigil hmr] runtime bundle failed:", result.logs);
-		else console.log("[sigil hmr] runtime bundled");
+			logger.error("[sigil hmr] runtime bundle failed:", result.logs);
+		else logger.debug("[sigil hmr] runtime bundled");
 	}
 
 	// grimoire client
@@ -45,5 +48,5 @@ export async function ensureRuntimeBundle(projectRoot: string): Promise<void> {
     export const afterNavigate = (cb) => window.__grimoire_afterNavigate__?.(cb);
     `.trim(),
 	);
-	console.log("[sigil hmr] grimoire client shim written");
+	logger.info("grimoire client shim written");
 }

package/src/integrations/vite.ts

@@ -22,7 +22,7 @@ export function grimoire(options: { routes?: string } = {}): Plugin {
 				: join(process.cwd(), options.routes ?? "src/routes");
 
 			// client entry
-			vite.middlewares.use("/__grimoire__/client.js", async (req, res) => {
+			vite.middlewares.use("/__grimoire__/client.js", async (_req, res) => {
 				const result = await vite.transformRequest(CLIENT_ENTRY);
 				if (!result) {
 					res.statusCode = 404;

package/src/logger/index.ts

@@ -0,0 +1,6 @@
+// src/logger/index.ts
+
+export * from "./logger.ts";
+export * from "./request-middleware.ts";
+export * from "./transports.ts";
+export * from "./types.ts";

package/src/logger/instance.ts

@@ -0,0 +1,6 @@
+import { Logger } from "./logger.ts";
+import { ConsoleTransport } from "./transports.ts";
+
+export const log = new Logger("grimoire", {
+	transports: [new ConsoleTransport()],
+});

package/src/logger/logger.ts

@@ -0,0 +1,113 @@
+// packages/grimoire/src/logger/logger.ts
+
+import type {
+	LogEntry,
+	LoggerOptions,
+	LogLevel,
+	LogTransport,
+	ScopedLogger,
+} from "./types.ts";
+import { LOG_LEVELS } from "./types.ts";
+
+export class Logger implements ScopedLogger {
+	private transports: LogTransport[];
+	private minLevel: number;
+	private filter?: (entry: LogEntry) => boolean;
+	private _scope: string;
+	private _worker?: string;
+	private _requestId?: string;
+
+	constructor(scope: string, options: LoggerOptions = {}, worker?: string) {
+		this._scope = scope;
+		this._worker = worker;
+		this.transports = options.transports ?? [];
+		this.minLevel =
+			LOG_LEVELS[
+				options.level ??
+					(process.env.LOG_LEVEL as LogLevel | undefined) ??
+					"info"
+			] ?? LOG_LEVELS.info;
+		this.filter = options.filter;
+	}
+
+	// called by loom coordinator after forking workers
+	setWorker(name: string) {
+		this._worker = name;
+	}
+
+	private write(level: LogLevel, message: string, ...args: unknown[]) {
+		if (LOG_LEVELS[level] < this.minLevel) return;
+
+		const data =
+			args.length === 0 ? undefined : args.length === 1 ? args[0] : args;
+
+		const entry: LogEntry = {
+			level,
+			scope: this._scope,
+			message,
+			data,
+			timestamp: Date.now(),
+			worker: this._worker,
+			requestId: this._requestId,
+		};
+
+		if (this.filter && !this.filter(entry)) return;
+		for (const t of this.transports) {
+			try {
+				t.write(entry);
+			} catch {}
+		}
+	}
+
+	debug(message: string, ...args: unknown[]) {
+		this.write("debug", message, ...args);
+	}
+	info(message: string, ...args: unknown[]) {
+		this.write("info", message, ...args);
+	}
+	warn(message: string, ...args: unknown[]) {
+		this.write("warn", message, ...args);
+	}
+	error(message: string, ...args: unknown[]) {
+		this.write("error", message, ...args);
+	}
+	fatal(message: string, ...args: unknown[]) {
+		this.write("fatal", message, ...args);
+	}
+
+	scope(name: string): ScopedLogger {
+		const child = new Logger(
+			`${this._scope}:${name}`,
+			{
+				transports: this.transports,
+				level: Object.keys(LOG_LEVELS).find(
+					(k) => LOG_LEVELS[k as LogLevel] === this.minLevel,
+				) as LogLevel,
+				filter: this.filter,
+			},
+			this._worker,
+		);
+		child._requestId = this._requestId;
+		return child;
+	}
+
+	withRequest(requestId: string): ScopedLogger {
+		const child = new Logger(
+			this._scope,
+			{
+				transports: this.transports,
+				level: Object.keys(LOG_LEVELS).find(
+					(k) => LOG_LEVELS[k as LogLevel] === this.minLevel,
+				) as LogLevel,
+				filter: this.filter,
+			},
+			this._worker,
+		);
+		child._requestId = requestId;
+		return child;
+	}
+
+	addTransport(t: LogTransport) {
+		this.transports.push(t);
+	}
+}

package/src/logger/request-middleware.ts

@@ -0,0 +1,24 @@
+// packages/grimoire/src/logger/request-middleware.ts
+// Injected automatically by Grimoire before hooks.server.ts runs.
+
+import crypto from "node:crypto";
+import type { Logger } from "./logger.ts";
+import type { ScopedLogger } from "./types.ts";
+
+declare module "@sigil-dev/grimoire" {
+	interface RequestLocals {
+		log: ScopedLogger;
+	}
+}
+
+export function createRequestMiddleware(root: Logger) {
+	return function requestMiddleware(
+		_req: Request,
+		locals: Record<string, unknown>,
+	) {
+		// 8-char hex ID — short enough to read in a terminal
+		const requestId = crypto.randomUUID().slice(0, 8);
+		locals.log = root.withRequest(requestId);
+		(locals.log as any)._requestId = requestId;
+	};
+}

package/src/logger/transports.ts

@@ -0,0 +1,117 @@
+// packages/grimoire/src/logger/transports.ts
+
+import { appendFileSync } from "node:fs";
+import type { LogEntry, LogTransport } from "./types.ts";
+
+// ── colours (only applied when stdout is a TTY) ──────────────────────────────
+
+const isTTY = process.stdout.isTTY;
+const c = isTTY
+	? {
+			reset: "\x1b[0m",
+			dim: "\x1b[2m",
+			bold: "\x1b[1m",
+			debug: "\x1b[90m", // grey
+			info: "\x1b[36m", // cyan
+			warn: "\x1b[33m", // yellow
+			error: "\x1b[31m", // red
+			fatal: "\x1b[35m", // magenta
+			scope: "\x1b[34m", // blue
+			req: "\x1b[32m", // green
+		}
+	: (Object.fromEntries(
+			[
+				"reset",
+				"dim",
+				"bold",
+				"debug",
+				"info",
+				"warn",
+				"error",
+				"fatal",
+				"scope",
+				"req",
+			].map((k) => [k, ""]),
+		) as Record<string, string>);
+
+const LEVEL_LABEL: Record<string, string> = {
+	debug: "DBG",
+	info: "INF",
+	warn: "WRN",
+	error: "ERR",
+	fatal: "FTL",
+};
+
+function ts(timestamp: number): string {
+	return new Date(timestamp).toISOString().slice(11, 23); // HH:mm:ss.ms
+}
+
+function formatData(data: unknown): string {
+	if (data === undefined) return "";
+	if (data instanceof Error) return `\n    ${data.stack ?? data.message}`;
+	if (typeof data !== "object" || data === null) return `  ${String(data)}`;
+
+	// flat key=value for simple objects, JSON block only for nested/complex
+	const entries = Object.entries(data as Record<string, unknown>);
+	const isFlat = entries.every(([, v]) => typeof v !== "object" || v === null);
+	if (isFlat) {
+		return `  ${entries.map(([k, v]) => `${colors.dim(`${k}=`)}${v}`).join("  ")}`;
+	}
+	// nested — indent but don't pretty-print the whole thing
+	return `\n    ${JSON.stringify(data).replace(/,/g, ", ")}`;
+}
+
+// ── ConsoleTransport ─────────────────────────────────────────────────────────
+
+export class ConsoleTransport implements LogTransport {
+	write(entry: LogEntry) {
+		const levelColor = c[entry.level] ?? c.info;
+		const label = LEVEL_LABEL[entry.level] ?? entry.level.toUpperCase();
+
+		const worker = entry.worker ? `${c.dim}[${entry.worker}]${c.reset} ` : "";
+		const requestId = entry.requestId
+			? `${c.req}#${entry.requestId.slice(0, 8)}${c.reset} `
+			: "";
+		const scope = `${c.scope}${entry.scope}${c.reset}`;
+		const time = `${c.dim}${ts(entry.timestamp)}${c.reset}`;
+		const lvl = `${levelColor}${c.bold}${label}${c.reset}`;
+		const msg = entry.message;
+		const data = formatData(entry.data);
+
+		const line = `${time} ${lvl} ${worker}${requestId}${scope}  ${msg}${data}`;
+
+		if (entry.level === "error" || entry.level === "fatal") {
+			process.stderr.write(`${line}\n`);
+		} else {
+			process.stdout.write(`${line}\n`);
+		}
+	}
+}
+
+// ── FileTransport ────────────────────────────────────────────────────────────
+// Writes newline-delimited JSON for ingestion by log collectors.
+
+export class FileTransport implements LogTransport {
+	constructor(private path: string) {}
+
+	write(entry: LogEntry) {
+		try {
+			appendFileSync(this.path, `${JSON.stringify(entry)}\n`);
+		} catch {
+			// if the file write fails we can't really do anything useful
+		}
+	}
+}
+
+// ── NullTransport ────────────────────────────────────────────────────────────
+// For tests — captures entries instead of printing them.
+
+export class NullTransport implements LogTransport {
+	readonly entries: LogEntry[] = [];
+	write(entry: LogEntry) {
+		this.entries.push(entry);
+	}
+	clear() {
+		this.entries.length = 0;
+	}
+}

package/src/logger/types.ts

@@ -0,0 +1,39 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+export const LOG_LEVELS: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+	fatal: 4,
+};
+
+export interface LogEntry {
+	level: LogLevel;
+	scope: string;
+	message: string;
+	data?: unknown;
+	timestamp: number;
+	worker?: string; // injected by loom, e.g. "violet"
+	requestId?: string; // injected per-request by middleware
+}
+
+export interface LogTransport {
+	write(entry: LogEntry): void | Promise<void>;
+}
+
+export interface ScopedLogger {
+	debug(message: string, ...args: unknown[]): void;
+	info(message: string, ...args: unknown[]): void;
+	warn(message: string, ...args: unknown[]): void;
+	error(message: string, ...args: unknown[]): void;
+	fatal(message: string, ...args: unknown[]): void;
+	scope(name: string): ScopedLogger;
+	withRequest(requestId: string): ScopedLogger;
+}
+
+export interface LoggerOptions {
+	transports?: LogTransport[];
+	level?: LogLevel;
+	filter?: (entry: LogEntry) => boolean;
+}

package/src/rendering/hydrate.ts

@@ -1,119 +1,119 @@
-import {
-	claim,
-	getHydrationNodes,
-	insert,
-	popHydrationNodes,
-	pushHydrationNodes,
-} from "@sigil-dev/runtime";
-//@ts-expect-error compiler generated
-import { layouts, routes } from "#grimoire-routes";
-import {
-	afterNavigate,
-	beforeNavigate,
-	navigate,
-	onNavigate,
-} from "../client/router";
-import { initRouter } from "../client/router.ts";
-import { withEffectScope } from "../client/scope.ts";
-import { Head } from "./head";
-
-// expose for HMR module shim
-(globalThis as any).__grimoire_Head__ = Head;
-(globalThis as any).__grimoire_navigate__ = navigate;
-(globalThis as any).__grimoire_beforeNavigate__ = beforeNavigate;
-(globalThis as any).__grimoire_onNavigate__ = onNavigate;
-(globalThis as any).__grimoire_afterNavigate__ = afterNavigate;
-
-const stateEl = document.getElementById("__grimoire_state__");
-let initialDispose: (() => void) | undefined;
-
-if (stateEl) {
-	const state = JSON.parse(stateEl.textContent!);
-	const Page = routes[state.pattern];
-	if (Page) {
-		const slot = document.getElementById("grimoire-root");
-		if (slot) {
-			const matchedLayouts = layouts
-				.filter(
-					(l: any) =>
-						l.path === "/" ||
-						state.pattern === l.path ||
-						state.pattern.startsWith(l.path + "/"),
-				)
-				.sort((a: any, b: any) => a.path.length - b.path.length);
-
-			// When layouts are involved, nested <!--g--> delimiters in the flat SSR pool
-			// cause anchor-mount to claim the wrong anchor and remove layout DOM nodes.
-			// Clear SSR content and re-render in DOM mode (empty pool) instead.
-			const hasLayouts = matchedLayouts.length > 0;
-			if (hasLayouts) {
-				slot.replaceChildren();
-			}
-
-			const ssrClones = hasLayouts
-				? []
-				: Array.from(slot.childNodes).map((n) => n.cloneNode(true));
-			pushHydrationNodes(
-				hasLayouts ? [] : (Array.from(slot.childNodes) as ChildNode[]),
-			);
-			try {
-				initialDispose = withEffectScope(() => {
-					try {
-						let renderFn = () => {
-							const pageDiv = claim(getHydrationNodes(), "div");
-							pageDiv.id = "grimoire-page";
-
-							if (pageDiv.childNodes.length > 0) {
-								pushHydrationNodes(
-									Array.from(pageDiv.childNodes) as ChildNode[],
-								);
-								const pageNode = Page({
-									data: state.data,
-									params: state.params,
-								});
-								popHydrationNodes();
-								insert(pageDiv, pageNode);
-							} else {
-								const pageNode = Page({
-									data: state.data,
-									params: state.params,
-								});
-								insert(pageDiv, pageNode);
-							}
-
-							return pageDiv;
-						};
-
-						for (let i = matchedLayouts.length - 1; i >= 0; i--) {
-							const LayoutComponent = matchedLayouts[i].component;
-							const innerRender = renderFn;
-							const layoutData = state.layoutData?.[i];
-							renderFn = () => {
-								// Pre-render inner content so children is a Node (insert() doesn't call functions)
-								const childNode = innerRender();
-								return LayoutComponent({
-									data: layoutData,
-									params: state.params,
-									children: childNode,
-								});
-							};
-						}
-
-						const rootNode = renderFn();
-						insert(slot, rootNode);
-					} finally {
-						popHydrationNodes();
-					}
-				});
-			} catch (e) {
-				console.warn("[grimoire] hydration error:", e);
-			}
-
-			if (!slot.hasChildNodes() && ssrClones.length > 0) {
-				slot.replaceChildren(...ssrClones);
-			}
-		}
-	}
-}
-
-initRouter(routes, layouts, initialDispose);
+import {
+	claim,
+	getHydrationNodes,
+	insert,
+	popHydrationNodes,
+	pushHydrationNodes,
+} from "@sigil-dev/runtime";
+//@ts-expect-error compiler generated
+import { layouts, routes } from "#grimoire-routes";
+import {
+	afterNavigate,
+	beforeNavigate,
+	navigate,
+	onNavigate,
+} from "../client/router";
+import { initRouter } from "../client/router.ts";
+import { withEffectScope } from "../client/scope.ts";
+import { Head } from "./head";
+
+// expose for HMR module shim
+(globalThis as any).__grimoire_Head__ = Head;
+(globalThis as any).__grimoire_navigate__ = navigate;
+(globalThis as any).__grimoire_beforeNavigate__ = beforeNavigate;
+(globalThis as any).__grimoire_onNavigate__ = onNavigate;
+(globalThis as any).__grimoire_afterNavigate__ = afterNavigate;
+
+const stateEl = document.getElementById("__grimoire_state__");
+let initialDispose: (() => void) | undefined;
+
+if (stateEl) {
+	const state = JSON.parse(stateEl.textContent!);
+	const Page = routes[state.pattern];
+	if (Page) {
+		const slot = document.getElementById("grimoire-root");
+		if (slot) {
+			const matchedLayouts = layouts
+				.filter(
+					(l: any) =>
+						l.path === "/" ||
+						state.pattern === l.path ||
+						state.pattern.startsWith(`${l.path}/`),
+				)
+				.sort((a: any, b: any) => a.path.length - b.path.length);
+
+			// When layouts are involved, nested <!--g--> delimiters in the flat SSR pool
+			// cause anchor-mount to claim the wrong anchor and remove layout DOM nodes.
+			// Clear SSR content and re-render in DOM mode (empty pool) instead.
+			const hasLayouts = matchedLayouts.length > 0;
+			if (hasLayouts) {
+				slot.replaceChildren();
+			}
+
+			const ssrClones = hasLayouts
+				? []
+				: Array.from(slot.childNodes).map((n) => n.cloneNode(true));
+			pushHydrationNodes(
+				hasLayouts ? [] : (Array.from(slot.childNodes) as ChildNode[]),
+			);
+			try {
+				initialDispose = withEffectScope(() => {
+					try {
+						let renderFn = () => {
+							const pageDiv = claim(getHydrationNodes(), "div");
+							pageDiv.id = "grimoire-page";
+
+							if (pageDiv.childNodes.length > 0) {
+								pushHydrationNodes(
+									Array.from(pageDiv.childNodes) as ChildNode[],
+								);
+								const pageNode = Page({
+									data: state.data,
+									params: state.params,
+								});
+								popHydrationNodes();
+								insert(pageDiv, pageNode);
+							} else {
+								const pageNode = Page({
+									data: state.data,
+									params: state.params,
+								});
+								insert(pageDiv, pageNode);
+							}
+
+							return pageDiv;
+						};
+
+						for (let i = matchedLayouts.length - 1; i >= 0; i--) {
+							const LayoutComponent = matchedLayouts[i].component;
+							const innerRender = renderFn;
+							const layoutData = state.layoutData?.[i];
+							renderFn = () => {
+								// Pre-render inner content so children is a Node (insert() doesn't call functions)
+								const childNode = innerRender();
+								return LayoutComponent({
+									data: layoutData,
+									params: state.params,
+									children: childNode,
+								});
+							};
+						}
+
+						const rootNode = renderFn();
+						insert(slot, rootNode);
+					} finally {
+						popHydrationNodes();
+					}
+				});
+			} catch (e) {
+				console.warn("[grimoire] hydration error:", e);
+			}
+
+			if (!slot.hasChildNodes() && ssrClones.length > 0) {
+				slot.replaceChildren(...ssrClones);
+			}
+		}
+	}
+}
+
+initRouter(routes, layouts, initialDispose);

package/src/rendering/index.ts

@@ -1,5 +1,5 @@
+import { randomBytes } from "node:crypto";
 import { SafeHtml } from "@sigil-dev/runtime";
-import { randomBytes } from "crypto";
 import { findClosestError, type MatchedRoute } from "../routing/router";
 import type { RouteFile } from "../routing/scanner";
 import { isErrorResult } from "../sentinels/error.ts";