@cosmicdrift/kumiko-dev-server 0.85.0 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -50,8 +50,8 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.85.0",
-    "@cosmicdrift/kumiko-framework": "0.85.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.87.0",
+    "@cosmicdrift/kumiko-framework": "0.87.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/cache-headers.test.ts

@@ -1,77 +1,83 @@
-// Unit-Tests für cacheHeadersFor — die Cache-Strategie hinter
+// Unit-Tests für staticCachePolicy — die Cache-Strategie hinter
 // runProdApp's static-fallback. Pure function, leicht zu testen.
 //
 // Strategie (siehe run-prod-app.ts):
-//   /assets/*               → max-age=31536000, immutable
-//   /, /index.html          → no-cache, must-revalidate
+//   /assets/*               → immutable
+//   /, /index.html          → revalidate (max-age=0, must-revalidate)
 //   /manifest.json, /sw.js,
 //   /build-info.json        → no-cache
-//   alles andere            → kein expliziter Header
+//   alles andere            → none
 
 import { describe, expect, test } from "bun:test";
-import { cacheHeadersFor } from "../run-prod-app";
+import { cacheControlHeader } from "@cosmicdrift/kumiko-framework/api";
+import { staticCachePolicy } from "../run-prod-app";
 
-describe("cacheHeadersFor", () => {
+function cacheControlFor(pathname: string): Record<string, string> {
+  const header = cacheControlHeader(staticCachePolicy(pathname));
+  return header === undefined ? {} : { "cache-control": header };
+}
+
+describe("staticCachePolicy", () => {
   test("hashed asset → immutable + 1 Jahr", () => {
-    expect(cacheHeadersFor("/assets/client-abc123.js")).toEqual({
+    expect(cacheControlFor("/assets/client-abc123.js")).toEqual({
       "cache-control": "public, max-age=31536000, immutable",
     });
   });
 
   test("hashed CSS asset → immutable + 1 Jahr", () => {
-    expect(cacheHeadersFor("/assets/styles-def456.css")).toEqual({
+    expect(cacheControlFor("/assets/styles-def456.css")).toEqual({
       "cache-control": "public, max-age=31536000, immutable",
     });
   });
 
   test("nested asset path → immutable", () => {
-    expect(cacheHeadersFor("/assets/chunks/foo-789.js")).toEqual({
+    expect(cacheControlFor("/assets/chunks/foo-789.js")).toEqual({
       "cache-control": "public, max-age=31536000, immutable",
     });
   });
 
-  test("/ → no-cache, must-revalidate", () => {
-    expect(cacheHeadersFor("/")).toEqual({
-      "cache-control": "no-cache, must-revalidate",
+  test("/ → revalidate", () => {
+    expect(cacheControlFor("/")).toEqual({
+      "cache-control": "public, max-age=0, must-revalidate",
     });
   });
 
-  test("/index.html → no-cache, must-revalidate", () => {
-    expect(cacheHeadersFor("/index.html")).toEqual({
-      "cache-control": "no-cache, must-revalidate",
+  test("/index.html → revalidate", () => {
+    expect(cacheControlFor("/index.html")).toEqual({
+      "cache-control": "public, max-age=0, must-revalidate",
     });
   });
 
   test("/manifest.json → no-cache", () => {
-    expect(cacheHeadersFor("/manifest.json")).toEqual({
+    expect(cacheControlFor("/manifest.json")).toEqual({
       "cache-control": "no-cache",
     });
   });
 
   test("/sw.js → no-cache", () => {
-    expect(cacheHeadersFor("/sw.js")).toEqual({
+    expect(cacheControlFor("/sw.js")).toEqual({
       "cache-control": "no-cache",
     });
   });
 
   test("/build-info.json → no-cache (sonst pollt UpdateChecker eine veraltete id)", () => {
-    expect(cacheHeadersFor("/build-info.json")).toEqual({
+    expect(cacheControlFor("/build-info.json")).toEqual({
       "cache-control": "no-cache",
     });
   });
 
   test("public-folder file (favicon) → kein expliziter Header", () => {
-    expect(cacheHeadersFor("/favicon.ico")).toEqual({});
+    expect(cacheControlFor("/favicon.ico")).toEqual({});
   });
 
   test("public-folder file (og-image) → kein expliziter Header", () => {
-    expect(cacheHeadersFor("/og-image.png")).toEqual({});
+    expect(cacheControlFor("/og-image.png")).toEqual({});
   });
 
   test("path mit assets als Substring (kein /assets/ prefix) → kein immutable", () => {
     // Schutz: /myassets/foo.js soll NICHT immutable kriegen — wäre ein Bug
     // weil die nicht gehashed sind.
-    expect(cacheHeadersFor("/myassets/foo.js")).toEqual({});
-    expect(cacheHeadersFor("/foo/assets/bar.js")).toEqual({});
+    expect(cacheControlFor("/myassets/foo.js")).toEqual({});
+    expect(cacheControlFor("/foo/assets/bar.js")).toEqual({});
   });
 });

package/src/__tests__/run-prod-app.integration.test.ts

@@ -361,6 +361,43 @@ describe("runProdApp", () => {
     const res = await handle.fetch(new Request("http://test/robots.txt"));
     expect(res.status).toBe(200);
     expect(await res.text()).toContain("User-agent: *");
+    expect(res.headers.get("etag")).toBeTruthy();
+  });
+
+  test("static-fallback: If-None-Match → 304 on disk file", async () => {
+    const tmpStaticDir = await createTempStaticDir({
+      "robots.txt": "User-agent: *\nAllow: /",
+      "index.html": "<html>SPA shell</html>",
+    });
+
+    const handle = await boot(undefined, { staticDir: tmpStaticDir });
+    const first = await handle.fetch(new Request("http://test/robots.txt"));
+    const etag = first.headers.get("etag");
+    expect(etag).toBeTruthy();
+
+    const second = await handle.fetch(
+      new Request("http://test/robots.txt", { headers: { "if-none-match": etag ?? "" } }),
+    );
+    expect(second.status).toBe(304);
+    expect(await second.text()).toBe("");
+  });
+
+  test("static-fallback: If-None-Match → 304 on SPA index.html", async () => {
+    const tmpStaticDir = await createTempStaticDir({
+      "index.html": "<html>SPA shell</html>",
+    });
+
+    const handle = await boot(undefined, { staticDir: tmpStaticDir });
+    const first = await handle.fetch(new Request("http://test/some/spa/route"));
+    const etag = first.headers.get("etag");
+    expect(etag).toBeTruthy();
+
+    const second = await handle.fetch(
+      new Request("http://test/some/spa/route", {
+        headers: { "if-none-match": etag ?? "" },
+      }),
+    );
+    expect(second.status).toBe(304);
   });
 
   test("static-fallback: unknown path → SPA-fallback to index.html", async () => {

package/src/build-server-bundle.ts

@@ -52,6 +52,8 @@ const RUNTIME_EXTERNALS = [
   "ioredis",
   "postgres",
   "temporal-polyfill",
+  "pino",
+  "pino-pretty",
 ] as const;
 
 // Pakete die nur im Build-Stack erscheinen (transitive Imports im Framework),
@@ -61,8 +63,6 @@ const RUNTIME_EXTERNALS = [
 // runtime-deps.
 const BUILD_ONLY_EXTERNALS = [
   "meilisearch",
-  "pino",
-  "pino-pretty",
   "@planetscale/database",
   "@libsql/client",
   "better-sqlite3",

package/src/create-kumiko-server.ts

@@ -719,7 +719,7 @@ export async function createKumikoServer(
   // dev-server injiziert das in jede HTML-Response. Re-build NICHT
   // bei Hot-Reload weil sich Feature-Defs nur über einen restart
   // ändern.
-  const appSchemaJson = JSON.stringify(buildAppSchema(stack.registry));
+  const appSchemaJson = JSON.stringify(buildAppSchema(stack.registry, { authoringWarnings: true }));
 
   // --- SSE reload ---
   // bootId identifiziert diese spezifische Server-Process-Instanz. Wird

package/src/run-prod-app.ts

@@ -44,7 +44,14 @@ import {
 import { createSessionCallbacks } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
-import { createSseBroker, type SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import {
+  type CachePolicy,
+  cachedResponse,
+  computeStrongEtag,
+  computeWeakEtag,
+  createSseBroker,
+  type SseBroker,
+} from "@cosmicdrift/kumiko-framework/api";
 import { createDbConnection, type DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildAppSchema,
@@ -1022,17 +1029,38 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
 // ~1 MB.
 async function readStaticFile(
   filePath: string,
-): Promise<{ readonly bytes: Uint8Array; readonly mime: string } | undefined> {
+): Promise<
+  { readonly bytes: Uint8Array; readonly mime: string; readonly mtimeMs: number } | undefined
+> {
   try {
-    const { readFile } = await import("node:fs/promises");
-    const bytes = await readFile(filePath);
-    return { bytes, mime: mimeTypeFor(filePath) };
+    const { readFile, stat } = await import("node:fs/promises");
+    const [bytes, fileStat] = await Promise.all([readFile(filePath), stat(filePath)]);
+    return { bytes, mime: mimeTypeFor(filePath), mtimeMs: fileStat.mtimeMs };
   } catch (err) {
     if ((err as { code?: string }).code === "ENOENT") return undefined;
     throw err;
   }
 }
 
+function serveDiskFile(
+  req: Request,
+  pathname: string,
+  file: {
+    readonly bytes: Uint8Array;
+    readonly mime: string;
+    readonly mtimeMs: number;
+  },
+): Response {
+  return cachedResponse(req, {
+    // @cast-boundary bun-types — Response BodyInit narrowing
+    body: file.bytes as unknown as BodyInit,
+    etag: computeWeakEtag(file.mtimeMs, file.bytes.byteLength),
+    cache: staticCachePolicy(pathname),
+    headers: { "content-type": file.mime },
+    lastModified: new Date(file.mtimeMs),
+  });
+}
+
 // Minimal-Mime-Map — deckt die Files ab die kumiko-build und typische
 // public/-Inhalte produzieren. Bun.file leitet das aus dem Suffix ab,
 // im node-Pfad müssen wir es selbst tun. Default: octet-stream (Browser
@@ -1085,7 +1113,7 @@ function buildStaticFallback(
   async function readHtmlFile(
     path: string,
     injectSchemaInto: boolean,
-  ): Promise<{ bytes: ArrayBuffer; mime: string } | null> {
+  ): Promise<{ bytes: ArrayBuffer; mime: string; etag: string; mtimeMs: number } | null> {
     const file = await readStaticFile(path);
     if (!file) return null;
     if (!injectSchemaInto) {
@@ -1095,11 +1123,34 @@ function buildStaticFallback(
           file.bytes.byteOffset + file.bytes.byteLength,
         ) as ArrayBuffer,
         mime: file.mime,
+        etag: computeWeakEtag(file.mtimeMs, file.bytes.byteLength),
+        mtimeMs: file.mtimeMs,
       };
     }
     const text = new TextDecoder().decode(file.bytes);
     const injected = injectSchema(text, appSchemaJson);
-    return { bytes: new TextEncoder().encode(injected).buffer as ArrayBuffer, mime: file.mime };
+    const bytes = new TextEncoder().encode(injected).buffer as ArrayBuffer;
+    return {
+      bytes,
+      mime: file.mime,
+      etag: computeStrongEtag(new Uint8Array(bytes)),
+      mtimeMs: file.mtimeMs,
+    };
+  }
+
+  function serveHtmlFile(
+    req: Request,
+    pathname: string,
+    html: { bytes: ArrayBuffer; mime: string; etag: string; mtimeMs: number },
+    extraHeaders?: Record<string, string>,
+  ): Response {
+    return cachedResponse(req, {
+      body: html.bytes,
+      etag: html.etag,
+      cache: staticCachePolicy(pathname),
+      headers: { "content-type": html.mime, ...extraHeaders },
+      lastModified: new Date(html.mtimeMs),
+    });
   }
 
   // hostDispatch konsultieren wenn gesetzt UND der Request auf den
@@ -1128,12 +1179,9 @@ function buildStaticFallback(
       // Liefer 500 statt silent-404 damit der Bug schnell auffällt.
       return new Response(`hostDispatch: file not found: ${result.file}`, { status: 500 });
     }
-    const headers: Record<string, string> = {
-      ...cacheHeadersFor("/index.html"),
-      "content-type": html.mime,
-    };
-    if (result.csp) headers["content-security-policy"] = result.csp;
-    return new Response(html.bytes, { headers });
+    const extraHeaders: Record<string, string> = {};
+    if (result.csp) extraHeaders["content-security-policy"] = result.csp;
+    return serveHtmlFile(req, "/index.html", html, extraHeaders);
   }
 
   return async (req: Request): Promise<Response> => {
@@ -1171,10 +1219,7 @@ function buildStaticFallback(
       const filePath = `${staticDir}/${relPath}`;
       const file = await readStaticFile(filePath);
       if (file) {
-        // @cast-boundary bun-types — Response BodyInit narrowing
-        return new Response(file.bytes as unknown as BodyInit, {
-          headers: { ...cacheHeadersFor(url.pathname), "content-type": file.mime },
-        });
+        return serveDiskFile(req, url.pathname, file);
       }
     }
 
@@ -1186,9 +1231,7 @@ function buildStaticFallback(
     // Default Single-App-Pfad: index.html, schema injected.
     const index = await readHtmlFile(indexHtml, true);
     if (index) {
-      return new Response(index.bytes, {
-        headers: { ...cacheHeadersFor("/index.html"), "content-type": index.mime },
-      });
+      return serveHtmlFile(req, "/index.html", index);
     }
 
     // Kein Hono-Match, keine Disk-Datei, kein index.html → liefer den
@@ -1197,16 +1240,16 @@ function buildStaticFallback(
   };
 }
 
-// Map URL-Pfad → Cache-Control. Hashed-Asset-Pfade (/assets/*) sind
-// unveränderlich, der Rest bleibt no-cache damit Updates ohne Hard-
-// Reload greifen. Exported für Unit-Tests; Konsumenten gehen via
+// Map URL-Pfad → Cache-Policy. Hashed-Asset-Pfade (/assets/*) sind
+// unveränderlich, der Rest bleibt revalidate/no-cache damit Updates ohne
+// Hard-Reload greifen. Exported für Unit-Tests; Konsumenten gehen via
 // runProdApp.
-export function cacheHeadersFor(pathname: string): Record<string, string> {
+export function staticCachePolicy(pathname: string): CachePolicy {
   if (pathname.startsWith(`/${ASSETS_DIR}/`)) {
-    return { "cache-control": "public, max-age=31536000, immutable" };
+    return { kind: "immutable" };
   }
   if (pathname === "/" || pathname === "/index.html") {
-    return { "cache-control": "no-cache, must-revalidate" };
+    return { kind: "revalidate" };
   }
   if (
     pathname === "/manifest.json" ||
@@ -1216,9 +1259,9 @@ export function cacheHeadersFor(pathname: string): Record<string, string> {
     // UpdateChecker eine veraltete id.
     pathname === "/build-info.json"
   ) {
-    return { "cache-control": "no-cache" };
+    return { kind: "no-cache" };
   }
-  return {};
+  return { kind: "none" };
 }
 
 function buildProdSessionAuth(