@cosmicdrift/kumiko-dev-server 0.385.0 → 0.387.0

package/dist/create-kumiko-server.js

@@ -61,14 +61,12 @@ 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.
+// 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>
   (() => {
@@ -95,7 +93,7 @@ const RELOAD_SNIPPET = `
 // 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
+// `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
@@ -159,9 +157,9 @@ function injectReload(html) {
         ? 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.
+// 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;
@@ -280,11 +278,10 @@ async function tryServePublicAsset(req, pathname, app, publicDir, socketAddress)
     return honoTry.response;
 }
 async function watchDir(dir, onChange, signal, watchEvents) {
-    // 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.
+    // The server's stop() aborts the signal; without it, the for-await loop
+    // would continue until process exit. During test teardown, removing the
+    // temporary directory could then be classified as a restart and call
+    // process.exit(75), surfacing as an unhandled Vitest error.
     const watcher = watchEvents(dir, { recursive: true, signal });
     try {
         for await (const ev of watcher) {
@@ -293,37 +290,28 @@ async function watchDir(dir, onChange, signal, watchEvents) {
         }
     }
     catch (err) {
-        // signal.abort() wirft AbortError aus dem async-iterator; das ist
-        // gewollt und kein Fehler. Andere Errors weiterreichen.
+        // signal.abort() causes the async iterator to throw AbortError during
+        // expected teardown; other errors must propagate.
         // skip: AbortSignal fired the abort, this is expected teardown not a real error
         if (typeof err === "object" && err !== null && "name" in err && 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…).
+// Classifies a changed file as `hot-reload` for client-side changes,
+// `restart` for server-side changes whose cached Bun modules must be
+// reloaded, or `ignore` when the server is unaffected.
 //
-// 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)
+// Tests and non-TypeScript files are ignored. TypeScript files under
+// `/web/`, `/admin/`, `/public/`, or `/client/`, as well as the client
+// entry itself, trigger hot reload; other TypeScript files trigger a
+// restart because they may contain schema or feature definitions.
 //
-// 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.
+// The multiple client directories are intentional: samples use different
+// layouts. Restarting for a client-only edit would be slower, drop the
+// ephemeral test database, and reseed it unnecessarily.
 //
-// Exportiert für Tests; intern wird's von der Watcher-Loop gerufen.
+// Exported for tests; internally called by the watcher loop.
 export function classifyChange(filename) {
     if (!filename.endsWith(".ts") && !filename.endsWith(".tsx"))
         return "ignore";
@@ -336,9 +324,9 @@ export function classifyChange(filename) {
         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).
+    // Platform-independent: checks both POSIX and Windows separators.
+    // Matches `<sep><dir><sep>` and trailing-`<sep><dir>` for watcher
+    // filenames supplied as relative paths.
     const clientSubdirs = ["web", "admin", "public", "client"];
     for (const dir of clientSubdirs) {
         if (filename.includes(`/${dir}/`) ||
@@ -361,12 +349,11 @@ export function classifyWatchedChange(watchedDir, filename, entrySourceFiles) {
         ? "hot-reload"
         : classifyChange(filename);
 }
-// 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.
+// Expands watchDirs patterns into concrete directories. Entries without
+// `*` are resolved as ordinary paths; entries with `*` are glob-expanded
+// and only directory matches are retained, so `"../../../packages/*/src"`
+// replaces a list of hard-coded paths. Expansion runs once at boot,
+// not while the watcher is running.
 function expandWatchPatterns(patterns) {
     const out = [];
     for (const p of patterns) {
@@ -421,14 +408,14 @@ export function resolveStylesheet(options) {
     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.
+    // Bun.resolveSync follows package exports: `"./styles.css"` in
+    // renderer/web's package.json resolves to the workspace file in the
+    // monorepo or the node_modules file in an installed app. Bun already
+    // returns an absolute filesystem path, so `fileURLToPath` is unnecessary.
     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.
+        // Node-based unit tests reach this branch. Without Bun, package-export
+        // resolution and a real Tailwind pipeline are unavailable, so skip
+        // silently rather than reporting an error.
         return undefined;
     }
     try {
@@ -470,9 +457,9 @@ async function startTailwindPipeline(entryCss, { 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.
+    // Wait for the initial build so the first /styles.css request does not
+    // return 404. Then run the watcher in the background with unref();
+    // otherwise it could remain as an orphan after the parent crashes.
     try {
         await new Promise((resolvePromise, rejectPromise) => {
             const child = spawn(bunPath, ["run", cliPath, "-i", entryCss, "-o", outPath], {
@@ -505,14 +492,14 @@ async function startTailwindPipeline(entryCss, { watch }) {
                 watcher.kill("SIGTERM");
             }
             catch {
-                // schon tot oder nie gestartet — nicht weiter relevant
+                // Already stopped or never started; no further action is needed.
             }
         },
     };
 }
-/** 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. */
+/** URL path used to serve an entry: `"client"` → `/client.js`
+ *  (the single-entry default), otherwise `/client-<name>.js`. Keeping
+ *  this in one place ensures routing and logging use the same convention. */
 function assetPathFor(entryName) {
     return entryName === "client" ? "/client.js" : `/client-${entryName}.js`;
 }
@@ -537,7 +524,7 @@ function normalizeEntries(options) {
 }
 export async function createKumikoServer(options) {
     const port = options.port ?? Number(process.env["PORT"] ?? 4173);
-    // --- client bundles (single-entry oder multi-entry über dieselbe Map) ---
+    // --- client bundles (single-entry or multi-entry through the same map) ---
     const entries = normalizeEntries(options);
     const buildBundle = options._buildBundle ?? buildClient;
     const clientBundles = new Map();
@@ -568,9 +555,9 @@ export async function createKumikoServer(options) {
         }
     }
     // --- 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.
+    // 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.
     const defaultTemplate = options.htmlPath !== undefined
         ? await readFile(resolve(options.htmlPath), "utf-8")
         : DEFAULT_HTML;
@@ -625,8 +612,8 @@ export async function createKumikoServer(options) {
     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.
+            // The raw ioredis client, not the TestRedis wrapper, matching runProdApp
+            // so application code sees the same interface in development and production.
             redis: stack.redis.redis,
             registry: stack.registry,
             metricsFor: createMetricsForFactory(stack.observability.meter),
@@ -634,20 +621,17 @@ export async function createKumikoServer(options) {
             dispatchSystemQuery: makeDispatchSystemQuery(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).
+    // Hook for caller-specific tables and seeding. It runs after entity tables
+    // are created, so the hook can use `stack.db` / `stack.dispatcher`, and
+    // before the server starts, so the first request sees initialized state. Idempotence is the caller's responsibility because
+    // persistent-DB mode runs the hook on every 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.
+    // setupTestStack configures but does not start the event dispatcher so
+    // integration tests can drain it deterministically with runOnce(). The
+    // dev server starts polling so SSE broadcasts reach connected clients;
+    // otherwise events remain in the events table.
     if (stack.eventDispatcher) {
         await stack.eventDispatcher.start();
     }
@@ -658,22 +642,21 @@ export async function createKumikoServer(options) {
         // 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).
+        // handler works on the request path.
         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).
+        // first call.
         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.
+    // Dev user = TestUsers.admin. Demo features are openToAll, but the
+    // auth middleware still requires a valid JWT. When `options.auth` is set,
+    // the client performs login instead.
     const autoMintJwt = options.auth === undefined;
     const devUser = TestUsers.admin;
     // Build once at boot purely to surface authoring warnings (settings-hub
@@ -685,11 +668,10 @@ export async function createKumikoServer(options) {
         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.
+    // bootId identifies this server process instance. It is sent on connect;
+    // the browser remembers the first value and refreshes when a reconnect
+    // receives a different one, indicating that the server restarted and
+    // the old bundle is stale. See RELOAD_SNIPPET above.
     const bootId = String(Date.now());
     const reloadClients = new Set();
     // JSON-encoded so a filename can never break the SSE framing.
@@ -734,7 +716,7 @@ export async function createKumikoServer(options) {
     });
     // 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).
+    // fallback path instead of a second copy of it.
     const htmlResponse = async (entryName, req, socketAddress, status = 200) => {
         const template = htmlTemplates.get(entryName) ?? defaultTemplate;
         const headers = new Headers();
@@ -781,10 +763,10 @@ export async function createKumikoServer(options) {
         });
     };
     // --- 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.
+    // Bundle path lookup: each entry is served at
+    //   GET /client[-name].js      → JS bundle
+    //   GET /client[-name].js.map  → sourcemap
+    // assetPathFor() is the single source of truth for the URL form.
     const bundleByAssetPath = new Map();
     for (const e of entries)
         bundleByAssetPath.set(assetPathFor(e.name), e.name);
@@ -822,7 +804,7 @@ export async function createKumikoServer(options) {
                     });
                 }
             }
-            // .js.map-Variante: gleicher Lookup mit /.map abgeschnitten.
+            // .js.map variant: perform the same lookup after removing /.map.
             if (url.pathname.endsWith(".js.map")) {
                 const jsPath = url.pathname.slice(0, -".map".length);
                 const mapName = bundleByAssetPath.get(jsPath);
@@ -872,9 +854,9 @@ export async function createKumikoServer(options) {
                     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().
+                    // boot event: the browser snippet compares this with the first
+                    // bootId. A different value after reconnect means the server
+                    // restarted, so location.reload() is called.
                     controller.enqueue(encoder.encode(`event: boot\ndata: ${bootId}\n\n`));
                 },
                 cancel() {
@@ -892,34 +874,28 @@ export async function createKumikoServer(options) {
                 },
             });
         }
-        // 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).
+        // 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 stack's
+        // 404 handling.
         //
-        // 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.
+        // Backend routes outside /api, currently including /sse, must be
+        // excluded so the catch-all does not shadow Hono routes.
         //
-        // 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.
+        // Feature routes declared with r.httpRoute can also be outside /api.
+        // Try stack.app.fetch first so a matching Hono route wins; only a Hono
+        // 404 proceeds to the SPA fallback, matching production behavior.
         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.
+        // Include HEAD: runProdApp falls back to the SPA for both GET and HEAD;
+        // omitting it would make development return 404 where production returns 200.
         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).
+            // Discriminated dispatch mirrors production. Without hostDispatch, use
+            // the single-entry default ("client").
             if (options.hostDispatch !== undefined) {
                 const dispatch = await options.hostDispatch(req, {
                     systemQuery: buildDevSystemQuery(req, socketAddress),
@@ -959,35 +935,32 @@ export async function createKumikoServer(options) {
     };
     const handleFetch = options.wrapFetch ? options.wrapFetch(routeFetch) : routeFetch;
     // --- 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.
+    // Under Node/vitest, skip Bun.serve; the handle's .fetch() is the test
+    // surface. Under Bun, Bun.serve wires the listener.
+    // Bun.serve options come from buildBunServeOptions (run-prod-app.ts) so
+    // development and production share the same SSE-relevant defaults
+    // (idleTimeout: 0); run-prod-app-spec.test.ts pins that.
     const server = hasBun
         ? 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.
+    // --- file watcher → rebundle + reload, or process restart for schema changes ---
+    // Heuristic: files in `web/` or `__tests__/` are client-side or test-only,
+    // so hot reload is sufficient. Other files are server-side; because Bun
+    // caches module imports, a schema change in feature.ts requires a process
+    // restart. Exit with code 75 (EX_TEMPFAIL) so the `kumiko-dev` wrapper
+    // can respawn the process.
     //
-    // 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".
+    // stop() aborts watcherAbort, which ends fs.watch's async iteration. This
+    // prevents a watcher from surviving test teardown and classifying an
+    // rmSync(tmpdir) as "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.
+        // Watch directories: all entry directories (deduplicated) plus the explicit
+        // watchDirs. In multi-entry setups, entries often share a src/ directory
+        // (`src/client-admin.tsx` + `src/client-public.tsx`), so the Set keeps
+        // one watcher per directory.
         const entryDirs = new Set();
         for (const e of entries)
             entryDirs.add(resolve(e.sourceFile, ".."));
@@ -1008,10 +981,9 @@ export async function createKumikoServer(options) {
                     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.
+                    // Rebuild all entries—even when only one file changes, because we do not
+                    // know which entries import it. With shared code, an edit triggers
+                    // both bundles; this is intentional.
                     for (const e of entries) {
                         const rebuilt = await buildBundle(e.sourceFile);
                         clientBundles.set(e.name, rebuilt);
@@ -1050,9 +1022,8 @@ export async function createKumikoServer(options) {
         }
     };
     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).
+        // 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();
@@ -1069,12 +1040,11 @@ export async function createKumikoServer(options) {
             await deleteEphemeralJobQueues(rawRedis);
     };
     // --- 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.
+    // Signal handlers run on Ctrl-C / kill. Without them, repeated dev
+    // restarts leak Postgres pools, leave the Tailwind watcher as an orphan,
+    // and leave temporary clients behind in persistent mode.
+    // uncaughtException and unhandledRejection previously left the Tailwind
+    // watcher running in the background; clean it up before exiting nonzero.
     const installHandlers = options.installSignalHandlers ?? true;
     if (installHandlers) {
         for (const sig of ["SIGINT", "SIGTERM"]) {

package/dist/env-schema.d.ts

@@ -4,7 +4,7 @@ import * as z from "zod";
  *
  *  PORT-default "3000" is the same fallback as
  *  `packages/dev-server/src/run-prod-app.ts:533` — keep in sync when the
- *  call-site is refactored to consume parsed env (Sprint 9.5 Phase 4). */
+ *  call-site is refactored to consume parsed env. */
 export declare const frameworkCoreEnvSchema: z.ZodObject<{
     PORT: z.ZodDefault<z.ZodString>;
     DATABASE_URL: z.ZodURL;

package/dist/env-schema.js

@@ -1,26 +1,26 @@
 // @runtime runtime
 // Consumed at prod boot via composeEnvSchema (same as compose-stacks),
-// not only by tooling — keep runtime-isolation-safe (kumiko-framework#2340).
+// not only by tooling — keep runtime-isolation-safe.
 //
 // Framework-core env-schema — the vars that runProdApp + buildServer
 // + the connection-pool read directly from process.env today. Apps merge
 // this into their app-wide schema via `composeEnvSchema({ core, ... })`.
 //
-// Sprint 9.2 is purely additive: the schema is exposed, but the call-sites
+// The schema is purely additive: it is exposed, but the call-sites
 // in run-prod-app.ts (requireEnv("DATABASE_URL"), …) and api/server.ts
 // (process.env["KUMIKO_INSTANCE_ID"]) keep reading process.env directly.
 // Apps that opt into the schema get aggregated boot-validation errors
 // BEFORE those legacy reads run; apps that don't, behave as before.
 //
 // Feature-specific vars (JWT_SECRET, KUMIKO_SECRETS_MASTER_KEY_*) live
-// in their owning feature's envSchema — Phase 2 (bundled-features).
+// in their owning feature's envSchema (bundled-features).
 import * as z from "zod";
 /** Env-vars read by framework-core (api/server, db/connection,
  *  dev-server/run-prod-app). NOT including feature-specific vars.
  *
  *  PORT-default "3000" is the same fallback as
  *  `packages/dev-server/src/run-prod-app.ts:533` — keep in sync when the
- *  call-site is refactored to consume parsed env (Sprint 9.5 Phase 4). */
+ *  call-site is refactored to consume parsed env. */
 export const frameworkCoreEnvSchema = z.object({
     PORT: z
         .string()

package/dist/index.js

@@ -1,22 +1,22 @@
-// Public API für den Kumiko-Dev-Server. Zwei Schichten:
+// Public API for the Kumiko development server, with two layers:
 //
 //   - createKumikoServer (low-level)
-//     Bun.serve-Wrapper der Client-Bundle, /styles.css, AppSchema-
-//     Injection, SSE-Reload und einen Auto-Mint-JWT-Modus liefert. Nimmt
-//     features + clientEntry direkt an, kein Auth-Auto-Wiring. Wer
-//     einen ungewöhnlichen Auth-Setup braucht (alternative Membership-
-//     Query, eigener Rate-Limiter, custom Login-Routes) geht hier rein.
+//     Bun.serve wrapper that provides the client bundle, /styles.css,
+//     AppSchema injection, SSE reload, and auto-minted JWTs. Accepts
+//     features + clientEntry directly without automatic auth wiring. Use it
+//     for unusual auth setups (alternative Membership query, custom rate
+//     limiter, or custom login routes).
 //
 //   - runDevApp (high-level)
-//     Mischt die Standard-Features (config/user/tenant/auth-email-
-//     password) automatisch dazu wenn `auth` gesetzt ist, wired die
-//     Login-Routes + Error-Map, ruft seedAdminGuarded im onAfterSetup. Default
-//     für Sample-Apps und Showcases — 5-10 Zeilen Bootstrap statt 50.
+//     Automatically adds the standard features (config/user/tenant/
+//     auth-email-password) when `auth` is set, wires the login routes and
+//     error map, and calls seedAdminGuarded in onAfterSetup. The default for
+//     sample apps and showcases: 5–10 lines of bootstrap instead of 50.
 export { composeFeatures, } from "@cosmicdrift/kumiko-server-runtime/compose-features";
-// Build-Toolchain (buildProdBundle, Bun.build, Tailwind-Pipeline, ts-morph) lebt
-// im Sub-Path-Export `@cosmicdrift/kumiko-dev-server/build`. Damit zieht der Main-Barrel
-// kein Bun-Toolchain-Bundle mehr in Production-Reads (z.B. wenn drizzle-kit
-// die App-Config unter Node lädt).
+// The build toolchain (buildProdBundle, Bun.build, Tailwind pipeline, ts-morph)
+// lives in the subpath export `@cosmicdrift/kumiko-dev-server/build`. This keeps
+// the Bun toolchain bundle out of production imports from the main barrel (for
+// example, when drizzle-kit loads the app config under Node).
 export { composeAuthStack, composeFileStack, composeGdprStack, composeIdentityStack, composeMailStack, composeOpsStack, composePagesStack, composeRendererStack, composeSaasStack, composeSecurityStack, composeUserDataRightsStack, stackFeatureNames, } from "./compose-stacks.js";
 export { createKumikoServer, PROD_BUNDLES_ENV, resolveStylesheet, STYLESHEET_WATCH_ENV, } from "./create-kumiko-server.js";
 export { frameworkCoreEnvSchema } from "./env-schema.js";