@cosmicdrift/kumiko-server-runtime 0.1.0

package/src/__tests__/resolve-tailwind-cli.test.ts

@@ -0,0 +1,81 @@
+// Unit-Tests für resolveTailwindCli — die zwei Failure-Branches sind
+// genau das, was den dev-server-Crash bei flakigem Netz verhindert:
+// kein Bun → undefined, Package nicht installiert → undefined.
+
+import { describe, expect, test } from "bun:test";
+import { canResolveTailwindStylesheet, resolveTailwindCli } from "../resolve-tailwind-cli";
+
+describe("resolveTailwindCli", () => {
+  test("ohne Bun-Resolver → undefined (silent skip)", () => {
+    const out = resolveTailwindCli({ bun: undefined, cwd: "/somewhere" });
+    expect(out).toBeUndefined();
+  });
+
+  test("Bun.resolveSync wirft → undefined", () => {
+    const out = resolveTailwindCli({
+      bun: {
+        resolveSync: () => {
+          throw new Error("module not found");
+        },
+      },
+      cwd: "/somewhere",
+    });
+    expect(out).toBeUndefined();
+  });
+
+  test("Bun.resolveSync liefert package.json → absoluter Bin-Pfad", () => {
+    const out = resolveTailwindCli({
+      bun: {
+        resolveSync: () => "/repo/node_modules/@tailwindcss/cli/package.json",
+      },
+      cwd: "/repo",
+    });
+    expect(out).toBe("/repo/node_modules/@tailwindcss/cli/dist/index.mjs");
+  });
+
+  test("Bun-Resolver wird mit korrektem id und cwd aufgerufen", () => {
+    const calls: Array<{ id: string; from: string }> = [];
+    resolveTailwindCli({
+      bun: {
+        resolveSync: (id, from) => {
+          calls.push({ id, from });
+          return "/x/node_modules/@tailwindcss/cli/package.json";
+        },
+      },
+      cwd: "/some/working/dir",
+    });
+    expect(calls).toEqual([{ id: "@tailwindcss/cli/package.json", from: "/some/working/dir" }]);
+  });
+});
+
+describe("canResolveTailwindStylesheet", () => {
+  test("tailwindcss resolvable from entry dir → true", () => {
+    const out = canResolveTailwindStylesheet("/repo/packages/app/src/styles.css", {
+      bun: {
+        resolveSync: (id, from) => {
+          if (id === "tailwindcss" && from === "/repo/packages/app/src") {
+            return "/repo/node_modules/tailwindcss/index.css";
+          }
+          throw new Error("not found");
+        },
+      },
+      cwd: "/repo/packages/app",
+    });
+    expect(out).toBe(true);
+  });
+
+  test("tailwindcss not resolvable from entry dir → false", () => {
+    const out = canResolveTailwindStylesheet(
+      "/cache/@cosmicdrift/kumiko-renderer-web/src/styles.css",
+      {
+        bun: {
+          resolveSync: () => {
+            throw new Error("not found");
+          },
+        },
+        cwd: "/tmp/minimal-fixture",
+      },
+    );
+    expect(out).toBe(false);
+  });
+});

package/src/__tests__/run-prod-app-env-source.test.ts

@@ -0,0 +1,157 @@
+// Regression: the boot-path must read the injected `envSource`, not the real
+// process.env. Boot-mode (KUMIKO_DRY_RUN_ENV=boot) validates wiring + builds
+// the registry, then tears down the lazy DB/Redis clients before any socket
+// opens — so this runs without a real Postgres/Redis (same as the CI boot
+// smoke). Before the fix, requireEnv/readEnv read process.env directly, so the
+// required-var test would throw "required env var DATABASE_URL is missing" and
+// the PORT test would bind the default instead of the injected port.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { runProdApp } from "../run-prod-app";
+
+const probeEntity = createEntity({
+  fields: {
+    name: createTextField({ required: true }),
+    active: createBooleanField({ default: true }),
+  },
+  table: "env_source_probe",
+});
+
+const probeFeature = defineFeature("env-source-probe", (r) => {
+  r.entity("widget", probeEntity);
+  r.queryHandler({
+    name: "ping",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    handler: async () => ({ pong: true }),
+  });
+});
+
+// Cleared from process.env so the test fully controls config via envSource.
+// DATABASE_URL/REDIS_URL/JWT_SECRET are required (their read throws pre-fix);
+// PORT is non-throwing, cleared only so ambient PORT can't mask the second
+// test's "PORT comes from envSource" assertion.
+const CLEARED_VARS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET", "PORT"] as const;
+
+const DUMMY_ENV = {
+  KUMIKO_DRY_RUN_ENV: "boot",
+  DATABASE_URL: "postgres://smoke:smoke@127.0.0.1:1/smoke",
+  REDIS_URL: "redis://127.0.0.1:1",
+  JWT_SECRET: "smokesmokesmokesmokesmokesmokesmokesmoke",
+} as const;
+
+describe("runProdApp boot-mode env-source", () => {
+  const saved: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const k of CLEARED_VARS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+
+  afterEach(() => {
+    for (const k of CLEARED_VARS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  test("boots from injected envSource even when process.env lacks the required vars", async () => {
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    let handle: Awaited<ReturnType<typeof runProdApp>>;
+    try {
+      handle = await runProdApp({
+        features: [probeFeature],
+        autoListen: false,
+        migrations: false,
+        // REDIS_URL points at an unreachable port — boot-mode must NOT
+        // construct the (eager) Redis client, so this never tries to connect.
+        envSource: { ...DUMMY_ENV },
+      });
+    } finally {
+      console.log = originalLog;
+    }
+
+    // Boot-mode with an injected envSource returns an inert dry-run handle.
+    expect(handle).toBeDefined();
+    expect(typeof handle.stop).toBe("function");
+    // The registry was built + validated before any connection was opened.
+    expect(logs.some((line) => line.includes("boot validation OK"))).toBe(true);
+    await handle.stop();
+  });
+
+  test("boot-mode constructs no eager Redis client — kein TCP-Connect auf REDIS_URL", async () => {
+    // Kern-Garantie (224/2), als Netzwerk-Beweis statt Konstruktor-Spy:
+    // REDIS_URL zeigt auf einen lokalen Listener — `new Redis(...)`
+    // connectet eager, der Boot-Exit MUSS also vorher liegen, sonst
+    // zählt der Listener eine Connection.
+    let connections = 0;
+    const listener = Bun.listen({
+      hostname: "127.0.0.1",
+      port: 0,
+      socket: {
+        open(socket) {
+          connections += 1;
+          socket.end();
+        },
+        data() {},
+      },
+    });
+
+    const originalLog = console.log;
+    console.log = () => {};
+    try {
+      const handle = await runProdApp({
+        features: [probeFeature],
+        autoListen: false,
+        migrations: false,
+        envSource: { ...DUMMY_ENV, REDIS_URL: `redis://127.0.0.1:${listener.port}` },
+      });
+      await handle.stop();
+    } finally {
+      console.log = originalLog;
+    }
+
+    // Ein eager Connect wäre bereits beim runProdApp-await passiert;
+    // kleine Nachfrist für asynchrone Socket-Anläufe.
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    listener.stop(true);
+    expect(connections).toBe(0);
+  });
+
+  test("resolves PORT from envSource, not process.env", async () => {
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    try {
+      const handle = await runProdApp({
+        features: [probeFeature],
+        autoListen: false,
+        migrations: false,
+        envSource: { ...DUMMY_ENV, PORT: "8123" },
+      });
+      await handle.stop();
+    } finally {
+      console.log = originalLog;
+    }
+
+    // The boot logs "booting Kumiko stack on port <port>" — pre-fix this read
+    // process.env["PORT"] (deleted here) and would log the 3000 default.
+    expect(logs.some((line) => line.includes("port 8123"))).toBe(true);
+    expect(logs.some((line) => line.includes("port 3000"))).toBe(false);
+  });
+});

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

@@ -0,0 +1,57 @@
+// Spec-Tests für die Bun.serve-Options + Heartbeat-Cadence. Diese
+// Konstanten/Defaults haben Live-Bugs verursacht und sind 1-Zeile-
+// revertierbar — die Tests pinsen Intent + akzeptablen Range gegen
+// "looks like a leak"-Reverts oder "bisschen rauf, sollte reichen"-
+// Tweaks.
+
+import { describe, expect, test } from "bun:test";
+import { SSE_HEARTBEAT_INTERVAL_MS } from "@cosmicdrift/kumiko-framework/api";
+import { buildBunServeOptions } from "../run-prod-app";
+
+describe("Bun.serve options for production", () => {
+  test("idleTimeout is 0 (disabled) — required for SSE long-lived connections", () => {
+    // Bun.serve default ist 10s — ohne Override killt das SSE-Streams
+    // mit halbem HTTP/2-RST_STREAM. Spec ist "disabled"; jeder andere
+    // Wert (auch ein vermeintlich "großzügiges" 60) bricht SSE sobald
+    // ein Client den Tab im Hintergrund hat (kein Heartbeat-Read auf
+    // Browser-Seite, Idle-Timer feuert).
+    const opts = buildBunServeOptions(0, () => new Response("ok"));
+    expect(opts.idleTimeout).toBe(0);
+  });
+
+  test("port + fetch werden 1:1 durchgereicht", () => {
+    const fetchHandler = (_req: Request) => new Response("test");
+    const opts = buildBunServeOptions(3000, fetchHandler);
+    expect(opts.port).toBe(3000);
+    expect(opts.fetch).toBe(fetchHandler);
+  });
+});
+
+describe("SSE heartbeat cadence", () => {
+  test("liegt unter dem strengsten Edge-Idle-Timeout (Cloudflare 100s)", () => {
+    // Bun.serve idleTimeout ist disabled (siehe buildBunServeOptions),
+    // damit fällt der Bun-default-10s-Layer raus. Die strengsten
+    // verbleibenden Layer sind CDN/LB-Edges:
+    //   - Cloudflare Edge: 100 s   ← strengster realistischer Layer
+    //   - AWS ALB: 60 s
+    //   - Nginx default: keep-alive 60 s, aber nicht für Streams
+    // Heartbeat muss DEUTLICH darunter liegen damit auch ein verschluckter
+    // Frame nicht zur Connection-Death führt — Faktor 5 ist konservativ.
+    expect(SSE_HEARTBEAT_INTERVAL_MS).toBeLessThan(60_000);
+  });
+
+  test("liegt nicht zu hoch — DefenseInDepth gegen Bun-Default-Drift", () => {
+    // Wenn jemand idleTimeout: 0 wieder rausnimmt (Audit, Linter,
+    // Misverständnis), darf der Heartbeat nicht der einzige
+    // Schutzwall sein der unter dem 10s-Bun-default liegt. ≤30s
+    // gibt Cushion + bleibt deutlich unter Bun-default-10s × 3.
+    expect(SSE_HEARTBEAT_INTERVAL_MS).toBeLessThanOrEqual(30_000);
+  });
+
+  test("ist >= 5 s — Frequency-Wall gegen versehentliches Network-Spam", () => {
+    // 1000 anonyme Viewer × Heartbeat-Frequency darf den Server nicht
+    // mit Frames fluten. 5s = 200 frames/s pro 1000 Clients ist OK.
+    // Unter 5s wäre eher ein "tippfehler" als bewusste Wahl.
+    expect(SSE_HEARTBEAT_INTERVAL_MS).toBeGreaterThanOrEqual(5_000);
+  });
+});