@cosmicdrift/kumiko-dev-server 0.39.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.39.0",
+  "version": "0.40.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>",

package/src/__tests__/create-kumiko-server.integration.test.ts

@@ -9,6 +9,7 @@ import {
   createTextField,
   defineFeature,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
 import { createKumikoServer, type KumikoServerHandle } from "../create-kumiko-server";
 
 // Integration-Test: bootet createKumikoServer mit echtem Postgres,
@@ -27,6 +28,18 @@ const probeEntity = createEntity({
 
 const probeFeature = defineFeature("dev-server-probe", (r) => {
   r.entity("probe", probeEntity);
+  // SystemAdmin-gated write — Ziel des extraRoutes.dispatchSystemWrite-
+  // Tests (252/2): Echo von user.tenantId + roles beweist Dispatch durch
+  // den echten Dispatcher (Zod + Access-Check) mit Ziel-Tenant-SystemUser.
+  r.writeHandler({
+    name: "probe-write",
+    schema: z.object({ note: z.string() }),
+    access: { roles: ["SystemAdmin"] },
+    handler: async (event) => ({
+      isSuccess: true as const,
+      data: { tenantSeen: event.user.tenantId, roles: event.user.roles },
+    }),
+  });
 });
 
 let handle: KumikoServerHandle | undefined;
@@ -285,3 +298,41 @@ describe("createKumikoServer (Multi-Entry)", () => {
     expect(res.status).toBe(404);
   });
 });
+
+// 252/2: der Dev-Pfad bekommt dieselbe extraRoutes-deps-Closure wie
+// runProdApp (seit der Extraktion nach extra-routes-deps.ts geteilt) —
+// hier der analoge Beweis gegen createKumikoServer.
+describe("createKumikoServer extraRoutes-deps", () => {
+  test("dispatchSystemWrite schreibt als SystemAdmin des Ziel-Tenants, registry verfügbar", async () => {
+    const tenantId = "00000000-0000-4000-8000-000000000042";
+    let registryHasProbe = false;
+    handle = await createKumikoServer({
+      features: [probeFeature],
+      port: 0,
+      installSignalHandlers: false,
+      extraRoutes: (app, deps) => {
+        registryHasProbe = deps.registry.features.has("dev-server-probe");
+        app.post("/webhook-probe", async (c) => {
+          const result = await deps.dispatchSystemWrite({
+            handlerQn: "dev-server-probe:write:probe-write",
+            payload: { note: "from-webhook" },
+            tenantId: tenantId as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+          });
+          return c.json(result);
+        });
+      },
+    });
+
+    expect(registryHasProbe).toBe(true);
+
+    const res = await handle.fetch(new Request("http://test/webhook-probe", { method: "POST" }));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      isSuccess: boolean;
+      data?: { tenantSeen: string; roles: string[] };
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(body.data?.tenantSeen).toBe(tenantId);
+    expect(body.data?.roles).toContain("SystemAdmin");
+  });
+});

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

@@ -92,6 +92,45 @@ describe("runProdApp boot-mode env-source", () => {
     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;

package/src/create-kumiko-server.ts

@@ -20,12 +20,7 @@ import { readFile, watch } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { type AuthRoutesConfig, generateToken } from "@cosmicdrift/kumiko-framework/api";
-import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
-import {
-  buildAppSchema,
-  createSystemUser,
-  type FeatureDefinition,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { buildAppSchema, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   pushEntityProjectionTables,
@@ -34,6 +29,7 @@ import {
   type TestStackOptions,
   TestUsers,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { type ExtraRoutesSystemDeps, makeDispatchSystemWrite } from "./extra-routes-deps";
 import { injectSchema } from "./inject-schema";
 import { canResolveTailwindStylesheet, resolveTailwindCli } from "./resolve-tailwind-cli";
 import { buildBunServeOptions } from "./run-prod-app";
@@ -193,24 +189,7 @@ export type CreateKumikoServerOptions = {
    *  Static/HTML-Auslieferung aufgerufen, sodass eigene GETs (/feed.xml,
    *  /og-image, …) Vorrang vor dem Dev-Asset-Pfad haben. `deps` statt
    *  `ctx` weil dies kein HandlerContext ist — kein user/tenant. */
-  readonly extraRoutes?: (
-    app: import("hono").Hono,
-    deps: {
-      db: TestStack["db"];
-      redis: TestStack["redis"];
-      /** Feature-registry — z.B. für Plugin-Lookups via
-       *  `registry.getExtensionUsages("subscriptionProvider")`. */
-      registry: TestStack["registry"];
-      /** System-Write durch den Command-Dispatcher — Semantik identisch zu
-       *  runProdApp.extraRoutes (SystemAdmin des Ziel-Tenants, kein
-       *  Access-Check; nur für signatur-authentifizierte Pfade). */
-      dispatchSystemWrite: (args: {
-        readonly handlerQn: string;
-        readonly payload: unknown;
-        readonly tenantId: import("@cosmicdrift/kumiko-framework/engine").TenantId;
-      }) => Promise<import("@cosmicdrift/kumiko-framework/engine").WriteResult>;
-    },
-  ) => void;
+  readonly extraRoutes?: (app: import("hono").Hono, deps: ExtraRoutesSystemDeps) => void;
 };
 
 export type KumikoServerHandle = {
@@ -702,10 +681,11 @@ export async function createKumikoServer(
   if (options.extraRoutes !== undefined) {
     options.extraRoutes(stack.app, {
       db: stack.db,
-      redis: stack.redis,
+      // 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: ({ handlerQn, payload, tenantId }) =>
-        stack.dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin])),
+      dispatchSystemWrite: makeDispatchSystemWrite(stack.dispatcher),
     });
   }
 

package/src/extra-routes-deps.ts

@@ -0,0 +1,47 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type Registry,
+  type SessionUser,
+  type TenantId,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type Redis from "ioredis";
+
+/** Deps für `extraRoutes` — geteilt zwischen runProdApp (prod) und
+ *  createKumikoServer (dev), damit die beiden Pfade nicht driften.
+ *  Naming: `deps` statt `ctx` weil im Framework `ctx` der HandlerContext
+ *  mit user/tenant/registry ist — hier ist der Scope absichtlich kleiner
+ *  (Routes laufen außerhalb der Auth/Tenant-Pipeline). */
+export type ExtraRoutesSystemDeps = {
+  readonly db: DbConnection;
+  readonly redis: Redis;
+  /** Feature-registry — z.B. für Plugin-Lookups via
+   *  `registry.getExtensionUsages("subscriptionProvider")`. */
+  readonly registry: Registry;
+  /** Schreibt durch den /api/*-Command-Dispatcher (gleiche Idempotency/
+   *  Job-Hooks) — aber als auto-konstruierter SystemAdmin des Ziel-
+   *  Tenants, OHNE Access-Check der Route. Privilege-Scope: SystemAdmin
+   *  ist die höchste nicht-tenant-scoped Rolle — der Call erreicht JEDEN
+   *  SystemAdmin-gegateten Handler auf jedem Tenant; das Rollen-Set ist
+   *  nicht konfigurierbar. Nur für Pfade, die ihre Authentizität selbst
+   *  beweisen (Provider-Webhook-Signaturen,
+   *  createSubscriptionWebhookHandler et al.). */
+  readonly dispatchSystemWrite: (args: {
+    readonly handlerQn: string;
+    readonly payload: unknown;
+    readonly tenantId: TenantId;
+  }) => Promise<WriteResult>;
+};
+
+type SystemWriteDispatcher = {
+  readonly write: (handlerQn: string, payload: unknown, user: SessionUser) => Promise<WriteResult>;
+};
+
+export function makeDispatchSystemWrite(
+  dispatcher: SystemWriteDispatcher,
+): ExtraRoutesSystemDeps["dispatchSystemWrite"] {
+  return ({ handlerQn, payload, tenantId }) =>
+    dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
+}

package/src/run-prod-app.ts

@@ -41,20 +41,16 @@ import { createSessionCallbacks } from "@cosmicdrift/kumiko-bundled-features/ses
 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 { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import { createDbConnection, type DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildAppSchema,
   createRegistry,
-  createSystemUser,
   type EffectiveFeaturesResolver,
   type FeatureDefinition,
   findTierResolverUsage,
-  type Registry,
   type TenantId,
   type TierResolverPlugin,
   validateBoot,
-  type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
   type ApiEntrypoint,
@@ -86,6 +82,7 @@ import Redis from "ioredis";
 import { applyBootSeeds } from "./boot/apply-boot-seeds";
 import { ASSETS_DIR } from "./build-prod-bundle";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
+import { type ExtraRoutesSystemDeps, makeDispatchSystemWrite } from "./extra-routes-deps";
 import { injectSchema } from "./inject-schema";
 import { tryHonoFirst } from "./try-hono-first";
 
@@ -428,26 +425,7 @@ export type RunProdAppOptions = {
    *  Naming: `deps` statt `ctx` weil im Framework `ctx` der HandlerContext
    *  mit user/tenant/registry ist — hier ist der Scope absichtlich kleiner
    *  (Routes laufen außerhalb der Auth/Tenant-Pipeline). */
-  readonly extraRoutes?: (
-    app: import("hono").Hono,
-    deps: {
-      db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
-      redis: import("ioredis").default;
-      /** Feature-registry — z.B. für Plugin-Lookups via
-       *  `registry.getExtensionUsages("subscriptionProvider")`. */
-      registry: Registry;
-      /** Schreibt durch den /api/*-Command-Dispatcher (gleiche Idempotency/
-       *  Job-Hooks) — aber als auto-konstruierter SystemAdmin des Ziel-
-       *  Tenants, OHNE Access-Check der Route. Nur für Pfade, die ihre
-       *  Authentizität selbst beweisen (Provider-Webhook-Signaturen,
-       *  createSubscriptionWebhookHandler et al.). */
-      dispatchSystemWrite: (args: {
-        readonly handlerQn: string;
-        readonly payload: unknown;
-        readonly tenantId: TenantId;
-      }) => Promise<WriteResult>;
-    },
-  ) => void;
+  readonly extraRoutes?: (app: import("hono").Hono, deps: ExtraRoutesSystemDeps) => void;
   /** When true (default), Bun.serve is started before runProdApp resolves —
    *  the common case: `await runProdApp({...})` boots the server and the
    *  process stays up listening on PORT. Set to false in tests that drive
@@ -840,12 +818,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       db,
       redis,
       registry,
-      dispatchSystemWrite: ({ handlerQn, payload, tenantId }) =>
-        entrypoint.dispatcher.write(
-          handlerQn,
-          payload,
-          createSystemUser(tenantId, [ROLES.SystemAdmin]),
-        ),
+      dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
     });
   }