@cosmicdrift/kumiko-dev-server 0.386.0 → 0.388.0

package/dist/create-kumiko-server-html.js

@@ -0,0 +1,132 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, createClientIpResolver, generateToken, sessionCookieName, } from "@cosmicdrift/kumiko-framework/api";
+import { rankPreferredLocales } from "@cosmicdrift/kumiko-framework/i18n";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
+import { resolveAndInjectPageHead, } from "@cosmicdrift/kumiko-renderer/headless/apex";
+import { buildRequestBoundSystemQuery } from "@cosmicdrift/kumiko-server-runtime/request-bound-system-query";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { injectReload } from "./create-kumiko-server-reload.js";
+// The dev server speaks plain http, so its minted cookies are never Secure and keep the unprefixed names.
+const CSRF_COOKIE = sessionCookieName(CSRF_COOKIE_BASE, { secure: false });
+const AUTH_COOKIE = sessionCookieName(AUTH_COOKIE_BASE, { secure: false });
+// Minimal HTML when the caller didn't hand one in. `#root` is the
+// default mount target for `createKumikoApp`, so the one-line client
+// can attach without the sample having to ship its own template.
+//
+// `type="module"` is load-bearing: a classic script turns the bundle's
+// top-level declarations into window properties, so a dependency exporting
+// `function history()` (prosemirror-history, pulled in by tiptap) silently
+// replaces `window.history` and every pushState afterwards throws. Prod
+// (build-prod-bundle) has always emitted the module form.
+//
+// `interactive-widget=resizes-content`: without it, a mobile
+// keyboard shrinks only the visual viewport, not the layout viewport that
+// `position: fixed` anchors to — a fixed bottom action bar would stay
+// pinned behind the keyboard instead of above it. iOS Safari ignores the
+// key; renderer/web's useKeyboardInset covers it via window.visualViewport.
+export const DEFAULT_HTML = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1,interactive-widget=resizes-content" />
+    <title>Kumiko</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/client.js"></script>
+  </body>
+</html>
+`;
+// Injects <link rel="stylesheet" href="/styles.css"> into <head> if it
+// is not already present. Called only when the stylesheet option is used;
+// otherwise no CSS route is provided.
+function injectStylesheet(html) {
+    if (html.includes('href="/styles.css"'))
+        return html;
+    const link = '<link rel="stylesheet" href="/styles.css" />';
+    return html.includes("</head>")
+        ? html.replace("</head>", `  ${link}\n</head>`)
+        : `${link}${html}`;
+}
+// Single-entry uses one template (`htmlPath` or DEFAULT_HTML). Multi-entry
+// uses one per entry (`entry.htmlPath ?? options.htmlPath ?? DEFAULT_HTML`);
+// hostDispatch selects it per request.
+export async function loadHtmlTemplates(entries, htmlPath) {
+    const defaultTemplate = htmlPath !== undefined ? await readFile(resolve(htmlPath), "utf-8") : DEFAULT_HTML;
+    const byEntry = new Map();
+    for (const e of entries) {
+        byEntry.set(e.name, e.htmlPath !== undefined ? await readFile(resolve(e.htmlPath), "utf-8") : defaultTemplate);
+    }
+    return { defaultTemplate, byEntry };
+}
+// Anonymous-role systemQuery, shared by resolvePageHead and hostDispatch —
+// mirrors runProdApp's HostDispatchFn deps so dev/prod stay symmetric.
+// Own resolver with the same effective hops as setupTestStack's internal
+// buildServer: this path runs ahead of requestIdMiddleware's /api/* mount,
+// so it can't reuse that instance. Two independent warn-once flags in dev
+// is an accepted, low-risk gap (dev normally runs unproxied).
+export function createDevSystemQueryBuilder(dispatcher, trustedProxyHops) {
+    const pageHeadClientIpResolver = createClientIpResolver(trustedProxyHops ?? 0, "createKumikoServer(pageHead)");
+    return (req, socketAddress) => buildRequestBoundSystemQuery({
+        req,
+        dispatcher,
+        resolver: pageHeadClientIpResolver,
+        socketAddress,
+    });
+}
+// Dev user = TestUsers.admin: demo features are openToAll, but the auth
+// middleware still requires a valid JWT.
+async function appendDevSessionCookies(headers, jwt) {
+    const token = await jwt.sign(TestUsers.admin);
+    const csrf = generateToken();
+    headers.append("Set-Cookie", `${AUTH_COOKIE}=${token}; Path=/; HttpOnly; SameSite=Lax`);
+    headers.append("Set-Cookie", `${CSRF_COOKIE}=${csrf}; Path=/; SameSite=Lax`);
+}
+// resolvePageHead goes through the same headless resolveAndInjectPageHead
+// that runProdApp uses, so dev and e2e exercise the one timeout and
+// fallback path instead of a second copy of it.
+async function injectDevPageHead(html, resolvePageHead, req, socketAddress, buildSystemQuery) {
+    const url = new URL(req.url);
+    const host = req.headers.get("host") ?? url.host;
+    return resolveAndInjectPageHead(html, resolvePageHead, {
+        path: url.pathname,
+        host,
+        preferredLocales: rankPreferredLocales({
+            queryLang: url.searchParams.get("lang"),
+            acceptLanguage: req.headers.get("accept-language"),
+        }),
+        systemQuery: buildSystemQuery(req, socketAddress),
+        requestSignal: req.signal,
+    });
+}
+export async function respondWithHtmlShell(deps, entryName, req, socketAddress, status = 200) {
+    const template = deps.templates.byEntry.get(entryName) ?? deps.templates.defaultTemplate;
+    const headers = new Headers();
+    headers.set("Content-Type", "text/html; charset=utf-8");
+    if (deps.autoMintJwt)
+        await appendDevSessionCookies(headers, deps.jwt);
+    let html = injectReload(template);
+    if (deps.stylesheetPath !== undefined)
+        html = injectStylesheet(html);
+    if (deps.resolvePageHead !== undefined) {
+        html = await injectDevPageHead(html, deps.resolvePageHead, req, socketAddress, deps.buildSystemQuery);
+    }
+    return new Response(html, { status, headers });
+}
+// Raw file serve, no bundle injection — mirrors prod's `{ kind: "html", file }`.
+export async function respondWithStaticHtmlFile(file, status) {
+    let content;
+    try {
+        content = await readFile(file, "utf-8");
+    }
+    catch (error) {
+        if (errorCodeOf(error) !== "ENOENT")
+            throw error;
+        return new Response(`hostDispatch: file not found: ${file}`, { status: 500 });
+    }
+    return new Response(content, {
+        status,
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+}

package/dist/create-kumiko-server-public-files.d.ts

@@ -0,0 +1,6 @@
+export declare function isRoutableGetOrHead(req: Request, pathname: string): boolean;
+export declare function servePublicFile(pathname: string, publicDir: string): Promise<{
+    readonly bytes: Uint8Array;
+    readonly mime: string;
+} | undefined>;
+export declare function resolveDevPublicDir(): string;

package/dist/create-kumiko-server-public-files.js

@@ -0,0 +1,96 @@
+import { existsSync, realpathSync } from "node:fs";
+import { readFile, realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
+// GET/HEAD to a non-API, non-SSE path — the dispatch-worthy set shared by
+// the SPA catch-all and the public/-file lookup (they split on whether the
+// path has a dot).
+export function isRoutableGetOrHead(req, pathname) {
+    return ((req.method === "GET" || req.method === "HEAD") &&
+        !pathname.startsWith("/api/") &&
+        !pathname.startsWith("/sse"));
+}
+// Resolves a request pathname to a file inside publicDir, or undefined if
+// it isn't one. Two traversal vectors, both must be blocked:
+//   - literal ".." segments (new URL() already collapses these in
+//     `pathname`, but resolve()+containment is checked regardless — no
+//     path-safety may depend on caller behavior upstream).
+//   - percent-encoded slashes (e.g. "%2e%2e%2f"): WHATWG URL parsing only
+//     normalizes dot-segments that are delimited by a literal "/", so an
+//     encoded slash survives into `pathname` untouched. decodeURIComponent
+//     resolves it to "../" before the containment check runs.
+function resolvePublicFilePath(pathname, publicDir) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        return undefined;
+    }
+    // A NUL byte makes readFile throw ERR_INVALID_ARG_VALUE (not ENOENT), which
+    // would surface as a 500 instead of a router miss.
+    if (decoded.includes("\0"))
+        return undefined;
+    const resolved = resolve(publicDir, `.${decoded}`);
+    return resolved === publicDir || resolved.startsWith(publicDir + sep) ? resolved : undefined;
+}
+// Same extension → content-type mapping as prod's
+// run-prod-app-static-files.ts#mimeTypeFor — that function isn't part of
+// server-runtime's public exports (its own package.json "exports" map),
+// so this is a small self-contained copy rather than a new cross-package
+// export for one call site.
+const PUBLIC_FILE_MIME_TYPES = new Map([
+    ["html", "text/html; charset=utf-8"],
+    ["js", "text/javascript; charset=utf-8"],
+    ["mjs", "text/javascript; charset=utf-8"],
+    ["css", "text/css; charset=utf-8"],
+    ["json", "application/json; charset=utf-8"],
+    ["svg", "image/svg+xml"],
+    ["png", "image/png"],
+    ["jpg", "image/jpeg"],
+    ["jpeg", "image/jpeg"],
+    ["ico", "image/x-icon"],
+    ["txt", "text/plain; charset=utf-8"],
+    ["xml", "application/xml; charset=utf-8"],
+    ["webmanifest", "application/manifest+json"],
+    ["woff2", "font/woff2"],
+]);
+function publicFileMimeType(filePath) {
+    const ext = filePath.toLowerCase().split(".").pop() ?? "";
+    return PUBLIC_FILE_MIME_TYPES.get(ext) ?? "application/octet-stream";
+}
+// Reads a file under publicDir for the dev-server's static-asset fallback
+// (dev-parity with prod's disk lookup in buildStaticFallback). undefined
+// means "not a servable file here" — caller treats that as a router miss,
+// same as ENOENT/EISDIR/ENOTDIR further down.
+export async function servePublicFile(pathname, publicDir) {
+    const filePath = resolvePublicFilePath(pathname, publicDir);
+    if (filePath === undefined)
+        return undefined;
+    try {
+        // Lexical containment (above) only catches "..", not a symlink inside
+        // publicDir that points outside it on disk — realpath resolves the
+        // actual target and the same containment check runs against it. Read
+        // from the resolved path so the checked target is the one read.
+        const real = await realpath(filePath);
+        if (real !== publicDir && !real.startsWith(publicDir + sep))
+            return undefined;
+        const bytes = await readFile(real);
+        return { bytes, mime: publicFileMimeType(filePath) };
+    }
+    catch (err) {
+        const code = errorCodeOf(err);
+        if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR" || code === "ENAMETOOLONG") {
+            return undefined;
+        }
+        throw err;
+    }
+}
+// App-root convention (same as the watchDirs patterns and resolveStylesheet):
+// process.cwd() is the app workspace, so public/ is its static asset dir.
+// Symlink-resolved once: servePublicFile compares realpath()s against it, so
+// a symlinked public/ would otherwise 404 every file.
+export function resolveDevPublicDir() {
+    const lexicalPublicDir = resolve(process.cwd(), "public");
+    return existsSync(lexicalPublicDir) ? realpathSync(lexicalPublicDir) : lexicalPublicDir;
+}

package/dist/create-kumiko-server-reload.d.ts

@@ -0,0 +1,14 @@
+export declare function injectReload(html: string): string;
+type ReloadClient = {
+    readonly controller: ReadableStreamDefaultController<Uint8Array>;
+    readonly encoder: TextEncoder;
+    closed: boolean;
+};
+export type DevReloadHub = {
+    readonly bootId: string;
+    readonly clients: Set<ReloadClient>;
+};
+export declare function createReloadHub(): DevReloadHub;
+export declare function broadcastReload(hub: DevReloadHub, changedFile: string): void;
+export declare function openReloadStream(hub: DevReloadHub): Response;
+export {};

package/dist/create-kumiko-server-reload.js

@@ -0,0 +1,73 @@
+// Reload snippet injected into every page-load so the browser
+// subscribes to /_reload without the HTML needing to hard-code it.
+//
+// Two reload triggers:
+//   - explicit `reload` event from the server after hot reload (rebuild + send)
+//   - implicit `boot` event on every SSE connection, containing the current
+//     server process's bootId. The snippet remembers the first bootId; if a
+//     reconnect receives a different one, it refreshes. Otherwise the
+//     browser could remain on a stale bundle after a server restart.
+const RELOAD_SNIPPET = `
+<script>
+  (() => {
+    const es = new EventSource("/_reload");
+    let firstBootId = null;
+    es.addEventListener("boot", (e) => {
+      if (firstBootId === null) {
+        firstBootId = e.data;
+      } else if (firstBootId !== e.data) {
+        location.reload();
+      }
+    });
+    es.addEventListener("reload", () => location.reload());
+  })();
+</script>
+`;
+export function injectReload(html) {
+    if (html.includes("/_reload"))
+        return html;
+    return html.includes("</body>")
+        ? html.replace("</body>", `${RELOAD_SNIPPET}</body>`)
+        : html + RELOAD_SNIPPET;
+}
+export function createReloadHub() {
+    return { bootId: String(Date.now()), clients: new Set() };
+}
+// JSON-encoded so a filename can never break the SSE framing.
+export function broadcastReload(hub, changedFile) {
+    const payload = `event: reload\ndata: ${JSON.stringify(changedFile)}\n\n`;
+    for (const client of hub.clients) {
+        if (client.closed)
+            continue;
+        try {
+            client.controller.enqueue(client.encoder.encode(payload));
+        }
+        catch {
+            client.closed = true;
+        }
+    }
+}
+export function openReloadStream(hub) {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            const entry = { controller, encoder, closed: false };
+            hub.clients.add(entry);
+            controller.enqueue(encoder.encode(": connected\n\n"));
+            controller.enqueue(encoder.encode(`event: boot\ndata: ${hub.bootId}\n\n`));
+        },
+        cancel() {
+            for (const c of hub.clients) {
+                if (c.closed)
+                    hub.clients.delete(c);
+            }
+        },
+    });
+    return new Response(stream, {
+        headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+        },
+    });
+}

package/dist/create-kumiko-server-routes.d.ts

@@ -0,0 +1,16 @@
+/// <reference types="bun-types" preserve="true" />
+import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import type { CreateKumikoServerOptions } from "./create-kumiko-server.ts";
+import { type ClientBundle, type NormalizedEntry } from "./create-kumiko-server-client-bundles.ts";
+import { type DevHtmlTemplates } from "./create-kumiko-server-html.ts";
+import { type DevReloadHub } from "./create-kumiko-server-reload.ts";
+export type DevFetchHandler = (req: Request, socketAddress?: string) => Promise<Response>;
+export declare function createDevFetchHandler(input: {
+    readonly options: CreateKumikoServerOptions;
+    readonly stack: TestStack;
+    readonly entries: readonly NormalizedEntry[];
+    readonly clientBundles: ReadonlyMap<string, ClientBundle>;
+    readonly templates: DevHtmlTemplates;
+    readonly stylesheetPath: string | undefined;
+    readonly reloadHub: DevReloadHub;
+}): DevFetchHandler;

package/dist/create-kumiko-server-routes.js

@@ -0,0 +1,206 @@
+/// <reference types="bun-types" preserve="true" />
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { RENDERER_WEB_FONT_FILE_PATTERN, RENDERER_WEB_FONTS_URL_PREFIX, resolveRendererWebFontsDir, } from "@cosmicdrift/kumiko-server-runtime/renderer-web-fonts";
+import { stripNoRouteMatchHeader, tryHonoFirst, } from "@cosmicdrift/kumiko-server-runtime/try-hono-first";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { indexBundlesByAssetPath, } from "./create-kumiko-server-client-bundles.js";
+import { createDevSystemQueryBuilder, respondWithHtmlShell, respondWithStaticHtmlFile, } from "./create-kumiko-server-html.js";
+import { isRoutableGetOrHead, resolveDevPublicDir, servePublicFile, } from "./create-kumiko-server-public-files.js";
+import { openReloadStream } from "./create-kumiko-server-reload.js";
+const JAVASCRIPT_HEADERS = { "Content-Type": "application/javascript; charset=utf-8" };
+function serveClientBundle({ req, url }, deps) {
+    if (req.method !== "GET")
+        return undefined;
+    const bundleName = deps.bundleByAssetPath.get(url.pathname);
+    if (bundleName === undefined)
+        return undefined;
+    const bundle = deps.clientBundles.get(bundleName);
+    if (bundle === undefined)
+        return new Response("no bundle", { status: 404 });
+    return new Response(bundle.js, { headers: JAVASCRIPT_HEADERS });
+}
+// Looked up in the live bundles instead of a separate index, which a
+// hot-reload rebuild would leave stale.
+function serveBundleChunk({ req, url }, deps) {
+    if (req.method !== "GET")
+        return undefined;
+    for (const bundle of deps.clientBundles.values()) {
+        const chunk = bundle.chunks?.get(url.pathname);
+        if (chunk !== undefined)
+            return new Response(chunk, { headers: JAVASCRIPT_HEADERS });
+    }
+    return undefined;
+}
+function serveBundleSourceMap({ req, url }, deps) {
+    if (req.method !== "GET" || !url.pathname.endsWith(".js.map"))
+        return undefined;
+    const mapName = deps.bundleByAssetPath.get(url.pathname.slice(0, -".map".length));
+    if (mapName === undefined)
+        return undefined;
+    const bundle = deps.clientBundles.get(mapName);
+    if (bundle === undefined || !bundle.map)
+        return new Response("no map", { status: 404 });
+    return new Response(bundle.map, {
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+    });
+}
+async function serveRendererWebFont({ req, url }, deps) {
+    if (!url.pathname.startsWith(RENDERER_WEB_FONTS_URL_PREFIX) || req.method !== "GET") {
+        return undefined;
+    }
+    const fontFile = url.pathname.slice(RENDERER_WEB_FONTS_URL_PREFIX.length);
+    // The allowlist pattern excludes "/", "." segments and encoded traversal.
+    if (deps.rendererWebFontsDir === undefined || !RENDERER_WEB_FONT_FILE_PATTERN.test(fontFile)) {
+        return new Response("not found", { status: 404 });
+    }
+    try {
+        const bytes = await readFile(join(deps.rendererWebFontsDir, fontFile));
+        // @cast-boundary Buffer satisfies BodyInit at runtime, bun-types just doesn't say so.
+        return new Response(bytes, {
+            headers: { "Content-Type": "font/woff2", "Cache-Control": "public, max-age=86400" },
+        });
+    }
+    catch (err) {
+        if (errorCodeOf(err) === "ENOENT") {
+            return new Response("not found", { status: 404 });
+        }
+        throw err;
+    }
+}
+async function serveStylesheet({ req, url }, deps) {
+    if (url.pathname !== "/styles.css" || req.method !== "GET")
+        return undefined;
+    const { stylesheetPath } = deps.html;
+    if (stylesheetPath === undefined)
+        return new Response("no stylesheet", { status: 404 });
+    const css = await readFile(stylesheetPath, "utf-8");
+    return new Response(css, { headers: { "Content-Type": "text/css; charset=utf-8" } });
+}
+function serveReloadStream({ req, url }, deps) {
+    if (url.pathname !== "/_reload" || req.method !== "GET")
+        return undefined;
+    return openReloadStream(deps.reloadHub);
+}
+function respondToNotFoundDispatch(dispatch, { req, socketAddress }, html) {
+    if (dispatch.file !== undefined)
+        return respondWithStaticHtmlFile(dispatch.file, 404);
+    if (dispatch.entryName !== undefined) {
+        return respondWithHtmlShell(html, dispatch.entryName, req, socketAddress, 404);
+    }
+    return new Response("Not Found", { status: 404 });
+}
+// Discriminated dispatch mirrors production; anything that is not a
+// redirect, not-found or static-html result serves its entry's shell.
+function respondToHostDispatch(dispatch, request, html) {
+    switch (dispatch.kind) {
+        case "redirect":
+            return new Response(null, {
+                status: dispatch.status ?? 302,
+                headers: { Location: dispatch.to },
+            });
+        case "not-found":
+            return respondToNotFoundDispatch(dispatch, request, html);
+        case "static-html":
+            return respondWithStaticHtmlFile(dispatch.file, 200);
+        default:
+            return respondWithHtmlShell(html, dispatch.entryName, request.req, request.socketAddress);
+    }
+}
+// SPA catch-all: GET or HEAD requests to non-API, non-asset paths return
+// the HTML shell so the client-side router can mount the screen for
+// location.pathname. Paths containing a dot are left to the public/ lookup.
+//
+// HEAD is included because runProdApp falls back to the SPA for both GET and
+// HEAD. Backend routes outside /api (currently /sse) are excluded, and an
+// r.httpRoute outside /api is tried first, so only a Hono router miss falls
+// back to the shell, matching production.
+async function serveSpaShell(request, deps) {
+    const { req, url, socketAddress } = request;
+    if (!isRoutableGetOrHead(req, url.pathname) || url.pathname.includes("."))
+        return undefined;
+    const honoTry = await tryHonoFirst(deps.app, req, socketAddress);
+    if (honoTry.matched) {
+        return honoTry.response;
+    }
+    if (deps.hostDispatch === undefined) {
+        return respondWithHtmlShell(deps.html, "client", req, socketAddress);
+    }
+    const dispatch = await deps.hostDispatch(req, {
+        systemQuery: deps.html.buildSystemQuery(req, socketAddress),
+        cspScriptHashes: [],
+    });
+    return respondToHostDispatch(dispatch, request, deps.html);
+}
+// Static assets under public/ — prod serves these via buildStaticFallback's
+// disk lookup (run-prod-app-static-files.ts). Hono still goes first (an
+// r.httpRoute could itself own a dotted path), then the file on disk, then
+// the router-miss 404, mirroring the SPA branch.
+async function servePublicAsset({ req, url, socketAddress }, deps) {
+    if (!isRoutableGetOrHead(req, url.pathname) || !url.pathname.includes("."))
+        return undefined;
+    const honoTry = await tryHonoFirst(deps.app, req, socketAddress);
+    if (honoTry.matched) {
+        return honoTry.response;
+    }
+    const file = await servePublicFile(url.pathname, deps.publicDir);
+    if (file !== undefined) {
+        // @cast-boundary Buffer satisfies BodyInit at runtime, bun-types
+        // just doesn't say so — same cast run-prod-app-static-files.ts uses.
+        return new Response(file.bytes, {
+            headers: { "Content-Type": file.mime },
+        });
+    }
+    return honoTry.response;
+}
+// Specific routes first (assets, reload SSE), then the SPA shell and
+// public/ files; whatever is left goes to the Kumiko stack.
+const DEV_ROUTES = [
+    serveClientBundle,
+    serveBundleChunk,
+    serveBundleSourceMap,
+    serveRendererWebFont,
+    serveStylesheet,
+    serveReloadStream,
+    serveSpaShell,
+    servePublicAsset,
+];
+function createDevRouteFetch(deps) {
+    return async (req, socketAddress) => {
+        const request = { req, url: new URL(req.url), socketAddress };
+        for (const route of DEV_ROUTES) {
+            const response = await route(request, deps);
+            if (response !== undefined)
+                return response;
+        }
+        // Bypasses tryHonoFirst entirely (API paths, /sse, non-GET/HEAD), so the
+        // router-miss marker must be stripped here too — otherwise an unmatched
+        // path would leak it straight to the client (see try-hono-first.ts's
+        // header-hygiene note).
+        return stripNoRouteMatchHeader(await deps.app.fetch(req, socketAddress));
+    };
+}
+export function createDevFetchHandler(input) {
+    const { options, stack } = input;
+    const buildSystemQuery = createDevSystemQueryBuilder(stack.dispatcher, options.trustedProxyHops);
+    const routeFetch = createDevRouteFetch({
+        app: stack.app,
+        clientBundles: input.clientBundles,
+        bundleByAssetPath: indexBundlesByAssetPath(input.entries),
+        publicDir: resolveDevPublicDir(),
+        // The app's cwd first, this package's own location as fallback (the cwd
+        // may not have renderer/web installed, e.g. a fixture dir).
+        rendererWebFontsDir: resolveRendererWebFontsDir([process.cwd(), import.meta.dir]),
+        reloadHub: input.reloadHub,
+        hostDispatch: options.hostDispatch,
+        html: {
+            templates: input.templates,
+            jwt: stack.jwt,
+            autoMintJwt: options.auth === undefined,
+            stylesheetPath: input.stylesheetPath,
+            resolvePageHead: options.resolvePageHead,
+            buildSystemQuery,
+        },
+    });
+    return options.wrapFetch ? options.wrapFetch(routeFetch) : routeFetch;
+}

package/dist/create-kumiko-server-shutdown.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="bun-types" preserve="true" />
+import type { TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import type { DevDbMode, DevJobRunners } from "./create-kumiko-server-stack.ts";
+import { type BunServer } from "./dev-server-runtime.ts";
+export type DevServerStopDeps = {
+    readonly watcherAbort: AbortController;
+    readonly killTailwind: (() => void) | undefined;
+    readonly server: BunServer | undefined;
+    readonly stack: TestStack;
+    readonly devJobRunners: DevJobRunners;
+    readonly dbMode: DevDbMode;
+};
+export declare function createDevServerStop(deps: DevServerStopDeps): () => Promise<void>;
+export declare function installDevSignalHandlers(stop: () => Promise<void>): void;

package/dist/create-kumiko-server-shutdown.js

@@ -0,0 +1,72 @@
+import { logError, logInfo } from "./dev-server-runtime.js";
+// The per-boot prefix is never reused, so its BullMQ keys (queues,
+// repeatables, delayed jobs) would pile up in the shared Redis forever.
+// Takes a prefix-less duplicate connection: SCAN returns full key names,
+// which the stack client's keyPrefix would otherwise prepend a second time.
+// The connection must be opened before stack.cleanup() closes the stack
+// client, yet used only after it, because closing the stack's enqueuer
+// queues re-writes their `meta` keys.
+async function deleteEphemeralJobQueues(raw, jobQueueNamePrefix) {
+    try {
+        const keys = [];
+        for await (const batch of raw.scanStream({
+            match: `bull:${jobQueueNamePrefix}-*`,
+            count: 500,
+        })) {
+            keys.push(...batch);
+        }
+        if (keys.length > 0)
+            await raw.del(...keys);
+    }
+    finally {
+        raw.disconnect();
+    }
+}
+export function createDevServerStop(deps) {
+    const { watcherAbort, killTailwind, server, stack, devJobRunners, dbMode } = deps;
+    return async () => {
+        // Stop the watcher first so no onChange callback runs during teardown;
+        // otherwise removing the temporary directory could trigger process.exit(75).
+        watcherAbort.abort();
+        if (killTailwind)
+            killTailwind();
+        if (server !== undefined) {
+            server.stop(true);
+        }
+        if (stack.eventDispatcher) {
+            await stack.eventDispatcher.stop();
+        }
+        await devJobRunners.stop();
+        const rawRedis = dbMode.persistentDb
+            ? undefined
+            : stack.redis.redis.duplicate({ keyPrefix: "" });
+        await stack.cleanup();
+        if (rawRedis)
+            await deleteEphemeralJobQueues(rawRedis, dbMode.jobQueueNamePrefix);
+    };
+}
+function stopAndExitOnCrash(event, stop) {
+    return async (err) => {
+        logError(`[kumiko-server] ${event} — cleaning up…`, err);
+        try {
+            await stop();
+        }
+        finally {
+            process.exit(1);
+        }
+    };
+}
+// Without these handlers, repeated dev restarts leak Postgres pools, leave
+// the Tailwind watcher as an orphan, and leave temporary clients behind in
+// persistent mode; a crash cleans up the same way before exiting nonzero.
+export function installDevSignalHandlers(stop) {
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, async () => {
+            logInfo(`[kumiko-server] ${sig} — cleaning up…`);
+            await stop();
+            process.exit(0);
+        });
+    }
+    process.on("uncaughtException", stopAndExitOnCrash("uncaughtException", stop));
+    process.on("unhandledRejection", stopAndExitOnCrash("unhandledRejection", stop));
+}

package/dist/create-kumiko-server-stack.d.ts

@@ -0,0 +1,12 @@
+import { startDevJobRunners } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
+import { type TestStack } from "@cosmicdrift/kumiko-testing/stack";
+import type { CreateKumikoServerOptions } from "./create-kumiko-server.ts";
+export type DevDbMode = {
+    readonly devDbName: string | undefined;
+    readonly persistentDb: boolean;
+    readonly jobQueueNamePrefix: string;
+};
+export type DevJobRunners = Awaited<ReturnType<typeof startDevJobRunners>>;
+export declare function resolveDevDbMode(processEnv: Record<string, string | undefined>): DevDbMode;
+export declare function bootDevStack(options: CreateKumikoServerOptions, dbMode: DevDbMode): Promise<TestStack>;
+export declare function startDevBackgroundRunners(stack: TestStack, jobQueueNamePrefix: string): Promise<DevJobRunners>;