@cosmicdrift/kumiko-dev-server 0.329.0 → 0.330.2

package/dist/create-kumiko-server.js

@@ -0,0 +1,1040 @@
+/// <reference types="bun-types" preserve="true" />
+// Dev server bootstrap. Wires the real Kumiko stack behind a Bun.serve
+// shell that also bundles the client, serves it at /client.js, mints
+// a JWT for a dev-admin on GET /, and broadcasts SSE reloads when
+// source files change. One import + one call is enough for any
+// sample's server.ts — the 150-line boilerplate of pre-dev-server
+// days lives here now.
+//
+// Not for production:
+//   - auto-mints a JWT for TestUsers.admin on every GET / (anyone
+//     hitting the server ends up as admin)
+//   - bundles the client in-process (prod uses a prebuilt dist)
+//   - no rate-limit, no helmet, no secure-cookie flags
+//
+// The companion prod entry will land at `@cosmicdrift/kumiko-framework/server`
+// with a different options shape (clientDist, auth config, db url).
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, statSync } from "node:fs";
+import { readFile, realpath, watch } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { resolveAnonymousAccessFromRegistry } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { buildRequestContextDataFromRequest, createClientIpResolver, generateToken, requestContext, } from "@cosmicdrift/kumiko-framework/api";
+import { buildAppSchema, createAnonymousUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { pushEntityProjectionTables, setupTestStack, TestUsers, } from "@cosmicdrift/kumiko-framework/stack";
+import { resolveAndInjectPageHead, } from "@cosmicdrift/kumiko-headless/apex";
+import { startDevJobRunners } from "@cosmicdrift/kumiko-server-runtime/boot/job-run-logger";
+import { buildBunServeOptions, resolveDerivedMaxRequestBodySize, } from "@cosmicdrift/kumiko-server-runtime/bun-serve-options";
+import { makeDispatchSystemWrite, } from "@cosmicdrift/kumiko-server-runtime/extra-routes-deps";
+import { RENDERER_WEB_FONT_FILE_PATTERN, RENDERER_WEB_FONTS_URL_PREFIX, resolveRendererWebFontsDir, } from "@cosmicdrift/kumiko-server-runtime/renderer-web-fonts";
+import { canResolveTailwindStylesheet, resolveTailwindCli, } from "@cosmicdrift/kumiko-server-runtime/resolve-tailwind-cli";
+import { stripNoRouteMatchHeader, tryHonoFirst, } from "@cosmicdrift/kumiko-server-runtime/try-hono-first";
+// Runtime-detection. The dev-server is meant to run under Bun (Kumiko's
+// target runtime), but the test-suite runs under vitest on Node — we
+// gate every Bun.* call so the module at least LOADS under Node, and
+// tests drive the fetch-handler directly instead of going through
+// Bun.serve + real sockets.
+const hasBun = typeof globalThis.Bun !== "undefined";
+// @wrapper-known semantic-alias
+// biome-ignore lint/suspicious/noConsole: dev-server status logging
+const logInfo = (msg) => console.log(msg);
+// @wrapper-known semantic-alias
+// biome-ignore lint/suspicious/noConsole: dev-server error logging
+const logError = (...args) => console.error(...args);
+const CSRF_COOKIE = "kumiko_csrf";
+const AUTH_COOKIE = "kumiko_auth";
+// Duplicated in packages/testing/src/e2e/constants.ts: the Playwright config
+// runs under Node and cannot import this module.
+export const STYLESHEET_WATCH_ENV = "KUMIKO_DEV_STYLESHEET_WATCH";
+// Duplicated in packages/testing/src/e2e/constants.ts: the Playwright config
+// runs under Node and cannot import this module.
+export const PROD_BUNDLES_ENV = "KUMIKO_DEV_PROD_BUNDLES";
+// Reload snippet injected into every page-load so the browser
+// subscribes to /_reload without the HTML needing to hard-code it.
+//
+// Zwei reload-Trigger:
+//   - explizites `reload`-Event vom Server beim hot-reload (rebuild + send)
+//   - implizites: jede SSE-Connection bekommt beim Connect ein `boot`-Event
+//     mit der bootId des aktuellen Server-Process. Das Snippet merkt sich
+//     die erste bootId; wenn nach einem Reconnect (Server-Restart!) eine
+//     ANDERE bootId kommt, refresh — sonst bleibt der Browser ewig auf
+//     dem alten Bundle hängen wenn der Watcher classifyChange="restart"
+//     gewählt hat oder der User Ctrl-C/bun dev gemacht hat.
+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>
+`;
+// 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` (fw#1918): 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.
+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>
+`;
+async function buildClient(entry) {
+    if (!hasBun) {
+        throw new Error("[kumiko-server] clientEntry is only supported under Bun — Bun.build is unavailable in this runtime.");
+    }
+    const unminified = process.env["KUMIKO_DEV_UNMINIFIED"] === "1";
+    // Same splitting/sourcemap/NODE_ENV as build-prod-bundle.ts, opt-in via
+    // env so `bun dev` stays unchanged.
+    const prodShaped = process.env[PROD_BUNDLES_ENV] === "1";
+    const built = await Bun.build({
+        entrypoints: [entry],
+        target: "browser",
+        minify: !unminified,
+        sourcemap: prodShaped ? "none" : "linked",
+        splitting: prodShaped,
+        ...(prodShaped ? { define: { "process.env.NODE_ENV": JSON.stringify("production") } } : {}),
+    });
+    if (!built.success) {
+        logError("[kumiko-server] client bundle failed:");
+        for (const log of built.logs)
+            logError(log);
+        throw new Error("client bundle failed");
+    }
+    const jsOutput = built.outputs.find((o) => o.kind === "entry-point");
+    const mapOutput = built.outputs.find((o) => o.path.endsWith(".js.map"));
+    if (!jsOutput)
+        throw new Error("[kumiko-server] client bundle produced no .js output");
+    const chunks = new Map();
+    for (const output of built.outputs) {
+        if (output.kind !== "chunk")
+            continue;
+        const chunkPath = `/${output.path.replace(/^\.\//, "")}`;
+        chunks.set(chunkPath, await output.text());
+    }
+    return {
+        js: await jsOutput.text(),
+        map: mapOutput ? await mapOutput.text() : "",
+        chunks,
+    };
+}
+function injectReload(html) {
+    if (html.includes("/_reload"))
+        return html;
+    return html.includes("</body>")
+        ? html.replace("</body>", `${RELOAD_SNIPPET}</body>`)
+        : html + RELOAD_SNIPPET;
+}
+// Injiziert <link rel="stylesheet" href="/styles.css"> in den <head>,
+// wenn es noch nicht da ist. Wird nur aufgerufen wenn die App das
+// stylesheet-Option genutzt hat — andernfalls kommt keine CSS-Route.
+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}`;
+}
+// GET/HEAD to a non-API, non-SSE path — the dispatch-worthy set shared by
+// the SPA catch-all and the public/-file lookup below (they split on
+// whether the path has a dot).
+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;
+    }
+    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.
+async function servePublicFile(pathname, publicDir) {
+    const filePath = resolvePublicFilePath(pathname, publicDir);
+    if (filePath === undefined)
+        return undefined;
+    try {
+        const bytes = await readFile(filePath);
+        // 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.
+        const real = await realpath(filePath);
+        if (real !== publicDir && !real.startsWith(publicDir + sep))
+            return undefined;
+        return { bytes, mime: publicFileMimeType(filePath) };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR")
+            return undefined;
+        throw err;
+    }
+}
+// Static assets under public/ — prod serves these via buildStaticFallback's
+// disk lookup (run-prod-app-static-files.ts), dev previously had no
+// equivalent: a dotted path (e.g. /marketing/hero.png) fell straight
+// through to the API stack and 404ed. Hono still goes first (an
+// r.httpRoute could itself own a dotted path), then the file on disk,
+// then the router-miss 404 — mirrors handleFetch's SPA branch. undefined
+// means "not a static-asset request", caller falls through to the next
+// route.
+async function tryServePublicAsset(req, pathname, app, publicDir, socketAddress) {
+    if (!isRoutableGetOrHead(req, pathname) || !pathname.includes("."))
+        return undefined;
+    const honoTry = await tryHonoFirst(app, req, socketAddress);
+    if (honoTry.matched) {
+        return honoTry.response;
+    }
+    const file = await servePublicFile(pathname, 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;
+}
+async function watchDir(dir, onChange, signal) {
+    // AbortSignal wird vom Server-stop() ausgelöst: ohne den Abort liefe
+    // die for-await-Schleife bis zum Process-Exit weiter. Im Test-Setup
+    // (afterEach räumt tmpdir mit rmSync auf) sähe der Watcher dann das
+    // rmSync, klassifizierte's als "restart" und riefe process.exit(75) —
+    // bubbles als unhandled error in vitest hoch.
+    const watcher = watch(dir, { recursive: true, signal });
+    try {
+        for await (const ev of watcher) {
+            if (ev.filename)
+                onChange(ev.filename);
+        }
+    }
+    catch (err) {
+        // signal.abort() wirft AbortError aus dem async-iterator; das ist
+        // gewollt und kein Fehler. Andere Errors weiterreichen.
+        // skip: AbortSignal fired the abort, this is expected teardown not a real error
+        if (err.name === "AbortError")
+            return;
+        throw err;
+    }
+}
+// Klassifiziert eine geänderte Datei: `hot-reload` für Client-Side
+// (Browser-Bundle rebuild + reload), `restart` für Server-Side (Bun-
+// Module-Cache zwingt einen Process-Restart durch), `ignore` für
+// alles was den Server nicht beeinflusst (Tests, .css, .json…).
+//
+// Heuristik:
+//   - Tests (`__tests__/` oder `*.test.ts(x)`) → ignore
+//   - `.ts` / `.tsx` außer Tests:
+//       - Client-side-Dirs (`/web/`, `/admin/`, `/public/`, `/client/`)
+//         oder die client-entry-Datei selbst → hot-reload
+//       - sonst → restart (könnte Schema/Feature-Definition sein)
+//   - andere Dateitypen → ignore (kein TS rebuild nötig)
+//
+// Warum mehrere Dirs für client-side: in Kumiko-Samples gibt's keine
+// Convention. publicstatus splittet `/admin/` (Admin-Bundle) und
+// `/public/` (Anonymous-Bundle); beammycar nutzt `/web/` für seine
+// Feature-Web-Code; ältere Samples haben einfach `/client.tsx` neben
+// dem Server. Der Watcher muss alle drei verstehen, sonst löst ein
+// Edit der Bridge-Component einen kompletten Server-Restart aus —
+// kostet 2-3s, droppt die Test-DB im ephemeral-Modus, reseed läuft
+// erneut. Ineffektiv und für der User verwirrend.
+//
+// Exportiert für Tests; intern wird's von der Watcher-Loop gerufen.
+export function classifyChange(filename) {
+    if (!filename.endsWith(".ts") && !filename.endsWith(".tsx"))
+        return "ignore";
+    if (filename.includes("__tests__"))
+        return "ignore";
+    if (filename.endsWith(".test.ts") || filename.endsWith(".test.tsx"))
+        return "ignore";
+    if (filename.endsWith(".integration.ts") ||
+        filename.endsWith(".integration.test.ts") ||
+        filename.endsWith(".e2e.ts")) {
+        return "ignore";
+    }
+    // Plattformpfad-agnostisch: prüfen auf POSIX und Windows-Trenner.
+    // Wir matchen sowohl `<sep><dir><sep>` als auch trailing-`<sep><dir>`
+    // (für Watcher-Filenames die als relativer Pfad ankommen).
+    const clientSubdirs = ["web", "admin", "public", "client"];
+    for (const dir of clientSubdirs) {
+        if (filename.includes(`/${dir}/`) ||
+            filename.includes(`\\${dir}\\`) ||
+            filename.startsWith(`${dir}/`) ||
+            filename.startsWith(`${dir}\\`)) {
+            return "hot-reload";
+        }
+    }
+    if (filename.endsWith("/client.tsx") || filename.endsWith("/client.ts")) {
+        return "hot-reload";
+    }
+    return "restart";
+}
+// Expandiert watchDirs-Patterns auf konkrete Verzeichnisse. Ein Eintrag
+// ohne `*` wird als gewöhnlicher Pfad resolved; mit `*` wird er per
+// glob expanded und alle Treffer die Verzeichnisse sind übernommen.
+// Erlaubt z.B. `"../../../packages/*/src"` statt vier hart-kodierte
+// Pfade. Glob ist sync — wird einmal beim Boot ausgewertet, nicht
+// während der Watcher läuft.
+function expandWatchPatterns(patterns) {
+    const out = [];
+    for (const p of patterns) {
+        if (!p.includes("*")) {
+            out.push(resolve(p));
+            continue;
+        }
+        // expandWatchPatterns wird nur unter Bun aufgerufen (createKumikoServer
+        // ist Bun-only); der ?.! -dance ist nötig weil TS Bun nicht im
+        // globalThis-default sieht. Wenn Bun fehlt, ist der Aufrufstapel eh
+        // schon fail-fast unten in Bun.serve.
+        const BunRef = globalThis.Bun;
+        if (!BunRef)
+            throw new Error("expandWatchPatterns requires Bun.Glob");
+        const glob = new BunRef.Glob(p);
+        const matches = Array.from(glob.scanSync({ onlyFiles: false, cwd: process.cwd() }));
+        for (const m of matches) {
+            const abs = resolve(m);
+            try {
+                if (statSync(abs).isDirectory())
+                    out.push(abs);
+            }
+            catch {
+                // ignore unreadable matches — typisch defekte Symlinks
+            }
+        }
+    }
+    return out;
+}
+// Resolve den Pfad zur Tailwind-Entry-CSS. Mehrere Fälle:
+//   - Explicit string  → den resolved'en absoluten Pfad verwenden
+//   - false            → CSS-Pipeline aus (undefined zurück)
+//   - undefined + client(s):
+//       1. App-eigenes src/styles.css (App-Theme-Override) wenn vorhanden
+//       2. Sonst Default `@cosmicdrift/kumiko-renderer-web/styles.css` über Package-Exports
+//   - undefined + kein clientEntry/clientEntries: undefined (keine CSS nötig)
+//
+// Auto-Detection von src/styles.css spiegelt die Logik aus
+// build-prod-bundle:resolveStylesheetEntry — damit dev und prod identisch
+// resolven. Ohne diesen Check müsste jede App `stylesheet: "./src/styles.css"`
+// setzen, sonst greift in dev der renderer-web-Default und Brand-Tokens
+// werden ignoriert (DX-Falle).
+//
+// @internal — exportiert nur für Unit-Tests, nicht aus dem Package-Index
+//   re-exportiert. Konsumenten gehen ausschließlich über die `stylesheet`-
+//   Option der createKumikoServer-Aufrufstelle.
+export function resolveStylesheet(options) {
+    if (options.stylesheet === false)
+        return undefined;
+    if (typeof options.stylesheet === "string")
+        return resolve(options.stylesheet);
+    const hasAnyEntry = options.clientEntry !== undefined ||
+        (options.clientEntries !== undefined && options.clientEntries.length > 0);
+    if (!hasAnyEntry)
+        return undefined;
+    // App-eigenes src/styles.css schlägt den renderer-web-Default — gleiche
+    // Logik wie kumiko-build, damit lokal/prod identisch bauen.
+    const local = resolve(process.cwd(), "src/styles.css");
+    if (existsSync(local))
+        return local;
+    // Bun.resolveSync folgt Package-Exports — "./styles.css" in renderer-web's
+    // package.json. Das Monorepo auflöst direkt auf den Workspace-File, eine
+    // installierte Fremd-App auf den node_modules-File. Kein `fileURLToPath`
+    // nötig, Bun gibt schon einen absoluten FS-Pfad zurück.
+    if (!hasBun) {
+        // Unit-Tests unter vitest/Node landen hier. Ohne Bun können wir die
+        // Package-Export-Resolution nicht machen — und im Test-Kontext gibt's
+        // keine echte Tailwind-Pipeline. Skip still, keine Fehlermeldung nötig.
+        return undefined;
+    }
+    try {
+        const resolved = globalThis.Bun.resolveSync("@cosmicdrift/kumiko-renderer-web/styles.css", process.cwd());
+        const bun = globalThis.Bun;
+        if (!canResolveTailwindStylesheet(resolved, { bun, cwd: process.cwd() })) {
+            return undefined;
+        }
+        return resolved;
+    }
+    catch (err) {
+        logError("[kumiko-server] couldn't auto-resolve @cosmicdrift/kumiko-renderer-web/styles.css — " +
+            "pass `stylesheet: <path>` or `stylesheet: false` explicitly.", err);
+        return undefined;
+    }
+}
+// The E2E template can only reach an app's own server entry through its env,
+// so the env has to count whenever the option is left undefined.
+//
+// @internal — exported for unit tests only, not re-exported from the index.
+export function resolveStylesheetWatch(options, env = process.env) {
+    if (options.stylesheetWatch !== undefined)
+        return options.stylesheetWatch;
+    return env[STYLESHEET_WATCH_ENV] !== "0";
+}
+// Non-fatal by design (returns undefined): if the CLI can't be resolved or
+// the initial build fails (flaky network, missing dependency), the server
+// boots without CSS instead of dying.
+async function startTailwindPipeline(entryCss, { watch }) {
+    const bunResolver = hasBun
+        ? globalThis.Bun
+        : undefined;
+    const cliPath = resolveTailwindCli({ bun: bunResolver, cwd: process.cwd() });
+    if (cliPath === undefined) {
+        logError("[kumiko-server] @tailwindcss/cli nicht auflösbar — booting ohne CSS-Pipeline. " +
+            "`bun install` und Restart, um Styles zu aktivieren.");
+        return undefined;
+    }
+    const outDir = mkdtempSync(join(tmpdir(), "kumiko-tw-"));
+    const outPath = join(outDir, "styles.css");
+    logInfo(watch
+        ? `[kumiko-server] tailwind watcher → ${outPath}`
+        : `[kumiko-server] tailwind one-shot build → ${outPath}`);
+    const bunPath = process.argv[0] ?? "bun";
+    // Initial-Build blockend, damit der erste /styles.css-Request kein
+    // 404 bekommt. Dann den watcher im Hintergrund mit unref() — sonst
+    // hing er beim Parent-Crash als orphan-process.
+    try {
+        await new Promise((resolvePromise, rejectPromise) => {
+            const child = spawn(bunPath, ["run", cliPath, "-i", entryCss, "-o", outPath], {
+                stdio: "inherit",
+            });
+            child.on("exit", (code) => {
+                if (code === 0)
+                    resolvePromise();
+                else
+                    rejectPromise(new Error(`tailwind one-shot-build exit ${code}`));
+            });
+            child.on("error", rejectPromise);
+        });
+    }
+    catch (err) {
+        logError("[kumiko-server] tailwind one-shot-build fehlgeschlagen — booting ohne CSS:", err);
+        return undefined;
+    }
+    if (!watch) {
+        return { outPath, kill: () => { } };
+    }
+    const watcher = spawn(bunPath, ["run", cliPath, "-i", entryCss, "-o", outPath, "--watch"], {
+        stdio: "inherit",
+    });
+    watcher.unref();
+    return {
+        outPath,
+        kill: () => {
+            try {
+                watcher.kill("SIGTERM");
+            }
+            catch {
+                // schon tot oder nie gestartet — nicht weiter relevant
+            }
+        },
+    };
+}
+/** URL-Pfad unter dem ein Entry ausgeliefert wird. "client" → /client.js
+ *  (Single-Mode-Default), sonst "/client-<name>.js". Single-Source-of-Truth
+ *  damit Routing + Logging dieselbe Konvention nutzen. */
+function assetPathFor(entryName) {
+    return entryName === "client" ? "/client.js" : `/client-${entryName}.js`;
+}
+function normalizeEntries(options) {
+    if (options.clientEntries !== undefined && options.clientEntry !== undefined) {
+        throw new Error("[kumiko-server] clientEntry und clientEntries sind mutually exclusive — wähle eins");
+    }
+    if (options.clientEntries !== undefined && options.clientEntries.length > 0) {
+        if (options.hostDispatch === undefined) {
+            throw new Error("[kumiko-server] clientEntries braucht hostDispatch — sonst weiß der Server nicht welches Template er liefern soll");
+        }
+        return options.clientEntries.map((e) => ({
+            name: e.name,
+            sourceFile: resolve(e.sourceFile),
+            htmlPath: e.htmlPath,
+        }));
+    }
+    if (options.clientEntry !== undefined) {
+        return [{ name: "client", sourceFile: resolve(options.clientEntry), htmlPath: undefined }];
+    }
+    return [];
+}
+export async function createKumikoServer(options) {
+    const port = options.port ?? Number(process.env["PORT"] ?? 4173);
+    // --- client bundles (single-entry oder multi-entry über dieselbe Map) ---
+    const entries = normalizeEntries(options);
+    const buildBundle = options._buildBundle ?? buildClient;
+    const clientBundles = new Map();
+    for (const e of entries) {
+        const bundle = await buildBundle(e.sourceFile);
+        clientBundles.set(e.name, bundle);
+        logInfo(`[kumiko-server] client bundle ${e.name}: ${bundle.js.length.toLocaleString()} bytes` +
+            (bundle.map ? ` (+ ${bundle.map.length.toLocaleString()} bytes sourcemap)` : ""));
+    }
+    // --- Tailwind stylesheet (optional) ---
+    // The Tailwind CLI writes to a temp file that every /styles.css request
+    // reads fresh: no in-memory signalling needed, and the browser only
+    // reloads after a bundle rebuild anyway.
+    //
+    // Without an explicit `stylesheet`, the default resolves through the
+    // package exports of `@cosmicdrift/kumiko-renderer-web`, which works both
+    // for a workspace link and for an installed app (node_modules).
+    let stylesheetPath;
+    let killTailwind;
+    const resolvedStylesheet = resolveStylesheet(options);
+    if (resolvedStylesheet !== undefined) {
+        const handle = await startTailwindPipeline(resolvedStylesheet, {
+            watch: resolveStylesheetWatch(options),
+        });
+        if (handle !== undefined) {
+            stylesheetPath = handle.outPath;
+            killTailwind = handle.kill;
+        }
+    }
+    // --- HTML templates ---
+    // Single-Entry: ein Template (htmlPath oder DEFAULT_HTML) für alles.
+    // Multi-Entry: pro Entry ein Template (entry.htmlPath ?? options.htmlPath
+    // ?? DEFAULT_HTML). Der hostDispatch wählt zur Request-Zeit.
+    const defaultTemplate = options.htmlPath !== undefined
+        ? await readFile(resolve(options.htmlPath), "utf-8")
+        : DEFAULT_HTML;
+    const htmlTemplates = new Map();
+    for (const e of entries) {
+        htmlTemplates.set(e.name, e.htmlPath !== undefined ? await readFile(resolve(e.htmlPath), "utf-8") : defaultTemplate);
+    }
+    // --- Kumiko stack ---
+    // KUMIKO_DEV_DB_NAME switches the underlying testDb from ephemeral
+    // (fresh kumiko_test_<random>, dropped on cleanup) to persistent
+    // (reuses the named DB across restarts). The var is framework-scoped
+    // on purpose — every dev-server pattern benefits from the same
+    // toggle, not just one sample.
+    const devDbName = process.env["KUMIKO_DEV_DB_NAME"];
+    const persistentDb = devDbName !== undefined && devDbName !== "";
+    // Redis is shared across boots AND across apps (unlike the per-boot test
+    // DB, which is ephemeral or persistent per KUMIKO_DEV_DB_NAME), so every
+    // boot needs its own queue-name prefix — otherwise two dev/e2e servers
+    // running in parallel drain each other's queues ("Unknown job: ..."). A
+    // persistent DB implies a stable prefix so jobs survive a restart; an
+    // ephemeral DB gets a fresh prefix per boot, matching the fresh DB.
+    const jobQueueNamePrefix = persistentDb
+        ? `kumiko-dev-${devDbName}`
+        : `kumiko-dev-${crypto.randomUUID()}`;
+    logInfo(`[kumiko-server] booting Kumiko stack${persistentDb ? ` — persistent DB "${devDbName}"` : " — ephemeral test DB"}…`);
+    const stack = await setupTestStack({
+        features: options.features,
+        ...(persistentDb && { dbName: devDbName, persistentDb: true }),
+        ...(options.auth !== undefined && { authConfig: options.auth }),
+        ...(options.extraContext !== undefined && { extraContext: options.extraContext }),
+        ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
+        enrichAnonymousAccess: (base, deps) => resolveAnonymousAccessFromRegistry(base, deps),
+        ...(options.files !== undefined && { files: options.files }),
+        ...(options.effectiveFeatures !== undefined && {
+            effectiveFeatures: options.effectiveFeatures,
+        }),
+        ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
+        ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
+        // jobs.consumerLane unset = enqueuer-only; startDevJobRunners below is
+        // the sole consumer/cron-scheduler per lane, so runOnBoot/cron jobs
+        // don't double-fire. queueNamePrefix keeps this boot's queues isolated
+        // from every other dev/e2e server sharing the same Redis.
+        jobs: { queueNamePrefix: jobQueueNamePrefix },
+    });
+    await createEventsTable(stack.db);
+    await pushEntityProjectionTables(stack, stack.registry);
+    // `extraRoutes` is already mounted — setupTestStack's buildServer() call
+    // wired it above, before this function ever runs. `wire` is the
+    // remaining escape-hatch for app-wired co-running components that need
+    // the system-write dispatcher but don't declare a route.
+    if (options.wire !== undefined) {
+        await options.wire({
+            db: stack.db,
+            // Der nackte ioredis-Client (nicht der TestRedis-Wrapper) —
+            // Parität mit runProdApp, App-Code soll in dev+prod dasselbe sehen.
+            redis: stack.redis.redis,
+            registry: stack.registry,
+            dispatchSystemWrite: makeDispatchSystemWrite(stack.dispatcher),
+        });
+    }
+    // Hook für Caller-spezifische Tables + Seed. Läuft nach den Entity-
+    // Tabellen damit das Sample auf `stack.db` / `stack.dispatcher`
+    // zugreifen kann, und VOR dem Server-Start damit der erste HTTP-Request
+    // bereits gegen einen gefüllten State läuft. Idempotenz ist Caller-
+    // Verantwortung (persistent-DB-Modus läuft es bei jedem Boot).
+    if (options.onAfterSetup !== undefined) {
+        await options.onAfterSetup(stack);
+    }
+    // setupTestStack konfiguriert den eventDispatcher, startet ihn aber
+    // NICHT — Integration-Tests drain'en deterministisch via runOnce().
+    // Ein Dev-Server will das laufende Polling, damit SSE-Broadcasts
+    // (system-hook sse, Priorität 1001) von selbst an connected Clients
+    // fließen. Ohne start() bleiben alle Events in der events-Tabelle
+    // liegen und die Tabs sehen nichts.
+    if (stack.eventDispatcher) {
+        await stack.eventDispatcher.start();
+    }
+    const redisUrl = `redis://${stack.redis.redis.options.host}:${stack.redis.redis.options.port}/${stack.redis.redis.options.db}`;
+    const devJobRunners = await startDevJobRunners({
+        registry: stack.registry,
+        db: stack.db,
+        // The stack's own AppContext, not a `{ db, registry }` literal: these
+        // runners consume the lanes, and a job reaching for ctx.files /
+        // ctx.notify / ctx.config would otherwise die here while the very same
+        // handler works on the request path (kumiko-framework#1232).
+        context: stack.context,
+        redisUrl,
+        // Same dispatcher the request path writes through — without this,
+        // ctx.write/ctx.writeAs/ctx.queryAs inside a dev-run job throw on their
+        // first call (kumiko-framework#2553).
+        dispatcher: stack.dispatcher,
+        // Same isolation reasoning as setupTestStack's jobs.queueNamePrefix
+        // above — both must use the same prefix so enqueuer and consumer agree
+        // on queue names.
+        queueNamePrefix: jobQueueNamePrefix,
+    });
+    // Dev user = TestUsers.admin. Demo features are openToAll but the
+    // auth-middleware still needs a valid JWT to let the request past.
+    // Nicht genutzt wenn `options.auth` gesetzt ist — dann macht der Client
+    // selbst den Login.
+    const autoMintJwt = options.auth === undefined;
+    const devUser = TestUsers.admin;
+    // Build once at boot purely to surface authoring warnings (settings-hub
+    // placement etc.) at the same point prod would — clients fetch the actual
+    // schema themselves from GET /api/schema, so the result itself is
+    // discarded here.
+    buildAppSchema(stack.registry, {
+        authoringWarnings: true,
+        searchAdapterMissing: !stack.context.searchAdapter,
+    });
+    // --- SSE reload ---
+    // bootId identifiziert diese spezifische Server-Process-Instanz. Wird
+    // beim Connect an jeden Browser geschickt; Browser merkt sich den
+    // ersten Wert und refresht wenn beim Reconnect ein anderer kommt
+    // (= Server wurde restartet, alter JS-Bundle ist stale). Siehe
+    // RELOAD_SNIPPET oben.
+    const bootId = String(Date.now());
+    const reloadClients = new Set();
+    const broadcastReload = () => {
+        const payload = "event: reload\ndata: now\n\n";
+        for (const client of reloadClients) {
+            if (client.closed)
+                continue;
+            try {
+                client.controller.enqueue(client.encoder.encode(payload));
+            }
+            catch {
+                client.closed = true;
+            }
+        }
+    };
+    // Build a fresh HTML response. In auto-mint mode (no auth config) we
+    // pack a valid JWT + CSRF cookie right in — deep-links work immediately
+    // without login (and that auth cookie is what a client-side fetch to
+    // GET /api/schema authenticates with). In auth mode we serve the bare
+    // HTML; the client then goes through /auth/login and gets its cookies
+    // from there.
+    //
+    // entryName is decided by the caller (handleFetch) after evaluating
+    // hostDispatch. Without hostDispatch it's always "client" (single-entry
+    // default).
+    //
+    // Anonymous-role systemQuery, shared by resolvePageHead and hostDispatch —
+    // mirrors runProdApp's HostDispatchFn deps so dev/prod stay symmetric.
+    // Own resolver mirroring the same effective hops as setupTestStack's
+    // internal buildServer — this path runs for
+    // page-head/hostDispatch resolution, 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 — see CreateKumikoServerOptions.trustedProxyHops).
+    const pageHeadClientIpResolver = createClientIpResolver(options.trustedProxyHops ?? 0, "createKumikoServer(pageHead)");
+    const buildDevSystemQuery = (req, socketAddress) => (type, payload, tenantId) => requestContext.run(requestContext.get() ??
+        buildRequestContextDataFromRequest(req, {
+            resolver: pageHeadClientIpResolver,
+            socketAddress,
+        }), () => stack.dispatcher.query(type, payload, createAnonymousUser(tenantId)));
+    // 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 (#3026).
+    const htmlResponse = async (entryName, req, socketAddress) => {
+        const template = htmlTemplates.get(entryName) ?? defaultTemplate;
+        const headers = new Headers();
+        headers.set("Content-Type", "text/html; charset=utf-8");
+        if (autoMintJwt) {
+            const jwt = await stack.jwt.sign(devUser);
+            const csrf = generateToken();
+            headers.append("Set-Cookie", `${AUTH_COOKIE}=${jwt}; Path=/; HttpOnly; SameSite=Lax`);
+            headers.append("Set-Cookie", `${CSRF_COOKIE}=${csrf}; Path=/; SameSite=Lax`);
+        }
+        let html = injectReload(template);
+        if (stylesheetPath !== undefined)
+            html = injectStylesheet(html);
+        if (options.resolvePageHead !== undefined) {
+            const url = new URL(req.url);
+            const host = req.headers.get("host") ?? url.host;
+            html = await resolveAndInjectPageHead(html, options.resolvePageHead, {
+                path: url.pathname,
+                host,
+                systemQuery: buildDevSystemQuery(req, socketAddress),
+            });
+        }
+        return new Response(html, { headers });
+    };
+    // --- Fetch handler (runtime-neutral) ---
+    // Bundle-Pfad-Lookup: für jede Entry serven wir
+    //   GET /client[-name].js      → JS-Bundle
+    //   GET /client[-name].js.map  → Sourcemap
+    // assetPathFor() ist die Single-Source-of-Truth für die URL-Form.
+    const bundleByAssetPath = new Map();
+    for (const e of entries)
+        bundleByAssetPath.set(assetPathFor(e.name), e.name);
+    // App-root convention (same as expandWatchPatterns/resolveStylesheet above):
+    // process.cwd() is the app workspace, so public/ is its static asset dir.
+    const publicDir = resolve(process.cwd(), "public");
+    // 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).
+    const rendererWebFontsDir = resolveRendererWebFontsDir([process.cwd(), import.meta.dir]);
+    const handleFetch = async (req, socketAddress) => {
+        const url = new URL(req.url);
+        // Specific routes first — assets, reload-SSE, API.
+        if (req.method === "GET") {
+            const bundleName = bundleByAssetPath.get(url.pathname);
+            if (bundleName !== undefined) {
+                const bundle = clientBundles.get(bundleName);
+                if (bundle === undefined)
+                    return new Response("no bundle", { status: 404 });
+                return new Response(bundle.js, {
+                    headers: { "Content-Type": "application/javascript; charset=utf-8" },
+                });
+            }
+            // Looked up in the live bundles instead of a separate index, which a
+            // hot-reload rebuild would leave stale.
+            for (const bundle of clientBundles.values()) {
+                const chunk = bundle.chunks?.get(url.pathname);
+                if (chunk !== undefined) {
+                    return new Response(chunk, {
+                        headers: { "Content-Type": "application/javascript; charset=utf-8" },
+                    });
+                }
+            }
+            // .js.map-Variante: gleicher Lookup mit /.map abgeschnitten.
+            if (url.pathname.endsWith(".js.map")) {
+                const jsPath = url.pathname.slice(0, -".map".length);
+                const mapName = bundleByAssetPath.get(jsPath);
+                if (mapName !== undefined) {
+                    const bundle = 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" },
+                    });
+                }
+            }
+        }
+        if (url.pathname.startsWith(RENDERER_WEB_FONTS_URL_PREFIX) && req.method === "GET") {
+            const fontFile = url.pathname.slice(RENDERER_WEB_FONTS_URL_PREFIX.length);
+            // The allowlist pattern excludes "/", "." segments and encoded traversal.
+            if (rendererWebFontsDir === undefined || !RENDERER_WEB_FONT_FILE_PATTERN.test(fontFile)) {
+                return new Response("not found", { status: 404 });
+            }
+            try {
+                const bytes = await readFile(join(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 (err.code === "ENOENT") {
+                    return new Response("not found", { status: 404 });
+                }
+                throw err;
+            }
+        }
+        if (url.pathname === "/styles.css" && req.method === "GET") {
+            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" },
+            });
+        }
+        if (url.pathname === "/_reload" && req.method === "GET") {
+            const encoder = new TextEncoder();
+            const stream = new ReadableStream({
+                start(controller) {
+                    const entry = { controller, encoder, closed: false };
+                    reloadClients.add(entry);
+                    controller.enqueue(encoder.encode(": connected\n\n"));
+                    // boot-Event: Browser-Snippet vergleicht das mit der ersten
+                    // bootId. Verschiedener Wert nach Reconnect = Server wurde
+                    // restartet → location.reload().
+                    controller.enqueue(encoder.encode(`event: boot\ndata: ${bootId}\n\n`));
+                },
+                cancel() {
+                    for (const c of reloadClients) {
+                        if (c.closed)
+                            reloadClients.delete(c);
+                    }
+                },
+            });
+            return new Response(stream, {
+                headers: {
+                    "Content-Type": "text/event-stream",
+                    "Cache-Control": "no-cache",
+                    Connection: "keep-alive",
+                },
+            });
+        }
+        // SPA catch-all: any GET to a non-API, non-asset path returns the
+        // HTML shell. The client-side router then reads location.pathname
+        // and mounts the right screen. The "no dot" filter skips
+        // /favicon.ico etc. (let the stack's 404 handler respond).
+        //
+        // Backend routes that live outside /api (currently just /sse) have
+        // to be excluded explicitly, otherwise the catch-all would shadow
+        // the real Hono route with HTML and EventSource would never
+        // connect.
+        //
+        // Plus: r.httpRoute-deklarierte Feature-Routes (z.B. /legal/*) liegen
+        // ebenfalls außerhalb /api und matchen sonst diesen catch-all. Wir
+        // probieren daher ZUERST stack.app.fetch — wenn Hono eine matchende
+        // Route hat, gewinnt sie. 404 vom Hono-stack → SPA-fallback wie
+        // bisher. Das spiegelt runProdApp's doc-intent ("Hono matched VOR
+        // staticDir-fallback") und macht r.httpRoute mit non-/api paths im
+        // dev-server symmetrisch zu prod.
+        if (
+        // HEAD mitnehmen — prod (runProdApp) fällt für GET UND HEAD auf die
+        // SPA zurück; ohne das liefert dev 404 wo prod 200 liefert.
+        isRoutableGetOrHead(req, url.pathname) &&
+            !url.pathname.includes(".")) {
+            const honoTry = await tryHonoFirst(stack.app, req, socketAddress);
+            if (honoTry.matched) {
+                return honoTry.response;
+            }
+            // Discriminated-Dispatch — symmetric zu prod. Ohne hostDispatch
+            // landet das im Single-Entry-Default ("client" + Schema-Inject).
+            if (options.hostDispatch !== undefined) {
+                const dispatch = await options.hostDispatch(req, {
+                    systemQuery: buildDevSystemQuery(req, socketAddress),
+                });
+                if (dispatch.kind === "redirect") {
+                    return new Response(null, {
+                        status: dispatch.status ?? 302,
+                        headers: { Location: dispatch.to },
+                    });
+                }
+                if (dispatch.kind === "not-found") {
+                    return new Response("Not Found", { status: 404 });
+                }
+                if (dispatch.kind === "static-html") {
+                    // Raw file serve, no bundle injection — mirrors prod's
+                    // `{ kind: "html", file: ... }` static-html branch.
+                    const file = await readFile(dispatch.file, "utf-8");
+                    return new Response(file, {
+                        headers: { "Content-Type": "text/html; charset=utf-8" },
+                    });
+                }
+                return htmlResponse(dispatch.entryName, req, socketAddress);
+            }
+            return htmlResponse("client", req, socketAddress);
+        }
+        // Static assets under public/ — see tryServePublicAsset's own comment
+        // for the Hono → file → router-miss ordering.
+        const staticAsset = await tryServePublicAsset(req, url.pathname, stack.app, publicDir, socketAddress);
+        if (staticAsset !== undefined)
+            return staticAsset;
+        // 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 stack.app.fetch(req, socketAddress));
+    };
+    // --- HTTP server (Bun only) ---
+    // Under Node/vitest we skip Bun.serve entirely — the handle's
+    // .fetch() is the test surface. Real dev runs under Bun, where
+    // Bun.serve wires the listener.
+    // Bun.serve-Options kommen aus buildBunServeOptions (run-prod-app.ts)
+    // damit Dev und Prod genau dieselben SSE-relevanten Defaults nutzen
+    // (idleTimeout: 0). Spec-Test in run-prod-app-spec.test.ts pinst das.
+    const server = hasBun
+        ? globalThis.Bun.serve(buildBunServeOptions(port, handleFetch, resolveDerivedMaxRequestBodySize(stack.registry), {
+            upgradeFetch: async (req, env) => stripNoRouteMatchHeader(await stack.app.fetch(req, env)),
+        }))
+        : undefined;
+    // --- file watcher → rebundle + reload, oder process-restart bei Schema-Änderungen ---
+    // Heuristik: alles in `web/` oder `__tests__/` ist client-side oder
+    // test-only — Hot-Reload reicht (rebuild + broadcast reload). Alles
+    // andere ist server-side; Bun cached die Module-Imports, also würde ein
+    // Schema-Change in feature.ts nicht durchschlagen ohne process-restart.
+    // Wir exiten dann mit Code 75 (EX_TEMPFAIL) — `kumiko-dev` Wrapper
+    // detected das und respawnt.
+    //
+    // watcherAbort wird beim stop() ausgelöst → fs.watch beendet die
+    // async-iteration → kein Watcher überlebt einen Test-Teardown und
+    // klassifiziert ein rmSync(tmpdir) als "restart needed".
+    const watcherAbort = new AbortController();
+    if (entries.length > 0) {
+        // Watch-Dirs: alle entry-Verzeichnisse (deduped) plus die explizit
+        // angegebenen watchDirs. In Multi-Entry-Setups liegen die Entries
+        // oft im selben src/-Verzeichnis (`src/client-admin.tsx` +
+        // `src/client-public.tsx`) — der Set kollabiert das auf einen
+        // Watcher pro Verzeichnis.
+        const entryDirs = new Set();
+        for (const e of entries)
+            entryDirs.add(resolve(e.sourceFile, ".."));
+        const dirs = [...entryDirs, ...expandWatchPatterns(options.watchDirs ?? [])];
+        for (const dir of dirs) {
+            void watchDir(dir, async (filename) => {
+                const action = classifyChange(filename);
+                // skip: file change classified as ignore (test/css/json), nothing to rebuild
+                if (action === "ignore")
+                    return;
+                if (action === "restart") {
+                    logInfo(`[kumiko-server] schema change in ${filename} — restarting (Bun caches imports, hot-reload reicht hier nicht). ` +
+                        "The kumiko-dev wrapper (package.json's `dev` script) respawns automatically " +
+                        "and re-syncs new r.entity() columns on the new boot; running this entry " +
+                        "directly (not via kumiko-dev) exits here without restarting.");
+                    await stop();
+                    process.exit(75);
+                }
+                try {
+                    // Alle Entries rebuilden — auch wenn nur eine Datei sich
+                    // ändert, wir wissen nicht welche Entries sie importieren.
+                    // Bei zwei Entries mit shared Code triggert ein Edit der
+                    // gemeinsamen Datei beide Bundles neu, das ist gewollt.
+                    for (const e of entries) {
+                        const rebuilt = await buildBundle(e.sourceFile);
+                        clientBundles.set(e.name, rebuilt);
+                    }
+                    logInfo(`[kumiko-server] rebuilt on ${filename}, broadcasting reload`);
+                    broadcastReload();
+                }
+                catch {
+                    // buildClient already logged the failure; keep serving the
+                    // last good bundle until the next successful rebuild.
+                }
+            }, watcherAbort.signal);
+        }
+    }
+    const stop = async () => {
+        // Watcher zuerst stoppen damit kein onChange während des Teardowns
+        // mehr feuert (sonst können tmpdir-rmSync ein process.exit(75)
+        // auslösen).
+        watcherAbort.abort();
+        if (killTailwind)
+            killTailwind();
+        if (server !== undefined) {
+            server.stop(true);
+        }
+        if (stack.eventDispatcher) {
+            await stack.eventDispatcher.stop();
+        }
+        await devJobRunners.stop();
+        await stack.cleanup();
+    };
+    // --- graceful shutdown ---
+    // Signal handlers fire on Ctrl-C / kill. Without them, repeated dev
+    // restarts leak Postgres pools, lassen Tailwind-Watcher als orphan
+    // hängen und (in persistent mode) hinterlassen temp Clients.
+    // uncaughtException + unhandledRejection: Crashes hatten den Tailwind-
+    // Watcher nicht gekillt, der lief munter weiter im Hintergrund. Jetzt
+    // räumen wir auch im Fehlerfall auf bevor wir mit non-zero exit'n.
+    const installHandlers = options.installSignalHandlers ?? true;
+    if (installHandlers) {
+        for (const sig of ["SIGINT", "SIGTERM"]) {
+            process.on(sig, async () => {
+                logInfo(`[kumiko-server] ${sig} — cleaning up…`);
+                await stop();
+                process.exit(0);
+            });
+        }
+        process.on("uncaughtException", async (err) => {
+            logError("[kumiko-server] uncaughtException — cleaning up…", err);
+            try {
+                await stop();
+            }
+            finally {
+                process.exit(1);
+            }
+        });
+        process.on("unhandledRejection", async (err) => {
+            logError("[kumiko-server] unhandledRejection — cleaning up…", err);
+            try {
+                await stop();
+            }
+            finally {
+                process.exit(1);
+            }
+        });
+    }
+    if (server !== undefined) {
+        logInfo(`[kumiko-server] listening on http://localhost:${port}` +
+            (entries.length > 0
+                ? ` (hot reload on ${entries.length === 1 ? "client entry" : `${entries.length} entries`})`
+                : ""));
+    }
+    return { fetch: handleFetch, server, stack, stop };
+}