@sigil-dev/grimoire 0.8.4 → 0.8.6

package/src/server/interactive.ts

@@ -0,0 +1,54 @@
+export interface InteractiveOptions {
+    onQuit:    () => void | Promise<void>;
+    onRestart: () => void | Promise<void>;
+    onClear:   () => void;
+}
+
+/**
+ * Returns a promise that resolves only when explicitly settled.
+ * Used to keep the dev/start process alive until the user quits.
+ */
+export function createWaiter() {
+    let resolve!: () => void;
+    const promise = new Promise<void>((r) => { resolve = r; });
+    return { promise, resolve };
+}
+
+/**
+ * Listen for interactive keypresses in dev mode.
+ * Mirrors Vite's UX: q=quit, r=restart, c=clear.
+ * Falls back gracefully if stdin is not a TTY (CI, piped input).
+ */
+export function listenForKeys(opts: InteractiveOptions) {
+    if (!process.stdin.isTTY) return;
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    process.stdin.on("data", async (key: string) => {
+        // ctrl+c
+        if (key === "\x03") {
+            await opts.onQuit();
+            return;
+        }
+
+        switch (key.toLowerCase()) {
+            case "q":
+                await opts.onQuit();
+                break;
+            case "r":
+                await opts.onRestart();
+                break;
+            case "c":
+                opts.onClear();
+                break;
+        }
+    });
+}
+
+export function stopListening() {
+    if (!process.stdin.isTTY) return;
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+}

package/src/types.ts

@@ -3,206 +3,208 @@ import type { RouteFile, RouteTree } from "./routing/scanner";
 
 /// <reference types="bun-types">
 declare global {
-	namespace App {
-		// augment in your own project via src/app.d.ts
-		interface Locals {}
-		interface Error {
-			message: string;
-			status?: number;
-		}
-		interface PageData {}
-		interface Platform {}
-	}
+    namespace App {
+        // augment in your own project via src/app.d.ts
+        interface Locals { }
+        interface Error {
+            message: string;
+            status?: number;
+        }
+        interface PageData { }
+        interface Platform { }
+    }
 }
 
 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
+    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
+    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
+    request: Request;
+    params: Record<string, string>;
+    url: URL;
+    locals: Record<string, unknown>; // set by plugins/hooks
+    fetch: typeof globalThis.fetch;  // ← add
 }
 
 export interface TypedLoadContext<
-	P extends Record<string, string> = Record<string, string>,
+    P extends Record<string, string> = Record<string, string>,
 > {
-	request: Request;
-	params: P;
-	url: URL;
-	locals: App.Locals;
+    request: Request;
+    params: P;
+    url: URL;
+    locals: App.Locals;
+    fetch: typeof fetch;
 }
 
 export interface RenderContext {
-	route: RouteInfo;
-	request: Request;
-	params: Record<string, string>;
-	data: unknown; // return value of load()
+    route: RouteInfo;
+    request: Request;
+    params: Record<string, string>;
+    data: unknown; // return value of load()
 }
 
 export interface BuildResult {
-	success: boolean;
-	outputs: string[];
-	errors: string[];
+    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?(reason: "shutdown" | "restart"): void | Promise<void>;
-
-	// request pipeline
-	onRequest?(
-		req: Request,
-		next: () => Promise<Response>,
-	): Response | Promise<Response>;
-
-	// 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,
-	): string | Promise<string>;
-
-	// build
-	onBuildStart?(): void | Promise<void>;
-	onBuildEnd?(result: BuildResult): void | Promise<void>;
-
-	// 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.
-	 */
-	onWorkerSpawn?(
-		worker: WorkerDescriptor,
-		// biome-ignore lint/suspicious/noConfusingVoidType: doesn't have to return a thing.
-	): 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>;
+    name: string;
+
+    // server lifecycle
+    onStart?(server: Server): void | Promise<void>;
+    onStop?(reason: "shutdown" | "restart"): void | Promise<void>;
+
+    // request pipeline
+    onRequest?(
+        req: Request,
+        next: () => Promise<Response>,
+    ): Response | Promise<Response>;
+
+    // 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,
+    ): string | Promise<string>;
+
+    // build
+    onBuildStart?(): void | Promise<void>;
+    onBuildEnd?(result: BuildResult): void | Promise<void>;
+
+    // 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.
+     */
+    onWorkerSpawn?(
+        worker: WorkerDescriptor,
+        // biome-ignore lint/suspicious/noConfusingVoidType: doesn't have to return a thing.
+    ): 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 {
-	port?: number;
-	host?: string;
-	plugins?: GrimoirePlugin[];
-	routes?: string; // glob, default 'src/routes/**';
-	dev?: boolean;
-	devEditor?: boolean;
-	vitePort?: number;
-	alias?: Record<string, string>; // e.g. { "$lib": "src/lib" } — resolved relative to cwd
-	cspNonce?: string; // CSP nonce for <script>/<style> tags
-	bundleStrategy?: "split" | "single"; // 'split' (default) or 'single' bundle
-	_skipBuild?: boolean;
+    port?: number;
+    host?: string;
+    plugins?: GrimoirePlugin[];
+    routes?: string; // glob, default 'src/routes/**';
+    dev?: boolean;
+    devEditor?: boolean;
+    vitePort?: number;
+    alias?: Record<string, string>; // e.g. { "$lib": "src/lib" } — resolved relative to cwd
+    cspNonce?: string; // CSP nonce for <script>/<style> tags
+    bundleStrategy?: "split" | "single"; // 'split' (default) or 'single' bundle
+    _skipBuild?: boolean;
 }
 
 export function defineConfig(config: GrimoireConfig): GrimoireConfig {
-	return config;
+    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>,
+    P extends Record<string, string> = Record<string, string>,
 > = (
-	ctx: TypedLoadContext<P>,
+    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>,
+    P extends Record<string, string> = Record<string, string>,
 > = (
-	ctx: TypedLoadContext<P>,
+    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>,
+    P extends Record<string, string> = Record<string, string>,
 > = (ctx: TypedLoadContext<P>) => Response | Promise<Response>;
 
 /**
@@ -211,14 +213,14 @@ export type RequestHandler<
  * 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>;
+    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***
@@ -241,13 +243,13 @@ export type WorkerMode = BuiltinWorkerMode | (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
+    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
 }
 
 /**
@@ -255,16 +257,16 @@ export interface WorkerDescriptor {
  * are merged — env from all plugins is combined, last name wins.
  */
 export interface WorkerEnv {
-	env?: Record<string, string>;
-	name?: string;
+    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;
+    workers: WorkerDescriptor[];
+    port: number;
+    secret: string; // ephemeral signing secret, generated per-run
+    routes: RouteTree;
 }